zouroboros-memory 3.0.0

package/dist/graph-traversal.js

@@ -0,0 +1,297 @@
+#!/usr/bin/env bun
+/**
+ * graph-traversal.ts — Enhanced Knowledge Graph Traversal
+ * MEM-105: Enhanced Knowledge Graph
+ *
+ * Usage:
+ *   bun graph-traversal.ts ancestors --entity <name>
+ *   bun graph-traversal.ts descendants --entity <name>
+ *   bun graph-traversal.ts cycles
+ *   bun graph-traversal.ts infer --entity <name>
+ *   bun graph-traversal.ts export-dot --entity <name> --output /tmp/graph.dot
+ */
+import { Database } from "bun:sqlite";
+import { writeFileSync } from "fs";
+const DB_PATH = process.env.ZO_MEMORY_DB || "/home/workspace/.zo/memory/shared-facts.db";
+function getDb() {
+    const db = new Database(DB_PATH);
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS relation_types (
+      relation TEXT PRIMARY KEY,
+      description TEXT,
+      inverse TEXT,
+      directed INTEGER NOT NULL DEFAULT 0,
+      category TEXT,
+      created_at INTEGER DEFAULT (strftime('%s','now'))
+    );
+    INSERT OR IGNORE INTO relation_types (relation, description, inverse, directed, category) VALUES
+      ('depends_on', 'A requires B', 'required_by', 1, 'dependency'),
+      ('supersedes', 'A replaces B', 'superseded_by', 1, 'temporal'),
+      ('caused_by', 'A was caused by B', 'causes', 1, 'causal'),
+      ('part_of', 'A is part of B', 'contains', 0, 'structural'),
+      ('related_to', 'A is related to B', 'related_to', 0, 'general'),
+      ('implements', 'A implements B', 'implemented_by', 1, 'dependency'),
+      ('blocks', 'A blocks B', 'blocked_by', 1, 'dependency');
+    CREATE TABLE IF NOT EXISTS graph_cycles (
+      id TEXT PRIMARY KEY,
+      entity_chain TEXT NOT NULL,
+      cycle_length INTEGER NOT NULL,
+      detected_at INTEGER DEFAULT (strftime('%s','now'))
+    );
+    CREATE INDEX IF NOT EXISTS idx_graph_cycles_detected ON graph_cycles(detected_at);
+  `);
+    return db;
+}
+export const KNOWN_RELATIONS = new Set([
+    "depends_on", "required_by", "supersedes", "superseded_by",
+    "caused_by", "causes", "part_of", "contains", "related_to",
+    "implements", "implemented_by", "blocks", "blocked_by",
+]);
+export function getAncestors(db, entity, maxDepth = 10) {
+    const result = [];
+    const visited = new Set();
+    const queue = [{ entity, depth: 0, path: [entity] }];
+    visited.add(entity);
+    while (queue.length > 0) {
+        const { entity: current, depth, path } = queue.shift();
+        if (depth >= maxDepth)
+            continue;
+        // Get all incoming links (things this entity depends on / is caused by / etc.)
+        const rows = db.prepare(`
+      SELECT f.entity, fl.relation, f.id FROM fact_links fl
+      JOIN facts f ON fl.source_id = f.id
+      WHERE fl.target_id = (SELECT MIN(id) FROM facts WHERE entity = ? AND expires_at IS NULL LIMIT 1)
+    `).all(current);
+        // Also check via entity name directly
+        const inbound = db.prepare(`
+      SELECT f.entity, fl.relation FROM fact_links fl
+      JOIN facts f ON fl.source_id = f.id
+      JOIN facts tf ON fl.target_id = tf.id
+      WHERE tf.entity = ?
+    `).all(current);
+        const combined = [...rows, ...inbound];
+        for (const row of combined) {
+            const nextEntity = row.entity;
+            if (visited.has(nextEntity))
+                continue;
+            visited.add(nextEntity);
+            result.push({ entity: nextEntity, relation: row.relation, depth: depth + 1, path: [...path, nextEntity] });
+            queue.push({ entity: nextEntity, depth: depth + 1, path: [...path, nextEntity] });
+        }
+    }
+    return result;
+}
+export function getDescendants(db, entity, maxDepth = 10) {
+    const result = [];
+    const visited = new Set();
+    const queue = [{ entity, depth: 0, path: [entity] }];
+    visited.add(entity);
+    while (queue.length > 0) {
+        const { entity: current, depth, path } = queue.shift();
+        if (depth >= maxDepth)
+            continue;
+        const outbound = db.prepare(`
+      SELECT f.entity, fl.relation FROM fact_links fl
+      JOIN facts f ON fl.target_id = f.id
+      JOIN facts sf ON fl.source_id = sf.id
+      WHERE sf.entity = ?
+    `).all(current);
+        for (const row of outbound) {
+            const nextEntity = row.entity;
+            if (visited.has(nextEntity))
+                continue;
+            visited.add(nextEntity);
+            result.push({ entity: nextEntity, relation: row.relation, depth: depth + 1, path: [...path, nextEntity] });
+            queue.push({ entity: nextEntity, depth: depth + 1, path: [...path, nextEntity] });
+        }
+    }
+    return result;
+}
+export function detectCycles(db) {
+    const allLinks = db.prepare("SELECT source_id, target_id FROM fact_links").all();
+    if (allLinks.length === 0)
+        return [];
+    const adj = new Map();
+    for (const { source_id, target_id } of allLinks) {
+        if (!adj.has(source_id))
+            adj.set(source_id, new Set());
+        adj.get(source_id).add(target_id);
+    }
+    const cycles = [];
+    const visited = new Set();
+    const recStack = new Set();
+    function dfs(node, path) {
+        visited.add(node);
+        recStack.add(node);
+        path.push(node);
+        for (const neighbor of adj.get(node) || []) {
+            if (!visited.has(neighbor)) {
+                dfs(neighbor, path);
+            }
+            else if (recStack.has(neighbor)) {
+                const cycleStart = path.indexOf(neighbor);
+                if (cycleStart >= 0) {
+                    const cycle = path.slice(cycleStart);
+                    cycles.push({ cycle, length: cycle.length });
+                }
+            }
+        }
+        path.pop();
+        recStack.delete(node);
+    }
+    for (const node of adj.keys()) {
+        if (!visited.has(node))
+            dfs(node, []);
+    }
+    // Deduplicate symmetric cycles
+    const seen = new Set();
+    return cycles.filter(c => {
+        const key = c.cycle.join("->");
+        const rev = [...c.cycle].reverse().join("->");
+        if (seen.has(key) || seen.has(rev))
+            return false;
+        seen.add(key);
+        return true;
+    });
+}
+export function inferRelations(db, entity) {
+    // Find facts with the same entity appearing in episodes together
+    const episodeRows = db.prepare(`
+    SELECT DISTINCT e.id FROM episodes e
+    JOIN episode_entities ee ON e.id = ee.episode_id
+    WHERE ee.entity = ?
+  `).all(entity);
+    if (episodeRows.length === 0)
+        return [];
+    const episodeIds = episodeRows.map(r => r.id);
+    const placeholders = episodeIds.map(() => "?").join(",");
+    const coEntities = db.prepare(`
+    SELECT DISTINCT ee2.entity, COUNT(DISTINCT ee2.episode_id) as co_occurrences
+    FROM episode_entities ee1
+    JOIN episode_entities ee2 ON ee1.episode_id = ee2.episode_id
+    WHERE ee1.entity = ? AND ee2.entity != ? AND ee2.episode_id IN (${placeholders})
+    GROUP BY ee2.entity
+    ORDER BY co_occurrences DESC
+    LIMIT 10
+  `).all(entity, entity, ...episodeIds);
+    const totalEpisodes = episodeRows.length;
+    return coEntities.map(r => ({
+        from: entity,
+        to: r.entity,
+        inferred_relation: "related_to",
+        confidence: r.co_occurrences / totalEpisodes,
+        reason: `Co-occurs in ${r.co_occurrences} episode(s) with "${entity}"`,
+    }));
+}
+export function exportDot(db, entity, outputPath) {
+    let links;
+    if (entity) {
+        const rows = db.prepare(`
+      SELECT fl.*, sf.entity as src_entity, tf.entity as tgt_entity
+      FROM fact_links fl
+      JOIN facts sf ON fl.source_id = sf.id
+      JOIN facts tf ON fl.target_id = tf.id
+      WHERE sf.entity = ? OR tf.entity = ?
+    `).all(entity, entity);
+        links = rows;
+    }
+    else {
+        const rows = db.prepare(`
+      SELECT fl.*, sf.entity as src_entity, tf.entity as tgt_entity
+      FROM fact_links fl
+      JOIN facts sf ON fl.source_id = sf.id
+      JOIN facts tf ON fl.target_id = tf.id
+    `).all();
+        links = rows;
+    }
+    const nodes = new Set();
+    for (const l of links) {
+        nodes.add(l.src_entity);
+        nodes.add(l.tgt_entity);
+    }
+    const lines = ["digraph memory_graph {", "  rankdir=LR;", "  node [shape=box];"];
+    for (const node of nodes)
+        lines.push(`  "${node}" [label="${node}"];`);
+    for (const l of links) {
+        lines.push(`  "${l.src_entity}" -> "${l.tgt_entity}" [label="${l.relation}"];`);
+    }
+    lines.push("}");
+    const dot = lines.join("\n");
+    if (outputPath) {
+        writeFileSync(outputPath, dot);
+    }
+    return dot;
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        console.log("Graph Traversal CLI\n\nCommands:\n  ancestors --entity <name>   Find all upstream dependencies\n  descendants --entity <name> Find all downstream dependents\n  cycles                    Detect dependency cycles\n  infer --entity <name>      Infer new relations from co-occurrence\n  export-dot --entity <name> --output <path>  Export to DOT format");
+        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];
+    const db = getDb();
+    if (command === "ancestors") {
+        if (!flags.entity) {
+            console.error("--entity required");
+            process.exit(1);
+        }
+        const ancestors = getAncestors(db, flags.entity);
+        if (ancestors.length === 0) {
+            console.log(`No ancestors for "${flags.entity}".`);
+        }
+        else {
+            ancestors.forEach(a => console.log(`  ${"  ".repeat(a.depth - 1)}--${a.relation}--> ${a.entity}`));
+        }
+    }
+    else if (command === "descendants") {
+        if (!flags.entity) {
+            console.error("--entity required");
+            process.exit(1);
+        }
+        const descendants = getDescendants(db, flags.entity);
+        if (descendants.length === 0) {
+            console.log(`No descendants for "${flags.entity}".`);
+        }
+        else {
+            descendants.forEach(d => console.log(`  ${"  ".repeat(d.depth - 1)}${d.entity} --${d.relation}-->`));
+        }
+    }
+    else if (command === "cycles") {
+        const cycles = detectCycles(db);
+        if (cycles.length === 0) {
+            console.log("No cycles detected.");
+        }
+        else {
+            console.log(`${cycles.length} cycle(s) found:\n`);
+            cycles.forEach((c, i) => console.log(`  ${i + 1}. ${c.cycle.join(" → ")} (${c.length} hops)`));
+        }
+    }
+    else if (command === "infer") {
+        if (!flags.entity) {
+            console.error("--entity required");
+            process.exit(1);
+        }
+        const inferred = inferRelations(db, flags.entity);
+        if (inferred.length === 0) {
+            console.log("No inferred relations.");
+        }
+        else {
+            inferred.forEach(r => console.log(`  ${r.from} --${r.inferred_relation}--> ${r.to} (${(r.confidence * 100).toFixed(0)}% conf)\n    ${r.reason}`));
+        }
+    }
+    else if (command === "export-dot") {
+        const dot = exportDot(db, flags.entity || undefined, flags.output);
+        if (flags.output)
+            console.log(`Exported to ${flags.output}`);
+        else
+            console.log(dot);
+    }
+    db.close();
+}
+if (import.meta.main)
+    main();

package/dist/graph.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Graph-boosted search v2
+ *
+ * Builds an implicit entity graph from facts and episodes,
+ * then uses graph traversal to boost search results for
+ * entities that are closely related to the query context.
+ */
+import type { GraphNode, GraphEdge, MemorySearchResult } from 'zouroboros-core';
+/**
+ * Invalidate the graph cache. Call after mutations (fact store/delete, episode create).
+ */
+export declare function invalidateGraphCache(): void;
+/**
+ * Build a graph of entity co-occurrences from episodes.
+ * Two entities are connected if they appear in the same episode.
+ * Results are cached with a 60-second TTL.
+ */
+export declare function buildEntityGraph(): {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+};
+/**
+ * Get entities related to a given entity via graph traversal.
+ * Returns entities within `depth` hops, scored by connection strength.
+ */
+export declare function getRelatedEntities(entity: string, options?: {
+    depth?: number;
+    limit?: number;
+}): {
+    entity: string;
+    score: number;
+}[];
+/**
+ * Graph-boosted search: augments keyword/vector results with
+ * graph-adjacent facts from related entities.
+ *
+ * Uses RRF fusion across three signals:
+ * 1. Exact/keyword matches (weight: exactWeight)
+ * 2. Vector/semantic matches (weight: vectorWeight)
+ * 3. Graph-adjacent facts (weight: graphWeight)
+ */
+export declare function searchFactsGraphBoosted(baseResults: MemorySearchResult[], queryEntities: string[], options?: {
+    limit?: number;
+    graphWeight?: number;
+    graphDepth?: number;
+}): MemorySearchResult[];
+/**
+ * Extract entity names from a query string.
+ * Simple heuristic: capitalized words, quoted strings, known entities.
+ */
+export declare function extractQueryEntities(query: string): string[];

package/dist/graph.js

@@ -0,0 +1,221 @@
+/**
+ * Graph-boosted search v2
+ *
+ * Builds an implicit entity graph from facts and episodes,
+ * then uses graph traversal to boost search results for
+ * entities that are closely related to the query context.
+ */
+import { getDatabase } from './database.js';
+/** Cached graph with TTL to avoid rebuilding on every search */
+let _graphCache = null;
+const GRAPH_CACHE_TTL_MS = 60_000; // 1 minute
+/**
+ * Invalidate the graph cache. Call after mutations (fact store/delete, episode create).
+ */
+export function invalidateGraphCache() {
+    _graphCache = null;
+}
+/**
+ * Build a graph of entity co-occurrences from episodes.
+ * Two entities are connected if they appear in the same episode.
+ * Results are cached with a 60-second TTL.
+ */
+export function buildEntityGraph() {
+    if (_graphCache && Date.now() - _graphCache.builtAt < GRAPH_CACHE_TTL_MS) {
+        return { nodes: _graphCache.nodes, edges: _graphCache.edges };
+    }
+    const db = getDatabase();
+    // Get all entities that appear in episodes
+    const entityRows = db.query('SELECT DISTINCT entity FROM episode_entities').all();
+    const nodes = entityRows.map(r => ({
+        id: r.entity,
+        type: 'entity',
+        label: r.entity,
+        properties: {},
+    }));
+    // Build edges from co-occurrence in episodes
+    const edgeMap = new Map();
+    const episodes = db.query('SELECT id FROM episodes').all();
+    // For each episode, get all entities and create edges between them
+    const stmt = db.query('SELECT entity FROM episode_entities WHERE episode_id = ?');
+    for (const ep of episodes) {
+        const entities = stmt.all(ep.id).map(r => r.entity);
+        for (let i = 0; i < entities.length; i++) {
+            for (let j = i + 1; j < entities.length; j++) {
+                const key = [entities[i], entities[j]].sort().join('||');
+                edgeMap.set(key, (edgeMap.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    // Also build edges from facts sharing the same entity
+    const factEntities = db.query('SELECT DISTINCT entity FROM facts').all();
+    for (const fe of factEntities) {
+        const existing = nodes.find(n => n.id === fe.entity);
+        if (!existing) {
+            nodes.push({
+                id: fe.entity,
+                type: 'entity',
+                label: fe.entity,
+                properties: {},
+            });
+        }
+    }
+    const edges = Array.from(edgeMap.entries()).map(([key, weight]) => {
+        const [source, target] = key.split('||');
+        return { source, target, relation: 'co-occurs', weight };
+    });
+    _graphCache = { nodes, edges, builtAt: Date.now() };
+    return { nodes, edges };
+}
+/**
+ * Get entities related to a given entity via graph traversal.
+ * Returns entities within `depth` hops, scored by connection strength.
+ */
+export function getRelatedEntities(entity, options = {}) {
+    const { depth = 2, limit = 20 } = options;
+    const { edges } = buildEntityGraph();
+    // BFS with decay
+    const visited = new Map(); // entity → score
+    const queue = [
+        { entity, score: 1.0, hop: 0 },
+    ];
+    visited.set(entity, 1.0);
+    while (queue.length > 0) {
+        const current = queue.shift();
+        if (current.hop >= depth)
+            continue;
+        // Find connected entities
+        for (const edge of edges) {
+            let neighbor = null;
+            if (edge.source === current.entity)
+                neighbor = edge.target;
+            else if (edge.target === current.entity)
+                neighbor = edge.source;
+            if (neighbor && !visited.has(neighbor)) {
+                const decayFactor = 1 / (current.hop + 2); // decay with distance
+                const score = current.score * decayFactor * Math.min(edge.weight, 5) / 5;
+                visited.set(neighbor, score);
+                queue.push({ entity: neighbor, score, hop: current.hop + 1 });
+            }
+        }
+    }
+    // Remove self, sort by score
+    visited.delete(entity);
+    return Array.from(visited.entries())
+        .map(([entity, score]) => ({ entity, score }))
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+}
+/**
+ * Graph-boosted search: augments keyword/vector results with
+ * graph-adjacent facts from related entities.
+ *
+ * Uses RRF fusion across three signals:
+ * 1. Exact/keyword matches (weight: exactWeight)
+ * 2. Vector/semantic matches (weight: vectorWeight)
+ * 3. Graph-adjacent facts (weight: graphWeight)
+ */
+export function searchFactsGraphBoosted(baseResults, queryEntities, options = {}) {
+    const { limit = 10, graphWeight = 0.2, graphDepth = 2 } = options;
+    const db = getDatabase();
+    // Collect related entities from graph
+    const relatedEntities = new Map();
+    for (const entity of queryEntities) {
+        for (const related of getRelatedEntities(entity, { depth: graphDepth })) {
+            const existing = relatedEntities.get(related.entity) ?? 0;
+            relatedEntities.set(related.entity, Math.max(existing, related.score));
+        }
+    }
+    if (relatedEntities.size === 0)
+        return baseResults;
+    // Fetch facts for related entities
+    const entityList = Array.from(relatedEntities.keys());
+    const placeholders = entityList.map(() => '?').join(',');
+    const graphRows = db.query(`
+    SELECT id, entity, key, value, category, decay_class as decayClass,
+           importance, created_at as createdAt
+    FROM facts
+    WHERE entity IN (${placeholders})
+      AND (expires_at IS NULL OR expires_at > strftime('%s', 'now'))
+    ORDER BY importance DESC
+    LIMIT 50
+  `).all(...entityList);
+    // Build graph results scored by entity relationship strength
+    const graphResults = graphRows.map(row => ({
+        entry: {
+            id: row.id,
+            entity: row.entity,
+            key: row.key,
+            value: row.value,
+            decay: row.decayClass,
+            createdAt: new Date(row.createdAt * 1000).toISOString(),
+            updatedAt: new Date(row.createdAt * 1000).toISOString(),
+            tags: row.category ? [row.category] : undefined,
+        },
+        score: relatedEntities.get(row.entity) ?? 0,
+        matchType: 'graph',
+    }));
+    // RRF fusion of base results + graph results
+    const k = 60;
+    const scores = new Map();
+    const baseWeight = 1 - graphWeight;
+    baseResults.forEach((result, rank) => {
+        const rrfScore = (1 / (k + rank + 1)) * baseWeight;
+        scores.set(result.entry.id, {
+            entry: result.entry,
+            score: rrfScore,
+            matchType: result.matchType,
+        });
+    });
+    graphResults
+        .sort((a, b) => b.score - a.score)
+        .forEach((result, rank) => {
+        const rrfScore = (1 / (k + rank + 1)) * graphWeight;
+        const existing = scores.get(result.entry.id);
+        if (existing) {
+            existing.score += rrfScore;
+        }
+        else {
+            scores.set(result.entry.id, {
+                entry: result.entry,
+                score: rrfScore,
+                matchType: 'graph',
+            });
+        }
+    });
+    return Array.from(scores.values())
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit)
+        .map(r => ({
+        entry: r.entry,
+        score: r.score,
+        matchType: r.matchType,
+    }));
+}
+/**
+ * Extract entity names from a query string.
+ * Simple heuristic: capitalized words, quoted strings, known entities.
+ */
+export function extractQueryEntities(query) {
+    const db = getDatabase();
+    const words = query.split(/\s+/);
+    // Check which words match known entities in facts
+    const knownEntities = new Set();
+    const entityRows = db.query('SELECT DISTINCT entity FROM facts').all();
+    const entitySet = new Set(entityRows.map(r => r.entity.toLowerCase()));
+    // Match individual words and bigrams
+    for (let i = 0; i < words.length; i++) {
+        const word = words[i].replace(/[^a-zA-Z0-9_-]/g, '');
+        if (entitySet.has(word.toLowerCase())) {
+            knownEntities.add(word);
+        }
+        // Try bigrams
+        if (i < words.length - 1) {
+            const bigram = `${word} ${words[i + 1].replace(/[^a-zA-Z0-9_-]/g, '')}`;
+            if (entitySet.has(bigram.toLowerCase())) {
+                knownEntities.add(bigram);
+            }
+        }
+    }
+    return Array.from(knownEntities);
+}

package/dist/import-pipeline.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env bun
+/**
+ * zo-memory-system Import Pipeline v1.0
+ *
+ * Import facts from external sources into the memory system.
+ *
+ * Supported sources:
+ *   chatgpt  — ChatGPT JSON export (conversations format)
+ *   obsidian — Obsidian vault (markdown files with frontmatter)
+ *   markdown — Generic markdown files
+ *
+ * Usage:
+ *   bun import.ts --source chatgpt --path ~/export.json
+ *   bun import.ts --source obsidian --path ~/Vault --dry-run
+ *   bun import.ts --source markdown --path ~/notes/file.md
+ */
+export {};