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.

Agents and conversations

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” or “main chat”.

When you run the letta CLI command in a project directory, Letta Code resumes the default conversation with your last used agent. In the Letta Code desktop app, the left sidebar is sorted by agents, and you can see conversations sorted by activity date.

If you want to run many CLI sessions with a single agent in parallel (eg in separate terminal windows), use letta --new to start a new conversation. In the desktop app, simply press the notepad icon to start a new conversation.

Letta Code has a default agent pre-installed (called “Letta Code”). To swap agents in the CLI, use /agents. You can favorite an agent in the CLI with “/pin”, or by clicking the favorites button in the desktop app.

Initializing your agent’s memory

When you run /init, Letta Code performs an interactive initialization in the main conversation, guided by context constitution principles for durable identity, preferences, and project structure. 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 memory layout and refine it for proper memory placement and efficient token usage.

Manually triggering memory updates

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 dreaming (reflection)

To improve proactive memory creation and consolidation, Letta Code launches periodic sleep-time (dream) 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 in the CLI to configure your reflection settings, or by clicking the sleeping alien icon in the bottom-right of the app.

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 dream trigger fires, Letta Code launches the dream subagent in the background automatically.

Dream/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.

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 older agent, run /memfs enable.

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.