hippo-memory 0.31.0 → 0.33.0

package/README.md

@@ -60,6 +60,22 @@ hippo recall "data pipeline issues" --budget 2000
 
 ---
 
+### What's new in v0.33.0
+
+- **Fact extraction at sleep time.** `hippo sleep` now extracts standalone facts from episodic memories via LLM, stored as semantic-layer entries that score 1.3x higher and auto-deduplicate against their raw source in search results.
+- **DAG summarization.** Extracted facts cluster by entity similarity into summary nodes. When a summary matches your query, its children drill down into results automatically.
+- **Multi-hop retrieval.** `hippo recall --multihop` chains two search passes via entity tags discovered in the first pass, finding connections that single-pass search misses.
+- **`hippo dag --stats`** shows how your memory is organized across DAG levels.
+- **Performance fix.** Temporal scoring refactored from O(N^2) to O(N), eliminating stack overflow risk on large stores.
+
+### What's new in v0.32.0
+
+- **Correction without deletion.** `hippo supersede <old-id> "<new content>"` links the old memory as historical truth and creates a successor. Default recall shows only current beliefs; the old one stays in the store so you can audit what changed and when.
+- **`--include-superseded`** on `recall` and `explain` surfaces historical memories with a `[superseded]` marker. Useful for "what did I used to think about X?"
+- **`--as-of <ISO-date>`** returns the set of beliefs that were current at a past moment. Invalid dates exit with a clear format hint.
+- **Schema v11, zero breaking changes.** Adds `valid_from` + `superseded_by` columns. Existing v10 stores upgrade on first open, no data loss, no manual migration.
+- **Physics search ablation: CUT.** Benchmarked over 60 LongMemEval-oracle questions: physics-on is statistically worse than plain BM25 + embeddings on MRR, Recall@5, and NDCG@5 (paired bootstrap, 5000 iters, 95% CI excludes zero). Full results in `benchmarks/physics-ablation/`. Physics stays in the codebase this release; removal is a separate decision.
+
 ### What's new in v0.31.0
 
 - **Scope-aware corrections.** Tag a memory with `hippo remember --scope plan-eng-review` and it only surfaces strongly when that scope is active again. Matching scope gets 1.5x boost, mismatching scope is suppressed 0.5x, unscoped memories stay neutral. Corrections said during one skill stop polluting unrelated contexts.

package/dist/cli.js

@@ -53,6 +53,7 @@ import { auditMemories } from './audit.js';
 import { runEval, bootstrapCorpus, compareSummaries } from './eval.js';
 import { refineStore } from './refine-llm.js';
 import { wmPush, wmRead, wmClear, wmFlush } from './working-memory.js';
+import { multihopSearch } from './multihop.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -377,7 +378,7 @@ function setupDailySchedule(globalRoot) {
         }
     }
 }
