Covers: Definitions; The pipeline; A worked example.
Definitions
Embedding, vector store, top-k, cosine similarity
Embedding: a vector of numbers computed from text so that texts with similar meaning are close together.
Vector store: a database that holds embeddings with their original text and metadata and can return the nearest ones to a query vector.
Cosine similarity: the cosine of the angle between two vectors; 1 means the same direction, 0 means unrelated.
Top-k: the k highest-scoring items. k is a budget on how many memories enter the window.
Relevance, recency, importance
Relevance: how well a memory matches the current query (here, cosine similarity).
Recency: a function of the memory's age that decays over time; here 0.5^(age / half-life) with a 14-day half-life.
Importance: a score assigned when the memory is written (a constraint or decision scores high, chatter low), so that an old but critical memory can outrank a recent trivial one.
Supersession, stale value, key
Key: a name for the thing a fact is about (meeting_time). Only facts with a key can be superseded.
Supersession: when a new fact is written under a key, the older value is marked superseded: kept for audit, excluded from default search.
Stale value: an out-of-date value for a key that is still retrievable.
Write gate, quarantine
A write gate decides whether a source may write a keyed fact; here only user and system may. Refused writes go to a quarantine list instead of the store, so an injected instruction cannot supersede a real fact.
Hard delete
Removing a memory so it can no longer be retrieved, including from the index statistics. In the example forget() removes the item and the inverse-document-frequency table is recomputed from what remains. (A production store also has to delete the vector and any copies; module 2 covers the byte-level check.)
The pipeline
Write path (left to right, top) and read path (bottom). The gate and supersession happen at write time; the score and filter happen at read time.
The key design decision is where each guarantee lives. "Only one current value" is enforced at write time (supersession); "the most relevant items" is computed at read time (score). Trying to enforce currency at read time (for example by asking the model to pick the newest) puts a correctness property in the least reliable component.
A worked example
One question where the old and new values are both stored (seed picked automatically by demo.py): "When do I like to schedule our call?" The current answer is 11am; the old value, 2pm, was written on day 19 and replaced on day 42.
Policy
Top 3 retrieved
Answer present
Stale present
recency only
three recent chatty notes
no
no
similarity only
"I prefer meetings at 11am", "I prefer meetings at 2pm", a chatty note
yes
yes
blended score
same two facts, then a note
yes
yes
blended + supersession
"I prefer meetings at 11am", two notes
yes
no
The two facts have the same similarity score (0.70). Nothing in the vector distinguishes them. The blended score ranks the newer one first (0.96 against 0.88), but the old one is still inside the top 3. Only supersession removes it.