Skip to content

docs: describe recall's real fusion; stop storing layer file counts (#562, #563) - #566

Merged
cdeust merged 1 commit into
mainfrom
docs/562-563-recall-fusion-inventory
Sep 15, 2026
Merged

docs: describe recall's real fusion; stop storing layer file counts (#562, #563)#566
cdeust merged 1 commit into
mainfrom
docs/562-563-recall-fusion-inventory

Conversation

@cdeust

@cdeust cdeust commented Sep 15, 2026

Copy link
Copy Markdown
Owner

Summary

Two documentation defects, each measured against the code at a3b3a79.

Closes #562
Closes #563

#562. The docs, the recall tool description and one MCP prompt described the read path as "6-signal WRRF" (vector, BM25, heat, Hopfield, HDC, SR). What the code does:

  • recall_memories() (mcp_server/infrastructure/pg_schema.py:918-1138) fuses five signals inside PostgreSQL: pgvector cosine, ts_rank_cd full-text (not BM25), pg_trgm trigram, effective_heat() and recency. It combines them as a weighted sum of max-normalised scores (:1059-1085).
  • SQLite fuses vector, FTS5, heat and recency by rank, w/(k + rank), with no trigram signal (mcp_server/infrastructure/sqlite_store_search.py:60-136).
  • Hopfield and HDC run after fusion, each blended by RRF k = 60 (mcp_server/core/pg_recall_stages.py, mcp_server/core/recall_pipeline.py:99-128). Successor Representation is not on the recall path: collect_signals (the only caller of compute_sr_scores via core/retrieval_signals.py) is not imported by handlers/recall.py.
  • core/query_router.py is a deprecated shim (its own docstring, ADR-0234).

Corrected in docs/mcp-tools.md, docs/architecture.md, docs/api-reference.md, docs/data-flow.md (diagram and signal tables), README.md (one sentence), the recall handler's description strings and mcp_server/mcp_prompts.py. ADR-013 keeps its original design text with a dated note; the note is written in the canonical page wiki/adr/cortex/0013-zikkaron-thermodynamic-memory.md and mirrored with scripts/check_project_wiki.py --write, since docs/adr/ is a read-only mirror.

The data-flow diagram also drops the "Query Enrichment / Doc2Query" box: build_expanded_query is only called from recall_helpers.compute_vector_fts, which handlers/recall.py does not import, so the box described a stage the tool does not run.

#563. docs/module-inventory.md stored four per-layer file counts that had drifted. A count there changes with every new module, and an exact gate would conflict across parallel branches (the reason check_doc_claims.py treats the test count as a floor). The page now gives the measurement command instead of a number.

Test plan

  • ruff check, ruff format --check (ruff 0.16.6): pass.
  • python scripts/check_craftsmanship.py: OK. python scripts/check_doc_claims.py: OK. python scripts/check_project_wiki.py: mirrors match.
  • pytest tests_py/test_mcp_prompts.py tests_py/scripts tests_py/handlers/test_recall.py tests_py/handlers/test_tool_schema_parity.py tests_py/server on PostgreSQL: 1011 passed, 359 subtests passed.

Coding-standards compliance

Documentation and description strings only; no behaviour change.

🤖 Generated with Claude Code

@cdeust @claude
docs: describe recall's real fusion; stop storing layer file counts (#…
6ff06d9 
…562, #563)

#562. The docs, the recall tool description and the MCP prompt called the
read path "6-signal WRRF" (vector, BM25, heat, Hopfield, HDC, SR). The
code fuses five signals inside the database: vector, full-text
(ts_rank_cd / FTS5), trigram, effective heat and recency. PostgreSQL
combines them as a weighted sum of max-normalised scores
(infrastructure/pg_schema.py, recall_memories()); SQLite uses rank-based
WRRF without the trigram signal (infrastructure/sqlite_store_search.py).
Hopfield and HDC run after fusion (core/pg_recall_stages.py). Corrected in
docs/mcp-tools.md, docs/architecture.md, docs/api-reference.md,
docs/data-flow.md (diagram and signal tables), README.md, the recall
handler's description strings and mcp_prompts.py. ADR-013 keeps its
original design text with a dated note, written in the canonical wiki page
and mirrored by scripts/check_project_wiki.py --write.

#563. docs/module-inventory.md stored four per-layer file counts that had
drifted from the tree. A count in this page changes with every new module
and no gate can hold it exactly without conflicting across parallel
branches, so the page now gives the measurement command instead.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
@cdeust

cdeust commented Sep 15, 2026

Copy link
Copy Markdown
Owner Author

ZETETIC-REVIEW: APPROVE

Reviewed at 6ff06d9 against the acceptance criteria of #562 and #563.

  • [docs] recall documented as 6-signal WRRF; PG path is a weighted sum of 5 SQL signals #562: every changed sentence was checked against the code it describes. The PostgreSQL fusion is a weighted sum of max-normalised scores (pg_schema.py:1059-1085), and full-text search uses ts_rank_cd. SQLite fuses by rank with no trigram signal (sqlite_store_search.py:60-136). Hopfield and HDC run after fusion (pg_recall_stages.py, apply_recollection_pipeline). handlers/recall.py does not import SR (compute_sr_scores) or query expansion (build_expanded_query); both are reached only through recall_helpers.collect_signals / compute_vector_fts, so they are off the tool path. ADR-013 was edited through its canonical wiki page, and check_project_wiki.py reports the mirror in sync.
  • [docs] docs/module-inventory.md per-layer file counts are stale #563: the counts are replaced by the measurement command, so there is no stored number left to drift.
  • No behaviour change: the only code edits are description strings and one prompt string. CI is green on all 24 required checks, including check_doc_claims.py and the craftsmanship gate.

@cdeust
cdeust merged commit 1d5a534 into main Sep 15, 2026
28 checks passed
@cdeust
cdeust deleted the docs/562-563-recall-fusion-inventory branch September 15, 2026 02:06
This was referenced Sep 15, 2026
Merged
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

[docs] docs/module-inventory.md per-layer file counts are stale [docs] recall documented as 6-signal WRRF; PG path is a weighted sum of 5 SQL signals

1 participant

@cdeust