@jeremiaheth/neolata-mem 0.1.0 → 0.2.0

package/README.md

@@ -1,73 +1,297 @@
-# @jeremiaheth/neolata-mem
+# neolata-mem
 
-A-MEM style memory graph engine for AI agents. Semantic auto-linking, decay, conflict resolution, and cross-agent traversal.
+**Graph-native memory engine for AI agents.** Zettelkasten-inspired linking, biological decay, conflict resolution.
 
-## Install
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen.svg)](https://nodejs.org)
+
+---
+
+No Python. No Docker. No Neo4j. Just `npm install`.
 
 ```bash
 npm install @jeremiaheth/neolata-mem
 ```
 
-## Quick Start
+## Quick Start (3 lines)
 
-```js
-import { MemoryGraph, NvidiaEmbeddingProvider, JsonFileStorage, LLMExtractionProvider } from '@jeremiaheth/neolata-mem';
+```javascript
+import { createMemory } from '@jeremiaheth/neolata-mem';
 
-const graph = new MemoryGraph({
-  embedding: new NvidiaEmbeddingProvider({ apiKey: process.env.NVIDIA_API_KEY }),
-  storage: new JsonFileStorage('./memory-data'),
-  extraction: new LLMExtractionProvider({
-    baseUrl: 'http://localhost:18789/v1/chat/completions',
-    apiKey: process.env.OPENCLAW_TOKEN,
-    model: 'anthropic/claude-haiku-4-5'
-  })
+const mem = createMemory();
+await mem.store('agent-1', 'User prefers dark mode');
+const results = await mem.search('agent-1', 'UI preferences');
+// [{ memory: 'User prefers dark mode', score: 1.0, ... }]
+```
+
+That's it. Zero config. Local JSON storage, keyword search, no API keys needed.
+
+## With Embeddings (Semantic Search)
+
+```javascript
+const mem = createMemory({
+  embeddings: {
+    type: 'openai',
+    apiKey: process.env.OPENAI_API_KEY,
+    model: 'text-embedding-3-small',
+  },
+});
+
+await mem.store('kuro', 'Found XSS vulnerability in login form', { category: 'finding', importance: 0.9 });
+await mem.store('kuro', 'OWASP Top 10 audit completed', { category: 'event' });
+
+const results = await mem.search('kuro', 'security vulnerabilities');
+// Ranked by semantic similarity
+```
+
+Works with any OpenAI-compatible API: **OpenAI, NVIDIA NIM, Ollama, Azure, Groq, Together, etc.**
+
+```javascript
+// NVIDIA NIM (free tier)
+embeddings: {
+  type: 'openai',
+  apiKey: process.env.NVIDIA_API_KEY,
+  model: 'baai/bge-m3',
+  baseUrl: 'https://integrate.api.nvidia.com/v1',
+}
+
+// Local Ollama
+embeddings: {
+  type: 'openai',
+  apiKey: 'ollama',
+  model: 'nomic-embed-text',
+  baseUrl: 'http://localhost:11434/v1',
+}
+```
+
+## Core Concepts
+
+### 🔗 A-MEM Zettelkasten Linking
+
+Every memory automatically links to related memories — bidirectionally. When you store "Redis runs on port 6379", it finds existing memories about Redis, ports, or databases and creates links in both directions.
+
+```javascript
+await mem.store('a', 'Redis runs on port 6379');
+await mem.store('a', 'We use Redis for session caching');  // Auto-links to first memory
+
+const links = await mem.links(memoryId);
+// { memory: 'Redis runs on port 6379', links: [{ memory: 'We use Redis for session caching', similarity: 0.87 }] }
+```
+
+### 🧬 Biological Decay
+
+Memories have a **strength** that decays over time, just like biological memory:
+
+- **Half-life**: 30 days (configurable)
+- **Link reinforcement**: More connections = slower decay (+5% per link, max +30%)
+- **Category stickiness**: Decisions (1.3×) and preferences (1.4×) resist decay
+- **Access boost**: Each reinforcement adds +2% importance
+
+```javascript
+const report = await mem.decay({ dryRun: true });  // Preview what would be pruned
+// { total: 100, healthy: 85, weakening: 10, archived: [...], deleted: [...] }
+
+await mem.decay();  // Archive weak memories, delete dead ones
+```
+
+### ⚔️ Conflict Resolution
+
+Detects contradictions and evolves memories over time (requires LLM):
+
+```javascript
+const mem = createMemory({
+  embeddings: { type: 'openai', apiKey: KEY },
+  llm: { type: 'openai', apiKey: KEY, model: 'gpt-4.1-nano' },
 });
 
-// Store with auto-linking
-const result = await graph.addWithLinking('agent-1', 'Port 443 is open on target', 'finding', 0.8, ['recon']);
+await mem.store('a', 'Server runs on port 3000');
+await mem.evolve('a', 'Server now runs on port 8080');
+// EVOLVED: "Server runs on port 3000" → "Server now runs on port 8080"
+// Old version archived with evolution history
+```
+
+### 🌐 Multi-Agent
 
-// Semantic search
-const results = await graph.search('open ports', 'agent-1');
+Native support for multiple agents with cross-agent search:
 
-// Evolve with conflict resolution
-await graph.evolve('agent-1', 'Port 443 is closed on target', 'finding', 0.9, ['recon']);
+```javascript
+await mem.store('kuro', 'Found SQL injection in /api/users');
+await mem.store('maki', 'Deployed fix for /api/users endpoint');
 
-// Graph health
-const health = await graph.healthReport();
+const results = await mem.searchAll('api users security');
+// Returns memories from both agents, ranked by relevance
 ```
 
-## Providers
+## Graph Queries
+
+```javascript
+// Multi-hop traversal
+const graph = await mem.traverse(memoryId, 3);  // Walk 3 hops from a memory
+
+// Find memory clusters
+const clusters = await mem.clusters(3);  // Connected components with 3+ members
 
-### Embedding
-- `NvidiaEmbeddingProvider` — NVIDIA NIM (baai/bge-m3)
-- `OpenAIEmbeddingProvider` — OpenAI or compatible APIs
+// Shortest path between memories
+const path = await mem.path(idA, idB);
 
-### Storage
-- `JsonFileStorage` — local JSON files
-- `SupabaseStorage` — Supabase REST API
+// Find disconnected memories
+const orphans = await mem.orphans('kuro');
+
+// Health report
+const health = await mem.health();
+// { total, byAgent, byCategory, avgStrength, distribution, orphans, ... }
+
+// Timeline view
+const timeline = await mem.timeline('kuro', 7);  // Last 7 days
+
+// Context generation (for RAG / prompt injection)
+const ctx = await mem.context('kuro', 'database security');
+// Returns formatted briefing with 1-hop expansion from top results
+```
 
-### Extraction
-- `LLMExtractionProvider` — any OpenAI-compatible chat API
-- `PassthroughExtractionProvider` — no LLM, wraps text as-is
+## Configuration
 
-## API
+```javascript
+const mem = createMemory({
+  // Storage backend
+  storage: {
+    type: 'json',         // 'json' (default) | 'memory' (ephemeral)
+    dir: './my-data',     // Custom directory for JSON storage
+  },
+
+  // Embeddings (optional — keyword search works without)
+  embeddings: {
+    type: 'openai',       // 'openai' (any compatible API) | 'noop' (keyword only)
+    apiKey: '...',
+    model: 'text-embedding-3-small',
+    baseUrl: 'https://api.openai.com/v1',
+    extraBody: {},        // Extra params (e.g. { input_type: 'passage' } for NIM)
+  },
+
+  // Fact extraction (optional — enables ingest())
+  extraction: {
+    type: 'llm',          // 'llm' | 'passthrough'
+    apiKey: '...',
+    model: 'gpt-4.1-nano',
+    baseUrl: 'https://api.openai.com/v1',
+  },
+
+  // LLM for conflict resolution (optional — enables evolve())
+  llm: {
+    type: 'openai',
+    apiKey: '...',
+    model: 'gpt-4.1-nano',
+    baseUrl: 'https://api.openai.com/v1',
+  },
+
+  // Graph behavior
+  graph: {
+    linkThreshold: 0.5,        // Min similarity for auto-linking (0-1)
+    maxLinksPerMemory: 5,      // Max auto-links per new memory
+    decayHalfLifeDays: 30,     // Decay half-life
+    archiveThreshold: 0.15,    // Archive below this strength
+    deleteThreshold: 0.05,     // Delete below this strength
+  },
+});
+```
+
+## CLI
+
+```bash
+npx @jeremiaheth/neolata-mem store agent-1 "User prefers dark mode"
+npx @jeremiaheth/neolata-mem search agent-1 "UI preferences"
+npx @jeremiaheth/neolata-mem health
+npx @jeremiaheth/neolata-mem decay --dry-run
+```
+
+Set `OPENAI_API_KEY` or `NVIDIA_API_KEY` for embedding support. See `npx @jeremiaheth/neolata-mem` for all commands.
+
+## API Reference
+
+### `createMemory(opts?) → MemoryGraph`
+
+Factory function. All options are optional — zero-config returns a working instance with JSON storage and keyword search.
+
+### Core Methods
+
+| Method | Description |
+|--------|-------------|
+| `store(agent, text, opts?)` | Store with A-MEM auto-linking |
+| `search(agent, query, opts?)` | Semantic/keyword search (single agent) |
+| `searchAll(query, opts?)` | Cross-agent search |
+| `evolve(agent, text, opts?)` | Store with conflict resolution |
+| `ingest(agent, text, opts?)` | Bulk extract facts and store |
+| `context(agent, query, opts?)` | Generate context briefing |
+
+### Graph Methods
 
 | Method | Description |
 |--------|-------------|
-| `addWithLinking(agent, memory, category, importance, tags)` | Store with A-MEM auto-linking |
-| `search(query, agent?, limit?)` | Semantic search |
-| `evolve(agent, memory, category, importance, tags)` | Store with conflict resolution |
-| `detectConflicts(agent, text)` | Check for contradictions |
-| `decay(dryRun?)` | Run decay cycle |
-| `reinforce(memoryId, boost?)` | Boost a memory |
-| `traverse(startId, maxHops?)` | Multi-hop graph walk |
-| `findClusters(minSize?)` | Detect connected components |
-| `findPath(idA, idB)` | Shortest path |
-| `findOrphans(agent?, maxLinks?)` | Unlinked memories |
-| `timeline(agent?, days?)` | Timeline view |
-| `healthReport()` | Full health report |
-| `generateContext(agent, query, maxMemories?)` | LLM-ready context block |
+| `links(memoryId)` | Get memory and its connections |
+| `traverse(startId, hops?)` | Multi-hop BFS walk |
+| `clusters(minSize?)` | Find connected components |
+| `path(idA, idB)` | Shortest path between memories |
+| `orphans(agent?, maxLinks?)` | Find disconnected memories |
+
+### Lifecycle Methods
+
+| Method | Description |
+|--------|-------------|
+| `decay(opts?)` | Run decay cycle (archive/delete weak memories) |
+| `reinforce(memoryId, boost?)` | Boost memory importance |
+| `health()` | Full health report |
+| `timeline(agent?, days?)` | Date-grouped memory view |
+
+### Advanced: Bring Your Own Providers
+
+```javascript
+import { MemoryGraph } from '@jeremiaheth/neolata-mem';
+
+const graph = new MemoryGraph({
+  storage: myCustomStorage,      // { load, save, loadArchive, saveArchive, genId }
+  embeddings: myCustomEmbedder,  // { embed(texts) → number[][] }
+  extraction: myExtractor,       // { extract(text) → Fact[] }
+  llm: myLLM,                   // { chat(prompt) → string }
+  config: { ... },
+});
+```
+
+## How It Works
+
+```
+Text → [Embed] → [Find Related] → [Link Bidirectionally] → [Store]
+                       ↑
+                 Existing memories
+                 with embeddings
+
+Conflict Detection:
+  New fact → [Embed] → [Find high-similarity] → [LLM: conflict/update/novel?]
+    → CONFLICT: archive old, store new
+    → UPDATE: modify existing in-place (with evolution history)
+    → NOVEL: normal A-MEM store
+
+Decay Cycle:
+  For each memory:
+    strength = (importance × ageFactor × touchFactor × categoryWeight) + linkBonus + accessBonus
+    if strength < 0.05: delete
+    if strength < 0.15: archive
+    Clean up broken links
+```
+
+## Comparison
+
+| Feature | neolata-mem | Mem0 | Letta | Zep |
+|---------|------------|------|-------|-----|
+| Zettelkasten linking | ✅ | ❌ | ❌ | ❌ |
+| Biological decay | ✅ | ❌ | ❌ | ❌ |
+| Graph traversal | ✅ | ❌ | ❌ | ✅ |
+| Multi-agent native | ✅ | ❌ | ❌ | ❌ |
+| Conflict resolution | ✅ | ✅ | ❌ | ❌ |
+| Works offline | ✅ | ✅ | ✅ | ❌ |
+| No Python needed | ✅ | ❌ | ❌ | ❌ |
+| Zero-config start | ✅ | ❌ | ❌ | ❌ |
+| LLM optional | ✅ | ❌ | ❌ | ❌ |
 
 ## License
 
-MIT
+MIT — do whatever you want.

package/cli/index.mjs

@@ -0,0 +1,203 @@
+#!/usr/bin/env node
+/**
+ * neolata-mem CLI
+ * Usage: npx @jeremiaheth/neolata-mem <command> [args]
+ */
+
+import { createMemory } from '../src/index.mjs';
+
+function parseEnvConfig() {
+  const opts = {};
+
+  // Auto-detect embedding provider from env
+  if (process.env.OPENAI_API_KEY) {
+    opts.embeddings = { type: 'openai', apiKey: process.env.OPENAI_API_KEY, model: process.env.NEOLATA_EMBED_MODEL || 'text-embedding-3-small' };
+    opts.llm = { type: 'openai', apiKey: process.env.OPENAI_API_KEY, model: process.env.NEOLATA_LLM_MODEL || 'gpt-4.1-nano' };
+    opts.extraction = { type: 'llm', apiKey: process.env.OPENAI_API_KEY, model: process.env.NEOLATA_LLM_MODEL || 'gpt-4.1-nano' };
+  } else if (process.env.NVIDIA_API_KEY) {
+    opts.embeddings = {
+      type: 'openai', apiKey: process.env.NVIDIA_API_KEY,
+      model: process.env.NEOLATA_EMBED_MODEL || 'baai/bge-m3',
+      baseUrl: 'https://integrate.api.nvidia.com/v1',
+    };
+  }
+
+  if (process.env.NEOLATA_STORAGE_DIR) {
+    opts.storage = { type: 'json', dir: process.env.NEOLATA_STORAGE_DIR };
+  }
+
+  return opts;
+}
+
+async function main() {
+  const [cmd, ...args] = process.argv.slice(2);
+  const mem = createMemory(parseEnvConfig());
+
+  switch (cmd) {
+    case 'store': {
+      const agent = args[0];
+      const text = args[1];
+      const tags = args.slice(2);
+      if (!agent || !text) { console.error('Usage: neolata-mem store <agent> <text> [tags...]'); process.exit(1); }
+      const result = await mem.store(agent, text, { tags });
+      console.log(`✅ Stored: ${result.id} (${result.links} links, top: ${result.topLink})`);
+      break;
+    }
+
+    case 'search': {
+      const agent = args[0];
+      const query = args.slice(1).join(' ');
+      if (!agent || !query) { console.error('Usage: neolata-mem search <agent> <query>'); process.exit(1); }
+      const results = await mem.search(agent, query);
+      for (const r of results) {
+        console.log(`[${r.score.toFixed(3)}] [${r.agent}/${r.category}] ${r.memory}`);
+      }
+      if (!results.length) console.log('No memories found.');
+      break;
+    }
+
+    case 'search-all': {
+      const query = args.join(' ');
+      if (!query) { console.error('Usage: neolata-mem search-all <query>'); process.exit(1); }
+      const results = await mem.searchAll(query);
+      for (const r of results) {
+        console.log(`[${r.score.toFixed(3)}] [${r.agent}/${r.category}] ${r.memory}`);
+      }
+      if (!results.length) console.log('No memories found.');
+      break;
+    }
+
+    case 'evolve': {
+      const agent = args[0];
+      const text = args.slice(1).join(' ');
+      if (!agent || !text) { console.error('Usage: neolata-mem evolve <agent> <text>'); process.exit(1); }
+      const result = await mem.evolve(agent, text);
+      for (const action of result.actions) {
+        if (action.type === 'archived') console.log(`  CONFLICT: Archived "${action.old?.slice(0, 60)}..." — ${action.reason}`);
+        else if (action.type === 'updated') console.log(`  EVOLVED: "${action.old?.slice(0, 50)}..." → "${action.new?.slice(0, 50)}..."`);
+        else if (action.type === 'stored') console.log(`  STORED: ${action.id} (${action.links} links)`);
+      }
+      break;
+    }
+
+    case 'links': {
+      const memId = args[0];
+      if (!memId) { console.error('Usage: neolata-mem links <memory-id>'); process.exit(1); }
+      const data = await mem.links(memId);
+      if (!data) { console.log('Memory not found.'); break; }
+      console.log(`Memory: ${data.memory} (${data.agent})`);
+      console.log(`Links (${data.links.length}):`);
+      for (const l of data.links) {
+        console.log(`  [${(l.similarity * 100).toFixed(1)}%] [${l.agent}/${l.category}] ${l.memory}`);
+      }
+      break;
+    }
+
+    case 'traverse': {
+      const memId = args[0];
+      const hops = parseInt(args[1]) || 2;
+      if (!memId) { console.error('Usage: neolata-mem traverse <memory-id> [hops]'); process.exit(1); }
+      const result = await mem.traverse(memId, hops);
+      if (!result) { console.log('Memory not found.'); break; }
+      console.log(`Traversal from: ${result.start.memory} (${result.start.agent})`);
+      console.log(`Max hops: ${result.hops} | Reached: ${result.reached}\n`);
+      let lastHop = -1;
+      for (const node of result.nodes) {
+        if (node.hop !== lastHop) { console.log(`--- Hop ${node.hop} ---`); lastHop = node.hop; }
+        const sim = node.hop === 0 ? 'origin' : `${(node.similarity * 100).toFixed(1)}%`;
+        console.log(`  [${sim}] [${node.agent}/${node.category}] ${node.memory}`);
+      }
+      break;
+    }
+
+    case 'clusters': {
+      const minSize = parseInt(args[0]) || 3;
+      const clusters = await mem.clusters(minSize);
+      console.log(`Found ${clusters.length} clusters (min size: ${minSize}):\n`);
+      for (let i = 0; i < clusters.length; i++) {
+        const c = clusters[i];
+        console.log(`Cluster ${i + 1}: ${c.size} memories | Agents: ${JSON.stringify(c.agents)} | Tags: ${c.topTags.join(', ') || '(none)'}`);
+        for (const m of c.memories.slice(0, 3)) {
+          console.log(`  [${m.agent}/${m.category}] ${m.memory.slice(0, 90)}`);
+        }
+        if (c.size > 3) console.log(`  ... and ${c.size - 3} more`);
+        console.log();
+      }
+      break;
+    }
+
+    case 'path': {
+      const [idA, idB] = args;
+      if (!idA || !idB) { console.error('Usage: neolata-mem path <id-a> <id-b>'); process.exit(1); }
+      const result = await mem.path(idA, idB);
+      if (!result || !result.found) { console.log('No path found.'); break; }
+      console.log(`Path: ${result.hops} hops\n`);
+      for (let i = 0; i < result.path.length; i++) {
+        const p = result.path[i];
+        const pre = i === 0 ? 'START' : i === result.path.length - 1 ? 'END  ' : `  ${i}  `;
+        console.log(`  ${pre} [${p.agent}/${p.category}] ${p.memory}`);
+        if (i < result.path.length - 1) console.log(`    |`);
+      }
+      break;
+    }
+
+    case 'decay': {
+      const dryRun = args.includes('--dry-run');
+      const report = await mem.decay({ dryRun });
+      console.log(`Decay Report${dryRun ? ' (DRY RUN)' : ''}:`);
+      console.log(`  Total: ${report.total} | Healthy: ${report.healthy} | Weakening: ${report.weakening}`);
+      console.log(`  Archived: ${report.archived.length} | Deleted: ${report.deleted.length} | Links cleaned: ${report.linksClean}`);
+      for (const a of report.archived) console.log(`    [${a.strength}] [${a.agent}] ${a.memory}`);
+      for (const d of report.deleted) console.log(`    [${d.strength}] [${d.agent}] ${d.memory}`);
+      break;
+    }
+
+    case 'health': {
+      const r = await mem.health();
+      console.log(`=== Memory Graph Health ===\n`);
+      console.log(`Memories: ${r.total} active, ${r.archivedCount} archived`);
+      console.log(`By agent: ${JSON.stringify(r.byAgent)}`);
+      console.log(`By category: ${JSON.stringify(r.byCategory)}`);
+      console.log(`Links: ${r.totalLinks} total, ${r.crossAgentLinks} cross-agent, avg ${r.avgLinksPerMemory}/memory`);
+      console.log(`Orphans: ${r.orphans}`);
+      console.log(`Age: avg ${r.avgAgeDays}d, max ${r.maxAgeDays}d`);
+      console.log(`Avg strength: ${r.avgStrength}`);
+      console.log(`Distribution: strong=${r.distribution.strong} healthy=${r.distribution.healthy} weakening=${r.distribution.weakening} critical=${r.distribution.critical} dead=${r.distribution.dead}`);
+      break;
+    }
+
+    case 'context': {
+      const agent = args[0];
+      const query = args.slice(1).join(' ');
+      if (!agent || !query) { console.error('Usage: neolata-mem context <agent> <query>'); process.exit(1); }
+      const result = await mem.context(agent, query);
+      console.log(result.context);
+      break;
+    }
+
+    default:
+      console.log(`neolata-mem — Graph-native memory for AI agents
+
+Commands:
+  store <agent> <text> [tags...]   Store with A-MEM auto-linking
+  search <agent> <query>           Semantic search (single agent)
+  search-all <query>               Cross-agent search
+  evolve <agent> <text>            Store with conflict resolution
+  links <memory-id>                Show memory connections
+  traverse <memory-id> [hops]      Multi-hop graph walk
+  clusters [min-size]              Find memory clusters
+  path <id-a> <id-b>               Shortest path between memories
+  decay [--dry-run]                Run memory decay cycle
+  health                           Full health report
+  context <agent> <query>          Generate context briefing
+
+Environment:
+  OPENAI_API_KEY                   Enables embeddings + LLM features
+  NVIDIA_API_KEY                   Use NVIDIA NIM for embeddings
+  NEOLATA_EMBED_MODEL              Override embedding model
+  NEOLATA_LLM_MODEL                Override LLM model
+  NEOLATA_STORAGE_DIR              Override storage directory`);
+  }
+}
+
+main().catch(e => { console.error(e.message); process.exit(1); });

package/package.json

@@ -1,26 +1,40 @@
 {
   "name": "@jeremiaheth/neolata-mem",
-  "version": "0.1.0",
-  "description": "A-MEM style memory graph engine with semantic linking, decay, conflict resolution, and cross-agent traversal",
+  "version": "0.2.0",
+  "description": "Graph-native memory engine for AI agents with Zettelkasten linking, biological decay, and conflict resolution",
   "type": "module",
   "main": "src/index.mjs",
   "exports": {
     ".": "./src/index.mjs",
-    "./providers/*": "./src/providers/*.mjs"
+    "./graph": "./src/graph.mjs",
+    "./embeddings": "./src/embeddings.mjs",
+    "./storage": "./src/storage.mjs",
+    "./extraction": "./src/extraction.mjs",
+    "./llm": "./src/llm.mjs"
+  },
+  "bin": {
+    "neolata-mem": "./cli/index.mjs"
   },
   "files": [
     "src/",
+    "cli/",
     "LICENSE",
     "README.md"
   ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
   "keywords": [
-    "memory-graph",
-    "a-mem",
+    "ai",
+    "memory",
+    "agent",
     "zettelkasten",
-    "semantic-search",
+    "graph",
     "embeddings",
-    "knowledge-graph",
-    "agent-memory",
+    "rag",
+    "llm",
+    "vector-search",
+    "multi-agent",
     "decay",
     "conflict-resolution"
   ],

package/src/embeddings.mjs

@@ -0,0 +1,68 @@
+/**
+ * Embedding provider interface and implementations.
+ * All providers must implement: embed(texts) → number[][]
+ */
+
+/**
+ * Cosine similarity between two vectors.
+ * @param {number[]} a
+ * @param {number[]} b
+ * @returns {number}
+ */
+export function cosineSimilarity(a, b) {
+  let dot = 0, normA = 0, normB = 0;
+  for (let i = 0; i < a.length; i++) {
+    dot += a[i] * b[i];
+    normA += a[i] * a[i];
+    normB += b[i] * b[i];
+  }
+  return dot / (Math.sqrt(normA) * Math.sqrt(normB));
+}
+
+// ─── OpenAI-Compatible Provider ─────────────────────────────
+/**
+ * Works with OpenAI, NVIDIA NIM, Ollama, Azure, any OpenAI-compatible API.
+ * @param {object} opts
+ * @param {string} opts.apiKey
+ * @param {string} opts.model - e.g. 'text-embedding-3-small', 'baai/bge-m3'
+ * @param {string} [opts.baseUrl='https://api.openai.com/v1'] - API base URL
+ * @param {object} [opts.extraBody] - Extra body params (e.g. { input_type: 'passage' })
+ * @param {number} [opts.retryMs=2000] - Retry delay on 429
+ */
+export function openaiEmbeddings({ apiKey, model, baseUrl = 'https://api.openai.com/v1', extraBody = {}, retryMs = 2000 }) {
+  return {
+    name: `openai-compatible(${model})`,
+    model,
+    async embed(texts) {
+      const input = Array.isArray(texts) ? texts : [texts];
+      const res = await fetch(`${baseUrl}/embeddings`, {
+        method: 'POST',
+        headers: { 'Authorization': `Bearer ${apiKey}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ model, input, ...extraBody }),
+      });
+      if (res.status === 429) {
+        await new Promise(r => setTimeout(r, retryMs));
+        return this.embed(texts);
+      }
+      if (!res.ok) throw new Error(`Embedding ${res.status}: ${await res.text()}`);
+      const data = await res.json();
+      return data.data.map(d => d.embedding);
+    },
+  };
+}
+
+// ─── Noop Provider (keyword-only mode) ──────────────────────
+/**
+ * No-op embedding provider. Returns null embeddings.
+ * Use this when you don't want/need vector search — keyword matching still works.
+ */
+export function noopEmbeddings() {
+  return {
+    name: 'noop',
+    model: null,
+    async embed(texts) {
+      const input = Array.isArray(texts) ? texts : [texts];
+      return input.map(() => null);
+    },
+  };
+}