Use Case: Multi-Agent Codebase (shared memory across tools)

What you’re solving for

You don’t use just one AI coding tool. You use Claude Code for the work you live in, Cursor when you want inline completions, OpenClaw or Hermes-Agent for one-off automations, maybe Claude Desktop for the chat-flavored questions. Each one is great at what it does. None of them learn from the others.

You want a shared memory layer underneath all of them — a single place where co-activations, file edits, and tool calls reinforce the same brain, so the smarter your Claude Code session gets, the smarter your Hermes session gets, automatically.

That’s what NeuralMind v0.6.0 unlocks. It was technically true in v0.5.x — every agent talking to the project hit the same synapses.db — but you couldn’t see it. v0.6.0 makes the union visible.

The shared substrate

Every agent that uses NeuralMind talks to the same three pieces of local state:

• graphify-out/graph.json — the call graph (created by graphify)
• graphify-out/neuralmind_db/ — the ChromaDB vector index
• <project>/.neuralmind/synapses.db — the learned synapse graph

There’s no per-agent partition. When Claude Code calls neuralmind_query, the brain reinforces the co-activated nodes. When Hermes-Agent calls the same tool an hour later in a separate process, the brain also reinforces. They’re talking to the same SQLite file.

In v0.5.x, that was an implementation detail. In v0.6.0, it’s a feature you can see.

Setup (one-time, per project)

pip install neuralmind
cd your-project
neuralmind build .

That’s the shared substrate. Now wire up every agent you use:

Claude Code:

neuralmind install-hooks .

Registers SessionStart / UserPromptSubmit / PreCompact synapse hooks, a PreToolUse stale-decision guard, and a PostToolUse Bash output cache for neuralmind last. Auto-active in every session.

Claude Desktop: Edit claude_desktop_config.json:

{
  "mcpServers": {
    "neuralmind": {
      "command": "neuralmind-mcp",
      "args": []
    }
  }
}

Cursor / Cline / Continue: Drop a .mcp.json at the project root:

{ "mcpServers": { "neuralmind": { "command": "neuralmind-mcp", "args": [] } } }

Hermes-Agent:

hermes mcp add  # or edit ~/.hermes/config.yaml
neuralmind install-hermes-plugin /path/to/project   # v4.9.0+

With the plugin, Hermes gets NeuralMind’s recall and recorded decisions on every turn, and the session recap on a session’s first turn, without calling a tool (v4.9.0+). Its edits are recorded in the same .neuralmind/ as Claude Code’s, so the recap crosses between the two. The path pins that project for every Hermes session using that Hermes home, in any directory: sessions in other repositories record their prompts there too, and put their edited files’ paths into its synapse store, from where neuralmind memory publish can carry them into the committed team-memory bundle. If you use Hermes across several projects, install without a path (or with --unpin, if you pinned one before), and the plugin follows the directory Hermes works in. That covers the terminal CLI and a standalone gateway; under Hermes Desktop, ACP editor sessions and per-session workspaces, pin a project or set NEURALMIND_PROJECT. See Hermes-Agent with code memory in every turn.

OpenClaw:

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

The launch spec carries no project path — neuralmind-mcp takes no arguments. Every tool takes its own project_path, so what points all five at the same brain is passing the same path per call, not the registration. Same MCP tools (neuralmind_wakeup, _query, _skeleton, _search, …). Same .neuralmind/synapses.db.

The new v0.6.0 superpower: see the union

neuralmind serve .

Opens http://127.0.0.1:8787/?token=… in your browser — a force-directed graph of the codebase with the learned synapse overlay. Pre-v0.6.0, that was a static snapshot.

In v0.6.0, the canvas is live. Every time any agent — Claude, Cursor, Hermes, OpenClaw — calls a NeuralMind MCP tool, the relevant nodes pulse on the canvas in real time. The sidebar feed logs the event with a timestamp.

The trick that makes this work across processes is the JSONL bridge (event_log.py, shipped in v0.6.0). Each event_bus.publish() call appends a line to <project>/.neuralmind/events.jsonl. The serve process tails that file and re-emits anything it didn’t originate. Net result: one canvas, all agents, no IPC complexity.

Opt out of the bridge with NEURALMIND_EVENT_LOG=0 (you still get the in-process feed for the agent that’s running serve itself).

A two-week walkthrough

Day 1. Set up the substrate. Wire up Claude Code + Cursor + OpenClaw. Pop neuralmind serve in a browser tab.

Day 2. You use Claude Code as usual. Every prompt that triggers a NeuralMind tool call pulses nodes on the canvas. You notice the auth cluster lighting up a lot.

Day 3. Cursor finishes a refactor across five files. Save-on-edit fires file activity events; nodes pulse. The synapse edges between those five files strengthen.

Day 4. You ask Hermes-Agent to run a one-off audit. It calls neuralmind_query against the same project. The auth cluster pulses — because that’s where Hermes started looking too. The synapse store reinforces those co-activations.

Day 7. You ask Claude Code “how does billing flow through the codebase?” Spreading activation now surfaces three files that didn’t even semantically match — they came from the Cursor refactor and the Hermes audit a few days earlier. The agent’s answer is visibly better because the brain has learned from all three tools.

Day 14. The graph view’s pulse density now visibly concentrates around the parts of the codebase you actually live in. Dead corners have decayed. Hub nodes are protected by LTP. You haven’t done anything special. You just used your tools normally.

That’s the multi-agent story. NeuralMind is the shared associative memory; the live graph is how you watch it work; the JSONL bridge is what makes it work across processes.

Which agent did what (v4.13.0+)

When Claude Code on one machine and a Hermes-Agent beside it both call the same project’s MCP server, each call’s audit event names the client that made it: the clientInfo name it sent when it connected.

neuralmind audit recent . --category security

  Timestamp                Category     Action               Actor        Client           Target
  2026-10-11T09:14:02      security     mcp_call             anonymous    claude-code      neuralmind_query
  2026-10-11T09:15:40      security     mcp_call             anonymous    hermes           neuralmind_wakeup

The full name and version are in details.client in --json and audit export. A client names itself, so this tells you who called; it isn’t an access control. For that, bind roles to OS accounts with security.identity: os.

To see whether the agents use the index at all, neuralmind metrics . counts every query and build (without the question text) with the last query’s age and a per-day table, whether they came from the CLI, an MCP tool or the daemon; prompt-time recall from the hooks is counted beside them.

What you should pin on the canvas

The graph view supports persistent pins (drag a node, it stays). v0.6.0 adds a visible pin glyph + Pin/Unpin button + Unpin-all.

Useful pins for a multi-agent workflow:

• Project entry point(s). They anchor the layout.
• The “domain core” — the few hub nodes everything else depends on.
• Whatever the agent keeps getting wrong. Pin it, ask the agent again, watch the canvas to see whether it actually hits the right node this time. If not, the replay-last-query overlay shows you which nodes it did hit. Often the fix is updating CLAUDE.md or rebuilding the index.

What it’s not

• Not a database. Synapse weights are derived state. If you blow away <project>/.neuralmind/, the brain forgets — but the next week of normal use rebuilds it. There’s no migration cost.
• Not a cross-repo brain. Each project has its own synapses.db. NeuralMind is per-project local-first by design.
• Not a network protocol. The JSONL bridge is single-machine. Two developers on different machines have two independent brains; sharing a brain across machines would require synapses.db import/export (tracked for v0.7).
• Not a queue. The bridge is best-effort. If you need guaranteed delivery between agents, that’s not what this is.

Related env vars

← Back to use-case index · Main README · Architecture: synapse layer + event bus