vektor-slipstream 1.0.1 → 1.0.2

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);
+});

package/examples/example-langchain-researcher.js

@@ -0,0 +1,116 @@
+/**
+ * example-langchain-researcher.js
+ * VEKTOR SLIPSTREAM — LangChain Research Agent Example
+ * ─────────────────────────────────────────────────────
+ * A research agent that uses LangChain to search the web,
+ * summarise findings, and store everything in persistent
+ * Slipstream memory so it learns across sessions.
+ *
+ * Install:
+ *   npm install vektor-slipstream langchain @langchain/openai
+ *
+ * Usage:
+ *   OPENAI_API_KEY=sk-... node example-langchain-researcher.js
+ */
+
+'use strict';
+
+const { createMemory }            = require('vektor-slipstream');
+const { ChatOpenAI }              = require('@langchain/openai');
+const { AgentExecutor }           = require('langchain/agents');
+const { createOpenAIFunctionsAgent } = require('langchain/agents');
+const { TavilySearchResults }     = require('@langchain/community/tools/tavily_search');
+const { ChatPromptTemplate, MessagesPlaceholder } = require('@langchain/core/prompts');
+
+// ── Config ────────────────────────────────────────────────────────────────────
+
+const AGENT_ID   = 'langchain-researcher';
+const TOPIC      = process.argv[2] || 'latest developments in agentic AI memory systems';
+
+// ── Boot ──────────────────────────────────────────────────────────────────────
+
+async function main() {
+  console.log('\n[RESEARCHER] Booting Slipstream memory...');
+  const memory = await createMemory({ agentId: AGENT_ID, dbPath: './research-memory.db' });
+
+  // ── 1. Recall what we already know ──────────────────────────────────────────
+  console.log(`[RESEARCHER] Recalling prior knowledge on: "${TOPIC}"`);
+  const priorKnowledge = await memory.recall(TOPIC, 5);
+
+  let priorContext = 'No prior research on this topic.';
+  if (priorKnowledge.length > 0) {
+    priorContext = priorKnowledge
+      .map((m, i) => `${i + 1}. [score: ${m.score}] ${m.content}`)
+      .join('\n');
+    console.log(`[RESEARCHER] Found ${priorKnowledge.length} prior memories.`);
+  } else {
+    console.log('[RESEARCHER] No prior memories — starting fresh.');
+  }
+
+  // ── 2. Build the LangChain agent ────────────────────────────────────────────
+  const llm   = new ChatOpenAI({ modelName: 'gpt-4o-mini', temperature: 0.1 });
+  const tools = [new TavilySearchResults({ maxResults: 5 })];
+
+  const prompt = ChatPromptTemplate.fromMessages([
+    ['system', `You are a meticulous research agent with persistent memory.
+
+PRIOR KNOWLEDGE FROM MEMORY:
+${priorContext}
+
+Instructions:
+- Search for new information on the given topic
+- Compare findings with prior knowledge — note what's changed or new
+- Produce a concise research summary (3-5 paragraphs)
+- End with a "KEY FINDINGS:" section listing 3-5 bullet points
+- Be specific: cite sources, dates, and data points`],
+    ['human', '{input}'],
+    new MessagesPlaceholder('agent_scratchpad'),
+  ]);
+
+  const agent   = await createOpenAIFunctionsAgent({ llm, tools, prompt });
+  const executor = new AgentExecutor({ agent, tools, verbose: false });
+
+  // ── 3. Run research ──────────────────────────────────────────────────────────
+  console.log('[RESEARCHER] Running LangChain agent...\n');
+  const result = await executor.invoke({ input: `Research this topic thoroughly: ${TOPIC}` });
+  const output = result.output;
+
+  console.log('─'.repeat(60));
+  console.log(output);
+  console.log('─'.repeat(60));
+
+  // ── 4. Store findings in Slipstream ─────────────────────────────────────────
+  console.log('\n[RESEARCHER] Storing findings in Slipstream memory...');
+
+  // Store the full summary
+  await memory.remember(
+    `[RESEARCH] ${TOPIC}: ${output}`,
+    { importance: 2 }
+  );
+
+  // Extract and store each KEY FINDING separately for granular recall
+  const keyFindingsMatch = output.match(/KEY FINDINGS:([\s\S]+?)(?:\n\n|$)/i);
+  if (keyFindingsMatch) {
+    const findings = keyFindingsMatch[1]
+      .split('\n')
+      .map(l => l.replace(/^[-•*]\s*/, '').trim())
+      .filter(Boolean);
+
+    for (const finding of findings) {
+      await memory.remember(`[FINDING] ${finding}`, { importance: 3 });
+    }
+    console.log(`[RESEARCHER] Stored ${findings.length} key findings separately.`);
+  }
+
+  // ── 5. Show memory briefing ──────────────────────────────────────────────────
+  const briefing = await memory.briefing();
+  console.log('\n[RESEARCHER] Memory briefing (last 24h):');
+  console.log(briefing);
+
+  console.log('\n[RESEARCHER] Done. Run again tomorrow — agent will build on today\'s findings.');
+}
+
+main().catch(e => {
+  console.error('[RESEARCHER] Error:', e.message);
+  process.exit(1);
+});