MemFS

MemFS is the git-backed filesystem where a Letta agent stores long-term memory. It projects the agent’s memory into Markdown files so the agent can read, edit, organize, and version what it learns.

MemFS is also called a context repository.

Memory structure

Each memory file is Markdown with YAML frontmatter:

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

I am a Letta agent. I remember durable preferences and improve with use.

Files under system/ are loaded into the agent’s system prompt on every turn. Use this directory for the agent’s identity, important user preferences, durable project facts, and critical workflow rules.

Files outside system/ remain discoverable through the memory tree, but their full contents are loaded only when relevant. This keeps the active context lean while preserving deeper reference material.

$MEMORY_DIR/
├── system/
│   ├── persona.md
│   └── human.md
├── reference/
│   └── project-notes.md
└── skills/
    └── my-skill/
        └── SKILL.md

Versioning and synchronization

Every memory edit is committed to the MemFS git repository. This provides version history, conflict resolution, and a clear boundary between saved memory and uncommitted changes.

For agents backed up to the cloud, commits sync back to Letta. Local-only agents commit to a repository on the current machine, so you are responsible for backing it up.

Memory subagents such as dreaming and memory doctor use git worktrees so they can update memory concurrently without blocking the main agent.

Skills in MemFS

Agent-owned skills live under $MEMORY_DIR/skills. They are versioned with the rest of the agent’s memory and travel with agents that are backed up to the cloud.

See Skills for skill sources, precedence, and authoring.

Managing memory

See Memory & dreaming to initialize memory, teach your agent, configure background reflection, and reorganize a hierarchy that has grown over time.