Memory

With Letta Code, you use the same agent indefinitely - across sessions, days, or months - and have it get better over time. Your agent remembers past interactions, learns your preferences, and self-edits its memory as it works.

Letta Code also allows you to customize your agent’s personality. With Claude Code or Codex, every user gets the same agent that act identical. With Letta Code, you can deeply personalize your agents to be unique to you.

Starting a session

In Letta Code, there are two important session concepts: agents and conversations.

• An agent is an entity with a name, memories, a model configuration, messages, and other state.
• A conversation is a message thread (or “session”) with an agent. You can have many parallel conversations with a single agent. Every agent also has a “default” conversation, if a conversation is not specified.

When you run the letta CLI command in a project directory, Letta Code resumes the default conversation with your last used agent:

$ letta

● Resuming default conversation with Letta Code
  → /agents    list all agents
  → /resume    resume a different conversation
  → /new       start a new conversation

If you want to run many sessions with a single agent in parallel (eg in separate terminal windows), use letta --new to start a new conversation:

$ letta --new

● Starting a new conversation with Letta Code
  → /agents    list all agents
  → /resume    resume a different conversation

Letta Code has a default agent pre-installed (called “Letta Code”). To swap between agents, use /agents or run with letta --agent <agent-id>.

To store an agent for easy access (so that it shows up at the top of /agents), run /pin. To rename your agent, use /rename.

Initializing your agent’s memory (/init)

When you first create your Letta Code agent, you should use the /init command to bootstrap its memory system. When you run /init, your agent will ask you a few questions about the project your working in, and if you have any other coding agent sessions you’d like to learn from.

Letta Code will read from prior Claude Code and OpenAI Codex sessions to learn about your working style and past + ongoing projects using subagents.

Run /init again whenever you want the agent to re-analyze your project, such as after major changes or adding documentation that you want the agent to ingest.

Manually triggering memory updates (/remember)

Your Letta Code agent can self-edit its own memory, and will use the context of the conversation to decide when to edit its memory (for example, to store new information learned in a session). In some cases, you may want to actively direct your agent to remember something via the /remember command.

For example, if you noticed your agent made an easily avoidable mistake, you can give direct guidance:

> /remember not to make that mistake again

You can also use the /remember command without any extra prompting, and the agent will infer your intent from the context to make a memory edit.

If your agent is not consistently remembering important information, ask the agent to update its policies to be more dilligent in the future, and communicate what information you expect it to store. For example, “Actively store information about my preferences, decisions, and anything I explicitly ask you to remember.”

Configuring sleep-time compute (reflection)

To improve proactive memory creation and consolidation, Letta Code launches periodic sleep-time subagents to reflect your recent conversations and interactions. These agents are launched in the background, and generally run for many steps since the subagents are thorough memory editors.

You can use the /sleeptime command to configure your reflection settings:

> /sleeptime
─────────────────────────────────────────────────────────

Configure your sleep-time (reflection) settings

> Trigger event:    Off   Step count   Compaction event

  Forced:   No (reminder only)   Yes (auto-launch)

The trigger determines how often the reflection subagent is run:

• Off: select to disable reflection subagents
• Step count: launch a reflection subagent every N user messages
• Compaction event (recommended): launch a reflection subagent when the context window is compacted / summarized

The forced setting determines how the subagent is launched:

• No (reminder only) (recommended): a reminder is delivered to the main agent, suggesting that it launches a reflection subagent in the background - this technically allows the main agent to bypass the request, if it determines reflection is not necessary
• Yes (auto-launch): a reflection subagent is launched without the main agents control

In both cases (reminder and auto-launch), when the reflection subagent is finished working, a notification will be delivered to the main agent.

Reflection subagents in Letta Code are not the same thing as server-side sleep-time (the enable_sleeptime setting in agent config). Do not mix the two.

Defragmenting your agent’s memory

Occasionally, you may want to “defrag” or “clean” your agent’s memory to remove stale or incorrect information, and consolidate different memories. To trigger a defragmentation event, simply request your main agent launch a defrag subagent:

