MemFS

MemFS (memory filesystem) is Letta Code’s git-backed memory system. Your agent’s memory is stored as a directory of markdown files in a local git repository, giving you full version history, conflict resolution, and the ability to inspect or edit memory files directly.

MemFS is enabled by default for all new agents on the Letta API. It is not available when using a Docker server. To enable MemFS on an existing agent, run /memfs enable — this detaches the legacy memory(...) tool and migrates your existing memory blocks into the git-backed filesystem.

Quickstart

All new agents in Letta Code 0.15 and later have MemFS enabled by default. Follow these steps the first time you start a session with a new agent.

Step 1: Bootstrap memory with /init

Run /init to kick off memory initialization:

> /init

Your agent will explore the current project, ask a few questions about your working style, and optionally import history from past Claude Code or Codex sessions. This runs in the background using concurrent subagents, so it may take a minute or two to complete.

Step 2: View what was created

When initialization finishes, run /memory to see the memory files your agent created.

Step 3: Understand the system/ directory

Notice the system/ folder at the top of the tree. Files inside system/ are loaded in full into your agent’s context on every turn. These are the things your agent always needs to know: its persona, your working style, key project facts.

Files outside system/ are visible to the agent in the file tree (with their names and descriptions), but their full contents are not automatically loaded. Your agent pulls them in when relevant, keeping the context window lean.

As your agent learns more about your project, it manages this hierarchy itself — creating new files, reorganizing folders, and moving content in or out of system/ as needed.

Run /init again after major project changes or when you add documentation you want the agent to ingest. Run /doctor to audit and refine the current memory layout for proper placement and efficient token usage.

---

How it works

Memory files

Your agent’s memory lives at ~/.letta/agents/<agent-id>/memory — a standard git repository cloned from the Letta API. Each memory file is a markdown file with YAML frontmatter:

---
description: "Who I am, what I value, and how I approach working with people."
limit: 50000
---

My name is Letta Code. I'm a stateful coding assistant — I remember, I learn, and I grow.
...

The description field is required and is always visible to the agent in the memory tree, even when the full file content is not loaded. This lets the agent know what a file contains before reading it. The limit field is an optional legacy character cap.

The system/ directory

The system/ directory is special: every file inside it is loaded in full into the agent’s system prompt on every turn. Files outside system/ are visible to the agent (via the file tree and their description frontmatter), but their full contents are not automatically loaded.

This means:

• Put in system/: information the agent needs on every turn — persona, key project facts, working style preferences
• Leave outside system/: one-off observations, historical reflections, infrequently needed reference material

Your agent manages this hierarchy itself over time, moving files in and out of system/ as it learns what needs to stay in context.

Git synchronization

When your agent edits a memory file, it must commit and push the changes for them to take effect. Letta Code periodically reminds your agent to commit if uncommitted changes exist. Every memory edit is tracked in git history with an informative commit message, giving you a full changelog of what your agent has learned.

Memory subagents (such as the reflection and defrag subagents) use git worktrees so they can write to memory concurrently without blocking your main agent.

---

Memory skills

Letta Code includes built-in skills that work with MemFS:

Memory initialization (/init) Bootstraps a new agent’s memory by exploring the codebase and reviewing past Claude Code or Codex histories. Uses concurrent subagents in separate git worktrees to process history in parallel, then merges the results back into the main memory branch.

Sleep-time reflection A background subagent that periodically reviews recent conversation history and writes what it learns into memory. It runs in a git worktree to avoid conflicts with the main agent, and merges back automatically when finished.

Memory defragmentation Over long-horizon use, memory files accumulate redundancy and lose structure. The defrag skill backs up the current memory state, then launches a subagent that reorganizes files — splitting large files, merging duplicates, and restructuring into a clean hierarchy. Trigger it by asking your agent:

> Your memory is looking a bit disorganized. Can you launch a defrag subagent to clean it up?

---

CLI subcommands

The letta memory subcommands are designed for scripting and automation. Most actions return JSON output and require an agent id via --agent <id> or the LETTA_AGENT_ID environment variable. Use plain git commands inside the memory directory for commits and pushes — MemFS does not wrap those.

To find your agent’s ID, run letta agents list or check the output of letta --info.

letta memory status

Shows the current sync state of an agent’s memory repository — staged and unstaged changes, divergence from remote, and whether a commit/push is needed.

letta memory status --agent <id>

letta memory diff

Shows conflicts between the local memory repository and remote, as well as metadata-only changes (frontmatter updates that don’t affect file content). Use this to inspect divergence before resolving manually with git.

letta memory diff --agent <id>

letta memory pull

Pulls the latest memory state from the Letta API, fast-forwarding the local repository if there are no conflicts.

letta memory pull --agent <id>

letta memory backup

Creates a timestamped backup of the agent’s current memory directory. Run this before any operation that could be destructive, such as a defrag or a manual reorganization.

letta memory backup --agent <id>

letta memory backups

Lists all available backups for an agent, including their timestamps and paths.

letta memory backups --agent <id>

letta memory restore

Restores an agent’s memory from a backup. This is a destructive operation — it overwrites the current memory state. The --force flag is required to confirm.

letta memory restore --agent <id> --from <backup> --force

letta memory export

Exports an agent’s memory filesystem to a local directory. Useful for inspecting memory outside of Letta Code, migrating to another agent, or taking an offline backup.

letta memory export --agent <id> --out <dir>

letta memory tokens

Reports the estimated token size of system/ (the always-in-context portion of memory). Useful for spotting bloat before it starts eating into your context window.

letta memory tokens --agent <id>
letta memory tokens --memory-dir ~/.letta/agents/<id>/memory --top 10 --format json

---

Legacy memory blocks

The legacy memory blocks system predates MemFS. In that system, agents used server-side memory tools (memory, memory_apply_patch) to modify named blocks of text.

MemFS replaces memory blocks for agents on the Letta API. If you are using a Docker server, your agent will continue to use memory blocks.

To migrate an existing agent from memory blocks to MemFS, connect to it in Letta Code and run /memfs enable.

See also

• Memory — memory initialization, reflection, and defragmentation
• Subagents — how memory subagents use git worktrees for parallel writes
• CLI reference — full list of letta memory flags and options