CSE Roadmap

Core tier · about 6 hours · 10 parts

Part 3 of 10 · 2 min read

A key lets a new fact replace the old one instead of sitting beside it

Two near-identical vectors for two different points in time look, to a similarity search, exactly like a contradiction with no way to resolve it.

Think of a whiteboard where someone always writes the new meeting time right next to the old one instead of erasing it. A glance at the board gives you two answers with no way to tell which one still holds.

In plain words: a key names what a fact is about (meeting_time). Supersession means that writing a new fact under an existing key marks the old one superseded: kept for audit, but excluded from default search. The stale value stops competing with the current one in every future search, rather than just losing by a score.

A worked example. Over 5 worlds and 30 questions at k=3, similarity-only retrieval is correct 43% of the time and surfaces a stale value on 30% of questions -- because it has no concept of "replaced." Blending in recency and importance raises correctness to 60%, still with a 30% stale-value rate: the two facts are still both in the store, just reordered. Only turning on supersession removes the stale value from search entirely (0% stale-present) and pushes correctness to 90%.

The key lines. From code/mini-recall/store.py:

# from code/mini-recall/store.py
def add(self, text: str, day: float, importance: float = 0.3, key: str | None = None, source: str = "user") -> Item | None:
    it = Item(self.next_id, text, day, importance, key, source)
    self.next_id += 1
    if key is not None:
        for o in self.items.values():
            if o.key == key and o.superseded_by is None:
                o.superseded_by = it.id     # kept for audit, excluded from default search
        self.items[it.id] = it
    return it

Read it as: the loop finds every existing item with the same key that hasn't already been superseded, and marks it superseded before the new item is even stored. Currency is decided once, at write time, by comparing keys. That is a check a similarity score can never perform, because two different points in time can produce nearly identical vectors.

Key, supersession, stale value

A key names what a fact is about; only keyed facts can be superseded. Supersession is marking an older fact under the same key as replaced when a new one is written. A stale value is an out-of-date fact that would still be retrievable without supersession.

Example: the jump from 60% correct (blended, no supersession) to 90% correct (blended plus supersession) is supersession doing the one thing no scoring weight can do -- making the old value physically absent from the search results, not just ranked lower.