# How do the top AI agent harnesses handle memory?

All seven harnesses read a hand-written instruction file such as AGENTS.md or CLAUDE.md. Only Claude Code, Codex and Hermes Agent document notes the agent writes for itself, and they differ in size and in how those notes load: Claude Code loads the first 200 lines of an index, Hermes Agent a 2,200-character file, Codex builds them in the background after a chat goes idle. Read 2026-11-06.

Short answer, from the docs read: every harness here has the same first layer of memory, a text file a person writes that is put in front of the model at the start of a session, and they split on the second layer, notes the agent writes for itself. Claude Code, Codex and Hermes Agent document that second layer.[1][2][3] Cursor's docs say plainly that models keep no memory between completions and treat rules as the substitute.[4] The docs read for OpenCode and pi describe instruction files and, for pi, summarizing a long session, but no agent-written notes.[5][6][7] For Antigravity, only the launch post mentions a knowledge base.[8] This is the second page in a series that began with a [survey of the harnesses](/research/top-ai-agent-harnesses-survey).

A [harness](/research/top-ai-agent-harnesses-survey) is the program around a model. [Agent memory](/reference/glossary/agent-memory) here means anything that carries information from one session to the next, or from early in a long session to late.

## Layer one is the instruction file

A person writes it, it is read at the start, and the agent treats it as context.

- **Codex** reads AGENTS.md. It takes one file from the global Codex home, then walks from the project root down to the current directory and joins the files from the root down, so files nearer the working directory come later and override earlier guidance. It stops adding files at 32 KiB by default.[9]
- **OpenCode** reads AGENTS.md in the project and a global one at ~/.config/opencode/AGENTS.md. It falls back to CLAUDE.md files when no AGENTS.md exists, and the first matching file wins in each category.[5]
- **pi** loads project context files (AGENTS.md) in order from global to project-specific, according to its author's post.[7]
- **Cursor** has Project Rules in .cursor/rules as files with metadata, plus User Rules, Team Rules and an AGENTS.md option. Rules apply in the order Team, then Project, then User, and earlier sources win a conflict.[4]
- **Claude Code** reads CLAUDE.md files. Its docs say these are context and not enforced configuration, and that a hook is the way to block an action whatever the model decides.[1]

The docs differ on how strongly this layer binds. Claude Code says outright that it is not enforced.[1] Codex says required team guidance belongs in AGENTS.md or checked-in documentation, not in memories.[2]

## Layer two is notes the agent writes for itself

- **Claude Code** calls it auto memory. Claude saves notes as files typed user, feedback, project or reference, and skips what it can derive from the code. The first 200 lines or 25 KB of the index file MEMORY.md load at every session start; detailed notes sit in topic files that are read when needed.[1] These docs were saved on 2026-10-22.
- **Codex** has Memories. Local Codex turns useful context from eligible earlier chats into files under its home directory, redacts secrets from the generated fields, and waits until a chat has been idle before writing. It can skip a pass when the rate-limit allowance is low. The docs call memories "a helpful recall layer" and not the only source for rules that must always apply.[2]
- **Hermes Agent** keeps two bounded files: MEMORY.md at 2,200 characters for the agent's own notes and USER.md at 1,375 characters for the user's profile. Both are put into the system prompt as a frozen snapshot when a session starts. When a write would go over the limit, the memory tool returns an error and the agent has to make room itself. Past conversations are stored in SQLite with full-text search, and a session_search tool reads them.[3]
- **Antigravity.** The launch post says Antigravity treats learning as a core primitive, with agent actions both retrieving from and adding to a knowledge base.[8] The docs overview and skills pages read here did not mention memory or a knowledge base.[10][11]
- **Cursor, OpenCode and pi.** No agent-written memory feature turned up in the docs pages read.

## Inside a long session

Memory also means what survives when one session grows past the model's context window. Pi documents two summarizing mechanisms. Compaction starts when the context passes the window minus a reserve of 16,384 tokens by default, and can be started by hand with /compact. Branch summarization, when the user moves to another branch of the session tree, summarizes the work being left and carries it into the new branch.[6] The other harnesses' docs on this were not read for this page.

## What the comparison rules out

These are consequences of the docs read, not findings from a test.

- "The agent has memory" does not name one thing. Claude Code loads up to 200 lines or 25 KB of an index; Hermes Agent caps its agent-notes file at 2,200 characters; Codex builds its files in the background after a chat goes idle.
- Three of seven document notes the agent writes. A reader choosing a harness for memory should check which layer a claim is about.
- Codex, OpenCode, pi and Cursor all read an AGENTS.md, and OpenCode also reads CLAUDE.md when no AGENTS.md exists. A plain markdown instruction file may therefore move between them without rewriting. This is an inference from the docs, not a tested migration.

## Terms

- **Instruction file:** a text file of standing guidance, such as AGENTS.md or CLAUDE.md.
- **Auto memory:** Claude Code's name for notes Claude writes for itself.
- **Compaction:** replacing older messages in a session with a summary.
- **Context window:** the amount of text a model can read at once.

## Not yet proven

- **Whether any of it works.** The docs describe design, not results. No source read measures whether memory improves task success.
- **Cursor's memory features.** Search results about Cursor memories came only from third-party blogs, which were not used. Cursor's own rules page was read.
- **Antigravity's knowledge base.** Only the launch post mentions it, and its current behavior was not found in the docs pages read.
- **OpenCode and pi.** A negative: no agent-written memory appeared in the pages read, which does not show none exists. Plugins and packages can add one.
- **Currency.** The Claude Code and Hermes Agent docs were saved on 2026-10-22 and 2026-10-23, two weeks before the others.

If you have chosen a harness for how it remembers and the docs misled you, I would like to hear it: mackenzie@mackenziebowes.com.

## Sources

1. Claude Code Docs, Memory. Saved 2026-10-22. <https://code.claude.com/docs/en/memory>
2. OpenAI, Codex docs, Memories (now at learn.chatgpt.com/docs/customization/memories). Read in Rotunda 2026-11-06. <https://developers.openai.com/codex/memories>
3. Hermes Agent docs, Persistent Memory, from a clone at commit 5894e750. Saved 2026-10-23. <https://github.com/NousResearch/hermes-agent/blob/main/website/docs/user-guide/features/memory.md>
4. Cursor Docs, Rules. Read in Rotunda 2026-11-06. <https://cursor.com/docs/rules>
5. OpenCode docs, Rules. Read in Rotunda 2026-11-06. <https://opencode.ai/docs/rules/>
6. Pi docs, Compaction Reference. Read in Rotunda 2026-11-06. <https://pi.dev/docs/latest/compaction>
7. Mario Zechner, "What I learned building an opinionated and minimal coding agent", 2025-11-30. Read in Rotunda 2026-11-06. <https://mariozechner.at/posts/2025-11-30-pi-coding-agent/>
8. Google Antigravity, "Introducing Google Antigravity". Read in Rotunda 2026-11-06. <https://antigravity.google/blog/introducing-google-antigravity/>
9. OpenAI, Codex docs, Custom instructions with AGENTS.md (now at learn.chatgpt.com/docs/agent-configuration/agents-md). Read in Rotunda 2026-11-06. <https://developers.openai.com/codex/guides/agents-md>
10. Google Antigravity Docs, overview. Read in Rotunda 2026-11-06. <https://antigravity.google/docs/overview/>
11. Google Antigravity Docs, skills. Read in Rotunda 2026-11-06. <https://antigravity.google/docs/skills/>

---

Published 2026-11-06. Web page: https://www.mackenziebowes.com/research/how-top-ai-agent-harnesses-handle-memory
