Fight ClubBlog

Anatomy of a memory for LLMs

Wrong facts cost tokens and cause context pollution

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

A postal service sorts everything by place: country, then state (province or county, etc.), then city, then the local post office. Each level keeps the facts that belong to it (the local office knows that the box outside is emptied at half past five, the city office knows which van covers which streets) and no single office keeps all of them. When you ask the clerk in your local office a question, the answer comes from the nearest level that has one: the local rule first, then the city, then the country. It never works in the other direction. The national office does not keep the emptying time of every post box in the country, because a question about the whole country should never be answered with one street's detail. A warehouse does the same with zones, aisles and shelves, a supermarket with departments and shelves. Anything that has to hold a lot of facts and still find the right one quickly ends up sorting them by where they belong.

A memory for an AI agent needs the same sorting, because the agent asks about one subject at a time. A question about card refunds should match and retrieve the facts about card refunds, the facts about refunds in general and any relevant global rules, like our website, our T&Cs location, etc. It should not get back the facts about shipping or opening hours or product information. Every wrong fact that comes back costs tokens for nothing. Worse, the model treats it as one more thing that might be true: an answer built on the wrong fact sounds just as sure as a correct one. In research this is usually called being distracted by irrelevant context, commonly known as context pollution or context poisoning.

So in ns-brain every memory is stored with a label that says which subject it belongs to, like the address on a letter. That label is called its scope. Scopes nest with a colon, exactly like an address written from the country down: product, then product:purchase, then product:purchase:refund, then product:purchase:refund:card. Above all of them sits global, which is never written in the name. Global holds the uncategorized facts, usually the basic rules of doing business (the website, where the T&Cs are). A search in one scope also sees every scope above it, so global is searched on every query (so it must be lean) and its facts come back whenever they match. The nearest scope ranks first. Every fact that matches gets a score for how well its words fit the question. For example, for the question "how long does a card refund take?" the fact "card refunds take 5 to 10 working days" fits better than "refunds need the original receipt", so it gets a higher score. ns-brain then multiplies that score by a weight that depends on where the fact is stored, as the diagram shows:

Figure 1Where a search looks

global x0.8 product x0.85 shipping purchase x1.1 catalog refund x1.35 payment card x1.6 cash
  • a fact in the scope that was asked for counts 1.6 times: its score is multiplied by 1.6, so it gets a 60% advantage over a fact that matches the question just as well but is stored somewhere more general
  • each step further up the tree counts 0.25 less: 1.35 for the parent (product:purchase:refund), 1.1 for the one above it (product:purchase) and 0.85 for product.
  • cash refunds, payments, the catalog and shipping are not on its way up, so the search never sees them.

Let's take as example two facts that match a question about card refunds equally well, with a score of 0.5 each. The one stored in product:purchase:refund:card scores 0.5 × 1.6 = 0.8 points and the one stored in product with 0.5 × 0.85 = 0.43, so the card fact comes first. The weight only decides between facts with similar accuracy. A refund rule in product:purchase:refund that matches far better (0.9) still scores 0.9 × 1.35 = 1.22 and comes above the card fact. The general facts are never hidden: they only make room for the specific ones.

A search in product sees only product and global. It does not see purchases, refunds or card refunds, because a general question should not be answered with a detail from somewhere below it: information flows inward, from the general to the specific. When someone really wants a whole branch (every refund rule, say), a pattern like product:purchase:refund* searches every scope whose name starts that way.

Figure 2Information flows inward

global x1.35 product x1.6 shipping purchase catalog refund payment card cash
The same tree, searched from product. It sees product (1.6 times) and global (1.35) and nothing below: a general question is never answered with the detail of one branch. A pattern such as product:purchase:refund* is the way to ask for a whole branch on purpose.

Here is the output of three real ns-brain commands, run against a test brain with one fact stored in each of the nine places of that tree (the whole shop, products, shipping, purchases, the catalog, refunds, payments, card refunds and cash refunds). Every one of those facts contains the word refund. The same word, asked from two different places, gets two different answers. A word that matches nothing gets nothing at all, which is how an agent asks (--strict):

$ ns-brain recall "refund" --scope product:purchase:refund:card
#8  [product:purchase:refund:card/infra] (score 0.728) Card refunds take 5 to 10 working days to reach the customer's account
      The time is set by the card networks, not by us.
#6  [product:purchase:refund/decision] (score 0.567) Refunds over 500 euro need a manager's approval
      Fraud rule from the bank.
#4  [product:purchase/decision] (score 0.462) A refund needs the order number from the purchase email
      Without it the till cannot find the sale.
#2  [product/decision] (score 0.357) Products can be returned for a refund within 30 days of delivery
      Set by the owners in January.
#1  [global/constraint] (score 0.336) Every refund goes back to the payment method the customer used
      Rule in the terms and conditions for the whole shop.

$ ns-brain recall "refund" --scope product
#2  [product/decision] (score 0.742) Products can be returned for a refund within 30 days of delivery
      Set by the owners in January.
#1  [global/constraint] (score 0.626) Every refund goes back to the payment method the customer used
      Rule in the terms and conditions for the whole shop.

$ ns-brain recall "warranty" --scope product:purchase:refund:card --strict
(no match for 'warranty' in memory; --browse to see the scope anyway)

The script that populates this test brain and runs these three commands is on GitHub, so you can run it yourself: https://github.com/chka/ns-brain-examples/tree/main/01-scope-tree

The agent asked about card refunds gets the 5 to 10 working days first, then the manager's approval for refunds over 500 euro, then the order number for purchases, then the 30-day return rule for products and last the rule from the terms that holds everywhere. Nothing else comes back: shipping, the catalog, payments and cash refunds never appear, even though each of them holds a fact with the word refund in it. Asked from product, the same word returns only the product rule and the shop rule.

This has a real cost: somebody has to choose the scope when the fact is stored and the choice can be wrong. A fact filed under product:purchase:refund:card is invisible to a search in shipping or in product:purchase:refund, the same way a letter with the wrong ZIP code goes to the wrong town. Too many small scopes split the memory into pieces that never meet. Too few put everything back in one pile. In a coding project the agent chooses the scope. In an app the app chooses it, so its memory is only as good as its categories. Everyone on a team files into the same places and searches the same places, so a fact one person filed under product:purchase:refund:card is found by anyone who asks there.

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