@neruva/mcp

MCP server for Neruva — reliability infrastructure for production AI agents. One MCP install. Your agent stops forgetting, stops drifting, stops repeating mistakes — every failure replayable bit-for-bit.

Backed by a 6-engine knowledge graph (incl. qbound for document-vs-LLM-prior conflict resolution), counterfactual queries, HD analogy, episodic CBR, deterministic snapshot/restore.

Drop into Claude Code / Cursor / Codex / Gemini CLI / Goose in one line. Free tier, no card.

For Claude Code users: see neruva.io/claude-code for the 30-second install + first-queries to try.

Benchmarks

Full breakdown: neruva.io/benchmarks. The only memory stack hitting world-class scores on memory, reasoning, AND audit determinism — simultaneously.

What's new in 0.27.0 — qbound engine for conflict resolution

New 6th KG engine: qbound (question-conditioned binding) for workloads where document-stated facts must override the LLM's training-time priors.

Use it when your agent reads CRM records, compliance docs, or internal policies that contradict what an LLM "knows" from pretraining:

await client.callTool({
  name: "hd_kg_add_facts",
  arguments: {
    kg: "compliance",
    engine: "qbound",  // <-- new
    facts: [
      { subject: "PolicyX", relation: "current_version", object: "v2024.3" },
      // ...
    ],
  },
});

Drop-in: same shard format as opb, same query surface. Backward-compat with all existing tools.

What's new in 0.26.0 — 7-layer federated recall

agent_recall_full lands. One question, seven buckets, returned in parallel (~150ms p95):

• records — semantic embedding search (existing)
• kg — entity-overlap + cosine across knowledge graphs (existing)
• rules — HD signature cosine across stored rule libraries (new)
• cbr — structural-distance nearest-neighbour across case episode stores (new)
• scm — variable-name match across causal models, ready for hd_causal_query follow-up (new)
• tom — name-resolved chain lookup across theory-of-mind belief stores (new)
• continual — predictive next-token recall against trained K-gram learners (new)

Records + KG light up automatically for any tenant. The other five layers light up when you pass opt-in text labels at ingest time (chain_names / prop_name on agent_model_belief_add, token_names on agent_continual_train, var_names on hd_causal_add_worlds, axis_vocab_names on hd_cbr_add_episodes). Layers without populated registries return a hint field telling the caller the exact param to pass next time — graceful degradation, not silent emptiness.

Per-layer prefix scoping (rules_prefix, cbr_prefix, scm_prefix, tom_prefix, continual_prefix, kg_prefix) bounds wall time on tenants with many resources of a single kind.

Use when one question could touch multiple reasoning artifacts — "what do I know about X?" across records + KG facts + learned rules + similar past cases + causal models + agent beliefs + trained sequences. Existing agent_recall (records + KG only) remains unchanged.

What's new in 0.25.0 — qa_optimized + recency_first graduated

The LongMemEval 93.3% recipe lifted into the substrate. agent_recall now accepts two opt-in flags (both default off, backwards compatible):

• mode="qa_optimized" — 3× over-fetches the candidate pool and BM25-RRF-fuses (k=60) over the text. Lifts records whose text contains specific entity tokens (brand names, amounts, dates, IDs) that pure semantic embedding under-weights. Worth ~+20pp on memory-QA benchmarks.
• recency_first=true — re-sorts returned records by ts desc after ranking. Use for knowledge-update questions where the most recent statement wins over older contradictory ones.

Pair them for the strongest memory-QA recipe. Auto-router in neruva-record 0.19+ suggests both automatically when the intent classifier hits recall_extended.

What's new in 0.24.0 — Code-graph bare-name resolution

code_kg_module_of and code_kg_class_of now accept short identifiers like bind (no module prefix). When the substrate sees an unqualified name, it falls back to a 1-hop called_by lookup to find the likely qualified target. Drops the friction of remembering full dotted paths inside Claude Code.

What's new in 0.23.0 — Native hook binary (sub-100ms cache-hit latency)

We benchmarked Neruva against the 2026 agent-memory field and made the hook faster than Mem0 without giving up any of the capability surface.

What changed: @neruva/mcp 0.23 bundles neruva-record-hook as a native Rust binary (~145-340 KB per platform; all 6 of Win/Mac/Linux × amd64/arm64). The hook talks to a long-lived Python daemon over TCP localhost. The daemon holds a warm httpx connection pool to api.neruva.io plus an in-memory TTL cache so consecutive prompt/tool-call hooks within a turn skip the network entirely.

Install:

# 1. MCP server. The -p ... neruva-mcp form is REQUIRED because 0.23+
#    ships two bins (neruva-mcp + neruva-record-hook) and npx can't
#    auto-pick when a package exposes more than one.
npx -y -p @neruva/mcp@latest neruva-mcp

