Agent operational memory

Agent operational memory means writing down the rules and lessons for an AI agent in ordinary text files that it reads at the start of every session. Without such files the agent starts each conversation from scratch, like a temp who needs the same instructions every morning. With a file of house rules, such as "always ask before deleting anything", it keeps working the way you agreed.

Why is it needed?

A language model does not remember earlier conversations. As the Claude Code documentation puts it, each session begins with a fresh context window, the text the model can see at once. What the agent learned in an earlier session is gone unless someone wrote it down. In May 2026 a user on Reddit's r/AI_Agents described the result: after hours of teaching an agent which tools it may touch and when to ask first, a new coding tool or MCP server meant explaining it all again.

The name is descriptive. The tools themselves speak of instruction files, such as AGENTS.md and CLAUDE.md, and of memory.

How does it work?

The files are plain text, usually Markdown, and they change how the agent behaves without retraining the model, as fine-tuning would. Claude Code, for example, loads two kinds at the start of every session:

• Instructions you write yourself: build commands, conventions, "always do X" rules. Claude Code reads CLAUDE.md. AGENTS.md is an open format for the same purpose, read by OpenAI's Codex, Google's Jules, Cursor and other coding agents.
• Notes the agent writes itself. With auto memory, Claude Code saves corrections and preferences and, in September 2026, loads the first 200 lines or 25 KB of its MEMORY.md index into each new session.

Instruction files come in layers. Claude Code has one for the whole organisation, a personal one for all your projects and a project file that the team shares through version control, so every change to the rules is visible. They do not override each other: Claude Code loads them all, with the file closest to the working directory last. With AGENTS.md, the nearest file wins.

Anthropic calls the agent-written variant structured note-taking (Effective context engineering for AI agents, September 2025): notes kept outside the context window, such as a NOTES.md file, that the agent reads back later.

Why not keep everything in the conversation?

Anthropic describes context rot: the more tokens a context window holds, the worse a model recalls information from it. The Claude Code documentation advises keeping each CLAUDE.md under 200 lines, because longer files take up more context and are followed less consistently.

Where does it go wrong?

• The file is context, and nothing enforces it. Claude Code's documentation says there is no guarantee of strict compliance. For something that must never happen, it points to hooks: scripts that run at fixed moments whatever the model decides.
• If two files give different rules for the same thing, Claude may pick one arbitrarily.
• Each tool has its own file names. AGENTS.md aims to be one file for many agents, yet in September 2026 Claude Code by default reads it only when a project has no CLAUDE.md.
• Notes the agent writes can go stale. Claude Code keeps them as plain Markdown that you can read, edit or delete.

Example

Suppose a developer uses a coding agent in several projects. A personal file says "use conventional commits", and the project file says "this codebase validates input with Zod". When the agent makes the same mistake twice, the developer adds one line to the project file, and the next session starts with that rule. The Reddit user from the discussion above went further in a follow-up post: a structured file that marks commands such as rm -rf and git push --force as high-consequence, so the agent treats them with extra care.