Appearance

Language

Mastering AI agents

How to Use Claude Code Memory: MEMORY.md, Auto Memory and Codex Memories (2026)

What belongs in an AI coding agent's memory versus CLAUDE.md, AGENTS.md and spec files, how Claude Code auto memory and Codex Memories work, and how I write and maintain more than forty memories.

Kelvin Wang · · 10 min read

Key points

  1. Memory holds the feedback I've given; rule files hold what every tool must follow; specs hold a project's full list of requirements.
  2. Claude Code keeps one file per memory with MEMORY.md as the index, loading its first 200 lines or 25KB every session.
  3. Codex Memories are off by default and generated in the background; the docs say not to rely on them as the only source of rules.
  4. A memory states the rule, why, and how to apply it; merge duplicates, delete wrong ones, link related ones.

I treat memory as the place for feedback: what I said while reviewing a draft, the corrections I made, and the reasons behind them. Rules every tool must follow go in AGENTS.md or CLAUDE.md, a project’s full list of requirements goes in a spec file, and anything that must never break becomes a test. Claude Code saves memories as files in ~/.claude/projects/<project>/memory/ on its own1; Codex has a Memories feature too, but it is off by default and generated in the background, so it isn’t meant to be maintained by hand2.

This is the memory part of the seven parts of an AI harness. The overview says what it is; this post covers how to write and maintain it.

What goes in memory, CLAUDE.md, AGENTS.md and spec files?

All four are text written for an AI to read. They differ in who writes them, who can read them, and how far they reach:

FileWritten byRead byHolds
MemoryThe AI, and I can edit itOnly the same tool on this machineFeedback I've given, approaches I've confirmed, project state the code doesn't show
CLAUDE.md / AGENTS.mdMeEvery tool that reads the file; travels with the repoTest commands, decisions already made, rules every tool must follow
Spec fileMe and the AI, in the repoAnyone and any tool that opens the repoA project's full requirements, numbered, with status
TestsMe and the AIThe buildRules that must hold and can't depend on the model remembering

To decide where something goes, I ask two questions:

  1. Does Codex need to know it too? Then it goes in AGENTS.md. Claude Code’s memory lives only on this machine and only Claude Code reads it1; Codex memories are its own local data as well2. The two don’t share.
  2. Is it a rule or a list? A rule (“work out the arithmetic”) goes in memory or a rule file. A list (a dozen requirements for the exchange section, which ones are done, which commit did each) goes in a spec file. The memory just says “the list is in this spec.”

How to write rule files is in the CLAUDE.md and AGENTS.md post; how to write specs is in Write the Spec, Then the Plan.

How does Claude Code auto memory work?

Auto memory is on by default in local sessions1. As it works, Claude decides what will be useful later and saves four kinds of memory, recorded as type in the file’s frontmatter:

  • user: your role, expertise and working preferences.
  • feedback: corrections you give and approaches you confirm.
  • project: ongoing work, deadlines, and decisions the code and git history don’t show.
  • reference: where outside information lives, such as an issue tracker or dashboard.

It skips anything it can derive from the code (architecture, file paths, debugging fixes) and anything your CLAUDE.md already says1. You can also say “remember that the API tests need a local Redis” and it goes into memory; to put something in CLAUDE.md instead, say “add this to CLAUDE.md”1.

The layout is one index plus topic files:

~/.claude/projects/<project>/memory/
├── MEMORY.md                 # Index, one line per memory, loaded every session
├── fix-the-whole-class.md    # One memory
├── no-self-evident-copy.md   # One memory
└── ...

A few details from the official docs that shape how you write them1:

  • Only the first 200 lines or 25KB of MEMORY.md load, whichever comes first. Anything past that is invisible at startup, so keep one line per memory and put detail in topic files.
  • Topic files don’t load at startup. Claude reads them with its file tools when needed, so each index line should say enough to know when to open the file.
  • All worktrees of one git repo share a memory folder, but it doesn’t cross machines or cloud environments.
  • Subagents don’t get the main conversation’s memory, except forks. Rules a subagent must follow belong in the brief you hand it.
  • Writes get a modified timestamp automatically, so you and Claude can see how current a memory is.
  • Old transcripts get cleaned up; memory files don’t, until you or Claude edit or delete them.

