vektor-slipstream 1.3.4 → 1.3.6

package/README.md

@@ -2,13 +2,18 @@
 
 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');
 
@@ -17,36 +22,216 @@ const memory = await createMemory({
   licenceKey: process.env.VEKTOR_LICENCE_KEY,
 });
 
+// Store a memory
 await memory.remember('User prefers TypeScript over JavaScript');
-const results = await memory.recall('coding preferences');
+
+// 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
-npx vektor activate    # Activate licence key
-npx vektor test        # Test memory engine
-npx vektor status      # System health check
-npx vektor mcp         # Start Claude MCP server
-npx vektor rem         # Run REM dream cycle
-npx vektor help        # All commands
+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
 
-- **MAGMA graph** — 4-layer associative memory (semantic, causal, temporal, entity)
-- **AUDN curation** — zero contradictions, zero duplicates
-- **REM dream cycle** — 50:1 memory compression
-- **Claude MCP server** — persistent memory for Claude Desktop
-- **Cloak** — stealth browser, AES-256 vault, layout sensor
-- **Mistral bridge** — vektor_memoire tool for Le Chat
-- **LangChain · OpenAI · Gemini · Groq · Ollama** — all supported
-- **Local ONNX embeddings** — $0 embedding cost, no API key
-- **Single SQLite file** — portable, yours forever
+### 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. 3-machine activation via Polar.  
-Purchase at: https://vektormemory.com/product#pricing  
-Support: hello@vektormemory.com
+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.3.4",
+  "version": "1.3.6",
   "description": "Hardware-accelerated persistent memory for AI agents. Local-first, zero cloud dependency, $0 embedding cost.",
   "main": "slipstream-core.js",
   "bin": {