vektor-slipstream 1.0.0

package/README.md

@@ -0,0 +1,252 @@
+\# vektor-slipstream
+
+
+
+\*\*Hardware-accelerated persistent memory for AI agents.\*\*  
+
+Local-first. Zero cloud dependency. $0 embedding cost.
+
+
+
+```bash
+
+npm install vektor-slipstream
+
+```
+
+
+
+\---
+
+
+
+\## What it is
+
+
+
+A drop-in memory layer for any AI agent. Your agent remembers everything across sessions — preferences, decisions, research, conversations — stored in a single portable SQLite file on your machine.
+
+
+
+No OpenAI embedding bill. No cloud roundtrip. No API key for memory.
+
+
+
+```js
+
+const { createMemory } = require('vektor-slipstream');
+
+
+
+const memory = await createMemory({ agentId: 'my-agent' });
+
+
+
+// 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');
+
+// → \[{ content: 'User prefers TypeScript...', score: 0.97, id: 1 }]
+
+```
+
+
+
+\---
+
+
+
+\## How it works
+
+
+
+\- \*\*Local ONNX embeddings\*\* — `all-MiniLM-L6-v2 INT8` runs on your hardware via `onnxruntime-node`. No API calls.
+
+\- \*\*Hyper-PRAGMA SQLite\*\* — WAL mode, 1GB mmap, 64MB cache. Recall at RAM speeds.
+
+\- \*\*MAGMA graph\*\* — 4-layer associative graph (semantic · causal · temporal · entity). Memories connect to each other.
+
+\- \*\*Hardware auto-detection\*\* — uses CUDA on NVIDIA, CoreML on Apple Silicon, CPU everywhere else.
+
+
+
+\---
+
+
+
+\## API
+
+
+
+```js
+
+const { createMemory } = require('vektor-slipstream');
+
+
+
+const memory = await createMemory({
+
+  agentId: 'my-agent',      // isolates memories per agent
+
+  dbPath:  './memory.db',   // default: ./slipstream-memory.db
+
+  silent:  false,           // suppress boot banner
+
+});
+
+```
+
+
+
+\### `memory.remember(text, opts?)`
+
+Store a memory with its vector embedding.
+
+```js
+
+const { id } = await memory.remember('User is based in Brisbane, AU');
+
+const { id } = await memory.remember('Closed Series A at $4M', { importance: 5 });
+
+```
+
+
+
+\### `memory.recall(query, topK?)`
+
+Semantic recall — returns top-k most relevant memories.
+
+```js
+
+const results = await memory.recall('user location', 5);
+
+// → \[{ id, content, score, importance }]
+
+```
+
+
+
+\### `memory.graph(concept, opts?)`
+
+Breadth-first traversal from a concept — finds connected memories.
+
+```js
+
+const { nodes, edges } = await memory.graph('fundraising', { hops: 2 });
+
+```
+
+
+
+\### `memory.delta(topic, days?)`
+
+What changed on a topic in the last N days.
+
+```js
+
+const changes = await memory.delta('project status', 7);
+
+```
+
+
+
+\### `memory.briefing()`
+
+Summary of everything learned in the last 24 hours. Inject into system prompt.
+
+```js
+
+const brief = await memory.briefing();
+
+// → "\[SLIPSTREAM BRIEFING — last 24h — 12 memories]\\n1. ..."
+
+```
+
+
+
+\---
+
+
+
+\## Examples
+
+
+
+Three production-ready agent examples are included in `examples/`:
+
+
+
+| File | Description |
+
+|------|-------------|
+
+| `example-langchain-researcher.js` | LangChain agent that builds a persistent knowledge base |
+
+| `example-openai-assistant.js` | OpenAI assistant with automatic cross-session memory |
+
+| `example-claude-mcp.js` | Claude MCP server + direct chat mode |
+
+
+
+See \[`examples/README.md`](examples/README.md) for setup and usage.
+
+
+
+\---
+
+
+
+\## Performance
+
+
+
+| Metric | Value |
+
+|--------|-------|
+
+| Recall latency | \~8ms avg (local SQLite) |
+
+| Embedding cost | $0 — fully local ONNX |
+
+| Embedding latency | \~10ms GPU / \~25ms CPU (post-warmup) |
+
+| DB engine | SQLite WAL + 1GB mmap |
+
+| Vector dimensions | 384 (all-MiniLM-L6-v2 INT8) |
+
+
+
+\---
+
+
+
+\## Requirements
+
+
+
+\- Node.js 18+
+
+\- \~25MB disk for the ONNX model (bundled)
+
+
+
+\---
+
+
+
+\## License
+
+
+
+Commercial licence — see LICENSE file.  
+
+One-time purchase includes all future updates.  
+
+Purchase at \[vektormemory.com](https://vektormemory.com)
+

package/detect-hardware.js

@@ -0,0 +1,181 @@
+'use strict';
+
+/**
+ * VEKTOR SLIPSTREAM
+ * detect-hardware.js — Execution Provider Probe
+ * ─────────────────────────────────────────────────────────────────────────────
+ * Probes the host system for hardware acceleration capabilities WITHOUT
+ * attempting to load any native binaries. Uses only OS-level CLI tools that
+ * ship with the relevant drivers/OS — so this file itself has zero native deps
+ * and zero risk of crashing the terminal.
+ *
+ * Returns: 'cuda' | 'coreml' | 'cpu'
+ * Execution time: < 10ms (CLI probe only, no driver load)
+ *
+ * Consumed by:
+ *   - postinstall.js   → to decide which onnxruntime variant to install
+ *   - slipstream.js    → to decide which EP to pass to InferenceSession.create()
+ * ─────────────────────────────────────────────────────────────────────────────
+ */
+
+const os   = require('os');
+const { execSync } = require('child_process');
+
+// ─── Constants ───────────────────────────────────────────────────────────────
+
+const EP = Object.freeze({
+  CUDA   : 'cuda',
+  COREML : 'coreml',
+  CPU    : 'cpu',
+});
+
+// ─── Probe Helpers ───────────────────────────────────────────────────────────
+
+/**
+ * macOS: Check for Apple Silicon via sysctl.
+ * sysctl is a native macOS syscall utility — always present, zero install.
+ * Returns 'coreml' on M-series chips, 'cpu' on Intel Macs.
+ */
+function probeDarwin() {
+  try {
+    const cpuBrand = execSync(
+      'sysctl -n machdep.cpu.brand_string 2>/dev/null',
+      { stdio: 'pipe', timeout: 2000 }
+    ).toString().trim();
+
+    if (cpuBrand.includes('Apple')) {
+      return EP.COREML;
+    }
+  } catch (_) {
+    // sysctl unavailable or returned non-zero — safe fallback
+  }
+  return EP.CPU;
+}
+
+/**
+ * Linux / Windows: Check for NVIDIA GPU via nvidia-smi.
+ * nvidia-smi ships with the NVIDIA driver package.
+ * If it exits 0, the GPU is present AND the driver is loaded — both required.
+ * stdio: 'ignore' suppresses the full nvidia-smi output table.
+ * timeout: 3000ms prevents hangs on misconfigured driver environments.
+ */
+function probeNvidia() {
+  try {
+    execSync('nvidia-smi', { stdio: 'ignore', timeout: 3000 });
+    return EP.CUDA;
+  } catch (_) {
+    // nvidia-smi not found, or GPU present but driver not loaded
+    return EP.CPU;
+  }
+}
+
+// ─── Main Export ─────────────────────────────────────────────────────────────
+
+/**
+ * detectHardware()
+ *
+ * Synchronous hardware probe. Returns the highest-performance execution
+ * provider available on the current machine. Decision tree:
+ *
+ *   macOS + Apple Silicon  →  'coreml'   (Neural Engine via CoreML)
+ *   macOS + Intel          →  'cpu'      (no CoreML acceleration)
+ *   Linux/Win + NVIDIA     →  'cuda'     (GPU via CUDA)
+ *   Linux/Win + no GPU     →  'cpu'      (optimised WASM SIMD path)
+ *   Any other platform     →  'cpu'      (safe universal fallback)
+ *
+ * @returns {'cuda'|'coreml'|'cpu'}
+ */
+function detectHardware() {
+  const platform = os.platform();
+
+  switch (platform) {
+    case 'darwin':
+      return probeDarwin();
+
+    case 'linux':
+    case 'win32':
+      return probeNvidia();
+
+    default:
+      // FreeBSD, Android, unknown — CPU is always safe
+      return EP.CPU;
+  }
+}
+
+/**
+ * detectHardwareAsync()
+ *
+ * Non-blocking wrapper. Runs the probe in a setImmediate tick so it doesn't
+ * stall the event loop during module initialisation. Preferred for use inside
+ * slipstream.js createMemory() boot sequence.
+ *
+ * @returns {Promise<'cuda'|'coreml'|'cpu'>}
+ */
+function detectHardwareAsync() {
+  return new Promise((resolve) => {
+    setImmediate(() => resolve(detectHardware()));
+  });
+}
+
+/**
+ * getEPLabel()
+ * Human-readable label for the audit log banner.
+ *
+ * @param {'cuda'|'coreml'|'cpu'} ep
+ * @returns {string}
+ */
+function getEPLabel(ep) {
+  const labels = {
+    [EP.CUDA]   : 'CUDA (NVIDIA GPU)',
+    [EP.COREML] : 'CoreML (Apple Neural Engine)',
+    [EP.CPU]    : 'CPU (WASM SIMD)',
+  };
+  return labels[ep] ?? 'CPU (WASM SIMD)';
+}
+
+module.exports = {
+  detectHardware,
+  detectHardwareAsync,
+  getEPLabel,
+  EP, // export constants so consumers don't hardcode strings
+};
+
+// ─── CLI Self-Test ───────────────────────────────────────────────────────────
+// Run directly to validate the probe on any target machine:
+//   node detect-hardware.js
+//
+// Expected outputs:
+//   Apple M-series  →  [SLIPSTREAM PROBE] EP: CoreML (Apple Neural Engine) ✓
+//   NVIDIA machine  →  [SLIPSTREAM PROBE] EP: CUDA (NVIDIA GPU) ✓
+//   Any other       →  [SLIPSTREAM PROBE] EP: CPU (WASM SIMD) ✓
+
+if (require.main === module) {
+  const start = Date.now();
+  const ep    = detectHardware();
+  const ms    = Date.now() - start;
+
+  const icon = ep === EP.CPU ? '⚙️ ' : '🚀';
+
+  console.log('');
+  console.log('  ╔══════════════════════════════════════════╗');
+  console.log('  ║       VEKTOR SLIPSTREAM — PROBE          ║');
+  console.log('  ╚══════════════════════════════════════════╝');
+  console.log('');
+  console.log(`  ${icon} EP:       ${getEPLabel(ep)}`);
+  console.log(`  ⏱  Probe:    ${ms}ms`);
+  console.log(`  🖥  Platform: ${os.platform()} / ${os.arch()}`);
+  console.log(`  💾  RAM:      ${(os.totalmem() / 1024 ** 3).toFixed(1)} GB`);
+  console.log('');
+
+  if (ep === EP.CPU) {
+    console.log('  ℹ️  No GPU acceleration detected.');
+    console.log('  Slipstream will run on optimised CPU (WASM SIMD).');
+    console.log('  For CUDA: ensure nvidia-smi is accessible in PATH.');
+    console.log('  For CoreML: Apple Silicon Mac required.');
+  } else {
+    console.log(`  ✓ Hardware acceleration confirmed. Slipstream will`);
+    console.log(`    engage ${getEPLabel(ep)} for sub-12ms embeddings.`);
+  }
+
+  console.log('');
+}

package/examples/example-claude-mcp.js

@@ -0,0 +1,284 @@
+/**
+ * example-claude-mcp.js
+ * VEKTOR SLIPSTREAM — Claude MCP Agent Example
+ * ─────────────────────────────────────────────
+ * Connects Claude to Slipstream persistent memory via the
+ * Model Context Protocol (MCP). Claude can recall, store,
+ * and traverse the memory graph across every conversation.
+ *
+ * Two modes:
+ *   1. MCP SERVER MODE  — run as a stdio MCP server for Claude Desktop
+ *   2. DIRECT CHAT MODE — interactive chat with memory, no MCP needed
+ *
+ * Install:
+ *   npm install vektor-slipstream @anthropic-ai/sdk
+ *
+ * MCP server mode (add to claude_desktop_config.json):
+ *   {
+ *     "mcpServers": {
+ *       "slipstream": {
+ *         "command": "node",
+ *         "args": ["/path/to/example-claude-mcp.js", "--mcp"],
+ *         "env": { "SLIPSTREAM_AGENT_ID": "claude-desktop" }
+ *       }
+ *     }
+ *   }
+ *
+ * Direct chat mode:
+ *   ANTHROPIC_API_KEY=sk-ant-... node example-claude-mcp.js
+ */
+
+'use strict';
+
+const { createMemory } = require('vektor-slipstream');
+const Anthropic        = require('@anthropic-ai/sdk');
+const readline         = require('readline');
+
+const IS_MCP  = process.argv.includes('--mcp');
+const AGENT_ID = process.env.SLIPSTREAM_AGENT_ID || 'claude-mcp';
+const MODEL   = 'claude-haiku-4-5-20251001'; // fast + cheap for tool use
+
+// ── MCP Tool Definitions ──────────────────────────────────────────────────────
+
+const MCP_TOOLS = [
+  {
+    name: 'vektor_recall',
+    description: 'Search Slipstream persistent memory for relevant context. Call before answering any question that might have prior context.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        query:  { type: 'string',  description: 'What to search for.' },
+        top_k:  { type: 'integer', description: 'Number of results (default 5, max 20).', default: 5 },
+      },
+      required: ['query'],
+    },
+  },
+  {
+    name: 'vektor_store',
+    description: 'Store a fact, preference, decision, or piece of context in persistent memory. Use whenever the user shares something worth remembering.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        content:    { type: 'string',  description: 'The memory to store as a clear complete sentence.' },
+        importance: { type: 'number',  description: 'Importance 1-5. 5=critical (name/key decision), 3=useful, 1=minor.' },
+      },
+      required: ['content'],
+    },
+  },
+  {
+    name: 'vektor_graph',
+    description: 'Traverse the memory graph from a concept — finds connected memories and relationships. Use to understand full context around a topic.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        concept: { type: 'string',  description: 'The concept to start from.' },
+        hops:    { type: 'integer', description: 'Traversal depth 1-3 (default 2).', default: 2 },
+      },
+      required: ['concept'],
+    },
+  },
+  {
+    name: 'vektor_delta',
+    description: 'See what changed in memory on a topic over recent days.',
+    input_schema: {
+      type: 'object',
+      properties: {
+        topic: { type: 'string',  description: 'The topic to check.' },
+        days:  { type: 'integer', description: 'How many days back to look (default 7).', default: 7 },
+      },
+      required: ['topic'],
+    },
+  },
+];
+
+// ── Tool execution ────────────────────────────────────────────────────────────
+
+async function runTool(name, input, memory) {
+  switch (name) {
+    case 'vektor_recall': {
+      const results = await memory.recall(input.query, input.top_k || 5);
+      if (!results.length) return { found: 0, memories: [] };
+      return {
+        found: results.length,
+        memories: results.map(r => ({
+          content:   r.content,
+          relevance: r.score,
+          id:        r.id,
+        })),
+      };
+    }
+    case 'vektor_store': {
+      const { id } = await memory.remember(input.content, { importance: input.importance || 2 });
+      return { stored: true, memory_id: id, content: input.content };
+    }
+    case 'vektor_graph': {
+      const { nodes, edges } = await memory.graph(input.concept, { hops: input.hops || 2 });
+      return {
+        nodes: nodes.slice(0, 10).map(n => ({ id: n.id, content: n.content, importance: n.importance })),
+        edge_count: edges.length,
+        node_count: nodes.length,
+      };
+    }
+    case 'vektor_delta': {
+      const changes = await memory.delta(input.topic, input.days || 7);
+      return {
+        topic:   input.topic,
+        days:    input.days || 7,
+        changes: changes.slice(0, 10).map(c => ({ content: c.content, updated_at: c.updated_at })),
+      };
+    }
+    default:
+      return { error: `Unknown tool: ${name}` };
+  }
+}
+
+// ── MCP Server Mode (stdio) ───────────────────────────────────────────────────
+
+async function runMCPServer(memory) {
+  // MCP JSON-RPC over stdio
+  process.stdin.setEncoding('utf8');
+  let buffer = '';
+
+  async function handleRequest(req) {
+    if (req.method === 'initialize') {
+      return {
+        protocolVersion: '2024-11-05',
+        serverInfo: { name: 'vektor-slipstream', version: '1.0.0' },
+        capabilities: { tools: {} },
+      };
+    }
+
+    if (req.method === 'tools/list') {
+      return { tools: MCP_TOOLS };
+    }
+
+    if (req.method === 'tools/call') {
+      const { name, arguments: args } = req.params;
+      try {
+        const result = await runTool(name, args, memory);
+        return {
+          content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+        };
+      } catch(e) {
+        return {
+          content: [{ type: 'text', text: `Error: ${e.message}` }],
+          isError: true,
+        };
+      }
+    }
+
+    return { error: { code: -32601, message: 'Method not found' } };
+  }
+
+  process.stdin.on('data', async chunk => {
+    buffer += chunk;
+    const lines = buffer.split('\n');
+    buffer = lines.pop();
+
+    for (const line of lines) {
+      if (!line.trim()) continue;
+      try {
+        const req = JSON.parse(line);
+        const result = await handleRequest(req);
+        const response = JSON.stringify({ jsonrpc: '2.0', id: req.id, result });
+        process.stdout.write(response + '\n');
+      } catch(e) {
+        const err = JSON.stringify({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
+        process.stdout.write(err + '\n');
+      }
+    }
+  });
+}
+
+// ── Direct Chat Mode ──────────────────────────────────────────────────────────
+
+async function runDirectChat(memory) {
+  const client   = new Anthropic();
+  const messages = [];
+
+  const briefing = await memory.briefing();
+  const system   = `You are a persistent assistant with long-term memory via VEKTOR Slipstream.
+
+You have four memory tools: vektor_recall, vektor_store, vektor_graph, vektor_delta.
+- Always recall before answering questions that might have prior context
+- Store important facts the user shares
+- Be proactive about remembering preferences and decisions
+
+${briefing}`;
+
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const prompt = () => new Promise(resolve => rl.question('\nYou: ', resolve));
+
+  console.log('\n[CLAUDE+SLIPSTREAM] Ready. Memories persist across sessions.');
+  console.log('[CLAUDE+SLIPSTREAM] Type "exit" to quit.\n');
+
+  while (true) {
+    const userInput = (await prompt()).trim();
+    if (!userInput) continue;
+    if (userInput.toLowerCase() === 'exit') { rl.close(); break; }
+
+    messages.push({ role: 'user', content: userInput });
+
+    // Agentic loop
+    while (true) {
+      const response = await client.messages.create({
+        model:      MODEL,
+        max_tokens: 1024,
+        system,
+        tools:      MCP_TOOLS,
+        messages,
+      });
+
+      const assistantMsg = { role: 'assistant', content: response.content };
+      messages.push(assistantMsg);
+
+      if (response.stop_reason !== 'tool_use') {
+        // Final text response
+        const text = response.content.find(b => b.type === 'text')?.text || '';
+        console.log(`\nClaude: ${text}`);
+        break;
+      }
+
+      // Handle tool calls
+      const toolResults = [];
+      for (const block of response.content) {
+        if (block.type !== 'tool_use') continue;
+        const result = await runTool(block.name, block.input, memory);
+        console.log(`  [${block.name}] ${JSON.stringify(result).slice(0, 100)}...`);
+        toolResults.push({
+          type:        'tool_result',
+          tool_use_id: block.id,
+          content:     JSON.stringify(result),
+        });
+      }
+      messages.push({ role: 'user', content: toolResults });
+    }
+  }
+
+  console.log('\n[CLAUDE+SLIPSTREAM] Session ended. Memories saved.');
+}
+
+// ── Entry Point ───────────────────────────────────────────────────────────────
+
+async function main() {
+  if (!IS_MCP) {
+    console.log('\n[CLAUDE+SLIPSTREAM] Booting Slipstream memory...');
+  }
+
+  const memory = await createMemory({
+    agentId: AGENT_ID,
+    dbPath:  './claude-memory.db',
+    silent:  IS_MCP, // suppress banner in MCP mode (stdout is JSON-RPC)
+  });
+
+  if (IS_MCP) {
+    await runMCPServer(memory);
+  } else {
+    await runDirectChat(memory);
+  }
+}
+
+main().catch(e => {
+  if (!IS_MCP) console.error('[CLAUDE+SLIPSTREAM] Error:', e.message);
+  process.exit(1);
+});