vektor-slipstream 1.4.4 → 2.0.0

package/errors.js

@@ -1,66 +0,0 @@
-/**
- * VEKTOR structured error codes — v1.3.7
- * Replace all string throws with VektorError instances.
- * Consumers can switch/case on error.code reliably.
- */
-
-export class VektorError extends Error {
-  constructor(code, message, detail = null) {
-    super(message);
-    this.name = 'VektorError';
-    this.code = code;
-    this.detail = detail;
-    if (Error.captureStackTrace) Error.captureStackTrace(this, VektorError);
-  }
-}
-
-export const ERR = {
-  // Licence
-  LICENCE_MISSING:        'ERR_LICENCE_MISSING',
-  LICENCE_INVALID:        'ERR_LICENCE_INVALID',
-  LICENCE_EXPIRED:        'ERR_LICENCE_EXPIRED',
-
-  // Memory operations
-  MEMORY_NOT_FOUND:       'ERR_MEMORY_NOT_FOUND',
-  MEMORY_WRITE_FAILED:    'ERR_MEMORY_WRITE_FAILED',
-  MEMORY_READ_FAILED:     'ERR_MEMORY_READ_FAILED',
-  MEMORY_DELETE_FAILED:   'ERR_MEMORY_DELETE_FAILED',
-
-  // Graph
-  GRAPH_NODE_NOT_FOUND:   'ERR_GRAPH_NODE_NOT_FOUND',
-  GRAPH_CORRUPTED:        'ERR_GRAPH_CORRUPTED',
-
-  // Provider / embedding
-  PROVIDER_NOT_SUPPORTED: 'ERR_PROVIDER_NOT_SUPPORTED',
-  EMBED_FAILED:           'ERR_EMBED_FAILED',
-  PROVIDER_RATE_LIMIT:    'ERR_PROVIDER_RATE_LIMIT',
-  PROVIDER_AUTH:          'ERR_PROVIDER_AUTH',
-
-  // Config
-  AGENT_ID_MISSING:       'ERR_AGENT_ID_MISSING',
-  DB_INIT_FAILED:         'ERR_DB_INIT_FAILED',
-
-  // Import / export
-  EXPORT_FAILED:          'ERR_EXPORT_FAILED',
-  IMPORT_FAILED:          'ERR_IMPORT_FAILED',
-  IMPORT_SCHEMA_MISMATCH: 'ERR_IMPORT_SCHEMA_MISMATCH',
-
-  // Namespace
-  NAMESPACE_INVALID:      'ERR_NAMESPACE_INVALID',
-};
-
-/**
- * Usage:
- *   throw new VektorError(ERR.LICENCE_INVALID, 'Licence key rejected', { key: '...' });
- *
- * Consumer:
- *   try { await memory.remember(...) }
- *   catch (e) {
- *     if (e instanceof VektorError) {
- *       switch (e.code) {
- *         case ERR.LICENCE_INVALID: // handle
- *         case ERR.EMBED_FAILED:    // retry
- *       }
- *     }
- *   }
- */

package/examples/example-claude-mcp.js

