Context
After #142 wired the live synapse graph into retrieval, we now have two co-occurrence-based ranking signals stacked in get_l3_search:
learned_patterns.json reranker (SemanticReranker / CooccurrenceIndex) — built at batch time by neuralmind learn from the query-event log.- The Hebbian synapse layer — learned continuously from edits/tools/queries via hooks + the watcher, with decay.
Why deprecate the reranker
A 2×2 A/B on the benchmark fixture (reranker on/off × synapse on/off):
|
rerank OFF |
rerank ON |
| synapse OFF |
71.7% |
71.7% |
| synapse ON |
83.3% |
83.3% |
- The reranker moves top-k hit rate by 0.0 points with or without synapses. Synapses do all the work (+11.6 pts).
- Why it's inert: the reranker sorts by
_combined_score (distance space); when synapses fire, _apply_synapse_boost re-sorts by score (similarity), discarding the reranker's order. On the warm path (how active users run) it's already overridden.
- End-user value is negative:
learned_patterns.json only exists if the user manually runs neuralmind learn; it goes stale until re-learned; it overlaps a strictly more capable automatic signal. learned_patterns.json has no consumer other than the reranker.
Caveat: this is the ~500-line fixture and the hit-rate metric is partly insensitive to pure reordering, so "0.0" is strong directional evidence on the warm path, not absolute proof across all large repos. The structural disadvantages (manual step, staleness, runtime override) hold regardless of repo size.
Scope (≈15 files — this is a documented-feature deprecation, not a refactor)
neuralmind/context_selector.py — remove enable_reranking, _get_reranker, the reranker.rerank call in get_l3_search.neuralmind/reranker.py — remove (or keep only if reused elsewhere).neuralmind/memory.py — build_cooccurrence_index, write_learned_patterns.neuralmind/cli.py — cmd_learn / the learn subcommand.neuralmind/core.py — enable_reranking plumbing.- Tests:
test_reranker.py, test_context_selector.py, test_memory*.py, test_cli.py, test_query_search_dedup.py.
- Benchmark:
tests/benchmark/run.py Phase 2 (currently measures learned_patterns) → fold into the synapse A/B; benchmark_queries.json learning_seed.
- Docs:
Learning-Guide.md (wiki), CLI-Reference.md, Usage-Guide.md, offline-regulated.md.
Recommendation
Do this as a dedicated PR with its own review and doc updates — not bundled into #142. Because the reranker is already runtime-superseded for active users, there's no urgency.
Context
After #142 wired the live synapse graph into retrieval, we now have two co-occurrence-based ranking signals stacked in
get_l3_search:learned_patterns.jsonreranker (SemanticReranker/CooccurrenceIndex) — built at batch time byneuralmind learnfrom the query-event log.Why deprecate the reranker
A 2×2 A/B on the benchmark fixture (reranker on/off × synapse on/off):
_combined_score(distance space); when synapses fire,_apply_synapse_boostre-sorts byscore(similarity), discarding the reranker's order. On the warm path (how active users run) it's already overridden.learned_patterns.jsononly exists if the user manually runsneuralmind learn; it goes stale until re-learned; it overlaps a strictly more capable automatic signal.learned_patterns.jsonhas no consumer other than the reranker.Caveat: this is the ~500-line fixture and the hit-rate metric is partly insensitive to pure reordering, so "0.0" is strong directional evidence on the warm path, not absolute proof across all large repos. The structural disadvantages (manual step, staleness, runtime override) hold regardless of repo size.
Scope (≈15 files — this is a documented-feature deprecation, not a refactor)
neuralmind/context_selector.py— removeenable_reranking,_get_reranker, thereranker.rerankcall inget_l3_search.neuralmind/reranker.py— remove (or keep only if reused elsewhere).neuralmind/memory.py—build_cooccurrence_index,write_learned_patterns.neuralmind/cli.py—cmd_learn/ thelearnsubcommand.neuralmind/core.py—enable_rerankingplumbing.test_reranker.py,test_context_selector.py,test_memory*.py,test_cli.py,test_query_search_dedup.py.tests/benchmark/run.pyPhase 2 (currently measureslearned_patterns) → fold into the synapse A/B;benchmark_queries.jsonlearning_seed.Learning-Guide.md(wiki),CLI-Reference.md,Usage-Guide.md,offline-regulated.md.Recommendation
Do this as a dedicated PR with its own review and doc updates — not bundled into #142. Because the reranker is already runtime-superseded for active users, there's no urgency.