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 acts identically. 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)

For new MemFS-enabled agents, Letta Code now runs a shallow background init automatically on your first user message. This fast pass captures core project context and identity basics without blocking chat.

When you run /init manually, Letta Code now performs a deeper interactive initialization in the main conversation, guided by context constitution principles for durable identity, preferences, and project structure. The primary agent can ask follow-up questions, load the initializing-memory skill, and update memory blocks directly as it learns more about your project and workflow.

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.

If your memory structure has drifted or become messy over time, run /doctor to audit the current layout and refine it without doing a full re-initialization pass.

Switching personalities (/personality)

Use /personality to swap between curated presets like Letta Code, Linus, Letta-Chan, Claude, and Codex. Letta Code updates the agent’s system/persona.md and system/human.md, commits the change to MemFS, and then asks you to run /clear or /new so the new personality fully takes effect in-message history.

Personality switching requires a clean memory repo. If your MemFS repo has uncommitted changes, commit or discard them first.

If you want a fresh agent that starts with a specific preset, use letta agents create --personality <name> from the CLI.

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

The trigger determines how often the reflection subagent is auto-launched:

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

When a reflection trigger fires, Letta Code launches the reflection subagent in the background automatically. The older reminder-only mode is gone, and --reflection-behavior remains only as a deprecated compatibility flag.

When the reflection subagent is finished working, a notification is 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 available through the Letta API and on Docker servers with LETTA_MEMFS_SERVICE_URL=local. See the Docker setup guide for details.

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 and optional metadata such as a legacy character limit or read-only status (if read-only is true, the agent will be unable to edit the file). The description field is required. 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 supported through Letta Code on the Letta API, and on Docker servers with LETTA_MEMFS_SERVICE_URL=local (see Docker setup guide). You can chat with MemFS-enabled agents in the ADE or chat.letta.com, but the agent 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.