---
title: MemFS | Letta Docs
description: Understand the git-backed memory filesystem used by Letta agents
---

**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](https://www.letta.com/blog/context-repositories).

## 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](/letta-agent/skills/index.md) for skill sources, precedence, and authoring.

## Shared memory

Every agent has its own MemFS for personal memory. If multiple cloud-hosted agents need to share memory with each other, attach the same **shared memory** repository to each of them.

A shared memory repository is git-backed context that does not belong to only one agent. Every attached agent can access the same files and working context, read or update them with file and shell tools, and see changes made by the others. Changes are versioned with git.

Use shared memory for context that should not belong to only one agent, such as:

- Team conventions and shared instructions
- Product or project knowledge
- Research and reference material
- Plans and documents that multiple agents maintain together

You can work with shared memory through the web and desktop apps. Applications can also manage repositories and attach them to cloud-hosted agents with the [Agent SDK](/letta-agent-sdk/repositories/index.md).

## Managing memory

See [Memory & dreaming](/letta-agent/memory/index.md) to initialize memory, teach your agent, configure background reflection, and reorganize a hierarchy that has grown over time.