@neruva/mcp

MCP server for Neruva — memory + reasoning substrate for AI agents. Knowledge graph (5 engines), Pearl do-operator, HD analogy, episodic CBR, deterministic replay. Drop into Claude Code / Cursor / Codex / Gemini CLI in one line.

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

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.
• Wrapper cleanup: 22 dead-wedge tools removed (legacy memory_*, agent_postmortem, hd_kg_add_fact singular). The remaining ~65 tools all earn their slot.

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.

| # | Capability | MCP tool(s) | Frontier LLM equivalent | |---:|---|---|---| | 1 | Vector retrieval (OPB pages + spectral routing) | records_query(engine="opb") | Pinecone/Zep (Level 1 only) | | 2 | KG + Pearl do-operator + HD analogy + CBR | hd_kg_* · agent_causal_query · hd_analogy · hd_cbr_* | nobody | | 3 | Theory of Mind (nested belief) | agent_model_belief_add · agent_model_belief | hallucinates at depth | | 4 | Counterfactual rollouts ("what if k → a'?") | agent_counterfactual_rollout | confabulates | | 5 | Schema lifting (analogical pattern matching) | agent_extract_schema | needs fine-tuning | | 6 | Active Inference planning (Friston EFE) | agent_register_action · agent_plan_efe | not a primitive | | 7 | Few-shot rule induction | agent_induce_rule | fine-tune (many examples) | | 8 | Persistent rule storage | agent_persist_rule · agent_recall_rule | re-feed demos every recall | | 9 | Continual learning, zero forgetting | agent_continual_train · agent_continual_predict | catastrophic forgetting | | + | Hierarchical chunking (recursive L^K decode) | agent_hierarchical_add · agent_hierarchical_decode | not a primitive |

~90 tools across Records, KG, Causal, Analogy, CBR, Blend, Vector memory, 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": "..." } } } }

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 5 engines, sub-ms cosine retrieval, matrix-power N-hop derive. Causal = Pearl's do-operator (observation vs intervention arithmetically distinct). Analogy = a:b::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

| | Vector DB | Zep | Neruva | |---|---|---|---| | KG engines | 0 | 1 | 5 | | Causal queries (Pearl do-operator) | ❌ | ❌ | ✅ | | Provable replay (deterministic snapshot/restore) | ❌ | ❌ | ✅ | | Anomaly detection (quorum disagreement) | ❌ | ❌ | ✅ | | Federated context (records+KG one call) | ❌ | partial | ✅ | | Portable container | ❌ | ❌ | ✅ .neruva | | p95 latency | varies | varies | <100ms | | Cost per recall vs context-stuffing | varies | varies | dramatically lower |

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.

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