Agent Memory That Survives /clear: Notes, Indexes and Pruning

Agent context gets reset constantly. The developer runs /clear between tasks, and long sessions get compacted automatically. Across three workspaces we counted close to 300 /clear commands in a single month.

On the web portal, the median developer prompt was 24 characters, and "go" and "Merged. Cleanup" made up about a third of all prompts. That only works if the state of the work lives somewhere other than the conversation.

Three layers of memory

• Instruction files. These are shared and live in git. They hold rules for everyone (Part 2).
• Session notes. These are short-lived and gitignored. Each module gets one running log: what I'm doing, what I found, and what's still open. The agent creates or updates the note before it edits anything.
• Auto memory. This is per developer and lives outside the repository. It holds durable lessons, one fact per file, with an index that loads at the start of every session. By October we had about 140 notes for the consumer app, 80 for the portal, 20 for the business app and 10 for the design workspace.

Lessons move upward over time. A session note becomes a memory note, and when a memory turns out to apply to everyone, it becomes a rule in the shared instruction file through a small commit.

How a note is written

Each note holds one fact, followed by a "Why" line and a "How to apply" line. The file name describes the lesson itself. We started with type prefixes like feedback_ and project_, then switched to names like clock-times-from-the-clock and ticket-triage-refetch-and-stay-on-ticket, because those are what the agent scans when it decides what applies.

An example, paraphrased:

Write clock times from the clock. Why: two pull request descriptions had times written "from feel", and both were wrong. How to apply: read the system time in the same step that writes a time.

The agent caught that mistake itself and wrote the note. Most notes come from a human correction instead.

What goes into memory

• Corrections. "The app doesn't support dark mode." "If a ticket has attachments you can't see, say they're unseen and ask for a paste; don't guess what they are." That one happened twice, and the note gained a "second case" section. "No front-end workarounds for backend gaps: build to what the backend provides, and disable unavailable controls with an explanation."
• Domain vocabulary. One client term meant something different from what we had assumed, and it flipped a conclusion.
• Credential policy. "Ask, don't hunt," plus which disposable test account the agent may use.
• Boundaries of the role. "Ask, don't estimate" for billing figures.
• Gotchas with a dated status. These look like "RESOLVED on date X", followed later by "BROKEN AGAIN on date Y".
• Runbooks. The recipe for the monthly client report, and the diagnosis of a production caching incident.

Memory pays off

A bottom sheet that silently blocked taps caused three separate incidents. The third was diagnosed straight from the note the first two had left behind.

In the design workspace, one correction ("apply changes to both twin modules by default") meant a later ten-column table change landed on twenty frames across both portals without being asked.

Clarifying questions there dropped from six in the first week to one in the third, because the answers were already in memory.

Memory can be wrong

A wrong memory is worse than no memory, because it is confident.

• The wrong test account. The agent once reported live results from the wrong test account, and recorded that account in a note. When the developer asked "which environment do you test?", the agent corrected the note in the same turn.
• A rule that was too strict. Another note said logging in through single sign-on was always the human's job. The developer pointed out that a disposable test account was fine for the agent to use, and the agent rewrote the note. It also switched to a login script that reads the password from a gitignored file, so the password never appears in the conversation.

Corrections to memory have to be treated as seriously as corrections to code.

Pruning

Three weeks in, the portal's memory index hit its size budget. A small hook now warns whenever an index passes a soft size cap after any write.

We restructured the index into four tiers:

• Always apply: rules that hold in every session
• Active: current tickets and work in flight
• Reference: lookups that are needed sometimes
• Archive: closed work, kept for history

Each entry is a single line of about 150 characters pointing to its leaf note, and the whole index stays under about 17 KB. When a ticket closes, its note moves to Archive.

One more lesson: memory is tied to the project's folder path. When we moved every repository under one parent folder in July, memory started again from empty under the new paths. If you're going to reorganise folders, plan for that.

What to copy

• Keep three layers: shared rules in git, short-lived session notes, and durable personal memory.
• Write each note as one fact with "Why" and "How to apply", and name the file after the lesson.
• Promote a lesson to the shared instruction file once it applies to everyone.
• Fix a wrong memory the moment you notice it.
• Budget the index, tier it, and archive notes when work closes.