hippo-memory 1.52.8 → 1.53.0

package/dist/dedupe.js

@@ -1,6 +1,6 @@
 /**
- * Store-level deduplication. Scans for near-duplicate memories by content
- * Jaccard overlap, keeps the stronger copy (by strength + retrieval count),
+ * Store-level deduplication. Scans for memories with the same text apart
+ * from spacing, keeps the stronger copy (by strength + retrieval count),
  * removes the rest.
  *
  * Extracted from cli.ts in Episode A (v1.11.3) so `api.sleep` can dedupe
@@ -25,6 +25,7 @@ import { loadAllEntries, deleteEntry } from './store.js';
 import { compareEntryIdentity } from './compare.js';
 import { canAutoDelete } from './memory.js';
 import { derivationPartitionKey } from './recall-scope.js';
+import { duplicateKey } from './same-text.js';
 /** Quantization step for strength-tie comparisons. The historical 0.01
  *  epsilon (see `strengthBucket` below) applied via rounding instead of a
  *  raw abs-diff threshold, so the tiebreak is transitive. */
@@ -55,16 +56,15 @@ export function strengthBucket(strength) {
     return Number.isFinite(s) ? Math.round(s / STRENGTH_TIE_EPSILON) : 0;
 }
 /**
- * Scan the store for near-duplicate memories and remove the weaker copy.
- * Two memories are duplicates if their content has > threshold Jaccard
- * overlap AND they belong to the same tenant: the scan is partitioned by
+ * Scan the store for duplicates and remove the weaker copy: same text apart
+ * from spacing, since a near-duplicate can differ in a value (port, version,
+ * path, name), AND the same tenant: the scan is partitioned by
  * tenantId, so byte-identical content in two tenants is never a duplicate
  * pair (the tenant boundary is an isolation boundary; cross-tenant removal
  * was the v1.32.0 known-issue data-loss bug).
- * Keeps the one with higher strength (or more retrievals if tied).
+ * Keeps the one with higher strength (or more retrievals if tied). `threshold` is accepted for old callers and ignored.
  */
 export function deduplicateStore(hippoRoot, options = {}) {
-    const threshold = options.threshold ?? 0.7;
     const dryRun = options.dryRun ?? false;
     // Only current distilled rows compete: raw rows are append-only (the delete
     // trigger would abort sleep mid-loop) and superseded rows are history, as in consolidate.ts.
@@ -111,15 +111,16 @@ export function deduplicateStore(hippoRoot, options = {}) {
                 return retrievalDiff;
             return compareEntryIdentity(a, b);
         });
