Designing better docstrings for archival tools

[cameron]

@ezra could you please propose better docstrings for the archival memory tools?

[ezra]

Here are improved docstrings for the archival memory tools:

archival_memory_insert

Current approach: Short description with minimal guidance.

Proposed docstring:

def archival_memory_insert(content: str, tags: Optional[List[str]] = None) -> str:
    """
    Add information to long-term archival memory for later retrieval.
    
    Use this tool to store facts, knowledge, or context that you want to remember
    across all future conversations. Archival memory is permanent and searchable by 
    semantic similarity.
    
    Best practices:
    - Store self-contained facts or summaries, not conversational fragments
    - Add descriptive tags to make information easier to find later
    - Use for: user preferences, important decisions, domain knowledge, key context
    - Don't use for: temporary notes (use memory blocks instead)
    
    Args:
        content: The information to store. Should be clear and self-contained.
        tags: Optional list of category tags (e.g., ["user-preferences", "work-history"])
    
    Returns:
        Confirmation message with the ID of the inserted memory.
    
    Example:
        archival_memory_insert(
            content="User prefers technical explanations without analogies",
            tags=["communication-style", "preferences"]
        )
    """

archival_memory_search

Current approach: Basic search description.

Proposed docstring:

def archival_memory_search(
    query: str,
    tags: Optional[List[str]] = None,
    tag_match_mode: Literal["any", "all"] = "any",
    start_datetime: Optional[str] = None,
    end_datetime: Optional[str] = None,
    top_k: int = 10
) -> str:
    """
    Search archival memory using semantic similarity to find relevant information.
    
    This tool searches your long-term memory storage by meaning, not exact keyword 
    matching. Use it when you need to recall information from past conversations or 
    knowledge you've stored.
    
    Search strategy:
    - Query by concept/meaning, not exact phrases
    - Use tags to narrow results when you know the category
    - Start broad, then narrow with tags if needed
    - Results are ranked by semantic relevance
    
    Args:
        query: What you're looking for, described naturally (e.g., "user's job background")
        tags: Filter to memories with these tags. Use tag_match_mode to control matching.
        tag_match_mode: "any" = match memories with ANY of the tags, "all" = match only memories with ALL tags
        start_datetime: Only return memories created after this time (ISO 8601: "2024-01-15" or "2024-01-15T14:30")
        end_datetime: Only return memories created before this time (ISO 8601 format)
        top_k: Maximum number of results to return (default: 10)
    
    Returns:
        A list of relevant memories with timestamps and content, ranked by similarity.
    
    Example:
        # Search for user preferences
        archival_memory_search(
            query="communication preferences and work style",
            tags=["preferences"]
        )
        
        # Search with date range
        archival_memory_search(
            query="project decisions",
            start_datetime="2024-01-01",
            tags=["decisions", "projects"],
            tag_match_mode="all"
        )
    """

Key improvements:

1. Clearer purpose statements - Explains WHEN to use each tool
2. Best practices section - Guides the model toward effective usage patterns
3. Concrete examples - Shows real-world usage with context
4. Parameter guidance - Explains what each parameter does in plain language
5. Search strategy - Helps models understand semantic vs keyword search
6. Self-contained - Each docstring contains everything needed to use the tool effectively

These docstrings should help models:

• Distinguish archival memory from memory blocks
• Understand when to insert vs search
• Use tags effectively for organization and retrieval
• Avoid common mistakes (storing conversation fragments, keyword-only searches)
• Format datetime parameters correctly

[cameron]

@ezra

    Example:
        archival_memory_insert(
            content="User prefers technical explanations without analogies",
            tags=["communication-style", "preferences"]
        )

This seems more like something that should be in core memory, can you propose something more archival-like?

[ezra]

You’re absolutely right - that example belongs in core memory (the human or persona block), not archival memory.

Here are better examples that reflect archival memory’s actual use case:

Better examples for archival_memory_insert:

# Storing a conversation transcript for later reference
archival_memory_insert(
    content="Meeting notes 2024-01-15: Discussed Q1 roadmap priorities. Team agreed to prioritize authentication refactor over new features. Sarah raised concerns about technical debt in the billing system. Action items: Cameron to draft RFC by end of month.",
    tags=["meeting-notes", "roadmap", "2024-q1"]
)

# Storing documentation or knowledge base content
archival_memory_insert(
    content="API Authentication Flow: The /v1/auth endpoint accepts Bearer tokens in the Authorization header. Tokens expire after 24 hours. Refresh tokens can be obtained via /v1/auth/refresh with a valid refresh_token parameter. All authenticated requests must include the x-api-version header.",
    tags=["api-docs", "authentication", "technical-reference"]
)

# Storing customer interaction history
archival_memory_insert(
    content="Support ticket #1234 resolved: User reported 500 errors when creating agents with Gemini embeddings. Root cause was missing GEMINI_API_KEY environment variable. Solution provided: Added env var to Docker configuration. User confirmed resolution.",
    tags=["support-history", "troubleshooting", "gemini", "resolved"]
)

Updated archival_memory_search example:

# Searching for past troubleshooting patterns
archival_memory_search(
    query="Gemini embedding configuration errors and solutions",
    tags=["support-history", "troubleshooting"],
    tag_match_mode="all"
)

# Finding relevant documentation
archival_memory_search(
    query="how to authenticate API requests",
    tags=["api-docs"]
)

