-
Notifications
You must be signed in to change notification settings - Fork 4
Learning Guide
How NeuralMind improves retrieval relevance by learning from how you actually use your codebase
NeuralMind's learning system improves automatically as you use it. The more you query, edit, and run tools over your code, the smarter recall gets — with no manual step to remember.
As of v3.9.0 the learning system combines six modern brain-inspired techniques in the synapse layer. It learns continuously from queries, edits, and tool calls, reinforces the edges between code nodes that fire together, and lets unused edges decay so recall tracks current usage instead of a stale snapshot.
┌──────────────────────────────────────────────────────────┐
│ 1. Observe │
│ Every query, tool call, and file edit co-activates a │
│ set of code nodes. │
│ ↓ The synapse layer reinforces edges between them │
├──────────────────────────────────────────────────────────┤
│ 2. Recall │
│ A new query lights up the relevant nodes; activation │
│ spreads across the learned graph. │
│ ↓ Related code surfaces that vector search would miss │
├──────────────────────────────────────────────────────────┤
│ 3. Decay │
│ Unused edges age out automatically; long-term │
│ potentiation protects frequently-used connections. │
│ ↓ Recall tracks current usage, not a stale batch │
├──────────────────────────────────────────────────────────┤
│ 4. Continuous improvement │
│ No `neuralmind learn` step — the graph grows as you │
│ work. │
└──────────────────────────────────────────────────────────┘
When one concept activates, it suppresses competing activations rather than only boosting neighbors. Prevents "attention dilution" in large codebases where many clusters are partially relevant.
Not every co-activation is meaningful. Two-phase model:
- Tag: Co-activation creates a temporary mark (short-term)
- Capture: If the same pair fires again within a consolidation window, tagged synapses capture "plasticity-related proteins" and become permanent
- Decay: Untagged marks fade without entering long-term memory
Memory retrieval both enhances the retrieved item AND weakens related but non-retrieved items (retrieval-induced forgetting). Prevents the "everything is vaguely associated with everything" problem.
Each node has a finite local resource pool. Strengthening edge (A,B) consumes resources from A's pool, naturally weakening competing edges (A,C), (A,D). Creates synaptic competition without global normalization.
Confidence gate on retrieval. If peak activation after spreading doesn't exceed an adaptive threshold, returns empty rather than weakly-associated noise. Prevents hallucination of irrelevant context.
Replay queue captures recent co-activation sequences. During idle periods, replays them to strengthen associations without new input. Interleaves recent + old patterns to prevent catastrophic forgetting.
For "how does X implement Y" queries, retrieval leans toward implementation code rather than docstrings.
On by default — both re-rank the hits retrieval already returned, so they cannot spend extra context:
-
Intent-aware classification: "how does X implement Y" → code intent,
which multiplies code hits by
NEURALMIND_CODE_BOOST(3.0) and doc hits by 0.5. The keyword heuristic alone scored this on "how does" and called it docs; matching the question shape is what fixed it. - Code-signal boost: Extracts identifiers, boosts matching source files.
Off by default, behind NEURALMIND_RETRIEVAL_EXPANSION=1 — these pull in
nodes vector search did not return, and so must displace a hit to make room:
- Synapse-seeded expansion: Spreads activation from query-matched nodes
- Dependency graph traversal: Finds callers/callees/imports
- Code snippet extraction: Shows actual source code with line numbers
Fixes 3–5 are disabled because they were measured and lost facts: on the
reference fixture they took the faithfulness delta from +0.041 to -0.065,
under the gate's +0.000 floor. Rebuilding them to be budget-neutral made it
-0.107 — worse — because displacement evicts a real hit for every candidate
pulled in, so a candidate that is worse than what it replaces now costs an
answer rather than only tokens. Their candidates are substring matches over
identifiers, and on that fixture they lose to the vector hits they displace.
Candidate quality is the open problem; the budget discipline is already there
waiting for it.
First-time only. When you run your first query, you'll be prompted:
$ neuralmind query . "How does authentication work?"
Enable local NeuralMind memory logging to improve retrieval over time? [y/N]: y✅ Consent saved to ~/.neuralmind/memory_consent.json
To disable: Set NEURALMIND_MEMORY=0 (query event logging) and/or
NEURALMIND_SYNAPSE_INJECT=0 (prompt-time synapse recall).
The synapse layer learns the most when it can observe your work. Install the lifecycle hooks once, and optionally run the file watcher for always-on learning from edits:
# One-time: install the lifecycle hooks (idempotent — safe to re-run)
neuralmind install-hooks .
# Optional: always-on learning from file edits
neuralmind watch &Just query and edit as usual. Co-activations are recorded automatically.
# Daily usage - these all reinforce the synapse graph
neuralmind query . "How does authentication work?"
neuralmind query . "What are the API endpoints?"
neuralmind query . "How is data validated?"
neuralmind query . "Where's the database logic?"
neuralmind query . "What's the error handling?"Each query also logs (when memory is enabled):
- The question you asked
- Which modules were retrieved
- How many tokens were used
- Which communities matched
The query event log is a local, auditable record; the synapse layer is what turns that activity into better recall.
On later queries, the synapse layer surfaces associations it has learned
— including related code that pure vector search would not have found,
because the relationship is behavioral (learned from co-activation),
not textual. Synapse-driven hits are labelled in the L3 output — a
[recalled] tag for code surfaced purely via the learned graph, and a
(+X.XX synapse) annotation on hits whose score the graph boosted:
$ neuralmind query . "How does auth work?"
## Search Results
1. **authenticate** (score: 0.91)
Type: function
File: auth.py
2. **validate_user** (score: 0.85 (+0.25 synapse)) ← boosted by the learned graph
Type: function
File: auth.py
3. **check_permissions** [recalled] (score: 0.23) ← surfaced purely via the graph
Type: function
File: middleware.pyReal-world data point: across a major rebuild of a private ~9,300-node TypeScript SaaS platform, personal synapse edges grew 36 → 135 as the layer learned the new code's co-activations — see the field report.
There is no weekly neuralmind learn step to run. The synapse store
grows continuously as you work, and SessionStart runs decay so weights
age between sessions. Inspect what's been learned at any time:
neuralmind stats . # includes a synapse breakdown
neuralmind memory inspect . # contribution by namespace
cat .neuralmind/SYNAPSE_MEMORY.mdFive activation paths, all of which strengthen pairwise edges between co-active nodes (Hebbian: "nodes that fire together wire together"):
-
Every
mind.query()— top search hits + loaded communities reinforce. -
PostToolUsehook — when the agent reads/runs/searches code together. -
UserPromptSubmithook — current prompt's neighbors get an activation pulse. -
SessionStarthook — runs decay so weights age between sessions, then exports memory. -
neuralmind watchdaemon — debounces file edits into co-activation batches; co-edited files wire together.
The synapse layer has been namespace-aware since v0.24.0:
branch:<name> / personal / shared / ephemeral memory live
separately in the same store, with a transparent merged read view. See
the memory namespaces commands.
The store is a weighted graph in SQLite (.neuralmind/synapses.db) with
two parts:
- An undirected co-activation graph — which nodes tend to be active together. Drives spreading-activation recall.
- A directional transition table (
synapse_transitions, v0.11.0+) — ordered(from_node, to_node)observations, so the agent can askneuralmind next <file>for a probability distribution over what's typically edited next.
Weights follow a Hebbian + decay + LTP (long-term potentiation) model: co-activation strengthens an edge, disuse decays it, and frequently-used edges are protected by an LTP floor so they don't evaporate.
Each SessionStart re-exports the synapse memory as markdown to:
-
<project>/.neuralmind/SYNAPSE_MEMORY.md— import inCLAUDE.mdvia@.neuralmind/SYNAPSE_MEMORY.mdso it's part of every session. -
~/.claude/projects/<slug>/memory/synapse-activations.md— Claude Code's auto-memory directory (when present); the model picks it up natively without anyone calling an MCP tool.
✅ 100% Local — All learning happens on your machine
✅ No Telemetry — Nothing sent to servers
✅ User Control — One-time consent, can disable anytime
✅ Persistent — Memory stays in your .neuralmind/ directory
Agents learn in their own store; the human and team layers change only through an explicit, git-committed bundle — never the agent writing them directly. Concretely:
-
Human-curated files (
CLAUDE.md, docs, config) are read-only to the learning layer — no hook, watcher, or MCP tool ever writes them. The exportedSYNAPSE_MEMORY.md/ Claude auto-memory files are separate, clearly-labeled render targets, not edits to your files. -
Agent-learned memory lives in
.neuralmind/synapses.dbunder thepersonalorbranch:<name>namespace. It is free to be noisy because it is weighted and decays — stale associations fade instead of compounding. -
Team-shared memory (
.neuralmind-team-memory.json) only changes via an explicit publish to a git-committed bundle — reviewable like any other diff. Imports are MAX-merged (a bundle can only raise weights it asserts, never rewrite or lower others) and never touch yourpersonalnamespace.
This means an association the agent learned can never silently become team-trusted knowledge — promotion requires an explicit, reviewable commit. See the repo-root positioning note TRINODE.md for the full trust-boundary rationale.
~/.neuralmind/
├── memory_consent.json # Consent flag (once per user)
└── memory/
└── query_events.jsonl # Global event log
project/.neuralmind/
├── memory/
│ └── query_events.jsonl # Project-specific events
└── synapses.db # SQLite-backed Hebbian synapse store
# Disable query event logging
export NEURALMIND_MEMORY=0
# Disable prompt-time synapse recall injection
export NEURALMIND_SYNAPSE_INJECT=0
# Disable the auto-memory export
export NEURALMIND_SYNAPSE_EXPORT=0You can also disable the layer entirely in Python with
NeuralMind(..., enable_synapses=False), or wipe the learned graph at
any time with mind.synapses.reset().
Problem: neuralmind stats . or neuralmind memory inspect . shows
nothing learned.
Solution:
- Have you run at least one query, or installed the hooks / watcher?
- Did you consent to memory logging? You should see the prompt on first query.
- Check the memory file exists:
ls -la project/.neuralmind/memory/query_events.jsonl - Check
NEURALMIND_MEMORYis not set to0.
Problem: You see no synapse-recalled hits in search results.
Solution:
- The synapse graph needs to warm up — query, edit, and run tools over a
few sessions, or run
neuralmind watch .to learn from edits. - Check
NEURALMIND_SYNAPSE_INJECTis not set to0. - Inspect the store:
neuralmind stats .andcat .neuralmind/SYNAPSE_MEMORY.md.
✅ DO: Ask questions and edit code naturally as you work
neuralmind query . "How does user login work?"
❌ DON'T: Artificially create queries just to "train" the layer✅ DO: Run neuralmind watch . so co-edits feed the synapse graph
neuralmind watch &
❌ DON'T: Expect rich recall from a cold store on day one✅ DO: Ask varied questions about your codebase
- "How does auth work?"
- "What are the API routes?"
- "How is data validated?"
❌ DON'T: Ask the exact same question repeatedly✅ DO: Use the built-in inspectors to understand your code's associations
neuralmind stats .
neuralmind memory inspect .
❌ DON'T: Hand-edit synapses.db (it's managed by the layer)Learning has negligible overhead:
- Recall (spreading activation): a few ms over the existing vector search
- Reinforcement: a small SQLite write, batched by the watcher
-
Storage: a compact SQLite graph in
.neuralmind/synapses.db
The untraced hot path pays nothing for trace/attribution machinery.
Before v0.25.0, NeuralMind also shipped a learned_patterns
cooccurrence reranker. You ran neuralmind learn . to analyze logged
query events, which wrote .neuralmind/learned_patterns.json, and the
next query re-ordered its L3 hits by a +0.3 cooccurrence boost.
It was removed after a 2×2 A/B on the benchmark fixture showed it
added 0.0 points to top-k hit rate whether the synapse layer was on
or off (77.2% → 77.2% cold, 83.3% → 83.3% warm — these are the levels that one run produced; the absolute hit rates move between runs, so the finding is the 0.0-point delta, not the levels), while the
synapse layer alone moved it. The reranker was also runtime-inert on the
warm path — the synapse boost re-sort discarded its ordering anyway — it
required the manual neuralmind learn step to populate, and its JSON
captured a snapshot that went stale between runs. The synapse layer is
strictly better on all three counts: automatic instead of manual,
decaying instead of staling, and the only mechanism with measured lift.
What this means for you:
-
neuralmind learnis now an exit-0 deprecation no-op. Scripts and CI that call it keep working; you can drop the call when convenient. -
.neuralmind/learned_patterns.jsonis no longer read or written. An existing one is simply ignored and can be deleted. -
NeuralMind(enable_reranking=...)is accepted and ignored for backward compatibility. - The L3 output no longer prints
(+X.XX boost)reranker labels; synapse-recall labels are unchanged.
See the v0.25.0 release notes for the full evidence and migration notes.
-
Synapse import/export — let teams share a learned brain (shipped as
neuralmind memory export/importin v0.24.0). - Quality benchmark — measure retrieval gain with vs without synapses (the self-benchmark's Phase 2 synapse A/B).
- Feedback signals — explicit ratings to further improve recall.
- CLI Reference — All commands
- Brain-Like Learning — design rationale
- Architecture — synapse layer architecture
- Troubleshooting — Common issues