letta-development-guide

Comprehensive guide for developing Letta agents, including architecture selection, memory design, model selection, and tool configuration. Use when building or troubleshooting Letta agents.

⭐28stars🔀4forks📁View on GitHub🕐Updated Jan 9, 2026⬇️2downloads

When & Why to Use This Skill

This Claude skill serves as a comprehensive development guide for building and optimizing Letta agents. It provides expert guidance on agentic engineering, focusing on architecture selection, sophisticated memory design (core, archival, and conversation history), and tool configuration to create high-performance, stateful AI agents.

Use Cases

  • Designing long-term memory systems for AI agents to maintain context across extended interactions using Letta's multi-tier memory architecture.
  • Choosing between letta_v1 and memgpt_v2 architectures to ensure compatibility with specific LLMs like GPT-4o or Claude 3.5 Sonnet.
  • Optimizing agent performance by managing core memory limits and implementing archival search for large-scale knowledge retrieval.
  • Implementing multi-agent systems with shared memory blocks while managing concurrency patterns and avoiding data race conditions.
  • Troubleshooting and debugging memory-related issues in complex agentic workflows to improve reliability and reasoning accuracy.
nameletta-development-guide
descriptionComprehensive guide for developing Letta agents, including architecture selection, memory design, model selection, and tool configuration. Use when building or troubleshooting Letta agents.
licenseMIT

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

1. Architecture Selection

Use letta_v1_agent when:

  • Building new agents (recommended default as of October 2025)
  • Need compatibility with reasoning models (GPT-5, Claude 4.5 Sonnet)
  • 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 4.5 Sonnet for complex reasoning
  • GPT-4o-mini for cost-efficient general tasks
  • Claude Haiku 4.5 for fast, lightweight operations

Avoid for production:

  • Small Ollama models (<7B parameters) - poor tool calling
  • Gemini older than 2.5 Pro - function calling reliability issues

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.

Concurrency Patterns

When multiple agents share memory blocks or an agent processes concurrent requests:

Safest operations:

  • memory_insert: Append-only, minimal race conditions
  • Database uses PostgreSQL row-level locking

Risk of race conditions:

  • memory_replace: Target string may change before write
  • memory_rethink: Last-writer-wins, no merge

Best practices:

  • Design for append operations when possible
  • Use memory_insert for concurrent writes
  • Reserve memory_rethink for single-agent exclusive access

Consult references/concurrency.md for detailed patterns.

Validation Checklist

Before finalizing your agent design:

Architecture:

  • Does the architecture match the model's capabilities?
  • Is the model appropriate for expected workload and latency requirements?

Memory:

  • Is core memory total under 80% of context window?
  • Is each block focused on one functional area?
  • Are descriptions clear about when to read/write?
  • Have you planned for size growth and overflow?
  • If multi-agent, are concurrency patterns considered?

Tools:

  • Are tools necessary and properly configured?
  • Are memory blocks granular enough for effective updates?

Common Antipatterns

Too few memory blocks:

# Bad: Everything in one block
agent_memory: "Agent is helpful. User is John..."

Split into focused blocks instead.

Too many memory blocks: Creating 10+ blocks when 3-4 would suffice. Start minimal, expand as needed.

Poor descriptions:

# Bad
data: "Contains data"

Provide actionable guidance instead. See references/description-patterns.md.

Ignoring size limits: Letting blocks grow indefinitely until they hit limits. Monitor and manage proactively.

Implementation Steps

  1. Design phase:

    • Choose architecture based on requirements
    • Design memory block structure
    • Select appropriate model
    • Plan tool configuration
  2. Creation phase:

    • Create agent via ADE or API
    • Initialize memory blocks with proper descriptions
    • Attach necessary tools
  3. Testing phase:

    • Test with representative queries
    • Monitor memory tool usage patterns
    • Verify tool calling behavior
  4. Iteration phase:

    • Refine memory block structure based on actual usage
    • Optimize system instructions
    • Adjust tool configurations

References

For detailed information on specific topics, consult the reference materials:

  • references/architectures.md - Architecture comparison and selection
  • references/memory-architecture.md - Memory types and when to use them
  • references/memory-patterns.md - Domain-specific memory block examples
  • references/description-patterns.md - Writing effective block descriptions
  • references/size-management.md - Managing memory block size limits
  • references/concurrency.md - Multi-agent memory sharing patterns
  • references/model-recommendations.md - Model selection guidance
  • references/tool-patterns.md - Common tool configurations