hippo-memory 1.46.0 → 1.48.0

package/README.md

@@ -256,7 +256,7 @@ hippo recall "data pipeline" --why --limit 5
 
 Input enters the buffer. Important things get encoded into episodic memory. During "sleep," repeated episodes compress into semantic patterns. Weak memories decay and disappear.
 
-The store is SQLite (`.hippo/hippo.db`). The markdown files and `index.json` are mirrors written after each change. From 1.46.0, `index.json` is no longer refreshed on every write; it comes only from an explicit export, so read the store through the CLI, the MCP server or the HTTP API.
+The store is SQLite (`.hippo/hippo.db`). The markdown files are mirrors written after each change. `index.json` is no longer refreshed by writes, deletes or recalls: it is written only when you call `rebuildIndex()` from the package, so a copy an older version left on disk goes stale. Read the store through the CLI, the MCP server or the HTTP API.
 
 ```mermaid
 flowchart TD
@@ -629,7 +629,9 @@ hippo watch "npm run build"
 | `hippo dormant restore <id>` | Bring a dormant memory back to active memory |
 | `hippo dormant forget <id>` | Delete a dormant memory permanently |
 | `hippo doctor [--json]` | Check the install: Node, store, schema, sleep, agent hooks; each problem names its fix |
+| `hippo support-bundle [--out <file>] [--include-logs]` | Write a redacted JSON file for a support ticket: versions, doctor checks, config, store counts and log names, never memory text; `--include-logs` adds each log's last 200 lines, which can quote it |
 | `hippo tokens [--days n]` | Estimated tokens of memory text handed to agents, per surface, and what skipping unchanged hook blocks saved |
+| `hippo failures [--days n]` | Failed tool calls the capture-error hook saw, by outcome, and how many errors first happened in another session |
 | `hippo embed` | Embed all memories for semantic search |
 | `hippo embed --status` | Show embedding coverage |
 | `hippo watch "<command>"` | Run command, auto-learn from failures |
@@ -725,7 +727,7 @@ For Claude Code, it also adds:
 - a `PreCompact` hook that runs `hippo pre-compact` before the transcript gets summarized. It saves a working-state snapshot (task/summary/next step) and extracts durable memories from the tail, so mid-session compaction can't drop them.
 - a second `SessionStart` hook (matcher `compact`) that runs `hippo compact-resume`, printing that snapshot plus the recent session trail back into context right after compaction.
 - a `PostCompact` hook that runs `hippo post-compact`, which tells you what was saved ("Hippo saved your task snapshot and 2 new memories before compacting"). It prints nothing when nothing was saved.
-- a `PostToolUseFailure` hook that runs `hippo capture-error`, which stores a failed tool call as an error memory. It skips interrupts, declined permissions and searches that found nothing, and stores a repeated failure once.
+- a `PostToolUseFailure` hook that runs `hippo capture-error`, which stores a failed tool call as an error memory. It skips interrupts, declined permissions and searches that found nothing, and stores a repeated failure once. It also logs every failure, stored or not, for `hippo failures`: the session, the tool and hashes of the error, never its text. A hash is not anonymous, since anyone who guesses an error's text can check it against the hash. The log keeps 90 days.
 
 To remove: `hippo hook uninstall claude-code`
 

package/dist/api.d.ts

@@ -11,6 +11,7 @@ import { deleteEntry, loadAllEntries, type TaskSnapshot, type SessionEvent } fro
 import { type RejectedValueRow } from './rejection.js';
 import { type DormantMemory, type ListDormantOpts } from './dormant.js';
 import { type TokenSummary, type TokenSurface } from './token-ledger.js';
+import { type FailureSummary } from './failure-log.js';
 import { type SessionHandoff } from './handoff.js';
 import { type MemoryKind, type MemoryEntry } from './memory.js';
 import { auditMemories, type AuditEvent, type AuditOp } from './audit.js';
@@ -82,6 +83,7 @@ import { isPrivateScope, passesScopeFilterForRecall } from './recall-scope.js';
 export { isPrivateScope, passesScopeFilterForRecall };
 export { passesCliRecallScopeFilter, ScopeForbiddenError } from './recall-scope.js';
 export type { TokenSummary, TokenSurface, TokenSurfaceSummary } from './token-ledger.js';
+export type { FailureSummary } from './failure-log.js';
 export { classifyOriginProject } from './project-identity.js';
 /**
  * v39 S4: the secret half of the ambient policy on its own, for surfaces
@@ -1019,6 +1021,10 @@ export declare function recordTokens(ctx: Context, surface: TokenSurface, use: {
 export declare function tokenSummary(ctx: Context, opts?: {
     days?: number;
 }): TokenSummary;
+/** Failed tool calls by outcome, and repeats across sessions, over the last `days` days (default 30); ROADMAP CD13. */
+export declare function failureSummary(ctx: Context, opts?: {
+    days?: number;
+}): FailureSummary;
 /**
  * A tenant's dormant memories (src/dormant.ts): what sleep moved out of
  * active memory instead of deleting, when `dormant.enabled` is on. Newest

package/dist/api.js

@@ -13,6 +13,7 @@ import { RejectedValueError } from './rejection.js';
 import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
 import { listDormantRows, readDormantSnapshot, deleteDormantRow, hasDormantRow, } from './dormant.js';
 import { recordTokenUse, summarizeTokenUse } from './token-ledger.js';
+import { summarizeFailures } from './failure-log.js';
 import { formatHandoffEvidenceLine } from './handoff.js';
 import { createMemory, applyOutcome, calculateStrength, Layer, } from './memory.js';
 import { appendAuditEvent, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
@@ -1215,11 +1216,11 @@ export function supersede(ctx, oldId, newContent) {
         }
         // Mirrors after COMMIT, while the db handle is still open. Same
         // invariant as the original writeEntry: a mirror failure leaves disk
-        // MISSING the markdown for the new memory (self-heals on next backfill
-        // via writeIndexMirror reading the DB) but DOES NOT desync the DB or
+        // MISSING the markdown for the new memory (rebuildIndex rewrites every
+        // markdown mirror from the DB) but DOES NOT desync the DB or
         // roll back the supersede. Logged + swallowed, non-fatal.
         try {
-            writeEntryMirrors(ctx.hippoRoot, db, newEntry);
+            writeEntryMirrors(ctx.hippoRoot, newEntry);
         }
         catch (mirrorErr) {
             console.error('supersede: mirror write failed (non-fatal, will self-heal):', mirrorErr);
@@ -1896,16 +1897,28 @@ export function recordTokens(ctx, surface, use) {
  * saved, and mean tokens per session.
  */
 export function tokenSummary(ctx, opts = {}) {
-    const days = opts.days !== undefined && Number.isFinite(opts.days) && opts.days > 0 ? opts.days : 30;
-    const since = new Date(Date.now() - days * 86_400_000).toISOString();
     const db = openHippoDb(ctx.hippoRoot);
     try {
-        return summarizeTokenUse(db, ctx.tenantId, since);
+        return summarizeTokenUse(db, ctx.tenantId, reportWindowStart(opts.days));
     }
     finally {
         closeHippoDb(db);
     }
 }
+/** Failed tool calls by outcome, and repeats across sessions, over the last `days` days (default 30); ROADMAP CD13. */
+export function failureSummary(ctx, opts = {}) {
+    const db = openHippoDb(ctx.hippoRoot);
+    try {
+        return summarizeFailures(db, ctx.tenantId, reportWindowStart(opts.days));
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+function reportWindowStart(days) {
+    const span = days !== undefined && Number.isFinite(days) && days > 0 ? days : 30;
+    return new Date(Date.now() - span * 86_400_000).toISOString();
+}
 /**
  * A tenant's dormant memories (src/dormant.ts): what sleep moved out of
  * active memory instead of deleting, when `dormant.enabled` is on. Newest
@@ -1985,7 +1998,7 @@ export function restoreDormant(ctx, id) {
             }
             throw err;
         }
-        writeEntryMirrors(ctx.hippoRoot, db, restored);
+        writeEntryMirrors(ctx.hippoRoot, restored);
         return restored;
     }
     finally {

package/dist/capture-error.d.ts

@@ -1,20 +1,26 @@
 import type { JsonValue } from './working-memory.js';
 /** Why a failure was not stored, or `stored`. */
 export type CaptureErrorOutcome = 'stored' | 'duplicate' | 'skipped-interrupt' | 'skipped-routine' | 'skipped-invalid';
-/** Normalised form used to spot repeats of the same failure. */
-export declare function failureSignature(text: string): string;
-/**
- * The memory text for a failure payload, or the reason it is not stored.
- * Pure: no store access.
- */
-export declare function lessonFromFailure(payload: JsonValue): {
+/** Which routine check skipped a failure; the log keeps it so declines can be told apart from empty searches. */
+export type RoutineRule = 'declined' | 'os-permission' | 'no-match' | 'search-tool' | 'quiet-exit';
+/** What {@link lessonFromFailure} read from a payload; `detail` is the finer failure-log key (untruncated, command head). */
+export type FailureReading = {
+    text: string;
+    detail: string;
+} | {
+    skip: 'skipped-routine';
+    rule: RoutineRule;
     text: string;
+    detail: string;
 } | {
-    skip: Exclude<CaptureErrorOutcome, 'stored' | 'duplicate'>;
+    skip: 'skipped-interrupt' | 'skipped-invalid';
+    text: null;
+    detail: null;
 };
-/**
- * Store a failure payload as an error memory unless it is routine or a
- * repeat of an auto-captured error already in the store.
- */
+/** Normalised form used to spot repeats. The failure log keeps only its hash, so changing it breaks repeat counts. */
+export declare function failureSignature(text: string): string;
+/** The memory text for a failure payload, or why it is not stored; a routine skip keeps its text for the log. Pure. */
+export declare function lessonFromFailure(payload: JsonValue): FailureReading;
+/** Store a failure as an error memory unless it is routine or a repeat, and log it either way, even when storing throws. */
 export declare function captureToolFailure(hippoRoot: string, tenantId: string, payload: JsonValue): CaptureErrorOutcome;
 //# sourceMappingURL=capture-error.d.ts.map

package/dist/capture-error.js

@@ -1,25 +1,20 @@
-/**
- * `hippo capture-error`: turn a failed tool call into an error memory. Run by
- * the Claude Code `PostToolUseFailure` hook (both `hippo hook install
- * claude-code` and the plugin), which writes the failure as JSON on stdin.
- *
- * Most failed tool calls are not lessons. An interrupt, a permission the
- * user declined, a search that found nothing or a `grep` that exits 1 is
- * routine, and error memories decay slower than other memories, so storing
- * them would crowd out real lessons. Those are dropped here, repeats of the
- * same failure are stored once, and what is stored is marked `observed`
- * (auto-captured, not verified): outcome feedback, not capture, is what
- * should strengthen it.
- */
+// `hippo capture-error`, run by the Claude Code PostToolUseFailure hook: routine failures and repeats are not
+// stored, because error memories decay slowly and would crowd out real lessons; what is stored stays `observed`
+// until outcome feedback confirms it. Every failure, stored or not, goes to the failure log (ROADMAP CD13).
 import { createMemory } from './memory.js';
 import { writeEntry, loadAllEntries } from './store.js';
 import { loadConfig } from './config.js';
+import { closeHippoDb, openHippoDb } from './db.js';
+import { recordFailure } from './failure-log.js';
+import { blockHash } from './token-ledger.js';
 const MAX_LEN = 200;
-/** Failures that are routine, not lessons. */
-const ROUTINE_PATTERNS = [
-    /user (?:doesn't|does not) want|denied by (?:the )?user|user (?:rejected|declined|denied)|permission (?:denied|to use)|was blocked by (?:a )?hook/i,
-    /\bno (?:matches|files|results) found\b/i,
-];
+/** The user, a permission prompt or a hook said no: routine, not a lesson. */
+const DECLINED = /user (?:doesn't|does not) want|denied by (?:the )?user|user (?:rejected|declined|denied)|permission to use|was blocked by (?:a )?hook/i;
+/** The OS or a remote host refused access (EACCES, SSH publickey): routine too, but nobody declined anything. */
+const OS_PERMISSION = /permission denied/i;
+/** Leading `cd` or `pushd` steps say where a command ran, not what it ran. */
+const LEADING_CD = /^\s*(?:(?:cd|pushd)\b[^;&|]*(?:&&|\|\||;)\s*)+/;
+const NO_MATCH = /\bno (?:matches|files|results) found\b/i;
 /** Shell commands whose exit code 1 means "nothing found" or "differs", not an error. */
 const QUIET_EXIT_1 = /^\s*(?:grep|rg|egrep|fgrep|find|test|\[|diff|cmp|git diff|git grep)\b/;
 function isString(v) {
@@ -28,48 +23,81 @@ function isString(v) {
 function isObject(v) {
     return v !== undefined && v !== null && !Array.isArray(v) && v.constructor === Object;
 }
-/** Normalised form used to spot repeats of the same failure. */
+function payloadString(payload, key) {
+    if (!isObject(payload))
+        return null;
+    const value = payload[key];
+    return isString(value) && value.trim() !== '' ? value : null;
+}
+/** Normalised form used to spot repeats. The failure log keeps only its hash, so changing it breaks repeat counts. */
 export function failureSignature(text) {
     return text.toLowerCase().replace(/[0-9a-f]{7,}/g, '#').replace(/\d+/g, '#').replace(/\s+/g, ' ').trim();
 }
-/**
- * The memory text for a failure payload, or the reason it is not stored.
- * Pure: no store access.
- */
+/** The memory text for a failure payload, or why it is not stored; a routine skip keeps its text for the log. Pure. */
 export function lessonFromFailure(payload) {
     if (!isObject(payload))
-        return { skip: 'skipped-invalid' };
+        return { skip: 'skipped-invalid', text: null, detail: null };
     // SAFETY: isObject narrowed payload to a plain JSON object; the fields read are all optional.
     const p = payload;
     if (p.is_interrupt === true)
-        return { skip: 'skipped-interrupt' };
+        return { skip: 'skipped-interrupt', text: null, detail: null };
     if (!isString(p.error) || p.error.trim().length < 12)
-        return { skip: 'skipped-invalid' };
+        return { skip: 'skipped-invalid', text: null, detail: null };
     const tool = isString(p.tool_name) ? p.tool_name : 'tool';
     const error = p.error.replace(/\s+/g, ' ').trim();
-    if (ROUTINE_PATTERNS.some((re) => re.test(error)))
-        return { skip: 'skipped-routine' };
+    const text = `${tool}: ${error}`.slice(0, MAX_LEN);
+    const command = isObject(p.tool_input) && isString(p.tool_input['command']) ? p.tool_input['command'].replace(LEADING_CD, '') : '';
+    const head = command.trim().split(/\s+/).slice(0, 2).join(' ');
+    const detail = `${tool}${head ? ` ${head}` : ''}: ${error}`;
+    const routine = (rule) => ({ skip: 'skipped-routine', rule, text, detail });
+    if (DECLINED.test(error))
+        return routine('declined');
+    if (OS_PERMISSION.test(error))
+        return routine('os-permission');
+    if (NO_MATCH.test(error))
+        return routine('no-match');
     if (tool === 'Grep' || tool === 'Glob')
-        return { skip: 'skipped-routine' };
-    if (tool === 'Bash' && isObject(p.tool_input) && isString(p.tool_input['command'])
-        && QUIET_EXIT_1.test(p.tool_input['command']) && /exit code 1\b/i.test(error)) {
-        return { skip: 'skipped-routine' };
-    }
-    return { text: `${tool}: ${error}`.slice(0, MAX_LEN) };
+        return routine('search-tool');
+    if (tool === 'Bash' && QUIET_EXIT_1.test(command) && /exit code 1\b/i.test(error))
+        return routine('quiet-exit');
+    return { text, detail };
 }
-/**
- * Store a failure payload as an error memory unless it is routine or a
- * repeat of an auto-captured error already in the store.
- */
+/** Store a failure as an error memory unless it is routine or a repeat, and log it either way, even when storing throws. */
 export function captureToolFailure(hippoRoot, tenantId, payload) {
     const lesson = lessonFromFailure(payload);
-    if ('skip' in lesson)
-        return lesson.skip;
-    const sig = failureSignature(lesson.text);
+    let outcome = 'store-failed';
+    try {
+        outcome = 'skip' in lesson ? lesson.skip : storeLesson(hippoRoot, tenantId, lesson.text);
+        return outcome;
+    }
+    finally {
+        logFailure(hippoRoot, tenantId, payload, lesson, outcome);
+    }
+}
+function logFailure(hippoRoot, tenantId, payload, lesson, outcome) {
+    const hash = (s) => (s === null ? null : blockHash(failureSignature(s)));
+    const db = openHippoDb(hippoRoot);
+    try {
+        recordFailure(db, {
+            tenantId,
+            sessionId: payloadString(payload, 'session_id'),
+            tool: payloadString(payload, 'tool_name'),
+            outcome,
+            rule: 'rule' in lesson ? lesson.rule : null,
+            sigHash: hash(lesson.text),
+            detailHash: hash(lesson.detail),
+        });
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
+function storeLesson(hippoRoot, tenantId, text) {
+    const sig = failureSignature(text);
     const repeat = loadAllEntries(hippoRoot, tenantId).some((e) => e.tags.includes('auto-captured') && failureSignature(e.content) === sig);
     if (repeat)
         return 'duplicate';
-    const entry = createMemory(lesson.text, {
+    const entry = createMemory(text, {
         tags: ['error', 'auto-captured'],
         source: 'tool-failure',
         confidence: 'observed',

package/dist/cli.js

@@ -60,8 +60,11 @@ import { computeSystemEnergy, vecNorm } from './physics.js';
 import { loadConfig } from './config.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { runDoctor, formatDoctor } from './doctor.js';
+import { buildSupportBundle, TAIL_MAX_LINES } from './support-bundle.js';
+import { PACKAGE_VERSION } from './version.js';
 import { captureToolFailure } from './capture-error.js';
 import { blockHash, hookPayloadSessionId, lastSentState, recordTokenUse, shouldSkipUnchanged } from './token-ledger.js';
+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';
@@ -263,7 +266,7 @@ export const BOOLEAN_FLAGS = new Set([
     'all', 'all-tenants', 'archive', 'auto', 'bad', 'bootstrap', 'classic', 'continuity',
     'cross-project', 'dry-run', 'equal-sources', 'error', 'evc-adaptive', 'extract',
     'filter-conflicts', 'fix', 'force', 'forget', 'git', 'global', 'good', 'graph-stream',
-    'help', 'include-superseded', 'inferred', 'json', 'last-session', 'multihop', 'no-hooks',
+    'help', 'include-logs', 'include-superseded', 'inferred', 'json', 'last-session', 'multihop', 'no-hooks',
     'no-learn', 'no-mmr', 'no-propagate', 'no-schedule', 'no-share', 'no-summarize-older',
     'observed', 'open', 'physics', 'pin', 'pinned-only', 'reject-loser', 'rerank-utility',
     'reset-physics', 'save-baseline', 'show-cases', 'stats', 'stdin',
@@ -487,7 +490,7 @@ function cmdInit(hippoRoot, flags) {
         initStore(hippoRoot);
         console.log('Initialized Hippo at', hippoRoot);
         console.log('   Directories: buffer/ episodic/ semantic/ conflicts/');
-        console.log('   Files: hippo.db index.json stats.json');
+        console.log('   Files: hippo.db stats.json');
     }
     const globalRoot = getGlobalRoot();
     registerWorkspace(globalRoot, path.dirname(hippoRoot));
@@ -3929,6 +3932,48 @@ function cmdTokens(hippoRoot, flags) {
         console.log(`  Mean per session (rows with a session id): ${summary.meanTokensPerSession} tokens.`);
     }
 }
+/** `hippo failures [--days <n>] [--json] [--global]`: failed tool calls by outcome, and repeats across sessions (CD13). */
+function cmdFailures(hippoRoot, flags) {
+    // The store the capture-error hook writes to; a report never creates one.
+    const root = flags['global'] ? getGlobalRoot() : hookStoreRoot(hippoRoot);
+    requireInit(root);
+    const ctx = {
+        hippoRoot: root,
+        tenantId: resolveTenantId({}),
+        actor: api.adminActor('cli'),
+    };
+    const days = parseCountFlag(flags['days']);
+    const summary = api.failureSummary(ctx, { days: days > 0 ? days : undefined });
+    if (flags['json']) {
+        console.log(JSON.stringify(summary, null, 2));
+        return;
+    }
+    const windowDays = days > 0 ? days : 30;
+    const kept = windowDays > FAILURE_LOG_RETENTION_DAYS ? ` (rows are kept ${FAILURE_LOG_RETENTION_DAYS} days)` : '';
+    if (summary.total === 0) {
+        console.log(`No failed tool calls recorded in the last ${windowDays} days${kept}.`);
+        return;
+    }
+    const o = summary.outcomes;
+    const errors = o.stored + o.duplicate + o['store-failed'];
+    const unsaved = o['store-failed'] > 0 ? `, ${o['store-failed']} could not be saved` : '';
+    const rows = [
+        ['errors', errors, `(${o.stored} new, ${o.duplicate} already in memory${unsaved})`],
+        ['routine', o['skipped-routine'], ''],
+        ['interrupted', o['skipped-interrupt'], ''],
+        ['unreadable', o['skipped-invalid'], ''],
+    ];
+    console.log(`Failed tool calls seen by the capture-error hook, last ${windowDays} days${kept}\n`);
+    for (const [label, count, note] of rows) {
+        console.log(`  ${label.padEnd(13)}${String(count).padStart(6)}  ${note}`.trimEnd());
+    }
+    // Counts, not a rate: a share means little without a holdout arm to compare against (CD11).
+    if (summary.rated > 0) {
+        const noSession = errors - summary.rated;
+        const unrated = noSession > 0 ? ` ${noSession} more had no session id.` : '';
+        console.log(`\n  Repeats: ${summary.repeats} of ${summary.rated} errors first happened in another session.${unrated}`);
+    }
+}
 function cmdSnapshot(hippoRoot, args, flags) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? 'show';
@@ -8632,12 +8677,21 @@ Commands:
                            PostToolUseFailure hook payload on stdin; skips routine failures)
   doctor                   Check the install: Node, store, schema, sleep, agent hooks
     --json                 Machine-readable report (exit code 1 on any failure)
+  support-bundle           Write a redacted JSON file for a support ticket: versions, doctor,
+                           config without secrets, store counts, log names; never memory text
+    --out <file>           Where to write it (default: hippo-support-<time>.json here)
+    --include-logs         Add the last ${TAIL_MAX_LINES} lines of each hippo log, known secret shapes removed
   tokens                   Tokens of memory text hippo handed agents, per surface
                            (hook, context, recall, MCP, HTTP), and what skipping
                            unchanged hook blocks saved
     --days <n>             Window in days (default: 30)
     --json                 Output as JSON
     --global               Operate on the global store
+  failures                 Failed tool calls capture-error saw, by outcome, and how
+                           many errors first happened in another session
+    --days <n>             Window in days (default: 30)
+    --json                 Output as JSON
+    --global               Operate on the global store
   snapshot <sub>           Persist or inspect the current active task
     snapshot save          Save active task state
       --task <task>
@@ -9373,6 +9427,9 @@ async function main(command, args, flags, hippoRoot) {
         case 'tokens':
             cmdTokens(hippoRoot, flags);
             break;
+        case 'failures':
+            cmdFailures(hippoRoot, flags);
+            break;
         case 'doctor': {
             // SAFETY: package.json always carries a string "version" (checked at release by check-manifest-versions).
             const pkg = JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf-8'));
@@ -9382,6 +9439,38 @@ async function main(command, args, flags, hippoRoot) {
                 process.exit(1);
             break;
         }
+        case 'support-bundle': {
+            const outFlag = cardStringFlag(flags, 'out');
+            if (outFlag === '') {
+                console.error('--out requires a file path.');
+                process.exit(1);
+            }
+            const includeLogs = flags['include-logs'] === true;
+            const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+            const now = new Date();
+            const bundle = buildSupportBundle({ cwd: process.cwd(), home, version: PACKAGE_VERSION, includeLogs, now });
+            const stamp = now.toISOString().replace(/[:.]/g, '-');
+            const file = outFlag ?? path.join(process.cwd(), `hippo-support-${stamp}.json`);
+            const json = JSON.stringify(bundle, null, 2);
+            try {
+                fs.writeFileSync(file, `${json}\n`, { flag: 'wx', mode: 0o600 });
+            }
+            catch (err) {
+                if (err instanceof Error && 'code' in err && err.code === 'EEXIST') {
+                    console.error(`${file} already exists; pass --out to choose another file. Nothing was written.`);
+                }
+                else {
+                    console.error(err instanceof Error ? err.message : String(err));
+                }
+                process.exit(1);
+            }
+            const kb = Math.round(Buffer.byteLength(json) / 1024);
+            console.log(`Wrote ${file} (${kb} KB).`);
+            console.log(includeLogs
+                ? `It holds versions, doctor checks, config with secrets removed, store counts, and the last ${TAIL_MAX_LINES} lines of each hippo log with known secret shapes removed. Those log lines can quote memory text. Read it before you attach it to a ticket.`
+                : 'It holds versions, doctor checks, config with secrets removed, store counts and log file names. It never holds memory text. Read it before you attach it to a ticket.');
+            break;
+        }
         case 'snapshot':
             cmdSnapshot(hippoRoot, args, flags);
             break;

package/dist/db.d.ts

@@ -13,11 +13,18 @@ export interface DatabaseSyncLike {
 }
 export declare function getHippoDbPath(hippoRoot: string): string;
 export declare function getCurrentSchemaVersion(): number;
+/** Thrown by {@link assertBinaryCompatible}; doctor uses it to pick the upgrade fix over a generic permissions fix. */
+export declare class IncompatibleBinaryError extends Error {
+}
 export declare function openHippoDb(hippoRoot: string): DatabaseSyncLike;
+/** Open an existing store without changing it: no mkdir, WAL switch, migration or mirror cleanup. Throws when hippo.db is missing. */
+export declare function openHippoDbReadOnly(hippoRoot: string): DatabaseSyncLike;
 export declare function getSchemaVersion(db: DatabaseSyncLike): number;
 export declare function closeHippoDb(db: DatabaseSyncLike): void;
 export declare function getMeta(db: DatabaseSyncLike, key: string, fallback?: string): string;
 export declare function setMeta(db: DatabaseSyncLike, key: string, value: string): void;
+/** Row count of one table; null when the table is missing or unreadable, which callers show as unknown. */
+export declare function countTableRows(db: DatabaseSyncLike, table: string): number | null;
 export declare function isFtsAvailable(db: DatabaseSyncLike): boolean;
 export declare function pruneConsolidationRuns(db: DatabaseSyncLike, keep?: number): void;
 export {};

package/dist/db.js

@@ -11,7 +11,7 @@ const require = createRequire(import.meta.url);
 // runtime (Node's built-in synchronous SQLite module); there are no bundled
 // types for it here, so this require + cast is the module's documented boundary.
 const { DatabaseSync } = require('node:sqlite');
-const CURRENT_SCHEMA_VERSION = 45;
+const CURRENT_SCHEMA_VERSION = 46;
 const MIGRATIONS = [
     {
         version: 1,
@@ -2423,6 +2423,30 @@ const MIGRATIONS = [
       `);
         },
     },
