Memory

Memory is what makes a Letta agent stateful. An agent’s memory is its own: it persists across conversations, follows the agent between models and computers, and the agent edits it as it learns.

Persona and human shorthand

persona and human are conveniences that set the agent’s persona and human memory:

const agentId = await client.createAgent({
  persona: "You are a resident engineering teammate for this repository.",
  human: "The user prefers practical handoffs with commands to run.",
});

Setting memory at creation

Pass memory for full control over the agent’s starting memory. Each entry becomes a Markdown file in the agent’s memory repository, named from its label:

const agentId = await client.createAgent({
  model: "anthropic/claude-opus-4-8",
  memory: [
    {
      label: "persona",
      value: "You are Quinn, a digital research analyst.",
    },
    {
      label: "team-context",
      value: "The team ships weekly on Thursdays. Staging is at stage.example.com.",
    },
  ],
});

Use objects with label and value; creation backends reject memory preset names.

Shared memory repositories give several agents access to the same files. Attaching one recompiles the agent’s system prompt so the repository shows up in its context — as a file tree it reads from on demand, rather than inlined the way system/ memory is. Repositories are hosted by Letta, so they are a cloud feature; self-hosted deployments can share memory by pointing agents at their own git remote.

MemFS

An agent’s memory is part of its state, not a folder on a machine: it lives in a git repository owned by the agent, which MemFS projects onto whatever computer the agent is working on. Edits become memory once they are committed and pushed. See MemFS for the full model.

Two things matter when you are writing against the SDK:

• A memory entry’s label becomes its path in the repository, and memory you set at creation lands under system/.
• Files under system/ are in the system prompt every turn. Everything else stays out of context — the agent sees the file tree and reads what it needs.

To find the memory directory on the computer the agent is working on, ask the session:

const { memoryDirectory } = await session.getDeviceStatus();
// → "/root/.letta/agents/agent-3f97f111-…/memory"

Dreaming

Dreaming uses background subagents to review recent conversations, consolidate lessons, and update memory without interrupting active work. Configure it with dreaming:

const agentId = await client.createAgent({
  persona: "You are a support engineer who learns each customer's environment.",
  dreaming: {
    trigger: "step-count", // "off" | "step-count" | "compaction-event"
    behavior: "auto-launch", // "reminder" | "auto-launch"
    stepCount: 25,
  },
});

• trigger controls when dreaming runs: after a number of steps, on context compaction, or never.
• behavior controls what happens at the trigger: remind the agent to update memory, or automatically launch a background dreaming subagent. It can only be set at agent creation.
• stepCount is the step interval for the "step-count" trigger.

Sessions can override trigger and stepCount (but not behavior) with the session dreaming option. The init message reports the effective settings for a session.

What to read next

• Creating agents — setting memory and dreaming at creation time
• Shared memory — versioned repositories shared between agents
• MemFS — the git-backed memory filesystem in depth