hippo-memory 1.50.0 → 1.51.0

package/dist/api.js

@@ -17,7 +17,7 @@ import { detectInstruction } from './instruction-detect.js';
 import { quarantineScopeFor, recordQuarantine, getQuarantineRow, listQuarantineRows, approveQuarantineRow, rejectQuarantineRow, } from './quarantine.js';
 import { summarizeFailures } from './failure-log.js';
 import { formatHandoffEvidenceLine } from './handoff.js';
-import { createMemory, applyOutcome, calculateStrength, Layer, } from './memory.js';
+import { createMemory, applyOutcome, calculateStrength, Layer, CHURN_STALE_TAG, } from './memory.js';
 import { appendAuditEvent, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
 import { promoteToGlobal, getGlobalRoot, autoShare, searchBothHybrid } from './shared.js';
 import { writeRecallTrace, writeRecallTraceAtRoot, recordTraceOutcome } from './recall-trace.js';
@@ -25,7 +25,7 @@ import { evalNow } from './ablation.js';
 import { archiveRawMemory } from './raw-archive.js';
 import { createApiKey, listApiKeys, revokeApiKey, grantScope, ungrantScope, } from './auth.js';
 import { applyGoalStackBoost } from './goals.js';
-import { markRetrieved, estimateTokens, hybridSearch, physicsSearch } from './search.js';
+import { markRetrieved, estimateTokens, hybridSearch, physicsSearch, churnStaleFactor } from './search.js';
 import { compareEntryIdentity, compareScoredResults } from './compare.js';
 import { scopeMatch } from './scope.js';
 import { consolidate } from './consolidate.js';
@@ -313,6 +313,10 @@ function recallFrom(ctx, opts, windowSize, all) {
     // for api.recall; cmdRecall pipeline rolls --outcome/--layer/--as-of/etc.
     // into the same field per the plan's Task 3 mapping table).
     droppedPreRankCount = all.length - entries.length;
+    entries = entries
+        .map((e, i) => ({ e, s: (1 - i / entries.length) * churnStaleFactor(e) }))
+        .sort((a, b) => b.s - a.s)
+        .map((r) => r.e);
     // BM25 ordering already comes from loadRecallSearchEntries; cap to `limit`.
     // Score is a placeholder — the physics/hybrid scorers in src/search.ts
     // produce richer breakdowns and will replace this when wired up.
@@ -992,7 +996,10 @@ export function outcome(ctx, ids, good, opts) {
             const entry = readEntry(ctx.hippoRoot, id, ctx.tenantId);
             if (!entry)
                 continue;
-            const updated = applyOutcome(entry, good);
+            let updated = applyOutcome(entry, good);
+            if (good && updated.tags.includes(CHURN_STALE_TAG)) { // FE2: a good outcome reconfirms the entry
+                updated = { ...updated, tags: updated.tags.filter((t) => t !== CHURN_STALE_TAG) };
+            }
             writeEntry(ctx.hippoRoot, updated, { actor: ctx.actor.subject });
             appendAuditEvent(db, {
                 tenantId: ctx.tenantId,

package/dist/churn-git.d.ts

@@ -0,0 +1,22 @@
+/** Git subprocess helpers for FE2 churn-staleness (src/invalidation.ts). */
+/** A real git failure (not git grep's expected exit-1-no-match). Callers abort the whole run on this. */
+export declare class GitReadError extends Error {
+}
+export declare function gitLsFilesAtHead(repoRoot: string): Set<string>;
+export interface ChurnCommitFile {
+    status: string;
+    path: string;
+}
+export interface ChurnCommit {
+    hash: string;
+    date: string;
+    files: ChurnCommitFile[];
+}
+export declare function fetchChurnWindowLog(repoRoot: string, sinceIso: string): ChurnCommit[];
+/** `git grep -o -h -w -F -f <patternFile> <rev>`; returns the subset of `patterns` found. */
+export declare function gitGrepPresence(repoRoot: string, patterns: string[], rev: string): Set<string>;
+/** Last commit at or before `beforeIso`, or null when the repo has none. */
+export declare function resolveCommitBefore(repoRoot: string, beforeIso: string): string | null;
+/** package.json `scripts` at a revision; {} when the file is absent, null when unparsable. Git failures throw GitReadError. */
+export declare function packageScriptsAt(repoRoot: string, rev: string): Record<string, string> | null;
+//# sourceMappingURL=churn-git.d.ts.map

package/dist/churn-git.js

@@ -0,0 +1,102 @@
+/** Git subprocess helpers for FE2 churn-staleness (src/invalidation.ts). */
+import { execFileSync } from 'child_process';
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+// A `git log --name-status` dump can run to tens of MB; default 1MB pipe would truncate it.
+const GIT_MAX_BUFFER = 64 * 1024 * 1024;
+/** A real git failure (not git grep's expected exit-1-no-match). Callers abort the whole run on this. */
+export class GitReadError extends Error {
+}
+function runGit(args, repoRoot) {
+    try {
+        return execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER });
+    }
+    catch (err) {
+        throw new GitReadError(`git ${args.join(' ')} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+// git grep exits 1 for "no match" -- a normal empty result, not a failure.
+function runGitGrepOrEmpty(args, repoRoot) {
+    try {
+        return execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8', maxBuffer: GIT_MAX_BUFFER });
+    }
+    catch (err) {
+        // SAFETY: execFileSync attaches `status` to the thrown Error on a non-zero child exit.
+        const status = err.status;
+        if (status === 1)
+            return '';
+        throw new GitReadError(`git ${args.join(' ')} failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+// ls-tree, not ls-files: the index can hold staged adds/deletes that HEAD does not.
+export function gitLsFilesAtHead(repoRoot) {
+    const raw = runGit(['ls-tree', '-r', '--name-only', 'HEAD'], repoRoot);
+    return new Set(raw.split('\n').map((l) => l.trim()).filter(Boolean));
+}
+// 1-day buffer guards against git's --since boundary excluding a commit dated exactly at the anchor.
+export function fetchChurnWindowLog(repoRoot, sinceIso) {
+    const buffered = new Date(new Date(sinceIso).getTime() - 24 * 60 * 60 * 1000).toISOString();
+    const raw = runGit(
+    // --first-parent -m: a merge's changes land as one diff against its mainline parent.
+    ['log', '--no-renames', '--first-parent', '-m', `--since=${buffered}`, '--pretty=format:%x01%H%x02%cI', '--name-status'], repoRoot);
+    const commits = [];
+    let current = null;
+    for (const line of raw.split('\n')) {
+        if (line.startsWith('\x01')) {
+            const [hash, date] = line.slice(1).split('\x02');
+            current = { hash, date, files: [] };
+            commits.push(current);
+        }
+        else if (current && line.trim()) {
+            const m = line.match(/^([AMD])\s+(.+)$/);
+            if (m)
+                current.files.push({ status: m[1], path: m[2] });
+        }
+    }
+    return commits;
+}
+/** `git grep -o -h -w -F -f <patternFile> <rev>`; returns the subset of `patterns` found. */
+export function gitGrepPresence(repoRoot, patterns, rev) {
+    if (patterns.length === 0)
+        return new Set();
+    const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'hippo-churn-grep-'));
+    try {
+        const patternFile = path.join(tmpDir, 'patterns.txt');
+        fs.writeFileSync(patternFile, `${patterns.join('\n')}\n`, 'utf8');
+        const raw = runGitGrepOrEmpty(['grep', '-o', '-h', '-w', '-F', '-f', patternFile, rev], repoRoot);
+        const patternSet = new Set(patterns);
+        const found = new Set();
+        for (const line of raw.split('\n')) {
+            const t = line.trim();
+            if (patternSet.has(t))
+                found.add(t);
+        }
+        return found;
+    }
+    finally {
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+}
+/** Last commit at or before `beforeIso`, or null when the repo has none. */
+export function resolveCommitBefore(repoRoot, beforeIso) {
+    const raw = runGit(['rev-list', '-1', '--first-parent', `--before=${beforeIso}`, 'HEAD'], repoRoot).trim();
+    return raw === '' ? null : raw;
+}
+/** package.json `scripts` at a revision; {} when the file is absent, null when unparsable. Git failures throw GitReadError. */
+export function packageScriptsAt(repoRoot, rev) {
+    if (runGit(['ls-tree', '--name-only', rev, '--', 'package.json'], repoRoot).trim() === '')
+        return {};
+    const raw = runGit(['show', `${rev}:package.json`], repoRoot);
+    try {
+        // SAFETY: optional chaining makes a `null` or scalar package.json read as "no scripts".
+        const parsed = JSON.parse(raw);
+        return parsed?.scripts ?? {};
+    }
+    catch (err) {
+        if (err instanceof SyntaxError)
+            return null;
+        throw err;
+    }
+}
+//# sourceMappingURL=churn-git.js.map

package/dist/cli.js

@@ -68,7 +68,8 @@ import { FAILURE_LOG_RETENTION_DAYS } from './failure-log.js';
 import { pushGoal, getActiveGoals, completeGoal, suspendGoal, resumeGoal, applyGoalStackBoost } from './goals.js';
 import { rowToGoal } from './goals.js';
 import { captureError, extractLessons, partitionLessons, deduplicateLesson, runWatched, fetchGitLog, isGitRepo, } from './autolearn.js';
-import { extractInvalidationTarget, invalidateMatching } from './invalidation.js';
+import { extractInvalidationTarget, invalidateMatching, detectChurnStale } from './invalidation.js';
+import { resolveProjectIdentity } from './project-identity.js';
 import { extractPathTags } from './path-context.js';
 import { detectScope } from './scope.js';
 import { getGlobalRoot, initGlobal, shareMemory, listPeers, autoShare, transferScore, searchBothHybrid, syncGlobalToLocal, } from './shared.js';
@@ -200,6 +201,24 @@ function requireInit(hippoRoot) {
         process.exit(1);
     }
 }
+/** FE2: run detectChurnStale against every store this repo's memories can live in. */
+function runChurnStaleForRepo(hippoRoot, dryRun) {
+    const repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: process.cwd(), encoding: 'utf8' }).trim();
+    const projectName = resolveProjectIdentity(process.cwd()).name;
+    const globalRoot = getGlobalRoot();
+    const roots = globalRoot !== hippoRoot && isInitialized(globalRoot) ? [hippoRoot, globalRoot] : [hippoRoot];
+    const tenantId = resolveTenantId({});
+    return roots.map((root) => {
+        // One store failing must not abort sleep's later phases or skip the other store.
+        try {
+            return { root, result: detectChurnStale(root, repoRoot, { tenantId, projectName, dryRun }) };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { root, result: { checked: 0, marked: 0, alreadyMarked: 0, skippedPinned: [], dryRun, preview: [], error: message } };
+        }
+    });
+}
 /**
  * H2: when HIPPO_REQUIRE_SERVER is set, the CLI must not silently fall back to
  * direct DB mode — a missing server then masks a real misconfiguration (the
@@ -263,7 +282,7 @@ async function runViaServerIfAvailable(hippoRoot, httpFn) {
 // and as off under === true (`--pin=true` would not pin), so parseArgs and main() refuse one.
 // tests/cli-parse-flag-equals.test.ts fails when a switch read is missing from this set.
 export const BOOLEAN_FLAGS = new Set([
-    'all', 'all-tenants', 'archive', 'auto', 'bad', 'bootstrap', 'classic', 'continuity',
+    'all', 'all-tenants', 'archive', 'auto', 'bad', 'bootstrap', 'classic', 'churn', 'continuity',
     'cross-project', 'dry-run', 'equal-sources', 'error', 'evc-adaptive', 'extract',
     'filter-conflicts', 'fix', 'force', 'forget', 'git', 'global', 'good', 'graph-stream',
     'help', 'include-logs', 'include-superseded', 'inferred', 'json', 'last-session', 'multihop', 'no-hooks',
@@ -2197,6 +2216,8 @@ async function cmdExplain(hippoRoot, query, flags) {
                 console.log(`    source:    x${fmt(b.sourceBump, 2)}  (local priority bump over global)`);
             if (b.outcomeBoost !== 1)
                 console.log(`    outcome:   x${fmt(b.outcomeBoost, 3)}  (user feedback: pos-neg = ${(r.entry.outcome_positive ?? 0) - (r.entry.outcome_negative ?? 0)})`);
+            if (b.churnStaleMultiplier !== 1)
+                console.log(`    churn:     x${fmt(b.churnStaleMultiplier, 2)}  (tagged 'churn-stale')`);
             if (b.preMmrRank !== undefined && b.postMmrRank !== undefined && b.preMmrRank !== b.postMmrRank) {
                 const arrow = b.postMmrRank < b.preMmrRank ? 'up' : 'down';
                 console.log(`    mmr:       rank ${b.preMmrRank} -> ${b.postMmrRank}  (diversity ${arrow})`);
@@ -2840,6 +2861,15 @@ async function cmdSleepCore(hippoRoot, flags) {
             if (added > 0)
                 console.log(`Auto-learned ${added} lessons from today's git commits.`);
         }
+        // FE2: opt-in code-churn staleness, off by default (config.churnStaleness.enabled).
+        if (config.churnStaleness.enabled && isGitRepo(process.cwd())) {
+            for (const { root, result } of runChurnStaleForRepo(hippoRoot, false)) {
+                if (result.marked > 0)
+                    console.log(`Tagged ${result.marked} memories churn-stale in ${root}.`);
+                if (result.error)
+                    console.error(`Churn-staleness check failed for ${root}: ${result.error}`);
+            }
+        }
         // Also learn from Claude Code MEMORY.md files
         const memImported = learnFromMemoryMd(hippoRoot);
         if (memImported > 0)
@@ -9022,6 +9052,11 @@ Commands:
                            'invalidated' re-weakens previously invalidated
                            memories - preview with --dry-run first
     --reason "<why>"       Optional: what replaced it
+  invalidate --churn       FE2: tag memories 'churn-stale' whose named file
+                           changed or was deleted, or whose named symbol or
+                           npm script was removed, in this repo's git history
+                           since the memory was stored or confirmed
+    --dry-run              Preview what would be tagged; writes nothing
   wm <sub>                 Working memory — bounded buffer for current state
     wm push                Push a working memory entry
       --scope <scope>      Scope name (default: default)
@@ -9134,6 +9169,7 @@ Examples:
   hippo invalidate "REST API" --dry-run
   hippo invalidate "REST API" --reason "migrated to GraphQL"
   hippo invalidate --id mem_a1b2c3d4e5f6 --reason "superseded by new policy"
+  hippo invalidate --churn --dry-run
   hippo export memories.json
   hippo export --format markdown memories.md
   hippo sleep --dry-run
@@ -9898,6 +9934,42 @@ async function main(command, args, flags, hippoRoot) {
         }
         case 'invalidate': {
             requireInit(hippoRoot);
+            if (flags['churn'] === true) {
+                if (args[0] || flags['id'] !== undefined) {
+                    console.error('Usage: hippo invalidate --churn [--dry-run]');
+                    console.error('--churn takes no pattern or --id.');
+                    process.exit(1);
+                }
+                if (!isGitRepo(process.cwd())) {
+                    console.error('hippo invalidate --churn must run inside a git repository.');
+                    process.exit(1);
+                }
+                const churnDryRun = flags['dry-run'] === true;
+                let churnFailed = false;
+                for (const { root, result } of runChurnStaleForRepo(hippoRoot, churnDryRun)) {
+                    if (result.error) {
+                        console.error(`Churn-staleness check failed for ${root}: ${result.error}`);
+                        churnFailed = true;
+                        continue;
+                    }
+                    if (result.preview.length === 0) {
+                        console.log(`No churn-stale candidates in ${root}.`);
+                    }
+                    else if (churnDryRun) {
+                        console.log(`DRY RUN - ${result.marked} memories in ${root} WOULD be tagged churn-stale (${result.alreadyMarked} already tagged):`);
+                    }
+                    else {
+                        console.log(`Tagged ${result.marked} memories churn-stale in ${root} (${result.alreadyMarked} already tagged):`);
+                    }
+                    result.preview.forEach(p => console.log(`   ${p.id}  ${p.evidence}  ${p.already ? '(already) ' : ''}${p.headline}`));
+                    if (result.skippedPinned.length > 0) {
+                        console.log(`Skipped ${result.skippedPinned.length} pinned: ${result.skippedPinned.join(', ')}`);
+                    }
+                }
+                if (churnFailed)
+                    process.exit(1);
+                break;
+            }
             const target = args[0];
             if (flags['id'] === true) {
                 // Value-less --id must never silently fall through to pattern mode

package/dist/config.d.ts

@@ -116,6 +116,11 @@ export interface HippoConfig {
          *  Default 180. 0 keeps dormant memories forever. */
         retentionDays: number;
     };
+    /** FE2: tags a memory `churn-stale` when its named file/symbol/script
+     *  changed since storage. Default OFF - FE3 measures before it flips. */
+    churnStaleness: {
+        enabled: boolean;
+    };
 }
 export declare function loadConfig(hippoRoot: string): HippoConfig;
 export declare function saveConfig(hippoRoot: string, config: HippoConfig): void;

