neuralmind v3.8.0 # x-release-please-versionA

Immutable. This exact content is served forever at /api/v1/blob/60cec5fae41a9e31.

---
name: neuralmind
description: Answer questions about a code repository in ~800 tokens instead of loading 50,000+ tokens of raw source. Use whenever the user asks how something works, where something is defined, who calls what, or to explore an unfamiliar file. Provides progressive context disclosure (L0 identity → L1 architecture → L2 relevant clusters → L3 semantic search) and a learned synapse graph for usage-based recall. Also supports unified content+code search for book-like projects.
version: 3.8.0 # x-release-please-version
author: dfrostar
license: MIT
tags:
  - code-intelligence
  - retrieval
  - context-compression
  - mcp
  - unified-search
triggers:
  - how does
  - where is
  - find function
  - find class
  - explain module
  - explain this file
  - trace callers
  - who calls
  - what calls
  - architecture overview
  - codebase question
  - unfamiliar repo
  - onboard to repo
  - book search
  - unified search
  - content search
  - chapter search
allowed_tools:
  - neuralmind_wakeup
  - neuralmind_query
  - neuralmind_search
  - neuralmind_skeleton
  - neuralmind_synaptic_neighbors
  - neuralmind_synapse_stats
  - neuralmind_synapse_decay
  - neuralmind_export_synapse_memory
  - neuralmind_build
  - neuralmind_stats
  - neuralmind_benchmark
runtime:
  binaries:
    - neuralmind
    - neuralmind-mcp
  install: pip install neuralmind
metadata:
  complexity: low
  category: developer-tools
---

# 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 12-50× 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. Tell the user to run:

```
pip install neuralmind   # if missing
neuralmind build .
```

…and stop. Do not fabricate answers when the index is missing. (Projects
using the optional graphify backend refresh its richer graph first:
`graphify update . && neuralmind build .`)

## 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
```

## Unified content+code search (v3.8+)

For book-like projects (markdown chapters + engine code), NeuralMind can
search both content and code scopes simultaneously and merge results.

**Build a book project:**
```
neuralmind build --content-type=book --force
```
Auto-detects book-like repos (markdown:code ratio > 3:1, no `src/` or
`lib/` at root) and routes indexing into separate scopes.

**Query both scopes:**
```
neuralmind query . "how does authentication work?" --mode=unified
```

Returns results labeled `[content]` (chapters) and `[code]` (implementation),
ranked by relevance.

**Filter by chapter:**
```
neuralmind query . "WANK worm" --mode=unified --chapter="Chapter 1"
```

**Bias toward one scope:**
```
neuralmind query . "explain the architecture" --mode=unified --scope-bias=content
neuralmind query . "show me the implementation" --mode=unified --scope-bias=code
```

`--scope-bias=balanced` (default) returns equal weighting. `content` boosts
chapter results 20%; `code` boosts implementation results 20%.

## 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.

```jsonc
// 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:

```jsonc
[
  {"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*.

## Host notes (Hermes-Agent, OpenClaw, Agent Zero)

The decision tree above is identical in every host. What differs is how
NeuralMind reaches you, and what to do when it hasn't.

**Hermes-Agent.** Hermes has a built-in MCP client and discovers servers at
startup, so the `neuralmind_*` tools arrive as first-class tools alongside
`terminal` and `read_file` — no bridge CLI. If they are absent, the server
isn't registered: the user runs `hermes mcp add` (or edits
`~/.hermes/config.yaml`) and confirms with `hermes mcp test neuralmind`.
This file also installs as a Hermes skill *without* the MCP server —
`hermes skills install dfrostar/neuralmind/skills/neuralmind` — in which
case drive the `neuralmind` CLI through `terminal` instead. See
*Failure modes*.

**OpenClaw.** Registered once with:

```bash
openclaw mcp set neuralmind '{"command":"neuralmind-mcp","args":[]}'
```

`openclaw mcp show neuralmind` confirms the connection.

**Agent Zero.** Reached through its MCP configuration, pointed at the same
`neuralmind-mcp` command. The `plugin.yaml` in this repo's root is the
plugin-index manifest for the registry listing — it is not runtime config,
so its presence tells you nothing about whether the server is wired up.
Check for the tools.

**Pass a real path, not `.`, when the host runs the server detached.**
`neuralmind-mcp` takes no launch arguments — every tool resolves its own
`project_path` argument, relative to whatever working directory the *server*
process happens to have. Under Claude Code and Cursor that is the project, so
`project_path="."` above is correct. Under a host that starts the server as a
long-lived background process — Hermes, OpenClaw, Agent Zero — it is not,
and the server now says so instead of failing silently: `neuralmind_stats`
returns `built: false` with a `hint` naming the directory the relative path
actually resolved to, and `wakeup` / `query` / `search` return that hint as
an explicit error rather than auto-building an index of the wrong directory.
When you see it, retry the same call with the absolute project path — do not
tell the user to build.

**One brain, several hosts.** Every host pointed at the same project path
reinforces the same `.neuralmind/synapses.db`. Associations the user's other
agents built are visible to you, and yours to them — so
`neuralmind_synaptic_neighbors` can legitimately surface code this session
never touched. That is the feature, not a stale index. Don't rebuild to
"clear" it.

## 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.