From 36728306843476fce19b0b2caeb30d27a38b403b Mon Sep 17 00:00:00 2001 From: Cameron Pfiffer Date: Tue, 28 Oct 2025 10:52:46 -0700 Subject: [PATCH] docs: add archival memory export guide (#5784) Add documentation page showing how to export all archival memories from an agent using the Letta SDK. Includes a complete Python script with pagination support and usage examples. --- fern/docs.yml | 2 + fern/pages/agents/archival_export.mdx | 253 ++++++++++++++++++++++++++ 2 files changed, 255 insertions(+) create mode 100644 fern/pages/agents/archival_export.mdx diff --git a/fern/docs.yml b/fern/docs.yml index d0f4dc19..e57d8ea4 100644 --- a/fern/docs.yml +++ b/fern/docs.yml @@ -117,6 +117,8 @@ navigation: path: pages/agents/archival_search.mdx - page: Best Practices path: pages/agents/archival_best_practices.mdx + - page: Exporting Archival Memories + path: pages/agents/archival_export.mdx - page: Agentic Context Engineering path: pages/agents/context_engineering.mdx diff --git a/fern/pages/agents/archival_export.mdx b/fern/pages/agents/archival_export.mdx new file mode 100644 index 00000000..88a3f1ff --- /dev/null +++ b/fern/pages/agents/archival_export.mdx @@ -0,0 +1,253 @@ +--- +title: Exporting Archival Memories +subtitle: Export all passages from an agent's archival memory +slug: guides/agents/archival-export +--- + +## Overview + +You can export all archival memories (passages) from an agent programmatically using the Letta SDK. This is useful for: +- Backing up agent knowledge +- Analyzing what an agent has learned +- Migrating memories between agents +- Auditing archival content + +## Export script + +Below is a Python script that paginates through all of an agent's archival memories and exports them to a JSON file: + +```python export_agent_memories.py +#!/usr/bin/env python3 +""" +Utility script to export all archival memories (passages) from a Letta agent. + +Usage: + python export_agent_memories.py [--output ] [--limit ] + +Example: + python export_agent_memories.py agent-123e4567-e89b-42d3-8456-426614174000 --output memories.json +""" + +import argparse +import json +import os +import sys +from typing import Any, Dict, List + +from letta_client import Letta + + +def export_agent_memories( + client: Letta, + agent_id: str, + page_limit: int = 100, +) -> List[Dict[str, Any]]: + """ + Export all archival memories from an agent by paginating through all results. + + Args: + client: Initialized Letta client + agent_id: The agent ID in format 'agent-' + page_limit: Number of results per page (default 100) + + Returns: + List of passage dictionaries with embedding and embedding_config removed + """ + all_passages = [] + after_cursor = None + page_num = 1 + + print(f"Exporting archival memories for agent: {agent_id}") + print(f"Using pagination with limit: {page_limit}") + print("-" * 60) + + while True: + # Fetch next page + print(f"Fetching page {page_num}...", end=" ", flush=True) + + try: + passages = client.agents.passages.list( + agent_id=agent_id, + after=after_cursor, + limit=page_limit, + ascending=True # Get oldest to newest + ) + except Exception as e: + print(f"\nError fetching memories: {e}") + raise + + if not passages: + print("(no more results)") + break + + print(f"got {len(passages)} passages") + + # Convert to dict and remove embedding fields + for passage in passages: + passage_dict = passage.model_dump() if hasattr(passage, 'model_dump') else passage.dict() + passage_dict.pop("embedding", None) + passage_dict.pop("embedding_config", None) + all_passages.append(passage_dict) + + # Check if we got fewer results than the limit (last page) + if len(passages) < page_limit: + break + + # Set cursor for next page (use the ID of the last passage) + after_cursor = passages[-1].id if hasattr(passages[-1], 'id') else passages[-1]['id'] + page_num += 1 + + print("-" * 60) + print(f"Total passages exported: {len(all_passages)}") + + return all_passages + + +def main(): + parser = argparse.ArgumentParser( + description="Export archival memories from a Letta agent" + ) + parser.add_argument( + "agent_id", + help="Agent ID in format 'agent-'" + ) + parser.add_argument( + "--output", + "-o", + help="Output JSON file path (default: _memories.json)" + ) + parser.add_argument( + "--limit", + "-l", + type=int, + default=100, + help="Number of results per page (default: 100)" + ) + + args = parser.parse_args() + + # Check for API key + api_key = os.getenv("LETTA_API_KEY") + if not api_key: + print("Error: LETTA_API_KEY environment variable not set", file=sys.stderr) + print("Please export LETTA_API_KEY with your API key", file=sys.stderr) + return 1 + + # Determine output file + output_file = args.output or f"{args.agent_id}_memories.json" + + try: + # Initialize client + client = Letta(token=api_key) + + # Export memories + passages = export_agent_memories( + client=client, + agent_id=args.agent_id, + page_limit=args.limit + ) + + # Write to file + with open(output_file, "w") as f: + json.dump(passages, f, indent=2, default=str) + + print(f"\nMemories exported successfully to: {output_file}") + return 0 + + except Exception as e: + print(f"\nError: {e}", file=sys.stderr) + return 1 + + +if __name__ == "__main__": + sys.exit(main()) +``` + +## Usage + +### Prerequisites + +Install the Letta Python SDK: + +```bash +pip install letta-client +``` + +Set your API key: + +```bash +export LETTA_API_KEY="your-api-key-here" +``` + +### Running the script + +Export all memories from an agent: + +```bash +python export_agent_memories.py agent-123e4567-e89b-42d3-8456-426614174000 +``` + +Specify a custom output file: + +```bash +python export_agent_memories.py agent-123e4567-e89b-42d3-8456-426614174000 --output my_memories.json +``` + +Adjust pagination size: + +```bash +python export_agent_memories.py agent-123e4567-e89b-42d3-8456-426614174000 --limit 50 +``` + +## Output format + +The script exports passages as a JSON array. Each passage contains all fields except `embedding` and `embedding_config`: + +```json +[ + { + "id": "passage-123e4567-e89b-42d3-8456-426614174000", + "text": "The user prefers Python for data science projects", + "created_at": "2025-01-15T10:30:00Z", + "updated_at": null, + "tags": ["preference", "programming"], + "metadata": {}, + "file_id": null, + "file_name": null, + "source_id": null, + "archive_id": "archive-abc123", + "created_by_id": "user-xyz789", + "last_updated_by_id": null, + "is_deleted": false + } +] +``` + +## Next steps + + + + Learn how to search through archival memories + + + Patterns and tips for using archival memory + + + Learn about archival memory basics + + + View the List Passages endpoint documentation + +