@@ -1,220 +0,0 @@
-'use strict';
-/**
- * example-claude-mcp.js — VEKTOR Slipstream + Claude
- * ─────────────────────────────────────────────────────────────────────────────
- * Auto-memory: every conversation turn is stored in the MAGMA graph.
- * Claude recalls relevant context before every response.
- * No setup required — memory just works.
- *
- * Usage (MCP server for Claude Desktop):
- *   node example-claude-mcp.js --mcp
- *
- * Usage (direct chat):
- *   ANTHROPIC_API_KEY=sk-ant-... VEKTOR_LICENCE_KEY=... node example-claude-mcp.js
- */
-
-const { createMemory } = require('vektor-slipstream');
-const readline = require('readline');
-
-// ── Memory init ───────────────────────────────────────────────────────────────
-let _memory = null;
-async function getMemory() {
-  if (_memory) return _memory;
-  _memory = await createMemory({
-    agentId:    process.env.SLIPSTREAM_AGENT_ID || 'claude-vektor',
-    licenceKey: process.env.VEKTOR_LICENCE_KEY,
-    dbPath:     process.env.VEKTOR_DB_PATH,
-    silent:     true,
-  });
-  return _memory;
-}
-
-// ── Auto-store: extract memorable facts from a conversation turn ──────────────
-async function autoStore(memory, userMsg, assistantResponse) {
-  // Store the user message if it contains memorable content
-  const memorable = isMemorableContent(userMsg);
-  if (memorable) {
-    await memory.remember(userMsg, { importance: memorable.importance }).catch(() => {});
-  }
-
-  // Store a condensed version of the exchange
-  const exchange = `User: ${userMsg.slice(0, 200)} | Assistant: ${assistantResponse.slice(0, 300)}`;
-  await memory.remember(exchange, { importance: 2 }).catch(() => {});
-}
-
-// ── Heuristic: is this content worth storing? ─────────────────────────────────
-function isMemorableContent(text) {
-  const t = text.toLowerCase();
-
-  // High importance — preferences, decisions, critical facts
-  if (/prefer|always|never|hate|love|my name|i am|i'm a|i work|my project|deadline|important|remember/.test(t)) {
-    return { importance: 4 };
-  }
-  // Medium importance — project details, tech choices, context
-  if (/project|build|using|stack|version|deploy|api|database|language|framework|decided|going with/.test(t)) {
-    return { importance: 3 };
-  }
-  // Low importance — general context worth keeping
-  if (text.length > 80) {
-    return { importance: 2 };
-  }
-  return null;
-}
-
-// ── MCP Server mode ───────────────────────────────────────────────────────────
-if (process.argv.includes('--mcp')) {
-  const TOOLS = [
-    {
-      name: 'vektor_recall',
-      description: 'Search persistent memory for relevant context. Call before answering anything that might have prior context.',
-      inputSchema: { type: 'object', properties: { query: { type: 'string' }, top_k: { type: 'integer', default: 5 } }, required: ['query'] },
-    },
-    {
-      name: 'vektor_store',
-      description: 'Store a fact, preference, decision, or context in persistent memory.',
-      inputSchema: { type: 'object', properties: { content: { type: 'string' }, importance: { type: 'integer', default: 3 } }, required: ['content'] },
-    },
-    {
-      name: 'vektor_graph',
-      description: 'Traverse the associative memory graph to find connected memories.',
-      inputSchema: { type: 'object', properties: { topic: { type: 'string' }, depth: { type: 'integer', default: 2 } }, required: ['topic'] },
-    },
-    {
-      name: 'vektor_delta',
-      description: 'See what changed in memory on a topic recently.',
-      inputSchema: { type: 'object', properties: { topic: { type: 'string' }, days: { type: 'integer', default: 7 } }, required: ['topic'] },
-    },
-    {
-      name: 'vektor_briefing',
-      description: 'Generate a briefing summary from recent memories.',
-      inputSchema: { type: 'object', properties: {} },
-    },
-  ];
-
-  async function runTool(name, input) {
-    const mem = await getMemory();
-    switch (name) {
-      case 'vektor_recall': {
-        const results = await mem.recall(input.query, input.top_k || 5);
-        return { results: (results || []).map(r => ({ id: r.id, content: r.content, score: r.score })) };
-      }
-      case 'vektor_store': {
-        const { id } = await mem.remember(input.content, { importance: input.importance || 3 });
-        return { id, stored: true };
-      }
-      case 'vektor_graph':    return await mem.graph(input.topic, input.depth || 2);
-      case 'vektor_delta':    return await mem.delta(input.topic, input.days || 7);
-      case 'vektor_briefing': return { briefing: await mem.briefing() };
-      default: throw new Error(`Unknown tool: ${name}`);
-    }
-  }
-
-  process.stdin.setEncoding('utf8');
-  let buffer = '';
-  const send = obj => process.stdout.write(JSON.stringify(obj) + '\n');
-
-  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;
-      let req;
-      try { req = JSON.parse(line); } catch {
-        send({ jsonrpc: '2.0', id: null, error: { code: -32700, message: 'Parse error' } });
-        continue;
-      }
-      if (req.method?.startsWith('notifications/')) continue;
-      try {
-        switch (req.method) {
-          case 'initialize':
-            send({ jsonrpc: '2.0', id: req.id, result: {
-              protocolVersion: '2024-11-05',
-              serverInfo: { name: 'vektor-slipstream', version: '1.3.9' },
-              capabilities: { tools: { listChanged: false } },
-            }});
-            break;
-          case 'tools/list':
-            send({ jsonrpc: '2.0', id: req.id, result: { tools: TOOLS } });
-            break;
-          case 'tools/call': {
-            const { name, arguments: args } = req.params;
-            const result = await runTool(name, args || {});
-            send({ jsonrpc: '2.0', id: req.id, result: {
-              content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
-              isError: false,
-            }});
-            break;
-          }
-          default:
-            send({ jsonrpc: '2.0', id: req.id, error: { code: -32601, message: `Method not found: ${req.method}` }});
-        }
-      } catch(e) {
-        send({ jsonrpc: '2.0', id: req.id, error: { code: -32603, message: e.message }});
-      }
-    }
-  });
-  process.stdin.on('end', () => process.exit(0));
-  process.on('uncaughtException', e => process.stderr.write('[vektor-mcp] ' + e.message + '\n'));
-
-} else {
-  // ── Direct chat mode with auto-memory ───────────────────────────────────────
-  const Anthropic = require('@anthropic-ai/sdk');
-
-  async function main() {
-    const memory   = await getMemory();
-    const client   = new Anthropic();
-    const messages = [];
-
-    // Morning briefing
-    const brief = await memory.briefing().catch(() => '');
-
-    const systemPrompt = [
-      'You are a helpful assistant with persistent memory via VEKTOR Slipstream.',
-      'Your memory persists across all sessions — you remember everything.',
-      brief ? `\nMEMORY BRIEFING (last 24h):\n${brief}` : '',
-      '\nWhen the user shares preferences, decisions, or important facts — they are automatically remembered.',
-      'Recall relevant context before answering. Store important new facts as they arise.',
-    ].filter(Boolean).join('\n');
-
-    console.log('\n🧠 VEKTOR Memory active — all conversations stored in MAGMA graph');
-    console.log('Type your message (Ctrl+C to exit)\n');
-
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-
-    const ask = () => rl.question('You: ', async userInput => {
-      if (!userInput.trim()) return ask();
-
-      // Auto-recall before responding
-      const recalled = await memory.recall(userInput, 5).catch(() => []);
-      const context  = recalled.length
-        ? '\n\nRELEVANT MEMORY:\n' + recalled.map(r => `- ${r.content} (score: ${r.score?.toFixed(2)})`).join('\n')
-        : '';
-
-      messages.push({ role: 'user', content: userInput + context });
-
-      try {
-        const res = await client.messages.create({
-          model:      'claude-opus-4-5',
-          max_tokens: 1024,
-          system:     systemPrompt,
-          messages,
-        });
-
-        const reply = res.content[0].text;
-        console.log(`\nClaude: ${reply}\n`);
-        messages.push({ role: 'assistant', content: reply });
-
-        // Auto-store the exchange into MAGMA graph
-        await autoStore(memory, userInput, reply);
-
-      } catch (err) {
-        console.error('API error:', err.message);
-      }
-
-      ask();
-    });
-  }
-
-  main().catch(console.error);
-}

