@jeremiaheth/neolata-mem 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jeremiaheth
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# @jeremiaheth/neolata-mem
+
+A-MEM style memory graph engine for AI agents. Semantic auto-linking, decay, conflict resolution, and cross-agent traversal.
+
+## Install
+
+```bash
+npm install @jeremiaheth/neolata-mem
+```
+
+## Quick Start
+
+```js
+import { MemoryGraph, NvidiaEmbeddingProvider, JsonFileStorage, LLMExtractionProvider } 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'
+  })
+});
+
+// Store with auto-linking
+const result = await graph.addWithLinking('agent-1', 'Port 443 is open on target', 'finding', 0.8, ['recon']);
+
+// Semantic search
+const results = await graph.search('open ports', 'agent-1');
+
+// Evolve with conflict resolution
+await graph.evolve('agent-1', 'Port 443 is closed on target', 'finding', 0.9, ['recon']);
+
+// Graph health
+const health = await graph.healthReport();
+```
+
+## Providers
+
+### Embedding
+- `NvidiaEmbeddingProvider` — NVIDIA NIM (baai/bge-m3)
+- `OpenAIEmbeddingProvider` — OpenAI or compatible APIs
+
+### Storage
+- `JsonFileStorage` — local JSON files
+- `SupabaseStorage` — Supabase REST API
+
+### Extraction
+- `LLMExtractionProvider` — any OpenAI-compatible chat API
+- `PassthroughExtractionProvider` — no LLM, wraps text as-is
+
+## API
+
+| 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 |
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,36 @@
+{
+  "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",
+  "type": "module",
+  "main": "src/index.mjs",
+  "exports": {
+    ".": "./src/index.mjs",
+    "./providers/*": "./src/providers/*.mjs"
+  },
+  "files": [
+    "src/",
+    "LICENSE",
+    "README.md"
+  ],
+  "keywords": [
+    "memory-graph",
+    "a-mem",
+    "zettelkasten",
+    "semantic-search",
+    "embeddings",
+    "knowledge-graph",
+    "agent-memory",
+    "decay",
+    "conflict-resolution"
+  ],
+  "author": "Jeremiaheth",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Jeremiaheth/neolata-mem"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/src/index.mjs

@@ -0,0 +1,464 @@
+/**
+ * @jeremiaheth/neolata-mem
+ * 
+ * A-MEM style memory graph engine with:
+ *   - Semantic auto-linking (Zettelkasten)
+ *   - Multi-agent support
+ *   - Memory decay (exponential with reinforcement)
+ *   - Conflict resolution & evolution
+ *   - Graph traversal, clustering, pathfinding
+ *   - Context generation for LLM prompts
+ * 
+ * @license MIT
+ */
+
+export { NvidiaEmbeddingProvider, OpenAIEmbeddingProvider } from './providers/embedding.mjs';
+export { JsonFileStorage, SupabaseStorage } from './providers/storage.mjs';
+export { LLMExtractionProvider, PassthroughExtractionProvider } from './providers/extraction.mjs';
+
+// ============================================================
+// UTILS
+// ============================================================
+
+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));
+}
+
+function genId() {
+  return `mem_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+}
+
+// ============================================================
+// MEMORY GRAPH
+// ============================================================
+
+export class MemoryGraph {
+  /**
+   * @param {Object} opts
+   * @param {import('./providers/embedding.mjs').EmbeddingProvider} opts.embedding
+   * @param {import('./providers/storage.mjs').StorageProvider} opts.storage
+   * @param {import('./providers/extraction.mjs').ExtractionProvider} [opts.extraction]
+   * @param {Object} [opts.config]
+   * @param {number} [opts.config.linkThreshold=0.5] — min cosine similarity for auto-linking
+   * @param {number} [opts.config.maxLinks=5] — max links per memory
+   * @param {number} [opts.config.decayHalfLifeDays=30]
+   * @param {number} [opts.config.archiveThreshold=0.15]
+   * @param {number} [opts.config.deleteThreshold=0.05]
+   */
+  constructor({ embedding, storage, extraction, config = {} } = {}) {
+    if (!embedding) throw new Error('embedding provider is required');
+    if (!storage) throw new Error('storage provider is required');
+    this.embedding = embedding;
+    this.storage = storage;
+    this.extraction = extraction;
+    this.config = {
+      linkThreshold: 0.5,
+      maxLinks: 5,
+      decayHalfLifeDays: 30,
+      archiveThreshold: 0.15,
+      deleteThreshold: 0.05,
+      ...config
+    };
+    this.memories = [];
+    this.loaded = false;
+  }
+
+  async init() {
+    if (this.loaded) return;
+    this.memories = await this.storage.load();
+    this.loaded = true;
+  }
+
+  async save() {
+    await this.storage.save(this.memories);
+  }
+
+  // ── Core: Add with A-MEM linking ─────────────────────────
+
+  async addWithLinking(agent, memory, category, importance, tags) {
+    await this.init();
+    const [emb] = await this.embedding.embed(memory);
+
+    const related = this.memories
+      .filter(m => m.embedding)
+      .map(m => ({ id: m.id, agent: m.agent, sim: cosineSimilarity(emb, m.embedding) }))
+      .filter(m => m.sim > this.config.linkThreshold)
+      .sort((a, b) => b.sim - a.sim)
+      .slice(0, this.config.maxLinks);
+
+    const id = genId();
+    const now = new Date().toISOString();
+
+    this.memories.push({
+      id, agent, memory, category, importance,
+      tags: tags || [],
+      embedding: emb,
+      links: related.map(l => ({ id: l.id, similarity: l.sim })),
+      created_at: now,
+      updated_at: now
+    });
+
+    // Backlinks
+    for (const link of related) {
+      const target = this.memories.find(m => m.id === link.id);
+      if (target) {
+        if (!target.links) target.links = [];
+        if (!target.links.find(l => l.id === id)) {
+          target.links.push({ id, similarity: link.sim });
+        }
+        target.updated_at = now;
+      }
+    }
+
+    await this.save();
+    return {
+      id,
+      links: related.length,
+      topLink: related[0]
+        ? `${related[0].id} (${(related[0].sim * 100).toFixed(1)}%, agent: ${related[0].agent})`
+        : 'none'
+    };
+  }
+
+  // ── Search ───────────────────────────────────────────────
+
+  async search(query, agent = null, limit = 10) {
+    await this.init();
+    const [qEmb] = await this.embedding.embed(query);
+    let candidates = agent ? this.memories.filter(m => m.agent === agent) : this.memories;
+
+    return candidates
+      .filter(m => m.embedding)
+      .map(m => ({ ...m, score: cosineSimilarity(qEmb, m.embedding), embedding: undefined }))
+      .sort((a, b) => b.score - a.score)
+      .slice(0, limit);
+  }
+
+  // ── Links ────────────────────────────────────────────────
+
+  async getLinks(memoryId) {
+    await this.init();
+    const mem = this.memories.find(m => m.id === memoryId);
+    if (!mem) return null;
+    return {
+      memory: mem.memory,
+      agent: mem.agent,
+      links: (mem.links || []).map(link => {
+        const t = this.memories.find(m => m.id === link.id);
+        return { id: link.id, similarity: link.similarity, memory: t?.memory || '(deleted)', agent: t?.agent || '?', category: t?.category || '?' };
+      })
+    };
+  }
+
+  // ── Decay ────────────────────────────────────────────────
+
+  calcStrength(mem) {
+    const now = Date.now();
+    const ageDays = (now - new Date(mem.created_at).getTime()) / 864e5;
+    const lastTouchDays = (now - new Date(mem.updated_at || mem.created_at).getTime()) / 864e5;
+    const base = mem.importance || 0.5;
+    const HL = this.config.decayHalfLifeDays;
+
+    const ageFactor = Math.max(0.1, Math.pow(0.5, ageDays / HL));
+    const touchFactor = Math.max(0.1, Math.pow(0.5, lastTouchDays / (HL * 2)));
+    const linkBonus = Math.min(0.3, (mem.links || []).length * 0.05);
+    const accessBonus = Math.min(0.2, (mem.accessCount || 0) * 0.02);
+    const categoryWeight = { decision: 1.3, preference: 1.4, insight: 1.1 }[mem.category] || 1.0;
+
+    const strength = Math.min(1.0, (base * ageFactor * touchFactor * categoryWeight) + linkBonus + accessBonus);
+    return { strength, ageDays, lastTouchDays, linkCount: (mem.links || []).length, base, ageFactor, touchFactor, categoryWeight };
+  }
+
+  async decay(dryRun = false) {
+    await this.init();
+    const { archiveThreshold: AT, deleteThreshold: DT } = this.config;
+    const report = { total: this.memories.length, healthy: 0, weakening: 0, archived: [], deleted: [], linksClean: 0 };
+    const toArchive = [], toDelete = [];
+
+    for (const mem of this.memories) {
+      const { strength } = this.calcStrength(mem);
+      if (strength < DT) { toDelete.push(mem); report.deleted.push({ id: mem.id, memory: mem.memory.slice(0, 80), strength: strength.toFixed(3), agent: mem.agent }); }
+      else if (strength < AT) { toArchive.push(mem); report.archived.push({ id: mem.id, memory: mem.memory.slice(0, 80), strength: strength.toFixed(3), agent: mem.agent }); }
+      else if (strength < 0.3) report.weakening++;
+      else report.healthy++;
+    }
+
+    if (!dryRun && (toArchive.length || toDelete.length)) {
+      let archived = await this.storage.loadArchive();
+      for (const mem of toArchive) { mem.archived_at = new Date().toISOString(); archived.push(mem); }
+      await this.storage.saveArchive(archived);
+
+      const removeIds = new Set([...toArchive, ...toDelete].map(m => m.id));
+      this.memories = this.memories.filter(m => !removeIds.has(m.id));
+      for (const mem of this.memories) {
+        const before = (mem.links || []).length;
+        mem.links = (mem.links || []).filter(l => !removeIds.has(l.id));
+        report.linksClean += before - mem.links.length;
+      }
+      await this.save();
+    }
+    return report;
+  }
+
+  // ── Reinforce ────────────────────────────────────────────
+
+  async reinforce(memoryId, boost = 0.1) {
+    await this.init();
+    const mem = this.memories.find(m => m.id === memoryId);
+    if (!mem) return null;
+    const oldImportance = mem.importance;
+    mem.importance = Math.min(1.0, (mem.importance || 0.5) + boost);
+    mem.accessCount = (mem.accessCount || 0) + 1;
+    mem.updated_at = new Date().toISOString();
+    await this.save();
+    const { strength } = this.calcStrength(mem);
+    return { id: mem.id, memory: mem.memory, oldImportance, newImportance: mem.importance, accessCount: mem.accessCount, strength: strength.toFixed(3) };
+  }
+
+  // ── Graph traversal ─────────────────────────────────────
+
+  async traverse(startId, maxHops = 2) {
+    await this.init();
+    const start = this.memories.find(m => m.id === startId);
+    if (!start) return null;
+    const visited = new Map();
+    const queue = [{ id: startId, hop: 0, similarity: 1.0 }];
+
+    while (queue.length) {
+      const { id, hop, similarity } = queue.shift();
+      if (visited.has(id)) continue;
+      const mem = this.memories.find(m => m.id === id);
+      if (!mem) continue;
+      visited.set(id, { hop, memory: mem.memory, agent: mem.agent, category: mem.category, importance: mem.importance, similarity, linkCount: (mem.links || []).length });
+      if (hop < maxHops) for (const link of (mem.links || [])) if (!visited.has(link.id)) queue.push({ id: link.id, hop: hop + 1, similarity: link.similarity });
+    }
+
+    return {
+      start: { id: startId, memory: start.memory, agent: start.agent },
+      hops: maxHops,
+      reached: visited.size,
+      nodes: [...visited.entries()].map(([id, data]) => ({ id, ...data })).sort((a, b) => a.hop - b.hop || b.similarity - a.similarity)
+    };
+  }
+
+  // ── Clusters ─────────────────────────────────────────────
+
+  async findClusters(minSize = 2) {
+    await this.init();
+    const visited = new Set();
+    const clusters = [];
+
+    for (const mem of this.memories) {
+      if (visited.has(mem.id)) continue;
+      const cluster = [];
+      const queue = [mem.id];
+      while (queue.length) {
+        const id = queue.shift();
+        if (visited.has(id)) continue;
+        visited.add(id);
+        const m = this.memories.find(x => x.id === id);
+        if (!m) continue;
+        cluster.push({ id: m.id, memory: m.memory, agent: m.agent, category: m.category, importance: m.importance });
+        for (const link of (m.links || [])) if (!visited.has(link.id)) queue.push(link.id);
+      }
+      if (cluster.length >= minSize) {
+        const tagCounts = {}, agentCounts = {};
+        for (const c of cluster) {
+          agentCounts[c.agent] = (agentCounts[c.agent] || 0) + 1;
+          const full = this.memories.find(m => m.id === c.id);
+          for (const tag of (full?.tags || [])) tagCounts[tag] = (tagCounts[tag] || 0) + 1;
+        }
+        clusters.push({ size: cluster.length, agents: agentCounts, topTags: Object.entries(tagCounts).sort((a, b) => b[1] - a[1]).slice(0, 5).map(e => e[0]), memories: cluster });
+      }
+    }
+    return clusters.sort((a, b) => b.size - a.size);
+  }
+
+  // ── Shortest path ────────────────────────────────────────
+
+  async findPath(idA, idB) {
+    await this.init();
+    if (!this.memories.find(m => m.id === idA) || !this.memories.find(m => m.id === idB)) return null;
+    const visited = new Map();
+    const queue = [idA];
+    visited.set(idA, null);
+
+    while (queue.length) {
+      const id = queue.shift();
+      if (id === idB) {
+        const path = [];
+        let cur = idB;
+        while (cur !== null) { const mem = this.memories.find(m => m.id === cur); path.unshift({ id: cur, memory: mem?.memory || '?', agent: mem?.agent || '?', category: mem?.category || '?' }); cur = visited.get(cur); }
+        return { found: true, hops: path.length - 1, path };
+      }
+      const mem = this.memories.find(m => m.id === id);
+      if (mem) for (const link of (mem.links || [])) if (!visited.has(link.id)) { visited.set(link.id, id); queue.push(link.id); }
+    }
+    return { found: false, hops: -1, path: [] };
+  }
+
+  // ── Orphans ──────────────────────────────────────────────
+
+  async findOrphans(agent = null, maxLinks = 0) {
+    await this.init();
+    let candidates = agent ? this.memories.filter(m => m.agent === agent) : this.memories;
+    return candidates
+      .filter(m => (m.links || []).length <= maxLinks)
+      .map(m => { const { strength, ageDays } = this.calcStrength(m); return { id: m.id, memory: m.memory, agent: m.agent, category: m.category, importance: m.importance, links: (m.links || []).length, strength: strength.toFixed(3), ageDays: ageDays.toFixed(1) }; })
+      .sort((a, b) => parseFloat(a.strength) - parseFloat(b.strength));
+  }
+
+  // ── Timeline ─────────────────────────────────────────────
+
+  async timeline(agent = null, days = 7) {
+    await this.init();
+    let mems = agent ? this.memories.filter(m => m.agent === agent) : this.memories;
+    const cutoff = Date.now() - (days * 864e5);
+    mems = mems.filter(m => new Date(m.created_at).getTime() > cutoff);
+    const byDate = {};
+    for (const m of mems) { const d = m.created_at.split('T')[0]; if (!byDate[d]) byDate[d] = []; byDate[d].push({ id: m.id, memory: m.memory, agent: m.agent, category: m.category, importance: m.importance, links: (m.links || []).length }); }
+    return { days, agent, dates: byDate, total: mems.length };
+  }
+
+  // ── Health report ────────────────────────────────────────
+
+  async healthReport() {
+    await this.init();
+    const stats = await this.stats();
+    const dist = { strong: 0, healthy: 0, weakening: 0, critical: 0, dead: 0 };
+    const strengths = [];
+    for (const mem of this.memories) {
+      const { strength } = this.calcStrength(mem);
+      strengths.push(strength);
+      if (strength >= 0.7) dist.strong++; else if (strength >= 0.3) dist.healthy++; else if (strength >= 0.15) dist.weakening++; else if (strength >= 0.05) dist.critical++; else dist.dead++;
+    }
+    const orphans = this.memories.filter(m => (m.links || []).length === 0).length;
+    const archivedCount = (await this.storage.loadArchive()).length;
+    const ages = this.memories.map(m => (Date.now() - new Date(m.created_at).getTime()) / 864e5);
+    return {
+      ...stats,
+      avgStrength: strengths.length ? (strengths.reduce((a, b) => a + b, 0) / strengths.length).toFixed(3) : '0',
+      distribution: dist,
+      orphans,
+      archivedCount,
+      avgAgeDays: ages.length ? (ages.reduce((a, b) => a + b, 0) / ages.length).toFixed(1) : '0',
+      maxAgeDays: ages.length ? Math.max(...ages).toFixed(1) : '0'
+    };
+  }
+
+  // ── Conflict resolution & evolution ──────────────────────
+
+  async detectConflicts(agent, newText) {
+    await this.init();
+    if (!this.extraction) return { conflicts: [], updates: [], novel: true };
+    const [newEmb] = await this.embedding.embed(newText);
+    const candidates = this.memories.filter(m => m.embedding).map(m => ({ ...m, sim: cosineSimilarity(newEmb, m.embedding) })).filter(m => m.sim > 0.6).sort((a, b) => b.sim - a.sim).slice(0, 10);
+    if (!candidates.length) return { conflicts: [], updates: [], novel: true };
+
+    const existing = candidates.map((c, i) => ({ index: i, id: c.id, agent: c.agent, memory: c.memory }));
+    const result = await this.extraction.detectConflicts(newText, existing);
+
+    result.conflicts = (result.conflicts || []).map(c => ({ ...c, memory: candidates[c.index]?.memory, memoryId: candidates[c.index]?.id, agent: candidates[c.index]?.agent, similarity: candidates[c.index]?.sim }));
+    result.updates = (result.updates || []).map(u => ({ ...u, memory: candidates[u.index]?.memory, memoryId: candidates[u.index]?.id, agent: candidates[u.index]?.agent, similarity: candidates[u.index]?.sim }));
+    return result;
+  }
+
+  async evolve(agent, memory, category, importance, tags) {
+    const conflicts = await this.detectConflicts(agent, memory);
+    const actions = [];
+
+    for (const conflict of (conflicts.conflicts || [])) {
+      if (!conflict.memoryId) continue;
+      const old = this.memories.find(m => m.id === conflict.memoryId);
+      if (!old) continue;
+      old.archived_at = new Date().toISOString();
+      old.archived_reason = `Superseded: ${conflict.reason}`;
+      let archived = await this.storage.loadArchive();
+      archived.push({ ...old, embedding: undefined });
+      await this.storage.saveArchive(archived);
+      this.memories = this.memories.filter(m => m.id !== conflict.memoryId);
+      actions.push({ type: 'archived', id: conflict.memoryId, reason: conflict.reason, old: old.memory });
+    }
+
+    for (const update of (conflicts.updates || [])) {
+      if (!update.memoryId) continue;
+      const existing = this.memories.find(m => m.id === update.memoryId);
+      if (!existing) continue;
+      const oldContent = existing.memory;
+      existing.memory = memory;
+      existing.updated_at = new Date().toISOString();
+      existing.importance = Math.max(existing.importance, importance);
+      const [newEmb] = await this.embedding.embed(memory);
+      existing.embedding = newEmb;
+      existing.evolution = existing.evolution || [];
+      existing.evolution.push({ from: oldContent, to: memory, reason: update.reason, at: new Date().toISOString() });
+      await this.save();
+      actions.push({ type: 'updated', id: update.memoryId, reason: update.reason, old: oldContent, new: memory });
+      return { actions, stored: false, evolved: true };
+    }
+
+    const result = await this.addWithLinking(agent, memory, category, importance, tags);
+    actions.push({ type: 'stored', id: result.id, links: result.links });
+    return { actions, stored: true, id: result.id, links: result.links, conflicts: conflicts.conflicts?.length || 0 };
+  }
+
+  // ── Context generation ───────────────────────────────────
+
+  async generateContext(agent, query, maxMemories = 15) {
+    await this.init();
+    const results = await this.search(query, null, 8);
+    const seen = new Set();
+    const contextMems = [];
+
+    for (const r of results) {
+      if (seen.has(r.id)) continue;
+      seen.add(r.id);
+      contextMems.push({ ...r, source: 'direct' });
+      const mem = this.memories.find(m => m.id === r.id);
+      if (mem) for (const link of (mem.links || []).slice(0, 3)) {
+        if (seen.has(link.id)) continue;
+        seen.add(link.id);
+        const linked = this.memories.find(m => m.id === link.id);
+        if (linked) contextMems.push({ id: linked.id, memory: linked.memory, agent: linked.agent, category: linked.category, importance: linked.importance, score: link.similarity * r.score, source: 'linked' });
+      }
+      if (contextMems.length >= maxMemories) break;
+    }
+
+    contextMems.sort((a, b) => (b.score || 0) - (a.score || 0));
+    const top = contextMems.slice(0, maxMemories);
+    if (!top.length) return { query, context: '(no relevant memories found)', count: 0 };
+
+    const lines = [`## Relevant Memory Context (query: "${query}")\n`];
+    const byCategory = {};
+    for (const m of top) { const cat = m.category || 'fact'; if (!byCategory[cat]) byCategory[cat] = []; byCategory[cat].push(m); }
+    for (const cat of ['decision', 'finding', 'preference', 'insight', 'fact', 'event', 'task']) {
+      if (!byCategory[cat]) continue;
+      lines.push(`### ${cat.charAt(0).toUpperCase() + cat.slice(1)}s`);
+      for (const m of byCategory[cat]) { const tag = m.agent !== agent ? ` (${m.agent})` : ''; lines.push(`- ${m.memory}${tag}`); }
+      lines.push('');
+    }
+    return { query, context: lines.join('\n'), count: top.length, memories: top };
+  }
+
+  // ── Stats ────────────────────────────────────────────────
+
+  async stats(agent = null) {
+    await this.init();
+    let mems = agent ? this.memories.filter(m => m.agent === agent) : this.memories;
+    const byAgent = {}, byCategory = {};
+    let totalLinks = 0, crossAgentLinks = 0;
+    for (const m of mems) {
+      byAgent[m.agent] = (byAgent[m.agent] || 0) + 1;
+      byCategory[m.category] = (byCategory[m.category] || 0) + 1;
+      totalLinks += (m.links || []).length;
+      for (const link of (m.links || [])) { const t = this.memories.find(x => x.id === link.id); if (t && t.agent !== m.agent) crossAgentLinks++; }
+    }
+    return { total: mems.length, byAgent, byCategory, totalLinks, crossAgentLinks, avgLinksPerMemory: mems.length ? (totalLinks / mems.length).toFixed(1) : '0' };
+  }
+}

