zouroboros-memory 3.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 marlandoj
+
+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/dist/capture.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Auto-capture integration
+ *
+ * Extracts facts, episodes, and decisions from conversation text
+ * and stores them in memory automatically.
+ */
+import type { MemoryConfig, MemoryEntry, EpisodicMemory } from 'zouroboros-core';
+export interface CaptureResult {
+    facts: MemoryEntry[];
+    episodes: EpisodicMemory[];
+    totalExtracted: number;
+    durationMs: number;
+}
+export interface CaptureOptions {
+    source?: string;
+    entity?: string;
+    conversationId?: string;
+    dryRun?: boolean;
+}
+/**
+ * Extract facts, decisions, and episodes from conversation text.
+ */
+export declare function extractFromText(text: string): {
+    facts: {
+        entity: string;
+        key: string | undefined;
+        value: string;
+        category: string;
+    }[];
+    episodes: {
+        summary: string;
+        outcome: 'success' | 'failure' | 'ongoing';
+        entities: string[];
+    }[];
+};
+/**
+ * Auto-capture: extract and store facts/episodes from conversation text.
+ */
+export declare function autoCapture(text: string, config: MemoryConfig, options?: CaptureOptions): Promise<CaptureResult>;
+/**
+ * Add text to the capture buffer.
+ * Text is accumulated and periodically flushed.
+ */
+export declare function bufferForCapture(text: string): void;
+/**
+ * Start interval-based auto-capture.
+ * Flushes the capture buffer at the configured interval.
+ */
+export declare function startAutoCapture(config: MemoryConfig, options?: CaptureOptions): void;
+/**
+ * Stop interval-based auto-capture and flush remaining buffer.
+ */
+export declare function stopAutoCapture(config: MemoryConfig, options?: CaptureOptions): Promise<CaptureResult | null>;
+/**
+ * Get the current capture buffer size (for diagnostics).
+ */
+export declare function getCaptureBufferSize(): number;

package/dist/capture.js