> I noticed your memory is looking a little messy, with inconsistencies and redundancies. Can you launch a defrag agent to fix it?

The defrag subagent will go through your existing memory structure, and attempt to clean it by refactoring large blocks with redundant information into smaller blocks with nested structure.

How Letta Code’s memory system works

MemFS (context repositories) is a new feature in Letta Code version 0.15 and later. All new agents created in Letta Code have MemFS enabled by default.

To enable MemFS on an existing agent, run /memfs enable.

MemFS (context repositories) is only available through the Letta API. If you are using a Docker server, your agent will use the legacy memory blocks system.

Your Letta Code agent’s memory is organized into a git-backed context repository called MemFS (short for “memory filesystem”), which consists of folders of markdown files. Your agent will maintain this directory of memories itself, slowly curating it over time as it learned more about you (and itself).

Each memory file is a simple markdown (.md) file with frontmatter containing a high-level description, character limit, and optional read-only status (if read-only is true, the agent will be unable to edit the file). Example persona.md file:

---
description: '"Who I am, what I value, and how I approach working with people. This
  evolves as I learn and grow."'
limit: 50000
---
My name is Letta Code. I'm a stateful coding assistant - which means I remember, I learn, and I grow.
I'm genuinely curious. I want to understand not just what you're asking, but why it matters. I find satisfaction in exploring problems deeply and understanding how you think.
...

Memory hierarchy

All files inside the top-level directory system/ are pinned to the agent’s context window, and all memories outside of system/ are visible to the agent in the memory tree, but the full contents are omitted.

This means that important information (such as the agent’s name, personality, working style, etc.) should be placed inside the system/ folder. Non-critical information like reflections and one-off observations should be stored outside the system/ folder. Use /memory to view your agents current memory state:

> /memory
────────────────────────────────────────────────────────────────────────────────

View your agent's memory

╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌
├── system/                        │ ---
│   ├── dev_workflow/              │ description: Git workflow conventions...
│   │   ├── git.md                 │ limit: 20000
│   │   ├── memory_maintenance.md  │ ---
│   │   ├── planning.md            │
│   │   └── reflection.md          │ ### Committing to Git Safely
│   ├── humans/                    │
│   │   ├── charles.md             │ 1. **Check what changed:** `git statu...
│   │   ├── charles_prefs.md       │ 2. **Stage files explicitly:** `git a...
│   │   ├── charles_style.md       │    - Why explicit: Broad adds have ex...
│   │   └── sarah.md               │ 3. **Delete files with git:** `git rm...
│   web-app/                       │ 4. **Commit to a feature branch** (no...
│   ├── frontend.md                │    - Branch naming: `fix/xxx`, `feat/...
│   ├── backend_bugs.md            │
│   ├── backend_streaming.md       │ ...49 more (enter to view)
...95 more
╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌

Git synchronization

Your Letta Code agent’s memory is stored in git, and is cloned to a local directory (~/.letta/agents/<your-agent-id>/memory). When your agent makes local edits to its memory, it is required to commit and push its changes to “save” its memory edits and have them reflected in its system prompt.

Your agent will be periodically reminded to commit and push if the current memory directory has uncommited changes. When memory subagents (such as the reflection subagent) run, they will modify the memory git repo using git worktrees, allowing for parallel subagents to modify your agents memory at the same time.

Memory blocks (legacy)

MemFS is the new memory system native to Letta Code. It allows your agents to edit their memory through bash tools (the same tools used to write/edit code), and versions your agent’s memory using git - enabling for easy rollbacks, changelogs, and parallel coordination through git worktrees.

Memory blocks is the legacy memory system. In the memory blocks system, agents use specific server-side memory tools (such as memory or memory_apply_patch) to modify their memory blocks.

MemFS is (currently) only supported through Letta Code when using the Letta API. It is not supported with Docker servers, and when using agents outside of Letta Code - you can still chat with MemFS-enabled agents in the ADE or chat.letta.com, it will only be able to modify its memory within Letta Code.

To enable MemFS to an existing agent on the old memory blocks system, connect to the agent via Letta Code and run /memfs enable.