Platform for stateful agents: AI with advanced memory that can learn and self-improve over time.
docs: add archival memory export guide (#5784)
Cameron Pfiffer367283068434
diff --git a/fern/docs.yml b/fern/docs.ymlindex d0f4dc192..e57d8ea4a 100644--- a/fern/docs.yml+++ b/fern/docs.yml@@ -117,6 +117,8 @@ navigation:path: pages/agents/archival_search.mdx- page: Best Practicespath: pages/agents/archival_best_practices.mdx+ - page: Exporting Archival Memories+ path: pages/agents/archival_export.mdx- page: Agentic Context Engineeringpath: pages/agents/context_engineering.mdxdiff --git a/fern/pages/agents/archival_export.mdx b/fern/pages/agents/archival_export.mdxnew file mode 100644index 000000000..88a3f1ff0--- /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 <agent_id> [--output <file>] [--limit <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-<uuid4>'+ 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-<uuid4>'"+ )+ parser.add_argument(+ "--output",+ "-o",+ help="Output JSON file path (default: <agent_id>_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++<CardGroup cols={2}>+ <Card+ title="Searching & Querying"+ href="/guides/agents/archival-search"+ >+ Learn how to search through archival memories+ </Card>+ <Card+ title="Best Practices"+ href="/guides/agents/archival-best-practices"+ >+ Patterns and tips for using archival memory+ </Card>+ <Card+ title="Archival Memory Overview"+ href="/guides/agents/archival-memory"+ >+ Learn about archival memory basics+ </Card>+ <Card+ title="API Reference"+ href="/api-reference/agents/passages/list"+ >+ View the List Passages endpoint documentation+ </Card>+</CardGroup>