@@ -0,0 +1,181 @@
+/**
+ * Auto-capture integration
+ *
+ * Extracts facts, episodes, and decisions from conversation text
+ * and stores them in memory automatically.
+ */
+import { storeFact } from './facts.js';
+import { createEpisode } from './episodes.js';
+/**
+ * Pattern matchers for extracting structured information from text.
+ */
+const FACT_PATTERNS = [
+    // "X is Y" / "X are Y"
+    /(?:^|\.\s+)([A-Z][a-zA-Z0-9_ -]+)\s+(?:is|are)\s+(.+?)(?:\.|$)/gm,
+    // "X uses Y" / "X requires Y"
+    /(?:^|\.\s+)([A-Z][a-zA-Z0-9_ -]+)\s+(?:uses?|requires?|depends?\s+on|runs?\s+on)\s+(.+?)(?:\.|$)/gm,
+    // Key-value from "set X to Y" / "changed X to Y"
+    /(?:set|changed?|updated?|configured?)\s+([a-zA-Z_][a-zA-Z0-9_.]+)\s+(?:to|=)\s+(.+?)(?:\.|,|$)/gim,
+];
+const DECISION_PATTERNS = [
+    // "decided to X" / "chose to X" / "will X"
+    /(?:decided?|chose|choosing|will|going)\s+to\s+(.+?)(?:\.|$)/gim,
+    // "instead of X, Y"
+    /instead\s+of\s+(.+?),\s*(.+?)(?:\.|$)/gim,
+];
+const EPISODE_PATTERNS = [
+    // "completed X" / "finished X" / "fixed X"
+    /(?:completed?|finished|fixed|resolved|deployed|implemented|shipped)\s+(.+?)(?:\.|$)/gim,
+    // "failed to X" / "error in X"
+    /(?:failed?\s+to|error\s+in|broke|crashed|bug\s+in)\s+(.+?)(?:\.|$)/gim,
+];
+/**
+ * Extract facts, decisions, and episodes from conversation text.
+ */
+export function extractFromText(text) {
+    const facts = [];
+    const episodes = [];
+    const seen = new Set();
+    // Extract facts
+    for (const pattern of FACT_PATTERNS) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(text)) !== null) {
+            const entity = match[1].trim();
+            const value = match[2].trim();
+            const key = entity + ':' + value;
+            if (!seen.has(key) && entity.length > 1 && value.length > 1) {
+                seen.add(key);
+                facts.push({ entity, key: undefined, value, category: 'fact' });
+            }
+        }
+    }
+    // Extract decisions
+    for (const pattern of DECISION_PATTERNS) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(text)) !== null) {
+            const value = match[1].trim();
+            if (value.length > 5 && !seen.has('decision:' + value)) {
+                seen.add('decision:' + value);
+                facts.push({
+                    entity: 'system',
+                    key: 'decision',
+                    value,
+                    category: 'decision',
+                });
+            }
+        }
+    }
+    // Extract episodes
+    for (const pattern of EPISODE_PATTERNS) {
+        pattern.lastIndex = 0;
+        let match;
+        while ((match = pattern.exec(text)) !== null) {
+            const summary = match[0].trim();
+            const isFailure = /fail|error|broke|crash|bug/i.test(summary);
+            if (summary.length > 5 && !seen.has('ep:' + summary)) {
+                seen.add('ep:' + summary);
+                // Extract capitalized words as entities
+                const entities = Array.from(new Set(summary.match(/[A-Z][a-zA-Z0-9_-]+/g)?.filter(w => w.length > 2) ?? ['system']));
+                episodes.push({
+                    summary,
+                    outcome: isFailure ? 'failure' : 'success',
+                    entities: entities.length > 0 ? entities : ['system'],
+                });
+            }
+        }
+    }
+    return { facts, episodes };
+}
+/**
+ * Auto-capture: extract and store facts/episodes from conversation text.
+ */
+export async function autoCapture(text, config, options = {}) {
+    const start = performance.now();
+    const { source = 'auto-capture', entity: defaultEntity, dryRun = false } = options;
+    const extracted = extractFromText(text);
+    const result = {
+        facts: [],
+        episodes: [],
+        totalExtracted: extracted.facts.length + extracted.episodes.length,
+        durationMs: 0,
+    };
+    if (dryRun) {
+        result.durationMs = performance.now() - start;
+        return result;
+    }
+    // Store facts
+    for (const fact of extracted.facts) {
+        const stored = await storeFact({
+            entity: defaultEntity ?? fact.entity,
+            key: fact.key,
+            value: fact.value,
+            category: fact.category,
+            source,
+            decay: 'medium',
+            importance: fact.category === 'decision' ? 1.5 : 1.0,
+        }, config);
+        result.facts.push(stored);
+    }
+    // Store episodes
+    for (const ep of extracted.episodes) {
+        const stored = createEpisode({
+            summary: ep.summary,
+            outcome: ep.outcome,
+            entities: ep.entities,
+            metadata: options.conversationId ? { conversationId: options.conversationId } : undefined,
+        });
+        result.episodes.push(stored);
+    }
+    result.durationMs = performance.now() - start;
+    return result;
+}
+/**
+ * Capture state for interval-based auto-capture.
+ */
+let captureTimer = null;
+let captureBuffer = [];
+/**
+ * Add text to the capture buffer.
+ * Text is accumulated and periodically flushed.
+ */
+export function bufferForCapture(text) {
+    captureBuffer.push(text);
+}
+/**
+ * Start interval-based auto-capture.
+ * Flushes the capture buffer at the configured interval.
+ */
+export function startAutoCapture(config, options = {}) {
+    if (captureTimer)
+        return;
+    const intervalMs = (config.captureIntervalMinutes ?? 30) * 60 * 1000;
+    captureTimer = setInterval(async () => {
+        if (captureBuffer.length === 0)
+            return;
+        const text = captureBuffer.join('\n\n');
+        captureBuffer = [];
+        await autoCapture(text, config, options);
+    }, intervalMs);
+}
+/**
+ * Stop interval-based auto-capture and flush remaining buffer.
+ */
+export async function stopAutoCapture(config, options = {}) {
+    if (captureTimer) {
+        clearInterval(captureTimer);
+        captureTimer = null;
+    }
+    if (captureBuffer.length === 0)
+        return null;
+    const text = captureBuffer.join('\n\n');
+    captureBuffer = [];
+    return autoCapture(text, config, options);
+}
+/**
+ * Get the current capture buffer size (for diagnostics).
+ */
+export function getCaptureBufferSize() {
+    return captureBuffer.length;
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env bun
+export {};

package/dist/cli.js

@@ -0,0 +1,91 @@
+#!/usr/bin/env bun
+import { parseArgs } from 'util';
+import { join } from 'path';
+import { VERSION } from './index.js';
+const { values, positionals } = parseArgs({
+    args: process.argv.slice(2),
+    options: {
+        stats: { type: 'boolean', short: 's' },
+        version: { type: 'boolean', short: 'v' },
+        help: { type: 'boolean', short: 'h' },
+    },
+    strict: false,
+    allowPositionals: true,
+});
+function printHelp() {
+    console.log(`
+zouroboros-memory v${VERSION} — Hybrid SQLite + Vector memory system
+
+USAGE:
+  zouroboros-memory [options]
+  zouroboros-memory <command> [args]
+
+OPTIONS:
+  --stats, -s    Show memory database statistics
+  --version, -v  Show version
+  --help, -h     Show this help
+
+COMMANDS (v4 enhancements):
+  metrics [report|record|clear]     Memory system metrics dashboard (MEM-101)
+  import --source <type> --path <p> Import from external sources (MEM-102)
+  budget [init|status|track|reset]  Context budget tracking (MEM-001)
+  summarize [args]                  Episode summarization (MEM-002)
+  multi-hop [retrieve|benchmark]    Multi-hop retrieval (MEM-003)
+  conflicts [detect|resolve|stats]  Conflict resolution (MEM-103)
+  cross-persona [args]              Cross-persona memory (MEM-104)
+  graph-traversal [args]            Graph traversal tools (MEM-105)
+  embed-bench [compare|benchmark]   Embedding model benchmark (MEM-202)
+
+PROGRAMMATIC USAGE:
+  import { init, storeFact, searchFacts } from 'zouroboros-memory';
+`);
+}
+if (values.help) {
+    printHelp();
+    process.exit(0);
+}
+if (values.version) {
+    console.log(`zouroboros-memory v${VERSION}`);
+    process.exit(0);
+}
+if (values.stats) {
+    console.log('Memory system statistics:');
+    console.log('  Run "zouroboros doctor" for a full health check.');
+    console.log('  Or use the programmatic API: import { getStats } from "zouroboros-memory"');
+    process.exit(0);
+}
+// v4 subcommand routing — delegates to individual script CLIs
+const command = positionals[0];
+if (command) {
+    const { execSync } = require('child_process');
+    const srcDir = import.meta.dir;
+    const subArgs = process.argv.slice(3).join(' ');
+    const commandMap = {
+        'metrics': 'metrics.ts',
+        'import': 'import-pipeline.ts',
+        'budget': 'context-budget.ts',
+        'summarize': 'episode-summarizer.ts',
+        'multi-hop': 'multi-hop.ts',
+        'conflicts': 'conflict-resolver.ts',
+        'cross-persona': 'cross-persona.ts',
+        'graph-traversal': 'graph-traversal.ts',
+        'embed-bench': 'embedding-benchmark.ts',
+    };
+    const scriptFile = commandMap[command];
+    if (scriptFile) {
+        const scriptPath = join(srcDir, scriptFile);
+        try {
+            execSync(`bun "${scriptPath}" ${subArgs}`, { stdio: 'inherit' });
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            console.error(`Command "${command}" failed: ${msg}`);
+            process.exit(1);
+        }
+        process.exit(0);
+    }
+    console.error(`Unknown command: ${command}`);
+    printHelp();
+    process.exit(1);
+}
+printHelp();

package/dist/conflict-resolver.d.ts

@@ -0,0 +1,55 @@
+#!/usr/bin/env bun
+/**
+ * conflict-resolver.ts — Memory Conflict Detection & Resolution
+ * MEM-103: Memory Conflict Resolution
+ *
+ * Usage:
+ *   bun conflict-resolver.ts detect --entity <name>
+ *   bun conflict-resolver.ts resolve --id <conflictId> --strategy supersede|flag
+ *   bun conflict-resolver.ts history --entity <name> --key <key>
+ */
+import { Database } from "bun:sqlite";
+export type ConflictType = "semantic" | "temporal" | "exact";
+export type ResolutionStrategy = "supersede" | "merge" | "flag" | "pending";
+export interface ConflictRecord {
+    id: string;
+    factId: string;
+    conflictingFactId: string;
+    conflictType: ConflictType;
+    resolution: ResolutionStrategy | null;
+    fact1Value: string;
+    fact2Value: string;
+    createdAt: number;
+}
+export interface ProvenanceRecord {
+    id: string;
+    factId: string;
+    source: string;
+    capturedAt: number;
+    captureMethod?: string;
+    supersededBy?: string;
+    supersededAt?: number;
+    effectiveFrom: number;
+    effectiveUntil?: number;
+}
+export declare function isContradiction(fact1: {
+    value: string;
+    entity: string;
+    key: string | null;
+}, fact2: {
+    value: string;
+    entity: string;
+    key: string | null;
+}): Promise<boolean>;
+export declare function findEntityConflicts(db: Database, entity: string): ConflictRecord[];
+export declare function detectNewConflict(db: Database, entity: string, key: string | null, newValue: string): Promise<ConflictRecord | null>;
+export declare function resolveConflict(db: Database, conflictId: string, strategy: ResolutionStrategy): void;
+export declare function resolveAllPending(db: Database, strategy?: ResolutionStrategy): number;
+export declare function trackProvenance(db: Database, factId: string, source: string, captureMethod?: string): void;
+export declare function getProvenance(db: Database, factId: string): ProvenanceRecord[];
+export declare function getFactHistory(db: Database, entity: string, key: string | null): Array<{
+    id: string;
+    value: string;
+    effectiveFrom: number;
+    superseded: boolean;
+}>;

package/dist/conflict-resolver.js

@@ -0,0 +1,221 @@
+#!/usr/bin/env bun
+/**
+ * conflict-resolver.ts — Memory Conflict Detection & Resolution
+ * MEM-103: Memory Conflict Resolution
+ *
+ * Usage:
+ *   bun conflict-resolver.ts detect --entity <name>
+ *   bun conflict-resolver.ts resolve --id <conflictId> --strategy supersede|flag
+ *   bun conflict-resolver.ts history --entity <name> --key <key>
+ */
+import { Database } from "bun:sqlite";
+import { randomUUID } from "crypto";
+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";
+function getDb() {
+    const db = new Database(DB_PATH);
+    db.exec("PRAGMA journal_mode = WAL");
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS fact_conflicts (
+      id TEXT PRIMARY KEY,
+      fact_id TEXT NOT NULL REFERENCES facts(id) ON DELETE CASCADE,
+      conflicting_fact_id TEXT NOT NULL REFERENCES facts(id) ON DELETE CASCADE,
+      conflict_type TEXT NOT NULL,
+      resolution TEXT CHECK(resolution IN ('superseded','merged','flagged','pending')),
+      resolved_at INTEGER,
+      created_at INTEGER DEFAULT (strftime('%s','now'))
+    );
+    CREATE TABLE IF NOT EXISTS fact_provenance (
+      id TEXT PRIMARY KEY,
+      fact_id TEXT NOT NULL REFERENCES facts(id) ON DELETE CASCADE,
+      source TEXT NOT NULL,
+      captured_at INTEGER NOT NULL,
+      capture_method TEXT,
+      superseded_by TEXT REFERENCES facts(id),
+      superseded_at INTEGER,
+      effective_from INTEGER DEFAULT (strftime('%s','now')),
+      effective_until INTEGER,
+      metadata TEXT,
+      UNIQUE(fact_id, source)
+    );
+    CREATE INDEX IF NOT EXISTS idx_conflicts_fact ON fact_conflicts(fact_id);
+    CREATE INDEX IF NOT EXISTS idx_provenance_fact ON fact_provenance(fact_id);
+  `);
+    return db;
+}
+async function ollamaCheck(prompt) {
+    try {
+        const resp = await fetch(`${OLLAMA_URL}/api/generate`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ model: "qwen2.5:1.5b", prompt, stream: false, options: { temperature: 0, num_predict: 50 } }),
+            signal: AbortSignal.timeout(15000),
+        });
+        if (!resp.ok)
+            return false;
+        const data = await resp.json();
+        const r = (data.response || "").trim().toLowerCase();
+        return r === "yes" || r === "true";
+    }
+    catch {
+        return false;
+    }
+}
+export async function isContradiction(fact1, fact2) {
+    if (fact1.value.trim().toLowerCase() === fact2.value.trim().toLowerCase())
+        return false;
+    const n1 = parseFloat((fact1.value.match(/^[\d.,]+/)?.[0] || "").replace(/,/g, ""));
+    const n2 = parseFloat((fact2.value.match(/^[\d.,]+/)?.[0] || "").replace(/,/g, ""));
+    if (!isNaN(n1) && !isNaN(n2) && Math.abs(n1 - n2) > 0.001 * Math.max(n1, n2))
+        return true;
+    const prompt = `Do these two statements directly contradict each other? Reply "yes" or "no".
+1: "${fact1.value.slice(0, 300)}"
+2: "${fact2.value.slice(0, 300)}"`;
+    return ollamaCheck(prompt);
+}
+export function findEntityConflicts(db, entity) {
+    const rows = db.prepare(`
+    SELECT fc.id, fc.fact_id, fc.conflicting_fact_id, fc.conflict_type, fc.resolution, fc.created_at,
+      f1.value as fact1_value, f2.value as fact2_value
+    FROM fact_conflicts fc
+    JOIN facts f1 ON fc.fact_id = f1.id
+    JOIN facts f2 ON fc.conflicting_fact_id = f2.id
+    WHERE f1.entity = ? OR f2.entity = ?
+    ORDER BY fc.created_at DESC
+  `).all(entity, entity);
+    return rows.map(r => ({
+        id: r.id, factId: r.fact_id, conflictingFactId: r.conflicting_fact_id,
+        conflictType: r.conflict_type, resolution: r.resolution,
+        fact1Value: r.fact1_value, fact2Value: r.fact2_value, createdAt: r.created_at,
+    }));
+}
+export async function detectNewConflict(db, entity, key, newValue) {
+    const existing = db.prepare(`
+    SELECT id, entity, key, value, created_at FROM facts
+    WHERE entity = ? ${key ? "AND key = ?" : "AND key IS NULL"} AND (expires_at IS NULL OR expires_at > ?)
+    ORDER BY created_at DESC LIMIT 10
+  `).all(entity, ...(key ? [key] : []), Math.floor(Date.now() / 1000));
+    for (const ef of existing) {
+        if (ef.value.trim().toLowerCase() === newValue.trim().toLowerCase())
+            continue;
+        const isContradict = await isContradiction({ value: newValue, entity, key }, { value: ef.value, entity, key });
+        if (isContradict) {
+            const nowSec = Math.floor(Date.now() / 1000);
+            const cid = randomUUID();
+            db.prepare(`INSERT OR IGNORE INTO fact_conflicts (id, fact_id, conflicting_fact_id, conflict_type, resolution, created_at) VALUES (?, ?, ?, 'semantic', 'pending', ?)`).run(cid, ef.id, randomUUID(), nowSec);
+            return { id: cid, factId: ef.id, conflictingFactId: ef.id, conflictType: "semantic", resolution: "pending", fact1Value: ef.value, fact2Value: newValue, createdAt: nowSec };
+        }
+    }
+    return null;
+}
+export function resolveConflict(db, conflictId, strategy) {
+    const nowSec = Math.floor(Date.now() / 1000);
+    if (strategy === "supersede") {
+        db.prepare("UPDATE fact_conflicts SET resolution = 'superseded', resolved_at = ? WHERE id = ?").run(nowSec, conflictId);
+        db.prepare("UPDATE facts SET expires_at = ? WHERE id = (SELECT fact_id FROM fact_conflicts WHERE id = ? AND resolution = 'superseded')").run(nowSec - 1, conflictId);
+    }
+    else {
+        db.prepare("UPDATE fact_conflicts SET resolution = ?, resolved_at = ? WHERE id = ?").run(strategy, nowSec, conflictId);
+    }
+}
+export function resolveAllPending(db, strategy = "flag") {
+    const result = db.prepare("UPDATE fact_conflicts SET resolution = ?, resolved_at = ? WHERE resolution = 'pending'").run(strategy, Math.floor(Date.now() / 1000));
+    return result.changes;
+}
+export function trackProvenance(db, factId, source, captureMethod) {
+    const nowSec = Math.floor(Date.now() / 1000);
+    db.prepare(`INSERT OR IGNORE INTO fact_provenance (id, fact_id, source, captured_at, capture_method, effective_from) VALUES (?, ?, ?, ?, ?, ?)`).run(randomUUID(), factId, source, nowSec, captureMethod || null, nowSec);
+}
+export function getProvenance(db, factId) {
+    return db.prepare("SELECT * FROM fact_provenance WHERE fact_id = ? ORDER BY effective_from DESC").all(factId).map(r => ({
+        id: r.id, factId: r.fact_id, source: r.source,
+        capturedAt: r.captured_at, captureMethod: r.capture_method,
+        supersededBy: r.superseded_by, supersededAt: r.superseded_at,
+        effectiveFrom: r.effective_from, effectiveUntil: r.effective_until,
+    }));
+}
+export function getFactHistory(db, entity, key) {
+    const rows = db.prepare(`
+    SELECT f.id, f.value, COALESCE(fp.effective_from, f.created_at) as eff, fp.superseded_by
+    FROM facts f LEFT JOIN fact_provenance fp ON f.id = fp.fact_id
+    WHERE f.entity = ? ${key ? "AND f.key = ?" : "AND f.key IS NULL"}
+    ORDER BY eff DESC
+  `).all(entity, ...(key ? [key] : []));
+    return rows.map(r => ({ id: r.id, value: r.value, effectiveFrom: r.eff, superseded: Boolean(r.superseded_by) }));
+}
+async function main() {
+    const args = process.argv.slice(2);
+    if (args.length === 0) {
+        console.log("Conflict Resolver CLI\n\nCommands:\n  detect --entity <name>            Detect conflicts for an entity\n  resolve --id <conflictId> --strategy supersede|flag\n  resolve-all --strategy <s>          Resolve all pending\n  provenance --id <factId>            Show provenance chain\n  history --entity <name> --key <key> Show value history\n  stats                             Conflict stats");
+        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 === "detect") {
+        if (!flags.entity) {
+            console.error("--entity required");
+            process.exit(1);
+        }
+        const conflicts = findEntityConflicts(db, flags.entity);
+        if (conflicts.length === 0) {
+            console.log(`No conflicts for "${flags.entity}".`);
+        }
+        else {
+            console.log(`${conflicts.length} conflict(s):\n`);
+            for (const c of conflicts) {
+                console.log(`  [${c.id.slice(0, 8)}] ${c.conflictType} | ${c.resolution || "pending"}\n    F1: ${c.fact1Value.slice(0, 80)}\n    F2: ${c.fact2Value.slice(0, 80)}\n`);
+            }
+        }
+    }
+    else if (command === "resolve") {
+        if (!flags.id || !flags.strategy) {
+            console.error("--id and --strategy required");
+            process.exit(1);
+        }
+        resolveConflict(db, flags.id, flags.strategy);
+        console.log(`Conflict ${flags.id.slice(0, 8)} resolved as ${flags.strategy}.`);
+    }
+    else if (command === "resolve-all") {
+        const n = resolveAllPending(db, flags.strategy || "flag");
+        console.log(`${n} pending conflict(s) resolved.`);
+    }
+    else if (command === "provenance") {
+        if (!flags.id) {
+            console.error("--id required");
+            process.exit(1);
+        }
+        const prov = getProvenance(db, flags.id);
+        if (prov.length === 0) {
+            console.log("No provenance records.");
+        }
+        else {
+            prov.forEach(p => console.log(`  ${new Date(p.capturedAt * 1000).toISOString()} | ${p.source} | superseded=${p.supersededBy ? "yes (" + p.supersededBy.slice(0, 8) + ")" : "no"}`));
+        }
+    }
+    else if (command === "history") {
+        if (!flags.entity) {
+            console.error("--entity required");
+            process.exit(1);
+        }
+        const history = getFactHistory(db, flags.entity, flags.key || null);
+        if (history.length === 0) {
+            console.log("No history found.");
+        }
+        else {
+            history.forEach(h => console.log(`  [${h.superseded ? "SUPERSEDED" : "active"}] ${h.value.slice(0, 80)}\n    since ${new Date(h.effectiveFrom * 1000).toDateString()}`));
+        }
+    }
+    else if (command === "stats") {
+        const total = db.prepare("SELECT COUNT(*) as c FROM fact_conflicts").get();
+        const pending = db.prepare("SELECT COUNT(*) as c FROM fact_conflicts WHERE resolution = 'pending'").get();
+        const resolved = db.prepare("SELECT COUNT(*) as c FROM fact_conflicts WHERE resolution != 'pending'").get();
+        console.log(`Conflicts: ${total.c} total | ${pending.c} pending | ${resolved.c} resolved`);
+    }
+    db.close();
+}
+if (import.meta.main)
+    main();