Specification

Directory structure

A memory is a directory. It may contain markdown files, other files, and subdirectories:

memory/
├── MEMORY.md          # Optional: index of the memory folder
├── persona.md         # Root files are loaded into context
├── human.md
├── projects/          # Read on demand
│   ├── MEMORY.md      # Optional: index for this directory
│   └── letta-code.md
└── notes/
    └── 2026-08-12.md

There are no required file names and no required directory names. A memory containing a single root Markdown file is valid.

The core contract

A conforming harness provides three guarantees:

1. Root Markdown files are in context. Every .md file at the root of the memory directory is loaded into the agent's context window, always visible to the model.
2. Deferred memory is readable on demand. The harness gives the agent a way to read files below the memory root when needed. It does not load those files into context at session start.
3. Loaded memory stays current. When a loaded root Markdown file changes, the harness either refreshes what the model sees or tells the model that its loaded copy is stale.

Because root Markdown files are the always-loaded tier, existing single-file and few-file layouts are already conforming: MEMORY.md alone, a USER.md/HUMAN.md pair, or a soul/persona/style set of files are all valid memory roots.

Freshness

When an in-context file changes, the model must either see the updated content or be told its loaded copy is stale. The mechanism is up to the harness: recompiling the prompt at session start, refreshing on file change, or refreshing at commit boundaries are all conforming. What is not conforming is silently serving stale root Markdown files indefinitely while the files on disk have moved on.

The MEMORY.md index

MEMORY.md is an optional index file that points the agent toward memory it may need later. The root MEMORY.md, when present, is loaded into context like any other root file. This lets it guide progressive disclosure without requiring the harness to inject a separate file tree.

The name is uppercase by convention — like README.md, SKILL.md, and AGENTS.md — signaling that the file is meaningful to the harness rather than ordinary memory content. All other file names are yours to choose.

The format of MEMORY.md is deliberately flexible. It can be learned (written and maintained by the agent), generated (compiled by the harness from the directory tree), or partially managed (the harness maintains a file listing while the agent maintains descriptions and retrieval guidance around it). All three are conforming indexes:

# Generated: one line per entry
- [persona.md] — Who I am and how I communicate
- [projects/] — What I know about each project I work on
- [notes/] — Dated session notes, newest first

# Learned: free-form navigation notes
Load context about a person from projects/<name>.md before
their standup. Debugging lore lives in notes/, filed by date.

Subdirectories may contain their own MEMORY.md describing their contents, and deeply nested trees repeat the pattern at each level the agent finds useful. A root MEMORY.md is recommended whenever the memory contains deferred files. The index only needs to point toward the next useful layer; it does not need to enumerate every descendant.

Progressive disclosure

Agents load memory progressively, in three tiers, mirroring how Agent Skills are loaded:

Directories exist to collapse context: if the agent is looking at a directory, it should not pay for the contents of that directory's subdirectories until it chooses to look. Frequently used context belongs in higher levels; rarely used context belongs deeper. Large numbers of related files should be collapsed into a subdirectory with an index built for navigation.

Root size budget

Everything at the root is paid for on every request, so the root must stay small. The spec recommends:

• Root Markdown files should total no more than ~10,000 tokens (roughly 40 KB), and substantially less is better.
• Any single topic that grows past a few hundred lines should be demoted into a directory, leaving a summary or index entry at the root.

These are recommendations rather than hard limits, but a harness is free to warn or refuse when the root exceeds its budget, and the Extras section shows how to enforce a budget mechanically.

Extras

Everything in this section is optional. These conventions make memory more robust and more portable, but a memory directory that uses none of them is still fully conforming. Harnesses must not reject a memory for lacking them.

File frontmatter

Memory files may carry YAML frontmatter mirroring the Agent Skills fields:

---
name: letta-code
description: What I know about the letta-code repo — build system,
  review conventions, and recurring gotchas.
metadata:
  updated: "2026-08-12"
---

