hippo-memory 0.30.1 → 0.32.0

package/README.md

@@ -60,6 +60,20 @@ 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.
+- **Auto-detect from env.** `HIPPO_SCOPE`, `GSTACK_SKILL`, `OPENCLAW_SKILL` populate the scope automatically. Explicit `--scope` on any command overrides.
+- **`hippo explain --why`** now shows the `scope:` multiplier when it fires, so you can see why a memory got ranked up or down.
+
 ### What's new in v0.30.1
 
 - **`hippo recall --layer <L>` is now a strict filter.** Previously the flag was accepted but silently dropped; other layers leaked into results. The RSI demo's `recall --layer trace` now does what it says.

package/dist/cli.js

@@ -44,6 +44,7 @@ import { openHippoDb, closeHippoDb } from './db.js';
 import { captureError, extractLessons, deduplicateLesson, runWatched, fetchGitLog, isGitRepo, } from './autolearn.js';
 import { extractInvalidationTarget, invalidateMatching } from './invalidation.js';
 import { extractPathTags } from './path-context.js';
+import { detectScope, scopeMatch } from './scope.js';
 import { getGlobalRoot, initGlobal, promoteToGlobal, shareMemory, listPeers, autoShare, transferScore, searchBothHybrid, syncGlobalToLocal, } from './shared.js';
 import { DAILY_TASK_NAME, buildDailyRunnerCommand, listRegisteredWorkspaces, registerWorkspace, runDailyMaintenance, } from './scheduler.js';
 import { importChatGPT, importClaude, importCursor, importGenericFile, importMarkdown, } from './importers.js';
@@ -413,6 +414,14 @@ function cmdRemember(hippoRoot, text, flags) {
         if (!entry.tags.includes(pt))
             entry.tags.push(pt);
     }
+    // Scope tagging: explicit --scope or auto-detected
+    const explicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
+    const activeScope = explicitScope || detectScope();
+    if (activeScope) {
+        const scopeTag = `scope:${activeScope}`;
+        if (!entry.tags.includes(scopeTag))
+            entry.tags.push(scopeTag);
+    }
     writeEntry(targetRoot, entry);
     updateStats(targetRoot, { remembered: 1 });
     const prefix = useGlobal ? '[global] ' : '';