package/examples/example-langchain-researcher.js

@@ -1,82 +0,0 @@
-'use strict';
-/**
- * example-langchain-researcher.js — VEKTOR Slipstream + LangChain
- * ─────────────────────────────────────────────────────────────────────────────
- * Auto-memory: agent context, research results, and decisions flow
- * into the MAGMA graph automatically after every run.
- *
- * Usage:
- *   OPENAI_API_KEY=sk-... VEKTOR_LICENCE_KEY=... node example-langchain-researcher.js
- */
-
-const { createMemory }                                    = require('vektor-slipstream');
-const { ChatOpenAI }                                      = require('@langchain/openai');
-const { AgentExecutor, createOpenAIFunctionsAgent }       = require('langchain/agents');
-const { TavilySearchResults }                             = require('@langchain/community/tools/tavily_search');
-const { ChatPromptTemplate, MessagesPlaceholder }         = require('@langchain/core/prompts');
-const readline                                            = require('readline');
-
-async function main() {
-  // ── Init VEKTOR memory ──────────────────────────────────────────────────────
-  const memory = await createMemory({
-    agentId:    process.env.SLIPSTREAM_AGENT_ID || 'langchain-vektor',
-    licenceKey: process.env.VEKTOR_LICENCE_KEY,
-    dbPath:     process.env.VEKTOR_DB_PATH,
-    silent:     true,
-  });
-
-  const brief = await memory.briefing().catch(() => '');
-  console.log('\n🧠 VEKTOR Memory active — research stored in MAGMA graph');
-  if (brief) console.log(`\nBriefing: ${brief}\n`);
-
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-
-  const ask = () => rl.question('\nResearch topic (Ctrl+C to exit): ', async topic => {
-    if (!topic.trim()) return ask();
-
-    // ── Recall prior research on this topic ─────────────────────────────────
-    const prior     = await memory.recall(topic, 5).catch(() => []);
-    const priorText = prior.length
-      ? 'PRIOR RESEARCH:\n' + prior.map(r => `- ${r.content}`).join('\n')
-      : 'No prior research found on this topic.';
-
-    // ── Build 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 research agent with persistent memory.\n\n${priorText}\n\nBuild on prior research. Identify new findings. Be concise.`],
-      ['human', '{input}'],
-      new MessagesPlaceholder('agent_scratchpad'),
-    ]);
-
-    const agent    = await createOpenAIFunctionsAgent({ llm, tools, prompt });
-    const executor = new AgentExecutor({ agent, tools, verbose: false });
-
-    try {
-      console.log(`\nResearching: ${topic}...`);
-      const result = await executor.invoke({ input: topic });
-
-      console.log(`\nFindings:\n${result.output}\n`);
-
-      // ── Auto-store findings into MAGMA graph ─────────────────────────────
-      await memory.remember(`Research topic: ${topic}`, { importance: 3 }).catch(() => {});
-      await memory.remember(`Research findings: ${result.output.slice(0, 500)}`, { importance: 4 }).catch(() => {});
-
-      // Store key sentences as individual memories for better graph connectivity
-      const sentences = result.output.split(/[.!?]+/).filter(s => s.trim().length > 40);
-      for (const sentence of sentences.slice(0, 5)) {
-        await memory.remember(sentence.trim(), { importance: 2 }).catch(() => {});
-      }
-
-      console.log(`✓ ${sentences.slice(0, 5).length + 2} memories stored in MAGMA graph`);
-
-    } catch (err) {
-      console.error('Agent error:', err.message);
-    }
-
-    ask();
-  });
-}
-
-main().catch(console.error);

