hippo-memory 1.52.9 → 1.53.1

package/dist/audit.js

@@ -109,11 +109,12 @@ function hasNoSpecificity(text) {
         return false;
     return words.length < 8 && VAGUE_ONLY.test(text);
 }
-export function auditMemory(entry) {
+export function auditMemory(entry, backsObject = false) {
     const issue = classifyMemory(entry);
-    // Error means "auto-remove"; a pinned or raw row is never auto-removed, so it can only warn.
-    if (issue?.severity === 'error' && !canAutoDelete(entry)) {
-        return { ...issue, severity: 'warning', reason: `${issue.reason} (${entry.pinned ? 'pinned' : 'raw'}, kept)` };
+    // Error means "auto-remove"; a pinned, raw, kept-for-good or object-backing row is never auto-removed, so it can only warn.
+    if (issue?.severity === 'error' && (!canAutoDelete(entry) || backsObject)) {
+        const why = entry.pinned ? 'pinned' : entry.kind === 'raw' ? 'raw' : backsObject ? 'backs an object' : 'keep rule';
+        return { ...issue, severity: 'warning', reason: `${issue.reason} (${why}, kept)` };
     }
     return issue;
 }
@@ -140,10 +141,11 @@ function classifyMemory(entry) {
     }
     return null;
 }
-export function auditMemories(entries) {
+/** `backing`: ids of memories that back an object (store.memoriesBackingObjects). */
+export function auditMemories(entries, backing) {
     const issues = [];
     for (const entry of entries) {
-        const issue = auditMemory(entry);
+        const issue = auditMemory(entry, backing.has(entry.id));
         if (issue)
             issues.push(issue);
     }
@@ -229,6 +231,8 @@ export const AUDIT_OPS = [
     'quarantine', // emitted by recordQuarantine inside remember's write transaction
     'quarantine_approve', // emitted by api.quarantineApprove
     'quarantine_reject', // emitted by api.quarantineReject
+    'agent_memory_restore', // emitted by the agent memory sync when a deleted note comes back
+    'agent_memory_set_aside', // emitted by the agent memory sync when a note is deleted or refused
 ];
 function isBigIntValue(value) {
     return typeof value === 'bigint';

package/dist/capture.d.ts

@@ -89,11 +89,13 @@ export declare function summariseTranscript(jsonl: string): string;
  * Priority, where the first source present is the only one tried:
  *   1. Explicit `transcriptPath` option (from `--transcript <path>`)
  *   2. Stdin JSON payload (Claude Code / OpenCode SessionEnd hook shape)
- *   3. Most recent `.jsonl` under `~/.claude/projects/<any>/`, only on a proven manual run (no path, no stdin text, no timed-out read), because this scan spans every project on the box
+ *   3. Most recent `.jsonl` under `~/.claude/projects/<any>/`, only when the caller passes `mayScan` (only the caller knows it is not a hook) and there is no path and no stdin text, because this scan spans every project on the box
  *
  * Returns null when nothing resolves, a named transcript or payload whose file is missing included. Never throws.
  */
-export declare function resolveLastSessionTranscript(explicit: string | undefined, stdinText: string | undefined, stdinTimedOut?: boolean): string | null;
+export declare function resolveLastSessionTranscript(explicit: string | undefined, stdinText: string | undefined, opts: {
+    mayScan: boolean;
+}): string | null;
 export declare function cmdCapture(hippoRoot: string, options: CaptureOptions): void;
 /** Never read the whole transcript — PreCompact fires exactly when it's largest. */
 export declare const PRE_COMPACT_TAIL_BYTES: number;
@@ -140,19 +142,6 @@ 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;
-    /** Claude Code session the run belonged to, when the payload named one. */
-    sessionId: string | null;
-}
-/** Line shown after compaction, or null when nothing was saved (Claude Code's own generic message is the fallback). */
-export declare function preCompactMessage(report: Pick<PreCompactReport, 'snapshotSaved'>): 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;
 /** A session's task, summary and next step from its transcript tail, secrets scrubbed and capped, '' where none; null with a logged reason when nothing is derivable. */
 export declare function transcriptWorkingState(transcriptPath: string, log: (message: string) => void): Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null;
 export interface PreCompactOptions {
@@ -168,12 +157,12 @@ 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;
+export interface PostCompactOptions {
+    stdinText?: string;
+    logFile?: string;
+    afterSave?: (transcriptPath: string, originProject: string, log: (message: string) => void) => void;
+}
+/** PostCompact entry point: saves the summary and its items, replays earlier leftovers, returns the one line to show. Never throws, so the hook exits 0. */
+export declare function cmdPostCompact(hippoRoot: string, options: PostCompactOptions): string | null;
 export {};
 //# sourceMappingURL=capture.d.ts.map

package/dist/capture.js

@@ -13,7 +13,9 @@ import * as path from 'path';
 import { createMemory, Layer } from './memory.js';
 import { duplicateKey, storedTextKeys } from './same-text.js';
 import { isContentWorthStoring } from './audit.js';
-import { isInitialized, writeEntry, loadAllEntries, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, } from './store.js';
+import { isInitialized, openStore, stampOriginProject, writeEntryMirrors, loadAllEntries, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, } from './store.js';
+import { gatedWrite } from './gated-write.js';
+import { PRE_COMPACT_INSTRUCTION, compactionOrigin, parsePostCompactPayload, postCompactLine, recordCompactionStart, recordSnapshotSaved, saveCompaction, replayCompactionsAt, COMPACTION_DB_WAIT_MS, } from './compaction-record.js';
 import { getGlobalRoot, initGlobal } from './shared.js';
 import { embedMemory } from './embeddings.js';
 import { resolveTenantId } from './tenant.js';
@@ -627,11 +629,11 @@ function summariseSessionTurns(turns) {
  * Priority, where the first source present is the only one tried:
  *   1. Explicit `transcriptPath` option (from `--transcript <path>`)
  *   2. Stdin JSON payload (Claude Code / OpenCode SessionEnd hook shape)
- *   3. Most recent `.jsonl` under `~/.claude/projects/<any>/`, only on a proven manual run (no path, no stdin text, no timed-out read), because this scan spans every project on the box
+ *   3. Most recent `.jsonl` under `~/.claude/projects/<any>/`, only when the caller passes `mayScan` (only the caller knows it is not a hook) and there is no path and no stdin text, because this scan spans every project on the box
  *
  * Returns null when nothing resolves, a named transcript or payload whose file is missing included. Never throws.
  */
-export function resolveLastSessionTranscript(explicit, stdinText, stdinTimedOut = false) {
+export function resolveLastSessionTranscript(explicit, stdinText, opts) {
     if (explicit)
         return fs.existsSync(explicit) ? explicit : null;
     if (stdinText && stdinText.trim() !== '') {
@@ -648,7 +650,7 @@ export function resolveLastSessionTranscript(explicit, stdinText, stdinTimedOut
         }
         return null;
     }
-    if (stdinTimedOut)
+    if (!opts.mayScan)
         return null;
     const home = process.env.HOME || process.env.USERPROFILE;
     if (!home)
@@ -788,7 +790,7 @@ function cmdCaptureCore(hippoRoot, options) {
         case 'last-session': {
             let turns = options.sessionTurns;
             if (!turns) {
-                const resolved = resolveLastSessionTranscript(options.transcriptPath, options.stdinText, options.stdinTimedOut);
+                const resolved = resolveLastSessionTranscript(options.transcriptPath, options.stdinText, { mayScan: !options.stdinTimedOut });
                 if (!resolved) {
                     console.log('No transcript found. Pass --transcript <path> or run from a SessionEnd hook.');
                     return;
@@ -832,6 +834,7 @@ function cmdCaptureCore(hippoRoot, options) {
     // once, run the same checkRejectionGuard the real write path uses via
     // writeEntry, never write anything.
     const dryRunDb = options.dryRun ? openHippoDb(targetRoot) : null;
+    const writeDb = options.dryRun ? null : openStore(targetRoot);
     try {
         for (const item of extracted) {
             if (keys.has(duplicateKey(item.content))) {
@@ -876,19 +879,20 @@ function cmdCaptureCore(hippoRoot, options) {
                 }
                 console.log(`  [capture] (${item.category}) ${item.content}`);
             }
-            else {
+            else if (writeDb !== null) {
                 // AT1 (plan §3 containment): one rejected item must not abort the
                 // rest of this capture's items.
-                try {
-                    writeEntry(targetRoot, entry);
+                const stamped = stampOriginProject(targetRoot, entry);
+                const outcome = gatedWrite(writeDb, targetRoot, stamped);
+                if (outcome === 'skipped:rejected') {
+                    rejected++;
+                    continue;
                 }
-                catch (err) {
-                    if (err instanceof RejectedValueError) {
-                        rejected++;
-                        continue;
-                    }
-                    throw err;
+                if (outcome !== 'written') {
+                    skipped++;
+                    continue;
                 }
+                writeEntryMirrors(targetRoot, stamped);
                 updateStats(targetRoot, { remembered: 1 });
                 keys.add(duplicateKey(item.content)); // within-batch dedup
                 void embedMemory(targetRoot, entry);
@@ -899,6 +903,8 @@ function cmdCaptureCore(hippoRoot, options) {
     finally {
         if (dryRunDb)
             closeHippoDb(dryRunDb);
+        if (writeDb)
+            closeHippoDb(writeDb);
     }
     const prefix = options.dryRun ? '[dry-run] ' : '';
     const globalPrefix = useGlobal ? '[global] ' : '';
@@ -1098,18 +1104,14 @@ function isReadableFile(filePath) {
         return false;
     }
 }
-/** Line shown after compaction, or null when nothing was saved (Claude Code's own generic message is the fallback). */
-export function preCompactMessage(report) {
-    if (!report.snapshotSaved)
-        return null;
-    return 'Hippo saved your task snapshot before compacting. 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');
+/** 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) {
+    try {
+        fs.writeSync(1, `${PRE_COMPACT_INSTRUCTION}\n`);
+    }
+    catch (err) {
+        appendPreCompactLog(logFile, `instruction not printed: ${errorMessage(err)}`);
+    }
 }
 /** A session's task, summary and next step from its transcript tail, secrets scrubbed and capped, '' where none; null with a logged reason when nothing is derivable. */
 export function transcriptWorkingState(transcriptPath, log) {
@@ -1150,8 +1152,8 @@ export function transcriptWorkingState(transcriptPath, log) {
         next_step: nextStep.trim() ? truncateCodePointSafe(nextStep, PRE_COMPACT_NEXT_STEP_CAP) : '',
     };
 }
-/** Runs the PreCompact producer: saves a working-state snapshot into `report`. Never extracts memories; SessionEnd capture owns that. */
-function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile, report) {
+/** 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, stdinText, stdinTimedOut, logFile) {
     // 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).
@@ -1175,6 +1177,8 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile, report) {
     const manualInvocation = !stdinText || stdinText.trim() === '';
     let sessionId = null;
     let payloadTranscriptPath = null;
+    let payloadCwd = null;
+    let payloadTrigger = null;
     if (!manualInvocation) {
         let payload;
         try {
@@ -1193,8 +1197,9 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile, report) {
         }
         if ('session_id' in payload && isStringValue(payload.session_id))
             sessionId = payload.session_id;
-        report.sessionId = sessionId;
         payloadTranscriptPath = payload.transcript_path;
+        payloadCwd = 'cwd' in payload && isStringValue(payload.cwd) ? payload.cwd : null;
+        payloadTrigger = 'trigger' in payload && isStringValue(payload.trigger) ? payload.trigger : null;
     }
     // X11: payload transcript_path must end .jsonl. No directory-containment
     // check is applied on top of this — CLAUDE_CONFIG_DIR can relocate the
@@ -1207,6 +1212,12 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile, report) {
         appendPreCompactLog(logFile, `skip: payload transcript_path is not a .jsonl file: ${payloadTranscriptPath}`);
         return;
     }
+    // The record is the "something saved before every compaction", so it lands even when no snapshot is derivable below.
+    let recordId = null;
+    if (sessionId !== null && sessionId !== '') {
+        recordId = recordCompactionStart(hippoRoot, { sessionId, trigger: payloadTrigger, cwd: payloadCwd, transcriptPath: payloadTranscriptPath }, (message) => appendPreCompactLog(logFile, message));
+        printPreCompactInstruction(logFile);
+    }
     // A payload transcript_path is EXCLUSIVE: never fall back to
     // newest-transcript auto-discovery when it's missing/unreadable. That
     // fallback would snapshot a DIFFERENT session's transcript under THIS
@@ -1224,7 +1235,7 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile, report) {
         }
     }
     else {
-        transcriptPath = resolveLastSessionTranscript(undefined, stdinText);
+        transcriptPath = resolveLastSessionTranscript(undefined, stdinText, { mayScan: true });
     }
     if (!transcriptPath) {
         appendPreCompactLog(logFile, 'skip: no transcript resolved');
@@ -1275,7 +1286,8 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile, report) {
                 session_id: sessionId,
             });
             appendPreCompactLog(logFile, 'snapshot saved');
-            report.snapshotSaved = true;
+            if (recordId !== null)
+                recordSnapshotSaved(hippoRoot, recordId, (message) => appendPreCompactLog(logFile, message));
         }
         catch (err) {
             appendPreCompactLog(logFile, `snapshot save failed: ${errorMessage(err)}`);
@@ -1291,68 +1303,51 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile, report) {
  */
 export async function cmdPreCompact(hippoRoot, options) {
     const logFile = options.logFile ?? defaultPreCompactLogPath();
-    const report = { snapshotSaved: false, sessionId: null };
     try {
-        runPreCompact(hippoRoot, options.stdinText, options.stdinTimedOut ?? false, logFile, report);
+        runPreCompact(hippoRoot, options.stdinText, options.stdinTimedOut ?? false, logFile);
     }
     catch (err) {
         appendPreCompactLog(logFile, `pre-compact failed: ${errorMessage(err)}`);
     }
-    // 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) {
-        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;
-    }
+/** A PostCompact hook has 10 s in all; replay stops starting new records after this. */
+const POST_COMPACT_REPLAY_BUDGET_MS = 6000;
+/** PostCompact entry point: saves the summary and its items, replays earlier leftovers, returns the one line to show. Never throws, so the hook exits 0. */
+export function cmdPostCompact(hippoRoot, options) {
+    const logFile = options.logFile ?? defaultPreCompactLogPath();
+    const log = (message) => appendPreCompactLog(logFile, `post-compact: ${message}`);
+    const deadline = Date.now() + POST_COMPACT_REPLAY_BUDGET_MS;
     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)
+        if (!isInitialized(hippoRoot)) {
+            log('skip: no hippo store');
             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 payload = parsePostCompactPayload(options.stdinText);
+        let line = null;
+        let storeBusy = false;
+        if (payload === null) {
+            log('skip: no PostCompact payload naming a session');
         }
-        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,
-        });
+        else {
+            const saved = saveCompaction(hippoRoot, payload, log);
+            line = postCompactLine(saved);
+            storeBusy = saved.deferred;
+            if (!storeBusy && payload.transcriptPath !== null && options.afterSave) {
+                try {
+                    options.afterSave(payload.transcriptPath, compactionOrigin(hippoRoot, payload.cwd), log);
+                }
+                catch (err) {
+                    log(`agent memory import failed: ${errorMessage(err)}`);
+                }
+            }
+        }
+        if (!storeBusy)
+            replayCompactionsAt(hippoRoot, log, { busyWaitMs: COMPACTION_DB_WAIT_MS, deadline });
+        return line;
     }
-    catch {
+    catch (err) {
+        log(`failed: ${errorMessage(err)}`);
         return null;
     }
 }

package/dist/cli.d.ts

@@ -43,8 +43,6 @@ export declare function parseArgs(argv: string[]): {
     args: string[];
     flags: Record<string, string | boolean | string[]>;
 };
-/** Import new entries from the Claude Code auto memory of the store's project, the frontmatter .md files in ~/.claude/projects/<project>/memory/. */
-export declare function learnFromMemoryMd(hippoRoot: string, homeDir?: string): number;
 /**
  * Render an api.sleep result as console output, byte-identical to the
  * pre-extraction inline implementation in cmdSleepCore.