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.
2025-10-28 10:52:46 -07:00
parent 5947e209c7
commit 3672830684
2 changed files with 255 additions and 0 deletions
--- 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

--- a/fern/pages/agents/archival_export.mdx
+++ 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>