vektor-slipstream 1.0.0

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

package/examples/example-openai-assistant.js

@@ -0,0 +1,195 @@
+/**
+ * example-openai-assistant.js
+ * VEKTOR SLIPSTREAM — OpenAI Agents SDK Assistant Loop Example
+ * ─────────────────────────────────────────────────────────────
+ * A persistent assistant that remembers every conversation.
+ * Uses the OpenAI Agents SDK for tool use and Slipstream for
+ * cross-session memory — the assistant genuinely knows who you
+ * are and what you've discussed before.
+ *
+ * Install:
+ *   npm install vektor-slipstream openai @openai/agents readline
+ *
+ * Usage:
+ *   OPENAI_API_KEY=sk-... node example-openai-assistant.js
+ */
+
+'use strict';
+
+const { createMemory } = require('vektor-slipstream');
+const OpenAI           = require('openai');
+const readline         = require('readline');
+
+// ── Config ────────────────────────────────────────────────────────────────────
+
+const AGENT_ID = 'openai-assistant';
+const MODEL    = 'gpt-4o-mini';
+
+// ── Tools available to the assistant ─────────────────────────────────────────
+
+function buildTools(memory) {
+  return [
+    {
+      type: 'function',
+      function: {
+        name: 'remember',
+        description: 'Store an important fact, preference, or decision in long-term memory. Call this whenever the user shares something worth remembering across sessions.',
+        parameters: {
+          type: 'object',
+          properties: {
+            content: {
+              type: 'string',
+              description: 'The fact or information to remember, written as a clear complete sentence.',
+            },
+            importance: {
+              type: 'number',
+              description: 'Importance score 1-5. Use 5 for critical facts (name, key decisions), 3 for useful context, 1 for minor details.',
+            },
+          },
+          required: ['content'],
+        },
+      },
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'recall',
+        description: 'Search long-term memory for relevant information. Call this when you need context about the user or a topic discussed previously.',
+        parameters: {
+          type: 'object',
+          properties: {
+            query: {
+              type: 'string',
+              description: 'What to search for in memory.',
+            },
+          },
+          required: ['query'],
+        },
+      },
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'memory_graph',
+        description: 'Explore connected memories around a concept. Use this to understand the full context around a topic.',
+        parameters: {
+          type: 'object',
+          properties: {
+            concept: { type: 'string', description: 'The concept to explore.' },
+            hops:    { type: 'number', description: 'How many hops to traverse (1-3). Default 2.' },
+          },
+          required: ['concept'],
+        },
+      },
+    },
+  ];
+}
+
+// ── Tool execution ────────────────────────────────────────────────────────────
+
+async function executeTool(name, args, memory) {
+  switch (name) {
+    case 'remember': {
+      const { id } = await memory.remember(args.content, { importance: args.importance || 2 });
+      return `Stored memory #${id}: "${args.content.slice(0, 80)}${args.content.length > 80 ? '...' : ''}"`;
+    }
+    case 'recall': {
+      const results = await memory.recall(args.query, 5);
+      if (!results.length) return 'No relevant memories found.';
+      return results.map((r, i) =>
+        `${i + 1}. [relevance: ${r.score}] ${r.content}`
+      ).join('\n');
+    }
+    case 'memory_graph': {
+      const { nodes, edges } = await memory.graph(args.concept, { hops: args.hops || 2 });
+      return `Found ${nodes.length} connected memories and ${edges.length} relationships.\n` +
+        nodes.slice(0, 5).map(n => `• ${n.content.slice(0, 100)}`).join('\n');
+    }
+    default:
+      return 'Unknown tool.';
+  }
+}
+
+// ── Main assistant loop ───────────────────────────────────────────────────────
+
+async function main() {
+  console.log('\n[ASSISTANT] Booting Slipstream memory...');
+  const memory = await createMemory({ agentId: AGENT_ID, dbPath: './assistant-memory.db' });
+
+  const client   = new OpenAI();
+  const tools    = buildTools(memory);
+  const messages = [];
+
+  // Inject morning briefing as system context
+  const briefing = await memory.briefing();
+  const systemPrompt = `You are a persistent personal assistant with long-term memory powered by VEKTOR Slipstream.
+
+You have access to tools to remember and recall information across sessions.
+Always recall relevant memories before answering questions about past conversations or the user's context.
+When the user shares important information, use the remember tool to store it.
+
+${briefing}`;
+
+  messages.push({ role: 'system', content: systemPrompt });
+
+  // Terminal interface
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const prompt = () => new Promise(resolve => rl.question('\nYou: ', resolve));
+
+  console.log('\n[ASSISTANT] Ready. Your memories persist across sessions.');
+  console.log('[ASSISTANT] Type "exit" to quit, "briefing" to see memory summary.\n');
+
+  while (true) {
+    const userInput = (await prompt()).trim();
+    if (!userInput) continue;
+    if (userInput.toLowerCase() === 'exit') { rl.close(); break; }
+
+    if (userInput.toLowerCase() === 'briefing') {
+      console.log('\n' + await memory.briefing());
+      continue;
+    }
+
+    messages.push({ role: 'user', content: userInput });
+
+    // Agent loop — handles tool calls automatically
+    let response;
+    while (true) {
+      response = await client.chat.completions.create({
+        model: MODEL,
+        messages,
+        tools,
+        tool_choice: 'auto',
+      });
+
+      const msg = response.choices[0].message;
+      messages.push(msg);
+
+      if (!msg.tool_calls?.length) break; // Done
+
+      // Execute all tool calls
+      const toolResults = await Promise.all(
+        msg.tool_calls.map(async tc => {
+          const args   = JSON.parse(tc.function.arguments);
+          const result = await executeTool(tc.function.name, args, memory);
+          console.log(`  [tool:${tc.function.name}] ${result.slice(0, 120)}`);
+          return {
+            role:         'tool',
+            tool_call_id: tc.id,
+            content:      result,
+          };
+        })
+      );
+      messages.push(...toolResults);
+    }
+
+    const reply = response.choices[0].message.content;
+    console.log(`\nAssistant: ${reply}`);
+  }
+
+  console.log('\n[ASSISTANT] Session ended. Memories saved for next time.');
+}
+
+main().catch(e => {
+  console.error('[ASSISTANT] Error:', e.message);
+  process.exit(1);
+});

