hippo-memory 1.45.0 → 1.47.0

package/dist/audit.d.ts

@@ -16,7 +16,7 @@ export interface AuditResult {
 export declare function auditMemory(entry: MemoryEntry): AuditIssue | null;
 export declare function auditMemories(entries: MemoryEntry[]): AuditResult;
 export declare function isContentWorthStoring(content: string): boolean;
-export type AuditOp = 'remember' | 'recall' | 'promote' | 'supersede' | 'forget' | 'archive_raw' | 'auth_revoke' | 'auth_create' | 'outcome' | 'consolidate' | 'audit_prune' | 'summary_marked_dirty' | 'summary_marked_clean' | 'summary_rebuilt' | 'predict_create' | 'predict_close' | 'predict_baserate' | 'recall_autodebias_hint' | 'recall_autodebias_hint_no_class_match' | 'recall_autodebias_hint_tiebreak' | 'recall_anchor_detected_query_repeat' | 'recall_anchor_detected_memory_dominance' | 'recall_anchor_skipped_no_session' | 'recall_availability_detected' | 'decision_create' | 'decision_supersede' | 'decision_close' | 'incident_open' | 'incident_resolve' | 'incident_close' | 'process_create' | 'process_supersede' | 'process_close' | 'policy_create' | 'policy_supersede' | 'policy_close' | 'skill_create' | 'skill_supersede' | 'skill_close' | 'project_brief_create' | 'project_brief_supersede' | 'project_brief_close' | 'customer_note_create' | 'customer_note_supersede' | 'customer_note_close' | 'mv_rescue' | 'reject_value' | 'reject_refusal' | 'unreject_value' | 'conflict_resolve';
+export type AuditOp = 'remember' | 'recall' | 'promote' | 'supersede' | 'forget' | 'archive_raw' | 'auth_revoke' | 'auth_create' | 'outcome' | 'consolidate' | 'audit_prune' | 'summary_marked_dirty' | 'summary_marked_clean' | 'summary_rebuilt' | 'predict_create' | 'predict_close' | 'predict_baserate' | 'recall_autodebias_hint' | 'recall_autodebias_hint_no_class_match' | 'recall_autodebias_hint_tiebreak' | 'recall_anchor_detected_query_repeat' | 'recall_anchor_detected_memory_dominance' | 'recall_anchor_skipped_no_session' | 'recall_availability_detected' | 'decision_create' | 'decision_supersede' | 'decision_close' | 'incident_open' | 'incident_resolve' | 'incident_close' | 'process_create' | 'process_supersede' | 'process_close' | 'policy_create' | 'policy_supersede' | 'policy_close' | 'skill_create' | 'skill_supersede' | 'skill_close' | 'project_brief_create' | 'project_brief_supersede' | 'project_brief_close' | 'customer_note_create' | 'customer_note_supersede' | 'customer_note_close' | 'mv_rescue' | 'reject_value' | 'reject_refusal' | 'unreject_value' | 'half_life_migrate' | 'dormant_restore' | 'conflict_resolve';
 export interface AppendAuditOpts {
     tenantId: string;
     actor: string;

package/dist/capture-error.d.ts

@@ -0,0 +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';
+/** 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: 'skipped-interrupt' | 'skipped-invalid';
+    text: null;
+    detail: null;
+};
+/** 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

@@ -0,0 +1,110 @@
+// `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;
+/** 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) {
+    return v !== undefined && v !== null && v.constructor === String;
+}
+function isObject(v) {
+    return v !== undefined && v !== null && !Array.isArray(v) && v.constructor === Object;
+}
+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 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', 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', text: null, detail: null };
+    if (!isString(p.error) || p.error.trim().length < 12)
+        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();
+    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 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 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);
+    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(text, {
+        tags: ['error', 'auto-captured'],
+        source: 'tool-failure',
+        confidence: 'observed',
+        tenantId,
+        baseHalfLifeDays: loadConfig(hippoRoot).defaultHalfLifeDays,
+    });
+    writeEntry(hippoRoot, entry);
+    return 'stored';
+}
+//# sourceMappingURL=capture-error.js.map

package/dist/capture.d.ts

@@ -45,14 +45,6 @@ export interface CaptureOptions {
      */
     tenantId?: string;
 }
-/**
- * Build a compact text summary from a Claude Code / OpenCode JSONL transcript.
- * Keeps plain user messages and the final chunk of assistant text, drops
- * thinking blocks, tool_use, and tool_result noise. Output is fed to the
- * existing `extractFromText` pipeline.
- *
- * Exported for tests.
- */
 export declare function summariseTranscript(jsonl: string): string;
 /**
  * Resolve a transcript path for `--last-session`.
@@ -111,6 +103,24 @@ export declare function readTranscriptTail(transcriptPath: string, capBytes?: nu
  * guard, not per-file copies.
  */
 export declare function sanitizeLogMessage(message: string): string;
+/** What one pre-compact run saved, reported to the user after compaction. */
+export interface PreCompactReport {
+    snapshotSaved: boolean;
+    captured: number;
+    /** Claude Code session the run belonged to, when the payload named one. */
+    sessionId: string | null;
+}
+/**
+ * The line shown to the user after compaction, or null when nothing was
+ * saved. Without it the only sign was Claude Code's generic
+ * "PreCompact [...] completed successfully".
+ */
+export declare function preCompactMessage(report: Pick<PreCompactReport, 'snapshotSaved' | 'captured'>): string | null;
+/**
+ * Where pre-compact leaves its report for `hippo post-compact`: next to the
+ * pre-compact log, so both hooks find it from the same `--log-file`.
+ */
+export declare function preCompactReportPath(logFile: string): string;
 export interface PreCompactOptions {
     stdinText?: string;
     stdinTimedOut?: boolean;
@@ -124,4 +134,11 @@ export interface PreCompactOptions {
  * could turn a caught-and-logged failure back into a non-zero exit.
  */
 export declare function cmdPreCompact(hippoRoot: string, options: PreCompactOptions): Promise<void>;
+/**
+ * The message for the PostCompact hook, from the report pre-compact left,
+ * or null when there is nothing to say. Consumes the report, so the message
+ * shows once. A report from another session, or an old one, is dropped.
+ * Never throws.
+ */
+export declare function postCompactMessage(stdinText: string | undefined, logFile?: string, now?: Date): string | null;
 //# sourceMappingURL=capture.d.ts.map

package/dist/capture.js

@@ -21,6 +21,7 @@ import { defaultPreCompactLogPath } from './hooks.js';
 import { redactSecrets } from './secret-detect.js';
 import { RejectedValueError, checkRejectionGuard } from './rejection.js';
 import { openHippoDb, closeHippoDb } from './db.js';
+import { loadConfig } from './config.js';
 // Sentence-level patterns
 //
 // T1 (DF2): each pattern now carries TWO capture groups — group 1 is the
@@ -489,6 +490,7 @@ function writeExtractedItems(hippoRoot, tenantId, extracted) {
     let captured = 0;
     let skipped = 0;
     let rejected = 0;
+    const baseHalfLifeDays = loadConfig(hippoRoot).defaultHalfLifeDays;
     for (const item of extracted) {
         if (isDuplicate(item.content, existing)) {
             skipped++;
@@ -500,6 +502,7 @@ function writeExtractedItems(hippoRoot, tenantId, extracted) {
             source: 'capture',
             confidence: 'observed',
             tenantId,
+            baseHalfLifeDays,
         });
         // AT1 (plan §3 containment): a refusal is per-VALUE — one rejected
         // extraction must not abort the rest of this transcript's captures.
@@ -551,6 +554,14 @@ function errorMessage(cause) {
  *
  * Exported for tests.
  */
+/** Leading markers of the command lines Claude Code writes with type 'user'. */
+const CLAUDE_CODE_COMMAND_PREFIXES = ['<local-command-', '<command-name>', '<command-message>', '<command-args>'];
+function isNonHumanUserLine(entry, content) {
+    if (entry.isMeta === true || entry.isSidechain === true || entry.isCompactSummary === true)
+        return true;
+    const head = content.trimStart();
+    return CLAUDE_CODE_COMMAND_PREFIXES.some((p) => head.startsWith(p));
+}
 export function summariseTranscript(jsonl) {
     const lines = jsonl.split('\n').filter((l) => l.trim());
     const userMessages = [];
@@ -571,8 +582,9 @@ export function summariseTranscript(jsonl) {
                 continue;
             const content = 'content' in message ? message.content : undefined;
             if (entry.type === 'user') {
-                // Plain text user messages only (skip tool_result arrays)
-                if (isStringValue(content) && content.trim()) {
+                // Plain text user messages only (skip tool_result arrays), and only
+                // ones the human wrote (see isNonHumanUserLine).
+                if (isStringValue(content) && content.trim() && !isNonHumanUserLine(entry, content)) {
                     userMessages.push(content.trim());
                 }
             }
@@ -1030,7 +1042,7 @@ function lastPlainUserMessage(jsonl) {
         if (!message)
             continue;
         const content = 'content' in message ? message.content : undefined;
-        if (isStringValue(content) && content.trim())
+        if (isStringValue(content) && content.trim() && !isNonHumanUserLine(entry, content))
             return content.trim();
     }
     return '';
@@ -1109,12 +1121,34 @@ function isReadableFile(filePath) {
         return false;
     }
 }
+/**
+ * The line shown to the user after compaction, or null when nothing was
+ * saved. Without it the only sign was Claude Code's generic
+ * "PreCompact [...] completed successfully".
+ */
+export function preCompactMessage(report) {
+    if (!report.snapshotSaved && report.captured === 0)
+        return null;
+    const parts = [];
+    if (report.snapshotSaved)
+        parts.push('your task snapshot');
+    if (report.captured > 0)
+        parts.push(`${report.captured} new memor${report.captured === 1 ? 'y' : 'ies'}`);
+    return `Hippo saved ${parts.join(' and ')} before compacting.${report.snapshotSaved ? ' The snapshot is restored into the new context.' : ''}`;
+}
+/**
+ * Where pre-compact leaves its report for `hippo post-compact`: next to the
+ * pre-compact log, so both hooks find it from the same `--log-file`.
+ */
+export function preCompactReportPath(logFile) {
+    return path.join(path.dirname(logFile), 'pre-compact-last.json');
+}
 /**
  * Runs the PreCompact producer. Returns any `embedMemory` promises kicked
  * off along the way (empty on every skip path) so `cmdPreCompact` can await
  * them, bounded, before it exits (X6).
  */
-function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile) {
+function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile, report) {
     // X3: the PreCompact hook fires in every Claude Code project, including
     // ones that never ran `hippo init`, so gate before any store-opening call
     // (saveActiveTaskSnapshot etc. call initStore, which would create one).
@@ -1156,6 +1190,7 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile) {
         }
         if ('session_id' in payload && isStringValue(payload.session_id))
             sessionId = payload.session_id;
+        report.sessionId = sessionId;
         payloadTranscriptPath = payload.transcript_path;
     }
     // X11: payload transcript_path must end .jsonl. No directory-containment
@@ -1291,6 +1326,7 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile) {
                 session_id: sessionId,
             });
             appendPreCompactLog(logFile, 'snapshot saved');
+            report.snapshotSaved = true;
         }
         catch (err) {
             appendPreCompactLog(logFile, `snapshot save failed: ${errorMessage(err)}`);
@@ -1300,6 +1336,7 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile) {
     // the next SessionEnd capture (existing dedup absorbs the overlap).
     try {
         const { captured, skipped, rejected, embeds } = writeExtractedItems(hippoRoot, tenantId, extracted);
+        report.captured = captured;
         appendPreCompactLog(logFile, `capture: ${captured} items captured, ${skipped} skipped` +
             (rejected > 0 ? `, ${rejected} rejected` : ''));
         return embeds;
@@ -1324,8 +1361,9 @@ const EMBED_SETTLE_TIMEOUT_MS = 3000;
 export async function cmdPreCompact(hippoRoot, options) {
     const logFile = options.logFile ?? defaultPreCompactLogPath();
     let embeds = [];
+    const report = { snapshotSaved: false, captured: 0, sessionId: null };
     try {
-        embeds = runPreCompact(hippoRoot, options.stdinText, options.stdinTimedOut ?? false, logFile);
+        embeds = runPreCompact(hippoRoot, options.stdinText, options.stdinTimedOut ?? false, logFile, report);
     }
     catch (err) {
         appendPreCompactLog(logFile, `pre-compact failed: ${errorMessage(err)}`);
@@ -1341,6 +1379,63 @@ export async function cmdPreCompact(hippoRoot, options) {
         clearTimeout(timer);
         appendPreCompactLog(logFile, outcome === 'settled' ? 'embeddings settled' : 'embeddings timeout');
     }
+    // Nothing goes to stdout: Claude Code passes PreCompact stdout to the
+    // summarising model as extra instructions. The PostCompact hook
+    // (`hippo post-compact`) tells the user instead, from this report.
+    if (report.snapshotSaved || report.captured > 0) {
+        try {
+            fs.writeFileSync(preCompactReportPath(logFile), JSON.stringify({ ...report, at: new Date().toISOString() }));
+        }
+        catch {
+            // Losing the message must never fail the hook.
+        }
+    }
     process.exit(0);
 }
+/** How old a pre-compact report may be and still describe this compaction. */
+const POST_COMPACT_REPORT_MAX_AGE_MS = 10 * 60_000;
+/**
+ * The message for the PostCompact hook, from the report pre-compact left,
+ * or null when there is nothing to say. Consumes the report, so the message
+ * shows once. A report from another session, or an old one, is dropped.
+ * Never throws.
+ */
+export function postCompactMessage(stdinText, logFile = defaultPreCompactLogPath(), now = new Date()) {
+    const reportFile = preCompactReportPath(logFile);
+    let raw;
+    try {
+        raw = fs.readFileSync(reportFile, 'utf8');
+        fs.rmSync(reportFile, { force: true });
+    }
+    catch {
+        return null;
+    }
+    try {
+        const report = JSON.parse(raw);
+        if (!isObjectLike(report))
+            return null;
+        const at = 'at' in report && isStringValue(report.at) ? Date.parse(report.at) : Number.NaN;
+        if (Number.isNaN(at) || now.getTime() - at > POST_COMPACT_REPORT_MAX_AGE_MS)
+            return null;
+        let payloadSession = null;
+        try {
+            const payload = JSON.parse((stdinText ?? '').trim() || 'null');
+            if (isObjectLike(payload) && 'session_id' in payload && isStringValue(payload.session_id))
+                payloadSession = payload.session_id;
+        }
+        catch {
+            // No usable payload: fall back to the age check alone.
+        }
+        const reportSession = 'sessionId' in report && isStringValue(report.sessionId) ? report.sessionId : null;
+        if (payloadSession !== null && reportSession !== null && payloadSession !== reportSession)
+            return null;
+        return preCompactMessage({
+            snapshotSaved: 'snapshotSaved' in report && report.snapshotSaved === true,
+            captured: 'captured' in report && Number.isInteger(report.captured) ? Number(report.captured) : 0,
+        });
+    }
+    catch {
+        return null;
+    }
+}
 //# sourceMappingURL=capture.js.map

package/dist/cli.d.ts

@@ -19,6 +19,9 @@
  *   hippo reject <id>|--value "<text>" --reason "<why>"
  *   hippo rejections
  *   hippo unreject <digest-prefix>
+ *   hippo dormant [<query>] [--limit <n>] [--json] | restore <id> | forget <id>
+ *   hippo tokens [--days <n>] [--json] [--global]
+ *   hippo doctor [--json]
  *   hippo inspect <id>
  *   hippo embed [--status]
  *   hippo watch "<command>"
@@ -58,6 +61,8 @@ export declare function printContextMarkdown(items: Array<{
     score: number;
     tokens: number;
     isGlobal: boolean;
-}>, totalTokens: number, framing?: string): void;
+}>, totalTokens: number, framing?: string, opts?: {
+    showStrength?: boolean;
+}): void;
 export declare function runCli(argv?: string[]): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map