Use Case: Claude Code User

What you’re solving for

You use Claude Code daily. Your context fills up fast, Read pulls in too much source, and the bill is adding up. You want retrieval-side optimization — less source pulled in per question — and a codebase memory that carries over between sessions.

Setup (one time)

pip install neuralmind
cd your-project
neuralmind build .             # builds the knowledge graph + vector index
neuralmind install-hooks .     # session memory, prompt recall, stale-decision guard
neuralmind init-hook .         # auto-rebuild on every git commit

Daily workflow

At session start, have Claude Code call:

neuralmind_wakeup(project_path=".")

That gives the agent ~400 tokens of architecture/cluster context instead of 50K tokens of file reads.

With the hooks installed, a fresh session, or one after /clear, also opens with a short recap of the previous session in the project: its first prompt, its last three, and the files it edited (v4.8.0+). It’s labelled as context, not instructions; ask “where were we?” when you want to carry on. See Pick up where you left off.

A prompt about the code also arrives with a short block naming the files it matches, with their symbols and line numbers, other files the synapse graph links to them (mostly code), and matching docs (v4.11.0+), as long as its best match clears the similarity cutoff (NEURALMIND_RECALL_MIN_SIMILARITY, default 0.35). That starts with the first prompt after neuralmind build, so it helps most in a repository you’ve just cloned. In a fresh index of Click, “which files in this repo handle parsing command-line options?” arrives with:

## NeuralMind associative recall

Code matching this prompt:
- src/click/core.py: make_parser() L1256, Parameter L2241
- src/click/parser.py: _OptionParser L224, parse_args() L298
- examples/repo/repo.py: cli() L44
- src/click/_termui_impl.py: _less_uses_raw_mode() L520
Docs: docs/parameters.md, docs/arguments.md, docs/complex.md

The links start out structural (calls, imports, inheritance) and come to reflect what you edit together. A prompt whose best match scores below that cutoff, like “yes”, gets nothing; it’s a similarity threshold, not a topic check, so an off-topic prompt can still clear it (1 of 15 did in the measurement). On fresh indexes the block named a file that answers the prompt for 14 of 14 Click prompts and 14 of 15 prompts about NeuralMind’s own code (measured); whether that makes the agent’s answers better isn’t measured.

When asking a code question, prefer neuralmind_query over raw exploration:

neuralmind_query(project_path=".", question="How does authentication flow through the middleware?")

Returns ~800–1,100 tokens with the right clusters and search hits.

Before opening a file, use neuralmind_skeleton:

neuralmind_skeleton(project_path=".", file_path="src/auth/handlers.py")

Returns the function list, rationales, call graph, and cross-file edges. Across the compression benchmark’s 136 files, replacing each whole-file Read with that outline would cut 86.7% of the tokens (files under 1,500 characters stay whole), but the outline repeats none of the source lines — use it to orient, then Read what you’re about to edit.

Everything else (Read, Bash, Grep you don’t route through NeuralMind) reaches Claude exactly as the tool returned it. NeuralMind doesn’t compress tool output by default: its hooks used to, and measured, that added tokens, so they now inject nothing. The one exception is opt-in and narrow: trimming install logs.

Trim noisy install logs (opt-in, v4.10.0+)

An agent setting up a project runs pip install -r requirements.txt or pip install -e ".[dev]" and gets dozens of Collecting, Downloading and Requirement already satisfied lines, when what it needs is the Successfully installed … line and any warnings. Turn on the replacement in the project’s .claude/settings.json:

{
  "env": { "NEURALMIND_BASH_REPLACE": "1" }
}

What Claude then sees for a fresh install, instead of 77 lines:

[neuralmind: 74 progress lines elided: Collecting ×24, Downloading ×48, progress bar ×2]
Installing collected packages: urllib3, typing-extensions, pygments, …
Successfully installed Jinja2-3.1.6 MarkupSafe-3.0.4 … requests-2.32.3 rich-13.9.4 …
[neuralmind: pip install progress lines elided where marked; every other line is verbatim. Full output: /path/to/project/.neuralmind/bash_outputs/33026abbedf96248.txt]

