neuralmind

NeuralMind

You have access to a neural index of the current project. Prefer it over reading source files directly whenever you need to locate, explain, or navigate code. The index returns compact, structured context that is typically 40–70× cheaper than raw source.

The index is not a code rewriter or executor. It retrieves; you reason. Treat it like a librarian: ask narrow questions, escalate only on a miss.

Prerequisite check

Before the first call in a session, confirm the index exists:

neuralmind_stats(project_path=".")

If built: false, the project hasn't been indexed yet. The build pipeline needs both neuralmind and graphifyy (separate package, ships the graphify CLI). Tell the user to run:

pip install neuralmind graphifyy   # if either is missing
graphify update . && neuralmind build .

…and stop. Do not fabricate answers when the index is missing.

Decision tree — which tool to call

New session / first question about this repo?
  └─► neuralmind_wakeup            ~400–600 tokens (L0 + L1)

Specific code question?
  └─► neuralmind_query             ~800–1,100 tokens (L0+L1+L2+L3)
      The single most-used tool. Hand it the user's question verbatim.

About to open a file you don't know?
  └─► neuralmind_skeleton          5–15× cheaper than reading the file
      Returns functions, call graph, cross-file edges. Only fall back to
      raw Read when you need an implementation body.

Looking for a specific symbol (function, class, file)?
  └─► neuralmind_search            ranked semantic matches

Want associations the agent has learned over time?
  └─► neuralmind_synaptic_neighbors   spreading activation over the
                                      synapse graph; complements semantic
                                      search with usage-based recall

Made code changes in this session?
  └─► neuralmind_build              incremental re-embedding

Output shape (so you know what to expect)

neuralmind_wakeup and neuralmind_query return a JSON object — the markdown context lives in the context field; reduction metrics are separate fields. Don't try to parse tokens / layers out of the markdown body — read them from the envelope directly.

// neuralmind_query
{
  "context": "## Project: <name>\n<description>\nKnowledge Graph: N entities, M clusters\n\n## Architecture Overview\n### Code Clusters\n- Cluster 5 (45 entities): function — authenticate_user, …\n\n## Relevant Code Areas\n### Cluster 5 (relevance: 1.73)\n- authenticate_user (code) — auth.py\n\n## Search Results\n- AuthMiddleware (score: 0.91) — middleware.py\n",
  "tokens": 847,
  "reduction_ratio": 59.0,
  "layers": ["L0", "L1", "L2", "L3"],
  "communities_loaded": [5, 12],
  "search_hits": 7
}

neuralmind_wakeup returns the same shape minus communities_loaded and search_hits (it doesn't load L2/L3).

neuralmind_search returns a list of hits — one object per match, not a wrapped envelope:

[
  {"id": "...", "label": "authenticate_user", "file_type": "function",
   "source_file": "auth.py", "score": 0.92}
]

neuralmind_skeleton returns {"file", "skeleton", "chars", "indexed"}; the skeleton string holds functions with line numbers, an intra-file call graph, and cross-file edges — without implementation bodies. When you need a body, follow up with a normal file read.

Synapse layer (learned associations)

NeuralMind keeps a persistent weighted graph of code nodes and strengthens edges between nodes that get co-activated within the same task. This means:

• The longer the project is used, the better neuralmind_synaptic_neighbors becomes at surfacing related-but-not-semantically-similar code.
• If the project has a .neuralmind/SYNAPSE_MEMORY.md, treat it as authoritative context about which code areas tend to move together.
• The graph decays over time so stale associations fade. Do not panic if a past co-activation no longer shows up.

You do not need to manage the synapse graph manually. The exposed tools (neuralmind_synapse_stats, neuralmind_synapse_decay, neuralmind_export_synapse_memory) are for diagnostic / housekeeping use, not for routine question-answering.

Anti-patterns

• Don't call neuralmind_query with a one-word search term — use neuralmind_search for that. query expects a natural-language question.
• Don't call neuralmind_build defensively on every turn. It's only needed after code changes within the session, or when stats shows the index is stale.
• Don't loop over neuralmind_skeleton for every file in a directory. Ask one good neuralmind_query instead — the L2 layer surfaces the right files for you.
• Don't ask the user to set NEURALMIND_BYPASS=1 unless they've explicitly asked for raw tool output. The bypass disables Claude Code's PostToolUse compression of file reads / shell output — it doesn't affect retrieval through the MCP tools. The MCP query / skeleton paths stay compressed either way.

Failure modes

• Tool unavailable / connection closed: the MCP server isn't wired up for this client. Fall back to neuralmind CLI (neuralmind wakeup ., neuralmind query . "…") via the shell. Same outputs, same semantics.
• Empty results from query: the question may be too broad or the repo wasn't indexed at sufficient depth. Try neuralmind_search with the most distinctive term from the question.
• built: false: stop and tell the user. See Prerequisite check.

Environment toggles (for reference)

These are set by the user, not by you. They change retrieval behavior:

• NEURALMIND_BYPASS=1 — skip Claude Code's PostToolUse compression of tool output (raw Read / Bash / Grep results). Does not change MCP-tool behavior.
• NEURALMIND_SYNAPSE_INJECT=0 — disable prompt-time synapse recall.
• NEURALMIND_SYNAPSE_EXPORT=0 — disable markdown export of learned associations.

One-line summary

Ask NeuralMind first. Read source only when you need the body.