package/src/providers/embedding.mjs

@@ -0,0 +1,72 @@
+/**
+ * Embedding Provider Interface
+ * 
+ * Implementations must provide:
+ *   embed(texts: string[]): Promise<number[][]>  — returns array of embedding vectors
+ */
+
+/**
+ * @typedef {Object} EmbeddingProvider
+ * @property {(texts: string[]) => Promise<number[][]>} embed
+ */
+
+/**
+ * NVIDIA NIM embedding provider (baai/bge-m3)
+ */
+export class NvidiaEmbeddingProvider {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.apiKey — NVIDIA_API_KEY
+   * @param {string} [opts.model] — embedding model (default: baai/bge-m3)
+   * @param {string} [opts.baseUrl] — API base URL
+   */
+  constructor({ apiKey, model = 'baai/bge-m3', baseUrl = 'https://integrate.api.nvidia.com/v1/embeddings' } = {}) {
+    if (!apiKey) throw new Error('apiKey is required');
+    this.apiKey = apiKey;
+    this.model = model;
+    this.baseUrl = baseUrl;
+  }
+
+  /** @param {string|string[]} texts */
+  async embed(texts) {
+    const input = Array.isArray(texts) ? texts : [texts];
+    const res = await fetch(this.baseUrl, {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${this.apiKey}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ model: this.model, input })
+    });
+    if (!res.ok) {
+      if (res.status === 429) {
+        await new Promise(r => setTimeout(r, 2000));
+        return this.embed(texts);
+      }
+      throw new Error(`Embedding failed: ${res.status} ${await res.text()}`);
+    }
+    const data = await res.json();
+    return data.data.map(d => d.embedding);
+  }
+}
+
+/**
+ * OpenAI-compatible embedding provider
+ */
+export class OpenAIEmbeddingProvider {
+  constructor({ apiKey, model = 'text-embedding-3-small', baseUrl = 'https://api.openai.com/v1/embeddings' } = {}) {
+    if (!apiKey) throw new Error('apiKey is required');
+    this.apiKey = apiKey;
+    this.model = model;
+    this.baseUrl = baseUrl;
+  }
+
+  async embed(texts) {
+    const input = Array.isArray(texts) ? texts : [texts];
+    const res = await fetch(this.baseUrl, {
+      method: 'POST',
+      headers: { 'Authorization': `Bearer ${this.apiKey}`, 'Content-Type': 'application/json' },
+      body: JSON.stringify({ model: this.model, input })
+    });
+    if (!res.ok) throw new Error(`Embedding failed: ${res.status} ${await res.text()}`);
+    const data = await res.json();
+    return data.data.map(d => d.embedding);
+  }
+}

