hippo-memory 1.69.0 → 1.71.0

package/dist/capture/compact.js

@@ -2,27 +2,18 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { isInitialized } from '../store/open.js';
 import { saveActiveTaskSnapshot, loadActiveTaskSnapshot } from '../store/sessions.js';
-import { PRE_COMPACT_INSTRUCTION, parsePostCompactPayload, postCompactLine, recordCompactionStart, recordSnapshotSaved, saveCompaction, replayCompactionsAt, COMPACTION_DB_WAIT_MS, } from '../compaction-record.js';
-import { resolveTenantId } from '../tenant.js';
+import { PRE_COMPACT_INSTRUCTION, postCompactLine, recordCompactionStart, recordSnapshotSaved, saveCompaction, replayCompactionsAt, COMPACTION_DB_WAIT_MS, } from './compaction-record.js';
+import { resolveTenantId } from '../store/tenant.js';
 import { defaultPreCompactLogPath, vscodeUserHooksFile } from '../hooks/shared.js';
-import { readClaudeCodePreCompact } from '../capture-contract.js';
-import { errorMessage } from '../log.js';
+import { readClaudeCodePostCompact, readClaudeCodePreCompact } from '../core/capture-contract.js';
+import { errorMessage, log as logger } from '../util/log.js';
 import { resolveLastSessionTranscript } from './transcript.js';
 import { isVscodeTranscript } from './copilot-transcript.js';
 import { mergeWorkingState, transcriptWorkingState } from './working-state.js';
-// ---------------------------------------------------------------------------
-// `hippo pre-compact` — PreCompact hook producer
-// ---------------------------------------------------------------------------
 // Diagnostic-only log; a long-lived install must not grow it unbounded.
 const PRE_COMPACT_LOG_MAX_BYTES = 256 * 1024;
