hippo-memory 1.51.0 → 1.52.1

package/README.md

@@ -724,9 +724,9 @@ For Claude Code, it also adds:
 - a `SessionEnd` hook so `hippo sleep` runs automatically when the session exits
 - a `SessionStart` hook that prints the previous session's consolidation output
 - a `UserPromptSubmit` hook that runs `hippo context --pinned-only --include-recent 5 --format additional-context` every turn. It re-injects pinned memories (`hippo remember <text> --pin`) plus the last 5 writes, so fresh same-session lessons appear on the next prompt before you pin them. The block is rendered without live strength percentages, so it stays byte-identical while its memories do not change, and it is sent only when it changed since the session's last prompt: an unchanged block is skipped, resent every 10 skips (`pinnedInject.refreshTurns`, `0` never resends) and resent after compaction. `{"pinnedInject":{"skipUnchanged":false}}` sends it every turn as before. Opt out entirely with `{"pinnedInject":{"enabled":false}}` in `.hippo/config.json`.
-- a `PreCompact` hook that runs `hippo pre-compact` before the transcript gets summarized. It saves a working-state snapshot (task/summary/next step) and extracts durable memories from the tail, so mid-session compaction can't drop them.
+- a `PreCompact` hook that runs `hippo pre-compact` before the transcript gets summarized. It saves a working-state snapshot (task/summary/next step) so mid-session compaction can't drop it; the `SessionEnd` hook still owns extracting durable memories.
 - a second `SessionStart` hook (matcher `compact`) that runs `hippo compact-resume`, printing that snapshot plus the recent session trail back into context right after compaction.
-- a `PostCompact` hook that runs `hippo post-compact`, which tells you what was saved ("Hippo saved your task snapshot and 2 new memories before compacting"). It prints nothing when nothing was saved.
+- a `PostCompact` hook that runs `hippo post-compact`, which tells you what was saved ("Hippo saved your task snapshot before compacting."). It prints nothing when nothing was saved.
 - a `PostToolUseFailure` hook that runs `hippo capture-error`, which stores a failed tool call as an error memory. It skips interrupts, declined permissions and searches that found nothing, and stores a repeated failure once. It also logs every failure, stored or not, for `hippo failures`: the session, the tool and hashes of the error, never its text. A hash is not anonymous, since anyone who guesses an error's text can check it against the hash. The log keeps 90 days.
 
 To remove: `hippo hook uninstall claude-code`

package/dist/api.d.ts

