zouroboros-memory 3.0.0

package/dist/multi-hop.js

@@ -0,0 +1,238 @@
+#!/usr/bin/env bun
+/**
+ * multi-hop.ts — Iterative Multi-Hop Retrieval
+ * MEM-003: Iterative Multi-Hop Retrieval
+ *
+ * Performs iterative graph traversal for complex queries that require
+ * multi-step reasoning through the knowledge graph.
+ *
+ * Usage:
+ *   bun multi-hop.ts retrieve --query "What decisions led to our database choice?" --maxHops 3
+ *   bun multi-hop.ts benchmark --query "FFB hosting decisions"
+ *   bun multi-hop.ts explain --factId <id>
+ */
+import { Database } from "bun:sqlite";
+const DB_PATH = process.env.ZO_MEMORY_DB || "/home/workspace/.zo/memory/shared-facts.db";
+const OLLAMA_URL = process.env.OLLAMA_URL || "http://localhost:11434";
+const HYDE_MODEL = process.env.ZO_HYDE_MODEL || "qwen2.5:1.5b";
+function getDb() {
+    const db = new Database(DB_PATH);
+    db.exec("PRAGMA journal_mode = WAL");
+    return db;
+}
+async function ollamaGenerate(prompt) {
+    try {
+        const resp = await fetch(`${OLLAMA_URL}/api/generate`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ model: HYDE_MODEL, prompt, stream: false, options: { temperature: 0.1, num_predict: 300 } }),
+            signal: AbortSignal.timeout(30000),
+        });
+        if (!resp.ok)
+            return "";
+        const data = await resp.json();
+        return data.response?.trim() || "";
+    }
+    catch {
+        return "";
+    }
+}
+async function semanticSearch(query, limit = 5) {
+    const db = getDb();
+    const safeQuery = query.replace(/['"*]/g, "").trim();
+    if (!safeQuery)
+        return [];
+    try {
+        const rows = db.prepare(`
+      SELECT f.id, f.entity, f.key, f.value, rank
+      FROM facts f
+      JOIN facts_fts fts ON f.rowid = fts.rowid
+      WHERE facts_fts MATCH ? AND (f.expires_at IS NULL OR f.expires_at > ?)
+      ORDER BY rank
+      LIMIT ?
+    `).all(safeQuery, Math.floor(Date.now() / 1000), limit);
+        return rows.map(r => ({
+            id: r.id, entity: r.entity,
+            key: r.key, value: r.value,
+            rank: r.rank,
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+function getNeighbors(db, factId) {
+    const rows = db.prepare(`
+    SELECT fl.target_id as id, f.entity, f.key, f.value, fl.relation, fl.weight
+    FROM fact_links fl JOIN facts f ON fl.target_id = f.id
+    WHERE fl.source_id = ? AND (f.expires_at IS NULL OR f.expires_at > ?)
+    UNION ALL
+    SELECT fl.source_id as id, f.entity, f.key, f.value, fl.relation, fl.weight
+    FROM fact_links fl JOIN facts f ON fl.source_id = f.id
+    WHERE fl.target_id = ? AND (f.expires_at IS NULL OR f.expires_at > ?)
+  `).all(factId, Math.floor(Date.now() / 1000), factId, Math.floor(Date.now() / 1000));
+    return rows.map(r => ({
+        id: r.id, entity: r.entity,
+        key: r.key, value: r.value,
+        relation: r.relation, weight: r.weight,
+    }));
+}
+function assessConfidence(results, query) {
+    if (results.length === 0)
+        return 0;
+    const avgRelevance = results.reduce((s, r) => s + r.relevance, 0) / results.length;
+    const diverseEntities = new Set(results.map(r => r.entity)).size;
+    const entityBonus = Math.min(diverseEntities / 3, 1) * 0.2;
+    return Math.min(avgRelevance * 0.7 + entityBonus, 1);
+}
+async function refineQueryForNextHop(originalQuery, gathered) {
+    const factsSummary = gathered.map(r => `[${r.entity}.${r.key || "_"}]: ${r.value.slice(0, 80)}`).join("\n");
+    const prompt = `Original question: "${originalQuery}"
+Facts already found:
+${factsSummary}
+
+What additional information would help answer the original question? Reply with 1-2 specific search terms.`;
+    const refined = await ollamaGenerate(prompt);
+    return refined.replace(/"/g, "").trim().slice(0, 100) || originalQuery;
+}
+async function multiHopRetrieve(query, maxHops = 3, limitPerHop = 5) {
+    const db = getDb();
+    const allResults = [];
+    const seenIds = new Set();
+    let currentQuery = query;
+    let confidence = 0;
+    for (let hop = 0; hop < maxHops; hop++) {
+        const results = await semanticSearch(currentQuery, limitPerHop);
+        for (const r of results) {
+            if (seenIds.has(r.id))
+                continue;
+            seenIds.add(r.id);
+            const neighbors = getNeighbors(db, r.id);
+            let connection = "direct match";
+            let relevance = 1 - (r.rank / (limitPerHop * 2));
+            // Check if connected to existing results
+            for (const n of neighbors) {
+                if (seenIds.has(n.id)) {
+                    connection = `linked via "${n.relation}"`;
+                    relevance = Math.min(relevance + 0.15, 1);
+                    break;
+                }
+            }
+            allResults.push({
+                hop: hop + 1,
+                factId: r.id,
+                entity: r.entity,
+                key: r.key,
+                value: r.value,
+                relevance,
+                connection,
+            });
+        }
+        confidence = assessConfidence(allResults, query);
+        if (confidence >= 0.75)
+            break;
+        if (hop < maxHops - 1) {
+            currentQuery = await refineQueryForNextHop(query, allResults);
+        }
+    }
+    const reasoningPrompt = `Question: "${query}"
+
+Found ${allResults.length} relevant facts across ${allResults.length > 0 ? Math.max(...allResults.map(r => r.hop)) : 0} hops.
+Key findings:
+${allResults.slice(0, 6).map(r => `• [${r.entity}.${r.key || "_"}] ${r.value.slice(0, 100)} (hop ${r.hop}, ${r.connection})`).join("\n")}
+
+Provide a 2-sentence answer to the question.`;
+    const reasoning = await ollamaGenerate(reasoningPrompt);
+    const summary = allResults.length > 0
+        ? `${allResults.length} facts found across ${Math.max(...allResults.map(r => r.hop))} hops. ${reasoning}`
+        : "No results found.";
+    return {
+        query, hopsTaken: Math.max(0, ...allResults.map(r => r.hop)),
+        confidence, allResults, summary, reasoning,
+    };
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0 || args[0] === "help") {
+        console.log(`Multi-Hop Retrieval CLI — v1.0
+
+Commands:
+  retrieve --query "<text>"          Perform iterative multi-hop retrieval
+  retrieve --query "<text>" --maxHops 3 --limit 5
+  benchmark --query "<text>"          Compare multi-hop vs single-shot
+  explain --factId <id>               Show all connections for a fact
+
+Flags:
+  --query    Search query string (required for retrieve/benchmark)
+  --maxHops  Maximum hops (default: 3)
+  --limit    Results per hop (default: 5)
+  --factId   Fact ID for explain command`);
+        process.exit(0);
+    }
+    const flags = {};
+    for (let i = 0; i < args.length; i++) {
+        if (args[i].startsWith("--"))
+            flags[args[i].slice(2)] = args[i + 1] || "";
+    }
+    const command = args[0];
+    if (command === "retrieve" || command === "search") {
+        if (!flags.query) {
+            console.error("--query is required");
+            process.exit(1);
+        }
+        const maxHops = parseInt(flags.maxhops || "3");
+        const limit = parseInt(flags.limit || "5");
+        console.log(`\nMulti-hop retrieval for: "${flags.query}"\n`);
+        const result = await multiHopRetrieve(flags.query, maxHops, limit);
+        console.log(`Hops taken: ${result.hopsTaken} | Confidence: ${(result.confidence * 100).toFixed(0)}%\n`);
+        for (const r of result.allResults) {
+            console.log(`  [Hop ${r.hop}] ${r.entity}.${r.key || "_"}`);
+            console.log(`    ${r.value.slice(0, 120)}${r.value.length > 120 ? "..." : ""}`);
+            console.log(`    ${r.connection} (relevance: ${(r.relevance * 100).toFixed(0)}%)`);
+            console.log();
+        }
+        console.log(`Summary: ${result.reasoning || result.summary}`);
+    }
+    else if (command === "benchmark") {
+        if (!flags.query) {
+            console.error("--query is required");
+            process.exit(1);
+        }
+        const db = getDb();
+        const singleStart = Date.now();
+        const singleResults = await semanticSearch(flags.query, 10);
+        const singleMs = Date.now() - singleStart;
+        const multiStart = Date.now();
+        const multiResult = await multiHopRetrieve(flags.query, 3, 5);
+        const multiMs = Date.now() - multiStart;
+        console.log(`\nBenchmark: "${flags.query}"\n`);
+        console.log(`Single-shot FTS:  ${singleResults.length} results in ${singleMs}ms`);
+        console.log(`Multi-hop:       ${multiResult.allResults.length} results in ${multiMs}ms (${multiResult.hopsTaken} hops, conf ${(multiResult.confidence * 100).toFixed(0)}%)`);
+        console.log(`\nNew facts discovered by multi-hop: ${multiResult.allResults.filter(r => r.hop > 1).length}`);
+    }
+    else if (command === "explain") {
+        if (!flags.factid) {
+            console.error("--factId is required");
+            process.exit(1);
+        }
+        const db = getDb();
+        const fact = db.prepare("SELECT id, entity, key, value FROM facts WHERE id = ?").get(flags.factid);
+        if (!fact) {
+            console.log("Fact not found.");
+            process.exit(0);
+        }
+        console.log(`\n[${fact.entity}.${fact.key || "_"}] ${fact.value}\n`);
+        const neighbors = getNeighbors(db, fact.id);
+        if (neighbors.length === 0) {
+            console.log("No connections.");
+        }
+        else {
+            console.log(`${neighbors.length} connections:\n`);
+            for (const n of neighbors) {
+                console.log(`  --${n.relation}--> [${n.entity}.${n.key || "_"}] ${n.value.slice(0, 80)}`);
+            }
+        }
+    }
+}
+if (import.meta.main)
+    main();

package/dist/profiles.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Cognitive profile tracking for entities (executors, users, subsystems).
+ *
+ * Tracks interaction patterns, performance traits, and preferences
+ * to enable adaptive behavior over time.
+ */
+import type { CognitiveProfile, InteractionRecord } from 'zouroboros-core';
+/**
+ * Get or create a cognitive profile for an entity.
+ */
+export declare function getProfile(entity: string): CognitiveProfile;
+/**
+ * Update traits for an entity (merges with existing).
+ */
+export declare function updateTraits(entity: string, traits: Record<string, number>): void;
+/**
+ * Update preferences for an entity (merges with existing).
+ */
+export declare function updatePreferences(entity: string, preferences: Record<string, string>): void;
+/**
+ * Record an interaction for tracking patterns.
+ */
+export declare function recordInteraction(entity: string, type: 'query' | 'store' | 'search', success: boolean, latencyMs: number): void;
+/**
+ * Get recent interactions for an entity.
+ */
+export declare function getRecentInteractions(entity: string, limit?: number): InteractionRecord[];
+/**
+ * Get performance summary for an entity.
+ */
+export declare function getProfileSummary(entity: string): {
+    entity: string;
+    totalInteractions: number;
+    successRate: number;
+    avgLatencyMs: number;
+    traitCount: number;
+    preferenceCount: number;
+};
+/**
+ * List all known entities with profiles.
+ */
+export declare function listProfiles(): string[];
+/**
+ * Delete a cognitive profile.
+ */
+export declare function deleteProfile(entity: string): boolean;
+/**
+ * Ensure the profile_interactions table exists.
+ * Called during memory system init.
+ */
+export declare function ensureProfileSchema(): void;

package/dist/profiles.js

@@ -0,0 +1,149 @@
+/**
+ * Cognitive profile tracking for entities (executors, users, subsystems).
+ *
+ * Tracks interaction patterns, performance traits, and preferences
+ * to enable adaptive behavior over time.
+ */
+import { getDatabase } from './database.js';
+/**
+ * Get or create a cognitive profile for an entity.
+ */
+export function getProfile(entity) {
+    const db = getDatabase();
+    const row = db.query('SELECT entity, traits, preferences, interaction_count, last_interaction, created_at FROM cognitive_profiles WHERE entity = ?').get(entity);
+    if (row) {
+        return {
+            entity: row.entity,
+            traits: row.traits ? JSON.parse(row.traits) : {},
+            preferences: row.preferences ? JSON.parse(row.preferences) : {},
+            interactionHistory: getRecentInteractions(entity),
+            lastUpdated: row.last_interaction
+                ? new Date(row.last_interaction * 1000).toISOString()
+                : new Date(row.created_at * 1000).toISOString(),
+        };
+    }
+    // Auto-create on first access
+    const now = Math.floor(Date.now() / 1000);
+    db.run('INSERT INTO cognitive_profiles (entity, traits, preferences, interaction_count, last_interaction) VALUES (?, ?, ?, 0, ?)', [entity, '{}', '{}', now]);
+    return {
+        entity,
+        traits: {},
+        preferences: {},
+        interactionHistory: [],
+        lastUpdated: new Date(now * 1000).toISOString(),
+    };
+}
+/**
+ * Update traits for an entity (merges with existing).
+ */
+export function updateTraits(entity, traits) {
+    const db = getDatabase();
+    const profile = getProfile(entity);
+    const merged = { ...profile.traits, ...traits };
+    const now = Math.floor(Date.now() / 1000);
+    db.run('UPDATE cognitive_profiles SET traits = ?, last_interaction = ? WHERE entity = ?', [JSON.stringify(merged), now, entity]);
+}
+/**
+ * Update preferences for an entity (merges with existing).
+ */
+export function updatePreferences(entity, preferences) {
+    const db = getDatabase();
+    const profile = getProfile(entity);
+    const merged = { ...profile.preferences, ...preferences };
+    const now = Math.floor(Date.now() / 1000);
+    db.run('UPDATE cognitive_profiles SET preferences = ?, last_interaction = ? WHERE entity = ?', [JSON.stringify(merged), now, entity]);
+}
+/**
+ * Record an interaction for tracking patterns.
+ */
+export function recordInteraction(entity, type, success, latencyMs) {
+    const db = getDatabase();
+    const now = Math.floor(Date.now() / 1000);
+    // Ensure profile exists
+    getProfile(entity);
+    // Store in interactions table
+    db.run(`INSERT INTO profile_interactions (entity, type, success, latency_ms, timestamp)
+     VALUES (?, ?, ?, ?, ?)`, [entity, type, success ? 1 : 0, latencyMs, now]);
+    // Update aggregate counts
+    db.run('UPDATE cognitive_profiles SET interaction_count = interaction_count + 1, last_interaction = ? WHERE entity = ?', [now, entity]);
+}
+/**
+ * Get recent interactions for an entity.
+ */
+export function getRecentInteractions(entity, limit = 50) {
+    const db = getDatabase();
+    // Check if table exists (it's created by ensureProfileSchema)
+    const tableExists = db.query("SELECT name FROM sqlite_master WHERE type='table' AND name='profile_interactions'").get();
+    if (!tableExists)
+        return [];
+    const rows = db.query('SELECT type, success, latency_ms, timestamp FROM profile_interactions WHERE entity = ? ORDER BY timestamp DESC LIMIT ?').all(entity, limit);
+    return rows.map(row => ({
+        timestamp: new Date(row.timestamp * 1000).toISOString(),
+        type: row.type,
+        success: row.success === 1,
+        latencyMs: row.latency_ms,
+    }));
+}
+/**
+ * Get performance summary for an entity.
+ */
+export function getProfileSummary(entity) {
+    const db = getDatabase();
+    const profile = getProfile(entity);
+    const row = db.query('SELECT interaction_count FROM cognitive_profiles WHERE entity = ?').get(entity);
+    const tableExists = db.query("SELECT name FROM sqlite_master WHERE type='table' AND name='profile_interactions'").get();
+    let successRate = 0;
+    let avgLatencyMs = 0;
+    if (tableExists) {
+        const stats = db.query('SELECT AVG(CAST(success AS REAL)) as sr, AVG(latency_ms) as avg_lat FROM profile_interactions WHERE entity = ?').get(entity);
+        successRate = stats?.sr ?? 0;
+        avgLatencyMs = stats?.avg_lat ?? 0;
+    }
+    return {
+        entity,
+        totalInteractions: row?.interaction_count ?? 0,
+        successRate,
+        avgLatencyMs,
+        traitCount: Object.keys(profile.traits).length,
+        preferenceCount: Object.keys(profile.preferences).length,
+    };
+}
+/**
+ * List all known entities with profiles.
+ */
+export function listProfiles() {
+    const db = getDatabase();
+    const rows = db.query('SELECT entity FROM cognitive_profiles ORDER BY last_interaction DESC').all();
+    return rows.map(r => r.entity);
+}
+/**
+ * Delete a cognitive profile.
+ */
+export function deleteProfile(entity) {
+    const db = getDatabase();
+    const result = db.run('DELETE FROM cognitive_profiles WHERE entity = ?', [entity]);
+    // Clean up interactions if table exists
+    const tableExists = db.query("SELECT name FROM sqlite_master WHERE type='table' AND name='profile_interactions'").get();
+    if (tableExists) {
+        db.run('DELETE FROM profile_interactions WHERE entity = ?', [entity]);
+    }
+    return result.changes > 0;
+}
+/**
+ * Ensure the profile_interactions table exists.
+ * Called during memory system init.
+ */
+export function ensureProfileSchema() {
+    const db = getDatabase();
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS profile_interactions (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      entity TEXT NOT NULL,
+      type TEXT NOT NULL CHECK(type IN ('query', 'store', 'search')),
+      success INTEGER NOT NULL DEFAULT 1,
+      latency_ms REAL NOT NULL DEFAULT 0,
+      timestamp INTEGER NOT NULL DEFAULT (strftime('%s', 'now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_profile_interactions_entity ON profile_interactions(entity, timestamp);
+  `);
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "zouroboros-memory",
+  "version": "3.0.0",
+  "description": "Hybrid SQLite + Vector memory system for Zouroboros",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/marlandoj/zouroboros.git",
+    "directory": "packages/memory"
+  },
+  "bin": {
+    "zouroboros-memory": "./dist/cli.js",
+    "zouroboros-memory-mcp": "./dist/mcp-server.js"
+  },
+  "dependencies": {
+    "zouroboros-core": "2.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.4.0"
+  },
+  "keywords": [
+    "zouroboros",
+    "memory",
+    "sqlite",
+    "vector-search",
+    "embeddings",
+    "episodic-memory"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "bun test src/",
+    "test:coverage": "bun test --coverage src/",
+    "cli": "bun ./src/cli.ts",
+    "mcp": "bun ./src/mcp-server.ts",
+    "typecheck": "tsc --noEmit"
+  }
+}