-/**
- * Log-forgery guard: messages here interpolate payload-controlled values
- * (transcript paths, session ids). Strip C0 control chars — newlines above
- * all — so a crafted value can't inject fake `[hippo] ...` log lines.
- * Exported for every `[hippo]`-prefixed log writer that interpolates
- * payload-controlled values (cli.ts appendSessionEndCloseLog) — one shared
- * guard, not per-file copies.
- */
+/** Log-forgery guard: strip C0 control chars (newlines above all) from payload-controlled values so a crafted value cannot inject fake `[hippo]` log lines.
+ *  Exported as the one shared guard for every `[hippo]`-prefixed log writer that interpolates payload values. */
 export function sanitizeLogMessage(message) {
     // eslint-disable-next-line no-control-regex
     return message.replace(/[\x00-\x1f]/g, '');
@@ -30,14 +21,22 @@ export function sanitizeLogMessage(message) {
 function appendPreCompactLog(logFile, message) {
     try {
         fs.mkdirSync(path.dirname(logFile), { recursive: true });
-        const stat = fs.existsSync(logFile) ? fs.statSync(logFile) : null;
-        if (stat && stat.size > PRE_COMPACT_LOG_MAX_BYTES) {
-            fs.writeFileSync(logFile, '', 'utf8'); // start fresh — dumb cap, no rotation
+        // One handle, so the cap acts on the file it measured; two hooks writing in the same instant can overwrite one diagnostic line, which this log accepts.
+        const fd = fs.openSync(logFile, fs.constants.O_RDWR | fs.constants.O_CREAT);
+        try {
+            const size = fs.fstatSync(fd).size;
+            const startFresh = size > PRE_COMPACT_LOG_MAX_BYTES; // a dumb cap, no rotation
+            if (startFresh)
+                fs.ftruncateSync(fd, 0);
+            fs.writeSync(fd, `[hippo] ${new Date().toISOString()} ${sanitizeLogMessage(message)}\n`, startFresh ? 0 : size, 'utf8');
+        }
+        finally {
+            fs.closeSync(fd);
         }
-        fs.appendFileSync(logFile, `[hippo] ${new Date().toISOString()} ${sanitizeLogMessage(message)}\n`, 'utf8');
     }
-    catch {
+    catch (err) {
         // Diagnostic-only; a log write failure must never affect the exit-0 contract.
+        logger.debug(`pre-compact log not written: ${errorMessage(err)}`);
     }
 }
 /** True iff `filePath` exists and is readable — checks both in one call. */
@@ -52,11 +51,14 @@ function isReadableFile(filePath) {
 }
 /** PreCompact stdout is the summariser's instructions; sent before the snapshot work because a locked store can run the hook past its 30 s limit, and via writeSync because process.exit drops buffered pipe output. */
 function printPreCompactInstruction(logFile) {
+    const text = `${PRE_COMPACT_INSTRUCTION}\n`;
     try {
-        fs.writeSync(1, `${PRE_COMPACT_INSTRUCTION}\n`);
+        fs.writeSync(1, text);
+        return text;
     }
     catch (err) {
         appendPreCompactLog(logFile, `instruction not printed: ${errorMessage(err)}`);
+        return null;
     }
 }
 /** The Copilot CLI accepts both preCompact and PreCompact, so hippo.json's pair can run twice for one compaction. */
@@ -70,9 +72,7 @@ function snapshotJustSaved(hippoRoot, sessionId) {
 /** Runs the PreCompact producer: records the compaction, asks the summariser for memories, saves a working-state snapshot. Never extracts memories itself; SessionEnd capture owns that. */
 function runPreCompact(hippoRoot, options, logFile) {
     const { stdinText, stdinTimedOut = false, runtime = 'claude-code' } = options;
-    // 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).
+    // PreCompact fires in every Claude Code project, including ones that never ran `hippo init`; gate before any call that would create a store.
     if (!isInitialized(hippoRoot)) {
         appendPreCompactLog(logFile, 'skip: store not initialized');
         return;
@@ -82,7 +82,7 @@ function runPreCompact(hippoRoot, options, logFile) {
         appendPreCompactLog(logFile, `skip: ${receipt.reason}`);
         return;
     }
-    const { sessionId, transcriptPath: payloadTranscriptPath, cwd: payloadCwd, trigger: payloadTrigger } = receipt.input;
+    const { sessionId, transcriptPath: payloadTranscriptPath } = receipt.input;
     // With chat.useClaudeHooks on, VS Code runs Claude Code's hooks too; it never sends PostCompact to close a record, nor reads the summariser text.
     const vscode = runtime === 'claude-code' && isVscodeTranscript(payloadTranscriptPath);
     if (vscode && fs.existsSync(vscodeUserHooksFile())) {
@@ -93,13 +93,7 @@ function runPreCompact(hippoRoot, options, logFile) {
         appendPreCompactLog(logFile, `skip: snapshot for session ${sessionId} saved under ${TWIN_FIRE_MS / 1000} s ago, by the other preCompact entry`);
         return;
     }
-    // The record is the "something saved before every compaction", so it lands even when no snapshot is derivable below.
-    // Copilot has no PostCompact hook to close a record, so its compactions get the snapshot alone.
-    let recordId = null;
-    if (runtime === 'claude-code' && !vscode && sessionId !== null && sessionId !== '') {
-        recordId = recordCompactionStart(hippoRoot, { sessionId, trigger: payloadTrigger, cwd: payloadCwd, transcriptPath: payloadTranscriptPath }, (message) => appendPreCompactLog(logFile, message));
-        printPreCompactInstruction(logFile);
-    }
+    const recordId = markCompactionBoundary(hippoRoot, options, logFile, receipt.input, runtime === 'claude-code' && !vscode);
     const transcriptPath = resolvePreCompactTranscript(payloadTranscriptPath, stdinText, logFile, runtime);
     if (!transcriptPath)
         return;
@@ -109,6 +103,26 @@ function runPreCompact(hippoRoot, options, logFile) {
         return;
     saveDerivedSnapshot(hippoRoot, logFile, sessionId, recordId, derived);
 }
+/** Starts the compaction record when the host will close one (`closable`), then tells `onBoundary` what was printed; the record id, or null without a record. */
+function markCompactionBoundary(hippoRoot, options, logFile, input, closable) {
+    const { sessionId } = input;
+    // The record is the "something saved before every compaction", so it lands even when no snapshot is derivable later.
+    // Copilot has no PostCompact hook to close a record, so its compactions get the snapshot alone.
+    let recordId = null;
+    let printed = null;
+    if (closable && sessionId !== null && sessionId !== '') {
+        recordId = recordCompactionStart(hippoRoot, { sessionId, trigger: input.trigger, cwd: input.cwd, transcriptPath: input.transcriptPath }, (message) => appendPreCompactLog(logFile, message));
+        printed = printPreCompactInstruction(logFile);
+    }
+    // Its own guard, so a throwing callback can never skip the snapshot work that follows.
+    try {
+        options.onBoundary?.(printed);
+    }
+    catch (err) {
+        appendPreCompactLog(logFile, `boundary callback failed: ${errorMessage(err)}`);
+    }
+    return recordId;
+}
 /** The transcript to snapshot, or null after logging why there is none. */
 function resolvePreCompactTranscript(payloadTranscriptPath, stdinText, logFile, runtime) {
     // A payload transcript_path is EXCLUSIVE: auto-discovery would snapshot a DIFFERENT session's
@@ -142,8 +156,8 @@ function saveDerivedSnapshot(hippoRoot, logFile, sessionId, recordId, derived) {
     try {
         existing = loadActiveTaskSnapshot(hippoRoot, tenantId);
     }
-    catch {
-        // No existing snapshot to merge against — proceed with derived-only.
+    catch (err) {
+        logger.debug(`pre-compact: stored snapshot unreadable, saving the derived one alone: ${errorMessage(err)}`);
     }
     // Carried-over fields are not re-capped, as `hippo snapshot save` stays uncapped; saveActiveTaskSnapshot scrubs every field.
     const merged = mergeWorkingState(derived, existing, sessionId);
@@ -162,13 +176,8 @@ function saveDerivedSnapshot(hippoRoot, logFile, sessionId, recordId, derived) {
         }
     }
 }
-/**
- * PreCompact hook entry point. Exit code 2 on PreCompact BLOCKS compaction,
- * so this verb must exit 0 on every path — malformed stdin, missing
- * transcript, and store errors all degrade to a logged no-op rather than a
- * thrown error. Callers (src/cli.ts) must not wrap this in anything that
- * could turn a caught-and-logged failure back into a non-zero exit.
- */
+/** PreCompact hook entry point. Exit code 2 BLOCKS compaction, so every path (bad stdin, missing transcript, store error) must exit 0 as a logged no-op.
+ *  Callers must not wrap this in anything that turns a caught-and-logged failure into a non-zero exit. */
 export async function cmdPreCompact(hippoRoot, options) {
     const logFile = options.logFile ?? defaultPreCompactLogPath();
     try {
@@ -191,19 +200,19 @@ export function cmdPostCompact(hippoRoot, options) {
             log('skip: no hippo store');
             return null;
         }
-        const payload = parsePostCompactPayload(options.stdinText);
+        const receipt = readClaudeCodePostCompact(options.stdinText, options.stdinTimedOut ?? false);
         let line = null;
         let storeBusy = false;
-        if (payload === null) {
-            log('skip: no PostCompact payload naming a session');
+        if (receipt.status !== 'received') {
+            log(`skip: ${receipt.reason}`);
         }
         else {
-            const saved = saveCompaction(hippoRoot, payload, log);
+            const saved = saveCompaction(hippoRoot, receipt.input, log);
             line = postCompactLine(saved);
             storeBusy = saved.deferred;
-            if (!storeBusy && payload.transcriptPath !== null && options.afterSave) {
+            if (!storeBusy && receipt.input.transcriptPath !== null && options.afterSave) {
                 try {
-                    options.afterSave(payload.transcriptPath, payload.cwd, log);
+                    options.afterSave(receipt.input.transcriptPath, receipt.input.cwd, log);
                 }
                 catch (err) {
                     log(`agent memory import failed: ${errorMessage(err)}`);

package/dist/capture/compaction-items-caller.d.ts

@@ -1,5 +1,5 @@
 import type { Context } from '../api/types.js';
-import type { CallerProject } from '../prompt-hook.js';
+import type { CallerProject } from '../api/prompt-hook.js';
 export interface CallerItemsRequest {
     readonly sessionId: string;
     readonly project: CallerProject;

package/dist/capture/compaction-items-caller.js

@@ -1,8 +1,8 @@
 // PostCompact for a caller on another machine: the items it parsed become rows under its owner and project, and a retried request id writes nothing twice.
-import { BadRequestError } from '../api-errors.js';
-import { COMPACTION_ITEM_MAX_CHARS } from '../compaction-items.js';
-import { compactionByRequest, recordSummary, saveItems, scrubCompactionItems } from '../compaction-record.js';
-import { log } from '../log.js';
+import { BadRequestError } from '../core/api-errors.js';
+import { COMPACTION_ITEM_MAX_CHARS } from './compaction-items.js';
+import { compactionByRequest, recordSummary, saveItems, scrubCompactionItems } from './compaction-record.js';
+import { log } from '../util/log.js';
 import { assertRequestId, assertTrigger, bindCaller, callerInHoldout, withCallerDb } from './caller-session.js';
 /** Busy throws, for the server's 503: the retry carries the same request id, so nothing is spooled or deferred here. */
 export function saveCompactionItemsForCaller(ctx, req) {
@@ -21,7 +21,9 @@ export function saveCompactionItemsForCaller(ctx, req) {
             return { written: earlier.itemsWritten };
         const meta = { sessionId: req.sessionId, trigger: req.trigger, cwd: null, transcriptPath: null };
         const text = { summary: '', items: scrubCompactionItems(req.items) };
-        const record = earlier ?? recordSummary(db, ctx.hippoRoot, ctx.tenantId, meta, text, new Date(), { originProject: req.project.name, requestId: req.requestId });
+        const record = earlier ?? recordSummary(db, ctx.hippoRoot, ctx.tenantId, {
+            meta, text, at: new Date(), caller: { originProject: req.project.name, requestId: req.requestId },
+        });
         const written = saveItems(db, ctx.hippoRoot, {
             tenantId: ctx.tenantId, recordId: record.id, sessionId: req.sessionId, originProject: record.originProject, cwd: null,
             items: record.items, caller: { actor: key.owner, origins: key.project },

package/dist/{compaction-items.js → capture/compaction-items.js}

@@ -2,10 +2,34 @@
 export const COMPACTION_ITEM_MAX_CHARS = 500;
 export const COMPACTION_ITEM_ROW_CAP = 10;
 const HEADING = 'memories for hippo';
-const ITEM_LINE = /^\s*(?:[-*]|\d+[.)])(?:\s+(.*))?$/;
+// `\S` parts the gap from the text, so a line that fails to match is scanned once, not once per space.
+const ITEM_LINE = /^\s*(?:[-*]|\d+[.)])(?:\s+(\S.*)?)?$/;
+const ANALYSIS_OPEN = '<analysis>';
+const ANALYSIS_CLOSE = '</analysis>';
+const HEADING_TRAILER = /[*:\s]/;
+/** `text` minus each closed <analysis> block; a search, as a lazy pattern rescans the rest from every unclosed tag. */
+function withoutAnalysis(text) {
+    let kept = '';
+    let from = 0;
+    for (;;) {
+        const open = text.indexOf(ANALYSIS_OPEN, from);
+        const close = open < 0 ? -1 : text.indexOf(ANALYSIS_CLOSE, open + ANALYSIS_OPEN.length);
+        if (close < 0)
+            return kept + text.slice(from);
+        kept += text.slice(from, open);
+        from = close + ANALYSIS_CLOSE.length;
+    }
+}
+/** `text` minus its trailing run of `*`, `:` and spaces; read from the end, as a `+$` pattern retries the run from each character. */
+function withoutHeadingTrailer(text) {
+    let end = text.length;
+    while (end > 0 && HEADING_TRAILER.test(text[end - 1]))
+        end--;
+    return text.slice(0, end);
+}
 /** The <summary> body of a PostCompact compact_summary with any <analysis> block removed; the whole text trimmed when there is no <summary> tag. */
 export function compactSummaryBody(compactSummary) {
-    const text = compactSummary.replace(/<analysis>[\s\S]*?<\/analysis>/g, '');
+    const text = withoutAnalysis(compactSummary);
     const open = text.lastIndexOf('<summary>');
     if (open < 0)
         return text.trim();
@@ -14,7 +38,7 @@ export function compactSummaryBody(compactSummary) {
     return text.slice(from, close < 0 ? undefined : close).trim();
 }
 function isHeading(line) {
-    const bare = line.replace(/^(?:[#*\s]|\d+\.)+/, '').replace(/[*:\s]+$/, '');
+    const bare = withoutHeadingTrailer(line.replace(/^(?:[#*\s]|\d+\.)+/, ''));
     return bare.toLowerCase() === HEADING;
 }
 /** found=false when no "Memories for hippo" heading; items in order, "none" dropped, never cut. */

package/dist/{compaction-record.d.ts → capture/compaction-record.d.ts}

@@ -1,4 +1,5 @@
-import { type DatabaseSyncLike } from './db.js';
+import { type DatabaseSyncLike } from '../db/index.js';
+import { type CompactionStatus } from '../store/compactions.js';
 /** PostCompact has 10 s in all (PreCompact 30 s), so a locked store must be given up on early. */
 export declare const COMPACTION_DB_WAIT_MS = 2000;
 /** Tested verbatim: Claude Code hands PreCompact stdout to the summariser as instructions. */
@@ -7,7 +8,7 @@ export declare const PRE_COMPACT_INSTRUCTION = "In your summary, add a last sect
 export declare const REPLAY_AFTER_MS: number;
 /** Claude Code deletes transcripts after 30 days, so an older gap can never be filled. */
 export declare const TRANSCRIPT_FILL_WINDOW_MS: number;
-export type CompactionStatus = 'started' | 'summarised' | 'done' | 'no-summary';
+export type { CompactionStatus };
 export interface CompactionRecord {
     id: string;
     tenantId: string;
@@ -61,8 +62,14 @@ export interface SummaryCaller {
     originProject?: string;
     requestId?: string;
 }
+export interface RecordSummaryOptions {
+    readonly meta: Omit<CompactionStart, 'originProject'>;
+    readonly text: CompactionText;
+    readonly at: Date;
+    readonly caller?: SummaryCaller;
+}
 /** Puts the summary on the session's `started` record, or inserts a `summarised` one when pre-compact wrote none. One statement each. */
-export declare function recordSummary(db: DatabaseSyncLike, hippoRoot: string, tenantId: string, meta: Omit<CompactionStart, 'originProject'>, text: CompactionText, at: Date, caller?: SummaryCaller): CompactionRecord;
+export declare function recordSummary(db: DatabaseSyncLike, hippoRoot: string, tenantId: string, options: RecordSummaryOptions): CompactionRecord;
 export interface ItemContext {
     tenantId: string;
     /** null when the record step failed: the items still go in, with no record to close. */
@@ -88,8 +95,6 @@ export interface PostCompactPayload {
     /** null when Claude Code sent none; the transcript fills the record later. */
     compactSummary: string | null;
 }
-/** null when the text is not a PostCompact payload naming a session. */
-export declare function parsePostCompactPayload(stdinText: string | undefined): PostCompactPayload | null;
 export interface CompactionSaveResult {
     /** Memories written; null when neither the record nor the items could be saved. */
     written: number | null;
@@ -108,5 +113,4 @@ export declare function replayCompactionsAt(hippoRoot: string, log: Log, opts?:
     busyWaitMs?: number;
     deadline?: number;
 }): number;
-export {};
 //# sourceMappingURL=compaction-record.d.ts.map