vektor-slipstream 1.4.1 → 1.4.2

package/README.md

@@ -1,237 +1,241 @@
-# vektor-slipstream
-
-Hardware-accelerated persistent memory for AI agents. Local-first. No cloud. One-time payment.
-
-[![npm](https://img.shields.io/npm/v/vektor-slipstream)](https://www.npmjs.com/package/vektor-slipstream)
-[![license](https://img.shields.io/badge/license-Commercial-blue)](https://vektormemory.com/product#pricing)
-
-## Install
-
-```bash
-npm install vektor-slipstream
-npx vektor setup
-```
-
-## Quick Start
-
-```js
-const { createMemory } = require('vektor-slipstream');
-
-const memory = await createMemory({
-  agentId:    'my-agent',
-  licenceKey: process.env.VEKTOR_LICENCE_KEY,
-});
-
-// Store a memory
-await memory.remember('User prefers TypeScript over JavaScript');
-
-// Recall by semantic similarity — avg 8ms, fully local
-const results = await memory.recall('coding preferences', 5);
-// → [{ content, score, id }]
-
-// Traverse the graph
-const graph = await memory.graph('TypeScript', { hops: 2 });
-
-// What changed in 7 days?
-const delta = await memory.delta('project decisions', 7);
-
-// Morning briefing
-const brief = await memory.briefing();
-```
-
-## CLI
-
-```bash
-npx vektor setup      # First-run wizard — licence, hardware, integrations
-npx vektor activate   # Activate licence key on this machine
-npx vektor test       # Test memory engine with progress bar
-npx vektor status     # System health check
-npx vektor mcp        # Start Claude Desktop MCP server
-npx vektor rem        # Run REM dream cycle
-npx vektor help       # All commands
-```
-
-## CLOAK — Developer Context Layer for Claude Code
-
-CLOAK is a 4-tool MCP layer that gives Claude Code persistent memory of your project.
-Every session starts with full context. Every error is remembered. Every wasted token is tracked.
-
-### What it does
-
-| Tool | Does exactly one thing |
-|---|---|
-| `cloak_cortex` | Scans project files, builds a token-aware anatomy index in Vektor's entity graph |
-| `cloak_axon` | Session boundary handler — loads last context on start, saves MemCell on stop |
-| `cloak_cerebellum` | Pre-write enforcer — checks writes against known error patterns, auto-resolves fixes |
-| `cloak_token` | Token ledger — detects repeated reads and waste, one summary write per session |
-
-### Import
-
-```js
-const { runCortex }        = require('vektor-slipstream/cloak/cortex');
-const { onSessionStart,
-        onSessionStop }    = require('vektor-slipstream/cloak/axon');
-const { checkWrite,
-        recordError }      = require('vektor-slipstream/cloak/cerebellum');
-const { getSessionSummary} = require('vektor-slipstream/cloak/token');
-
-// Clean terminal output (replaces emoji with box-drawing chars)
-const { createMemory }     = require('vektor-slipstream/boot');
-```
-
-### Claude Code setup
-
-Add to `.claude/settings.json` in your project:
-
-```json
-{
-  "mcpServers": {
-    "cloak": {
-      "command": "node",
-      "args": ["/path/to/node_modules/vektor-slipstream/index.js"],
-      "env": {
-        "VEKTOR_LICENCE_KEY": "your-licence-key",
-        "CLOAK_PROJECT_PATH": "/path/to/your/project"
-      }
-    }
-  },
-  "hooks": {
-    "SessionStart": [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook SessionStart" }],
-    "Stop":         [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook Stop" }],
-    "PreToolUse":   [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook PreToolUse" }],
-    "PostToolUse":  [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook PostToolUse" }]
-  }
-}
-```
-
-### Usage
-
-```js
-// Scan project files into Vektor entity graph (call once on init)
-await cloak_cortex({})
-
-// Start session — loads last context automatically
-await cloak_axon({ action: 'start' })
-
-// Check before a risky write
-await cloak_cerebellum({
-  action: 'check',
-  content: '...code...',
-  filePath: 'src/auth.ts'
-})
-
-// Record a bug you just hit
-await cloak_cerebellum({
-  action: 'record_error',
-  description: 'Null ref on user.id when DB returns empty',
-  filePath: 'src/auth.ts',
-  errorType: 'null_reference',
-  fix: 'Add guard: if (user && user.id)'
-})
-
-// Save session with intent — the "why" not just the "what"
-await cloak_axon({
-  action: 'stop',
-  narrative: 'Fixed null reference in auth module'
-})
-
-// Check token waste
-await cloak_token({ action: 'summary' })
-```
-
-### Architecture
-
-```
-Claude Code
-    ↓ hooks + MCP tool calls
-CLOAK (4 tools, ~800 lines Node.js)
-    ↓ memory.remember() / memory.recall()
-Vektor / MAGMA
-    ↓ 4-layer graph (semantic, temporal, causal, entity)
-SQLite-vec (local, no cloud)
-```
-
-### DB growth
-
-CLOAK writes 3-5 nodes per session — not per operation.
-At 1 year of daily use: ~1,000 nodes. Sub-millisecond recall throughout.
-
-> ⚠️ **Concurrency warning**: Use stdio MCP (default). The HTTP mode
-> (`CLOAK_HTTP=1`) does not support concurrent multi-agent sessions.
-
----
-
-## What's Included
-
-### Memory Core (MAGMA)
-
-- 4-layer associative graph — semantic, causal, temporal, entity
-- AUDN curation loop — zero contradictions, zero duplicates
-- REM dream cycle — up to 50:1 compression
-- Sub-20ms recall — HNSW index, local SQLite
-- Local ONNX embeddings — $0 embedding cost, no API key required
-
-### Integrations
-
-- **Claude MCP** — `vektor_recall`, `vektor_store`, `vektor_graph`, `vektor_delta`
-- **Claude Code** — CLOAK 4-tool developer context layer (see above)
-- **LangChain** — v1 + v2 adapter included
-- **OpenAI Agents SDK** — drop-in integration
-- **Mistral** — `vektor_memoire` HTTP tool, localhost bridge
-- **Gemini · Groq · Ollama** — provider agnostic
-
-### Cloak (Sovereign Identity)
-
-- `cloak_fetch` — stealth headless browser fetch
-- `cloak_render` — computed CSS · post-JS DOM sensor
-- `cloak_passport` — AES-256-GCM credential vault, machine-bound
-- `cloak_diff` — semantic diff since last fetch
-- `tokens_saved` — ROI audit per session
-
-```js
-const { cloak_passport, cloak_fetch, tokens_saved } = require('vektor-slipstream/cloak');
-
-cloak_passport('GITHUB_TOKEN', 'ghp_xxxx');
-const token = cloak_passport('GITHUB_TOKEN');
-
-const { text, tokensSaved } = await cloak_fetch('https://example.com');
-
-const roi = tokens_saved({ raw_tokens: 10000, actual_tokens: 3000 });
-// → { reduction_pct: 70, cost_saved_usd: 0.0175, roi_multiple: 2.3 }
-```
-
-## Performance
-
-| Metric | Value |
-|--------|-------|
-| Recall latency | ~8ms avg (local SQLite) |
-| Embedding cost | $0 — fully local ONNX |
-| Embedding latency | ~10ms GPU / ~25ms CPU |
-| First run | ~2 min (downloads ~25MB model once) |
-| Subsequent boots | <100ms |
-
-## Hardware Auto-Detection
-
-Zero config. VEKTOR detects and uses the best available accelerator:
-
-- **NVIDIA CUDA** — GPU acceleration
-- **Apple Silicon** — CoreML
-- **CPU** — optimised fallback, works everywhere
-
-## Licence
-
-Commercial licence. One-time payment of $159. Activates on up to 3 machines.
-Manage at [polar.sh](https://polar.sh).
-
-Purchase: [vektormemory.com/product#pricing](https://vektormemory.com/product#pricing)
-Docs: [vektormemory.com/docs](https://vektormemory.com/docs)
-Support: hello@vektormemory.com
-
-## Research
-
-Built on peer-reviewed research:
-
-- [MAGMA (arxiv:2601.03236)](https://arxiv.org/abs/2601.03236) — Multi-Graph Agentic Memory Architecture
-- [EverMemOS (arxiv:2601.02163)](https://arxiv.org/abs/2601.02163) — Self-Organizing Memory OS
-- [HippoRAG (arxiv:2405.14831)](https://arxiv.org/abs/2405.14831) — Neurobiologically Inspired Long-Term Memory (NeurIPS 2024)
-- [Mem0 (arxiv:2504.19413)](https://arxiv.org/abs/2504.19413) — Production-Ready Agent Memory
+# vektor-slipstream
+
+Hardware-accelerated persistent memory for AI agents. Local-first. No cloud. One-time payment.
+
+[![npm](https://img.shields.io/npm/v/vektor-slipstream)](https://www.npmjs.com/package/vektor-slipstream)
+[![license](https://img.shields.io/badge/license-Commercial-blue)](https://vektormemory.com/product#pricing)
+
+## Install
+
+```bash
+npm install vektor-slipstream
+npx vektor setup
+```
+
+## Quick Start
+
+```js
+const { createMemory } = require('vektor-slipstream');
+
+const memory = await createMemory({
+  agentId:    'my-agent',
+  licenceKey: process.env.VEKTOR_LICENCE_KEY,
+});
+
+// Store a memory
+await memory.remember('User prefers TypeScript over JavaScript');
+
+// Recall by semantic similarity — avg 8ms, fully local
+const results = await memory.recall('coding preferences', 5);
+// → [{ content, score, id }]
+
+// Traverse the graph
+const graph = await memory.graph('TypeScript', { hops: 2 });
+
+// What changed in 7 days?
+const delta = await memory.delta('project decisions', 7);
+
+// Morning briefing
+const brief = await memory.briefing();
+```
+
+## CLI
+
+```bash
+npx vektor setup      # First-run wizard — licence, hardware, integrations
+npx vektor activate   # Activate licence key on this machine
+npx vektor test       # Test memory engine with progress bar
+npx vektor status     # System health check
+npx vektor mcp        # Start Claude Desktop MCP server
+npx vektor rem        # Run REM dream cycle
+npx vektor chat       # Persistent memory chat (all LLMs)
+npx vektor remember   # Store a fact: npx vektor remember "I prefer TypeScript"
+npx vektor ask        # Query memory: npx vektor ask "what stack am I using?"
+npx vektor agent      # Autonomous goal executor
+npx vektor help       # All commands
+```
+
+## CLOAK — Developer Context Layer for Claude Code
+
+CLOAK is a 4-tool MCP layer that gives Claude Code persistent memory of your project.
+Every session starts with full context. Every error is remembered. Every wasted token is tracked.
+
+### What it does
+
+| Tool | Does exactly one thing |
+|---|---|
+| `cloak_cortex` | Scans project files, builds a token-aware anatomy index in Vektor's entity graph |
+| `cloak_axon` | Session boundary handler — loads last context on start, saves MemCell on stop |
+| `cloak_cerebellum` | Pre-write enforcer — checks writes against known error patterns, auto-resolves fixes |
+| `cloak_token` | Token ledger — detects repeated reads and waste, one summary write per session |
+
+### Import
+
+```js
+const { runCortex }        = require('vektor-slipstream/cloak/cortex');
+const { onSessionStart,
+        onSessionStop }    = require('vektor-slipstream/cloak/axon');
+const { checkWrite,
+        recordError }      = require('vektor-slipstream/cloak/cerebellum');
+const { getSessionSummary} = require('vektor-slipstream/cloak/token');
+
+// Clean terminal output (replaces emoji with box-drawing chars)
+const { createMemory }     = require('vektor-slipstream/boot');
+```
+
+### Claude Code setup
+
+Add to `.claude/settings.json` in your project:
+
+```json
+{
+  "mcpServers": {
+    "cloak": {
+      "command": "node",
+      "args": ["/path/to/node_modules/vektor-slipstream/index.js"],
+      "env": {
+        "VEKTOR_LICENCE_KEY": "your-licence-key",
+        "CLOAK_PROJECT_PATH": "/path/to/your/project"
+      }
+    }
+  },
+  "hooks": {
+    "SessionStart": [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook SessionStart" }],
+    "Stop":         [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook Stop" }],
+    "PreToolUse":   [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook PreToolUse" }],
+    "PostToolUse":  [{ "type": "command", "command": "node /path/to/node_modules/vektor-slipstream/index.js --hook PostToolUse" }]
+  }
+}
+```
+
+### Usage
+
+```js
+// Scan project files into Vektor entity graph (call once on init)
+await cloak_cortex({})
+
+// Start session — loads last context automatically
+await cloak_axon({ action: 'start' })
+
+// Check before a risky write
+await cloak_cerebellum({
+  action: 'check',
+  content: '...code...',
+  filePath: 'src/auth.ts'
+})
+
+// Record a bug you just hit
+await cloak_cerebellum({
+  action: 'record_error',
+  description: 'Null ref on user.id when DB returns empty',
+  filePath: 'src/auth.ts',
+  errorType: 'null_reference',
+  fix: 'Add guard: if (user && user.id)'
+})
+
+// Save session with intent — the "why" not just the "what"
+await cloak_axon({
+  action: 'stop',
+  narrative: 'Fixed null reference in auth module'
+})
+
+// Check token waste
+await cloak_token({ action: 'summary' })
+```
+
+### Architecture
+
+```
+Claude Code
+    ↓ hooks + MCP tool calls
+CLOAK (4 tools, ~800 lines Node.js)
+    ↓ memory.remember() / memory.recall()
+Vektor / MAGMA
+    ↓ 4-layer graph (semantic, temporal, causal, entity)
+SQLite-vec (local, no cloud)
+```
+
+### DB growth
+
+CLOAK writes 3-5 nodes per session — not per operation.
+At 1 year of daily use: ~1,000 nodes. Sub-millisecond recall throughout.
+
+> ⚠️ **Concurrency warning**: Use stdio MCP (default). The HTTP mode
+> (`CLOAK_HTTP=1`) does not support concurrent multi-agent sessions.
+
+---
+
+## What's Included
+
+### Memory Core (MAGMA)
+
+- 4-layer associative graph — semantic, causal, temporal, entity
+- AUDN curation loop — zero contradictions, zero duplicates
+- REM dream cycle — up to 50:1 compression
+- Sub-20ms recall — HNSW index, local SQLite
+- Local ONNX embeddings — $0 embedding cost, no API key required
+
+### Integrations
+
+- **Claude MCP** — `vektor_recall`, `vektor_store`, `vektor_graph`, `vektor_delta`
+- **Claude Code** — CLOAK 4-tool developer context layer (see above)
+- **LangChain** — v1 + v2 adapter included
+- **OpenAI Agents SDK** — drop-in integration
+- **Mistral** — `vektor_memoire` HTTP tool, localhost bridge
+- **Gemini · Groq · Ollama** — provider agnostic
+
+### Cloak (Sovereign Identity)
+
+- `cloak_fetch` — stealth headless browser fetch
+- `cloak_render` — computed CSS · post-JS DOM sensor
+- `cloak_passport` — AES-256-GCM credential vault, machine-bound
+- `cloak_diff` — semantic diff since last fetch
+- `tokens_saved` — ROI audit per session
+
+```js
+const { cloak_passport, cloak_fetch, tokens_saved } = require('vektor-slipstream/cloak');
+
+cloak_passport('GITHUB_TOKEN', 'ghp_xxxx');
+const token = cloak_passport('GITHUB_TOKEN');
+
+const { text, tokensSaved } = await cloak_fetch('https://example.com');
+
+const roi = tokens_saved({ raw_tokens: 10000, actual_tokens: 3000 });
+// → { reduction_pct: 70, cost_saved_usd: 0.0175, roi_multiple: 2.3 }
+```
+
+## Performance
+
+| Metric | Value |
+|--------|-------|
+| Recall latency | ~8ms avg (local SQLite) |
+| Embedding cost | $0 — fully local ONNX |
+| Embedding latency | ~10ms GPU / ~25ms CPU |
+| First run | ~2 min (downloads ~25MB model once) |
+| Subsequent boots | <100ms |
+
+## Hardware Auto-Detection
+
+Zero config. VEKTOR detects and uses the best available accelerator:
+
+- **NVIDIA CUDA** — GPU acceleration
+- **Apple Silicon** — CoreML
+- **CPU** — optimised fallback, works everywhere
+
+## Licence
+
+Commercial licence. One-time payment of $159. Activates on up to 3 machines.
+Manage at [polar.sh](https://polar.sh).
+
+Purchase: [vektormemory.com/product#pricing](https://vektormemory.com/product#pricing)
+Docs: [vektormemory.com/docs](https://vektormemory.com/docs)
+Support: hello@vektormemory.com
+
+## Research
+
+Built on peer-reviewed research:
+
+- [MAGMA (arxiv:2601.03236)](https://arxiv.org/abs/2601.03236) — Multi-Graph Agentic Memory Architecture
+- [EverMemOS (arxiv:2601.02163)](https://arxiv.org/abs/2601.02163) — Self-Organizing Memory OS
+- [HippoRAG (arxiv:2405.14831)](https://arxiv.org/abs/2405.14831) — Neurobiologically Inspired Long-Term Memory (NeurIPS 2024)
+- [Mem0 (arxiv:2504.19413)](https://arxiv.org/abs/2504.19413) — Production-Ready Agent Memory

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vektor-slipstream",
-  "version": "1.4.1",
+  "version": "1.4.2",
   "description": "Hardware-accelerated persistent memory for AI agents. Local-first, zero cloud dependency, $0 embedding cost.",
   "main": "slipstream-core-extended.js",
   "types": "./types/index.d.ts",