hippo-memory 1.45.0 → 1.46.0

package/dist/capture-error.d.ts

@@ -0,0 +1,20 @@
+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): {
+    text: string;
+} | {
+    skip: Exclude<CaptureErrorOutcome, 'stored' | 'duplicate'>;
+};
+/**
+ * Store a failure payload as an error memory unless it is routine or a
+ * repeat of an auto-captured error already in the store.
+ */
+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,82 @@
+/**
+ * `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.
+ */
+import { createMemory } from './memory.js';
+import { writeEntry, loadAllEntries } from './store.js';
+import { loadConfig } from './config.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,
+];
+/** 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;
+}
+/** Normalised form used to spot repeats of the same failure. */
+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.
+ */
+export function lessonFromFailure(payload) {
+    if (!isObject(payload))
+        return { skip: 'skipped-invalid' };
+    // 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' };
+    if (!isString(p.error) || p.error.trim().length < 12)
+        return { skip: 'skipped-invalid' };
+    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' };
+    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) };
+}
+/**
+ * Store a failure payload as an error memory unless it is routine or a
+ * repeat of an auto-captured error already in the store.
+ */
+export function captureToolFailure(hippoRoot, tenantId, payload) {
+    const lesson = lessonFromFailure(payload);
+    if ('skip' in lesson)
+        return lesson.skip;
+    const sig = failureSignature(lesson.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, {
+        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