Agent Memory Overview

What is Agent Memory?

Agent Memory gives an agent continuity: who it is, who it works with, what it has learned, and what it is still working toward.

At its core, a memory is a folder. Markdown files at the root of the folder are always loaded into the agent's context. Subdirectories hold everything else, and the agent reads into them on demand. An optional MEMORY.md file indexes the folder so the agent knows what is inside without loading it.

memory/
├── MEMORY.md          # In context: map of learned context
├── <file>.md          # In context: always available
├── <folder>/          # On demand: read when relevant
└── ...                # Any additional files or directories

That is the whole format. There are no required file names, no required schema, and no required storage backend. A memory folder containing a single MEMORY.md is valid. So is a folder with hundreds of files organized into nested directories.

Why Agent Memory?

Agents accumulate context that matters: preferences of the people they work with, corrections they've been given, decisions and their reasons, knowledge about projects. Today each product stores this differently, so memory is locked to one harness. An agent's accumulated experience should be portable, inspectable, and owned by its user, the same way Agent Skills made procedural knowledge portable.

• Plain files: Memory is markdown in a folder. You can read it, edit it, diff it, and back it up with tools you already have.
• Portable: The same memory folder works in any harness that supports the format. Moving an agent between products means moving a folder.
• Bounded context cost: Only root Markdown files are loaded. Everything else is disclosed progressively, so memory can grow without growing the prompt.

How does it work?

Agents load memory through progressive disclosure, in three stages:

1. Core memory: At session start, the harness loads every Markdown file at the memory root into the context window and shows the names of folders directly under the root. It does not recursively disclose what is inside them.
2. Discovery: When the agent needs something that isn't in context, it explores the relevant folder. A MEMORY.md index can tell it what the folder contains; otherwise it uses an ordinary directory listing.
3. Recall: The agent reads the specific files it needs with its ordinary file tools, going only as deep as the task requires.

Root Markdown files stay small and always present; the folder underneath can be effectively unlimited. When the harness provides write access, the agent can maintain memory with the same file tools it uses for everything else.

Memory, AGENTS.md, and skills

Models are post-trained to use AGENTS.md and Agent Skills. Memory complements them rather than replacing them; the distinction is purpose and scope:

A useful test: if the content would still be true for a brand-new agent dropped into the project, it belongs in AGENTS.md or a skill. If it is durable context meant to travel with or be attached to an agent, it belongs in memory.

Open development

The Agent Memory format was originally developed by Letta, and is designed to work with existing memory systems in existing agent harnesses, including OpenClaw, Hermes Agent, Pi, Claude Code, Codex, and others.

If you are interested in contributing, please join the discussion on GitHub or email us.

Get started