How memories are made
Nothing is written because a session happened. A fragment exists because an extraction pass found a conclusion worth keeping, and a gate agreed.
The four extraction points
| When | What it looks at |
|---|---|
| End of turn | The turn that just settled. Runs after the answer, never in front of it. |
| Mid-session | Long-running sessions that would otherwise never reach a boundary. |
| After compaction | When a session is summarised for context overflow, a second pass mines the summary for discrete knowledge. |
| Explicitly | You tell the agent to remember something, and it is persisted immediately. |
The compaction hook matters more than it looks. Compaction is exactly the moment a session's early reasoning is about to be condensed into prose and lose its edges — mining it on the way past is how the decisions from hour one survive hour four.
Two more paths populate memory outside the per-turn flow: seeding, which gathers workspace metadata so a brand-new workspace isn't starting from nothing, and enrichment, which augments existing fragments.
Asking for one
You don't need a syntax. Tell the agent to remember something and it writes a fragment:
Remember that we never add a dependency without checking bundle size first.The same works in reverse — asking what was decided about something triggers a recall rather than a guess.
The gate
Every write, from every path, goes through the same accept-stamp-store pipeline. It exists to stop memory turning into a log:
- Relevance — a fragment has to be a conclusion, not a restatement of the request.
- Grounding — assertions are checked against what the session actually did.
- Dedupe — a fragment that repeats one already stored isn't stored twice.
Each accepted fragment is stamped with the git commit at the time of writing and the file paths it referenced, which is what makes the next section possible.
Staleness
Knowledge about code goes wrong when the code changes. Rather than a time-based expiry — which would drop good knowledge about a file nobody touched — the decay is tied to real drift.
On retrieval, and during a scheduled sweep, the files a fragment referenced are compared against the commit it was written at. Substantial drift decays the fragment's confidence proportionally, which lowers its rank. Retrieval requires a minimum confidence, so a sufficiently stale fragment simply stops surfacing.
Two properties are deliberate:
- Decay is floored. It can demote a fragment but never delete it. Drift is evidence that knowledge might be out of date, not proof that it is.
- Only supersession replaces. When a decision is revised, the new fragment references the old one's id and the old one's confidence goes to zero. That's the one path by which memory forgets something on purpose.
This is the classic RAG failure mode — confidently surfacing context that stopped being true — handled with the one signal a coding tool actually has: the diff.
Next
- Retrieval and the vector store — what happens on the way back out.