hippo-memory 1.52.0 → 1.52.2

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

@@ -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';
@@ -132,14 +133,14 @@ export function ambientSecretAdmit(e, currentProjectName) {
         return false;
     return origin === currentProjectName;
 }
-// The pinned-only branch needs pins and recent-N candidates, not the corpus.
-function loadAmbientEntries(hippoRoot, tenantId, pinnedOnly, includeRecent, admit) {
+// The pinned-only branch needs pins and recent-N candidates, not the corpus; `recall` applies there only.
+function loadAmbientEntries(hippoRoot, tenantId, pinnedOnly, includeRecent, admit, recall) {
     if (!pinnedOnly)
-        return loadAllEntries(hippoRoot, tenantId).filter(admit);
+        return { entries: loadAllEntries(hippoRoot, tenantId).filter(admit) };
     // DF3's quality floor runs on the recent-N slice AFTER this load, so the load
     // counts by it too, or it stops short of a store whose newest rows are junk.
     const admitAmbient = (e) => admit(e) && (e.pinned || isContentWorthStoring(e.content));
-    return loadAmbientCandidates(hippoRoot, tenantId, includeRecent, admitAmbient);
+    return loadAmbientCandidates(hippoRoot, tenantId, includeRecent, admitAmbient, recall);
 }
 export function remember(ctx, opts) {
     const detection = opts.untrusted ? detectInstruction(opts.content) : { flagged: false, reason: null };
@@ -1490,6 +1491,7 @@ export function auditList(ctx, opts) {
         closeHippoDb(db);
     }
 }
+const finiteOr = (v, dflt, min) => Number.isFinite(v) && v >= min ? v : dflt;
 /**
  * Assemble a context bundle: recalled memories (pinned-only / strength-sorted
  * fallback / hybrid search) + active task snapshot + session handoff + recent
@@ -1539,13 +1541,24 @@ export async function getContext(ctx, opts = {}) {
     // secrets, so WHICH rows reach this predicate is what loadAmbientEntries cares
     // about below.
     const admit = (e) => !e.superseded_by && ambientAdmit(e);
-    // Tenant-scoped loads (v1.11.1 lesson: NEVER resolveTenantId({}) here).
-    let localEntries = hasLocal
-        ? loadAmbientEntries(ctx.hippoRoot, ctx.tenantId, pinnedOnly, includeRecent, admit)
-        : [];
-    let globalEntries = hasGlobal
-        ? loadAmbientEntries(globalRoot, ctx.tenantId, pinnedOnly, includeRecent, admit)
+    // Z1: decided before the ambient loads so the FTS candidate query below (pinned-only
+    // branch) can piggyback on that connection instead of opening its own.
+    const promptRecallPending = pinnedOnly && Boolean(opts.prompt?.trim()) && config.pinnedInject.promptRecall === true;
+    const promptRecallTerms = promptRecallPending && config.pinnedInject.enabled
+        ? Array.from(promptTokens(opts.prompt ?? ''))
         : [];
+    const recallRequest = promptRecallTerms.length > 0
+        ? { terms: promptRecallTerms, limit: Math.floor(finiteOr(config.pinnedInject.promptRecallCandidates, 100, 1)) }
+        : undefined;
+    // Tenant-scoped loads (v1.11.1 lesson: NEVER resolveTenantId({}) here).
+    const localLoad = hasLocal
+        ? loadAmbientEntries(ctx.hippoRoot, ctx.tenantId, pinnedOnly, includeRecent, admit, recallRequest)
+        : { entries: [] };
+    const globalLoad = hasGlobal
+        ? loadAmbientEntries(globalRoot, ctx.tenantId, pinnedOnly, includeRecent, admit, !isGlobalStoreRoot(ctx.hippoRoot) ? recallRequest : undefined)
+        : { entries: [] };
+    let localEntries = localLoad.entries;
+    let globalEntries = globalLoad.entries;
     // Computed below, after markRetrieved runs, so avgStrength reflects the
     // post-retrieval strengths rather than a stale pre-mutation snapshot.
     let ambientState;
@@ -1587,7 +1600,8 @@ export async function getContext(ctx, opts = {}) {
             limit: 5,
         }).filter((e) => passesScopeFilterForRecall(rowScope(e), undefined))
         : [];
-    if (localEntries.length === 0 &&
+    if (!promptRecallPending &&
+        localEntries.length === 0 &&
         globalEntries.length === 0 &&
         !activeSnapshot &&
         !sessionHandoff &&
@@ -1654,7 +1668,51 @@ 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 = promptRecallPending;
+        if (promptRecallOn) {
+            const rawMetric = pinnedCfg.pinnedInject.promptRecallMetric;
+            const metric = rawMetric === 'cosine' ? 'cosine' : 'jaccard';
+            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 p = promptTokens(opts.prompt ?? '');
+            if (p.size > 0) {
+                // Candidates came off the ambient load's own connection (recallRequest above), not a fresh open.
+                const localCandidates = localLoad.recall ?? [];
+                const globalCandidates = globalLoad.recall ?? [];
+                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-error.js

@@ -2,7 +2,7 @@
 // stored, because error memories decay slowly and would crowd out real lessons; what is stored stays `observed`
 // until outcome feedback confirms it. Every failure, stored or not, goes to the failure log (ROADMAP CD13).
 import { createMemory } from './memory.js';
-import { writeEntry, loadAllEntries } from './store.js';
+import { writeEntry, loadContentsWithTag } from './store.js';
 import { loadConfig } from './config.js';
 import { closeHippoDb, openHippoDb } from './db.js';
 import { recordFailure } from './failure-log.js';
@@ -94,7 +94,7 @@ function logFailure(hippoRoot, tenantId, payload, lesson, outcome) {
 }
 function storeLesson(hippoRoot, tenantId, text) {
     const sig = failureSignature(text);
-    const repeat = loadAllEntries(hippoRoot, tenantId).some((e) => e.tags.includes('auto-captured') && failureSignature(e.content) === sig);
+    const repeat = loadContentsWithTag(hippoRoot, tenantId, 'auto-captured').some((content) => failureSignature(content) === sig);
     if (repeat)
         return 'duplicate';
     const entry = createMemory(text, {

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

@@ -6328,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.
@@ -6349,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).
@@ -6400,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)
@@ -6410,49 +6424,77 @@ 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 || recallBlock) {
+            // One connection for both rows; each insert in its own try so one failing doesn't skip the other.
+            withLedgerDb(hippoRoot, (db) => {
+                if (finalStatic) {
+                    try {
+                        recordTokenUse(db, {
+                            tenantId: ctx.tenantId, sessionId: currentSessionId, surface, event: 'inject',
+                            items: staticItems.length, tokens: estimateTokens(finalStatic), hash: blockHash(finalStatic),
+                        });
+                    }
+                    catch { /* best effort; see withLedgerDb doc comment */ }
+                }
+                if (recallBlock) {
+                    try {
+                        recordTokenUse(db, {
+                            tenantId: ctx.tenantId, sessionId: currentSessionId, surface: 'hook_recall', event: 'inject',
+                            items: recallItems.length, tokens: estimateTokens(recallBlock), hash: blockHash(recallBlock),
+                        });
+                    }
+                    catch { /* best effort; see withLedgerDb doc comment */ }
+                }
+            });
+        }
     }
     else {
         // markdown (default)
@@ -6577,7 +6619,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(', ')}]` : '';
@@ -8744,6 +8787,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)

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/db.js

@@ -2819,9 +2819,10 @@ function backfillFtsIndex(db) {
     // SAFETY: this get() result's shape matches the single aliased `c` column
     // named in the SELECT above.
     const memCount = db.prepare(`SELECT COUNT(*) AS c FROM memories`).get()?.c ?? 0;
-    // SAFETY: this get() result's shape matches the single aliased `c` column
-    // named in the SELECT above.
-    const ftsCount = db.prepare(`SELECT COUNT(*) AS c FROM memories_fts`).get()?.c ?? 0;
+    // SAFETY: this get() result's shape matches the single aliased `c` column named in the SELECT above.
+    // memories_fts_docsize is FTS5's cheaper one-row-per-document shadow table; fall back for a foreign-built index.
+    const ftsTable = tableExists(db, 'memories_fts_docsize') ? 'memories_fts_docsize' : 'memories_fts';
+    const ftsCount = db.prepare(`SELECT COUNT(*) AS c FROM ${ftsTable}`).get()?.c ?? 0;
     if (memCount === ftsCount)
         return;
     db.exec(`