package/examples/example-openai-assistant.js

@@ -1,84 +0,0 @@
-'use strict';
-/**
- * example-openai-assistant.js — VEKTOR Slipstream + OpenAI
- * ─────────────────────────────────────────────────────────────────────────────
- * Auto-memory: every conversation turn flows into the MAGMA graph.
- * No setup required — memory just works from the first message.
- *
- * Usage:
- *   OPENAI_API_KEY=sk-... VEKTOR_LICENCE_KEY=... node example-openai-assistant.js
- */
-
-const { createMemory } = require('vektor-slipstream');
-const OpenAI           = require('openai');
-const readline         = require('readline');
-
-// ── Heuristic: importance scoring ────────────────────────────────────────────
-function scoreImportance(text) {
-  const t = text.toLowerCase();
-  if (/prefer|always|never|my name|i am|i'm a|i work|my project|deadline|critical|remember/.test(t)) return 4;
-  if (/project|build|using|stack|deploy|api|database|decided|going with|language|framework/.test(t)) return 3;
-  if (text.length > 80) return 2;
-  return null;
-}
-
-async function main() {
-  const memory = await createMemory({
-    agentId:    process.env.SLIPSTREAM_AGENT_ID || 'openai-vektor',
-    licenceKey: process.env.VEKTOR_LICENCE_KEY,
-    dbPath:     process.env.VEKTOR_DB_PATH,
-    silent:     true,
-  });
-
-  const client   = new OpenAI();
-  const messages = [];
-
-  // Boot briefing — inject yesterday's context
-  const brief = await memory.briefing().catch(() => '');
-  const system = [
-    'You are a helpful assistant with persistent memory. You remember everything across sessions.',
-    brief ? `\nMEMORY BRIEFING:\n${brief}` : '',
-  ].filter(Boolean).join('\n');
-
-  console.log('\n🧠 VEKTOR Memory active — conversations stored in MAGMA graph');
-  console.log('Type your message (Ctrl+C to exit)\n');
-
-  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-
-  const ask = () => rl.question('You: ', async userInput => {
-    if (!userInput.trim()) return ask();
-
-    // Auto-recall relevant context
-    const recalled = await memory.recall(userInput, 5).catch(() => []);
-    const context  = recalled.length
-      ? '\n\n[MEMORY CONTEXT]\n' + recalled.map(r => `- ${r.content}`).join('\n') + '\n[/MEMORY CONTEXT]'
-      : '';
-
-    messages.push({ role: 'user', content: userInput + context });
-
-    try {
-      const res   = await client.chat.completions.create({ model: 'gpt-4o-mini', messages: [{ role: 'system', content: system }, ...messages] });
-      const reply = res.choices[0].message.content;
-
-      console.log(`\nAssistant: ${reply}\n`);
-      messages.push({ role: 'assistant', content: reply });
-
-      // Auto-store user input if memorable
-      const imp = scoreImportance(userInput);
-      if (imp) await memory.remember(userInput, { importance: imp }).catch(() => {});
-
-      // Always store the exchange summary
-      await memory.remember(
-        `Exchange — User: ${userInput.slice(0, 150)} | Assistant: ${reply.slice(0, 200)}`,
-        { importance: 2 }
-      ).catch(() => {});
-
-    } catch (err) {
-      console.error('API error:', err.message);
-    }
-
-    ask();
-  });
-}
-
-main().catch(console.error);

package/examples/examples-README.md

@@ -1,161 +0,0 @@
-# VEKTOR Slipstream — Production Agent Examples
-
-Three complete, copyable agents built on the Slipstream memory API.
-Each works out of the box — adapt the agent logic, keep the memory layer.
-
----
-
-## Quick Start
-
-```bash
-npm install vektor-slipstream
-```
-
-All three examples use the same two-line memory setup:
-
-```js
-const { createMemory } = require('vektor-slipstream');
-const memory = await createMemory({ agentId: 'my-agent' });
-```
-
----
-
-## Example 1 — LangChain Researcher
-
-`example-langchain-researcher.js`
-
-A research agent that searches the web, summarises findings, and builds
-a persistent knowledge base that grows smarter with every run.
-
-**What it does:**
-- Recalls prior research before starting a new search
-- Runs a LangChain agent with Tavily web search
-- Stores the full summary and each key finding separately
-- Prints a memory briefing showing everything learned today
-
-**Install:**
-```bash
-npm install vektor-slipstream langchain @langchain/openai @langchain/community
-```
-
-**Run:**
-```bash
-OPENAI_API_KEY=sk-... TAVILY_API_KEY=tvly-... \
-  node example-langchain-researcher.js "quantum computing breakthroughs 2025"
-```
-
-**Run again tomorrow** — the agent picks up where it left off.
-
----
-
-## Example 2 — OpenAI Assistant Loop
-
-`example-openai-assistant.js`
-
-An interactive personal assistant that genuinely remembers you across sessions.
-Uses the OpenAI Agents SDK with three memory tools wired in.
-
-**What it does:**
-- Injects a memory briefing into every session
-- Gives the assistant `remember`, `recall`, and `memory_graph` tools
-- Stores important facts automatically as you chat
-- Traverses the memory graph for full context on any topic
-
-**Install:**
-```bash
-npm install vektor-slipstream openai
-```
-
-**Run:**
-```bash
-OPENAI_API_KEY=sk-... node example-openai-assistant.js
-```
-
-**Commands:**
-- Type naturally — the assistant manages memory automatically
-- Type `briefing` to see everything stored in the last 24h
-- Type `exit` to end the session
-
----
-
-## Example 3 — Claude MCP Agent
-
-`example-claude-mcp.js`
-
-Connects Claude to Slipstream via the Model Context Protocol.
-Runs in two modes: as an MCP server for Claude Desktop, or as a
-standalone interactive chat.
-
-**What it does:**
-- Implements `vektor_recall`, `vektor_store`, `vektor_graph`, `vektor_delta` as MCP tools
-- Full stdio MCP server (JSON-RPC 2.0) for Claude Desktop integration
-- Direct chat mode for testing without Claude Desktop
-
-**Install:**
-```bash
-npm install vektor-slipstream @anthropic-ai/sdk
-```
-
-**Direct chat mode:**
-```bash
-ANTHROPIC_API_KEY=sk-ant-... node example-claude-mcp.js
-```
-
-**Claude Desktop MCP mode** — add to `claude_desktop_config.json`:
-```json
-{
-  "mcpServers": {
-    "slipstream": {
-      "command": "node",
-      "args": ["/absolute/path/to/example-claude-mcp.js", "--mcp"],
-      "env": {
-        "SLIPSTREAM_AGENT_ID": "claude-desktop"
-      }
-    }
-  }
-}
-```
-
-Restart Claude Desktop — Slipstream memory tools appear automatically.
-
----
-
-## The Memory API
-
-All three examples use the same four methods:
-
-```js
-// Store a memory
-await memory.remember('User prefers TypeScript over JavaScript', { importance: 3 });
-
-// Recall by semantic similarity
-const results = await memory.recall('coding preferences', 5);
-// → [{ content, score, id, importance }]
-
-// Traverse the graph
-const { nodes, edges } = await memory.graph('TypeScript', { hops: 2 });
-
-// See what changed recently
-const changes = await memory.delta('project status', 7); // last 7 days
-
-// Morning briefing
-const brief = await memory.briefing(); // inject into system prompt
-```
-
----
-
-## Each agent gets its own DB
-
-```js
-// Separate memory per agent — no cross-contamination
-const researchMemory  = await createMemory({ agentId: 'researcher', dbPath: './research.db' });
-const assistantMemory = await createMemory({ agentId: 'assistant',  dbPath: './assistant.db' });
-```
-
-Or share memory across agents:
-
-```js
-// Same DB, different agent IDs — memories are scoped per agent
-const scout = await createMemory({ agentId: 'scout', dbPath: './shared.db' });
-const forge = await createMemory({ agentId: 'forge', dbPath: './shared.db' });
-```