The build uses bun, not npm. ...

Frontmatter is never required. Memory written without it (OpenClaw, Hermes) and memory written with it (Claude Code auto-memory, Letta) are equally valid, and harnesses that don't understand frontmatter can treat it as file content.

Version marker

A memory directory may declare which version of this spec it follows with a .memoryspec file at the root containing a single version string:

v1

The marker lets harnesses and migration tools detect the layout generation without guessing from structure. Dotfiles at the memory root are not memory content for the purposes of the core contract: they are not loaded into context.

Version control

The spec is silent on storage: a memory root is just a directory, on any filesystem. That said, tracking the memory directory with git is strongly recommended:

• Traceability: every change to what the agent knows has an author, a time, and a reason.
• Continuity: memory can be moved between machines and harnesses by cloning; conflicting concurrent edits merge with normal git machinery.
• Recovery: bad memory edits are revertable, and an agent can inspect the history of its own beliefs.

Codex and Letta Code both git-track memory today. Commit boundaries also pair naturally with the freshness rule: recompile in-context memory when the committed state changes.

Enforcing the root budget

When memory is git-tracked, budgets become enforceable with an ordinary pre-commit hook. For example, rejecting commits that push the root past 40 KB:

#!/bin/sh
# .git/hooks/pre-commit — keep the always-in-context root small
BUDGET=40960
total=$(find . -maxdepth 1 -type f -name '*.md' \
  -exec cat {} + | wc -c)
if [ "$total" -gt "$BUDGET" ]; then
  echo "memory root is ${total} bytes (budget ${BUDGET})."
  echo "Demote detail into a subdirectory and index it."
  exit 1
fi

The same hook point can validate index freshness (every entry in MEMORY.md resolves to a real path) or frontmatter well-formedness, turning the spec's recommendations into checks the agent gets immediate feedback on.

What Agent Memory does not define

The format stays deliberately small so existing memory systems can adopt it without replacing how they work.

Memory taxonomy

Agent Memory does not prescribe how an agent organizes memory. An agent may keep everything in one MEMORY.md, use files such as USER.md, SOUL.md, or PERSONA.md, or divide memory into any number of files and folders. These choices do not affect compatibility.

Traces and trajectories

Agent Memory does not define how conversation traces, tool calls, or execution trajectories are stored. Those records capture what happened; memory contains durable context the agent carries forward. Harnesses may derive memory from traces, but trace storage is a separate concern. For a portable format for agent trajectories, see Trajectory.

Non-Markdown files

Agent Memory standardizes Markdown memory files. Other file types may coexist in the memory folder, but the spec does not define how they are loaded or shown to the model. Harnesses may support additional types. For example, Letta Code can associate a root profile.png with the agent's visual identity.

Learning and forgetting

Agent Memory does not prescribe how memory is created, consolidated, corrected, or forgotten. Harnesses may use direct agent edits, user edits, reflection, summarization, or background processing. The spec defines the portable result, not the learning algorithm.

Storage and synchronization

Agent Memory does not require git, a database, a vector store, or a particular synchronization service. A harness may use any backend as long as the agent sees a conforming memory folder.

Ownership, sharing, and permissions

Agent Memory does not define who owns memory or who may modify it. A memory root may contain agent-owned, user-owned, organization-owned, or shared sources, and individual files or folders may be writable or read-only. The same loading and progressive-disclosure rules apply after those sources appear in the memory root.

Harnesses may add their own attachment, permission, synchronization, and conflict-resolution systems. For example, Letta Code can attach memory repositories with different owners into one agent's memory root. Agent write access is useful for learning, but it is a harness capability rather than a requirement of this format.

If you are an agent reading this

This document may itself be stored inside a memory directory, and you may be reading it from your own filesystem. The canonical version of the specification, with guides for migration and harness integration, lives at agentmemory.io. The short version of your responsibilities: keep your root small, keep your indexes true, demote detail into directories, and treat memory edits as writing for your future self.