NeuralMind + Claude Teams
Procedures, Token Measurement, and Amnesia Prevention
Verified against the live codebase. DeepSeek v4 Pro QA-corrected.
Abstract
NeuralMind is a persistent memory layer that turns Claude (a stateless cortex) into an agent with long-term memory. This report provides a complete, citation-heavy reference for using NeuralMind with Claude Code teams: one-time setup, team memory publish/inherit workflows, daily usage patterns, token measurement at every layer, and the five mechanisms that eliminate agent amnesia. All claims are verified against the live codebase at commit 3fe5a61. A DeepSeek v4 Pro QA sweep corrected multiple refuted and aspirational claims from the original draft — the corrections are flagged inline.
Architecture
The Two-Brain Model: Claude is the cortex (stateless reasoning over a working-memory window). NeuralMind is the hippocampus + associative cortex (persistent weighted graph of code nodes that learns by Hebbian co-activation, decays unused edges, and runs spreading activation for recall).
Communication channels: MCP tools (15 tools, any agent), Claude Code lifecycle hooks (SessionStart, UserPromptSubmit, PreCompact, PostToolUse), and the file activity watcher (always-on, per-project).
Procedures
1. One-Time Setup (per repo)
pip install neuralmind
cd /path/to/your-project
neuralmind build . # builds knowledge graph + vector index (1-3 min)
neuralmind install-hooks . # registers PostToolUse + SessionStart + PreCompact hooks
neuralmind init-hook . # auto-rebuild on every git commit
neuralmind watch . & # always-on file watcher — the "brain" that learns
2. Team Memory Workflow (publish → inherit)
To publish (any team member, after the watcher has learned):
neuralmind memory publish . # writes .neuralmind-team-memory.json at repo root
git add .neuralmind-team-memory.json && git commit -m "nm: publish team memory"
This exports the union of personal + shared namespaces (MAX-merged per-field) into a provenance-stamped bundle at the repo root. Capped at 5,000 strongest associations.
To inherit (automatically, zero manual steps):
- Claude Code: SessionStart hook fires
maybe_import_team_memory()— merges committed bundle intosharedonce per content hash. - Generic agents:
neuralmind buildtriggers the same import seam. - Safety: Import only ever writes
shared; MAX-merge can only raise weights; per-namespace decay erodes stale edges.
3. Daily Claude Code Workflow
claude> neuralmind_wakeup(project_path=".") # ~400 tokens instead of 50K
claude> neuralmind_query(project_path=".", question="...") # ~800-1100 tokens
claude> neuralmind_skeleton(project_path=".", file_path="...") # ~88% cheaper than Read
claude> neuralmind_review(project_path=".") # catch co-breaks
claude> neuralmind_next_likely(project_path=".", from_node="...") # predict next file
Token Measurement
Measurement Stack
| Layer | Content | Budget |
|---|---|---|
| L0 Identity | Project name, description, key facts | ~150 tok |
| L1 Summary | High-level architecture, main components | ~600 tok |
| L2 On-Demand | Specific communities/modules as needed | ~800 tok |
| L3 Search | Semantic search hits | ~1000 tok |
Total wakeup: ~600 tok. Per-query: ~500-1000 tok. Vs full codebase: 50K+ tok loaded naively.
Benchmark Commands
neuralmind benchmark . --json # wakeup, avg query, avg reduction
neuralmind benchmark . --quality # MRR, answerability, recall@k
neuralmind probe . --sample-size 100 # self-probe on YOUR code
neuralmind savings . --cost --model claude-opus-4-8 --queries-per-day 100
Consumption-Side Compression
| Tool | Typical reduction | Mechanism |
|---|---|---|
| Read | Up to ~88% | File → skeleton (functions + rationales + call graph) |
| Bash | Up to ~91% | Keep errors + tail, drop middle |
| Grep | Capped | Max 25 matches, "N more hidden" pointer |
Note: The 88%/91% figures are documentation claims, not measured benchmarks. Actual compression depends on file size (Read only fires on files ≥1500 chars) and content type. Combined retrieval + consumption 5-10× is a documentation claim without measured evidence.
Amnesia Prevention — Five Mechanisms
1. Persistent Synapse Store (synapses.py, SQLite)
Learns weighted associations from how an agent actually uses the codebase. Time-based half-life decay: weight × exp(−λ × age_days). Per-namespace half-lives: personal=30d, shared=60d, ephemeral=1d. Structural synapse seeding (v0.46.0) converts 1,903 code graph edges into synapse edges on every build.
2. SessionStart Auto-Import (hooks.py:313-362)
Fires on every new session: decay tick → team memory import → autotune (opt-in) → ephemeral cleanup → synapse export to auto-memory.
3. Committed Team Memory Bundle
.neuralmind-team-memory.json at repo root travels with git clone. New hire's agent inherits on first session — zero manual steps. MAX-merge only raises weights; per-namespace decay erodes stale edges.
4. Synapse Memory Export (synapse_memory.py)
Renders top pairs, hub nodes, and directional transitions as markdown. Written to both project-local .neuralmind/SYNAPSE_MEMORY.md and Claude Code's auto-memory directory.
5. Spreading Activation Injection (hooks.py:364-385)
UserPromptSubmit hook runs spreading activation over the synapse graph for each prompt. Injects the top-8 most-associated nodes as additional context before Claude sees the prompt.
Self-Improvement Loop
The Product Ops vision: NeuralMind as a self-improving / self-evolving product — autonomous signal → diagnose → experiment → promote/rollback loop.
What's wired (Wave 1-4):
- Wave 2 (C1/A1/A2/B2/B3/G2): 6 modules shipped, 88 tests. All stdlib-only top-level, gated by env vars, fail-open.
- Wave 3 (C2/C3/A3/A4): Fitness function, trace store, tuner (single-variable in trace fallback; live eval is multi-objective but unmeasured). A3 learned decay is now wired (was dead code, patched).
- Wave 4 (E1/E2/E3/E4+G4): Contribution scoring, merge semantics, peer review (threshold 0.70, auto_promote fires), staleness (constant-per-pass after C2 fix). G4 incremental extraction built + tested but not wired into build_graph().
The gap: The fitness function is effectively single-variable in trace fallback mode. Live eval is multi-objective but unmeasured in production. Auto-tune is opt-in and capped at ±1 step per session. The "self-evolving product" is aspirational — the infrastructure is built, the tuning signal is weak in production.
DeepSeek QA Correction Log
This report was corrected on 2026-07-26 after DeepSeek v4 Pro verification against the live codebase. The following claims were based on outdated reference docs that described pre-fix states:
| Original Claim | Correction | Status |
|---|---|---|
| 88%/91% compression (measured) | Only in docs, not benchmarked. Actual ratio varies by file size. | Aspirational |
| 30-50x reduction (measured) | Modeled estimate with 50K default baseline. | Modeled |
| AUTO_PROMOTE_THRESHOLD = 0.75 (dead code) | Actual threshold = 0.70. auto_promote fires. | Refuted |
| "5x acceleration" (total speedup) | Parameter is 5.0, cumulative speedup is 16×. | Overclaim |
| learned_decay is dead code | Wired into reinforce() at synapses.py:600-607. | Refuted |
| Denominator bias exists | Fixed — uses len(fixture_queries). | Refuted |
| Fail-open fitness wipe | Guarded — doesn't persist 0.0. | Refuted |
| NaN leak via min() | Uses _clamp, all axes safe. | Refuted |
Reference Implementation
- Language: Python 3.10+ (stdlib-only)
- Repo: https://github.com/dfrostar/neuralmind
- Commit:
3fe5a61(2026-07-26) - Key files:
- neuralmind/context_selector.py (993 lines)
- neuralmind/synapses.py (1,593 lines)
- neuralmind/team_memory.py (366 lines)
- neuralmind/hooks.py (544 lines)
- neuralmind/mcp_server.py (879 lines)
- neuralmind/compressors.py
- neuralmind/learned_decay.py (139 lines, now wired)
- neuralmind/fitness.py (all 3 axes _clamp-safe)
- neuralmind/tuner.py (denominator-safe, incumbent-guarded)