Memory quality

A memory layer is only useful if what it recalls is true, current, and actually relevant. Memory Layer treats that as a defense-in-depth problem: quality is enforced when memories are written, while they sit at rest, at the moment they are recalled, and by measurement gates that catch regressions before a release.

This page is the map. Each section summarizes one mechanism and links to the detailed description and reference material.

Write time

Curation and lexical dedup

Raw captures never become memory directly. Curation extracts candidate assertions, drops noise, and checks each candidate against existing knowledge. An exact re-observation does not create a duplicate — it raises the existing memory's confidence and importance instead. When a candidate overlaps an existing memory strongly (shared wording, files, tags, or explicit update language), a replacement decision engine either supersedes the old memory in place or queues a human-reviewed proposal, governed by the per-repo conservative / balanced / aggressive replacement policy.

Read more: How it works — curation · memory curate and memory proposals · Project config

Semantic dedup and conflict detection

Lexical overlap misses paraphrases: "deploys ship after checks pass" and "releases publish once verification completes" share almost no words. Once chunk embeddings are built, a semantic pass compares new memories against the project by cosine similarity. Near-duplicates are linked and queued as human-gated merge proposals. Pairs with high embedding similarity but low lexical overlap and supersede/negation cues are flagged as likely contradictions — an old fact versus a new one — and routed to review as conflicts, never merged automatically.

Read more: [curation] config section · memory proposals

At rest

Immutable versioning

Nothing destructive happens to accepted knowledge. Replacements, corrections, and rewordings append a new version under the same canonical identity; the old version stays available to history-aware queries and every change can be reverted. This is what makes the rest of the machinery safe to automate.

Read more: Memory types and lifecycle · Database schema

Provenance verification

Memories cite their evidence: files, symbols, commits, prompts. A background verifier re-checks that cited files still exist and cited symbols still appear in the code graph. Verification never deletes anything — a memory whose evidence went missing is down-ranked at query time and surfaced with a diagnostic, and the rate of change in a memory's source files feeds its volatility, which schedules it for earlier re-validation.

Read more: memory verify-provenance · Retrieval and search

Maintenance

Activation scoring (reinforcement)

Every memory earns an activation score from real usage: being cited in a synthesized answer counts most, appearing in results counts, direct reads count a little. Scores decay exponentially between accesses and spread to related memories with fan normalization, following the ACT-R activation model from cognitive science. Activation gives ranking a tie-breaking usage signal and tells the validation pipeline which memories are hot enough to be worth re-checking.

Read more: Self-maintaining memory · memory scores

Evidence-backed validation

When a hot memory crosses the activation threshold, the pipeline gathers deterministic evidence — sources, provenance status, related memories, recent git history — and asks an LLM for a verdict under strict rules: it may cite only evidence it was shown, and any verdict citing anything else is rejected outright. The cardinal rule is that weak or contradictory evidence never edits content: corrections are always human-gated, and ambiguous verdicts only flag the memory needs review, which rank-penalizes it until a person resolves it.

Read more: Validation · memory validate and memory review · TUI review queue

Hygiene automations

Background loops propose cleanups over the existing corpus: merging likely duplicates, deprecating stale low-confidence memories, and linking related facts. Loop proposals are risk-tiered, budgeted, sandboxed, and land in the same human review queue as everything else — the loops never mutate memory directly.

Read more: Automations · TUI automations tab

Consolidation and insights

Recall of many small, related memories is worse than recall of one that sees the whole picture. Consolidation discovers clusters of related memories and synthesizes a higher-level insight memory that summarizes them — and, crucially, names the unifying concept, the internal tensions or contradictions, the open gaps, and the implications for design or refactoring. This is where the memory layer stops being a filing cabinet and starts producing understanding.

Clusters are found by fusing three signals into one graph and running community detection over it: memory relations, embedding similarity, and co-access (memories retrieved or cited together in the same query). A value gate keeps only clusters that are cohesive and either salient (used together) or dense-but-cold (not used individually) — so consolidation triggers on both use and neglect, and noise is left unconsolidated. Synthesis is a two-step LLM pass with the same citable-evidence guard as validation: it may only reference the member memories it was shown. The result is a human-gated proposal that, once approved, inserts the insight, links it to each member with a summarizes relation, and records the members as provenance — atomically, in one review. Insights are ordinary memories, so a later run consolidates insights into higher-level insights: a schema tree that grows with the project.