@@ -429,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);
@@ -437,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
@@ -459,6 +533,8 @@ async function cmdRecall(hippoRoot, query, flags) {
     const minResults = flags['min-results'] !== undefined
         ? parseInt(String(flags['min-results']), 10)
         : undefined;
+    const recallExplicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
+    const recallActiveScope = recallExplicitScope || detectScope();
     let results;
     if (usePhysics && !hasGlobal) {
         results = await physicsSearch(query, localEntries, {
@@ -466,17 +542,18 @@ async function cmdRecall(hippoRoot, query, flags) {
             hippoRoot,
             physicsConfig: config.physics,
             minResults,
+            scope: recallActiveScope,
         });
     }
     else if (hasGlobal) {
         // Use searchBothHybrid for merged results with embedding support
         results = await searchBothHybrid(query, hippoRoot, globalRoot, {
-            budget, mmr: mmrEnabled, mmrLambda, localBump, minResults,
+            budget, mmr: mmrEnabled, mmrLambda, localBump, minResults, scope: recallActiveScope,
         });
     }
     else {
         results = await hybridSearch(query, localEntries, {
-            budget, hippoRoot, mmr: mmrEnabled, mmrLambda, minResults,
+            budget, hippoRoot, mmr: mmrEnabled, mmrLambda, minResults, scope: recallActiveScope,
         });
     }
     // --outcome filter: drop trace entries whose trace_outcome !== target.
@@ -543,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);
@@ -565,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);
@@ -585,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);
@@ -602,33 +718,38 @@ async function cmdExplain(hippoRoot, query, flags) {
         : flags['local-bump'] !== undefined
             ? parseFloat(String(flags['local-bump']))
             : config.search.localBump;
+    const explainExplicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
+    const explainActiveScope = explainExplicitScope || detectScope();
     let results;
     let modeUsed;
     if (usePhysics && !hasGlobal) {
-        results = await physicsSearch(query, localEntries, {
+        results = await physicsSearch(query, explainLocalEntries, {
             budget,
             hippoRoot,
             physicsConfig: config.physics,
             explain: true,
+            scope: explainActiveScope,
         });
         modeUsed = 'physics';
     }
     else if (hasGlobal) {
         results = await searchBothHybrid(query, hippoRoot, globalRoot, {
-            budget, explain: true, mmr: mmrEnabled, mmrLambda, localBump,
+            budget, explain: true, mmr: mmrEnabled, mmrLambda, localBump, scope: explainActiveScope,
+            includeSuperseded: explainIncludeSuperseded, asOf: explainAsOf,
         });
         modeUsed = 'searchBothHybrid';
     }
     else {
-        results = await hybridSearch(query, localEntries, {
-            budget, hippoRoot, explain: true, mmr: mmrEnabled, mmrLambda,
+        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,
@@ -691,6 +812,8 @@ async function cmdExplain(hippoRoot, query, flags) {
             console.log(`    recency:   x${fmt(b.recencyMultiplier, 3)}  (age=${b.ageDays}d)`);
             if (b.decisionBoost !== 1)
                 console.log(`    decision:  x${fmt(b.decisionBoost, 2)}  (tagged 'decision')`);
+            if (b.scopeBoost !== 1)
+                console.log(`    scope:     x${fmt(b.scopeBoost, 2)}  (scope tag ${b.scopeBoost > 1 ? 'match' : 'mismatch'})`);
             if (b.pathBoost !== 1)
                 console.log(`    path:      x${fmt(b.pathBoost, 3)}  (cwd path tag overlap)`);
             if (b.sourceBump !== 1)
@@ -2190,6 +2313,8 @@ async function cmdContext(hippoRoot, args, flags) {
     }
     const budget = parseInt(String(flags['budget'] ?? '1500'), 10);
     const limit = parseLimitFlag(flags['limit']);
+    const ctxExplicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
+    const ctxActiveScope = ctxExplicitScope || detectScope();
     // If budget is 0, skip entirely (zero token cost)
     if (budget <= 0)
         return;
@@ -2207,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
@@ -2239,12 +2367,16 @@ async function cmdContext(hippoRoot, args, flags) {
             ...pinnedLocal.map((e) => ({ entry: e, isGlobal: false })),
             ...pinnedGlobal.map((e) => ({ entry: e, isGlobal: true })),
         ]
-            .map(({ entry, isGlobal }) => ({
-            entry,
-            score: calculateStrength(entry, nowP) * (isGlobal ? 1 / 1.2 : 1),
-            tokens: estimateTokens(entry.content),
-            isGlobal,
-        }))
+            .map(({ entry, isGlobal }) => {
+            const scopeSig = scopeMatch(entry.tags, ctxActiveScope);
+            const sBst = scopeSig === 1 ? 1.5 : scopeSig === -1 ? 0.5 : 1.0;
+            return {
+                entry,
+                score: calculateStrength(entry, nowP) * (isGlobal ? 1 / 1.2 : 1) * sBst,
+                tokens: estimateTokens(entry.content),
+                isGlobal,
+            };
+        })
             .sort((a, b) => b.score - a.score);
         let usedP = 0;
         for (const r of rankedPinned) {
@@ -2287,7 +2419,7 @@ async function cmdContext(hippoRoot, args, flags) {
     else {
         let results;
         if (hasGlobal) {
-            const merged = await searchBothHybrid(query, hippoRoot, globalRoot, { budget });
+            const merged = await searchBothHybrid(query, hippoRoot, globalRoot, { budget, scope: ctxActiveScope });
             const localIndex = loadIndex(hippoRoot);
             results = merged.map((r) => ({
                 entry: r.entry,
@@ -2300,8 +2432,8 @@ async function cmdContext(hippoRoot, args, flags) {
             const ctxConfig = loadConfig(hippoRoot);
             const usePhysicsCtx = ctxConfig.physics?.enabled !== false;
             const ctxResults = usePhysicsCtx
-                ? await physicsSearch(query, localEntries, { budget, hippoRoot, physicsConfig: ctxConfig.physics })
-                : await hybridSearch(query, localEntries, { budget, hippoRoot });
+                ? await physicsSearch(query, localEntries, { budget, hippoRoot, physicsConfig: ctxConfig.physics, scope: ctxActiveScope })
+                : await hybridSearch(query, localEntries, { budget, hippoRoot, scope: ctxActiveScope });
             results = ctxResults.map((r) => ({
                 entry: r.entry,
                 score: r.score,
@@ -3518,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) {