afx-team / afx-team/hebb-mind

feat(retrieval): genuinely multi-cortical recall — link channels via content-cued spreading activation

Abierto
#27 1 comentario 0 reacciones 0 asignados Ver en GitHub
effort: hard feature retrieval
Lenguaje dominante
Python
Estrellas
52
Forks
18
Métricas de merge de PR
Sin PR fusionados en 30 d

Descripción

## Summary

Recall today fuses three independent channels (vector + keyword + graph) with RRF and then a cross-encoder rerank, but it does **not** genuinely *combine cortical regions* the way the README's brain-inspired framing implies. The "graph" channel matches query tokens against tag nodes, expands one hop, and surfaces the result as a UI-side `related[]` list — it never participates in ranking, and there is no spreading activation, pattern completion, or region-aware combination.

This issue proposes making recall **genuinely multi-cortical**: let activation flow *across* channels so that evidence found in one region (e.g. a vector hit) can cue and strengthen related memories in another region (graph neighbors, same-partition siblings), more closely mirroring how cortical areas co-activate during retrieval.

## Current state (as shipped)

- `MemorySearcher.search` runs three parallel paths — **vector** (embedding similarity), **keyword** (FTS5 / tsvector), **graph** (tag match → neighbor expansion) — fused with RRF (k=60), then optionally cross-encoder reranked.
- The graph path is **tag-keyed and content-blind**: `search_tags` does token-wise matching of the query against tag ids/labels, traversal is fixed depth-1, and the expanded neighbors feed a `related[]` list rather than the ranked results. When it does contribute, hits carry a static frequency-derived score, not a content-relevance score.
- Channels are **siloed**: a strong vector hit cannot cue its graph neighbors or same-partition siblings into the candidate pool. There is no cross-channel activation.
- The knowledge graph is only populated by **consolidation**, so raw-write deployments have an empty/sparse graph — the "multi-cortical" path is effectively inert there.

Net: the "multi-cortical recall / CA3 cell-assembly" language is aspirational relative to what the pipeline actually does. The Hebbian/CA3 mechanics that *are* real live in the consolidation + forgetting loop, not in recall.

## Proposed feature — link the cortices

Add a genuine cross-region activation stage, all behind **default-OFF flags** and **A/B-gated** (see constraints):

1. **Content-cued spreading activation** as a real 4th RRF channel.
Seed activation from the *tags of the top vector + keyword hits* (not a query substring), then propagate over weighted graph edges with distance decay (e.g. `activation *= decay ** hops`). Collect the memories on activated nodes as a ranked channel that joins the RRF fusion — so a vector hit can pull in its graph-connected relatives.
2. **CA3-style pattern completion** — when a subset of an assembly (co-occurring tags / co-consolidated cluster) is activated, boost the remaining members so a partial cue completes the pattern.
3. **CLS / region-aware recall** — use the existing partition plumbing to recall per partition-group and combine, instead of pooling all partitions undifferentiated (the search router currently never sets `partition_ids`).
4. **Populate the graph on raw writes** (lightweight tag edges), so the spreading-activation channel is non-empty without requiring consolidation first.

## Constraints & acceptance criteria

- Every new mechanism ships behind a **default-OFF flag**; shipped default behaviour stays bit-for-bit until proven.
- **Eval per house rules**: full dataset (no train/test split), isolated server on ports 8401–8409 with its own `hebb.db`, `.venv/bin/python`, run with rerank **ON and OFF**, and include **multi-hop** MemBench slices (single-hop recall is near-saturated, so the lever should show up on multi-hop).
- **Ship-gate**: ≥ +1pp headline or ≥ +2pp multi-hop vs. the current default; record the in-tree `run-N` report before any number lands in `repo_pages/benchmarks/`.
- Honest-README correction can land independently and immediately (zero code risk): scope the CA3/Hebbian language to consolidation, describe recall as hybrid RRF + rerank until the multi-cortical channel proves out.

## Risks / open questions

- Tag graph may be **too sparse** (< ~1.5 edges/node) for spreading activation to fire — measure edge density first; consider embedding-kNN edges as a denser substrate.
- **Wash risk**: rerank is the dominant retrieval lever and already recovers in-pool answers; LongMemEval R@10 is saturated (~0.994). The new channel must earn its keep on multi-hop, not on saturated single-hop.
- RRF normalization when a channel is ablated needs a look (the per-hit cap can under-normalize a missing channel).
- Latency / cost budget for the extra traversal + re-fusion.

## References

- Internal audit (2026-06-07): "multi-cortical recall is a pseudo-claim as shipped."
- `src/hebb/retrieval/searcher.py` — three-path recall + RRF + rerank.
- `src/hebb/graph/knowledge_graph.py` — tag graph, `search_tags`, neighbor expansion.

Guía de contribución

Abrir la guía de contribución

Evaluación

Este issue todavía no se ha evaluado.

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.