package/src/providers/extraction.mjs

@@ -0,0 +1,119 @@
+/**
+ * Extraction Provider Interface
+ * 
+ * Implementations must provide:
+ *   extractFacts(text: string): Promise<Fact[]>
+ *   detectConflicts(newText: string, existingFacts: string[]): Promise<ConflictResult>
+ * 
+ * Fact: { fact: string, category: string, importance: number, tags: string[] }
+ * ConflictResult: { conflicts: [...], updates: [...], novel: boolean }
+ */
+
+/**
+ * OpenAI-compatible LLM extraction provider
+ * Works with any OpenAI chat completions API (OpenAI, Anthropic via proxy, local LLMs)
+ */
+export class LLMExtractionProvider {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.baseUrl — chat completions endpoint
+   * @param {string} [opts.apiKey] — bearer token
+   * @param {string} [opts.model] — model to use
+   */
+  constructor({ baseUrl, apiKey, model = 'anthropic/claude-haiku-4-5' } = {}) {
+    if (!baseUrl) throw new Error('baseUrl is required');
+    this.baseUrl = baseUrl;
+    this.apiKey = apiKey;
+    this.model = model;
+  }
+
+  async _chat(prompt) {
+    const headers = { 'Content-Type': 'application/json' };
+    if (this.apiKey) headers['Authorization'] = `Bearer ${this.apiKey}`;
+    const res = await fetch(this.baseUrl, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify({
+        model: this.model,
+        messages: [{ role: 'user', content: prompt }],
+        max_tokens: 2000,
+        temperature: 0.1
+      })
+    });
+    if (!res.ok) throw new Error(`LLM request failed: ${res.status}`);
+    const data = await res.json();
+    const content = data.choices?.[0]?.message?.content || '';
+    return content.replace(/```json\n?/g, '').replace(/```\n?/g, '').trim();
+  }
+
+  async extractFacts(text) {
+    const prompt = `You are a precise fact extractor. Extract discrete, atomic facts from the following text. Each fact should be self-contained and include specific details (names, numbers, dates, decisions, preferences).
+
+Output as a JSON array of objects with fields:
+- "fact": the extracted fact (string)
+- "category": one of "decision", "finding", "fact", "insight", "task", "event", "preference"
+- "importance": 0.0 to 1.0 (how important for long-term memory)
+- "tags": array of relevant keywords
+
+Text to extract from:
+${text}
+
+Respond ONLY with the JSON array, no markdown formatting.`;
+
+    try {
+      const json = await this._chat(prompt);
+      return JSON.parse(json);
+    } catch (e) {
+      return [{ fact: text, category: 'fact', importance: 0.5, tags: [] }];
+    }
+  }
+
+  /**
+   * @param {string} newText
+   * @param {{ index: number, id: string, agent: string, memory: string }[]} existing
+   */
+  async detectConflicts(newText, existing) {
+    if (!existing.length) return { conflicts: [], updates: [], novel: true };
+
+    const existingFacts = existing.map((c, i) =>
+      `[${i}] (id:${c.id}, agent:${c.agent}) ${c.memory}`
+    ).join('\n');
+
+    const prompt = `You are a fact-checker. Compare the NEW FACT against EXISTING FACTS and identify:
+1. CONFLICTS: The new fact directly contradicts an existing fact
+2. UPDATES: The new fact is a newer version of an existing fact (same topic, updated info)
+3. NOVEL: The new fact adds genuinely new information
+
+NEW FACT: ${newText}
+
+EXISTING FACTS:
+${existingFacts}
+
+Respond ONLY with a JSON object:
+{
+  "conflicts": [{"index": <number>, "reason": "<why it contradicts>"}],
+  "updates": [{"index": <number>, "reason": "<what changed>"}],
+  "novel": <true|false>
+}`;
+
+    try {
+      const json = await this._chat(prompt);
+      return JSON.parse(json);
+    } catch (e) {
+      return { conflicts: [], updates: [], novel: true, error: e.message };
+    }
+  }
+}
+
+/**
+ * No-op extraction (just wraps text as a single fact, no LLM needed)
+ */
+export class PassthroughExtractionProvider {
+  async extractFacts(text) {
+    return [{ fact: text, category: 'fact', importance: 0.5, tags: [] }];
+  }
+
+  async detectConflicts() {
+    return { conflicts: [], updates: [], novel: true };
+  }
+}