The mechanism is grounded in memory science — complementary learning systems and schema consolidation, sleep-replay gist extraction, the reflection trees of generative agents, and hierarchical summarization (RAPTOR, GraphRAG). It is off by default and dry-run first, like validation.

Read more: Consolidation and insights — the full mechanism, triggers, and cited science · [consolidation] config section · memory proposals

Recall

Hybrid retrieval and ranking

Recall quality starts with finding the right candidates: lexical full-text, semantic embedding, and code-graph retrieval run together and their results are fused. Ranking then combines match strength with quality signals — confidence, importance, recency, relation links, activation — and applies penalties: weak matches are damped, needs review memories are down-weighted, and missing-provenance decay pulls stale evidence down. Every result carries a score explanation so you can see exactly why it ranked where it did.

Read more: Retrieval and search · memory query

Answer synthesis guardrails

Synthesized answers cite the specific memories they draw from, and those citations feed back into activation scoring. When the best match is too weak to support an answer, the query returns insufficient_evidence instead of guessing — the design preference is refusing over fabricating. Concretely: an answer is refused when nothing anchors the top result to the question (low term overlap and low semantic similarity with no exact phrase match) or when the best evidence is itself a low-confidence memory; and a runner-up that restates the top result's topic — a duplicate, or a superseded sibling carrying a stale value — is never echoed as supporting context or cited.

Read more: Ranking diagnostics · Query and briefings CLI

Measurement

Eval suites and release gates

Scoring changes are easy to get wrong, so quality is measured, not assumed. The eval harness runs paired conditions (no-memory baseline versus full memory) over reviewed suites and gates releases on the deltas. The memory-quality canary (evals/suites/memory-quality-v1) adds adversarial items: seeded stale facts with fresher contradictions, vague rumors, and unanswerable questions, asserting the pipeline refuses or prefers the fresh fact. Its gate enforces absolute floors — including zero tolerated adversarial failures.

Status: the adversarial group passes (7/7) and the gate is green. It caught real failures first — deterministic synthesis used to echo superseded facts as supporting context and answered confidently on weak evidence — and the fixes were tuned against its measured per-item signals rather than intuition. That is the canary doing its job.

Read more: Evaluating Memory · Eval CLI

Summary table

References

The quality mechanisms are grounded in the memory and retrieval literature rather than invented heuristics.

Reinforcement (activation scoring):

• Anderson, J. R. & Schooler, L. J. (1991). Reflections of the environment in memory. Psychological Science — ACT-R base-level activation: usefulness of a memory tracks recency and frequency of use.
• Petrov, A. A. (2006). Computationally efficient approximation of the base-level learning equation in ACT-R. ICCM — the O(1) incremental form used for the running activation score.
• Collins, A. M. & Loftus, E. F. (1975). A spreading-activation theory of semantic processing. Psychological Review — spreading activation over related memories.
• Anderson, J. R. (1983). A spreading activation theory of memory. Journal of Verbal Learning and Verbal Behavior — the fan effect behind hub normalization.

Consolidation (insights):

• McClelland, J. L., McNaughton, B. L. & O'Reilly, R. C. (1995). Why there are complementary learning systems in the hippocampus and neocortex. Psychological Review — the fast/slow memory-store division.
• Tse, D. et al. (2007). Schemas and memory consolidation. Science — consolidation is faster when it attaches to an existing schema.
• Park, J. S. et al. (2023). Generative Agents. — reflection: theme extraction, insight synthesis, and reflection trees.
• Sarthi, P. et al. (2024). RAPTOR. — recursive embed-cluster-summarize hierarchies.
• Edge, D. et al. (2024). From Local to Global (GraphRAG). — community detection plus per-community summaries.
• Raghavan, U. N., Albert, R. & Kumara, S. (2007). Near linear time algorithm to detect community structures. — the label-propagation clustering used for consolidation.

Procedural utility (loop learning):

• Fu, W.-T. & Anderson, J. R. (2006). From recurrent choice to skill learning: a reinforcement-learning model. Journal of Experimental Psychology: General — the delta-rule utility learning behind ACT-R's procedural module, used here to learn each automation loop's value from proposal outcomes.

See the consolidation page for how each result maps onto the implementation. Deeper design material lives in the repository: docs/developer/architecture/memory-reinforcement.md, docs/developer/architecture/graph-and-curation-foundations.md, and docs/developer/adr/.