package/dist/half-life-migration.js

@@ -20,7 +20,7 @@
  * (7 days when never recorded) to the configured `defaultHalfLifeDays`.
  */
 import { deriveHalfLife } from './memory.js';
-import { initStore, selectAllEntries, HALF_LIFE_BASE_META_KEY } from './store.js';
+import { openStore, selectAllEntries, HALF_LIFE_BASE_META_KEY } from './store.js';
 import { openHippoDb, closeHippoDb, getMeta, setMeta } from './db.js';
 import { appendAuditEvent } from './audit.js';
 /** The base every store used before the base was recorded. */
@@ -65,8 +65,7 @@ function readBase(db) {
 export function migrateDefaultHalfLife(hippoRoot, to, opts = {}) {
     const dryRun = opts.dryRun ?? false;
     const noop = (from) => ({ from, to, rescaled: 0, kept: 0, dryRun, halfLives: new Map() });
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // Plan, write, audit and record the base under one write lock, so a concurrent write or sleep cannot interleave.
         if (!dryRun)

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/reject-flow.js

@@ -11,11 +11,11 @@
  * raw-archive.ts and dormant.ts. Nothing imports FROM this file except
  * cli.ts and api.ts, so it introduces no cycle.
  */
-import { openHippoDb, closeHippoDb } from './db.js';
+import { closeHippoDb } from './db.js';
 import { appendAuditEvent } from './audit.js';
 import { archiveRawMemory } from './raw-archive.js';
 import { purgeDormantByDigest } from './dormant.js';
-import { initStore, deleteEntryCore, purgeMirrorBestEffort, } from './store.js';
+import { openStore, deleteEntryCore, purgeMirrorBestEffort, } from './store.js';
 import { rejectionDigest, normalizeValueForRejection, insertRejectedValue, deleteRejectedValue, listRejectedValues, } from './rejection.js';
 /**
  * `hippo reject` / `api.reject` core flow. ONE connection, one transaction:
@@ -46,8 +46,7 @@ export function rejectValue(opts) {
         // and pollute the listing.
         throw new Error('reject --value requires non-empty content.');
     }
-    initStore(opts.hippoRoot);
-    const db = openHippoDb(opts.hippoRoot);
+    const db = openStore(opts.hippoRoot);
     try {
         let content;
         if (opts.memoryId !== undefined) {
@@ -170,8 +169,7 @@ export function unrejectValue(hippoRoot, tenantId, digestOrPrefix, actor) {
     if (digestOrPrefix.trim().length === 0) {
         return { status: 'not_found' };
     }
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const all = listRejectedValues(db, tenantId);
         const matches = all.filter((r) => r.digest.startsWith(digestOrPrefix));
@@ -201,8 +199,7 @@ export function unrejectValue(hippoRoot, tenantId, digestOrPrefix, actor) {
 }
 /** `hippo rejections` / `api.listRejections` — list tombstones for a tenant. */
 export function listRejectionsForTenant(hippoRoot, tenantId) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         return listRejectedValues(db, tenantId);
     }