hippo-memory 0.31.0 → 0.32.0

package/README.md

@@ -60,6 +60,14 @@ hippo recall "data pipeline issues" --budget 2000
 
 ---
 
+### 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

@@ -438,6 +438,37 @@ function cmdRemember(hippoRoot, text, flags) {
         });
     }
 }
+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);
     const budget = parseInt(String(flags['budget'] ?? '4000'), 10);
@@ -446,9 +477,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
@@ -555,6 +620,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 +646,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 +667,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 +723,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 +735,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,
@@ -2226,8 +2332,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
@@ -3541,6 +3650,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) {