package/dist/config.js

@@ -73,6 +73,9 @@ const DEFAULT_CONFIG = {
         enabled: true,
         retentionDays: 180,
     },
+    churnStaleness: {
+        enabled: false,
+    },
 };
 function isMemoryValueConfig(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -80,6 +83,9 @@ function isMemoryValueConfig(value) {
 function isDormantConfig(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+function isChurnStalenessConfig(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
 export function loadConfig(hippoRoot) {
     const configPath = path.join(hippoRoot, 'config.json');
     if (!fs.existsSync(configPath))
@@ -124,6 +130,21 @@ export function loadConfig(hippoRoot) {
                 `(got ${JSON.stringify(dormantRetentionDays)}) - using ${DEFAULT_CONFIG.dormant.retentionDays}.`);
             dormantRetentionDays = DEFAULT_CONFIG.dormant.retentionDays;
         }
+        // Same "never silently wrong" rule as memoryValue/dormant above.
+        const churnStalenessRaw = raw.churnStaleness;
+        const validChurnStalenessConfig = churnStalenessRaw === undefined || isChurnStalenessConfig(churnStalenessRaw);
+        if (!validChurnStalenessConfig) {
+            console.error(`Warning: config.json's "churnStaleness" must be an object like {"enabled": true} ` +
+                `(got ${JSON.stringify(churnStalenessRaw)}) - using defaults.`);
+        }
+        let churnStalenessEnabled = churnStalenessRaw !== undefined && isChurnStalenessConfig(churnStalenessRaw)
+            ? churnStalenessRaw.enabled
+            : DEFAULT_CONFIG.churnStaleness.enabled;
+        if (churnStalenessEnabled !== true && churnStalenessEnabled !== false) {
+            console.error(`Warning: config.json's "churnStaleness.enabled" must be true or false ` +
+                `(got ${JSON.stringify(churnStalenessEnabled)}) - using false.`);
+            churnStalenessEnabled = false;
+        }
         return {
             defaultHalfLifeDays: raw.defaultHalfLifeDays ?? DEFAULT_CONFIG.defaultHalfLifeDays,
             defaultBudget: raw.defaultBudget ?? DEFAULT_CONFIG.defaultBudget,
@@ -155,6 +176,9 @@ export function loadConfig(hippoRoot) {
                 enabled: dormantEnabled,
                 retentionDays: dormantRetentionDays,
             },
+            churnStaleness: {
+                enabled: churnStalenessEnabled,
+            },
         };
     }
     catch (err) {

package/dist/invalidation.d.ts

@@ -38,4 +38,34 @@ export declare function extractInvalidationTarget(message: string): Invalidation
  * auto-learn-from-git path) inherit this contract.
  */
 export declare function invalidateMatching(hippoRoot: string, target: InvalidationTarget, tenantId?: string, options?: InvalidationOptions): InvalidationResult;
+export interface ChurnRefs {
+    paths: string[];
+    symbols: string[];
+    scripts: string[];
+}
+/** Pure syntactic extraction; repo-aware resolution (trackedness, path relativization) happens only in detectChurnStale. */
+export declare function extractChurnRefs(content: string): ChurnRefs;
+export interface DetectChurnStaleOptions {
+    tenantId: string;
+    projectName: string;
+    /** Evaluate matches but write nothing. */
+    dryRun?: boolean;
+}
+export interface ChurnStalePreviewRow {
+    id: string;
+    headline: string;
+    evidence: string;
+    already: boolean;
+}
+export interface ChurnStaleResult {
+    checked: number;
+    marked: number;
+    alreadyMarked: number;
+    skippedPinned: string[];
+    dryRun: boolean;
+    preview: ChurnStalePreviewRow[];
+    error?: string;
+}
+/** Flags memories whose named file/symbol/script changed or disappeared since storage (or last confirmation); only adds/removes CHURN_STALE_TAG, never confidence/half-life/strength. */
+export declare function detectChurnStale(hippoRoot: string, repoRoot: string, opts: DetectChurnStaleOptions): ChurnStaleResult;
 //# sourceMappingURL=invalidation.d.ts.map

package/dist/invalidation.js

@@ -1,4 +1,7 @@
-import { loadAllEntries, writeEntry } from './store.js';
+import { loadAllEntries, readEntry, writeEntry } from './store.js';
+import { openHippoDb, closeHippoDb } from './db.js';
+import { CHURN_STALE_TAG } from './memory.js';
+import { GitReadError, gitLsFilesAtHead, fetchChurnWindowLog, gitGrepPresence, resolveCommitBefore, packageScriptsAt, } from './churn-git.js';
 /**
  * Extract what was replaced/removed from a commit message.
  * Returns null if the commit isn't a breaking/migration change.
@@ -126,4 +129,266 @@ function matchScore(fromTokens, contentTokens) {
     const matches = fromTokens.filter(t => contentSet.has(t)).length;
     return matches / fromTokens.length;
 }
+// FE2: staleness from code churn (opt-in, ROADMAP Part XIII).
+const CHURN_PATH_EXTENSIONS = [
+    'ts', 'tsx', 'js', 'mjs', 'cjs', 'py', 'md', 'json', 'sh', 'ps1',
+    'toml', 'yml', 'yaml', 'sql', 'rs', 'go', 'css', 'html',
+];
+const CHURN_PATH_RE = new RegExp(
+// The lookahead stops `ts` winning over `tsx` and `js` over `json`.
+`[A-Za-z0-9_./\\\\:-]+\\.(?:${CHURN_PATH_EXTENSIONS.join('|')})(?![A-Za-z0-9_])(?::\\d+(?:-\\d+)?)?`, 'g');
+const CHURN_SYMBOL_RE = /`([A-Za-z_$][A-Za-z0-9_$]*)(?:\(\))?`/g;
+const CHURN_SCRIPT_RE = /npm run(?:-script)?\s+([A-Za-z0-9:_-]+)/g;
+/** Pure syntactic extraction; repo-aware resolution (trackedness, path relativization) happens only in detectChurnStale. */
+export function extractChurnRefs(content) {
+    const paths = new Set();
+    for (const m of content.matchAll(CHURN_PATH_RE)) {
+        let token = m[0].replace(/:\d+(?:-\d+)?$/, '');
+        token = token.replace(/\\/g, '/').replace(/^\.\//, '');
+        if (token)
+            paths.add(token);
+    }
+    const symbols = new Set();
+    for (const m of content.matchAll(CHURN_SYMBOL_RE)) {
+        const name = m[1];
+        // Plain words never count: require a camelCase/PascalCase transition or an inner underscore.
+        if (name.length >= 6 && (/[a-z][A-Z]/.test(name) || /[A-Za-z0-9]_[A-Za-z0-9]/.test(name))) {
+            symbols.add(name);
+        }
+    }
+    const scripts = new Set();
+    for (const m of content.matchAll(CHURN_SCRIPT_RE))
+        scripts.add(m[1]);
+    return { paths: [...paths], symbols: [...symbols], scripts: [...scripts] };
+}
+const IS_WIN32 = process.platform === 'win32';
+function buildTrackedIndex(paths) {
+    const lower = new Map();
+    for (const p of paths)
+        lower.set(p.toLowerCase(), p);
+    return { exact: paths, lower };
+}
+// Returns git's spelling so later exact matches against the log agree on case-insensitive Windows.
+function trackedSpelling(index, candidate) {
+    if (index.exact.has(candidate))
+        return candidate;
+    return IS_WIN32 ? index.lower.get(candidate.toLowerCase()) ?? null : null;
+}
+function isTrackedPath(index, candidate) {
+    return trackedSpelling(index, candidate) !== null;
+}
+// Absolute-path relativization and the <repoName>/ strip both need the repo, so they
+// happen here rather than in the pure extractor.
+function resolveTrackedPath(token, repoRoot, projectName, index) {
+    let candidate = token;
+    const isAbsUnix = candidate.startsWith('/');
+    const isAbsWin = /^[A-Za-z]:\//.test(candidate);
+    if (isAbsUnix || isAbsWin) {
+        const rootPosix = repoRoot.replace(/\\/g, '/').replace(/\/$/, '');
+        const prefix = `${rootPosix}/`;
+        const under = IS_WIN32
+            ? candidate.toLowerCase().startsWith(prefix.toLowerCase())
+            : candidate.startsWith(prefix);
+        if (!under)
+            return null;
+        candidate = candidate.slice(prefix.length);
+    }
+    const direct = trackedSpelling(index, candidate);
+    if (direct)
+        return direct;
+    const repoPrefix = `${projectName}/`;
+    if (candidate.toLowerCase().startsWith(repoPrefix.toLowerCase())) {
+        return trackedSpelling(index, candidate.slice(repoPrefix.length));
+    }
+    return null;
+}
+// Anchor SQL runs on its own handle (closed in finally); queryAuditEvents is NOT
+// reused here because its 10k-row cap would silently miss old confirmations.
+function queryConfirmedAt(hippoRoot, tenantId) {
+    const db = openHippoDb(hippoRoot);
+    try {
+        // SAFETY: the SELECT list above is exactly target_id and ts; no other shape reaches this cast.
+        const rows = db.prepare(`SELECT target_id, MAX(ts) AS ts FROM audit_log
+       WHERE tenant_id = ? AND op = 'outcome' AND target_id IS NOT NULL
+         AND json_extract(metadata_json, '$.good') = 1
+       GROUP BY target_id`).all(tenantId);
+        return new Map(rows.map((r) => [r.target_id, r.ts]));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+function emptyChurnResult(dryRun, skippedPinned = [], error) {
+    const result = { checked: 0, marked: 0, alreadyMarked: 0, skippedPinned, dryRun, preview: [] };
+    if (error !== undefined)
+        result.error = error;
+    return result;
+}
+/** Flags memories whose named file/symbol/script changed or disappeared since storage (or last confirmation); only adds/removes CHURN_STALE_TAG, never confidence/half-life/strength. */
+export function detectChurnStale(hippoRoot, repoRoot, opts) {
+    const dryRun = opts.dryRun === true;
+    if (!opts.projectName)
+        return emptyChurnResult(dryRun);
+    const entries = loadAllEntries(hippoRoot, opts.tenantId);
+    const skippedPinned = [];
+    const candidates = [];
+    for (const entry of entries) {
+        if (!entry.origin_project || entry.origin_project !== opts.projectName)
+            continue;
+        if (entry.superseded_by)
+            continue;
+        if (entry.kind === 'raw' || entry.kind === 'archived')
+            continue;
+        if (entry.pinned) {
+            skippedPinned.push(entry.id);
+            continue;
+        }
+        // An unparsable created has no anchor to compare commits against.
+        if (Number.isNaN(Date.parse(entry.created)))
+            continue;
+        candidates.push({ entry, refs: extractChurnRefs(entry.content) });
+    }
+    if (candidates.length === 0)
+        return emptyChurnResult(dryRun, skippedPinned);
+    const confirmedAt = queryConfirmedAt(hippoRoot, opts.tenantId);
+    // Compared as epoch ms, not strings: imported rows may carry offsets or other ISO forms.
+    const anchorOf = (entry) => {
+        const confirmed = confirmedAt.get(entry.id);
+        const confirmedMs = confirmed ? Date.parse(confirmed) : NaN;
+        return confirmedMs > Date.parse(entry.created) ? new Date(confirmedMs).toISOString() : new Date(entry.created).toISOString();
+    };
+    const needsPaths = candidates.some((c) => c.refs.paths.length > 0);
+    const needsSymbols = candidates.some((c) => c.refs.symbols.length > 0);
+    const needsScripts = candidates.some((c) => c.refs.scripts.length > 0);
+    if (!needsPaths && !needsSymbols && !needsScripts) {
+        return { checked: candidates.length, marked: 0, alreadyMarked: 0, skippedPinned, dryRun, preview: [] };
+    }
+    const result = { checked: 0, marked: 0, alreadyMarked: 0, skippedPinned, dryRun, preview: [] };
+    try {
+        const headFiles = gitLsFilesAtHead(repoRoot);
+        let windowLog = [];
+        if (needsPaths) {
+            const minAnchor = candidates.reduce((min, c) => {
+                const a = anchorOf(c.entry);
+                return min === '' || a < min ? a : min;
+            }, '');
+            windowLog = fetchChurnWindowLog(repoRoot, minAnchor);
+        }
+        const touchedInWindow = new Set();
+        for (const c of windowLog)
+            for (const f of c.files)
+                touchedInWindow.add(f.path);
+        const trackedIndex = buildTrackedIndex(new Set([...headFiles, ...touchedInWindow]));
+        const headIndex = buildTrackedIndex(headFiles);
+        const presentAtHeadSymbols = needsSymbols
+            ? gitGrepPresence(repoRoot, [...new Set(candidates.flatMap((c) => c.refs.symbols))], 'HEAD')
+            : new Set();
+        const anchorCommitCache = new Map();
+        const resolveAnchorCommit = (anchorIso) => {
+            if (!anchorCommitCache.has(anchorIso)) {
+                anchorCommitCache.set(anchorIso, resolveCommitBefore(repoRoot, anchorIso));
+            }
+            return anchorCommitCache.get(anchorIso) ?? null;
+        };
+        const symbolsAtCommit = new Map();
+        const symbolsPresentAt = (hash, symbols) => {
+            const known = symbolsAtCommit.get(hash) ?? new Set();
+            const missing = symbols.filter((s) => !known.has(s));
+            if (missing.length > 0) {
+                for (const s of gitGrepPresence(repoRoot, missing, hash))
+                    known.add(s);
+                symbolsAtCommit.set(hash, known);
+            }
+            return known;
+        };
+        const headScripts = needsScripts ? packageScriptsAt(repoRoot, 'HEAD') : null;
+        const scriptsAtCommit = new Map();
+        // Collected here, written only after every candidate's evidence is
+        // computed: a GitReadError thrown mid-loop must never leave an earlier
+        // candidate tagged while a later one aborts the run untagged.
+        const toTag = [];
+        for (const { entry, refs } of candidates) {
+            result.checked++;
+            const anchor = anchorOf(entry);
+            const anchorTime = new Date(anchor).getTime();
+            let evidence = null;
+            for (const rawPath of refs.paths) {
+                const resolved = resolveTrackedPath(rawPath, repoRoot, opts.projectName, trackedIndex);
+                if (!resolved)
+                    continue;
+                if (isTrackedPath(headIndex, resolved)) {
+                    const changed = windowLog.some((c) => new Date(c.date).getTime() > anchorTime && c.files.some((f) => f.path === resolved));
+                    if (changed) {
+                        evidence = `file-changed: ${resolved}`;
+                        break;
+                    }
+                }
+                else {
+                    // --no-renames means a rename shows as a D + A pair, so this also fires for renames.
+                    const deleted = windowLog.some((c) => new Date(c.date).getTime() > anchorTime &&
+                        c.files.some((f) => f.status === 'D' && f.path === resolved));
+                    if (deleted) {
+                        evidence = `file-deleted: ${resolved}`;
+                        break;
+                    }
+                }
+            }
+            if (!evidence && refs.symbols.length > 0) {
+                const absent = refs.symbols.filter((s) => !presentAtHeadSymbols.has(s));
+                if (absent.length > 0) {
+                    const anchorCommit = resolveAnchorCommit(anchor);
+                    if (anchorCommit) {
+                        const presentAtAnchor = symbolsPresentAt(anchorCommit, absent);
+                        const hit = absent.find((s) => presentAtAnchor.has(s));
+                        if (hit)
+                            evidence = `symbol-gone: \`${hit}\``;
+                    }
+                }
+            }
+            if (!evidence && refs.scripts.length > 0 && headScripts !== null) {
+                const anchorCommit = resolveAnchorCommit(anchor);
+                if (anchorCommit) {
+                    if (!scriptsAtCommit.has(anchorCommit)) {
+                        scriptsAtCommit.set(anchorCommit, packageScriptsAt(repoRoot, anchorCommit));
+                    }
+                    const anchorScripts = scriptsAtCommit.get(anchorCommit);
+                    const hit = anchorScripts
+                        ? refs.scripts.find((s) => anchorScripts[s] !== undefined && headScripts[s] === undefined)
+                        : undefined;
+                    if (hit)
+                        evidence = `script-gone: ${hit}`;
+                }
+            }
+            if (!evidence)
+                continue;
+            const headline = entry.content.replace(/\s+/g, ' ').slice(0, 60);
+            if (entry.tags.includes(CHURN_STALE_TAG)) {
+                result.alreadyMarked++;
+                result.preview.push({ id: entry.id, headline, evidence, already: true });
+                continue;
+            }
+            result.marked++;
+            result.preview.push({ id: entry.id, headline, evidence, already: false });
+            toTag.push(entry);
+        }
+        if (!dryRun && toTag.length > 0) {
+            // The git calls above can take seconds; a good outcome landing meanwhile moves the anchor past the evidence.
+            const confirmedNow = queryConfirmedAt(hippoRoot, opts.tenantId);
+            for (const stale of toTag) {
+                if (confirmedNow.get(stale.id) !== confirmedAt.get(stale.id))
+                    continue;
+                const entry = readEntry(hippoRoot, stale.id, opts.tenantId);
+                if (!entry || entry.tags.includes(CHURN_STALE_TAG))
+                    continue;
+                writeEntry(hippoRoot, { ...entry, tags: [...entry.tags, CHURN_STALE_TAG] });
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof GitReadError)
+            return emptyChurnResult(dryRun, skippedPinned, err.message);
+        throw err;
+    }
+    return result;
+}
 //# sourceMappingURL=invalidation.js.map

package/dist/memory.d.ts

@@ -120,6 +120,8 @@ export declare const POLICY_HALF_LIFE_DAYS = 90;
 export declare const SKILL_HALF_LIFE_DAYS = 90;
 export declare const PROJECT_BRIEF_HALF_LIFE_DAYS = 90;
 export declare const CUSTOMER_NOTE_HALF_LIFE_DAYS = 90;
+/** FE2: tag on a memory whose named file/symbol/script changed after it was stored. */
+export declare const CHURN_STALE_TAG = "churn-stale";
 /**
  * Test-only helper. Tests that mutate `process.env.HIPPO_LOSS_AVERSION_RATIO`
  * MUST call this in BOTH `beforeEach` AND `afterEach`:

package/dist/memory.js

@@ -18,6 +18,8 @@ export const POLICY_HALF_LIFE_DAYS = 90;
 export const SKILL_HALF_LIFE_DAYS = 90;
 export const PROJECT_BRIEF_HALF_LIFE_DAYS = 90;
 export const CUSTOMER_NOTE_HALF_LIFE_DAYS = 90;
+/** FE2: tag on a memory whose named file/symbol/script changed after it was stored. */
+export const CHURN_STALE_TAG = 'churn-stale';
 // Emotional multipliers from PLAN.md.
 //
 // v1.13.5 / J5 loss-aversion calibration (Lovallo-Kahneman TFAS empirics:

package/dist/search.d.ts

@@ -5,6 +5,8 @@
 import { estimateTokens } from './token-ledger.js';
 import { MemoryEntry } from './memory.js';
 import type { PhysicsConfig } from './physics-config.js';
+export declare const CHURN_STALE_RANK_MULTIPLIER = 0.5;
+export declare function churnStaleFactor(entry: MemoryEntry): number;
 export declare function tokenize(text: string): string[];
 /**
  * Tokenized BM25 corpus. Callers can pre-build this with `buildCorpus` once
@@ -119,6 +121,8 @@ export interface ScoreBreakdown {
      *  to [0.85, 1.15]. Immediate nudge from `hippo outcome --good/--bad`.
      *  Separate from the slow strength-via-reward-factor path. */
     outcomeBoost: number;
+    /** FE2: CHURN_STALE_RANK_MULTIPLIER if tagged 'churn-stale', else 1.0. */
+    churnStaleMultiplier: number;
     /** Pre-MMR rank (1-indexed). Only set when MMR re-ranking ran. */
     preMmrRank?: number;
     /** Post-MMR rank (1-indexed). Only set when MMR re-ranking ran. */

package/dist/search.js

@@ -3,7 +3,7 @@
  * Zero external dependencies when embeddings are not available.
  */
 import { estimateTokens } from './token-ledger.js';
-import { calculateStrength, netWrong } from './memory.js';
+import { calculateStrength, netWrong, CHURN_STALE_TAG } from './memory.js';
 import { isOutcomeFastAblated, isRecallBoostAblated, isRecencyAblated, evalRecencyScaleDays, evalNow } from './ablation.js';
 import { extractPathTags, pathBoostMultiplier } from './path-context.js';
 import { detectScope, scopeMatch } from './scope.js';
@@ -16,6 +16,10 @@ import { openHippoDb, closeHippoDb } from './db.js';
 import { rrfFuse } from './rrf.js';
 import { graphRankStream, selectGraphSeeds, DEFAULT_GRAPH_SEED_COUNT } from './graph-stream.js';
 import { compareEntryIdentity, compareScoredResults } from './compare.js';
+export const CHURN_STALE_RANK_MULTIPLIER = 0.5; // SHORTCUT: untuned; FE3 measures before any default.
+export function churnStaleFactor(entry) {
+    return entry.tags.includes(CHURN_STALE_TAG) ? CHURN_STALE_RANK_MULTIPLIER : 1.0;
+}
 // ---------------------------------------------------------------------------
 // Tokenizer
 // ---------------------------------------------------------------------------
@@ -368,6 +372,8 @@ export async function hybridSearch(query, entries, options = {}) {
         // Decision-tagged memories get a 1.2x recall boost
         const decisionBoost = entries[i].tags.includes('decision') ? 1.2 : 1.0;
         compositeScore *= decisionBoost;
+        const churnStaleMultiplier = churnStaleFactor(entries[i]);
+        compositeScore *= churnStaleMultiplier;
         // Path-based boost: memories tagged with matching path segments get up to 1.3x
         const pathBoost = pathBoostMultiplier(entries[i].tags, currentPathTags);
         compositeScore *= pathBoost;
@@ -424,6 +430,7 @@ export async function hybridSearch(query, entries, options = {}) {
                 scopeBoost,
                 sourceBump: 1,
                 outcomeBoost,
+                churnStaleMultiplier,
                 matchedTerms,
                 final: compositeScore,
                 ageDays,
@@ -476,7 +483,7 @@ export async function hybridSearch(query, entries, options = {}) {
         for (const child of childEntriesAsync) {
             if (!scoredDeduped.some((r) => r.entry.id === child.id)) {
                 const parentResult = scoredDeduped.find((r) => r.entry.id === child.dag_parent_id);
-                const childScore = parentResult ? parentResult.score * 0.9 : 0;
+                const childScore = parentResult ? parentResult.score * 0.9 * churnStaleFactor(child) : 0;
                 scoredDeduped.push({
                     entry: child,
                     score: childScore,
@@ -700,7 +707,8 @@ export async function physicsSearch(query, entries, options = {}) {
                     freshnessMultiplier = summaryFreshnessMultiplier(entry, now);
                 }
             }
-            const finalScore = s.finalScore * summaryDeboostMultiplier * freshnessMultiplier;
+            const churnStaleMultiplier = churnStaleFactor(entry);
+            const finalScore = s.finalScore * summaryDeboostMultiplier * freshnessMultiplier * churnStaleMultiplier;
             if (finalScore <= 0)
                 continue;
             const result = {
@@ -726,6 +734,7 @@ export async function physicsSearch(query, entries, options = {}) {
                     scopeBoost: 1,
                     sourceBump: 1,
                     outcomeBoost: 1,
+                    churnStaleMultiplier,
                     matchedTerms: [],
                     final: finalScore,
                     ageDays,
@@ -768,8 +777,9 @@ export async function physicsSearch(query, entries, options = {}) {
 }
 /** Normalize two score pools to [0,1] and combine. */
 function mergeScorePools(poolA, poolB) {
-    const maxA = poolA.reduce((m, r) => Math.max(m, r.score), 1e-9);
-    const maxB = poolB.reduce((m, r) => Math.max(m, r.score), 1e-9);
+    const unpenalised = (r) => r.score / churnStaleFactor(r.entry);
+    const maxA = poolA.reduce((m, r) => Math.max(m, unpenalised(r)), 1e-9);
+    const maxB = poolB.reduce((m, r) => Math.max(m, unpenalised(r)), 1e-9);
     const merged = [];
     for (const r of poolA) {
         merged.push({ ...r, score: r.score / maxA });
@@ -842,6 +852,7 @@ export function search(query, entries, options = {}) {
         // Decision-tagged memories get a 1.2x recall boost
         const decisionBoost = entries[i].tags.includes('decision') ? 1.2 : 1.0;
         composite *= decisionBoost;
+        composite *= churnStaleFactor(entries[i]);
         // Path-based boost: memories tagged with matching path segments get up to 1.3x
         composite *= pathBoostMultiplier(entries[i].tags, currentPathTagsSync);
         // Scope boost (sync path)
@@ -883,7 +894,7 @@ export function search(query, entries, options = {}) {
         for (const child of childEntries) {
             if (!dedupedSync.some((r) => r.entry.id === child.id)) {
                 const parentResult = dedupedSync.find((r) => r.entry.id === child.dag_parent_id);
-                const childScore = parentResult ? parentResult.score * 0.9 : 0;
+                const childScore = parentResult ? parentResult.score * 0.9 * churnStaleFactor(child) : 0;
                 dedupedSync.push({
                     entry: child,
                     score: childScore,

package/dist/version.d.ts

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export declare const PACKAGE_VERSION = "1.50.0";
+export declare const PACKAGE_VERSION = "1.51.0";
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export declare function compareSemver(a: string, b: string): number;
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export const PACKAGE_VERSION = '1.50.0';
+export const PACKAGE_VERSION = '1.51.0';
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export function compareSemver(a, b) {
     const parse = (v) => {

package/extensions/openclaw-plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Biologically-inspired memory for AI agents. Decay by default, retrieval strengthening, sleep consolidation.",
-  "version": "1.50.0",
+  "version": "1.51.0",
 
   "configSchema": {
     "type": "object",

package/extensions/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.50.0",
+  "version": "1.51.0",
   "type": "module",
   "description": "Hippo Memory plugin for OpenClaw - biologically-inspired agent memory",
   "main": "index.ts",

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Biologically-inspired memory for AI agents. Decay by default, retrieval strengthening, sleep consolidation.",
-  "version": "1.50.0",
+  "version": "1.51.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.50.0",
+  "version": "1.51.0",
   "description": "Biologically-inspired memory for AI agents. Zero runtime deps, SQLite, MCP server, and an opt-in hosted TypeSafe Jev reranker. Decay, retrieval strengthening, consolidation.",
   "mcpName": "io.github.kitfunso/hippo-memory",
   "type": "module",