Letta Development Guide

Letta Development Guide

Comprehensive guide for designing and building effective Letta agents with appropriate architectures, memory configurations, model selection, and tool setups.

When to Use This Skill

Use this skill when:

• Starting a new Letta agent project
• Choosing between agent architectures (letta_v1_agent vs memgpt_v2_agent)
• Designing memory block structure and architecture
• Selecting appropriate models for your use case
• Planning tool configurations
• Optimizing memory management and performance
• Implementing shared memory between agents
• Debugging memory-related issues

Quick Start Guide

Minimal Working Example

from letta_client import Letta

client = Letta()
agent = client.agents.create(
    name="my-assistant",
    model="openai/gpt-4o",
    embedding="openai/text-embedding-3-small",
    memory_blocks=[
        {"label": "persona", "value": "You are a helpful assistant."},
        {"label": "human", "value": "The user's name and preferences."},
    ],
)

# Send a message
response = client.agents.messages.create(
    agent_id=agent.id,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.messages[-1].content)

1. Architecture Selection

Use letta_v1_agent when:

• Building new agents (recommended default)
• Need compatibility with reasoning models (GPT-4o, Claude Sonnet 4)
• Want simpler system prompts and direct message generation

Use memgpt_v2_agent when:

• Maintaining legacy agents
• Require specific tool patterns not yet supported in v1

For detailed comparison, see references/architectures.md.

2. Memory Architecture Design

Memory is the foundation of effective agents. Letta provides three memory types:

Core Memory (in-context):

• Always accessible in agent's context window
• Use for: current state, active context, frequently referenced information
• Limit: Keep total core memory under 80% of context window

Archival Memory (out-of-context):

• Semantic search over vector database
• Use for: historical records, large knowledge bases, past interactions
• Access: Agent must explicitly call archival_memory_search
• Note: NOT automatically populated from context overflow

Conversation History:

• Past messages from current conversation
• Retrieved via conversation_search tool
• Use for: referencing earlier discussion, tracking conversation flow

See references/memory-architecture.md for detailed guidance.

3. Memory Block Design

Core principle: One block per distinct functional unit.

Essential blocks:

• persona: Agent identity, behavioral guidelines, capabilities
• human: User information, preferences, context

Add domain-specific blocks based on use case:

• Customer support: company_policies, product_knowledge, customer
• Coding assistant: project_context, coding_standards, current_task
• Personal assistant: schedule, preferences, contacts

Memory block guidelines:

• Keep blocks focused and purpose-specific
• Use clear, instructional descriptions
• Monitor size limits (typically 2000-5000 characters per block)
• Design for append operations when sharing memory between agents

See references/memory-patterns.md for domain examples and references/description-patterns.md for writing effective descriptions.

4. Model Selection

Match model capabilities to agent requirements:

For production agents:

• GPT-4o or Claude Sonnet 4 for complex reasoning
• GPT-4o-mini for cost-efficient general tasks
• Claude Haiku 3.5 for fast, lightweight operations
• Gemini 2.0 Flash for balanced speed/capability

Avoid for production:

• Small Ollama models (<7B parameters) - poor tool calling
• Models without reliable function calling support

See references/model-recommendations.md for detailed guidance.

5. Tool Configuration

Start minimal: Attach only tools the agent will actively use.

Common starting points:

• Memory tools (memory_insert, memory_replace, memory_rethink): Core for most agents
• File system tools: Auto-attached when folders are connected
• Custom tools: For domain-specific operations (databases, APIs, etc.)

Tool Rules: Use to enforce sequencing when needed (e.g., "always call search before answer")

Consult references/tool-patterns.md for common configurations.

Advanced Topics

Memory Size Management

When approaching character limits:

1. Split by topic: customer_profile → customer_business, customer_preferences
2. Split by time: interaction_history → recent_interactions, archive older to archival memory
3. Archive historical data: Move old information to archival memory
4. Consolidate with memory_rethink: Summarize and rewrite block

See references/size-management.md for strategies.