+        const texts = tenantEntries.map((e) => duplicateKey(e.content));
         for (let i = 0; i < tenantEntries.length; i++) {
             if (removed.has(tenantEntries[i].id))
                 continue;
             for (let j = i + 1; j < tenantEntries.length; j++) {
                 if (removed.has(tenantEntries[j].id) || !canAutoDelete(tenantEntries[j]))
                     continue;
-                const similarity = textOverlap(tenantEntries[i].content, tenantEntries[j].content);
-                if (similarity <= threshold)
+                if (texts[j] !== texts[i])
                     continue;
+                const similarity = textOverlap(tenantEntries[i].content, tenantEntries[j].content);
                 removed.add(tenantEntries[j].id);
                 pairs.push({
                     kept: tenantEntries[i].id,

package/dist/doctor.d.ts

@@ -19,7 +19,7 @@ export interface DoctorReport {
 /** Inputs for {@link runDoctor}; defaults come from the process. */
 export interface DoctorOpts {
     cwd?: string;
-    /** Home directory used to find agent configuration (~/.claude). */
+    /** Home directory used to find agent configuration (~/.claude, ~/.codex). */
     home?: string;
     version: string;
     nodeVersion?: string;

package/dist/doctor.js

@@ -11,7 +11,9 @@ import { findHippoStoreDir } from './project-identity.js';
 import { getGlobalRoot } from './shared.js';
 import { isInitialized } from './store.js';
 import { openHippoDbReadOnly, closeHippoDb, getSchemaVersion, getCurrentSchemaVersion, countTableRows, IncompatibleBinaryError } from './db.js';
+import { REPLAY_AFTER_MS, TRANSCRIPT_FILL_WINDOW_MS } from './compaction-record.js';
 import { isEmbeddingAvailable } from './embeddings.js';
+import { CODEX_TRUST_LINE, codexHomeDir, isCodexPresent, isJsonObject } from './hooks.js';
 /** Minimum Node.js version hippo supports (package.json engines). */
 export const MIN_NODE = '22.16.0';
 function versionAtLeast(actual, min) {
@@ -34,6 +36,29 @@ function readJson(file) {
         return null;
     }
 }
+// Trust lives in Codex's own config.toml rows; doctor reads only the hooks file and reminds.
+function codexCheck(home) {
+    const file = path.join(codexHomeDir(home), 'hooks.json');
+    const parsed = readJson(file);
+    // Codex drops every hook in a hooks.json it cannot parse, hippo's included.
+    if (fs.existsSync(file) && !isJsonObject(parsed)) {
+        return { id: 'codex', status: 'warn', detail: "Codex's hooks.json is not a JSON object, so Codex runs no hook from it", fix: 'repair hooks.json, then run: hippo hook install codex' };
+    }
+    const text = JSON.stringify(parsed ?? '');
+    const codexHooks = [
+        ['hippo context --pinned-only', 'per-prompt memory'],
+        ['hippo compact-resume', 'resume after compaction'],
+    ];
+    const missing = codexHooks.filter(([marker]) => !text.includes(marker)).map(([, what]) => what);
+    if (missing.length === 0)
+        return { id: 'codex', status: 'pass', detail: `Codex: hippo memory hooks installed. ${CODEX_TRUST_LINE}` };
+    return {
+        id: 'codex',
+        status: 'warn',
+        detail: missing.length === codexHooks.length ? "Codex found, but hippo's memory hooks are not installed" : `Codex: hippo hooks missing for ${missing.join(', ')}`,
+        fix: 'hippo hook install codex   (then trust the hooks once in /hooks)',
+    };
+}
 // Migration 46 creates failure_log; a read-only open no longer creates it on an older store.
 const FAILURE_LOG_SCHEMA = 46;
 /** The failed-tool-call count over the last 7 days, or why it could not be read. */
@@ -72,6 +97,36 @@ function sleepCheck(db, now) {
         return { id: 'sleep', status: 'info', detail: `sleep history unavailable (${message})` };
     }
 }
+/** Compaction records the PostCompact hook left unfinished, which `hippo sleep` replays. */
+function compactionsCheck(db, now) {
+    const stuckBefore = new Date(now.getTime() - REPLAY_AFTER_MS).toISOString();
+    const transcriptFloor = new Date(now.getTime() - TRANSCRIPT_FILL_WINDOW_MS).toISOString();
+    try {
+        // SAFETY: COUNT aggregate row.
+        const row = db.prepare(`SELECT COUNT(*) AS total,
+              COUNT(CASE WHEN status = 'summarised' AND summarised_at < ? THEN 1 END) AS summarised,
+              COUNT(CASE WHEN status = 'started' AND started_at < ? AND started_at > ? AND transcript_path IS NOT NULL THEN 1 END) AS started
+       FROM compactions`).get(stuckBefore, stuckBefore, transcriptFloor);
+        const total = Number(row?.total ?? 0);
+        const summarised = Number(row?.summarised ?? 0);
+        const started = Number(row?.started ?? 0);
+        const stuck = summarised + started;
+        if (stuck === 0)
+            return { id: 'compactions', status: 'pass', detail: `${total} compaction${total === 1 ? '' : 's'} recorded, none stuck` };
+        return {
+            id: 'compactions',
+            status: 'warn',
+            detail: `${stuck} compaction${stuck === 1 ? '' : 's'} unfinished after 10 minutes (${summarised} with a summary whose memories are not saved yet, ${started} with no summary yet)`,
+            fix: 'hippo sleep   (replays them)',
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return message.includes('no such table')
+            ? { id: 'compactions', status: 'info', detail: 'no compaction records yet (hippo creates them on the next write)' }
+            : { id: 'compactions', status: 'warn', detail: `cannot read the compaction records: ${message}` };
+    }
+}
 /** Run every check. Never throws for a broken install; broken parts become failed checks. */
 export function runDoctor(opts) {
     const cwd = opts.cwd ?? process.cwd();
@@ -123,14 +178,22 @@ export function runDoctor(opts) {
             const since = new Date(now.getTime() - 7 * 86_400_000).toISOString();
             try {
                 // SAFETY: COUNT/SUM aggregate row.
-                const row = db.prepare(`SELECT COUNT(*) AS n, COALESCE(SUM(tokens), 0) AS t FROM token_ledger WHERE ts >= ? AND event = 'inject'`).get(since);
-                checks.push({ id: 'tokens', status: 'info', detail: `${Number(row?.n ?? 0)} memory blocks sent to agents in 7 days, about ${Number(row?.t ?? 0)} tokens (hippo tokens for detail)` });
+                const row = db.prepare(`SELECT COUNT(CASE WHEN event = 'inject' THEN 1 END) AS n,
+                  COALESCE(SUM(CASE WHEN event = 'inject' THEN tokens END), 0) AS t,
+                  COALESCE(SUM(CASE WHEN event = 'reread' THEN tokens END), 0) AS r
+           FROM token_ledger WHERE ts >= ?`).get(since);
+                checks.push({
+                    id: 'tokens',
+                    status: 'info',
+                    detail: `${Number(row?.n ?? 0)} memory blocks sent to agents in 7 days, about ${Number(row?.t ?? 0)} tokens sent and ${Number(row?.r ?? 0)} re-read by later model calls (hippo tokens for detail)`,
+                });
             }
             catch {
                 checks.push({ id: 'tokens', status: 'info', detail: 'no token ledger yet (created on the next write)' });
             }
             checks.push(failuresCheck(db, since, have));
             checks.push(sleepCheck(db, now));
+            checks.push(compactionsCheck(db, now));
         }
         catch (err) {
             checks.push({
@@ -154,9 +217,9 @@ export function runDoctor(opts) {
         const hooks = [
             ['hippo context --pinned-only', 'per-prompt memory'],
             ['hippo session-end', 'session-end capture and sleep'],
-            ['hippo pre-compact', 'compaction snapshot and capture'],
+            ['hippo pre-compact', 'compaction snapshot and memories request'],
             ['hippo compact-resume', 'resume after compaction'],
-            ['hippo post-compact', 'the message after compaction'],
+            ['hippo post-compact', 'saving the memories a compaction lists'],
             ['hippo capture-error', 'failed-tool capture'],
         ];
         const missing = hooks.filter(([marker]) => !text.includes(marker)).map(([, what]) => what);
@@ -176,6 +239,8 @@ export function runDoctor(opts) {
     else {
         checks.push({ id: 'claude-code', status: 'info', detail: 'Claude Code not found; other agents can use hippo over MCP (hippo mcp)' });
     }
+    if (isCodexPresent(home))
+        checks.push(codexCheck(home));
     checks.push({ id: 'embeddings', status: 'info', detail: isEmbeddingAvailable() ? 'local embeddings available (hybrid search)' : 'embeddings not installed; recall uses BM25 (optional: hippo embed --help)' });
     return { ok: !checks.some((c) => c.status === 'fail'), version: opts.version, store, checks };
 }

package/dist/dormant.d.ts

@@ -19,8 +19,8 @@
  */
 import type { DatabaseSyncLike } from './db.js';
 import type { MemoryEntry } from './memory.js';
-/** Why sleep made a memory dormant. Only the decay pass does today. */
-export type DormantReason = 'decay';
+/** Why a memory went dormant: sleep's decay pass, or an imported agent memory whose note was deleted. */
+export type DormantReason = 'decay' | 'source-deleted';
 /** One memory that sleep is moving out of active memory into the dormant store. */
 export interface DormantMove {
     /** The memory as it stood when it faded; restored verbatim apart from its recall clock. */
@@ -39,7 +39,7 @@ export interface DormantMemory {
     tags: string[];
     /** Live strength when it went dormant. */
     strength: number;
-    /** Why it went dormant (`decay`). */
+    /** Why it went dormant (`decay` or `source-deleted`). */
     reason: string;
     /** ISO time it went dormant. */
     dormantAt: string;
@@ -71,6 +71,12 @@ export interface DormantSnapshot {
  * has no dormant memory with that id (another tenant's id reads as absent).
  */
 export declare function readDormantSnapshot(db: DatabaseSyncLike, tenantId: string, id: string): DormantSnapshot | null;
+/** Every dormant memory of a tenant whose snapshot still reads back. */
+export declare function listDormantSnapshots(db: DatabaseSyncLike, tenantId: string): DormantSnapshot[];
+/** Readable snapshots whose entry's source starts with `prefix`; a malformed snapshot is passed over, not an error. */
+export declare function dormantSnapshotsBySourcePrefix(db: DatabaseSyncLike, tenantId: string, prefix: string): DormantSnapshot[];
+/** Put `entry` in place of a tenant's dormant memory `id`, keeping when and why that one went dormant. */
+export declare function replaceDormantEntry(db: DatabaseSyncLike, tenantId: string, id: string, entry: MemoryEntry): void;
 /** Whether a tenant has a dormant memory with this id (snapshot readable or not). */
 export declare function hasDormantRow(db: DatabaseSyncLike, tenantId: string, id: string): boolean;
 /** Delete a tenant's dormant memory. Returns false when there was none. */

package/dist/dormant.js

@@ -74,8 +74,32 @@ export function readDormantSnapshot(db, tenantId, id) {
     // SAFETY: row's shape matches the seven columns named in the SELECT.
     const row = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
        FROM dormant_memories WHERE tenant_id = ? AND id = ?`).get(tenantId, id);
-    const entry = row ? parseSnapshot(row) : null;
-    return row && entry ? { entry, reason: row.reason, strength: row.strength, dormantAt: row.dormant_at } : null;
+    return row ? toSnapshot(row) : null;
+}
+/** Every dormant memory of a tenant whose snapshot still reads back. */
+export function listDormantSnapshots(db, tenantId) {
+    // SAFETY: rows' shape matches the seven columns named in the SELECT.
+    const rows = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
+       FROM dormant_memories WHERE tenant_id = ?`).all(tenantId);
+    return rows.flatMap((row) => toSnapshot(row) ?? []);
+}
+/** Readable snapshots whose entry's source starts with `prefix`; a malformed snapshot is passed over, not an error. */
+export function dormantSnapshotsBySourcePrefix(db, tenantId, prefix) {
+    // SAFETY: rows' shape matches the seven columns named in the SELECT.
+    const rows = db.prepare(`SELECT tenant_id, id, content, entry_json, reason, strength, dormant_at
+       FROM dormant_memories
+      WHERE tenant_id = ?
+        AND CASE WHEN json_valid(entry_json) THEN json_extract(entry_json, '$.source') END LIKE ? ESCAPE '\\'`).all(tenantId, `${escapeLike(prefix)}%`);
+    return rows.flatMap((row) => toSnapshot(row) ?? []).filter((s) => String(s.entry.source).startsWith(prefix));
+}
+function toSnapshot(row) {
+    const entry = parseSnapshot(row);
+    return entry ? { entry, reason: row.reason, strength: row.strength, dormantAt: row.dormant_at } : null;
+}
+/** Put `entry` in place of a tenant's dormant memory `id`, keeping when and why that one went dormant. */
+export function replaceDormantEntry(db, tenantId, id, entry) {
+    db.prepare(`UPDATE dormant_memories SET id = ?, content = ?, entry_json = ? WHERE tenant_id = ? AND id = ?`)
+        .run(entry.id, entry.content, JSON.stringify(entry), tenantId, id);
 }
 /** Whether a tenant has a dormant memory with this id (snapshot readable or not). */
 export function hasDormantRow(db, tenantId, id) {

package/dist/embedding-provider.d.ts

@@ -19,7 +19,8 @@
  *   - API provider `id` is `${kind}:${model}`; switching to/from an API embedder
  *     (or a dimension change) flips the identity and triggers the existing
  *     reindex-on-change path.
- *   - `resolveEmbeddingProvider` NEVER throws. `isAvailable()` is provider-aware
+ *   - `resolveEmbeddingProvider` throws on an invalid config (unknown provider,
+ *     bad apiBaseUrl); `embedMemory` turns that into a warning. `isAvailable()` is provider-aware
  *     (local -> dependency installed; api -> key present). `embed()` MAY throw on
  *     a hard transport/auth failure so a reindex can abort atomically; hot paths
  *     wrap it and fall back to BM25.

package/dist/embedding-provider.js

@@ -19,7 +19,8 @@
  *   - API provider `id` is `${kind}:${model}`; switching to/from an API embedder
  *     (or a dimension change) flips the identity and triggers the existing
  *     reindex-on-change path.
- *   - `resolveEmbeddingProvider` NEVER throws. `isAvailable()` is provider-aware
+ *   - `resolveEmbeddingProvider` throws on an invalid config (unknown provider,
+ *     bad apiBaseUrl); `embedMemory` turns that into a warning. `isAvailable()` is provider-aware
  *     (local -> dependency installed; api -> key present). `embed()` MAY throw on
  *     a hard transport/auth failure so a reindex can abort atomically; hot paths
  *     wrap it and fall back to BM25.

package/dist/embeddings.js

@@ -12,6 +12,7 @@ import { openHippoDb, closeHippoDb, getMeta, setMeta } from './db.js';
 import { initializeParticle, savePhysicsState, loadPhysicsState, resetAllPhysicsState } from './physics-state.js';
 import { loadConfig } from './config.js';
 import { resolveEmbeddingProvider } from './embedding-provider.js';
+import { redactSecretsStrict } from './secret-detect.js';
 // Use createRequire for synchronous module resolution check in ESM
 const _require = createRequire(import.meta.url);
 // Cached availability check
@@ -460,11 +461,29 @@ async function withEmbedLock(hippoRoot, fn) {
         resolve();
     }
 }
+// A bad key fails every write; one warning tells the user, N would bury the command's own output.
+let _embedFailureWarned = false;
+function warnEmbedFailureOnce(source, rawMessage) {
+    if (_embedFailureWarned)
+        return;
+    _embedFailureWarned = true;
+    // Strict scrub: this line can land in a hook log file, and an API may echo the key back in its error body.
+    const message = redactSecretsStrict(rawMessage).replace(/\s+/g, ' ').replace(/\.+$/, '');
+    console.error(`hippo: embedding failed (${source}): ${message}. Memories are stored without embeddings until this is fixed.`);
+}
 /**
  * Embed a single memory entry and cache the result in the embedding index.
  */
 export async function embedMemory(hippoRoot, entry, model) {
-    const provider = resolveEmbeddingProvider(hippoRoot, { model });
+    let provider;
+    try {
+        provider = resolveEmbeddingProvider(hippoRoot, { model });
+    }
+    catch (err) {
+        // Callers fire and forget, so this must resolve: a bad config warns once instead of rejecting.
+        warnEmbedFailureOnce('config', err instanceof Error ? err.message : String(err));
+        return;
+    }
     if (!provider.isAvailable())
         return;
     return withEmbedLock(hippoRoot, async () => {
@@ -513,8 +532,9 @@ export async function embedMemory(hippoRoot, entry, model) {
                 // Physics init is best-effort — don't break embedding
             }
         }
-        catch {
-            // Provider failure (API down / bad key). Best-effort: leave the index as-is.
+        catch (err) {
+            // Provider failure (API down / bad key). Best-effort: leave the index as-is, but say so once.
+            warnEmbedFailureOnce(provider.kind, err instanceof Error ? err.message : String(err));
         }
     }).catch((err) => {
         console.error(`hippo: skipped embedding ${entry.id} (${err instanceof Error ? err.message : String(err)}); run 'hippo embed' to backfill`);

package/dist/extract.js

@@ -3,6 +3,7 @@ import { writeEntry } from './store.js';
 import { loadConfig } from './config.js';
 import { RejectedValueError } from './rejection.js';
 import { redactSecrets } from './secret-detect.js';
+import { neverAutoShareTags } from './shared.js';
 function isJsonString(value) {
     return typeof value === 'string';
 }
@@ -81,7 +82,10 @@ export async function extractFacts(text, opts) {
 }
 const INHERITABLE_PREFIXES = ['conv:', 'session:', 'scope:', 'path:'];
 export function storeExtractedFacts(hippoRoot, source, facts) {
-    const inheritedTags = source.tags.filter((t) => INHERITABLE_PREFIXES.some((p) => t.startsWith(p)));
+    const inheritedTags = [
+        ...source.tags.filter((t) => INHERITABLE_PREFIXES.some((p) => t.startsWith(p))),
+        ...neverAutoShareTags([source]),
+    ];
     const entries = [];
     let rejected = 0;
     const baseHalfLifeDays = loadConfig(hippoRoot).defaultHalfLifeDays;

package/dist/forward-claim-detector.d.ts

@@ -11,7 +11,7 @@
  * Kahneman 2003 inside-vs-outside view).
  *
  * Iteration signal: the `recall_autodebias_hint_no_class_match` audit op
- * (emitted by computePlanningFallacyHint when a phrase matches but no class
+ * (emitted by computePlanningFallacyOutput when a phrase matches but no class
  * resolves) is the telemetry channel for deciding whether to add an
  * embedding-based detector in J3.3.
  *

package/dist/forward-claim-detector.js

@@ -11,7 +11,7 @@
  * Kahneman 2003 inside-vs-outside view).
  *
  * Iteration signal: the `recall_autodebias_hint_no_class_match` audit op
- * (emitted by computePlanningFallacyHint when a phrase matches but no class
+ * (emitted by computePlanningFallacyOutput when a phrase matches but no class
  * resolves) is the telemetry channel for deciding whether to add an
  * embedding-based detector in J3.3.
  *

package/dist/gated-write.d.ts

@@ -0,0 +1,9 @@
+import type { DatabaseSyncLike } from './db.js';
+import type { MemoryEntry } from './memory.js';
+export type GatedWriteResult = 'written' | 'skipped:not-worth-storing' | 'skipped:secret' | 'skipped:rejected';
+/** Runs on the caller's handle so it nests in the caller's transaction (writeEntry would open a second handle and wait on that lock); the caller mirrors after commit with an entry it stamped itself. The rejection audit lands inside that transaction, which is safe because a batch that rolls back stays `summarised` and replay writes the audit again. */
+export declare function gatedWrite(db: DatabaseSyncLike, hippoRoot: string, entry: MemoryEntry, opts?: {
+    actor?: string;
+    worthCheck?: boolean;
+}): GatedWriteResult;
+//# sourceMappingURL=gated-write.d.ts.map

package/dist/gated-write.js

@@ -0,0 +1,24 @@
+// The one write path for text no person typed into hippo: capture, compaction items and imported agent memories.
+import { isContentWorthStoring } from './audit.js';
+import { RejectedValueError } from './rejection.js';
+import { detectSecret } from './secret-detect.js';
+import { auditRejectionRefusal, stampOriginProject, writeEntryDbOnly } from './store.js';
+/** Runs on the caller's handle so it nests in the caller's transaction (writeEntry would open a second handle and wait on that lock); the caller mirrors after commit with an entry it stamped itself. The rejection audit lands inside that transaction, which is safe because a batch that rolls back stays `summarised` and replay writes the audit again. */
+export function gatedWrite(db, hippoRoot, entry, opts) {
+    // Off for imported agent memories: a person wrote those notes, and a one-line preference fails the check.
+    if (opts?.worthCheck !== false && !isContentWorthStoring(entry.content))
+        return 'skipped:not-worth-storing';
+    if (detectSecret(entry).flagged)
+        return 'skipped:secret';
+    try {
+        writeEntryDbOnly(db, stampOriginProject(hippoRoot, entry), opts);
+        return 'written';
+    }
+    catch (err) {
+        if (!(err instanceof RejectedValueError))
+            throw err;
+        auditRejectionRefusal(db, err, opts?.actor ?? 'cli');
+        return 'skipped:rejected';
+    }
+}
+//# sourceMappingURL=gated-write.js.map

package/dist/graph-recall.d.ts

@@ -1,4 +1,4 @@
-import { type SearchResult } from './search.js';
+import { type ResultCost, type SearchResult } from './search.js';
 /** Hard cap on `--hops` (a higher value just walks more of a finite graph; this bounds
  *  worst-case work and keeps the flag honest). */
 export declare const MAX_HOPS = 3;
@@ -23,6 +23,8 @@ export interface GraphExpandOpts {
     asOf?: string;
     /** Token budget for the augmented set (defaults to 4000, matching recall's default). */
     budget?: number;
+    /** Budget cost per result; defaults to the memory text. */
+    cost?: ResultCost;
     /** The recall --min-results floor: this many top base rows are kept regardless of
      *  budget, so graph expansion never violates the floor. Defaults to 1. */
     minResults?: number;

package/dist/graph-recall.js

@@ -247,15 +247,17 @@ export function graphExpandRecall(baseResults, opts) {
     // baseResults is score-ordered, so slice(0, N) is the top N.
     const protectedCount = Math.min(Math.max(minResults, 1), baseResults.length);
     const keep = new Set(baseResults.slice(0, protectedCount));
-    let usedTokens = [...keep].reduce((s, r) => s + r.tokens, 0);
+    const price = opts.cost ?? ((r) => r.tokens);
+    let usedTokens = [...keep].reduce((s, r) => s + price(r), 0);
     // T2 note: PLAIN stable score sort on purpose -- both input lists are
     // deterministically ordered by this point, stability inherits that, and a
     // base-vs-graph-hit tie keeps the BASE result first (the concat order),
     // preserving pre-T2 semantics.
     for (const r of [...baseResults.slice(protectedCount), ...allHits].sort((a, b) => b.score - a.score)) {
-        if (usedTokens + r.tokens > budget)
+        const tokens = price(r);
+        if (usedTokens + tokens > budget)
             continue;
-        usedTokens += r.tokens;
+        usedTokens += tokens;
         keep.add(r);
     }
     // DISPLAY order: base order preserved (it may be MMR-diversified); each kept new hit

package/dist/hooks.d.ts

@@ -16,6 +16,10 @@
  *      - < 0.20.2: `Stop` hook firing `hippo sleep` on every assistant turn.
  *      - < 0.21.0: bare `hippo sleep` in SessionEnd, no `--log-file`.
  *      - 0.22.x: separate sleep + capture SessionEnd entries.
+ *    PreCompact and PostCompact entries go in too: the first records the compaction and
+ *    asks the summariser for a "Memories for hippo" list, the second saves that list.
+ *    Codex's hooks.json gets only two groups (per-prompt memory and
+ *    compact-resume); see installCodexHooks.
  *
  * 2. Plugin install (OpenCode only). OpenCode does NOT share Claude Code's
  *    JSON-hook schema — its config has `additionalProperties: false` and no
@@ -28,7 +32,11 @@
  *    the installer + the migration that removes any pre-existing broken
  *    `hooks` block from opencode.json.
  */
-export type JsonHookTarget = 'claude-code';
+import type { JsonValue, JsonObject } from './working-memory.js';
+/** JSON-value plain-object check (excludes arrays and null), typeof-free for the same
+ *  reason as isJsonString above. */
+export declare function isJsonObject(value: JsonValue | undefined): value is JsonObject;
+export type JsonHookTarget = 'claude-code' | 'codex';
 export interface CodexWrapperPaths {
     wrapperDir: string;
     metadataPath: string;
@@ -85,7 +93,7 @@ export interface InstallResult {
     installedUserPromptSubmit: boolean;
     installedPreCompact: boolean;
     installedCompactResume: boolean;
-    /** PostCompact -> `hippo post-compact` (tells the user what compaction saved). */
+    /** PostCompact -> `hippo post-compact` (saves the summary's memories, tells the user how many). */
     installedPostCompact: boolean;
     /** PostToolUseFailure -> `hippo capture-error` (failed tool calls become error memories). */
     installedCaptureError: boolean;
@@ -93,6 +101,8 @@ export interface InstallResult {
     migratedFromStop: boolean;
     migratedLegacySessionEnd: boolean;
     migratedSplitSessionEnd: boolean;
+    /** The file exists but is not JSON hippo can merge into, so it was left untouched. */
+    invalidJson: boolean;
 }
 export interface ToolDetection {
     name: string;
@@ -141,6 +151,12 @@ declare const HIPPO_OPENCODE_PLUGIN_MARKER = "HIPPO_OPENCODE_PLUGIN_V1";
  */
 export declare const OPENCODE_PLUGIN_SOURCE = "// HIPPO_OPENCODE_PLUGIN_V1\n// hippo-memory opencode plugin. DO NOT EDIT \u2014 regenerated on every\n// `hippo hook install opencode` from src/hooks.ts OPENCODE_PLUGIN_SOURCE\n// in https://github.com/kitfunso/hippo-memory. Local changes will be lost.\n\nexport const HippoPlugin = async ({ $ }) => {\n  return {\n    event: async ({ event }) => {\n      // Defense in depth: opencode currently runs in Bun where $ is the shell\n      // template helper. A non-Bun runtime would have $ as undefined; fail\n      // closed instead of crashing the host session.\n      if (typeof $ !== \"function\") return;\n      try {\n        if (event.type === \"session.idle\") {\n          await $`hippo session-end`.quiet().nothrow();\n        } else if (event.type === \"session.created\") {\n          await $`hippo last-sleep`.quiet().nothrow();\n        }\n      } catch {\n        // hippo CLI not on PATH or other failure \u2014 never crash the host session.\n      }\n    },\n  };\n};\n";
 export { HIPPO_OPENCODE_PLUGIN_MARKER };
+/** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
+export declare function codexHomeDir(home?: string, env?: Readonly<Record<string, string | undefined>>): string;
+/** Codex counts as installed only when its config folder exists: Codex itself refuses a CODEX_HOME that is not a folder. */
+export declare function isCodexPresent(home?: string): boolean;
+/** Codex hashes each hook and skips new or changed ones until the user reviews them in `/hooks`, so the reminder says what they would trust. */
+export declare const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus the five most recent ones. Codex runs hippo's hooks only after you trust them once in `/hooks`.";
 /**
  * Default log path consumed by `hippo last-sleep`. Shared fallback when
  * a caller doesn't pass --path explicitly.