Metadata-Version: 2.4
Name: neruva-mcp
Version: 0.21.0
Summary: MCP server for Neruva agent memory + reasoning substrate. v0.21 adds code_kg_callees/callers/class_of/module_of/imports for sub-ms structural code queries on KGs built locally via neruva-record-code-index. Removes agent_postmortem_prompt (transport stall). Plus Records, 5-engine KG, federated agent_remember/recall/context, Pearl do-operator, HD analogy, CBR, ToM, counterfactual rollouts, schema lifting, EFE, continual K-gram, rule induction, replay, .neruva V3. MCP drop-in for Claude Code, Cursor, Codex.
Author-email: Clouthier Simulation Labs <info@neruva.io>
License: MIT
Project-URL: Homepage, https://neruva.io/claude-code/
Project-URL: Documentation, https://neruva.io/docs/
Project-URL: Source, https://github.com/CloutSimLabs/neruva
Keywords: mcp,model-context-protocol,neruva,agent-memory,agent-context,agentic-ai,knowledge-graph,causal-inference,pearl-do-operator,graph-rag,rag,vector-database,langchain,langgraph,crewai,claude-code,ai,llm
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx>=0.27
Dynamic: license-file

# neruva-mcp

MCP server for [Neruva](https://neruva.io) — 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](https://neruva.io/claude-code) for the 30-second install + first-queries to try.

## What's new in 0.21.0 — code-graph MCP tools + postmortem removed

- **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`. Thin wrappers over
  `hd_kg_query` with "Call this when..." routing nudges.
- **`agent_postmortem_prompt` tool removed.** Paired with the
  `neruva-record` v0.10.1 strip of `NERUVA_AUTO_POSTMORTEM` — the
  synchronous fetch in the failure hook was stalling sessions under
  transport hiccups. `/v1/agent/postmortem_prompt` substrate endpoint
  now returns 410 Gone.
- **Tool-description routing nudges.** All 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.

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

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

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

```bash
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
```bash
claude mcp add-json neruva '{"command":"npx","args":["-y","@neruva/mcp@latest"],"env":{"NERUVA_API_KEY":"..."}}'
```

### Cursor (`~/.cursor/mcp.json`)
```json
{
  "mcpServers": {
    "neruva": {
      "command": "npx",
      "args": ["-y", "@neruva/mcp@latest"],
      "env": { "NERUVA_API_KEY": "..." }
    }
  }
}
```

### Codex (`~/.codex/config.toml`)
```toml
[mcp_servers.neruva]
command = "npx"
args = ["-y", "@neruva/mcp@latest"]
env = { NERUVA_API_KEY = "..." }
```

### Gemini CLI (`~/.gemini/settings.json`)
```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

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

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