+    {
+        version: 46,
+        up: (db) => {
+            // CD13 failure log (src/failure-log.ts): hashes only, since failure text can carry paths and secrets.
+            // Additive only: no min_compatible_binary bump.
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS failure_log (
+          id          INTEGER PRIMARY KEY AUTOINCREMENT,
+          ts          TEXT NOT NULL,
+          tenant_id   TEXT NOT NULL DEFAULT 'default',
+          session_id  TEXT,
+          tool        TEXT,
+          outcome     TEXT NOT NULL,
+          skip_rule   TEXT,
+          sig_hash    TEXT,
+          detail_hash TEXT
+        );
+        CREATE INDEX IF NOT EXISTS idx_failure_log_tenant
+          ON failure_log(tenant_id, id);
+        CREATE INDEX IF NOT EXISTS idx_failure_log_ts
+          ON failure_log(ts);
+      `);
+        },
+    },
 ];
 function tableHasColumn(db, tableName, columnName) {
     if (!/^[a-z_]+$/i.test(tableName))
@@ -2445,11 +2469,14 @@ export function getHippoDbPath(hippoRoot) {
 export function getCurrentSchemaVersion() {
     return CURRENT_SCHEMA_VERSION;
 }
+/** Thrown by {@link assertBinaryCompatible}; doctor uses it to pick the upgrade fix over a generic permissions fix. */
+export class IncompatibleBinaryError extends Error {
+}
 /** Refuse a store stamped for a newer binary. Fails closed: runMigrations creates meta first, so a failed read is a real error. */
 function assertBinaryCompatible(db) {
     const minRequired = getMeta(db, 'min_compatible_binary');
     if (minRequired && compareSemver(minRequired, PACKAGE_VERSION) > 0) {
-        throw new Error(`hippo-memory: this database requires hippo-memory >= ${minRequired}, but the running binary is ${PACKAGE_VERSION}. ` +
+        throw new IncompatibleBinaryError(`hippo-memory: this database requires hippo-memory >= ${minRequired}, but the running binary is ${PACKAGE_VERSION}. ` +
             `Upgrade hippo-memory to open it; an older binary does not know this schema and could expose private rows or damage the store.`);
     }
 }
@@ -2506,6 +2533,25 @@ export function openHippoDb(hippoRoot) {
         throw error;
     }
 }
+/** Open an existing store without changing it: no mkdir, WAL switch, migration or mirror cleanup. Throws when hippo.db is missing. */
+export function openHippoDbReadOnly(hippoRoot) {
+    const db = new DatabaseSync(getHippoDbPath(hippoRoot), { readOnly: true });
+    try {
+        db.exec('PRAGMA busy_timeout = 5000');
+        if (tableExists(db, 'meta'))
+            assertBinaryCompatible(db);
+        return db;
+    }
+    catch (error) {
+        try {
+            db.close();
+        }
+        catch {
+            // Best effort only.
+        }
+        throw error;
+    }
+}
 function runMigrations(db, hippoRoot) {
     ensureMetaTable(db);
     // Before anything writes, so a stale binary never repairs or migrates a store it does not understand.
@@ -2554,6 +2600,8 @@ function ensureMetaTable(db) {
   `);
 }
 export function getSchemaVersion(db) {
+    if (!tableExists(db, 'meta'))
+        return 0;
     // SAFETY: row's shape matches the single `value` column named in the
     // SELECT above.
     const row = db.prepare(`SELECT value FROM meta WHERE key = 'schema_version'`).get();
@@ -2760,6 +2808,18 @@ export function getMeta(db, key, fallback = '') {
 export function setMeta(db, key, value) {
     db.prepare(`INSERT INTO meta(key, value) VALUES(?, ?) ON CONFLICT(key) DO UPDATE SET value=excluded.value`).run(key, value);
 }
+/** Row count of one table; null when the table is missing or unreadable, which callers show as unknown. */
+export function countTableRows(db, table) {
+    try {
+        // SAFETY: COUNT(*) returns one row with one numeric column.
+        const row = db.prepare(`SELECT COUNT(*) AS n FROM "${table.replace(/"/g, '""')}"`).get();
+        return Number(row?.n ?? 0);
+    }
+    catch {
+        // Callers treat an uncountable table as unknown; the bundle and doctor still finish.
+        return null;
+    }
+}
 export function isFtsAvailable(db) {
     return getMeta(db, 'fts5_available', '0') === '1';
 }