How ai-memory Finds the Right Past
ai-memory's retrieval problem is not simply “find text similar to the query.” A later agent may ask about a failure using different words, need a page linked to the one that matched, or want to know what the project believed before a migration. This chapter explains how the system combines several bounded signals, why canonicality is adjusted only after relevance, what the published measurements establish, and why historical as_of search means “what the store knew” rather than “what was true in the world.”
Why one query needs several kinds of evidence
Imagine asking, “How do we deploy this service safely?” The relevant page might use the phrase “release procedure,” mention a particular environment as an entity, link to a gotcha about stale binaries, and have no exact word in common with the question. No single retrieval method is guaranteed to see all of those relationships.
The first stream is lexical full-text search through SQLite's FTS5 index. It is strong when the question and page share meaningful terms, especially names, error messages, or distinctive phrases. It is transparent and works without an embedding provider. Its weakness is paraphrase: “resume the release process” may not match a page that says “publish the container image” even when the two refer to the same practice.
The entity stream starts from the nouns a page declares in its frontmatter, including entities derived from tags. A project can therefore be found through a named database, service, or tool even when the body uses varied language. The index is project-scoped and weights a common entity less than a rare one, so a tag applied to nearly every page does not dominate the ranking simply because it appears everywhere.
The graph stream follows page links and typed relations. A page about a linker failure may lead to a page describing the fix; a decision may link to the gotcha that motivated it. The relation vocabulary is deliberately closed—causes, fixes, and contradicts—so a typo cannot invent a new ranking category. A declared contradiction can also feed lint as a high-signal maintenance finding. The graph helps retrieve connected context, but the existence of an edge is a declared relationship, not proof that the relationship is true.
When embeddings are available, vector similarity supplies another candidate stream. It can recognize paraphrase and related wording even when full-text overlap is weak. ai-memory combines the streams with reciprocal-rank fusion, or RRF: each stream contributes a candidate's position rather than asking the system to pretend that lexical scores, entity weights, graph distance, and cosine similarity share one natural unit. The fused candidate set is then adjusted by bounded page authority signals.
Those authority signals include page kind, memory tier, pinning, and a small tag vocabulary. In a close contest, a maintained decision, procedure, or gotcha may receive a modest advantage over an episodic session page. This does not exclude the session page or declare the maintained page correct.