Notes that go stale

In the lesson on reading what the agent remembers, two of the planted notes had gone stale. One waited for a branch that no longer existed, and the other described tests that no longer opened the data file. A git branch and a grep showed it in a few seconds. This lesson is about the habit behind those two commands: before an agent acts on a note, someone checks the note against the thing it describes.

You don’t run anything here. The examples are memory notes and the facts around them, and the exercise is a judgment you write down.

Where a note gets its facts

A memory note is a summary. Someone saw something true, wrote a line about it, and the line was saved. The thing they saw is still there, and it can change after the line is written. The difference between the two is the difference between primary and secondary sources.

For a claim about what a project does now, the primary source is the project itself: the code, the tests, the configuration and the git history. Running the tests or reading the file tells you what is true today. A secondary source records what someone believed at one moment. Auto-memory notes are secondary, and so are handoff files, plans and old chat messages. Each of them was right when it was written, or at least the writer thought so.

Not every primary source is in the repository. You are the primary source for a note about your preference for short commit messages. For a note about where the team tracks bugs, the source is the tracker. And a decision (“we drop the old export in March”) comes from the meeting or the issue where it was made, which the code may not show yet. So the first question about any note is which source it summarizes. The second is whether that source still says the same.

Claude Code’s documentation says the agent doesn’t save what it can read from the code, such as file paths or the structure of the project. A project note is for things outside the code: work still under way, a deadline, or a decision that neither the files nor the git history record [1]. Those are the claims that change fastest.

Checkpoint · match

Where would you check it?

Match each memory note to the primary source that shows whether it is still true.

The payment rewrite is on the pay-v3 branchChoose…The branches and commit historyThe test filesThe person who said itThe issue tracker the team uses

The tests replace the mail server with a fake, so no mail is sentChoose…The branches and commit historyThe test filesThe person who said itThe issue tracker the team uses

Answer in English, even when I write in DutchChoose…The branches and commit historyThe test filesThe person who said itThe issue tracker the team uses

Open bugs for the shop carry the label shop-bugChoose…The branches and commit historyThe test filesThe person who said itThe issue tracker the team uses

CheckHintSkip

Why notes go stale

Code changes in commits, and a commit says what changed. A note doesn’t change when the code does. The two aren’t linked, so when a branch is merged, a note that says the work is still on that branch stays as it was.

At the start of a session Claude Code puts the instruction files and the start of the memory index into the context. The documentation calls both context for the agent, as opposed to settings that Claude Code enforces [1]. A stale line is in the context with the same weight as a true one. The memory files aren’t removed when Claude Code cleans up old session logs. They stay until you or the agent edits or deletes them. The documentation describes one reminder to drop stale entries. Claude Code sends it to the agent, and you don’t see it as a prompt. It comes right after the agent writes MEMORY.md, when the file is close to its read limit [1]. That reminder is about the length of the file, and it compares no note with the code.

One feature helps. From version 2.1.214, when the agent writes a memory file that starts with a header, Claude Code records the time of the write in a modified field of that header. The documentation says the date lets both you and the agent judge how recent the fact is [1]. The date tells you how long ago the claim was last written down. It doesn’t tell you whether the claim is still true. A note from last year about your commit message style can be right, and a note from yesterday about a branch can be wrong by tonight.

Check the note before acting on it

Here is the rule this course uses. Claude Code’s documentation says notes can go stale but doesn’t give a rule for it, so the wording is ours. Treat a note as a lead, and check it against its primary source before acting on it. When the two disagree about what the project does now, you follow the project, and you correct or delete the note.

When you review a note, it gets one of these outcomes:

• Trust it in two cases. A preference is trusted when the person it belongs to confirms that it still holds. A pointer is trusted because following it opens the source anyway, and you read the source there.
• Check it when the note makes a claim about the project that the agent acts on: a branch, a test, a setting, a time a command takes. The check is often one command or one file. Do it before the agent acts, and again at each review.
• Delete it when the primary source already contradicts it, or when the note only repeats what the code states plainly. The code is the record in the second case, and a copy of it can only go out of date.

A note that lets the agent skip a step deserves the check most. “Skip the lint step, CI runs it” stays in memory after the team removes the lint job from CI. From then on the agent skips lint in every session, and nothing lints the code.

Checkpoint · scenario

The agent is about to tag a release

A memory note says “release tags are made from the release branch”. You ask the agent to tag version 2.4. What do you do before it tags?

Let the agent tag from the release branch right away, as the note says.Ask the agent whether the note is still right before it starts tagging.Have the agent read the release script and the recent commits on each branch first.Delete every memory note older than a month first, then ask it again.

DecideHintSkip

Pitfall: Asking the agent whether its note is true

A developer reviewed the memory of a coding agent by asking it, for each note, whether the note was still correct. The agent said yes to every one. Each note was in its context, and the agent had read nothing that contradicted them, so it repeated them back. A secondary source can’t confirm itself. Ask the agent to run the command or open the file that the note describes, and read what that shows.

Exercise

Below are five memory notes of a small invoice tool, with one fact from the project next to two of them. For each note, write down which source it summarizes and whether you trust it, check it against that source, or delete it, with a one-line reason. It takes about ten minutes, and you need only a pen or a text file.

1. user      Keep commit messages to one line.
2. project   The CSV export is behind the setting export_v2 until the beta ends.
             (git log shows a commit last week: "Remove export_v2, CSV export is on for everyone")
3. project   The date helpers are in billing/dates.py.
             (billing/dates.py exists and holds the date helpers)
4. feedback  Skip the type check before a commit. CI runs it.
5. reference Customer complaints are in the support queue, under the tag invoice.

A good result: note 1 summarizes you, and you trust it once you confirm that you still want it. Note 2 summarizes the code and its history, and the commit contradicts it, so you delete it. Note 3 summarizes the code and repeats what the code shows, so you delete it, because the file is the record. Note 4 summarizes the CI configuration, and you check it, by reading that configuration, before the agent skips the type check. Note 5 summarizes the support queue and is a pointer to it, so you trust it, because whoever follows it reads the queue itself. Which note would you have trusted without a check before this lesson, and what would the agent have done because of it?

Stretch: Open the memory folder of one of your own projects, under `~/.claude/projects/`, and do the same for every note in it. Read and judge only, and change the notes afterwards if you decide to.

Recap

1. A note in memory is a secondary source. It records what was true, or believed, when it was written. The code, the tests, the configuration and the git history are the primary source for what the project does now.
2. Before acting on a note, name the source it summarizes and check the note against it. When they disagree about the project, the project counts, and the note is corrected or deleted.
3. In Claude Code a memory note stays until someone edits or deletes it, and every session reads the index as context. A modified date shows how old a note is, which isn’t the same as whether it is still true [1].
4. Asking the agent whether its own note is true checks nothing. Have it run the command or open the file the note describes.

You can now

• Manages what the agent carries between sessions

Mark lesson finishedI know this, skip it

References

1. Anthropic. How Claude remembers your project. Claude Code documentation. Reference. Claude Code memory