The toggle is /memory in a session, saved as autoMemoryEnabled in ~/.claude/settings.json. To turn it off for one project, set "autoMemoryEnabled": false in that project’s settings; CLAUDE_CODE_DISABLE_AUTO_MEMORY=1 turns it off everywhere1.

My website project has 45 memories right now; the index is 44 lines, about 6.5KB, far from the limit. By type:

My website project's memories by type count; 2026-11-17
  • feedback (what I told it) 24
  • project (project state) 17
  • reference (where things live) 3
  • user (who I am) 1

Counted from this website project's memory folder under ~/.claude/projects/, by the type field in each file's frontmatter.

More than half are feedback. That’s where memory earns its keep for me: something I said once in a review is still findable at the next edit.

Does Codex have memory?

Yes, called Memories. As of 2026-11-17 the official docs say2:

  • Off by default. In the desktop app, turn on “Enable Codex memories” under Settings → Personalization; it applies to that machine. In the CLI, add memories = true under [features] in config.toml.
  • Generated in the background. Once a chat has been idle long enough, Codex summarizes eligible chats in the background, skips short or active ones, and redacts secrets. A pass is skipped when remaining rate limit is below a threshold.
  • Stored locally. Under ~/.codex (memories_v2/ on a fresh setup), separate from ChatGPT web memory.
  • Per-chat controls. /memories in a chat decides whether this chat uses existing memories and whether it generates new ones; settings can also exclude chats that used MCP or web search.
  • Not meant for hand-editing. The docs call the files generated state and say not to rely on manual edits as your main control; “Delete Codex memories” resets everything.

The key line: treat memories as a recall layer, not the only source for rules that must always apply, and keep required guidance in AGENTS.md or checked-in docs2. Claude Code’s docs say the same: memory on both sides is context, not enforced configuration1.

So the main difference between the two is who maintains it. Claude Code memories are Markdown files you can open and edit; Codex memories are curated by a background process. Either way, rules I want both tools to follow live in ~/ai-config/AGENTS.md, and each tool’s memory holds only the feedback that tool needs.

What does a memory look like?

Here is the shape of one of my memories, with internal fields like the session ID removed:

---
name: fix-the-whole-class
description: When one instance is flagged, find every instance of the same class and fix them in one batch
metadata:
  type: feedback
  modified: 2026-10-25T13:22:39.708Z
---

When the user flags one instance (a formula not worked out, an FAQ with no answer,
a stray disclaimer), treat it as a class: scan every exchange copy file and the
rendered pages for the same pattern and fix all of them in one batch.

**Why:** 2026-10-25, reviewing the exchange reviews, the user flagged "12 × 20%",
an empty FAQ and similar items one by one. A scan then found 32 formulas,
42 non-answers and 38 disclaimers still live.

**How to apply:** The requirements list lives in
spec/2026-10-25-exchange-requirements-and-polish-plan.md; check new feedback
against it and append. Related: [[apply-review-directly]], [[exchange-section-state]]

Each part has a job:

  • description: the index line comes from here. Topic files don’t load at startup, so write this line as the rule itself, not a heading. “Flag one, fix the class” is actionable; “review feedback” isn’t.
  • Rule body: one or two sentences on what to do.
  • Why: the date and what happened, ideally with my own words. When a rule meets an edge case, the reason is how the AI decides whether it applies.
  • How to apply: where to look and what it relates to. This one points to the spec for the list instead of copying it.

Of my 45 memories, 41 have a Why, 43 have a How to apply, and 42 link to at least one other.

How did two review rules become memories?

The overview mentions two of my review rules. Here is what each looks like in memory and in the spec.

