@neruva/mcp 0.22.1 → 0.23.1

package/README.md

@@ -4,6 +4,69 @@ MCP server for [Neruva](https://neruva.io) — memory + reasoning substrate for
 
 > **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.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.
+
+| System | p95 | Capability |
+|---|---|---|
+| **Neruva 0.23 (cache hit)** | **~80ms** | Full cognitive surface |
+| Mem0 | ~200ms | Vector memory only |
+| Mem0g (graph) | ~2.6s | KG + vector |
+| Letta / MemGPT | 1.4–17s | OS-style paging |
+| RAG baseline | 450ms+ | Embedding + vector + rerank |
+
+**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:**
+
+```bash
+# 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:
+
+```json
+{
+  "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:
+
+```json
+{
+  "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

package/bin/neruva-record-hook.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+// neruva-record-hook -- platform-detecting wrapper for the native Rust binary
+//
+// Bundled binaries (one per platform) live in ../binaries/. This wrapper
+// picks the right one based on process.platform + process.arch, exec's it
+// with stdin/stdout/stderr inherited, and exits with the child's exit code.
+//
+// Cost vs direct native call: ~50-100ms Node cold start. Still ~10x faster
+// than the Python hook fallback. For latency-critical setups, point
+// settings.json directly at binaries/neruva-record-hook-<plat>-<arch>[.exe]
+// to skip the Node wrapper entirely.
+//
+// On chmod-required platforms (POSIX), the postinstall script makes the
+// right binary executable. If the binary isn't present or isn't executable,
+// we exit 0 silently (Claude Code keeps running; the user just doesn't get
+// the auto-pilot block this turn).
+
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { platform, arch } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+function pickBinary() {
+  const p = platform();
+  const a = arch();
+  const platSeg =
+    p === 'win32' ? 'win'
+    : p === 'darwin' ? 'mac'
+    : 'linux';
+  const archSeg = a === 'arm64' ? 'arm64' : 'x64';
+  const ext = p === 'win32' ? '.exe' : '';
+  return join(__dirname, '..', 'binaries', `neruva-record-hook-${platSeg}-${archSeg}${ext}`);
+}
+
+const binary = pickBinary();
+
+if (!existsSync(binary)) {
+  // Silent fallback -- never block Claude Code. User can re-install
+  // @neruva/mcp or check that the postinstall ran (chmod +x on POSIX).
+  process.exit(0);
+}
+
+const child = spawn(binary, process.argv.slice(2), {
+  stdio: 'inherit',
+});
+
+child.on('error', () => process.exit(0));
+child.on('exit', (code) => process.exit(code ?? 0));

package/bin/postinstall.js

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// postinstall: chmod +x the right platform binary on POSIX (Win is a no-op).
+// npm extracts files but doesn't preserve +x bits on POSIX from tarballs in
+// all cases, so make sure the binary we'll exec is actually executable.
+
+import { chmodSync, existsSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { platform, arch } from 'node:os';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const p = platform();
+if (p === 'win32') process.exit(0);  // Windows doesn't need chmod
+
+const a = arch();
+const platSeg = p === 'darwin' ? 'mac' : 'linux';
+const archSeg = a === 'arm64' ? 'arm64' : 'x64';
+const binary = join(__dirname, '..', 'binaries', `neruva-record-hook-${platSeg}-${archSeg}`);
+
+if (existsSync(binary)) {
+  try {
+    chmodSync(binary, 0o755);
+  } catch {}
+}

package/package.json

@@ -1,20 +1,24 @@
 {
   "name": "@neruva/mcp",
-  "version": "0.22.1",
-  "description": "MCP server for Neruva agent memory + reasoning substrate. v0.22 adds the AUTO-PILOT surface: agent_route_intent_prompt (Layer 2 -- 18-pattern intent classifier that routes user messages to the right cognitive tool) + agent_reflect_prompt (Layer 3 -- self-curates substrate from recent turns by writing structured decisions / facts / mistakes / open_questions). Combined with auto-extract on every records_ingest (Layer 1), the agent uses the full substrate without prompting. Plus typed Records, 5-engine KG, federated agent_remember/recall/context, Pearl do-operator, HD analogy, CBR, ToM, counterfactual rollouts, EFE planning, rule induction, replay, code_kg_* navigation, .neruva V3 container. Pattern-C throughout: substrate stays $0/call.",
+  "version": "0.23.1",
+  "description": "MCP server for Neruva agent memory + reasoning substrate. INSTALL: npx -y -p @neruva/mcp@latest neruva-mcp (the -p ... bin form is required because the package ships two bins: neruva-mcp + neruva-record-hook). v0.23 BUNDLES neruva-record-hook native binary (Rust, ~145-340KB) for all 6 platforms (Win/Mac/Linux x amd64/arm64). Hook talks to long-lived Python daemon over TCP localhost, daemon holds warm httpx pool + TTL cache: cache-hit p95 ~80ms, warm avg 167ms -- faster than Mem0 (200ms p95) with full cognitive surface (5 KG engines + Pearl do-operator + HD analogy + CBR + ToM + EFE planning + replay). v0.22 added AUTO-PILOT (agent_route_intent_prompt + agent_reflect_prompt + auto-extract on records_ingest). Plus typed Records, 5-engine KG, federated agent_remember/recall/context, counterfactual rollouts, rule induction, replay, code_kg_* navigation, .neruva V3 container. Pattern-C throughout: substrate stays $0/call.",
   "license": "MIT",
   "type": "module",
   "bin": {
-    "neruva-mcp": "dist/server.js"
+    "neruva-mcp": "dist/server.js",
+    "neruva-record-hook": "bin/neruva-record-hook.js"
   },
   "files": [
     "dist",
+    "bin",
+    "binaries",
     "README.md"
   ],
   "scripts": {
     "build": "tsc",
     "start": "node dist/server.js",
-    "dev": "tsx src/server.ts"
+    "dev": "tsx src/server.ts",
+    "postinstall": "node bin/postinstall.js"
   },
   "engines": {
     "node": ">=18"