# Notes that go stale

> Tell a primary source from a secondary one, name the source each memory note summarizes, and decide whether to trust, check or delete each note.

Page: https://schubergphilis.github.io/ai-training/customizing-agents/notes-that-go-stale/
License: CC BY-SA 4.0, https://creativecommons.org/licenses/by-sa/4.0/

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 (How Claude remembers your project, Claude Code documentation). Those are the claims that change fastest.

#### Checkpoint: Where would you check it?

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

Statements:

- The payment rewrite is on the pay-v3 branch
- The tests replace the mail server with a fake, so no mail is sent
- Answer in English, even when I write in Dutch
- Open bugs for the shop carry the label shop-bug

Options:

- The branches and commit history
- The test files
- The person who said it
- The issue tracker the team uses

## 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 (How Claude remembers your project, Claude Code documentation). 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 (How Claude remembers your project, Claude Code documentation). 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
(How Claude remembers your project, Claude Code documentation).
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: 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.

#### 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.

```text
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
   (How Claude remembers your project, Claude Code documentation).
4. Asking the agent whether its own note is true checks nothing. Have
   it run the command or open the file the note describes.

## References

- How Claude remembers your project, Claude Code documentation, https://code.claude.com/docs/en/memory