@@ -952,6 +952,8 @@ export interface ContextOpts {
      *  it just means every snapshot goes through the age check. Host-resolved
      *  (stdin payload, HIPPO_SESSION_ID, else the host's session var) so this stays host-agnostic. */
     currentSessionId?: string | null;
+    /** Z1: raw hook-payload prompt; only the pinned-only branch reads it, gated on `pinnedInject.promptRecall`. */
+    prompt?: string;
 }
 export interface ContextResultEntry {
     entry: MemoryEntry;
@@ -959,6 +961,8 @@ export interface ContextResultEntry {
     tokens: number;
     isGlobal?: boolean;
     isFreshTail?: boolean;
+    /** Z1: admitted by the prompt-recall gate, not the recent-N backfill or a pin. */
+    promptRecall?: boolean;
     /** v39: the entry's owning project ('' = user-global, null = legacy row). */
     origin?: string | null;
     /** v39: how the origin relates to the active project. 'cross-project'

package/dist/api.js

@@ -8,7 +8,7 @@
  */
 import { createHash } from 'node:crypto';
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry, writeEntryDbOnly, strengthenRetrieved, stampOriginProject, writeEntryMirrors, readEntry, deleteEntry, loadRecallSearchEntries, loadEntriesByIds, loadChildrenOf, loadFreshRawMemories, loadSessionRawMemories, countSessionRawMemories, DEFAULT_SEARCH_CANDIDATE_LIMIT, removeEntryMirrors, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, loadLatestHandoff, listSessionEvents, SNAPSHOT_AMBIENT_MAX_AGE_MS, loadIndex, saveIndex, loadAllEntries, loadAmbientCandidates, updateStats, isInitialized, markSummaryDirtyInTx, auditRejectionRefusal, } from './store.js';
+import { writeEntry, writeEntryDbOnly, strengthenRetrieved, stampOriginProject, writeEntryMirrors, readEntry, deleteEntry, loadRecallSearchEntries, loadRecallSearchEntriesFromDb, pickRarestFtsQuery, loadEntriesByIds, loadChildrenOf, loadFreshRawMemories, loadSessionRawMemories, countSessionRawMemories, DEFAULT_SEARCH_CANDIDATE_LIMIT, removeEntryMirrors, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, loadLatestHandoff, listSessionEvents, SNAPSHOT_AMBIENT_MAX_AGE_MS, loadIndex, saveIndex, loadAllEntries, loadAmbientCandidates, updateStats, isInitialized, markSummaryDirtyInTx, auditRejectionRefusal, } from './store.js';
 import { RejectedValueError } from './rejection.js';
 import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
 import { listDormantRows, readDormantSnapshot, deleteDormantRow, hasDormantRow, } from './dormant.js';
@@ -30,7 +30,8 @@ import { compareEntryIdentity, compareScoredResults } from './compare.js';
 import { scopeMatch } from './scope.js';
 import { consolidate } from './consolidate.js';
 import { loadConfig } from './config.js';
-import { resolveProjectIdentity, classifyOriginProject } from './project-identity.js';
+import { resolveProjectIdentity, classifyOriginProject, isGlobalStoreRoot } from './project-identity.js';
+import { promptTokens, contentTokens, gatePromptRecall, } from './prompt-recall.js';
 import { detectSecret } from './secret-detect.js';
 import { deduplicateStore } from './dedupe.js';
 import { computeAmbientState } from './ambient.js';
@@ -1587,7 +1588,10 @@ export async function getContext(ctx, opts = {}) {
             limit: 5,
         }).filter((e) => passesScopeFilterForRecall(rowScope(e), undefined))
         : [];
-    if (localEntries.length === 0 &&
+    const promptRecallPending = pinnedOnly && Boolean(opts.prompt?.trim())
+        && loadConfig(ctx.hippoRoot).pinnedInject.promptRecall === true;
+    if (!promptRecallPending &&
+        localEntries.length === 0 &&
         globalEntries.length === 0 &&
         !activeSnapshot &&
         !sessionHandoff &&
@@ -1654,7 +1658,79 @@ export async function getContext(ctx, opts = {}) {
         // under-fills recents slightly -- it never displaces a pin -- so it is
         // the safe direction and is not worth extra bookkeeping to recover.
         const recentBudget = Math.max(0, effBudget - pinnedReserve);
-        if (includeRecent > 0) {
+        // Z1: gate the backfill on the prompt instead of recency (docs/plans/2026-09-26-z1-prompt-recall.md).
+        const promptRecallOn = Boolean(opts.prompt?.trim()) && pinnedCfg.pinnedInject.promptRecall === true;
+        if (promptRecallOn) {
+            const rawMetric = pinnedCfg.pinnedInject.promptRecallMetric;
+            const metric = rawMetric === 'cosine' ? 'cosine' : 'jaccard';
+            // Config values come from JSON with no runtime type check; Number.isFinite also rejects a string there.
+            const finiteOr = (v, dflt, min) => Number.isFinite(v) && v >= min ? v : dflt;
+            const gate = {
+                metric,
+                threshold: finiteOr(pinnedCfg.pinnedInject.promptRecallThreshold, 0.04, 0),
+                minShared: finiteOr(pinnedCfg.pinnedInject.promptRecallMinShared, 2, 0),
+                maxItems: finiteOr(pinnedCfg.pinnedInject.promptRecallMaxItems, 5, 1),
+            };
+            const candidateLimit = Math.floor(finiteOr(pinnedCfg.pinnedInject.promptRecallCandidates, 100, 1));
+            const p = promptTokens(opts.prompt ?? '');
+            if (p.size > 0) {
+                const promptTermList = Array.from(p);
+                // One open connection per store instead of loadRecallSearchEntries's own
+                // initStore+open/close per call: store is already initialized (hasLocal/hasGlobal).
+                let localCandidates = [];
+                if (hasLocal) {
+                    const localDb = openHippoDb(ctx.hippoRoot);
+                    try {
+                        const ftsQuery = pickRarestFtsQuery(localDb, promptTermList);
+                        // An empty query would load the oldest rows, not matches.
+                        if (ftsQuery)
+                            localCandidates = loadRecallSearchEntriesFromDb(localDb, ftsQuery, candidateLimit, ctx.tenantId, undefined, 'exact', false);
+                    }
+                    finally {
+                        closeHippoDb(localDb);
+                    }
+                }
+                let globalCandidates = [];
+                if (hasGlobal && !isGlobalStoreRoot(ctx.hippoRoot)) {
+                    const globalDb = openHippoDb(globalRoot);
+                    try {
+                        const ftsQuery = pickRarestFtsQuery(globalDb, promptTermList);
+                        if (ftsQuery)
+                            globalCandidates = loadRecallSearchEntriesFromDb(globalDb, ftsQuery, candidateLimit, ctx.tenantId, undefined, 'exact', false);
+                    }
+                    finally {
+                        closeHippoDb(globalDb);
+                    }
+                }
+                const seenCandidateIds = new Set();
+                const candidateItems = [];
+                // Local wins the id collision (a global row synced into the local store).
+                for (const e of localCandidates) {
+                    if (!admit(e) || e.pinned || !isContentWorthStoring(e.content) || seenCandidateIds.has(e.id))
+                        continue;
+                    seenCandidateIds.add(e.id);
+                    candidateItems.push({ id: e.id, tokens: contentTokens(e.content), entry: e, isGlobal: false });
+                }
+                for (const e of globalCandidates) {
+                    if (!admit(e) || e.pinned || !isContentWorthStoring(e.content) || seenCandidateIds.has(e.id))
+                        continue;
+                    seenCandidateIds.add(e.id);
+                    candidateItems.push({ id: e.id, tokens: contentTokens(e.content), entry: e, isGlobal: true });
+                }
+                const gated = gatePromptRecall(p, candidateItems, gate);
+                for (const g of gated) {
+                    if (selectedIds.has(g.item.id))
+                        continue;
+                    const tokens = estimateTokens(g.item.entry.content);
+                    if (usedP + tokens > recentBudget)
+                        continue;
+                    selectedItems.push({ entry: g.item.entry, score: g.score, tokens, isGlobal: g.item.isGlobal, promptRecall: true });
+                    selectedIds.add(g.item.id);
+                    usedP += tokens;
+                }
+            }
+        }
+        else if (includeRecent > 0) {
             const recent = [
                 ...localEntries.map((entry) => ({ entry, isGlobal: false })),
                 ...globalEntries.map((entry) => ({ entry, isGlobal: true })),

package/dist/audit.d.ts

@@ -13,6 +13,7 @@ export interface AuditResult {
     issues: AuditIssue[];
     clean: number;
 }
+export declare const STOP_WORDS: Set<string>;
 export declare function auditMemory(entry: MemoryEntry): AuditIssue | null;
 export declare function auditMemories(entries: MemoryEntry[]): AuditResult;
 export declare function isContentWorthStoring(content: string): boolean;

package/dist/audit.js

@@ -1,5 +1,5 @@
 import { canAutoDelete } from './memory.js';
-const STOP_WORDS = new Set([
+export const STOP_WORDS = new Set([
     'the', 'a', 'an', 'is', 'was', 'are', 'were', 'be', 'been', 'being',
     'to', 'of', 'in', 'for', 'on', 'with', 'at', 'by', 'from', 'it',
     'this', 'that', 'and', 'or', 'but', 'not', 'no', 'so', 'if', 'do',

package/dist/auth.d.ts

@@ -1,4 +1,5 @@
 import type { DatabaseSyncLike } from './db.js';
+export declare function _dummyHashForTests(): string;
 export interface CreateApiKeyOpts {
     tenantId: string;
     label?: string;

package/dist/auth.js

@@ -24,7 +24,12 @@ function hashKey(plaintext) {
 // rate limit on /v1/* to bound key-id enumeration. Stored format identical to
 // real hashes: scrypt$saltHex$hashHex.
 const DUMMY_PLAINTEXT = 'hk_dummy_constant_padding_for_timing.dummy_secret_padding_for_timing_x';
-const DUMMY_HASH = hashKey(DUMMY_PLAINTEXT);
+// Precomputed `hashKey(DUMMY_PLAINTEXT)`: computing it at module load put one scrypt on every CLI start.
+const DUMMY_HASH = 'scrypt$5b2117156f1ad78738fd8b6a5bace454$92e098fa28003b7c38ba8f1451bd8618260a4a3c5a64b87cc2b471567c0960e7';
+// Not a secret (it's padding, not a real key hash): exposed only so a test can pin its shape.
+export function _dummyHashForTests() {
+    return DUMMY_HASH;
+}
 function verifyKey(plaintext, stored) {
     const parts = stored.split('$');
     if (parts.length !== 3 || parts[0] !== 'scrypt')

package/dist/capture.d.ts

@@ -106,16 +106,11 @@ 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;
+/** 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`.

package/dist/capture.js

@@ -21,7 +21,6 @@ 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
@@ -469,62 +468,6 @@ function isDuplicate(content, existing) {
     }
     return false;
 }
-/**
- * Write already-extracted items to the store, deduped against existing
- * tenant-scoped entries. Shared write path for `cmdCapture` (extracted from
- * raw text inline) and `cmdPreCompact` (extracted from a pre-computed tail
- * summary, no raw-text re-extraction). Mirrors the non-dry-run write loop in
- * `cmdCaptureCore`: same layer/source/confidence, same embed-if-configured,
- * fire-and-forget behaviour.
- *
- * Returns the fire-and-forget `embedMemory` promises alongside the counts
- * (review round X6) so a caller that must not exit before embeddings settle
- * — `cmdPreCompact`, which runs process.exit(0) right after — can await them
- * with a bounded timeout instead of racing a detached write.
- */
-function writeExtractedItems(hippoRoot, tenantId, extracted) {
-    if (extracted.length === 0)
-        return { captured: 0, skipped: 0, rejected: 0, embeds: [] };
-    const existing = loadAllEntries(hippoRoot, tenantId);
-    const embeds = [];
-    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++;
-            continue;
-        }
-        const entry = createMemory(item.content, {
-            layer: Layer.Episodic,
-            tags: item.tags,
-            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.
-        try {
-            writeEntry(hippoRoot, entry);
-        }
-        catch (err) {
-            if (err instanceof RejectedValueError) {
-                rejected++;
-                continue;
-            }
-            throw err;
-        }
-        updateStats(hippoRoot, { remembered: 1 });
-        existing.push(entry); // within-batch dedup
-        if (isEmbeddingConfigured(hippoRoot)) {
-            embeds.push(embedMemory(hippoRoot, entry).catch(() => { }));
-        }
-        captured++;
-    }
-    return { captured, skipped, rejected, embeds };
-}
 /**
  * Runtime shape guards used throughout this file wherever a value arrives
  * unparsed (JSONL transcript records, stdout/stderr write() chunks). Generic
@@ -557,7 +500,7 @@ function errorMessage(cause) {
 /** 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)
+    if (entry.isMeta === true || entry.isSidechain === true || entry.isCompactSummary === true || entry.promptSource === 'system')
         return true;
     const head = content.trimStart();
     return CLAUDE_CODE_COMMAND_PREFIXES.some((p) => head.startsWith(p));
@@ -1121,20 +1064,11 @@ 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".
- */
+/** 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 && report.captured === 0)
+    if (!report.snapshotSaved)
         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.' : ''}`;
+    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
@@ -1143,24 +1077,20 @@ export function preCompactMessage(report) {
 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).
- */
+/** 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) {
     // 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).
     if (!isInitialized(hippoRoot)) {
         appendPreCompactLog(logFile, 'skip: store not initialized');
-        return [];
+        return;
     }
     // Same hazard X4 guards below, different trigger: a read that timed out
     // must not reach auto-discovery either, or it snapshots another session.
     if (stdinTimedOut && (!stdinText || stdinText.trim() === '')) {
         appendPreCompactLog(logFile, 'skip: no PreCompact payload arrived before the stdin wait window closed');
-        return [];
+        return;
     }
     // A true manual invocation has no stdin at all (TTY, or a non-TTY pipe
     // that yielded an empty read) — that's the ONLY case newest-transcript
@@ -1186,7 +1116,7 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile, report) {
             // `"transcript_path": null` (or the key missing entirely) — all fail
             // the string check. Log and skip; never fall through to auto-discovery.
             appendPreCompactLog(logFile, 'skip: malformed or incomplete PreCompact payload (missing string transcript_path)');
-            return [];
+            return;
         }
         if ('session_id' in payload && isStringValue(payload.session_id))
             sessionId = payload.session_id;
@@ -1202,7 +1132,7 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile, report) {
     // this check could gate on, so containment buys no real isolation.
     if (payloadTranscriptPath !== null && !/\.jsonl$/i.test(payloadTranscriptPath)) {
         appendPreCompactLog(logFile, `skip: payload transcript_path is not a .jsonl file: ${payloadTranscriptPath}`);
-        return [];
+        return;
     }
     // A payload transcript_path is EXCLUSIVE: never fall back to
     // newest-transcript auto-discovery when it's missing/unreadable. That
@@ -1217,7 +1147,7 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile, report) {
         }
         else {
             appendPreCompactLog(logFile, `skip: payload transcript_path unreadable: ${payloadTranscriptPath}`);
-            return [];
+            return;
         }
     }
     else {
@@ -1225,7 +1155,7 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile, report) {
     }
     if (!transcriptPath) {
         appendPreCompactLog(logFile, 'skip: no transcript resolved');
-        return [];
+        return;
     }
     let tail;
     try {
@@ -1248,22 +1178,18 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile, report) {
     }
     catch (err) {
         appendPreCompactLog(logFile, `skip: could not read transcript tail: ${errorMessage(err)}`);
-        return [];
+        return;
     }
     const summaryFull = summariseTranscript(tail);
-    // CX5 (codex round 2): extraction runs over REDACTED text — extracted
-    // items become durable memories and must never carry raw secrets any more
-    // than the snapshot fields may. (The pre-existing SessionEnd capture path
-    // is deliberately unchanged.)
+    // Snapshot fields must never carry raw secrets, same rule X9 applies below to task/next_step.
     const scrubbedSummary = redactSecrets(summaryFull);
-    const extracted = extractFromText(scrubbedSummary);
     const rawTask = lastPlainUserMessage(tail);
     const rawNextStep = lastAssistantTextBlock(tail);
-    // Full skip only when EVERY derived field is empty and nothing was
-    // extracted — never clobber a user-authored active snapshot with junk.
-    if (!rawTask.trim() && !summaryFull.trim() && !rawNextStep.trim() && extracted.length === 0) {
-        appendPreCompactLog(logFile, 'skip: empty summary and no extracted items');
-        return [];
+    // Full skip only when every derived field is empty: never clobber a
+    // user-authored active snapshot with junk.
+    if (!rawTask.trim() && !summaryFull.trim() && !rawNextStep.trim()) {
+        appendPreCompactLog(logFile, 'skip: empty summary');
+        return;
     }
     const tenantId = resolveTenantId({});
     // Per-field merge (X1): a tool-heavy tail whose only user turns are
@@ -1309,10 +1235,8 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile, report) {
     const nextStep = scrubbedNextStep.trim()
         ? truncateCodePointSafe(scrubbedNextStep, PRE_COMPACT_NEXT_STEP_CAP)
         : (fallback?.next_step ?? '');
-    // Snapshot writes FIRST: a capture-extraction failure below must never
-    // lose the headline artifact. The reverse order would risk it. All-empty
-    // fields (cross-session tail with nothing derivable) skip the write so a
-    // foreign session's junk never displaces the owning session's snapshot.
+    // All-empty fields (cross-session tail with nothing derivable) skip the
+    // write so a foreign session's junk never displaces the owning snapshot.
     if (!task && !summary && !nextStep) {
         appendPreCompactLog(logFile, 'skip: no snapshot content for this session (nothing derivable; fallback blocked or empty)');
     }
@@ -1332,25 +1256,7 @@ function runPreCompact(hippoRoot, stdinText, stdinTimedOut, logFile, report) {
             appendPreCompactLog(logFile, `snapshot save failed: ${errorMessage(err)}`);
         }
     }
-    // Capture extraction SECOND, own try/catch: a failure here self-heals at
-    // 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;
-    }
-    catch (err) {
-        appendPreCompactLog(logFile, `capture failed: ${errorMessage(err)}`);
-        return [];
-    }
 }
-// X6: bound how long cmdPreCompact will wait for fire-and-forget embeddings
-// to settle before it exits. PreCompact runs under a hook timeout (30s in
-// the installer) — 3s leaves ample headroom while still giving embeddings a
-// real chance to finish instead of racing process.exit(0) unconditionally.
-const EMBED_SETTLE_TIMEOUT_MS = 3000;
 /**
  * PreCompact hook entry point. Exit code 2 on PreCompact BLOCKS compaction,
  * so this verb must exit 0 on every path — malformed stdin, missing
@@ -1360,29 +1266,17 @@ 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 };
+    const report = { snapshotSaved: false, sessionId: null };
     try {
-        embeds = runPreCompact(hippoRoot, options.stdinText, options.stdinTimedOut ?? false, logFile, report);
+        runPreCompact(hippoRoot, options.stdinText, options.stdinTimedOut ?? false, logFile, report);
     }
     catch (err) {
         appendPreCompactLog(logFile, `pre-compact failed: ${errorMessage(err)}`);
     }
-    if (embeds.length > 0) {
-        let timer;
-        const timeout = new Promise((resolve) => {
-            timer = setTimeout(() => resolve('timeout'), EMBED_SETTLE_TIMEOUT_MS);
-            timer.unref?.();
-        });
-        const settled = Promise.allSettled(embeds).then(() => 'settled');
-        const outcome = await Promise.race([settled, timeout]);
-        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) {
+    if (report.snapshotSaved) {
         try {
             fs.writeFileSync(preCompactReportPath(logFile), JSON.stringify({ ...report, at: new Date().toISOString() }));
         }
@@ -1431,7 +1325,6 @@ export function postCompactMessage(stdinText, logFile = defaultPreCompactLogPath
             return null;
         return preCompactMessage({
             snapshotSaved: 'snapshotSaved' in report && report.snapshotSaved === true,
-            captured: 'captured' in report && Number.isInteger(report.captured) ? Number(report.captured) : 0,
         });
     }
     catch {

package/dist/cli.d.ts

@@ -63,6 +63,7 @@ export declare function printContextMarkdown(items: Array<{
     isGlobal: boolean;
 }>, totalTokens: number, framing?: string, opts?: {
     showStrength?: boolean;
+    heading?: string;
 }): void;
 export declare function runCli(argv?: string[]): Promise<void>;
 //# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -41,7 +41,7 @@ import { execFileSync, execSync, spawn } from 'child_process';
 import { installJsonHooks, uninstallJsonHooks, resolveJsonHookPaths, detectInstalledTools, defaultSleepLogPath, ensureCodexWrapperInstalled, installCodexWrapper, isCodexWrapperInstalled, repairCodexWrapperIfInstalled, uninstallCodexWrapper, resolveCodexSessionTranscript, resolveCodexWrapperPaths, installOpencodePlugin, uninstallOpencodePlugin, resolveOpencodePluginPath, } from './hooks.js';
 import { createMemory, calculateStrength, calculateRewardFactor, deriveHalfLife, resolveConfidence, confidenceFacets, confidenceLabel, computeSchemaFit, Layer, } from './memory.js';
 import { detectSecret } from './secret-detect.js';
-import { getHippoRoot, isInitialized, initStore, writeEntry, strengthenRetrieved, readEntry, deleteEntry, loadAllEntries, loadSearchEntries, loadRecallSearchEntries, loadIndex, saveIndex, loadStats, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, createCard, loadCard, listCards, loadCardRuns, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, } from './store.js';
+import { getHippoRoot, isInitialized, initStore, writeEntry, strengthenRetrieved, readEntry, deleteEntry, loadAllEntries, loadSearchEntries, loadRecallSearchEntries, loadIndex, saveIndex, loadStats, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, createCard, loadCard, listCards, loadCardRuns, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, } from './store.js';
 import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
 import { RejectedValueError } from './rejection.js';
 import { isHandoffOutcome, formatHandoffEvidenceLine } from './handoff.js';
@@ -2935,6 +2935,8 @@ function cmdLastSleep(flags) {
 // X8: session-event content is capped at print time only — the shared
 // printSessionEvents stays untouched for every other caller.
 const COMPACT_RESUME_EVENT_CONTENT_CAP = 400;
+// A snapshot older than this was not written for this compaction (pre-compact skipped), so restoring it is stale, not a resume.
+const COMPACT_RESUME_MAX_AGE_MS = 15 * 60_000;
 function cmdCompactResume(hippoRoot, stdinText, stdinTimedOut) {
     try {
         // X3: gate on the non-exiting isInitialized check before any
@@ -2985,7 +2987,7 @@ function cmdCompactResume(hippoRoot, stdinText, stdinTimedOut) {
         }
         if (!suppressOutput) {
             const tenantId = resolveTenantId({});
-            const snapshot = loadActiveTaskSnapshot(hippoRoot, tenantId);
+            const snapshot = loadFreshActiveTaskSnapshot(hippoRoot, tenantId, { maxAgeMs: COMPACT_RESUME_MAX_AGE_MS });
             // X5: concurrent sessions must not cross-restore. Only suppress when
             // BOTH ids are present and differ — either side missing, or a manual
             // invocation with no payload session_id, still prints.
@@ -6326,12 +6328,16 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
     // hostSessionId(); absent both, undefined -- api.getContext then applies
     // the pure freshness bound with no owner-match short-circuit.
     let payloadSessionId;
+    // Z1: the hook payload's raw prompt, read beside session_id (docs/plans/2026-09-26-z1-prompt-recall.md).
+    let payloadPrompt;
     if (stdinText && stdinText.trim() !== '') {
         try {
-            const payload = JSON.parse(stdinText.trim());
-            if (payload && typeof payload === 'object' && typeof payload.session_id === 'string' && payload.session_id.trim() !== '') {
-                payloadSessionId = payload.session_id;
-            }
+            // SAFETY: both fields are type-checked below before use; `?? {}` covers a JSON null payload.
+            const { session_id: sid, prompt } = (JSON.parse(stdinText.trim()) ?? {});
+            if (typeof sid === 'string' && sid.trim() !== '')
+                payloadSessionId = sid;
+            if (typeof prompt === 'string')
+                payloadPrompt = prompt;
         }
         catch {
             // Malformed/non-JSON stdin: fall through to the env fallback below.
@@ -6347,6 +6353,7 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
         includeRecent: parseCountFlag(flags['include-recent']),
         crossProject,
         currentSessionId,
+        prompt: payloadPrompt,
     };
     const result = await api.getContext(ctx, opts);
     // Early exit when there's nothing to render (matches pre-extraction behavior).
@@ -6398,9 +6405,18 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
         }));
     }
     else if (format === 'additional-context') {
-        // Claude Code UserPromptSubmit hook JSON shape. Capture print* helpers'
-        // output into a string buffer and wrap as `additionalContext`.
-        const textBlock = captureConsole(() => {
+        // Z1: split into a static block (snapshot/handoff/events/pins/recent-N,
+        // TE2-skippable) and a prompt-recall block (never skipped, own heading).
+        const staticEntries = mainEntries.filter((r) => !r.promptRecall);
+        const staticCrossEntries = crossEntries.filter((r) => !r.promptRecall);
+        const recallEntries = result.entries.filter((r) => r.promptRecall);
+        const staticItems = staticEntries.map((r) => ({ entry: r.entry, score: r.score, tokens: r.tokens, isGlobal: r.isGlobal ?? false }));
+        const recallItems = recallEntries.map((r) => ({ entry: r.entry, score: r.score, tokens: r.tokens, isGlobal: r.isGlobal ?? false }));
+        // Header total is static-only once a recall section exists; otherwise byte-identical to today.
+        const staticHeaderTokens = recallItems.length > 0
+            ? staticItems.reduce((sum, r) => sum + r.tokens, 0)
+            : result.tokens;
+        const staticBlock = captureConsole(() => {
             if (result.activeSnapshot)
                 printActiveTaskSnapshot(result.activeSnapshot);
             if (result.sessionHandoff)
@@ -6408,49 +6424,66 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
             if (result.recentEvents && result.recentEvents.length > 0) {
                 printSessionEvents(result.recentEvents);
             }
-            if (renderItems.length > 0) {
+            if (staticItems.length > 0) {
                 // TE1: no live strength percentage, so an unchanged set of memories
                 // renders byte-identically turn after turn.
-                printContextMarkdown(renderItems, result.tokens, framing, { showStrength: false });
+                printContextMarkdown(staticItems, staticHeaderTokens, framing, { showStrength: false });
             }
-            printCrossProjectSection(crossEntries);
+            printCrossProjectSection(staticCrossEntries);
         });
-        if (!textBlock.trim())
+        const recallTokens = recallItems.reduce((sum, r) => sum + r.tokens, 0);
+        const recallBlock = recallItems.length > 0
+            ? captureConsole(() => printContextMarkdown(recallItems, recallTokens, framing, { showStrength: false, heading: 'Prompt-Relevant Memory' }))
+            : '';
+        if (!staticBlock.trim() && !recallBlock.trim())
             return;
         const surface = pinnedOnly ? 'hook' : 'context';
-        const hash = blockHash(textBlock);
-        const tokens = estimateTokens(textBlock);
-        // TE2: the per-prompt hook skips a block identical to the one this
-        // session already has, and resends it every refreshTurns skips. Only
-        // with a session id from the hook payload itself: an inherited env id
-        // (a manual run inside an agent's shell) must never suppress output.
-        if (pinnedOnly && payloadSessionId !== undefined) {
+        let sendStatic = staticBlock.trim().length > 0;
+        // TE2: the per-prompt hook skips a static block identical to the one this
+        // session already has, resent every refreshTurns skips. Hashed on the
+        // static text alone so an unchanged pin set still skips while recall varies.
+        if (sendStatic && pinnedOnly && payloadSessionId !== undefined) {
             const injectCfg = loadConfig(hippoRoot).pinnedInject;
             if (injectCfg.skipUnchanged !== false) {
                 const refreshTurns = Number.isFinite(injectCfg.refreshTurns) && injectCfg.refreshTurns >= 0
                     ? injectCfg.refreshTurns
                     : 10;
+                const staticHash = blockHash(staticBlock);
                 const last = withLedgerDb(hippoRoot, (db) => lastSentState(db, ctx.tenantId, payloadSessionId, surface));
-                if (shouldSkipUnchanged(last ?? null, hash, refreshTurns)) {
+                if (shouldSkipUnchanged(last ?? null, staticHash, refreshTurns)) {
                     withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
                         tenantId: ctx.tenantId, sessionId: payloadSessionId, surface, event: 'skip',
-                        items: renderItems.length, tokens, hash,
+                        items: staticItems.length, tokens: estimateTokens(staticBlock), hash: staticHash,
                     }));
-                    return;
+                    sendStatic = false;
                 }
             }
         }
+        const finalStatic = sendStatic ? staticBlock : '';
+        const additionalContext = finalStatic && recallBlock
+            ? `${finalStatic}\n\n${recallBlock}`
+            : finalStatic || recallBlock;
+        if (!additionalContext.trim())
+            return;
         const payload = {
             hookSpecificOutput: {
                 hookEventName: 'UserPromptSubmit',
-                additionalContext: textBlock,
+                additionalContext,
             },
         };
         process.stdout.write(JSON.stringify(payload));
-        withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
-            tenantId: ctx.tenantId, sessionId: currentSessionId, surface, event: 'inject',
-            items: renderItems.length, tokens, hash,
-        }));
+        if (finalStatic) {
+            withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
+                tenantId: ctx.tenantId, sessionId: currentSessionId, surface, event: 'inject',
+                items: staticItems.length, tokens: estimateTokens(finalStatic), hash: blockHash(finalStatic),
+            }));
+        }
+        if (recallBlock) {
+            withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
+                tenantId: ctx.tenantId, sessionId: currentSessionId, surface: 'hook_recall', event: 'inject',
+                items: recallItems.length, tokens: estimateTokens(recallBlock), hash: blockHash(recallBlock),
+            }));
+        }
     }
     else {
         // markdown (default)
@@ -6575,7 +6608,8 @@ function printCrossProjectSection(items) {
 export function printContextMarkdown(items, totalTokens, framing = 'observe', opts = {}) {
     const now = evalNow();
     const showStrength = opts.showStrength !== false;
-    console.log(`## Project Memory (${items.length} entries, ${totalTokens} tokens)\n`);
+    const heading = opts.heading ?? 'Project Memory';
+    console.log(`## ${heading} (${items.length} entries, ${totalTokens} tokens)\n`);
     for (const item of items) {
         const e = item.entry;
         const tagStr = e.tags.length > 0 ? ` [${e.tags.join(', ')}]` : '';
@@ -8742,6 +8776,7 @@ Commands:
     --budget <n>           Token budget (default: 1500)
     --pinned-only          Only inject pinned memories (used by UserPromptSubmit hook)
     --include-recent <n>   With --pinned-only, also inject the last N writes regardless of pinning
+    (the hook payload's "prompt" drives prompt recall instead of --include-recent when pinnedInject.promptRecall is on)
     --format <fmt>         Output format: markdown (default), json, or additional-context (Claude Code hook JSON)
     --framing <mode>       Framing: observe (default), suggest, assert
   sleep                    Run consolidation pass (auto-learns + dedup + auto-shares)
@@ -8953,7 +8988,7 @@ Commands:
   last-sleep               Print the last 'hippo sleep --log-file' output and clear it
     --path <p>             Log path (default: ~/.hippo/logs/last-sleep.log)
     --keep                 Print without clearing
-  pre-compact              PreCompact hook: snapshot + capture the tail before compaction
+  pre-compact              PreCompact hook: save a working-state snapshot before compaction
     --log-file <p>         Diagnostic log path (default: ~/.hippo/logs/pre-compact.log)
   compact-resume           SessionStart(compact) hook: re-print the snapshot + session trail
   post-compact             PostCompact hook: tell the user what pre-compact saved

package/dist/config.d.ts

@@ -2,6 +2,7 @@
  * Config support for Hippo: reads .hippo/config.json with sane defaults.
  */
 import { type PhysicsConfig } from './physics-config.js';
+import type { PromptRecallMetric } from './prompt-recall.js';
 export type DecayBasis = 'clock' | 'session' | 'adaptive';
 export interface HippoConfig {
     defaultHalfLifeDays: number;
@@ -69,6 +70,20 @@ export interface HippoConfig {
          *  sessions still see pinned rules near the latest turn. Default 10; 0
          *  never resends an unchanged block. */
         refreshTurns: number;
+        /** Z1: gate the hook's backfill on the prompt's own content instead of
+         *  the five newest memories. Default false: the eval failed its overlap gate
+         *  (docs/evals/2026-09-26-z1-prompt-recall-result.md). */
+        promptRecall: boolean;
+        /** Z1: overlap metric for the prompt-recall gate. Default 'jaccard' (tuned, docs/evals/2026-09-26-z1-prompt-recall-result.md). */
+        promptRecallMetric: PromptRecallMetric;
+        /** Z1: minimum overlap score to admit a candidate. Default 0.04 (tuned). */
+        promptRecallThreshold: number;
+        /** Z1: minimum shared tokens to admit a candidate. Default 2. */
+        promptRecallMinShared: number;
+        /** Z1: max prompt-recall entries injected per prompt. Default 5 (tuned). */
+        promptRecallMaxItems: number;
+        /** Z1: FTS candidate pool size per store before gating. Default 100. */
+        promptRecallCandidates: number;
     };
     /** Memory scope isolation (v39): when true (default), ambient context
      *  (`hippo context`, the UserPromptSubmit hook, /v1/context, MCP

package/dist/config.js

@@ -47,6 +47,12 @@ const DEFAULT_CONFIG = {
         budget: 1500,
         skipUnchanged: true,
         refreshTurns: 10,
+        promptRecall: false,
+        promptRecallMetric: 'jaccard',
+        promptRecallThreshold: 0.04,
+        promptRecallMinShared: 2,
+        promptRecallMaxItems: 5,
+        promptRecallCandidates: 100,
     },
     contextProjectIsolation: true,
     extraction: {

package/dist/prompt-recall.d.ts

@@ -0,0 +1,33 @@
+export type PromptRecallMetric = 'jaccard' | 'cosine';
+export interface PromptRecallGate {
+    metric: PromptRecallMetric;
+    threshold: number;
+    minShared: number;
+    maxItems: number;
+}
+export declare const PROMPT_RECALL_MAX_CHARS = 4000;
+/** Distinct content tokens: longer than 2 chars, not a stop word. */
+export declare function contentTokens(text: string): Set<string>;
+export declare function promptTokens(prompt: string): Set<string>;
+export interface OverlapScore {
+    score: number;
+    shared: number;
+}
+/** Overlap of two token sets under `metric`. 0 when either set is empty. */
+export declare function scoreOverlap(p: ReadonlySet<string>, m: ReadonlySet<string>, metric: PromptRecallMetric): OverlapScore;
+/** Candidates that clear the gate, sorted score desc then id asc, capped at `gate.maxItems`. */
+export declare function gatePromptRecall<T extends {
+    id: string;
+    tokens: ReadonlySet<string>;
+}>(p: ReadonlySet<string>, candidates: readonly T[], gate: PromptRecallGate): Array<{
+    item: T;
+    score: number;
+    shared: number;
+}>;
+/** The prompt's content tokens as an FTS pre-select query, capped at `maxTerms`. */
+export declare function promptRecallFtsQuery(p: ReadonlySet<string>, maxTerms?: number): string;
+export declare const RAREST_TERM_COUNT = 8;
+/** Terms sorted by ascending FTS doc count (rarest first), zero-count terms dropped, ties by term.
+ *  Pure: `docCount` (an FTS lookup in the caller) does the only I/O. */
+export declare function rarestPromptTerms(terms: Iterable<string>, docCount: (term: string) => number, maxTerms?: number): string[];
+//# sourceMappingURL=prompt-recall.d.ts.map

package/dist/prompt-recall.js

@@ -0,0 +1,68 @@
+/** Z1: recall gated on the hook prompt, not the five newest memories (pure, no I/O).
+ *  See docs/plans/2026-09-26-z1-prompt-recall.md. */
+import { tokenize } from './search.js';
+import { STOP_WORDS } from './audit.js';
+// Latency bound, not tuned: fixed in the prereg regardless of gate config.
+export const PROMPT_RECALL_MAX_CHARS = 4000;
+/** Distinct content tokens: longer than 2 chars, not a stop word. */
+export function contentTokens(text) {
+    const out = new Set();
+    for (const t of tokenize(text)) {
+        if (t.length > 2 && !STOP_WORDS.has(t))
+            out.add(t);
+    }
+    return out;
+}
+export function promptTokens(prompt) {
+    return contentTokens(prompt.slice(0, PROMPT_RECALL_MAX_CHARS));
+}
+/** Overlap of two token sets under `metric`. 0 when either set is empty. */
+export function scoreOverlap(p, m, metric) {
+    if (p.size === 0 || m.size === 0)
+        return { score: 0, shared: 0 };
+    const [small, large] = p.size <= m.size ? [p, m] : [m, p];
+    let shared = 0;
+    for (const t of small)
+        if (large.has(t))
+            shared++;
+    const score = metric === 'jaccard'
+        ? shared / (p.size + m.size - shared)
+        : shared / Math.sqrt(p.size * m.size);
+    return { score, shared };
+}
+/** Candidates that clear the gate, sorted score desc then id asc, capped at `gate.maxItems`. */
+export function gatePromptRecall(p, candidates, gate) {
+    if (p.size === 0)
+        return [];
+    const kept = [];
+    for (const item of candidates) {
+        const { score, shared } = scoreOverlap(p, item.tokens, gate.metric);
+        if (score >= gate.threshold && shared >= gate.minShared)
+            kept.push({ item, score, shared });
+    }
+    kept.sort((a, b) => (b.score - a.score) || (a.item.id < b.item.id ? -1 : a.item.id > b.item.id ? 1 : 0));
+    return kept.slice(0, gate.maxItems);
+}
+/** The prompt's content tokens as an FTS pre-select query, capped at `maxTerms`. */
+export function promptRecallFtsQuery(p, maxTerms = 32) {
+    const terms = [];
+    for (const t of p) {
+        if (terms.length >= maxTerms)
+            break;
+        terms.push(t);
+    }
+    return terms.join(' ');
+}
+// bm25 ranks every row matching any term, so fewer and rarer terms bound latency; 8 is a bound, not tuned.
+export const RAREST_TERM_COUNT = 8;
+/** Terms sorted by ascending FTS doc count (rarest first), zero-count terms dropped, ties by term.
+ *  Pure: `docCount` (an FTS lookup in the caller) does the only I/O. */
+export function rarestPromptTerms(terms, docCount, maxTerms = RAREST_TERM_COUNT) {
+    return Array.from(terms)
+        .map((t) => ({ t, c: docCount(t) }))
+        .filter((x) => x.c > 0)
+        .sort((a, b) => (a.c - b.c) || (a.t < b.t ? -1 : a.t > b.t ? 1 : 0))
+        .slice(0, maxTerms)
+        .map((x) => x.t);
+}
+//# sourceMappingURL=prompt-recall.js.map

package/dist/store.d.ts

@@ -445,6 +445,10 @@ export declare function loadSearchEntries(hippoRoot: string, query: string, limi
  * undefined as "no tenant filter" for legacy callers.
  */
 export declare function loadRecallSearchEntries(hippoRoot: string, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive', includeSuperseded?: boolean): MemoryEntry[];
+export declare function loadRecallSearchEntriesFromDb(db: DatabaseSyncLike, query: string, limit?: number, tenantId?: string, requestedScope?: string, explicitScopeMode?: 'exact' | 'additive', includeSuperseded?: boolean): MemoryEntry[];
+/** Rarest-K prompt terms for this connection's FTS index, as a space-joined query string.
+ *  Without FTS, returns the first 32 terms, as before rarest-term selection. */
+export declare function pickRarestFtsQuery(db: DatabaseSyncLike, terms: readonly string[], maxTerms?: number): string;
 /**
  * Rebuild mirrors from SQLite, importing any legacy markdown files not already present.
  */

package/dist/store.js

@@ -13,6 +13,7 @@ import { rowToSessionHandoff, isHandoffOutcome } from './handoff.js';
 import { CARD_TRANSITIONS, CARD_LEASE_MS } from './card.js';
 import { tokenize, markRetrieved } from './search.js';
 import { isRecallBoostAblated } from './ablation.js';
+import { rarestPromptTerms, RAREST_TERM_COUNT } from './prompt-recall.js';
 import { appendAuditEvent } from './audit.js';
 import { resolveTenantId } from './tenant.js';
 import { deriveOriginProject, originFromSource, findHippoStoreDir, realpathOrResolve } from './project-identity.js';
@@ -1896,21 +1897,46 @@ export function loadRecallSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH
     initStore(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
-        // explicitScopeMode only matters when requestedScope is set:
-        //   'exact'    — api.recall semantics: narrow to m.scope = requested.
-        //   'additive' — CLI --scope semantics (v1.25.0): default-admitted set
-        //                PLUS the requested scope; see RecallScopeFilter docs.
-        const scopeFilter = requestedScope && requestedScope !== ''
-            ? explicitScopeMode === 'additive'
-                ? { mode: 'default-deny-or-exact', value: requestedScope }
-                : { mode: 'exact', value: requestedScope }
-            : { mode: 'default-deny' };
-        return loadSearchRows(db, query, limit, tenantId, scopeFilter, includeSuperseded).map(rowToEntry);
+        return loadRecallSearchEntriesFromDb(db, query, limit, tenantId, requestedScope, explicitScopeMode, includeSuperseded);
     }
     finally {
         closeHippoDb(db);
     }
 }
+// Split out so callers with an already-open db (Z1 prompt-recall path) skip
+// the initStore+open/close cycle per store per call.
+export function loadRecallSearchEntriesFromDb(db, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true) {
+    // 'exact' narrows to requestedScope; 'additive' adds it to the default-admitted set.
+    const scopeFilter = requestedScope && requestedScope !== ''
+        ? explicitScopeMode === 'additive'
+            ? { mode: 'default-deny-or-exact', value: requestedScope }
+            : { mode: 'exact', value: requestedScope }
+        : { mode: 'default-deny' };
+    return loadSearchRows(db, query, limit, tenantId, scopeFilter, includeSuperseded).map(rowToEntry);
+}
+/** Rarest-K prompt terms for this connection's FTS index, as a space-joined query string.
+ *  Without FTS, returns the first 32 terms, as before rarest-term selection. */
+export function pickRarestFtsQuery(db, terms, maxTerms = RAREST_TERM_COUNT) {
+    // The LIKE path has no bm25 ranking to bound, so it keeps the pre-rarest 32-term query.
+    if (!isFtsAvailable(db))
+        return terms.slice(0, 32).join(' ');
+    db.exec(`CREATE VIRTUAL TABLE IF NOT EXISTS temp.z1_rarest_vocab USING fts5vocab(main, 'memories_fts', 'row')`);
+    // unicode61 splits `journal_mode` into two vocab terms; a term's count is its rarest part's (an upper bound).
+    const partsOf = (t) => t.split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+    const vocab = Array.from(new Set(terms.flatMap(partsOf)));
+    if (vocab.length === 0)
+        return '';
+    // SAFETY: rows' shape matches the two columns named in the SELECT.
+    const rows = db
+        .prepare(`SELECT term, doc FROM temp.z1_rarest_vocab WHERE term IN (${vocab.map(() => '?').join(', ')})`)
+        .all(...vocab);
+    const counts = new Map(rows.map((r) => [r.term, r.doc]));
+    const docCount = (t) => {
+        const parts = partsOf(t);
+        return parts.length === 0 ? 0 : Math.min(...parts.map((x) => counts.get(x) ?? 0));
+    };
+    return rarestPromptTerms(terms, docCount, maxTerms).join(' ');
+}
 /**
  * Rebuild mirrors from SQLite, importing any legacy markdown files not already present.
  */

package/dist/token-ledger.d.ts

@@ -2,11 +2,12 @@ import type { DatabaseSyncLike } from './db.js';
 /**
  * Where a block of memory text was sent.
  * - `hook`: the per-prompt `UserPromptSubmit` hook (`hippo context --pinned-only`).
+ * - `hook_recall`: the same hook's Z1 prompt-recall section (docs/plans/2026-09-26-z1-prompt-recall.md).
  * - `context`, `recall`: the CLI commands.
  * - `mcp_recall`, `mcp_context`: the MCP tools.
  * - `http_recall`, `http_context`, `http_assemble`: the HTTP API.
  */
-export type TokenSurface = 'hook' | 'context' | 'recall' | 'mcp_recall' | 'mcp_context' | 'http_recall' | 'http_context' | 'http_assemble';
+export type TokenSurface = 'hook' | 'hook_recall' | 'context' | 'recall' | 'mcp_recall' | 'mcp_context' | 'http_recall' | 'http_context' | 'http_assemble';
 /** All surfaces, in report order. */
 export declare const TOKEN_SURFACES: readonly TokenSurface[];
 /**

package/dist/token-ledger.js

@@ -21,7 +21,7 @@
 import { createHash } from 'node:crypto';
 /** All surfaces, in report order. */
 export const TOKEN_SURFACES = [
-    'hook', 'context', 'recall', 'mcp_recall', 'mcp_context',
+    'hook', 'hook_recall', 'context', 'recall', 'mcp_recall', 'mcp_context',
     'http_recall', 'http_context', 'http_assemble',
 ];
 /** Rows older than this are pruned on write. */

package/dist/version.d.ts

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export declare const PACKAGE_VERSION = "1.51.0";
+export declare const PACKAGE_VERSION = "1.52.1";
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export declare function compareSemver(a: string, b: string): number;
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export const PACKAGE_VERSION = '1.51.0';
+export const PACKAGE_VERSION = '1.52.1';
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export function compareSemver(a, b) {
     const parse = (v) => {

package/extensions/openclaw-plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Biologically-inspired memory for AI agents. Decay by default, retrieval strengthening, sleep consolidation.",
-  "version": "1.51.0",
+  "version": "1.52.1",
 
   "configSchema": {
     "type": "object",

package/extensions/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.51.0",
+  "version": "1.52.1",
   "type": "module",
   "description": "Hippo Memory plugin for OpenClaw - biologically-inspired agent memory",
   "main": "index.ts",

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Biologically-inspired memory for AI agents. Decay by default, retrieval strengthening, sleep consolidation.",
-  "version": "1.51.0",
+  "version": "1.52.1",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.51.0",
+  "version": "1.52.1",
   "description": "Biologically-inspired memory for AI agents. Zero runtime deps, SQLite, MCP server, and an opt-in hosted TypeSafe Jev reranker. Decay, retrieval strengthening, consolidation.",
   "mcpName": "io.github.kitfunso/hippo-memory",
   "type": "module",