-function cmdRemember(hippoRoot, text, flags) {
+async function cmdRemember(hippoRoot, text, flags) {
     const useGlobal = Boolean(flags['global']);
     const targetRoot = useGlobal ? getGlobalRoot() : hippoRoot;
     if (useGlobal) {
@@ -437,6 +438,59 @@ function cmdRemember(hippoRoot, text, flags) {
             // Silently ignore embedding errors
         });
     }
+    const config = loadConfig(targetRoot);
+    const shouldExtract = flags['extract'] || config.extraction.enabled === true;
+    const apiKey = process.env.ANTHROPIC_API_KEY ?? '';
+    if (shouldExtract && apiKey) {
+        try {
+            const { extractFacts, storeExtractedFacts } = await import('./extract.js');
+            const facts = await extractFacts(entry.content, {
+                apiKey,
+                model: config.extraction.model,
+            });
+            if (facts.length > 0) {
+                storeExtractedFacts(targetRoot, entry, facts);
+                console.error(`  extracted ${facts.length} fact(s)`);
+            }
+        }
+        catch {
+            // Extraction is best-effort — never block remember
+        }
+    }
+    else if (shouldExtract && !apiKey) {
+        console.error('  (extraction skipped: ANTHROPIC_API_KEY not set)');
+    }
+}
+function cmdSupersede(hippoRoot, oldId, newContent, flags) {
+    requireInit(hippoRoot);
+    const old = readEntry(hippoRoot, oldId);
+    if (!old) {
+        console.error(`Error: memory ${oldId} not found.`);
+        process.exit(1);
+    }
+    if (old.superseded_by) {
+        console.error(`Error: memory ${oldId} is already superseded by ${old.superseded_by}. Supersede that one instead.`);
+        process.exit(1);
+    }
+    const layer = (typeof flags['layer'] === 'string' ? flags['layer'] : old.layer);
+    const rawTags = flags['tag'];
+    const tags = Array.isArray(rawTags)
+        ? rawTags.map((t) => String(t))
+        : typeof rawTags === 'string'
+            ? rawTags.split(',').map((t) => t.trim()).filter(Boolean)
+            : [...old.tags];
+    const pinned = flags['pin'] === true || old.pinned;
+    const newEntry = createMemory(newContent, {
+        layer,
+        tags,
+        pinned,
+        source: old.source,
+        confidence: 'verified',
+    });
+    old.superseded_by = newEntry.id;
+    writeEntry(hippoRoot, old);
+    writeEntry(hippoRoot, newEntry);
+    console.log(`Superseded ${oldId} → ${newEntry.id}`);
 }
 async function cmdRecall(hippoRoot, query, flags) {
     requireInit(hippoRoot);
@@ -446,9 +500,43 @@ async function cmdRecall(hippoRoot, query, flags) {
     const showWhy = Boolean(flags['why']);
     const forcePhysics = Boolean(flags['physics']);
     const forceClassic = Boolean(flags['classic']);
+    const includeSuperseded = Boolean(flags['include-superseded']);
+    const asOf = typeof flags['as-of'] === 'string' ? flags['as-of'] : undefined;
+    if (asOf !== undefined && Number.isNaN(new Date(asOf).getTime())) {
+        console.error(`Error: --as-of value "${asOf}" is not a valid ISO date (e.g. 2026-04-22 or 2026-04-22T12:00:00Z).`);
+        process.exit(1);
+    }
     const globalRoot = getGlobalRoot();
-    const localEntries = loadSearchEntries(hippoRoot, query);
-    const globalEntries = isInitialized(globalRoot) ? loadSearchEntries(globalRoot, query) : [];
+    let localEntries = loadSearchEntries(hippoRoot, query);
+    let globalEntries = isInitialized(globalRoot) ? loadSearchEntries(globalRoot, query) : [];
+    // Bi-temporal filtering for physics path (hybridSearch handles it internally)
+    if (asOf) {
+        const filterAsOf = (entries) => {
+            const asOfDate = new Date(asOf);
+            const successorValidFrom = new Map();
+            for (const e of entries) {
+                if (e.superseded_by) {
+                    const successor = entries.find(s => s.id === e.superseded_by);
+                    if (successor)
+                        successorValidFrom.set(e.id, successor.valid_from);
+                }
+            }
+            return entries.filter(e => {
+                if (new Date(e.valid_from) > asOfDate)
+                    return false;
+                if (!e.superseded_by)
+                    return true;
+                const succVf = successorValidFrom.get(e.id);
+                return succVf ? new Date(succVf) > asOfDate : true;
+            });
+        };
+        localEntries = filterAsOf(localEntries);
+        globalEntries = filterAsOf(globalEntries);
+    }
+    else if (!includeSuperseded) {
+        localEntries = localEntries.filter(e => !e.superseded_by);
+        globalEntries = globalEntries.filter(e => !e.superseded_by);
+    }
     const hasGlobal = globalEntries.length > 0;
     // Determine search mode: --physics forces physics, --classic forces BM25+cosine,
     // default uses physics if config.physics.enabled is not false
@@ -470,8 +558,19 @@ async function cmdRecall(hippoRoot, query, flags) {
         : undefined;
     const recallExplicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
     const recallActiveScope = recallExplicitScope || detectScope();
+    const useMultihop = flags['multihop'] === true || config.multihop.enabled;
     let results;
-    if (usePhysics && !hasGlobal) {
+    if (useMultihop) {
+        const allEntries = [...localEntries, ...globalEntries];
+        results = multihopSearch(query, allEntries, {
+            budget,
+            hippoRoot,
+            minResults,
+            includeSuperseded,
+            asOf,
+        });
+    }
+    else if (usePhysics && !hasGlobal) {
         results = await physicsSearch(query, localEntries, {
             budget,
             hippoRoot,
@@ -555,6 +654,10 @@ async function cmdRecall(hippoRoot, query, flags) {
             if (r.entry.layer === Layer.Trace) {
                 base.trace_outcome = r.entry.trace_outcome;
             }
+            if (r.entry.superseded_by) {
+                base.superseded = true;
+                base.superseded_by = r.entry.superseded_by;
+            }
             if (showWhy) {
                 const explanation = explainMatch(query, r);
                 base.confidence = resolveConfidence(r.entry);
@@ -577,8 +680,9 @@ async function cmdRecall(hippoRoot, query, flags) {
         const strengthBar = '\u2588'.repeat(Math.round(e.strength * 10)) + '\u2591'.repeat(10 - Math.round(e.strength * 10));
         const isGlobal = isInitialized(globalRoot) && !localIndex.entries[e.id];
         const globalMark = isGlobal ? ' [global]' : '';
+        const supersededMark = e.superseded_by ? ' [superseded]' : '';
         const sourceMark = isGlobal ? ' [global]' : ' [local]';
-        console.log(`--- ${e.id} [${e.layer}] ${confLabel}${globalMark} score=${fmt(r.score, 3)} strength=${fmt(e.strength)}`);
+        console.log(`--- ${e.id} [${e.layer}] ${confLabel}${globalMark}${supersededMark} score=${fmt(r.score, 3)} strength=${fmt(e.strength)}`);
         console.log(`    [${strengthBar}] tags: ${e.tags.join(', ') || 'none'} | retrieved: ${e.retrieval_count}x`);
         if (showWhy) {
             const explanation = explainMatch(query, r);
@@ -597,10 +701,44 @@ async function cmdExplain(hippoRoot, query, flags) {
     const asJson = Boolean(flags['json']);
     const forcePhysics = Boolean(flags['physics']);
     const forceClassic = Boolean(flags['classic']);
+    const explainIncludeSuperseded = Boolean(flags['include-superseded']);
+    const explainAsOf = typeof flags['as-of'] === 'string' ? flags['as-of'] : undefined;
+    if (explainAsOf !== undefined && Number.isNaN(new Date(explainAsOf).getTime())) {
+        console.error(`Error: --as-of value "${explainAsOf}" is not a valid ISO date (e.g. 2026-04-22 or 2026-04-22T12:00:00Z).`);
+        process.exit(1);
+    }
     const globalRoot = getGlobalRoot();
-    const localEntries = loadSearchEntries(hippoRoot, query);
-    const globalEntries = isInitialized(globalRoot) ? loadSearchEntries(globalRoot, query) : [];
-    const hasGlobal = globalEntries.length > 0;
+    let explainLocalEntries = loadSearchEntries(hippoRoot, query);
+    let explainGlobalEntries = isInitialized(globalRoot) ? loadSearchEntries(globalRoot, query) : [];
+    // Bi-temporal filtering
+    if (explainAsOf) {
+        const filterAsOfExplain = (entries) => {
+            const asOfDate = new Date(explainAsOf);
+            const successorValidFrom = new Map();
+            for (const e of entries) {
+                if (e.superseded_by) {
+                    const successor = entries.find(s => s.id === e.superseded_by);
+                    if (successor)
+                        successorValidFrom.set(e.id, successor.valid_from);
+                }
+            }
+            return entries.filter(e => {
+                if (new Date(e.valid_from) > asOfDate)
+                    return false;
+                if (!e.superseded_by)
+                    return true;
+                const succVf = successorValidFrom.get(e.id);
+                return succVf ? new Date(succVf) > asOfDate : true;
+            });
+        };
+        explainLocalEntries = filterAsOfExplain(explainLocalEntries);
+        explainGlobalEntries = filterAsOfExplain(explainGlobalEntries);
+    }
+    else if (!explainIncludeSuperseded) {
+        explainLocalEntries = explainLocalEntries.filter(e => !e.superseded_by);
+        explainGlobalEntries = explainGlobalEntries.filter(e => !e.superseded_by);
+    }
+    const hasGlobal = explainGlobalEntries.length > 0;
     const config = loadConfig(hippoRoot);
     const usePhysics = forcePhysics
         || (!forceClassic && config.physics.enabled !== false);
@@ -619,7 +757,7 @@ async function cmdExplain(hippoRoot, query, flags) {
     let results;
     let modeUsed;
     if (usePhysics && !hasGlobal) {
-        results = await physicsSearch(query, localEntries, {
+        results = await physicsSearch(query, explainLocalEntries, {
             budget,
             hippoRoot,
             physicsConfig: config.physics,
@@ -631,19 +769,21 @@ async function cmdExplain(hippoRoot, query, flags) {
     else if (hasGlobal) {
         results = await searchBothHybrid(query, hippoRoot, globalRoot, {
             budget, explain: true, mmr: mmrEnabled, mmrLambda, localBump, scope: explainActiveScope,
+            includeSuperseded: explainIncludeSuperseded, asOf: explainAsOf,
         });
         modeUsed = 'searchBothHybrid';
     }
     else {
-        results = await hybridSearch(query, localEntries, {
+        results = await hybridSearch(query, explainLocalEntries, {
             budget, hippoRoot, explain: true, mmr: mmrEnabled, mmrLambda, scope: explainActiveScope,
+            includeSuperseded: explainIncludeSuperseded, asOf: explainAsOf,
         });
         modeUsed = 'hybrid';
     }
     if (limit < results.length) {
         results = results.slice(0, limit);
     }
-    const candidates = localEntries.length + globalEntries.length;
+    const candidates = explainLocalEntries.length + explainGlobalEntries.length;
     if (asJson) {
         const output = results.map((r, rank) => ({
             rank: rank + 1,
@@ -1190,7 +1330,7 @@ function cmdDedup(hippoRoot, flags) {
         console.log(`  ... and ${result.pairs.length - 15} more (run with --dry-run to see all)`);
     }
 }
-function cmdSleep(hippoRoot, flags) {
+async function cmdSleep(hippoRoot, flags) {
     // Tee stdout/stderr to a log file when --log-file is set. The SessionEnd
     // hook uses this so the output is captured somewhere the SessionStart hook
     // can re-display it next time the agent UI starts.
@@ -1229,7 +1369,7 @@ function cmdSleep(hippoRoot, flags) {
         }
     }
     try {
-        cmdSleepCore(hippoRoot, flags);
+        await cmdSleepCore(hippoRoot, flags);
         if (logFile)
             console.log('[hippo] sleep complete');
     }
@@ -1243,7 +1383,7 @@ function cmdSleep(hippoRoot, flags) {
             restoreStdout();
     }
 }
-function cmdSleepCore(hippoRoot, flags) {
+async function cmdSleepCore(hippoRoot, flags) {
     requireInit(hippoRoot);
     // Auto-learn from git before consolidating (unless --no-learn)
     if (!flags['no-learn']) {
@@ -1260,7 +1400,7 @@ function cmdSleepCore(hippoRoot, flags) {
     }
     const dryRun = Boolean(flags['dry-run']);
     console.log(`Running consolidation${dryRun ? ' (dry run)' : ''}...`);
-    const result = consolidate(hippoRoot, { dryRun });
+    const result = await consolidate(hippoRoot, { dryRun });
     console.log(`\nResults:`);
     console.log(`   Active memories:  ${result.decayed}`);
     console.log(`   Removed (decayed): ${result.removed}`);
@@ -2226,8 +2366,11 @@ async function cmdContext(hippoRoot, args, flags) {
     // When the local store isn't initialized (pinned-only path in a fresh dir),
     // skip the local load — loadAllEntries would auto-create .hippo here and
     // we don't want to pollute arbitrary cwds.
-    const localEntries = hasLocal ? loadAllEntries(hippoRoot) : [];
-    const globalEntries = hasGlobal ? loadAllEntries(globalRoot) : [];
+    let localEntries = hasLocal ? loadAllEntries(hippoRoot) : [];
+    let globalEntries = hasGlobal ? loadAllEntries(globalRoot) : [];
+    // Default context always filters superseded (no --include-superseded / --as-of for context)
+    localEntries = localEntries.filter(e => !e.superseded_by);
+    globalEntries = globalEntries.filter(e => !e.superseded_by);
     const allEntries = [...localEntries];
     if (allEntries.length === 0 && globalEntries.length === 0)
         return; // no memories, zero output
@@ -3265,6 +3408,44 @@ function cmdWm(hippoRoot, args, flags) {
     console.error('Usage: hippo wm <push|read|clear|flush>');
     process.exit(1);
 }
+function cmdDag(hippoRoot, flags) {
+    requireInit(hippoRoot);
+    const entries = loadAllEntries(hippoRoot);
+    const isStats = flags['stats'] === true;
+    const byLevel = new Map();
+    let unlinked = 0;
+    for (const entry of entries) {
+        const level = entry.dag_level ?? 0;
+        byLevel.set(level, (byLevel.get(level) ?? 0) + 1);
+        if (level === 1 && !entry.dag_parent_id)
+            unlinked++;
+    }
+    if (isStats) {
+        console.log('DAG Structure:');
+        console.log(`  Level 3 (entity profiles):  ${byLevel.get(3) ?? 0}`);
+        console.log(`  Level 2 (topic summaries):  ${byLevel.get(2) ?? 0}`);
+        console.log(`  Level 1 (extracted facts):  ${byLevel.get(1) ?? 0}`);
+        console.log(`  Level 0 (raw memories):     ${byLevel.get(0) ?? 0}`);
+        console.log(`  Unlinked facts: ${unlinked}`);
+        return;
+    }
+    // Tree view: show summaries and their children
+    const summaries = entries.filter((e) => e.dag_level === 2);
+    if (summaries.length === 0) {
+        console.log('No DAG summaries yet. Run `hippo sleep` with ANTHROPIC_API_KEY set.');
+        return;
+    }
+    for (const summary of summaries) {
+        const summaryTags = summary.tags.filter((t) => t !== 'dag-summary').join(', ');
+        console.log(`\n📌 ${summary.content.slice(0, 80)}`);
+        if (summaryTags)
+            console.log(`   [${summaryTags}]`);
+        const children = entries.filter((e) => e.dag_parent_id === summary.id);
+        for (const child of children) {
+            console.log(`   └─ ${child.content.slice(0, 70)}`);
+        }
+    }
+}
 function printUsage() {
     console.log(`
 Hippo - biologically-inspired memory system for AI agents
@@ -3529,7 +3710,7 @@ async function main() {
                 console.error('Memory content too short (minimum 3 characters).');
                 process.exit(1);
             }
-            cmdRemember(hippoRoot, text, flags);
+            await cmdRemember(hippoRoot, text, flags);
             break;
         }
         case 'recall': {
@@ -3541,6 +3722,16 @@ async function main() {
             await cmdRecall(hippoRoot, query, flags);
             break;
         }
+        case 'supersede': {
+            const oldId = args[0];
+            const newContent = args.slice(1).join(' ').trim();
+            if (!oldId || !newContent) {
+                console.error('Usage: hippo supersede <old-id> "<new content>" [--layer L] [--tag T] [--pin]');
+                process.exit(1);
+            }
+            cmdSupersede(hippoRoot, oldId, newContent, flags);
+            break;
+        }
         case 'explain': {
             const query = args.join(' ').trim();
             if (!query) {
@@ -3572,7 +3763,7 @@ async function main() {
             await cmdRefine(hippoRoot, flags);
             break;
         case 'sleep':
-            cmdSleep(hippoRoot, flags);
+            await cmdSleep(hippoRoot, flags);
             break;
         case 'last-sleep':
             cmdLastSleep(flags);
@@ -3592,6 +3783,9 @@ async function main() {
         case 'dedup':
             cmdDedup(hippoRoot, flags);
             break;
+        case 'dag':
+            cmdDag(hippoRoot, flags);
+            break;
         case 'audit': {
             requireInit(hippoRoot);
             const entries = loadAllEntries(hippoRoot);