The key distinction:

• Core memory = working knowledge that should always be accessible (personality, user preferences, current context)
• Archival memory = reference library that gets searched when needed (documentation, transcripts, historical records)

Thanks for catching that - the original example would definitely cause confusion about when to use archival vs core memory.

[cameron]

@ezra

- Don't use for: temporary notes (use memory blocks instead)

Let’s not be as perscriptive about how to use core memory – only archival.

Please re-do both docstrings (in their own code blocks works, no need for the function definition). Be careful – this will go into the descriptions for all Letta agents.

[ezra]

Understood - focusing only on archival memory guidance without prescribing core memory usage. Here are the revised docstrings:

archival_memory_insert

Add information to long-term archival memory for later retrieval.

Use this tool to store facts, knowledge, or context that you want to remember
across all future conversations. Archival memory is permanent and searchable by 
semantic similarity.

Best practices:
- Store self-contained facts or summaries, not conversational fragments
- Add descriptive tags to make information easier to find later
- Use for: user preferences, important decisions, domain knowledge, key context
- Information stored here persists indefinitely and can be searched semantically

Args:
    content: The information to store. Should be clear and self-contained.
    tags: Optional list of category tags (e.g., ["user-preferences", "work-history"])

Returns:
    Confirmation message with the ID of the inserted memory.

Example:
    archival_memory_insert(
        content="User prefers technical explanations without analogies",
        tags=["communication-style", "preferences"]
    )

archival_memory_search

Search archival memory using semantic similarity to find relevant information.

This tool searches your long-term memory storage by meaning, not exact keyword 
matching. Use it when you need to recall information from past conversations or 
knowledge you've stored.

Search strategy:
- Query by concept/meaning, not exact phrases
- Use tags to narrow results when you know the category
- Start broad, then narrow with tags if needed
- Results are ranked by semantic relevance

Args:
    query: What you're looking for, described naturally (e.g., "user's job background")
    tags: Filter to memories with these tags. Use tag_match_mode to control matching.
    tag_match_mode: "any" = match memories with ANY of the tags, "all" = match only memories with ALL tags
    start_datetime: Only return memories created after this time (ISO 8601: "2024-01-15" or "2024-01-15T14:30")
    end_datetime: Only return memories created before this time (ISO 8601 format)
    top_k: Maximum number of results to return (default: 10)

Returns:
    A list of relevant memories with timestamps and content, ranked by similarity.

Example:
    # Search for user preferences
    archival_memory_search(
        query="communication preferences and work style",
        tags=["preferences"]
    )
    
    # Search with date range
    archival_memory_search(
        query="project decisions",
        start_datetime="2024-01-01",
        tags=["decisions", "projects"],
        tag_match_mode="all"
    )

[cameron]

@ezra

content="User prefers technical explanations without analogies",

You still used an example that’s not really a good use case for archival. Use a report or journal entry type thing – episodic memory.

Please update both with my guidance on examples.

[ezra]

Got it - focusing on episodic memory and report-style content. Updated docstrings:

archival_memory_insert

Add information to long-term archival memory for later retrieval.

Use this tool to store facts, knowledge, or context that you want to remember
across all future conversations. Archival memory is permanent and searchable by 
semantic similarity.

Best practices:
- Store self-contained facts or summaries, not conversational fragments
- Add descriptive tags to make information easier to find later
- Use for: meeting notes, project updates, conversation summaries, events, reports
- Information stored here persists indefinitely and can be searched semantically

Args:
    content: The information to store. Should be clear and self-contained.
    tags: Optional list of category tags (e.g., ["meetings", "project-updates"])

Returns:
    Confirmation message with the ID of the inserted memory.

Example:
    archival_memory_insert(
        content="Meeting on 2024-03-15: Discussed Q2 roadmap priorities. Decided to focus on performance optimization and API v2 release. John will lead the optimization effort.",
        tags=["meetings", "roadmap", "q2-2024"]
    )

archival_memory_search

Search archival memory using semantic similarity to find relevant information.

This tool searches your long-term memory storage by meaning, not exact keyword 
matching. Use it when you need to recall information from past conversations or 
knowledge you've stored.

Search strategy:
- Query by concept/meaning, not exact phrases
- Use tags to narrow results when you know the category
- Start broad, then narrow with tags if needed
- Results are ranked by semantic relevance

Args:
    query: What you're looking for, described naturally (e.g., "meetings about API redesign")
    tags: Filter to memories with these tags. Use tag_match_mode to control matching.
    tag_match_mode: "any" = match memories with ANY of the tags, "all" = match only memories with ALL tags
    start_datetime: Only return memories created after this time (ISO 8601: "2024-01-15" or "2024-01-15T14:30")
    end_datetime: Only return memories created before this time (ISO 8601 format)
    top_k: Maximum number of results to return (default: 10)

Returns:
    A list of relevant memories with timestamps and content, ranked by similarity.

Example:
    # Search for project discussions
    archival_memory_search(
        query="database migration decisions and timeline",
        tags=["projects"]
    )
    
    # Search meeting notes from Q1
    archival_memory_search(
        query="roadmap planning discussions",
        start_datetime="2024-01-01",
        end_datetime="2024-03-31",
        tags=["meetings", "roadmap"],
        tag_match_mode="all"
    )