neruva-mcp 0.13.0

Model Context Protocol server for Neruva — typed agentic memory (Records: decisions, mistakes, llm_turns, tool_calls), knowledge graph with 4 engines (Hadamard / OPB / multi-shard / quorum / feature-bundle) + raw-text ingest + N-hop matrix-power derive + customizable context blocks, Pearl's do-operator, HD analogy, plus self-introspection (wallet, op stats, op log, keys). Drop-in for any MCP host.

neruva-mcp

Model Context Protocol server for Neruva -- typed agentic memory (Records substrate) plus an HD-native substrate (knowledge graphs, analogy, causal do-operator). Drop into any MCP host. Python mirror of the TypeScript @neruva/mcp package; same tool surface.

What's new in 0.7.0

Four self-introspection tools so an agent can answer "what did I just do, and what's it costing me?" without leaving the loop:

Tool	What it does
neruva_wallet_status	Current credit / usage / plan for the active key
neruva_op_stats	Per-tool call counts + latency stats for this agent
neruva_keys_list	List API keys visible to the active account
neruva_op_log	Recent op log entries (tool, latency, ts) for audit

These mirror the substrate's own audit surface back to the agent -- the same data the dashboard sees, available inline at sub-ms.

Install

The killer path -- one shot, every Claude Code session is auto-recorded:

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

That installs the Claude Code hook + the Records SDK; every session you run after that lands in your Neruva account, secrets-redacted, queryable later.

For the MCP server itself:

pip install neruva-mcp
export NERUVA_API_KEY=...        # from https://app.neruva.io

Or zero-install via uvx:

uvx neruva-mcp@latest

Wire into a client

Claude Code

claude mcp add neruva --scope user \
  --env NERUVA_API_KEY=nv_... \
  -- uvx neruva-mcp@latest

Cursor (~/.cursor/mcp.json)

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

Codex (~/.codex/config.toml)

[mcp_servers.neruva]
command = "uvx"
args = ["neruva-mcp@latest"]
env = { NERUVA_API_KEY = "..." }

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

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

Or run directly:

NERUVA_API_KEY=YOUR_KEY neruva-mcp

The 4-layer substrate

• Records = typed agentic memory. Every event has kind, tags[], ts, meta, auto-embedded at D=1024. Filter on any dimension. GDPR-native via records_forget. Portable as .neruva.
• KG = mutable structured state. Sharded (K=16 by default), deterministic from a seed, batched cleanup. Deploy state, project status, refactor tracking.
• Causal = "if I do X, what happens?" -- Pearl's do-operator as native HD substitution.
• Analogy = a:b::c:? pattern transfer in HD feature space, sub-ms, n_feat up to 20.

A 5th legacy layer -- Memory Index -- exposes raw vector upsert/query at /v1/indexes/* for users migrating from generic vector stores. Kept for back-compat; new agents should reach for Records first.

Cost wedge

~3,125x cheaper per recall than context-stuffing with Opus 4.7 (records_query at $2/M input vs context-stuff at ~$0.00625/turn). See /benchmarks on the site for the measured run.

Tools

Records -- typed agentic memory (flagship)

Tool	What it does
records_append	Append a typed event (kind, tags, ts, meta, text) -- auto-embedded
records_query	Filter on any combo of kind / tags / time range / semantic similarity
records_fetch	Fetch records by id
records_forget	GDPR-native delete (tombstoned, excluded from query + export)
records_export	Export to portable .neruva container -- your data is yours
records_import	Import a .neruva blob
records_compact	Compact tombstones, rebuild index

HD-native substrate

Tool	What it does
hd_kg_add_fact	Add (subject, relation, object) to a KG (sharded K=16)
hd_kg_query	Query KG for object of (subject, relation)
hd_kg_delete_fact	Cancel a previously-added fact (mutable state)
hd_analogy	Four-term analogy in HD space (n_feat up to 20)
hd_causal_add_worlds	Add worlds to a structural causal model
hd_causal_query	Observational or interventional (Pearl do-operator)

Self-introspection (new in 0.7.0)

Tool	What it does
neruva_wallet_status	Current credit / usage / plan
neruva_op_stats	Per-tool call counts + latency stats
neruva_keys_list	API keys visible to the active account
neruva_op_log	Recent op log entries for audit

Memory index -- vector upsert/query (legacy compat surface)

Tool	What it does
memory_embed	Encode texts to D=1024 vectors via the server-side static-MRL encoder. No BYOE.
memory_upsert_text	Embed and upsert text in one call
memory_query_text	Embed a text query and search in one call
memory_create_index	Create a vector index
memory_list_indexes	List your indexes
memory_describe_index	Describe one index
memory_stats	Per-namespace vector counts
memory_upsert	Insert/update raw vectors
memory_query	Cosine top-K search (raw vectors)
memory_fetch	Fetch vectors by id
memory_update	In-place edit values/metadata
memory_delete	Delete by id
memory_export	Portable .nmm export
memory_import	.nmm import
memory_bind_role	Bind a role atom for compound queries
memory_read_roles	Recover bound role atoms

Auto-record (opt-in, 0.4.0+)

Set NERUVA_AUTO_RECORD=<index>/<namespace> and every tool call the agent makes is auto-upserted into that namespace as a side-effect.

# single-agent
NERUVA_AUTO_RECORD=brain/main

# multi-agent: one namespace per agent
NERUVA_AUTO_RECORD=brain/support-bot
NERUVA_AUTO_RECORD=brain/research-agent

Each record carries metadata {kind: "tool_call", tool, latency_ms, ts}. memory_* and records_* reads are excluded to prevent loops. Fire-and-forget: never blocks or breaks the call. ~1.2 KB per tool call.

For Claude Code specifically, prefer the one-shot installer:

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

Env

Variable	Default
NERUVA_API_KEY	required
NERUVA_URL	https://api.neruva.io
NERUVA_AUTO_RECORD	optional <index>/<namespace> to enable auto-record

License

MIT -- Clouthier Simulation Labs.