hippo-memory 1.52.0 → 1.52.1

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/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,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)
@@ -6577,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(', ')}]` : '';
@@ -8744,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)

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.52.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.52.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.52.0",
+  "version": "1.52.1",
 
   "configSchema": {
     "type": "object",

package/extensions/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.52.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.52.0",
+  "version": "1.52.1",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.52.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",