Fix the whole class. Item A2.11 in the exchange spec says “12 × 20%” should read “2.4 USDT” and “0.06% × (1 − 20%)” should read “0.048%”. The spec records the requirement; the memory records the method: when this kind of feedback appears, scan all 28 copy files and the live pages. That scan found 32 formulas not worked out, 42 sentences whose only answer was “not stated officially,” and 38 disclaimers, which were then fixed in batches.

Delete what the layout already says. The Binance incident page had the heading “Timeline (newest first).” The list itself shows the order, so the parenthesis was redundant. What I said that day: “Don’t put obvious copy like this on the page.” The memory turns it into a class: sentences about the page itself, like “this page is updated regularly,” “link below,” or “numbers update automatically,” get scanned out before shipping; its How to apply points back to “fix the whole class.”

The second memory links back to the first because it is carried out with the first one’s method.

How do you maintain memory?

Auto memory grows on its own. Left alone, the same thing ends up in two memories and old rules contradict new ones. The docs warn that when two instructions conflict, Claude may pick one arbitrarily1. How I keep it clean:

  • Search before writing. When new feedback comes in, check the index for a memory of the same class and add to it instead of starting another. One topic, one file.
  • When a rule changes, edit the original and date it. My content-pipeline memory said on November 3 “write, review, then publish directly”; on November 5 I changed it so publishing waits for my OK. The memory wasn’t rewritten. It got a “2026-11-05 update” paragraph at the end stating the new rule and linking to the newer memory. Whoever reads it later, person or AI, can see how the rule changed and which one stands.
  • State the scope to avoid false conflicts. “Push site changes straight to main” and “ask before pushing an article” look contradictory, but they cover different things: code and layout versus articles. The newer memory spells out its scope in its Why: a push deploys the site, so pushing an article is publishing it.
  • Delete wrong ones. Memory files are plain Markdown you can edit or delete any time; /memory opens the auto memory folder1. Stale project state (a feature “not live yet”) only misleads once it ships, so update it.
  • Link related ones. My memory files point to each other with [[file-name]]. Reading one leads to the rest of its class without loading everything.
  • Move what every tool needs into AGENTS.md. If Codex should follow a piece of feedback too, memory isn’t its final home.
  • Turn must-hold rules into tests. Every article on this site must belong to a topic; tests/blog-topics.test.ts enforces that now, not memory.

Whether I keep a memory depends on whether there’s a need: only things I’ll keep doing over the long run become a Markdown file. I’m not building a full memory store yet, and I don’t use tools like LangChain memory to manage it.

Go deeper How to Write AGENTS.md and CLAUDE.md: One Rules File for Every AI Coding Tool (2026) Where rule files go, what to put in and leave out, and how one file serves both tools.

With memory, do you still need to review the work yourself?

Yes. Both vendors’ docs say memory is context, not enforced configuration12. It makes getting things right more likely at the start; it doesn’t guarantee it.

I read every post myself. Memory keeps these rules findable at the next edit, and I check the draft at the end to see whether it followed them. When it didn’t, I look at whether the memory was unclear, in the wrong place, or should become a test.

FAQ

Does Claude Code memory travel with the git repo?

No. Memory lives under ~/.claude/projects/ on this machine; it doesn’t cross machines or go into cloud environments1. Rules for another computer or a teammate belong in the repo’s CLAUDE.md or AGENTS.md.

Do subagents read my memory?

No, except forked subagents1. When I hand research or writing to a subagent, the rules it must follow go into a written brief alongside the files. Parallel work is covered in the subagent and worktree post.

How do I clear Claude Code or Codex memory?

Claude Code: open the auto memory folder from /memory, delete the files you don’t want, and remove their lines from MEMORY.md1. Codex: choose “Delete Codex memories” in the desktop app to reset, or use /memories in a chat to turn off use and generation for that chat2.

Sources

  1. 1. How Claude remembers your project · Claude Code Docs · checked 2026-11-17
  2. 2. Memories · OpenAI Codex Docs · checked 2026-11-17

About the author

Kelvin Wang

Electrical engineer building tools with AI agents, sharing hands-on notes on engineering and investing.

More about me