package/examples/examples-README.md

@@ -0,0 +1,161 @@
+# 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' });
+```

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "vektor-slipstream",
+  "version": "1.0.0",
+  "description": "Hardware-accelerated persistent memory for AI agents. Local-first, zero cloud dependency, $0 embedding cost.",
+  "main": "slipstream-core.js",
+  "exports": {
+    ".": "./slipstream-core.js",
+    "./db": "./slipstream-db.js",
+    "./embedder": "./slipstream-embedder.js"
+  },
+  "keywords": [
+    "ai", "memory", "agent", "vector", "sqlite", "embeddings",
+    "langchain", "openai", "anthropic", "claude", "mcp",
+    "rag", "persistent-memory", "local-ai", "onnx"
+  ],
+  "author": "VEKTOR Memory <hello@vektormemory.com>",
+  "license": "SEE LICENSE IN LICENSE",
+  "homepage": "https://vektormemory.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Vektor-Memory/Vektor-memory"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "better-sqlite3": "^9.4.3",
+    "onnxruntime-node": "^1.17.3"
+  },
+  "optionalDependencies": {
+    "sqlite-vec-windows-x64": "^0.1.6",
+    "sqlite-vec-darwin-arm64": "^0.1.6",
+    "sqlite-vec-linux-x64": "^0.1.6"
+  },
+  "files": [
+    "slipstream-core.js",
+    "slipstream-db.js",
+    "slipstream-embedder.js",
+    "detect-hardware.js",
+    "models/model_quantized.onnx",
+    "examples/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}