• Only pip install and neuralmind build, run on their own (cd, source .venv/bin/activate or variable assignments before them are fine). A pipe, a redirect or a second command (pip install x && pytest) leaves the output whole, and so does every other command: test runs, diffs, file dumps and search results are never touched.
• Only progress lines go. Every other line is passed through verbatim, and a line that mentions an error, warning, failure or deprecation is never removed. A failed install fires PostToolUseFailure, which no hook can shrink, so a failure reaches Claude exactly as Claude Code delivers it.
• The rest is one Read away. The full output (credentials redacted) is kept in its own file, and the result ends with its path. Asked about a line that was elided, Claude reads that file.
• Measured, gated, and small: on the compression benchmark’s five noisy logs it cuts 81.9% of the tokens (per call: mean −54.8%, from 0% for the next build log it leaves alone to −96.5%), with every must-keep line kept. CI fails the build if a replaced call keeps under 95% of them or if any other kind of output is replaced. Five commands from two tools is a small sample.

What changes for you

Predict the next file (v0.11.0+)

Once neuralmind watch has been running for a few sessions, the directional synapse layer accumulates ordered (from_file, to_file) transitions and the agent can ask:

$ neuralmind next . src/auth/handlers.py
After src/auth/handlers.py:
   45.2%  tests/test_auth.py
   28.4%  src/auth/middleware.py
   12.1%  docs/auth.md

Same data via the neuralmind_next_likely MCP tool — Claude Code can call it right after finishing edits in one file to surface the files you usually touch next, no manual prompt needed.

Let the selector tune itself (v0.26.0+, opt-in)

If you want NeuralMind to adapt how much context a query surfaces to how you actually work, set NEURALMIND_SELECTOR_AUTOTUNE=1. The SessionStart hook then runs the self-improvement tuner once per session (after the synapse decay tick): it watches the re-query rate — when you fire two same-session queries whose recalled communities overlap heavily, the first one under-disclosed and you had to come back — and nudges the L2 recall depth up (so the next query lands more in one shot) or down (so it stops spending tokens on context you didn’t use). Moves are single-step, clamped to [2, 6], and fail-open.

export NEURALMIND_SELECTOR_AUTOTUNE=1   # off by default; unset = byte-identical to before
neuralmind self-improve status .        # read-only: current depth, re-query rate, warm-up state

It’s off by default and does zero extra hot-path work when unset, so it’s safe to try and trivial to turn back off.

Understand why a retrieval answered the way it did (v0.39.0+)

Add --explain to any query call to get a structured trace of how the budget was spent:

neuralmind query . "How does authentication flow through the middleware?" --explain

Output appended after the normal context block:

  Token budget breakdown:
    L0 (identity):   42 tok
    L1 (summary):   180 tok
    L2 (communities): 410 tok  [auth, middleware, session]
    L3 (search):    268 tok    [handlers.py:authenticate, session.py:validate_token, ...]
  Synapse recall:  +3 edges injected
  Reduction ratio: 6.1×

The trace is the primary tool for diagnosing a retrieval that felt wrong or incomplete — it shows you exactly which clusters loaded and which search hits scored, so you know where to look.

Since v4.6.0 the trace also prints the query intent L3 ranked with, and how it was decided — by keywords, by the classifier, or, with the off-by-default NEURALMIND_INTENT_RULES=1, by question shape (Query intent : code (by question shape)) — and its hit list shows each hit’s label and file instead of raw node ids. If a code question comes back with docs intent, that explains docs outranking code: docs intent multiplies doc hits ×2.0 and code hits ×0.7.

Catch co-breaks before you push (v0.39.0+)

Before opening a PR, run:

neuralmind review .

NeuralMind reads git diff --name-only main, maps each changed file to its graph nodes, runs spreading activation, and surfaces the nodes most strongly associated with your changes that you haven’t touched yet — the most likely co-break candidates:

Co-break candidates for 3 changed files:
  1. src/session/store.py          (weight 0.84, 12 activations)
  2. tests/test_auth_middleware.py (weight 0.71,  8 activations)
  3. src/auth/token_validator.py   (weight 0.58,  6 activations)

Same data via the neuralmind_review MCP tool — Claude Code can call it automatically after editing a file, before a commit or push.

Flag a commit that drifts from its own patterns (v3.2.0+)

review (above) answers “what else might this change break?” It says nothing about whether the change itself fits the pattern its siblings follow. neuralmind drift closes that gap: it reads the diff, maps changed lines to graph symbols, and flags a symbol that skips an association a strong majority of its peer group shares.

neuralmind drift . --staged

## NeuralMind drift check (warning) — 1 finding(s)

- api/routes.py:67 — `delete_me_endpoint()` skips `verify_session()`, which
  3 of its 9 peers (33%) use. Confirm this is deliberate.

Warning only — the commit proceeds. Use --strict to block on drift.

Only symbols the diff actually touched are ever reported — a pre-existing outlier elsewhere in the graph never gets blamed on your commit. neuralmind init-hook . installs this as a pre-commit hook automatically (warn-only; pass --strict to init-hook to make it block instead).

Repeat reads and stale decisions (v4.6.0+)

Two things the hooks now do without being asked:

• A repeat read becomes a stub. When Claude reads a file it already read this session and nothing changed, the Read hook replaces the repeat with a two-sentence note: the earlier result is still current. If Claude needs the content again (say, after a long detour), it reads once more and gets the whole file: a stub is never followed by another stub. Compaction and /clear reset it, subagents are tracked separately, and reads under 2,000 characters always come through. Off with NEURALMIND_READ_DEDUP=0.
• Decisions retire themselves on commit. With neuralmind init-hook . installed (re-run it on an older checkout), every commit that changes a file named in a recorded decision, after that decision was recorded, marks it STALE and prints it. The next time Claude edits that file, the PreToolUse guard says which commit moved it and how to restore it if it still holds. See Keep decision memory honest across commits.

Track cumulative savings (v0.39.0+, requires NEURALMIND_MEMORY=1)

export NEURALMIND_MEMORY=1   # enables the JSONL event log (off by default)
# … work for a week …
neuralmind savings .

Shows total sessions tracked, total tokens saved, average reduction ratio, and a table of the most recent queries with individual ratios. A concrete number for the cost you’ve avoided.

Escape hatches

Want NeuralMind’s hooks switched off?

NEURALMIND_BYPASS=1 claude

Hooks inherit Claude Code’s environment, so set the variable when you start Claude Code; prefixing one command inside a session doesn’t reach them. NEURALMIND_BYPASS=1 switches off every NeuralMind hook action. You don’t need it to see raw tool output: Claude already gets exactly what Read/Bash/Grep return.

Expected savings

NeuralMind’s measured savings are on the retrieval side; it doesn’t compress tool output by default, and the opt-in install-log trimming above is measured on its own (compression benchmark). Run neuralmind benchmark . --json on your repo for your retrieval number. On the public benchmark (4 pinned repos, 40 queries), NeuralMind’s context is 51–242× smaller than pasting every source file, and it finds the gold file on all 40 queries.

Second screen: see what the agent is looking at (v0.6.0+)

Pop a separate terminal and run:

neuralmind serve .

Open the URL it prints. You now have an Obsidian-style graph view of your codebase that updates in real time as Claude works. Every time Claude calls neuralmind_query (or any other NeuralMind tool), the relevant nodes pulse on the canvas — animated radial rings, color-coded by event source. The sidebar shows a rolling log of the most recent ~80 events.

The use this unlocks is trust-gap closure:

Pin the nodes you want to keep in focus (the visible pin glyph shows pinned state at a glance), use the depth slider (1–3 hops) to see how far the agent’s retrieval reached, and use Cmd/Ctrl-K or / to jump-to-search from anywhere.

NEURALMIND_EVENT_LOG=0 disables the cross-process bridge if you prefer the in-process feed only.

← Back to use-case index · Main README · Multi-agent: share the brain across all your tools