package/src/providers/storage.mjs

@@ -0,0 +1,103 @@
+/**
+ * Storage Provider Interface
+ * 
+ * Implementations must provide:
+ *   load(): Promise<Memory[]>
+ *   save(memories: Memory[]): Promise<void>
+ *   loadArchive(): Promise<Memory[]>
+ *   saveArchive(memories: Memory[]): Promise<void>
+ */
+
+import { readFile, writeFile, mkdir } from 'fs/promises';
+import { join } from 'path';
+import { existsSync } from 'fs';
+
+/**
+ * Local JSON file storage (default)
+ */
+export class JsonFileStorage {
+  /**
+   * @param {string} storePath — directory for graph.json / archived.json
+   */
+  constructor(storePath) {
+    this.storePath = storePath;
+  }
+
+  async load() {
+    await mkdir(this.storePath, { recursive: true });
+    const file = join(this.storePath, 'graph.json');
+    if (!existsSync(file)) return [];
+    let raw = await readFile(file, 'utf8');
+    if (raw.charCodeAt(0) === 0xFEFF) raw = raw.slice(1);
+    return JSON.parse(raw);
+  }
+
+  async save(memories) {
+    const file = join(this.storePath, 'graph.json');
+    await writeFile(file, JSON.stringify(memories, null, 2), 'utf8');
+  }
+
+  async loadArchive() {
+    const file = join(this.storePath, 'archived.json');
+    if (!existsSync(file)) return [];
+    return JSON.parse(await readFile(file, 'utf8'));
+  }
+
+  async saveArchive(memories) {
+    const file = join(this.storePath, 'archived.json');
+    await writeFile(file, JSON.stringify(memories, null, 2), 'utf8');
+  }
+}
+
+/**
+ * Supabase REST storage
+ */
+export class SupabaseStorage {
+  /**
+   * @param {Object} opts
+   * @param {string} opts.url — Supabase project URL
+   * @param {string} opts.key — service_role or anon key
+   * @param {string} [opts.table] — table name (default: memories)
+   */
+  constructor({ url, key, table = 'memories' } = {}) {
+    if (!url || !key) throw new Error('url and key are required');
+    this.url = url;
+    this.key = key;
+    this.table = table;
+    this.headers = {
+      'apikey': key,
+      'Authorization': `Bearer ${key}`,
+      'Content-Type': 'application/json'
+    };
+  }
+
+  async load() {
+    const res = await fetch(`${this.url}/rest/v1/${this.table}?archived_at=is.null&select=*`, {
+      headers: this.headers
+    });
+    if (!res.ok) throw new Error(`Supabase load failed: ${res.status}`);
+    return res.json();
+  }
+
+  async save(memories) {
+    // Upsert all memories
+    const res = await fetch(`${this.url}/rest/v1/${this.table}`, {
+      method: 'POST',
+      headers: { ...this.headers, 'Prefer': 'resolution=merge-duplicates' },
+      body: JSON.stringify(memories)
+    });
+    if (!res.ok) throw new Error(`Supabase save failed: ${res.status}`);
+  }
+
+  async loadArchive() {
+    const res = await fetch(`${this.url}/rest/v1/${this.table}?archived_at=not.is.null&select=*`, {
+      headers: this.headers
+    });
+    if (!res.ok) return [];
+    return res.json();
+  }
+
+  async saveArchive(memories) {
+    await this.save(memories); // Same table, just has archived_at set
+  }
+}