Anthropic shows how to give an AI agent project memory without bloating its context
An AI agent without memory starts every project from scratch, like a developer with amnesia. Lamis Mukta from Anthropic walked through how Claude Code evolved: from a single CLAUDE.md file with rules to a catalog of markdown notes with an index. The agent reads only the index and opens the notes it needs, so the context, meaning everything the model sees in a given call, does not bloat. Memory should be trusted with caveats: each entry needs a source, a scope, and a status.
AI-processed from Habr AI; edited by Hamidun News
Imagine a strong developer joins the team. On day one, they figure out the project, find the right service, work out why the tests are failing, and close a pile of tickets. On day two, it turns out they have amnesia: they study the same repository again and step on yesterday's rakes.
By default, an AI agent works much the same way. General knowledge is baked into the model's weights, but the structure of your project, the team's agreed rules, and the reasons you rejected one solution three times are not known to it out of the box. Experience does not accumulate on its own between runs.
Lamis Mukta from Anthropic explained how Claude Code handles this: the agent keeps project memory in files and loads only what is needed into the context, meaning the data the model sees during a specific call. Her talk was covered in the tenth part of the "Put me in the harness" series on Habr.
From a single file to a catalog of notes
First, the author advises distinguishing four things. The context window is what the model sees right now. The transcript is the record of the session's messages and actions. The execution state tracks which step is running and what has been confirmed. Memory is a selection of information for future tasks. It does not replace the log or the current state of the system.
In Claude Code, memory evolved in steps, although the author notes that this is not a mandatory ladder. The simplest option is a CLAUDE.md file with the test run command, the location of services, and team agreements. It is easy to review by eye and can be stored in git. But the file loads into the context in full for every session. If you write everything there, you get an instruction set "the size of a nuclear icebreaker," and even fixing a typo will spend the agent's attention on extra text.
The next step is a memory tool. The model has the functions memory_read, memory_write, and memory_edit, and it decides for itself when to call them. The implementation determines where everything is stored: a folder of markdown files, a database, or something else. That means you can limit what the agent reads and writes, and check entries before they are saved. Editing is targeted, so neighboring information is not lost.
After that come skills. Memory stores facts ("tests run with command X"), while a skill stores a procedure ("how to ship a release"). Physically, it is a folder with a SKILL.md file; templates, examples, and scripts can sit next to it. The agent constantly sees only a list of descriptions and loads the full instructions when a task matches. That is why you can keep dozens of skills without large context costs. Where precision matters, a script is more reliable than a text request: it runs the same way every time. But it executes on your machine with your permissions, so third-party skills should be read like third-party code.
How writing and reading work
The scheme from the talk goes like this. During work, the agent decides what is worth saving: a team agreement, a user preference, the cause of a bug it found. It creates or updates a markdown file.
At the start of a session, it reads a short index, one line per note. When a task matches a description, it opens the relevant file. If the index is too small to be useful, it searches the contents with ordinary tools such as grep, which is why clear file and folder names matter.
Folders should be separated: organization rules, project notes, user preferences, and temporary findings. Otherwise the agent will apply one team's agreement to another project just because both notes matched the word "deploy."
A good entry includes an identifier, a scope, a type, a status, a source, and an update date. A note saying "the table breaks" is useless: a week later, no one will know which table or whether the problem is fixed. An entry like "a discrepancy was reproduced when importing a DOCX with an empty cell; check the current code before drawing conclusions" gives direction and honestly marks the limits of the knowledge.
A date alone does not indicate that something is outdated: the test run command can live for years, while the version of a deployed service changes within minutes. So different types of entries need different verification rules. Otherwise the agent will cheerfully report that everything is deployed because someone left such a note six months ago.
Read gradually and still verify
Suppose a thousand notes have accumulated. Sending all of them with every request is technically possible, but you pay for processing extra text, and the model has a harder time finding what matters among neighboring facts. So memory is read in stages: the task's scope, the index, keyword search and, when needed, semantic search, and then only the relevant fragments. Semantic search helps when the user and the note's author describe the same thing in different words. Exact search is better for file names, error codes, and identifiers. Neither guarantees that the entry found is correct.
An example from the talk: a user asks to fix table import. The agent finds a note about where the DOCX handler lives and about an old defect with an empty cell, then opens the current code and tests. If the note describes an old branch, that is no reason to declare the old cause a new error. Memory narrows the search, but it does not cancel verification.
Another idea from the talk is dreaming: a background process that reviews past sessions and tidies up accumulated knowledge.
The practical takeaway for those building agents: start with a short CLAUDE.md, move procedures into skills, and keep project facts in notes with an index, a source, and a status. And always treat an entry as a hint, not as the truth.
- Nov 21, 2026FDE job postings grew 4.6x in a year: what a forward deployed engineer actually does at the client's site
- Nov 21, 2026Anthropic cuts Claude Fable 5.2 price by 20%, and on the coding test it nearly matches Opus 5.5
- Nov 21, 2026Dreamteam Raises $53M for a CRM That Fills Itself from Email and Calls
- Nov 21, 2026Claude Opus 5.5 Builds Out Dimension 9 Horror Game From the Author's 15 Rooms
Key Questions Answered
What are the key details on From a single file to a catalog of notes?
First, the author advises distinguishing four things. The context window is what the model sees right now. The transcript is the record of the session's messages and actions. The execution state tracks which step is running and what has been confirmed. Memory is a selection of information for future tasks. It does not replace the log or the current state of the system. In Claude Code, memory evolved in steps, although the author notes that this is not a mandatory ladder.
How writing and reading work?
The scheme from the talk goes like this. During work, the agent decides what is worth saving: a team agreement, a user preference, the cause of a bug it found. It creates or updates a markdown file. At the start of a session, it reads a short index, one line per note. When a task matches a description, it opens the relevant file. If the index is too small to be useful, it searches the contents with ordinary tools such as grep, which is why clear file and folder names matter.
What are the key details on Read gradually and still verify?
Suppose a thousand notes have accumulated. Sending all of them with every request is technically possible, but you pay for processing extra text, and the model has a harder time finding what matters among neighboring facts. So memory is read in stages: the task's scope, the index, keyword search and, when needed, semantic search, and then only the relevant fragments. Semantic search helps when the user and the note's author describe the same thing in different words.
Build & Ship Production AI Agents Without Boilerplate Code
Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.
The AI world, distilled — once a week
Seven stories that actually mattered, hand-picked. No noise, no reposts, no press releases.
Done! Check your inbox for a confirmation.