Specification

Memory directory

Agent Memory is a directory containing Markdown files and optional subdirectories:

memory/
├── MEMORY.md
├── persona.md
├── human.md
├── projects/
│   ├── MEMORY.md
│   └── project.md
└── notes/
    ├── MEMORY.md
    └── 2026-08-12.md

Agent memory consists of core memory and external memory:

• Markdown files directly inside the memory root are core memory and are always in context.
• Markdown below the root is external memory and is not automatically loaded.
• Subdirectories structure progressive disclosure. Placing context deeper in the tree places it lower in the context hierarchy.

Every directory that is part of agent memory must contain MEMORY.md. A directory is part of memory when it contains Markdown memory directly or contains another memory directory.

The memory root may also contain directories governed by another format. For example, skills/ may contain Agent Skills and their Markdown resources. Those files remain valid alongside Agent Memory, but they are loaded and validated by the Agent Skills system rather than treated as core or external memory.

MEMORY.md

MEMORY.md can store context for its directory, index files and child directories, or do both.

The root MEMORY.md is core memory and is always loaded. A nested MEMORY.md remains outside the context window until the agent reaches that directory. It then provides the next layer of context and points toward more specific memory.

The agent must be able to discover context throughout the tree through progressive discovery of MEMORY.md files. A parent MEMORY.md may describe its child directories, or the harness may surface immediate child memory directories through a generated listing or search interface.

Valid configurations

A single root index with collapsed logs:

memory/
├── MEMORY.md
└── example-repository-name/
    ├── MEMORY.md
    ├── 03082026.md
    └── 03092026.md

Core memory only, with no external memory:

memory/
├── MEMORY.md
├── SOUL.md
└── USER.md

The smallest valid memory:

memory/
└── MEMORY.md

Several levels of progressive disclosure:

memory/
├── MEMORY.md
└── projects/
    ├── MEMORY.md
    └── project-1/
        └── MEMORY.md

Invalid configurations

A memory root without MEMORY.md is invalid:

memory/
├── project-1/
│   ├── MEMORY.md
│   ├── user_preferences.md
│   └── bad_bugs.md
└── project-2/
    ├── MEMORY.md
    ├── memories_03082026.md
    └── memories_03092026.md

A nested memory directory without its own MEMORY.md is also invalid:

memory/
├── MEMORY.md
└── notes/
    └── 2026-08-12.md

Harness contract

A conforming harness follows four rules:

1. Load root Markdown. Every .md file directly inside the memory root is included in the agent's context.
2. Defer nested Markdown. Markdown below the root is not automatically loaded into context.
3. Surface deferred memory. If nested memory exists, the harness gives the agent enough information to discover the next relevant MEMORY.md. This may come from the current MEMORY.md, an immediate-child directory listing, memory search, or an equivalent mechanism. Ordinary filesystem readability without memory-specific discovery is insufficient.
4. Support selective reads. The agent can load individual external-memory files when needed, through file tools or an equivalent memory-read interface.

The contract applies only to memory content. A harness may place unrelated instructions and conversation history in context as usual.

Size guidance

Root Markdown should stay small because it is expected to appear in the prefix on every request. A reasonable target is less than 30,000 tokens of core memory for a 200,000-token context window, or less than 15 percent of the context window.

Harnesses may enforce a limit when memory is edited, such as refusing a root-memory append that exceeds the configured budget. Agents should be guided to move detail into subdirectories and use progressive disclosure to keep core memory small.

This is a recommendation, not a compatibility requirement.

Scope

Agent Memory standardizes the directory and loading behavior. It does not define:

• how memory is edited or organized beyond the core-root and external-memory distinction;
• additional files required by a specific harness;
• who owns or may write each file;
• where memory is stored or how it is synchronized;
• whether memory is version-controlled;
• when a running conversation refreshes its prefix after an edit;
• non-Markdown files.

Harnesses may implement those features however they choose while preserving the directory contract above.