hippo-memory 1.55.0 → 1.57.0

package/dist/cli/shared.js

@@ -0,0 +1,830 @@
+// Helpers two or more CLI verbs use, split from cli.ts so a verb can move to its own file without importing cli.ts.
+// This module must never import cli.ts.
+import * as path from 'path';
+import * as fs from 'fs';
+import { execFileSync, execSync } from 'child_process';
+import { installJsonHooks, CODEX_TRUST_LINE } from '../hooks.js';
+import { confidenceLabel, computeSchemaFit, createMemory, Layer } from '../memory.js';
+import { isInitialized, loadAllEntries, writeEntry, updateStats } from '../store.js';
+import { RejectedValueError } from '../rejection.js';
+import { explainMatch } from '../search.js';
+import { embedMemory } from '../embeddings.js';
+import { loadConfig } from '../config.js';
+import { openHippoDb, closeHippoDb } from '../db.js';
+import { hookPayloadSessionId, isSubagentPayload, recordTokenUse } from '../token-ledger.js';
+import { isGitRepo, fetchGitLog, extractLessons, partitionLessons } from '../autolearn.js';
+import { storedTextKeys, duplicateKey } from '../same-text.js';
+import { importAtSessionEnd, currentMachine } from '../agent-memories/sync.js';
+import { summaryLine } from '../agent-memories/report.js';
+import { detectChurnStale, extractInvalidationTarget, invalidateMatching } from '../invalidation.js';
+import { resolveProjectIdentity } from '../project-identity.js';
+import { extractPathTags } from '../path-context.js';
+import { getGlobalRoot, initGlobal } from '../shared.js';
+import { DAILY_TASK_NAME, buildDailyRunnerCommand, buildSchtasksCreateArgs, buildWindowsTaskRun } from '../scheduler.js';
+import { sanitizeLogMessage } from '../capture.js';
+import { appendAuditEvent } from '../audit.js';
+import { createHash } from 'node:crypto';
+import * as client from '../client.js';
+import { detectServer, removePidfileIfOwned } from '../server-detect.js';
+import { resolveTenantId } from '../tenant.js';
+import { snapshotText, sessionTrailText, handoffText } from '../context-render.js';
+export function parseLimitFlag(value) {
+    if (!value)
+        return Infinity;
+    const parsed = parseInt(String(value), 10);
+    return Number.isFinite(parsed) && parsed >= 1 ? parsed : Infinity;
+}
+export function parseCountFlag(value) {
+    if (!value || value === true || Array.isArray(value))
+        return 0;
+    const parsed = parseInt(String(value), 10);
+    return Number.isFinite(parsed) && parsed >= 1 ? parsed : 0;
+}
+export function parseBudgetFlag(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    // A value-less flag and a junk value are different typos; the --hops guard already splits them.
+    if (typeof value !== 'string') {
+        console.error('--budget requires an integer value (e.g. --budget 1500).');
+        process.exit(1);
+    }
+    // Number(), like the --hops guard: parseInt('12abc') is 12, silently accepting what this message rejects.
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        console.error(`Invalid --budget: "${value}". Must be a non-negative integer.`);
+        process.exit(1);
+    }
+    return parsed;
+}
+/**
+ * Emit an audit event against `hippoRoot`'s db. Opens its own short-lived
+ * connection so callers don't have to thread a db handle. Swallows all errors
+ * — audit must never crash a CLI command.
+ */
+export function emitCliAudit(hippoRoot, op, targetId, metadata) {
+    try {
+        const db = openHippoDb(hippoRoot);
+        try {
+            appendAuditEvent(db, {
+                tenantId: resolveTenantId({}),
+                actor: 'cli',
+                op,
+                targetId,
+                metadata,
+            });
+        }
+        finally {
+            closeHippoDb(db);
+        }
+    }
+    catch {
+        // Audit is best-effort; surface failures only via missing rows.
+    }
+}
+export function requireInit(hippoRoot) {
+    if (!isInitialized(hippoRoot)) {
+        console.error(`No hippo store at ${hippoRoot} (searched ${process.cwd()} and its parents up to your home directory). Run \`hippo init\` first.`);
+        process.exit(1);
+    }
+}
+/** Runs detectChurnStale against every store this repo's memories can live in. */
+export function runChurnStaleForRepo(hippoRoot, dryRun) {
+    const repoRoot = execFileSync('git', ['rev-parse', '--show-toplevel'], { cwd: process.cwd(), encoding: 'utf8', windowsHide: true }).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 } };
+        }
+    });
+}
+/**
+ * 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
+ * configured HIPPO_API_KEY is also silently discarded on fallback). Throws a
+ * clear error then. It guards only the routed writes (remember, forget, archive,
+ * promote); every other command opens the store directly, knob or not.
+ */
+function failIfServerRequired(reason) {
+    if (process.env['HIPPO_REQUIRE_SERVER']) {
+        throw new Error(`hippo: HIPPO_REQUIRE_SERVER is set but ${reason}. ` +
+            `Start \`hippo serve\`, or unset HIPPO_REQUIRE_SERVER to allow direct-mode fallback.`);
+    }
+}
+/**
+ * Run an HTTP-routed command if a `hippo serve` instance is detected for
+ * `hippoRoot`. Returns:
+ *   - true  if the HTTP path ran (success OR a structured server error that
+ *           was already surfaced to stdout/stderr by `httpFn`),
+ *   - false if no server was detected, or if the detected pidfile turned out
+ *           to be stale (connection refused). On stale, the pidfile is removed
+ *           if it still names that dead server (a newer one may have replaced
+ *           it) and the caller should fall back to the direct path.
+ *
+ * Stale pidfiles must self-heal, not crash.
+ * When HIPPO_REQUIRE_SERVER is set, both fallback paths throw instead of
+ * returning false, so a missing server fails loudly rather than silently
+ * degrading to direct mode.
+ */
+export async function runViaServerIfAvailable(hippoRoot, httpFn) {
+    const info = await detectServer(hippoRoot);
+    if (!info) {
+        failIfServerRequired('no running server was detected for this hippoRoot');
+        return false;
+    }
+    const apiKey = process.env['HIPPO_API_KEY'];
+    try {
+        await httpFn(info, apiKey);
+        return true;
+    }
+    catch (err) {
+        const failure = client.classifyTransportFailure(err);
+        if (failure === 'never-sent') {
+            failIfServerRequired('the server pidfile was stale (connection refused)');
+            console.error('hippo: stale server pidfile detected, falling back to direct mode');
+            // Clear the pidfile only if it still names the dead server we just
+            // probed — a newer server may have rewritten it (removePidfileIfOwned).
+            removePidfileIfOwned(hippoRoot, { pid: info.pid, startedAt: info.started_at });
+            return false;
+        }
+        if (failure === 'delivery-unknown') {
+            // Every caller of this helper is a non-idempotent write, so replaying on
+            // the direct path would store a row the server may already have committed.
+            // Leave the pidfile alone: the next command's connect-phase failure heals it.
+            console.error(`hippo: the connection to ${info.url} dropped mid-request, so the write may already have been applied. Not retrying locally. Check with \`hippo recall\` before running this again.`);
+            process.exit(1);
+        }
+        throw err;
+    }
+}
+export function fmt(n, digits = 2) {
+    return n.toFixed(digits);
+}
+// What `hippo recall` prints for one result; the budget prices this same text.
+export function recallEntryText(r, query, showWhy, isGlobal) {
+    const e = r.entry;
+    const label = confidenceLabel(e);
+    const confLabel = label.warn ? `[${label.text}] ⚠️` : `[${label.text}]`;
+    const bars = Math.round(e.strength * 10);
+    const graphMark = r.graphVia ? ` [graph: ${r.graphVia.hops}hop ${r.graphVia.relType}]` : '';
+    const lines = [
+        `--- ${e.id} [${e.layer}] ${confLabel}${isGlobal ? ' [global]' : ''}${e.superseded_by ? ' [superseded]' : ''}${graphMark} score=${fmt(r.score, 3)} strength=${fmt(e.strength)}`,
+        `    [${'█'.repeat(bars)}${'░'.repeat(10 - bars)}] tags: ${e.tags.join(', ') || 'none'} | retrieved: ${e.retrieval_count}x`,
+    ];
+    if (showWhy) {
+        const explanation = explainMatch(query, r);
+        lines.push(`    source:${isGlobal ? ' [global]' : ' [local]'} | layer: [${e.layer}] | confidence: [${label.text}]`, `    reason: ${explanation.reason}`);
+        const env = explanation.envelope;
+        if (env) {
+            lines.push(`    kind: ${env.kind}`);
+            if (env.scope)
+                lines.push(`    scope: ${env.scope}`);
+            if (env.owner)
+                lines.push(`    owner: ${env.owner}`);
+            if (env.artifact_ref)
+                lines.push(`    artifact_ref: ${env.artifact_ref}`);
+            if (env.session_id)
+                lines.push(`    session_id: ${env.session_id}`);
+            lines.push(`    confidence: ${env.confidence}`);
+        }
+        // The recall trace, e.g. "ranking: base 0.420 -> interference x0.30 -> 0.126 -> goal-boost x1.50 -> 0.189".
+        if (r.rerankTrace && r.rerankTrace.length > 0) {
+            const parts = [`base ${fmt(r.rerankTrace[0].scoreBefore, 3)}`];
+            for (const step of r.rerankTrace) {
+                parts.push(`${step.stage}${step.multiplier !== undefined ? ` x${fmt(step.multiplier, 2)}` : ''}`, fmt(step.scoreAfter, 3));
+            }
+            lines.push(`    ranking: ${parts.join(' -> ')}`);
+        }
+    }
+    lines.push('', e.content, '');
+    return lines.join('\n');
+}
+export function recallHeading(entries, tokens, query) {
+    return `Found ${entries} memories (${tokens} tokens) for: "${query}"\n`;
+}
+/** One line when an agent memory import moved anything; its warnings go to stderr. */
+export function printAgentImport(report, indent = '   ') {
+    const line = summaryLine(report);
+    if (line !== null)
+        console.log(`${indent}${line}`);
+    for (const warning of report.warnings)
+        console.error(`hippo: agent memories: ${warning}`);
+}
+/** The first hippo block in `text` and the agent whose current or shipped text it is; `owner` is undefined for an edited block. */
+export function hippoBlock(text) {
+    const at = text.indexOf(HOOK_MARKERS.start);
+    const start = at + HOOK_MARKERS.start.length;
+    const end = text.indexOf(HOOK_MARKERS.end, start);
+    if (at < 0 || end < 0)
+        return null;
+    // git autocrlf checks these files out with CRLF: match as LF, write back in the file's own ending.
+    const raw = text.slice(start, end);
+    const inner = raw.replace(/\r\n/g, '\n').trim();
+    const owner = Object.keys(HOOKS).find((k) => HOOKS[k].content === inner) ?? SHIPPED_HOOK_HASHES.get(createHash('sha256').update(inner).digest('hex'));
+    return { start, end, eol: raw.includes('\r\n') ? '\r\n' : '\n', inner, owner };
+}
+/** Adds hippo's two Codex hooks and says what changed; each install ends on the trust reminder, since Codex skips an untrusted hook. */
+export function installCodexMemoryHooks(indent) {
+    const result = installJsonHooks('codex');
+    if (result.invalidJson) {
+        console.log(`${indent}WARNING: ${result.settingsPath} is not a hooks file hippo can merge into; fix it, then run \`hippo hook install codex\`.`);
+        return;
+    }
+    const added = [
+        result.installedUserPromptSubmit ? 'UserPromptSubmit' : '',
+        result.installedCompactResume ? 'SessionStart(compact)' : '',
+    ].filter(Boolean);
+    console.log(added.length > 0
+        ? `${indent}Installed hippo's Codex memory hooks (${added.join(', ')}) in ${result.settingsPath}`
+        : `${indent}hippo's Codex memory hooks already in ${result.settingsPath}`);
+    console.log(`${indent}${CODEX_TRUST_LINE}`);
+}
+/**
+ * Set up a machine-level daily runner that sweeps all registered Hippo
+ * workspaces.
+ * Linux/macOS: writes to user crontab.
+ * Windows: creates a scheduled task.
+ * Skips if already installed.
+ */
+export function setupDailySchedule(globalRoot) {
+    const runnerDir = path.resolve(globalRoot);
+    // Reject paths with characters that could break shell/crontab quoting
+    // (backslash is normal on Windows, only dangerous in Unix shell/crontab)
+    const unsafeChars = process.platform === 'win32' ? /["`$%\n\r]/ : /["`$\n\r\\]/;
+    if (unsafeChars.test(runnerDir)) {
+        console.log(`   Skipping schedule: runner path contains unsafe characters.`);
+        return;
+    }
+    const isWindows = process.platform === 'win32';
+    const taskName = DAILY_TASK_NAME;
+    const cmd = buildDailyRunnerCommand(runnerDir);
+    if (isWindows) {
+        // Check if task already exists
+        try {
+            const existing = execSync(`schtasks /query /tn "${taskName}" 2>nul`, { encoding: 'utf-8', windowsHide: true });
+            if (existing.includes(taskName)) {
+                return; // already scheduled
+            }
+        }
+        catch {
+            // Task doesn't exist, create it
+        }
+        try {
+            execFileSync('schtasks', buildSchtasksCreateArgs(taskName, cmd), { stdio: 'pipe', windowsHide: true });
+            console.log(`   Scheduled machine-level daily runner (6:15am) via Task Scheduler: ${taskName}`);
+        }
+        catch {
+            // No admin rights or schtasks unavailable, fall back to printing instructions
+            console.log(`   To schedule the machine-level daily runner, run:`);
+            console.log(`   schtasks /create /tn "${taskName}" /tr "${buildWindowsTaskRun(cmd).replace(/"/g, '\\"')}" /sc daily /st 06:15`);
+        }
+    }
+    else {
+        // Unix: check crontab for existing entry
+        const marker = `# hippo:${taskName}`;
+        try {
+            const existing = execSync('crontab -l 2>/dev/null', { encoding: 'utf-8', windowsHide: true });
+            if (existing.includes(marker)) {
+                return; // already scheduled
+            }
+            const cronLine = `15 6 * * * ${cmd} ${marker}`;
+            const newCrontab = existing.trimEnd() + '\n' + cronLine + '\n';
+            execSync('crontab -', { input: newCrontab, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+            console.log(`   Scheduled machine-level daily runner (6:15am) via crontab`);
+        }
+        catch {
+            const cronLine = `15 6 * * * ${cmd}`;
+            console.log(`   To schedule the machine-level daily runner, add to crontab (crontab -e):`);
+            console.log(`   ${cronLine}`);
+        }
+    }
+}
+export function parseAsOfFlag(flags) {
+    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);
+    }
+    return asOf;
+}
+/** --physics forces physics, --classic forces BM25+cosine, else physics unless the config turns it off. */
+export function engineFlags(flags, config) {
+    return {
+        usePhysics: Boolean(flags['physics']) || (!flags['classic'] && config.physics.enabled !== false),
+        physicsConfig: config.physics,
+        mmr: !flags['no-mmr'] && config.mmr.enabled,
+        mmrLambda: flags['mmr-lambda'] !== undefined ? parseFloat(String(flags['mmr-lambda'])) : config.mmr.lambda,
+        localBump: flags['equal-sources']
+            ? 1.0
+            : flags['local-bump'] !== undefined ? parseFloat(String(flags['local-bump'])) : config.search.localBump,
+    };
+}
+/**
+ * Detached worker that counts re-reads, runs sleep, then capture. Invoked via the internal
+ * `__session-end-worker` subcommand (not user-facing). Failures in one stage
+ * do not block the other.
+ */
+// Best-effort git state; a missing git, non-repo cwd, or the timeout all
+// yield null fields rather than throw (autolearn.ts execFileSync shape).
+export function collectHandoffEvidence(cwd, testStatus) {
+    let gitRef = null;
+    try {
+        gitRef = execFileSync('git', ['rev-parse', 'HEAD'], {
+            cwd, encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
+        }).trim() || null;
+    }
+    catch {
+        gitRef = null;
+    }
+    let dirtyTree = null;
+    try {
+        const status = execFileSync('git', ['status', '--porcelain'], {
+            cwd, encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
+        });
+        dirtyTree = status.trim().length > 0;
+    }
+    catch {
+        dirtyTree = null;
+    }
+    return { gitRef, dirtyTree, testStatus };
+}
+/** A folder without its own store never sleeps at session end, so its project's agent notes go to the global store here. */
+export function logSessionEndImport(logFile, transcriptPath) {
+    try {
+        const report = importAtSessionEnd(process.cwd(), transcriptPath, { machine: currentMachine() });
+        const line = summaryLine(report);
+        if (line !== null)
+            appendSessionEndCloseLog(logFile, line);
+        for (const warning of report.warnings)
+            appendSessionEndCloseLog(logFile, `agent memories: ${warning}`);
+    }
+    catch (err) {
+        appendSessionEndCloseLog(logFile, `agent memory import failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/**
+ * Best-effort log line for the snapshot-close step in
+ * `cmdSessionEndWorker`. `cmdSleep`/`cmdCapture` each tee console output to
+ * `logFile` only for their own duration (the tee is restored before this
+ * runs), so a plain `console.log` here would be silently discarded under
+ * the detached worker's `stdio: 'ignore'` — write straight to the file
+ * instead, matching capture.ts's `appendPreCompactLog` convention.
+ */
+export function appendSessionEndCloseLog(logFile, message, opts = {}) {
+    if (!logFile)
+        return;
+    try {
+        fs.mkdirSync(path.dirname(logFile), { recursive: true });
+        // sanitizeLogMessage: `message` interpolates the payload-controlled
+        // session_id — same log-forgery guard appendPreCompactLog applies.
+        const write = opts.startFresh ? fs.writeFileSync : fs.appendFileSync;
+        write(logFile, `[hippo] ${new Date().toISOString()} ${sanitizeLogMessage(message)}\n`, 'utf8');
+    }
+    catch {
+        // Best-effort only — never let a log-write failure surface as an error.
+    }
+}
+export function printActiveTaskSnapshot(snapshot) {
+    console.log(snapshotText(snapshot));
+}
+export function printSessionEvents(events) {
+    console.log(events.length === 0 ? 'No session events found.' : sessionTrailText(events));
+}
+export function printHandoff(handoff) {
+    console.log(handoffText(handoff));
+}
+// parseArgs turns a value-less flag into `true`; refuse rather than silently
+// stringifying it (String(true) === 'true'), mirroring cmdHandoff's guard.
+export function cardStringFlag(flags, key) {
+    const v = flags[key];
+    if (v === undefined)
+        return undefined;
+    if (v === true || v === false || Array.isArray(v)) {
+        console.error(`--${key} requires a value`);
+        process.exit(1);
+    }
+    return v.trim();
+}
+// Claude Code exports its own session var, not ours; without the fallback agent-run recalls trace with no session.
+export function hostSessionId() {
+    return process.env.HIPPO_SESSION_ID?.trim() || process.env.CLAUDE_CODE_SESSION_ID?.trim() || undefined;
+}
+/**
+ * Compaction drops the pinned blocks the per-prompt hook injected
+ * earlier, so record a `reset` for the payload's session and the next prompt
+ * injects again even if nothing changed. `requiredSource` limits it to hook
+ * payloads with that `source` (SessionStart fires for other reasons too).
+ * Best-effort and silent: a malformed payload records nothing.
+ */
+export function resetHookInjection(hippoRoot, stdinText, requiredSource) {
+    const sessionId = hookPayloadSessionId(stdinText, requiredSource);
+    // A sub-agent's compaction leaves its parent's context, and the blocks in it, as they were.
+    if (sessionId === null || isSubagentPayload(stdinText))
+        return;
+    withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
+        tenantId: resolveTenantId({}), sessionId, surface: 'hook', event: 'reset', items: 0, tokens: 0,
+    }));
+}
+/**
+ * Run `fn` with console.log captured; returns the captured lines joined by
+ * newlines (what the same calls would have printed, minus the final newline).
+ */
+export function captureConsole(fn) {
+    const lines = [];
+    const realLog = console.log;
+    console.log = (...parts) => { lines.push(parts.map(String).join(' ')); };
+    try {
+        fn();
+    }
+    finally {
+        console.log = realLog;
+    }
+    return lines.join('\n');
+}
+/**
+ * The store a Claude Code hook writes to: the project store when there is
+ * one, else an existing global store, else the project path (which the hook
+ * then skips, since hooks fire in every directory and must not create one).
+ * Pre-compact and compact-resume must agree, or a snapshot saved to one store
+ * is looked for in the other.
+ */
+export function hookStoreRoot(hippoRoot) {
+    if (isInitialized(hippoRoot))
+        return hippoRoot;
+    const globalRoot = getGlobalRoot();
+    return isInitialized(globalRoot) ? globalRoot : hippoRoot;
+}
+/**
+ * Run `fn` against the token ledger's store: the local store when it is
+ * initialized, else the global one (the per-prompt hook runs in directories
+ * without a local store). Best-effort: returns undefined and never throws,
+ * because a ledger failure must not break context or recall.
+ */
+export function withLedgerDb(hippoRoot, fn) {
+    let root = null;
+    try {
+        if (isInitialized(hippoRoot))
+            root = hippoRoot;
+        else if (isInitialized(getGlobalRoot()))
+            root = getGlobalRoot();
+    }
+    catch {
+        return undefined;
+    }
+    if (root === null)
+        return undefined;
+    let db;
+    try {
+        db = openHippoDb(root);
+        return fn(db);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (db)
+            closeHippoDb(db);
+    }
+}
+export function learnFromRepo(hippoRoot, repoPath, days, label) {
+    const prefix = label ? `[${label}] ` : '';
+    if (!isGitRepo(repoPath)) {
+        console.log(`${prefix}No git history found (or not a git repository).`);
+        return { added: 0, skipped: 0, lowInfo: 0 };
+    }
+    const gitLog = fetchGitLog(repoPath, days);
+    if (!gitLog.trim()) {
+        console.log(`${prefix}No fix/revert/bug commits found in the specified period.`);
+        return { added: 0, skipped: 0, lowInfo: 0 };
+    }
+    // Same patterns as MCP hippo_learn: config.gitLearnPatterns (whose default
+    // equals extractLessons' built-in list) so a custom list applies everywhere.
+    const config = loadConfig(hippoRoot);
+    const parsedLessons = extractLessons(gitLog, config.gitLearnPatterns);
+    if (parsedLessons.length === 0) {
+        console.log(`${prefix}No fix/revert/bug commits found in the specified period.`);
+        return { added: 0, skipped: 0, lowInfo: 0 };
+    }
+    // The admission gate lives at the write path, not in extractLessons
+    // (a published API surface that only parses). Bare subjects like "fixed
+    // signals" are dropped here, before they ever become a memory.
+    // The gate filters the loop INPUT, so a dropped lesson neither stores nor
+    // invalidates. That is deliberate, and it was argued both ways.
+    //
+    // One review called the lost invalidation serious: a migration subject
+    // too thin to store ("replace webpack with vite") would stop weakening
+    // stale webpack memories. True. So the loop was widened to walk every
+    // parsed lesson with the gate on the write alone.
+    //
+    // A second review found the cure was worse. STORAGE is what makes invalidation
+    // idempotent here: a stored lesson is recognised by its same-text key on
+    // the next scan and short-circuits before invalidating again. A lesson that
+    // invalidates but is never stored has no such record, so every rescan
+    // re-invalidates, and invalidateMatching halves half_life_days each time.
+    // Measured: 7 -> 3 -> 1 over two runs. That is compounding data damage.
+    //
+    // Measured frequency decided it. Across 413 real auto-learn rows in 4
+    // stores, 24 are gated and ZERO of those carry an invalidation target; the
+    // 45 lessons that do carry targets all pass the gate and are unaffected
+    // either way. Both failure modes are empty on real data, so the tie breaks
+    // on which one is benign if it ever fires: not invalidating is a missed
+    // improvement, re-invalidating forever is damage.
+    //
+    // Documented limitation, pinned by test: a migration subject too thin to
+    // store also does not invalidate. Making invalidateMatching idempotent
+    // would allow both, and is backlogged - it is a latent issue for the manual
+    // `hippo invalidate` path too, not just this one.
+    const { kept: lessons, dropped } = partitionLessons(parsedLessons);
+    const lowInfo = dropped.length;
+    let added = 0;
+    let skipped = 0;
+    // Containment: per-lesson refusal must not abort the rest
+    // of the git-log scan. No signature change (added/skipped return shape
+    // used by cmdLearn + cmdSleepCore callers) — counted locally, folded into
+    // the existing summary line.
+    let rejected = 0;
+    const gitLearnTags = ['error', 'git-learned'];
+    const existingForSchema = loadAllEntries(hippoRoot, resolveTenantId({}));
+    const keys = storedTextKeys(existingForSchema);
+    for (const lesson of lessons) {
+        if (keys.has(duplicateKey(lesson))) {
+            skipped++;
+            continue;
+        }
+        const target = extractInvalidationTarget(lesson);
+        if (target) {
+            const invResult = invalidateMatching(hippoRoot, target, resolveTenantId({}));
+            if (invResult.invalidated > 0) {
+                console.log(`${prefix}   Invalidated ${invResult.invalidated} memories referencing "${target.from}"`);
+            }
+        }
+        const schemaFitVal = computeSchemaFit(lesson, gitLearnTags, existingForSchema);
+        const entry = createMemory(lesson, {
+            layer: Layer.Episodic,
+            tags: [...gitLearnTags],
+            source: 'git-learn',
+            confidence: 'observed',
+            schema_fit: schemaFitVal,
+            tenantId: resolveTenantId({}),
+            baseHalfLifeDays: config.defaultHalfLifeDays,
+        });
+        // Auto-tag with path context from the repo being learned
+        const learnPathTags = extractPathTags(repoPath);
+        for (const pt of learnPathTags) {
+            if (!entry.tags.includes(pt))
+                entry.tags.push(pt);
+        }
+        try {
+            writeEntry(hippoRoot, entry);
+        }
+        catch (err) {
+            if (err instanceof RejectedValueError) {
+                rejected++;
+                continue;
+            }
+            throw err;
+        }
+        updateStats(hippoRoot, { remembered: 1 });
+        keys.add(duplicateKey(lesson));
+        void embedMemory(hippoRoot, entry);
+        added++;
+    }
+    console.log(`${prefix}${added} new lessons added, ${skipped} duplicates skipped` +
+        (rejected > 0 ? `, ${rejected} rejected value(s) skipped` : '') +
+        (lowInfo > 0 ? `, ${lowInfo} low-information subject(s) dropped` : '') +
+        '.');
+    return { added, skipped, lowInfo };
+}
+export const HOOK_MARKERS = {
+    start: '<!-- hippo:start -->',
+    end: '<!-- hippo:end -->',
+};
+export const HOOKS = {
+    'claude-code': {
+        file: 'CLAUDE.md',
+        description: 'Claude Code',
+        content: `
+## Project Memory (Hippo)
+
+Pinned rules and recent writes auto-inject at every prompt via the installed
+UserPromptSubmit hook; never re-run that part manually. At the START of a
+task (not per prompt), additionally load task-specific context: git-aware
+recall over the full store that per-prompt injection does not cover. Also
+run it if the hook is not installed:
+\`\`\`bash
+hippo context --auto --budget 1500
+\`\`\`
+
+When you find out why something failed, record it right then, while you
+work, never as a closing step:
+\`\`\`bash
+hippo remember "<what went wrong and why>" --error
+\`\`\`
+
+The installed hooks store failed tool calls and capture the session when it
+ends, so there is nothing to run before you finish.
+`.trim(),
+    },
+    'codex': {
+        file: 'AGENTS.md',
+        description: 'OpenAI Codex',
+        content: `
+## Project Memory (Hippo)
+
+At the start of every task, run:
+\`\`\`bash
+hippo context --auto --budget 1500
+\`\`\`
+Read the output before writing any code.
+
+On errors or unexpected behaviour, record it right then, while you work,
+never as a closing step:
+\`\`\`bash
+hippo remember "<description of what went wrong>" --error
+\`\`\`
+
+When you learn something that should outlive this session (a decision and
+its reason, a user preference, a lesson), record it right then, while you
+work, never as a closing step. Leave out secrets and personal details:
+\`\`\`bash
+hippo remember "<what you learned and why>"
+\`\`\`
+
+When Hippo's Codex wrapper is installed, session-end capture runs automatically.
+If the wrapper is not installed, capture a brief summary manually:
+\`\`\`bash
+hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
+\`\`\`
+`.trim(),
+    },
+    'cursor': {
+        file: 'AGENTS.md',
+        description: 'Cursor',
+        content: `
+## Project Memory (Hippo)
+
+At the start of every task, run:
+\`\`\`bash
+hippo context --auto --budget 1500
+\`\`\`
+Read the output before writing any code.
+
+On errors or unexpected behaviour, record it right then, while you work,
+never as a closing step:
+\`\`\`bash
+hippo remember "<description of what went wrong>" --error
+\`\`\`
+
+When you learn something that should outlive this session (a decision and
+its reason, a user preference, a lesson), record it right then, while you
+work, never as a closing step. Leave out secrets and personal details:
+\`\`\`bash
+hippo remember "<what you learned and why>"
+\`\`\`
+
+When ending a session, capture a brief summary:
+\`\`\`bash
+hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
+\`\`\`
+`.trim(),
+    },
+    'openclaw': {
+        file: 'AGENTS.md',
+        description: 'OpenClaw',
+        content: `
+## Project Memory (Hippo)
+
+At the start of every session, run:
+\`\`\`bash
+hippo context --auto --budget 1500
+\`\`\`
+Read the output before writing any code.
+
+On errors or unexpected behaviour, record it right then, while you work,
+never as a closing step:
+\`\`\`bash
+hippo remember "<description of what went wrong>" --error
+\`\`\`
+
+When you learn something that should outlive this session (a decision and
+its reason, a user preference, a lesson), record it right then, while you
+work, never as a closing step. Leave out secrets and personal details:
+\`\`\`bash
+hippo remember "<what you learned and why>"
+\`\`\`
+
+When ending a session, capture a brief summary:
+\`\`\`bash
+hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
+\`\`\`
+`.trim(),
+    },
+    'opencode': {
+        file: 'AGENTS.md',
+        description: 'OpenCode',
+        content: `
+## Project Memory (Hippo)
+
+At the start of every task, run:
+\`\`\`bash
+hippo context --auto --budget 1500
+\`\`\`
+Read the output before writing any code.
+
+On errors or unexpected behaviour, record it right then, while you work,
+never as a closing step:
+\`\`\`bash
+hippo remember "<description of what went wrong>" --error
+\`\`\`
+
+When you learn something that should outlive this session (a decision and
+its reason, a user preference, a lesson), record it right then, while you
+work, never as a closing step. Leave out secrets and personal details:
+\`\`\`bash
+hippo remember "<what you learned and why>"
+\`\`\`
+
+When stuck or repeating yourself, check if this happened before:
+\`\`\`bash
+hippo recall "<what's going wrong>" --budget 2000
+\`\`\`
+
+When ending a session, capture a brief summary:
+\`\`\`bash
+hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
+\`\`\`
+`.trim(),
+    },
+    'pi': {
+        file: 'AGENTS.md',
+        description: 'Pi',
+        content: `
+## Project Memory (Hippo)
+
+At the start of every session, run:
+\`\`\`bash
+hippo context --auto --budget 1500
+\`\`\`
+Read the output before writing any code.
+
+On errors or unexpected behaviour, record it right then, while you work,
+never as a closing step:
+\`\`\`bash
+hippo remember "<description of what went wrong>" --error
+\`\`\`
+
+When you learn something that should outlive this session (a decision and
+its reason, a user preference, a lesson), record it right then, while you
+work, never as a closing step. Leave out secrets and personal details:
+\`\`\`bash
+hippo remember "<what you learned and why>"
+\`\`\`
+
+When ending a session, capture a brief summary:
+\`\`\`bash
+hippo capture --stdin <<< '<decisions, errors, lessons: 2-5 bullets>'
+\`\`\`
+
+For full integration, copy the hippo-memory Pi extension to \`~/.pi/agent/extensions/hippo-memory/\`.
+`.trim(),
+    },
+};
+// sha256 of each trimmed block an earlier hippo wrote, so init refreshes only blocks nobody edited. Add the old hash when a block changes.
+const SHIPPED_HOOK_HASHES = new Map([
+    ['c04e48f2896a4fee9ae98f8f832e2d26a3910269df3beb5bcd6baee3cd9db68e', 'claude-code'],
+    ['e6b12bd8983c032e5ca8e95a97aeff4178a5a05026d10acad5b2e1b25d5656dd', 'claude-code'],
+    ['4c64e11d3e5be68fa547c9248d7553feb645a02f7cf13ba02f7275e1854baf44', 'claude-code'],
+    ['293bd319bbc86225a0ee027490a3322a0336257f5832f7fade65e4ffb2530654', 'claude-code'],
+    ['15abcece9712279fb4721f7a8f0ba117457400278977beb5cf5b5d7ba49f7b1a', 'codex'],
+    ['0c81a6b2c21473313001f624b80ea870e661aecbfda9bfe8503febc0d5f34533', 'codex'],
+    ['88e45358aba4f17912f113221c991dc758275991335d1daa4aa1974a69c46769', 'codex'],
+    ['e61632fe177450a06541c148a9a4f9182530d8df667806927a99792825903298', 'codex'],
+    ['a1415ecda9b2f8f317c233738e4a5ac16e6b2cc385a017c0c8ecfbfacbcab6a3', 'cursor'],
+    ['a38c428bbdfc14ec50f6f7b9183785170a4eae1ce9cde60257cca6efc7206b3a', 'cursor'],
+    ['0ec9f556abfd55e94f9e6fb47ece0fc5acb841977d144b35a2371e03645d8636', 'cursor'],
+    ['40524c3bd5a2eb04036567cc761451961d950995768bccd93a9900b0f75eafea', 'openclaw'],
+    ['7b3518e8c0feaa7b8b454cde7743f7598ad14cd9979e1680d0954484e2464aae', 'openclaw'],
+    ['1137dcf04568caf011e41db77bc55324faee88bc29c3a5fcc98ab687cd952a16', 'openclaw'],
+    ['4601c67c31f41cd5b1324cfccdb1afc66872b7fb0bc1e7c5789ecabb1f6bd942', 'opencode'],
+    ['90d9e21d8d1ecbe99a0fc7b7f2d9f8af7b5315a6b4b0203df4f7a9bdc0699b98', 'opencode'],
+    ['ca4e00284f1397ed2f2fcc53210c27f63b90edf6b37fd66dad5ee58b94ea3eee', 'opencode'],
+    ['8b8f5986d7f7ed15f06e68720d8913c3cab23d94366b411935ca2bbaa334553b', 'pi'],
+    ['37767b355e18beac726b05b9e2b898dab8c6135fd7b98f3aa52edc734d5dd283', 'pi'],
+    ['6e85a5cccb3cfeaa9a080713754936db730f96376f94cc9a9888a746149c7268', 'pi'],
+]);
+export function resolveAuthRoot(hippoRoot, flags) {
+    if (flags['global']) {
+        initGlobal();
+        return getGlobalRoot();
+    }
+    requireInit(hippoRoot);
+    return hippoRoot;
+}
+//# sourceMappingURL=shared.js.map