Letta Memory Architect

This skill guides the design of effective memory architectures for Letta agents, including memory block structure, memory type selection, and concurrency patterns.

When to Use This Skill

Use this skill when users are:

• Designing memory block structure for a new agent
• Choosing between core memory, archival memory, and conversation history
• Optimizing memory block organization for performance
• Implementing shared memory between agents
• Debugging memory-related issues (size limits, concurrency)

Memory Architecture Process

1. Memory Type Selection

Consult references/memory-types.md for detailed comparison. Quick guidance:

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 archivalmemorysearch
• 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

2. 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:

For customer support:

company_policies:
  description: "Company policies and procedures. Reference when handling customer requests."
  read_only: true

product_knowledge:
  description: "Product features and common issues. Update when learning new solutions."
  read_only: false

customer:
  description: "Current customer's context and history. Update as you learn more about them."
  read_only: false

For coding assistants:

project_context:
  description: "Current project architecture and active tasks. Update as project evolves."
  
coding_standards:
  description: "Team's coding standards and review checklist. Reference before code suggestions."
  read_only: true

current_task:
  description: "Active task and implementation progress. Update as work progresses."

See references/memory-patterns.md for more domain examples.

3. Label and Description Best Practices

Labels:

• Use underscores, not spaces: brand_guidelines not brand guidelines
• Keep short and descriptive: customerprofile, projectcontext
• Think like variable names

Descriptions: Use instructional style for blocks the agent actively manages:

Good:

"Brand tone and style guidelines. Reference this when generating content to ensure consistency with brand identity."

Poor:

"Contains brand information"

Template for active blocks:

[What this block contains]. [When to reference it]. [When/how to update it].

Consult references/description-patterns.md for examples.

4. Size Management

Character limits per block:

• Typical limit: 2000-5000 characters
• Monitor via block size in ADE or API

When approaching limits:

1. Split by topic: customerprofile → customerbusiness, customer_preferences
2. Split by time: interactionhistory → recentinteractions, 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.

5. Concurrency Patterns

When multiple agents share memory blocks or 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 patterns.

Validation Questions

Before finalizing memory architecture:

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

Common Antipatterns to Avoid

Too few blocks:

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

Split into focused blocks instead.

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

Poor descriptions:

# Bad
data: "Contains data"

Provide actionable guidance instead.

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

Next Steps

After architecture design:

1. Create memory blocks via ADE or API
2. Test agent behavior with representative queries
3. Monitor memory tool usage patterns
4. Iterate on structure based on actual usage