Memory Model

How Letta's stateful memory system works and how lettactl manages memory lifecycle across your fleet.

Why Stateful Memory Matters

Most AI agents are stateless — every conversation starts from zero. Letta agents have persistent memory that survives across sessions. They remember what you told them, learn from interactions, and build context over time. lettactl gives you infrastructure-level control over this memory.

Core Memory (Blocks)

Core memory blocks are the agent's working memory — always loaded into the context window. Each block has a name, description, token limit, and content. Think of them as structured scratchpads the agent can read and write to during conversations.

agent_owned vs YAML-managed

This is the critical distinction. When `agent_owned: true`, the agent modifies the block during conversations and lettactl preserves those changes on redeploy. When `agent_owned: false`, the YAML content is the source of truth — lettactl will overwrite whatever the agent wrote. Use agent_owned for things like customer context that accumulates. Use YAML-managed for reference data you control.

Ownership modes
memory_blocks:
  # Agent learns and accumulates here
  - name: user_preferences
    description: "What I've learned about this user"
    agent_owned: true
    limit: 5000

  # You control this content
  - name: pricing_rules
    description: "Current pricing logic"
    agent_owned: false
    limit: 3000
    from_file: "memory/pricing.md"

Archival Memory

Long-term storage with vector search. Agents write to archival memory using the `archival_memory_insert` tool and search it with `archival_memory_search`. Unlike core memory, archival memory isn't loaded into the context window — the agent queries it on demand. Useful for building up large knowledge stores over time.

Shared Memory

Shared blocks let multiple agents read from the same memory. Define a block once at the top level and reference it by name in each agent. When you update the content in YAML, every agent gets the update on next apply. This is how you keep a fleet in sync — brand guidelines, product catalogs, company policies.

Memory Lifecycle

On first deploy, lettactl creates blocks with their initial content. On subsequent deploys, the diff engine checks each block: if it's agent_owned, it leaves the content alone (only updates metadata like description or limit). If it's YAML-managed, it compares content and updates if different. Deleting a block from YAML detaches it from the agent on next apply.