Fight ClubBlog

Anatomy of a memory for LLMs

A correction keeps the old version

The project behind this series: ns-brain.fightclub.pro

When a shop charges your card twice by mistake, the bank does not erase the wrong line from your statement. The bank adds a new line below the wrong one (a refund) and all three stay there, so anyone who reads the statement later can see what happened, what was wrong and when it was put right. Accountants have kept their books this way for a very long time: a mistake is never erased from the ledger, because a new entry reverses it (a correcting entry) and the wrong entry stays exactly where it was. The balance at the bottom shows only what is true now and the lines above the balance show how the account got there, which is what an auditor or a confused customer asks about a year later. A shared document with its version history works the same way and so does a contract with a dated amendment (instead of a page that was quietly replaced).

When a fact changes, AI memory tools often handle the correction in one of two wrong ways. The first wrong way is to only add: an agent stored "We deploy from main" in March, then in October main broke twice, the team moved deploys to the release branch and the agent stored that too. Now both facts sit in memory with equal weight and a question about deploys gets two answers. The model has to guess which fact still counts and may choose the old one with full confidence. Two facts that disagree are worse than one wrong fact, because a wrong fact can at least be noticed and fixed, while a pair that disagrees looks like knowledge. The second wrong way is to overwrite the old fact: that gives one answer, but the reason for the change is gone (nobody can see what the memory said before or why it changed), so the next session can make the same mistake again.

ns-brain refuses to store a second fact on the same subject. If the new title and a title already in that scope share half or more of their words, the save stops and shows both. This is a real transcript from a test brain for an invented payments company, one command at a time. The main-branch fact goes in first and the release-branch fact is stopped as a second answer to the same question:

$ ns-brain remember --type decision --scope deploy --title "Production deploys are made from the main branch" --body "Every merge to main goes live the same day."
remembered #1 [deploy/decision] Production deploys are made from the main branch

$ ns-brain remember --type decision --scope deploy --title "Production deploys are made from the release branch" --body "Main broke production twice in October. Only the release branch goes live now."
#1 in deploy is already about this (78% title overlap):
  stored:  Production deploys are made from the main branch
  yours:   Production deploys are made from the release branch
Storing both would put two answers to one question in the brain. Pick one:
  the fact CHANGED       --supersedes 1
  same fact, better words  ns-brain update 1 --body ...
  genuinely separate     --allow-duplicate

The agent then has to say how the two facts relate: the fact changed (supersede it), it is the same fact in better words (update it, which moves the old wording to history) or they really are two separate facts (store it anyway, on purpose). That check happens at the moment of saving because it is the only moment when the agent still has the text and knows why it wrote it: a cleanup report a week later reaches a different session that knows neither.

Here the fact changed, so the agent writes a correction. In ns-brain a correction is its own kind of write (remember --supersedes <id>) that works like the correcting entry: the new fact takes the old one's place, even under the same title, and the old fact stays in the brain as history with a link to the fact that replaced it.

$ ns-brain remember --type decision --scope deploy --title "Production deploys are made from the release branch" --body "Main broke production twice in October. Only the release branch goes live now." --supersedes 1
remembered #2 [deploy/decision] Production deploys are made from the release branch (supersedes #1)

A search for the old fact returns the new fact and the whole story with it: a question about "deploys from main" gets back the new rule (deploy from the release branch), why it changed (main broke production twice in October, the reason stored with the correction) and a note naming the old rule it replaced. The model never sees two answers to compare and it learns why the old way was dropped, so a session that thinks of deploying from main again is told at once what went wrong the last time.

$ ns-brain recall "deploys from main" --scope deploy
#2  [deploy/decision] (score 0.672) Production deploys are made from the release branch
      Main broke production twice in October. Only the release branch goes live now.
      matched the RETRACTED #1 (2026-11-16): Production deploys are made from the main branch  ·  ns-brain get 1 for its text

Opening the old fact by its number also shows the new fact underneath, so nobody can quote the old version by accident. The history is still there when someone asks why the branch changed (the same way the double charge is still on the statement above the refund).

$ ns-brain get 1
#1 [deploy/decision] tier B reported pinned=False importance=3 used=0x
created 2026-11-16 11:05  updated 2026-11-16 11:05  verified never
source session
Production deploys are made from the main branch

Every merge to main goes live the same day.

--- SUPERSEDED. The current version is #2: ---
Production deploys are made from the release branch

Main broke production twice in October. Only the release branch goes live now.

The replacement cannot be deleted while it replaces something, because deleting the replacement would bring back a fact that was withdrawn on purpose:

$ ns-brain forget 2
#2 is the current version of 1 superseded memory. Deleting it would put these back into recall as live facts:
  #1 Production deploys are made from the main branch
Supersede it with a correct version instead, or pass --force to accept the resurrection.

A second correction of a fact that was already corrected is refused too, until the agent says how the two corrections relate. Here an agent tries to replace the main-branch fact again, this time with "deploys are made from a tagged release":

$ ns-brain remember --type decision --scope deploy --title "Production deploys are made from a tagged release" --body "Only a signed tag goes live." --supersedes 1
#1 has already been superseded by #2 (this session, earlier).
  retracted:  Production deploys are made from the main branch
  by #2:      Production deploys are made from the release branch
  yours:      Production deploys are made from a tagged release
Two corrections to one fact is a fork, and the store can only record one:
  yours is the later correction   --supersedes 2   (chain them)
  both are true, different facts  drop --supersedes
  you mean it, take the branch    --fork-ok

Usually the newer correction replaces the other one (--supersedes 2) and recall follows the chain to the latest fact, which the oldest words still find:

$ ns-brain remember --type decision --scope deploy --title "Production deploys are made from a tagged release" --body "Only a signed tag goes live." --supersedes 2
remembered #3 [deploy/decision] Production deploys are made from a tagged release (supersedes #2)

$ ns-brain recall "deploys from main" --scope deploy
#3  [deploy/decision] (score 0.672) Production deploys are made from a tagged release
      Only a signed tag goes live.
      matched the RETRACTED #1 (2026-11-16): Production deploys are made from the main branch  ·  ns-brain get 1 for its text
      matched the RETRACTED #2 (2026-11-16): Production deploys are made from the release branch  ·  ns-brain get 2 for its text

When the brain is shared by a team, one person's correction is what every agent on the team gets the next time any of them asks about deploys.

This has a real cost: the brain cannot tell when two facts contradict each other. The same-subject check compares title words, so a contradiction written in different words is still stored (titles shorter than five words are not checked at all, because "prod db host" and "prod db port" share half their words and are different facts). When two facts on one question come out level and neither replaces the other, recall marks them as two answers to one question. Recall cannot choose between them, so a person or the agent still has to decide which one stands.

The project behind this series ns-brain.fightclub.pro