# 2. The Python daemon comes from neruva-record (pip)
pip install neruva-record
neruva-record install     # writes ~/.claude/settings.json hooks

# That's it. Restart Claude Code.

Your ~/.claude.json mcpServers entry should be:

{
  "neruva": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "-p", "@neruva/mcp@latest", "neruva-mcp"],
    "env": { "NERUVA_API_KEY": "nv_..." }
  }
}

On install, @neruva/mcp exposes neruva-record-hook on your PATH (a tiny Node wrapper that exec's the platform-native binary). neruva-record install wires it into ~/.claude/settings.json for UserPromptSubmit + PostToolUse. The daemon auto-spawns on first SessionStart and stays warm for 30 minutes after the last hook fire (NERUVA_DAEMON_IDLE_S override).

For max speed, you can skip the Node wrapper entirely by pointing settings.json directly at the bundled binary path:

{
  "hooks": {
    "UserPromptSubmit": [{
      "hooks": [{
        "type": "command",
        "command": "<npm-root>/@neruva/mcp/binaries/neruva-record-hook-<plat>-<arch>"
      }]
    }]
  }
}

Removes the ~80ms Node startup. Total per-hook overhead drops to ~80ms p95 on cache hit, ~200ms on cache miss. The daemon's TTL cache (default 30s, override NERUVA_DAEMON_CACHE_TTL_S) means tool-heavy turns reuse the recall/turns fetches at ~$0/call.

Cost impact: NEGATIVE. TTL cache reduces Cloud Run requests by ~50-80% during tool-heavy turns. Stop-time prefetch is net-zero (shifts a request from hot path to idle path; result is cached and reused). No new infra, no new services.

What's new in 0.22.0 — Auto-pilot surface (the moat)

Two new tools complete the auto-pilot that makes the substrate use itself. The agent automatically routes user intents to the right cognitive primitive AND self-curates memory across sessions, without the user ever telling it which Neruva tool to call.

• agent_route_intent_prompt — returns the canonical 18-pattern intent classifier (counterfactual / analogy / theory-of-mind / rule induction / causal / planning / recall / comparison / state / composition / decision / mistake, plus 6 code-graph navigation intents). Pair with NERUVA_AUTO_ROUTE=1 in neruva-record for hands-free routing on every user prompt.
• agent_reflect_prompt — returns the canonical reflection prompt that extracts durable decisions / facts / mistakes / open questions from recent turns. Pair with NERUVA_AUTO_REFLECT=1 in neruva-record for hands-free self-curation. Next session boots with curated context, not raw transcript.

Both endpoints are pattern-C: substrate emits a prompt, caller LLM runs it in its normal turn, structured result pushed back via existing tools. Substrate stays $0/call. Combined with the existing hd_kg_extraction_prompt (Layer 1 — auto-extract on records_ingest), the three layers form a complete auto-pilot:

See neruva-record v0.11+ for the SDK that wires these into Claude Code's hook system automatically.

What's new in 0.21.0 — code-graph MCP tools

• 5 new code_kg_* tools for sub-ms structural code queries against KGs built locally via neruva-record-code-index: code_kg_callees, code_kg_callers, code_kg_class_of, code_kg_module_of, code_kg_imports. Each is a thin wrapper over hd_kg_query with "Call this when..." routing nudges.
• Tool-description routing nudges. All 17 high-leverage tools (records_*, agent_recall/context/remember, hd_kg_query, hd_analogy, hd_causal_query, agent_counterfactual_rollout, agent_model_belief(_add), agent_register_action, agent_plan_efe, agent_induce_rule, agent_extract_schema, agent_hierarchical_decode) lead with "Call this when..." so LLMs route into the right substrate primitive without explicit prompting.
• extract="managed" on agent_remember removed. Pairs with the substrate's "no server-side LLM calls" architecture decision: use extract="byo" with caller-side triple extraction via hd_kg_extraction_prompt.

What's new in 0.18.3 — depth-unlimited theory of mind + 125× faster cleanup

• Theory of mind is now depth-unlimited (v0.5.4 substrate fix). Position-tagged at every chain index via non-commutative permutation binding. Inner-position swaps correctly reject; recursive self- reference (same agent at multiple chain positions) works natively.
• Cleanup acceleration via FAISS-binary popcount. OPB query stage 2 now uses SIMD popcount over sign-quantized atoms with deterministic float32 cosine rerank. Substantially faster on warm queries; replay bit-identical.
• 551× compression on stored OPB pages (rank-12 SVD). Persistence blobs that were >100 MB now fit in under 1 MB at perfect recall on round-trip.

The 9-level cognitive ladder — no LLM vendor ships rows 3-9

The substrate now exposes the full 9-level cognitive ladder. Every primitive runs sub-100ms, deterministic from seed, behind one MCP install.

~80 tools across Records, KG, Causal, Analogy, CBR, Blend, federated agent_*, the 9 cognitive primitives above, self-introspection.

Why this is unique

Every primitive in rows 3-9 is a graduated, production-shipped engine. No published memory vendor offers more than rows 1-2. Substrate-augmented small LLMs can match frontier-class agentic capabilities at a fraction of the cost per recall.

Install

# In Claude Code (any directory, user scope):
claude mcp add-json neruva '{"command":"npx","args":["-y","@neruva/mcp@latest"],"env":{"NERUVA_API_KEY":"nv_..."}}'

Or one-line install via npx for any MCP host:

npx -y @neruva/mcp@latest    # one-off
npm i -g @neruva/mcp         # then `neruva-mcp`

Get an API key at https://app.neruva.io (free tier, no credit card).

Wire into a host

Claude Code

claude mcp add-json neruva '{"command":"npx","args":["-y","@neruva/mcp@latest"],"env":{"NERUVA_API_KEY":"..."}}'

Cursor (~/.cursor/mcp.json)

{
  "mcpServers": {
    "neruva": {
      "command": "npx",
      "args": ["-y", "@neruva/mcp@latest"],
      "env": { "NERUVA_API_KEY": "..." }
    }
  }
}

Codex (~/.codex/config.toml)

[mcp_servers.neruva]
command = "npx"
args = ["-y", "@neruva/mcp@latest"]
env = { NERUVA_API_KEY = "..." }

Gemini CLI (~/.gemini/settings.json)

{ "mcpServers": { "neruva": { "command": "npx", "args": ["-y", "@neruva/mcp@latest"], "env": { "NERUVA_API_KEY": "..." } } } }

Goose (~/.config/goose/config.yaml)

extensions:
  neruva:
    type: stdio
    cmd: npx
    args: ["-y", "@neruva/mcp@latest"]
    env:
      NERUVA_API_KEY: nv_...

For Goose auto-pilot (pattern-C route / reflect / extract via your LLM): pip install neruva-goose.

The substrate, in one paragraph

Five layers, one API. Records = typed agentic events (decisions, mistakes, tool_calls, llm_turns; auto-embedded at D=1024). Knowledge Graph = mutable structured state across 6 engines (hadamard, opb, qbound, multishard, quorum, feature_bundle), sub-ms cosine retrieval, matrix-power N-hop derive. Causal = Pearl's do-operator (observation vs intervention arithmetically distinct). Analogy = a🅱️:c:? in HD feature space. Concept Blending = provenance-preserving merge of multiple memories. CBR = factored episode store. The new federated agent_* layer (agent_remember / agent_recall / agent_context) routes across all substrates so a single call handles "where does X store, and how do I get it back?"

Deterministic from a seed. Replayable bit-exactly. Portable as .neruva containers — your data is yours.

Three-line LangChain integration

# pip install neruva-langchain
from neruva_langchain import NeruvaChatMessageHistory
history = NeruvaChatMessageHistory(namespace="user_alice")
# wire into any chain that takes BaseChatMessageHistory

Same pattern: neruva-langgraph (BaseCheckpointSaver + BaseStore), neruva-crewai (Storage interface + 3 memory flavors).

Auto-record for Claude Code

pip install neruva-record && neruva-record-install

Every Claude Code session lands in your Neruva account: tool calls, chat turns, secrets-redacted client-side, queryable across sessions.

Why use this over a vector DB or Zep

KG engine selector

Pick engine on first hd_kg_add_facts call to a new KG:

Auth

Set NERUVA_API_KEY in env. NERUVA_URL defaults to https://api.neruva.io.

Optional: NERUVA_AUTO_RECORD=namespace[:ttl_days] — every tool call this agent makes auto-records into the named records namespace. Fire-and-forget, never blocks or breaks the call.

Tool tiers (v0.28+)

NERUVA_MCP_TIER controls how many tools the agent sees:

• full (default) — all ~79 tools: records, federated recall, 6 KG engines, causal, analogy, CBR, belief tracking, rule induction, continual/hierarchical memory, code-graph, snapshot/replay.
• basic — the 28 high-traffic core tools (records, agent_recall/agent_context, KG basics, hd_causal_*, code_kg_*, snapshot/restore, op stats). Smaller tool list = less prompt overhead + sharper tool selection for agents that don't need the research-grade primitives.

The filter only changes what tools/list advertises — every tool stays callable by name, so setting basic never breaks an existing caller. Flip it with NERUVA_MCP_TIER=basic in the MCP server's env.

Update flow

The startup banner prints when a newer version is available:

[neruva-mcp] update available: you have 0.16.0, latest is 0.16.1.

If registered with @neruva/mcp@latest, a Claude Code restart auto-updates.

License

MIT