@neruva/mcp 0.16.0 → 0.16.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +61 -122
- package/dist/server.js +2 -2
- package/package.json +14 -4
package/README.md
CHANGED
|
@@ -1,50 +1,50 @@
|
|
|
1
1
|
# @neruva/mcp
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
MCP server for [Neruva](https://neruva.io) — agent memory substrate with knowledge graph, causal reasoning, and federated context assembly. Drop into Claude Code / Cursor / Codex / Gemini CLI in one line.
|
|
4
4
|
|
|
5
|
-
## What's new in 0.
|
|
5
|
+
## What's new in 0.16
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
| Tool | What it does |
|
|
7
|
+
| Capability | Tool(s) |
|
|
10
8
|
|---|---|
|
|
11
|
-
|
|
|
12
|
-
|
|
|
13
|
-
|
|
|
14
|
-
|
|
|
15
|
-
|
|
16
|
-
|
|
9
|
+
| Auto-managed entity extraction (Sonnet, server-side) | `agent_remember(extract="managed")` |
|
|
10
|
+
| Federated agent memory (records + KG, one call) | `agent_remember` · `agent_recall` · `agent_context` |
|
|
11
|
+
| Cross-session graph RAG | `agent_recall(namespaces=[...])` |
|
|
12
|
+
| Question-type dispatch (temporal / multi-hop / single-hop / adversarial) | `agent_context(question_type="auto")` |
|
|
13
|
+
| Pearl's do-operator on agent memory | `agent_causal_query` |
|
|
14
|
+
| Provable replay (snapshot + restore) | `agent_snapshot` · `agent_restore` |
|
|
15
|
+
| Anomaly detection on quorum KGs | `agent_check_consistency` |
|
|
16
|
+
| Fact invalidation (Zep-style temporal resolution) | `hd_kg_replace_fact` |
|
|
17
|
+
| Canonical extraction prompt (BYO-LLM) | `hd_kg_extraction_prompt` |
|
|
18
|
+
| 5 KG engines: hadamard / opb / multi-shard / quorum / feature-bundle | `hd_kg_add_fact(engine=...)` |
|
|
19
|
+
| Concept blending (provenance-preserving merge) | `hd_blend_query` |
|
|
20
|
+
| Case-based episode retrieval | `hd_cbr_*` |
|
|
21
|
+
|
|
22
|
+
**~70 tools across Records, KG, Causal, Analogy, CBR, Blend, Vector memory, federated agent_*, self-introspection.**
|
|
17
23
|
|
|
18
24
|
## Install
|
|
19
25
|
|
|
20
|
-
The killer path -- one shot, every Claude Code session is auto-recorded:
|
|
21
|
-
|
|
22
26
|
```bash
|
|
23
|
-
|
|
27
|
+
# In Claude Code (any directory, user scope):
|
|
28
|
+
claude mcp add-json neruva '{"command":"npx","args":["-y","@neruva/mcp@latest"],"env":{"NERUVA_API_KEY":"nv_..."}}'
|
|
24
29
|
```
|
|
25
30
|
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
For the MCP server itself:
|
|
31
|
+
Or one-line install via npx for any MCP host:
|
|
29
32
|
|
|
30
33
|
```bash
|
|
31
|
-
npx -y @neruva/mcp
|
|
32
|
-
#
|
|
33
|
-
npm i -g @neruva/mcp # then `neruva-mcp`
|
|
34
|
+
npx -y @neruva/mcp@latest # one-off
|
|
35
|
+
npm i -g @neruva/mcp # then `neruva-mcp`
|
|
34
36
|
```
|
|
35
37
|
|
|
36
|
-
|
|
38
|
+
Get an API key at https://app.neruva.io (free tier, no credit card).
|
|
37
39
|
|
|
38
|
-
|
|
40
|
+
## Wire into a host
|
|
39
41
|
|
|
42
|
+
### Claude Code
|
|
40
43
|
```bash
|
|
41
|
-
claude mcp add neruva
|
|
42
|
-
--env NERUVA_API_KEY=nv_... \
|
|
43
|
-
-- npx -y @neruva/mcp@latest
|
|
44
|
+
claude mcp add-json neruva '{"command":"npx","args":["-y","@neruva/mcp@latest"],"env":{"NERUVA_API_KEY":"..."}}'
|
|
44
45
|
```
|
|
45
46
|
|
|
46
47
|
### Cursor (`~/.cursor/mcp.json`)
|
|
47
|
-
|
|
48
48
|
```json
|
|
49
49
|
{
|
|
50
50
|
"mcpServers": {
|
|
@@ -58,7 +58,6 @@ claude mcp add neruva --scope user \
|
|
|
58
58
|
```
|
|
59
59
|
|
|
60
60
|
### Codex (`~/.codex/config.toml`)
|
|
61
|
-
|
|
62
61
|
```toml
|
|
63
62
|
[mcp_servers.neruva]
|
|
64
63
|
command = "npx"
|
|
@@ -67,122 +66,62 @@ env = { NERUVA_API_KEY = "..." }
|
|
|
67
66
|
```
|
|
68
67
|
|
|
69
68
|
### Gemini CLI (`~/.gemini/settings.json`)
|
|
70
|
-
|
|
71
69
|
```json
|
|
72
|
-
{
|
|
73
|
-
"mcpServers": {
|
|
74
|
-
"neruva": {
|
|
75
|
-
"command": "npx",
|
|
76
|
-
"args": ["-y", "@neruva/mcp@latest"],
|
|
77
|
-
"env": { "NERUVA_API_KEY": "..." }
|
|
78
|
-
}
|
|
79
|
-
}
|
|
80
|
-
}
|
|
70
|
+
{ "mcpServers": { "neruva": { "command": "npx", "args": ["-y", "@neruva/mcp@latest"], "env": { "NERUVA_API_KEY": "..." } } } }
|
|
81
71
|
```
|
|
82
72
|
|
|
83
|
-
## The
|
|
73
|
+
## The substrate, in one paragraph
|
|
84
74
|
|
|
85
|
-
|
|
86
|
-
- **KG** = mutable structured state. Sharded (K=16 by default), deterministic from a seed, batched cleanup. Deploy state, project status, refactor tracking.
|
|
87
|
-
- **Causal** = "if I do X, what happens?" -- Pearl's do-operator as native HD substitution.
|
|
88
|
-
- **Analogy** = `a:b::c:?` pattern transfer in HD feature space, sub-ms, n_feat up to 20.
|
|
75
|
+
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?"
|
|
89
76
|
|
|
90
|
-
|
|
77
|
+
Deterministic from a seed. Replayable bit-exactly. Portable as `.neruva` containers — your data is yours.
|
|
91
78
|
|
|
92
|
-
##
|
|
79
|
+
## Three-line LangChain integration
|
|
93
80
|
|
|
94
|
-
|
|
81
|
+
```python
|
|
82
|
+
# pip install neruva-langchain
|
|
83
|
+
from neruva_langchain import NeruvaChatMessageHistory
|
|
84
|
+
history = NeruvaChatMessageHistory(namespace="user_alice")
|
|
85
|
+
# wire into any chain that takes BaseChatMessageHistory
|
|
86
|
+
```
|
|
95
87
|
|
|
96
|
-
|
|
88
|
+
Same pattern: `neruva-langgraph` (BaseCheckpointSaver + BaseStore), `neruva-crewai` (Storage interface + 3 memory flavors).
|
|
97
89
|
|
|
98
|
-
|
|
90
|
+
## Auto-record for Claude Code
|
|
99
91
|
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
| `records_query` | Filter on any combo of kind / tags / time range / semantic similarity |
|
|
104
|
-
| `records_fetch` | Fetch records by id |
|
|
105
|
-
| `records_forget` | GDPR-native delete (tombstoned, excluded from query + export) |
|
|
106
|
-
| `records_export` | Export to portable `.neruva` container -- your data is yours |
|
|
107
|
-
| `records_import` | Import a `.neruva` blob |
|
|
108
|
-
| `records_compact` | Compact tombstones, rebuild index |
|
|
92
|
+
```bash
|
|
93
|
+
pip install neruva-record && neruva-record-install
|
|
94
|
+
```
|
|
109
95
|
|
|
110
|
-
|
|
96
|
+
Every Claude Code session lands in your Neruva account: tool calls, chat turns, secrets-redacted client-side, queryable across sessions.
|
|
111
97
|
|
|
112
|
-
|
|
113
|
-
|---|---|
|
|
114
|
-
| `hd_kg_add_fact` | Add (subject, relation, object) to a knowledge graph (sharded K=16) |
|
|
115
|
-
| `hd_kg_query` | Query a knowledge graph for the object of a (subject, relation) |
|
|
116
|
-
| `hd_kg_delete_fact` | Cancel a previously-added fact -- mutable state for refactor/deploy tracking |
|
|
117
|
-
| `hd_analogy` | Solve `a:b::c:?` analogies in HD space (n_feat up to 20) |
|
|
118
|
-
| `hd_causal_add_worlds` | Add worlds to a structural causal model |
|
|
119
|
-
| `hd_causal_query` | Observational *or* interventional (Pearl do-operator) query |
|
|
98
|
+
## Why use this over a vector DB or Zep
|
|
120
99
|
|
|
121
|
-
|
|
100
|
+
| | Vector DB | Zep | Neruva |
|
|
101
|
+
|---|---|---|---|
|
|
102
|
+
| KG engines | 0 | 1 | 5 |
|
|
103
|
+
| Causal queries (Pearl do-operator) | ❌ | ❌ | ✅ |
|
|
104
|
+
| Provable replay (deterministic snapshot/restore) | ❌ | ❌ | ✅ |
|
|
105
|
+
| Anomaly detection (quorum disagreement) | ❌ | ❌ | ✅ |
|
|
106
|
+
| Federated context (records+KG one call) | ❌ | partial | ✅ |
|
|
107
|
+
| Portable container | ❌ | ❌ | ✅ `.neruva` |
|
|
108
|
+
| p95 latency | varies | 189–200ms | <100ms |
|
|
109
|
+
| Cost per recall vs context-stuffing | varies | varies | ~3,125× cheaper |
|
|
122
110
|
|
|
123
|
-
|
|
124
|
-
|---|---|
|
|
125
|
-
| `neruva_wallet_status` | Current credit / usage / plan |
|
|
126
|
-
| `neruva_op_stats` | Per-tool call counts + latency stats |
|
|
127
|
-
| `neruva_keys_list` | API keys visible to the active account |
|
|
128
|
-
| `neruva_op_log` | Recent op log entries for audit |
|
|
111
|
+
## Auth
|
|
129
112
|
|
|
130
|
-
|
|
113
|
+
Set `NERUVA_API_KEY` in env. `NERUVA_URL` defaults to `https://api.neruva.io`.
|
|
131
114
|
|
|
132
|
-
|
|
133
|
-
|---|---|
|
|
134
|
-
| `memory_embed` | Encode texts to D=1024 vectors via the server-side static-MRL encoder. No BYOE. |
|
|
135
|
-
| `memory_upsert_text` | Embed and upsert text in one call |
|
|
136
|
-
| `memory_query_text` | Embed a text query and search in one call |
|
|
137
|
-
| `memory_create_index` | Create a vector index |
|
|
138
|
-
| `memory_list_indexes` | List all your indexes |
|
|
139
|
-
| `memory_describe_index` | Describe one index (dim, metric, host, status) |
|
|
140
|
-
| `memory_stats` | Per-namespace vector counts |
|
|
141
|
-
| `memory_upsert` | Insert/update vectors in a namespace (raw vectors) |
|
|
142
|
-
| `memory_query` | Cosine top-K search (raw vectors) |
|
|
143
|
-
| `memory_fetch` | Fetch vectors by id |
|
|
144
|
-
| `memory_update` | Update one vector's values/metadata in place |
|
|
145
|
-
| `memory_delete` | Delete vectors by id |
|
|
146
|
-
| `memory_export` | Export to portable .nmm format |
|
|
147
|
-
| `memory_import` | Import a .nmm blob |
|
|
148
|
-
| `memory_bind_role` | Bind a role atom onto a stored vector for compound queries |
|
|
149
|
-
| `memory_read_roles` | Recover the role atoms bound to a stored vector |
|
|
150
|
-
|
|
151
|
-
## Auto-record (opt-in, 0.4.0+)
|
|
152
|
-
|
|
153
|
-
Set `NERUVA_AUTO_RECORD=<index>/<namespace>` and every tool call this
|
|
154
|
-
agent makes is auto-upserted into that namespace as a side-effect.
|
|
155
|
-
Stop manually saving things; query the namespace later for "what did
|
|
156
|
-
this agent do?" Fire-and-forget, never blocks or breaks the call.
|
|
115
|
+
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.
|
|
157
116
|
|
|
158
|
-
|
|
159
|
-
# single-agent: one brain, one main namespace
|
|
160
|
-
NERUVA_AUTO_RECORD=brain/main
|
|
117
|
+
## Update flow
|
|
161
118
|
|
|
162
|
-
|
|
163
|
-
NERUVA_AUTO_RECORD=brain/support-bot
|
|
164
|
-
NERUVA_AUTO_RECORD=brain/research-agent
|
|
165
|
-
NERUVA_AUTO_RECORD=brain/orchestrator
|
|
119
|
+
The startup banner prints when a newer version is available:
|
|
166
120
|
```
|
|
167
|
-
|
|
168
|
-
Agents themselves don't need to know about it -- the recording
|
|
169
|
-
happens at the MCP wrapper layer below them. Each record gets
|
|
170
|
-
metadata `{kind: "tool_call", tool, latency_ms, ts}` so you can
|
|
171
|
-
filter at query time. `memory_*` and `records_*` reads are excluded
|
|
172
|
-
from recording to prevent loops. Storage cost is ~1.2 KB per tool
|
|
173
|
-
call (~44 MB/year for an active agent at 100 tool calls/day).
|
|
174
|
-
|
|
175
|
-
For Claude Code specifically, prefer the one-shot installer:
|
|
176
|
-
|
|
177
|
-
```bash
|
|
178
|
-
pip install neruva-record && neruva-record-install
|
|
121
|
+
[neruva-mcp] update available: you have 0.16.0, latest is 0.16.1.
|
|
179
122
|
```
|
|
180
123
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
Set `NERUVA_API_KEY` in the environment. Get a key at https://app.neruva.io.
|
|
184
|
-
|
|
185
|
-
`NERUVA_URL` is optional and defaults to `https://api.neruva.io`.
|
|
124
|
+
If registered with `@neruva/mcp@latest`, a Claude Code restart auto-updates.
|
|
186
125
|
|
|
187
126
|
## License
|
|
188
127
|
|
package/dist/server.js
CHANGED
|
@@ -92,7 +92,7 @@ if (!API_KEY) {
|
|
|
92
92
|
// or stale npm CDN never blocks the server -- we just skip the banner.
|
|
93
93
|
// Print to stderr so the MCP host (Claude Code, Cursor, etc.) shows it
|
|
94
94
|
// in the /mcp panel and the user knows an update is available.
|
|
95
|
-
const CURRENT_VERSION = "0.16.
|
|
95
|
+
const CURRENT_VERSION = "0.16.1";
|
|
96
96
|
async function _checkForUpdate() {
|
|
97
97
|
try {
|
|
98
98
|
const r = await fetch("https://registry.npmjs.org/@neruva/mcp/latest", {
|
|
@@ -1897,7 +1897,7 @@ const HANDLERS = {
|
|
|
1897
1897
|
neruva_keys_list: () => call("GET", "/v1/me/keys"),
|
|
1898
1898
|
neruva_op_log: (a) => call("GET", `/v1/me/op_log?limit=${encodeURIComponent(String(a?.limit ?? 50))}`),
|
|
1899
1899
|
};
|
|
1900
|
-
const server = new Server({ name: "neruva", version: "0.16.
|
|
1900
|
+
const server = new Server({ name: "neruva", version: "0.16.1" }, { capabilities: { tools: {} } });
|
|
1901
1901
|
server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
|
|
1902
1902
|
server.setRequestHandler(CallToolRequestSchema, async (req) => {
|
|
1903
1903
|
const name = req.params.name;
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@neruva/mcp",
|
|
3
|
-
"version": "0.16.
|
|
4
|
-
"description": "
|
|
3
|
+
"version": "0.16.1",
|
|
4
|
+
"description": "MCP server for Neruva agent memory: typed Records (decisions/mistakes/tool_calls/llm_turns, auto-embedded), 5-engine knowledge graph (Hadamard / OPB / multi-shard / quorum / feature-bundle) with managed or BYO-LLM extraction, federated agent_remember/recall/context with question-type dispatch, Pearl's do-operator causal queries, HD analogy, concept blending with provenance, CBR episode store, provable replay via agent_snapshot/restore, quorum anomaly detection, fact invalidation, portable .neruva container, sub-100ms p95. Drop-in for Claude Code / Cursor / Codex / Gemini CLI. LangChain / LangGraph / CrewAI adapters available.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
7
7
|
"bin": {
|
|
@@ -36,9 +36,19 @@
|
|
|
36
36
|
"mcp",
|
|
37
37
|
"model-context-protocol",
|
|
38
38
|
"neruva",
|
|
39
|
-
"vector-database",
|
|
40
39
|
"agent-memory",
|
|
40
|
+
"agent-context",
|
|
41
41
|
"knowledge-graph",
|
|
42
|
-
"
|
|
42
|
+
"causal-inference",
|
|
43
|
+
"pearl-do-operator",
|
|
44
|
+
"vector-database",
|
|
45
|
+
"rag",
|
|
46
|
+
"graph-rag",
|
|
47
|
+
"langchain",
|
|
48
|
+
"langgraph",
|
|
49
|
+
"crewai",
|
|
50
|
+
"claude-code",
|
|
51
|
+
"ai",
|
|
52
|
+
"llm"
|
|
43
53
|
]
|
|
44
54
|
}
|