hippo-memory 1.53.2 → 1.55.0

package/README.md

@@ -118,7 +118,7 @@ Run `hippo init` inside one project. This is everything it writes, in the projec
 - **Instruction files.** A block between `<!-- hippo:start -->` and `<!-- hippo:end -->` in the project's `CLAUDE.md` or `AGENTS.md`, only if that file already exists. Codex, Cursor, OpenClaw, OpenCode and Pi read `AGENTS.md`.
 - **Claude Code,** when the project has `CLAUDE.md` or `.claude/settings.json`: 7 hook entries in `~/.claude/settings.json`, one each on SessionEnd, UserPromptSubmit, PreCompact, PostCompact and PostToolUseFailure and two on SessionStart. [Framework Integrations](#framework-integrations) says what each one runs.
 - **OpenCode,** when the project has `.opencode/` or `opencode.json`: a plugin at `~/.config/opencode/plugins/hippo.ts`.
-- **Codex,** when the project has `AGENTS.md` or `.codex` and Codex is installed (`$CODEX_HOME`, else `~/.codex`, exists): 2 hook entries in Codex's `hooks.json`, one on UserPromptSubmit that sends your pinned memories plus the five most recent ones with every prompt and one on SessionStart after a compaction. **Codex runs them only after you trust them once in `/hooks`.** Init also prints `hippo hook install codex`, the opt-in that wraps the Codex launcher to capture sessions; `hippo hook uninstall codex` removes hippo's hooks and the wrapper.
+- **Codex,** when the project has `AGENTS.md` or `.codex` and Codex is installed (`$CODEX_HOME`, else `~/.codex`, exists): 2 hook entries in Codex's `hooks.json`, one on UserPromptSubmit that sends your pinned memories plus up to 5 that match the prompt with every prompt and one on SessionStart after a compaction. **Codex runs them only after you trust them once in `/hooks`.** Init also prints `hippo hook install codex`, the opt-in that wraps the Codex launcher to capture sessions; `hippo hook uninstall codex` removes hippo's hooks and the wrapper.
 - **A daily run at 6:15am,** one per machine: a crontab line on Linux and macOS, a scheduled task named `hippo-daily-runner` on Windows. It runs `hippo learn --git --days 1` and then `hippo sleep` in every project listed in `~/.hippo/workspaces.json`, and init adds this project to that list.
 - **Agent memories.** On every run, the notes your coding agents keep about this project go into its store, and the ones about you go into the global store. [Agent memories](#agent-memories) lists what is read.
 
@@ -783,7 +783,7 @@ The block asks for nothing a hook already does, because each extra tool call re-
 For Claude Code, it also adds 7 hook entries to `~/.claude/settings.json`:
 - a `SessionEnd` hook that runs `hippo sleep` and then `hippo capture` when the session exits. Capture matches the last 20 user and 10 assistant messages of the transcript against word patterns for decisions, rules, errors and preferences. It uses no model and does not read earlier turns, so record lessons with `hippo remember` as you go.
 - 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 5 newest memories in the store, so fresh same-session lessons appear on the next prompt before you pin them. It does not read your prompt unless you set `{"pinnedInject":{"promptRecall":true}}`, which swaps the 5 newest for memories that match the prompt. 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 `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 up to 5 memories that share words with your prompt. When nothing matches, it adds only the pinned ones. Since 1.55.0 this replaces the 5 newest memories, which cut the median block from 847 to 533 tokens in our eval. `{"pinnedInject":{"promptRecall":false}}` brings back the 5 newest, so fresh same-session lessons appear on the next prompt whatever you ask. 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. The prompt-matched memories go in a separate block that is never skipped, so they are sent on every prompt they match. `{"pinnedInject":{"skipUnchanged":false}}` sends the pinned block 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 records the compaction in the store, saves a working-state snapshot (task/summary/next step) so mid-session compaction can't drop it, and asks the summariser to end its summary with a "Memories for hippo" list: the lessons, decisions and corrections from the session that should outlive it. The `SessionEnd` hook still owns extracting durable memories from the transcript.
 - a second `SessionStart` hook (matcher `compact`) that runs `hippo compact-resume`, printing that snapshot back into context right after compaction, if it is under 15 minutes old.
 - a `PostCompact` hook that runs `hippo post-compact`. It keeps the summary in the store with secrets scrubbed, and saves each item of that list as a memory that sleep never deletes: at most 10 per compaction, skipping an item an earlier compaction already saved and any item that looks like a secret. An item over 500 characters stays in the compaction's record only. It then prints one line, such as "Hippo saved 3 memories from this compaction and restored your task snapshot." If the store is busy, the summary waits in the store's `compactions-spool/` folder and `hippo sleep` finishes the save; `hippo doctor` names any compaction left unfinished for over 10 minutes. The session that compacted does not have those memories injected back into its own prompts, since it just read them in the summary; `hippo recall` still finds them. The hook prints nothing when there is no store to save to.
@@ -794,7 +794,7 @@ Only Claude Code saves memories at a compaction: hippo installs no `PreCompact`
 To remove: `hippo hook uninstall claude-code`
 
 For Codex, it adds two hooks to `$CODEX_HOME/hooks.json` (else `~/.codex/hooks.json`) and keeps every hook already there:
-- a `UserPromptSubmit` hook that runs the same `hippo context --pinned-only` command as Claude Code's, so your pinned memories plus the five most recent ones reach every prompt as developer context
+- a `UserPromptSubmit` hook that runs the same `hippo context --pinned-only` command as Claude Code's, so your pinned memories plus up to 5 that match the prompt reach every prompt as developer context
 - a `SessionStart` hook (matcher `compact`) that runs `hippo compact-resume` after a compaction, so the next prompt sends that block again. Codex gets no `PreCompact` hook from hippo, so it restores a task snapshot only if one was saved with `hippo snapshot save` in the last 15 minutes
 
 **Codex runs a new or changed hook only after you trust it, so open `/hooks` in Codex once and trust both;** `hippo doctor` reminds you. The per-prompt hook was checked against a real Codex request; the compaction hook follows Codex's documented `compact` start source and has not been watched end to end in Codex. Each hook also carries a `commandWindows` form (`hippo.cmd ...`), because Codex runs hooks through PowerShell on Windows, where the execution policy can block npm's `hippo.ps1`. hippo only ever appends these two entries and never rewrites one, since Codex treats a changed command as a new hook to trust. To remove: `hippo hook uninstall codex`, which takes out only hippo's exact commands and leaves every other hook, including one of yours that runs hippo.
@@ -1056,7 +1056,7 @@ node run.mjs --adapter all
 
 ### How do I give Claude Code memory between sessions?
 
-Run `npm install -g hippo-memory`, then `hippo init` in the project. If the project has a `CLAUDE.md`, init adds a short block telling Claude to run `hippo context --auto` when a session starts. It also adds 7 hook entries to Claude Code's settings that keep your pinned memories plus the five most recent ones in context, save a task snapshot and the memories a compaction summary lists, store failed tool calls as lessons, and run `hippo sleep` when the session ends, and it sets up a daily 6:15am run. [What hippo init changes](#what-hippo-init-changes) lists everything. The [Claude Code plugin](https://github.com/kitfunso/hippo-memory/tree/master/extensions/claude-code-plugin) is the alternative to these hooks; use one, not both. To set up every git repo up to three folders below your home directory at once, know what the scan changes first: each repo gets its own store, seeded from a year of its git history, the same hooks go in when one of those repos uses Claude Code, and the daily run is set up, but no block goes into any repo's `CLAUDE.md`. The command is `hippo init --scan ~`; run `hippo init` in the projects where you want the block.
+Run `npm install -g hippo-memory`, then `hippo init` in the project. If the project has a `CLAUDE.md`, init adds a short block telling Claude to run `hippo context --auto` when a session starts. It also adds 7 hook entries to Claude Code's settings that keep your pinned memories plus up to 5 that match the prompt in context, save a task snapshot and the memories a compaction summary lists, store failed tool calls as lessons, and run `hippo sleep` when the session ends, and it sets up a daily 6:15am run. [What hippo init changes](#what-hippo-init-changes) lists everything. The [Claude Code plugin](https://github.com/kitfunso/hippo-memory/tree/master/extensions/claude-code-plugin) is the alternative to these hooks; use one, not both. To set up every git repo up to three folders below your home directory at once, know what the scan changes first: each repo gets its own store, seeded from a year of its git history, the same hooks go in when one of those repos uses Claude Code, and the daily run is set up, but no block goes into any repo's `CLAUDE.md`. The command is `hippo init --scan ~`; run `hippo init` in the projects where you want the block.
 
 ### How do I give Cursor memory between sessions?
 
@@ -1064,7 +1064,7 @@ Run `npm install -g hippo-memory`, then `hippo init` in the project. If the proj
 
 ### How do I give Codex memory across sessions?
 
-`hippo init` adds its instructions to your `AGENTS.md`, which Codex reads before it starts work. When Codex is installed, init also adds two hooks to Codex's `hooks.json`: one puts your pinned memories plus the five most recent ones into every prompt, the other makes the next prompt send them again after a compaction. Codex asks you to trust each new hook once in `/hooks`, and skips it until you do. Capturing Codex sessions is opt-in: `hippo hook install codex` wraps the Codex launcher, and `hippo hook uninstall codex` removes the wrapper and the hooks.
+`hippo init` adds its instructions to your `AGENTS.md`, which Codex reads before it starts work. When Codex is installed, init also adds two hooks to Codex's `hooks.json`: one puts your pinned memories plus up to 5 that match the prompt into every prompt, the other makes the next prompt send them again after a compaction. Codex asks you to trust each new hook once in `/hooks`, and skips it until you do. Capturing Codex sessions is opt-in: `hippo hook install codex` wraps the Codex launcher, and `hippo hook uninstall codex` removes the wrapper and the hooks.
 
 ### Which agents does hippo work with?
 

package/dist/api.d.ts

@@ -43,6 +43,8 @@ export interface Actor {
     role: 'admin' | 'member';
     /** EI2: restricted scopes a member key may read (auth.ts grantScope). Unused for admin actors. */
     scopes?: readonly string[];
+    /** An auth resolver vouched for this caller, so its admin role stops at its own tenant. */
+    viaAuthResolver?: true;
 }
 export interface Context {
     hippoRoot: string;
@@ -869,8 +871,8 @@ export interface AuthCreateResult {
  * `src/server.ts` POST /v1/auth/keys mirrors this: it ignores any body
  * `tenantId` and uses the resolved Bearer's tenant exclusively.
  *
- * Only an admin actor can mint (ForbiddenError otherwise), so a member key
- * can never create a key, least of all an admin one.
+ * Only an admin actor can mint (ForbiddenError otherwise), and a key never
+ * outranks its minter: a resolver admin is tenant-only, so it mints members.
  */
 export declare function authCreate(ctx: Context, opts: AuthCreateOpts): AuthCreateResult;
 /**

package/dist/api.js

@@ -6,7 +6,6 @@
  * (`hippo serve`, A1) call into this module so the business logic lives
  * in exactly one place.
  */
-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, memoriesBackingObjects, } from './store.js';
 import { RejectedValueError } from './rejection.js';
@@ -18,7 +17,7 @@ import { quarantineScopeFor, recordQuarantine, getQuarantineRow, listQuarantineR
 import { summarizeFailures } from './failure-log.js';
 import { formatHandoffEvidenceLine } from './handoff.js';
 import { createMemory, createSuccessor, applyOutcome, calculateStrength, CHURN_STALE_TAG, COMPACTION_MEMORY_TAG, } from './memory.js';
-import { appendAuditEvent, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
+import { appendAuditEvent, auditQueryFields, queryAuditEvents, auditMemories, isContentWorthStoring, } from './audit.js';
 import { promoteToGlobal, getGlobalRoot, autoShare, searchBothHybrid } from './shared.js';
 import { writeRecallTrace, writeRecallTraceAtRoot, recordTraceOutcome } from './recall-trace.js';
 import { evalNow } from './ablation.js';
@@ -549,8 +548,7 @@ function recallFrom(ctx, opts, windowSize, all) {
             actor: ctx.actor.subject,
             op: 'recall',
             metadata: {
-                query_hash: createHash('sha256').update(opts.query).digest('hex').slice(0, 16),
-                query_length: opts.query.length,
+                ...auditQueryFields(opts.query),
                 results: rankedOut.length,
             },
         });
@@ -1348,16 +1346,19 @@ export function archiveRaw(ctx, id, reason, opts = {}) {
  * `src/server.ts` POST /v1/auth/keys mirrors this: it ignores any body
  * `tenantId` and uses the resolved Bearer's tenant exclusively.
  *
- * Only an admin actor can mint (ForbiddenError otherwise), so a member key
- * can never create a key, least of all an admin one.
+ * Only an admin actor can mint (ForbiddenError otherwise), and a key never
+ * outranks its minter: a resolver admin is tenant-only, so it mints members.
  */
 export function authCreate(ctx, opts) {
     if (ctx.actor.role !== 'admin') {
         throw new ForbiddenError('Only an admin key can create API keys');
     }
+    if (ctx.actor.viaAuthResolver && opts.role === 'admin') {
+        throw new ForbiddenError('A key minted through the auth resolver can only be a member key');
+    }
     const db = openHippoDb(ctx.hippoRoot);
     try {
-        const role = opts.role ?? 'admin';
+        const role = opts.role ?? (ctx.actor.viaAuthResolver ? 'member' : 'admin');
         const result = createApiKey(db, { tenantId: ctx.tenantId, label: opts.label, role });
         // v1.12.4: audit emit (closes the gap v1.12.3 CHANGELOG flagged as deferred).
         // Mirrors the auth_revoke pattern at authRevoke — same try/catch so audit
@@ -1408,10 +1409,10 @@ export function authRevoke(ctx, keyId) {
     }
     const db = openHippoDb(ctx.hippoRoot);
     try {
-        // SAFETY: row's shape matches the three columns named in the SELECT
+        // SAFETY: row's shape matches the four columns named in the SELECT
         // above.
         const row = db
-            .prepare(`SELECT key_id, tenant_id, revoked_at FROM api_keys WHERE key_id = ?`)
+            .prepare(`SELECT key_id, tenant_id, revoked_at, role FROM api_keys WHERE key_id = ?`)
             .get(keyId);
         if (!row) {
             throw new Error(`Unknown key_id: ${keyId}`);
@@ -1420,6 +1421,9 @@ export function authRevoke(ctx, keyId) {
         if (row.tenant_id !== ctx.tenantId) {
             throw new Error(`Unknown key_id: ${keyId}`);
         }
+        if (ctx.actor.viaAuthResolver && row.role === 'admin') {
+            throw new ForbiddenError('An auth resolver admin cannot revoke an admin key, which outranks it');
+        }
         let revokedAt;
         let alreadyRevoked = false;
         if (row.revoked_at) {
@@ -1930,7 +1934,7 @@ export async function getContext(ctx, opts = {}) {
         // 'recall' op emitted by api.recall for parity). pinnedOnly + '*' fallback
         // never hit the search engines, so they don't emit (matches cmdContext).
         const ctxRecallMetadata = {
-            query: query.slice(0, 200),
+            ...auditQueryFields(query),
             results: selectedItems.length,
             mode: 'context',
         };

package/dist/audit.d.ts

@@ -27,6 +27,11 @@ export interface AppendAuditOpts {
     targetId?: string;
     metadata?: unknown;
 }
+export type AuditQueryFields = {
+    query_hash: string;
+    query_length: number;
+};
+export declare function auditQueryFields(query: string): AuditQueryFields;
 export declare function appendAuditEvent(db: DatabaseSyncLike, opts: AppendAuditOpts): void;
 export interface QueryAuditOpts {
     tenantId: string;
@@ -44,4 +49,18 @@ export interface AuditEvent {
     metadata: JsonObject;
 }
 export declare function queryAuditEvents(db: DatabaseSyncLike, opts: QueryAuditOpts): AuditEvent[];
+export interface ListAuditAfterOpts {
+    /** Last id already consumed; 0 starts from the beginning. */
+    afterId: number;
+    /** Clamped to 1..10000; default 1000. */
+    limit?: number;
+    /** Omit for every tenant (deployment-wide export). */
+    tenantId?: string;
+}
+/**
+ * Cursor read: events with id > afterId, ascending by id. Ids are AUTOINCREMENT
+ * and never reused, but deletes (retention prune) leave gaps, so resume from
+ * the last id returned, never from a count.
+ */
+export declare function listAuditEventsAfter(db: DatabaseSyncLike, opts: ListAuditAfterOpts): AuditEvent[];
 //# sourceMappingURL=audit.d.ts.map

package/dist/audit.js

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import { canAutoDelete } from './memory.js';
 export const STOP_WORDS = new Set([
     'the', 'a', 'an', 'is', 'was', 'are', 'were', 'be', 'been', 'being',
@@ -240,6 +241,12 @@ function isBigIntValue(value) {
 function bigintSafeReplacer(_key, value) {
     return isBigIntValue(value) ? value.toString() : value;
 }
+export function auditQueryFields(query) {
+    return {
+        query_hash: createHash('sha256').update(query).digest('hex').slice(0, 16),
+        query_length: query.length,
+    };
+}
 export function appendAuditEvent(db, opts) {
     db.prepare(`INSERT INTO audit_log (ts, tenant_id, actor, op, target_id, metadata_json) VALUES (?, ?, ?, ?, ?, ?)`).run(new Date().toISOString(), opts.tenantId, opts.actor, opts.op, opts.targetId ?? null, JSON.stringify(opts.metadata ?? {}, bigintSafeReplacer));
 }
@@ -255,13 +262,40 @@ export function queryAuditEvents(db, opts) {
         params.push(opts.since);
     }
     const limit = Math.max(1, Math.min(opts.limit ?? 100, 10000));
-    // SAFETY: the SELECT above names exactly these six columns in this order, so the
-    // row shape matches this assertion.
+    // SAFETY: AUDIT_COLUMNS names exactly the AuditRow columns, in this order.
+    const rows = db
+        .prepare(`SELECT ${AUDIT_COLUMNS} FROM audit_log WHERE ${where.join(' AND ')} ORDER BY ts DESC, id DESC LIMIT ?`)
+        .all(...params, limit);
+    return rows.map(rowToAuditEvent);
+}
+/**
+ * Cursor read: events with id > afterId, ascending by id. Ids are AUTOINCREMENT
+ * and never reused, but deletes (retention prune) leave gaps, so resume from
+ * the last id returned, never from a count.
+ */
+export function listAuditEventsAfter(db, opts) {
+    if (!Number.isInteger(opts.afterId) || opts.afterId < 0) {
+        throw new RangeError('afterId must be a non-negative integer');
+    }
+    if (opts.limit !== undefined && !Number.isInteger(opts.limit)) {
+        throw new RangeError('limit must be an integer');
+    }
+    const where = ['id > ?'];
+    const params = [opts.afterId];
+    if (opts.tenantId !== undefined) {
+        where.push('+tenant_id = ?');
+        params.push(opts.tenantId);
+    }
+    const limit = Math.max(1, Math.min(opts.limit ?? 1000, 10000));
+    // SAFETY: AUDIT_COLUMNS names exactly the AuditRow columns, in this order.
     const rows = db
-        .prepare(`SELECT id, ts, tenant_id, actor, op, target_id, metadata_json
-       FROM audit_log WHERE ${where.join(' AND ')} ORDER BY ts DESC, id DESC LIMIT ?`)
+        .prepare(`SELECT ${AUDIT_COLUMNS} FROM audit_log WHERE ${where.join(' AND ')} ORDER BY id ASC LIMIT ?`)
         .all(...params, limit);
-    return rows.map((r) => ({
+    return rows.map(rowToAuditEvent);
+}
+const AUDIT_COLUMNS = 'id, ts, tenant_id, actor, op, target_id, metadata_json';
+function rowToAuditEvent(r) {
+    return {
         id: r.id,
         ts: r.ts,
         tenantId: r.tenant_id,
@@ -271,7 +305,7 @@ export function queryAuditEvents(db, opts) {
         op: r.op,
         targetId: r.target_id,
         metadata: safeJsonParse(r.metadata_json),
-    }));
+    };
 }
 function safeJsonParse(raw) {
     try {

package/dist/auth.d.ts

@@ -1,4 +1,6 @@
 import type { DatabaseSyncLike } from './db.js';
+/** Every minted API key starts with this, so the server can route a bearer token by shape. */
+export declare const API_KEY_PREFIX = "hk_";
 export declare function _dummyHashForTests(): string;
 export interface CreateApiKeyOpts {
     tenantId: string;

package/dist/auth.js

@@ -1,5 +1,6 @@
 import { randomBytes, scryptSync, timingSafeEqual } from 'node:crypto';
-const KEY_PREFIX = 'hk_';
+/** Every minted API key starts with this, so the server can route a bearer token by shape. */
+export const API_KEY_PREFIX = 'hk_';
 const ID_LEN = 24; // base32 chars after prefix
 const SECRET_LEN = 32; // base32 chars after dot
 const SCRYPT_KEYLEN = 32;
@@ -40,7 +41,7 @@ function verifyKey(plaintext, stored) {
     return expected.length === actual.length && timingSafeEqual(expected, actual);
 }
 export function createApiKey(db, opts) {
-    const keyId = `${KEY_PREFIX}${randBase32(ID_LEN)}`;
+    const keyId = `${API_KEY_PREFIX}${randBase32(ID_LEN)}`;
     const secret = randBase32(SECRET_LEN);
     const plaintext = `${keyId}.${secret}`;
     const hash = hashKey(plaintext);

package/dist/cli.js

@@ -81,7 +81,7 @@ import { importChatGPT, importClaude, importCursor, importGenericFile, importMar
 import { cmdCapture, cmdPreCompact, cmdPostCompact, resolveLastSessionTranscript, truncateCodePointSafe, sanitizeLogMessage, transcriptWorkingState } from './capture.js';
 import { COMPACTION_DB_WAIT_MS, replayCompactionsAt } from './compaction-record.js';
 import { readStdinBounded } from './stdin.js';
-import { auditMemories, appendAuditEvent, AUDIT_OPS, } from './audit.js';
+import { auditMemories, appendAuditEvent, auditQueryFields, AUDIT_OPS, } from './audit.js';
 import { listApiKeys, revokeApiKey } from './auth.js';
 import { buildProvenanceCoverage } from './provenance-coverage.js';
 import { buildCorrectionLatency } from './correction-latency.js';
@@ -1853,10 +1853,7 @@ async function cmdRecall(hippoRoot, query, flags) {
     }
     else if (process.env.HIPPO_ANCHORING !== 'off') {
         // SHA-256/16 per the recall-audit convention; hashQueryText is FNV-1a and brute-forceable on short queries.
-        emitCliAudit(hippoRoot, 'recall_anchor_skipped_no_session', undefined, {
-            query_hash: createHash('sha256').update(query).digest('hex').slice(0, 16),
-            query_length: query.length,
-        });
+        emitCliAudit(hippoRoot, 'recall_anchor_skipped_no_session', undefined, auditQueryFields(query));
     }
     if (cmdAnchoringHint?.reason === 'memory_dominance') {
         emitCliAudit(hippoRoot, 'recall_anchor_detected_memory_dominance', cmdAnchoringHint.memoryId, {
@@ -1878,7 +1875,7 @@ async function cmdRecall(hippoRoot, query, flags) {
     }
     // A5 audit: one 'recall' event per query, before the early-empty return, in every participating store.
     const recallMetadata = {
-        query: query.slice(0, 200),
+        ...auditQueryFields(query),
         results: results.length,
     };
     emitCliAudit(hippoRoot, 'recall', undefined, recallMetadata);
@@ -8776,7 +8773,7 @@ Commands:
     --budget <n>           Token budget for the whole printed block (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)
+    (the hook payload's "prompt" drives prompt recall instead of --include-recent when pinnedInject.promptRecall is on, the default)
     --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

@@ -71,8 +71,8 @@ export interface HippoConfig {
          *  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). */
+         *  the five newest memories. Default true since 1.55.0: overlap tied but median
+         *  tokens fell 847 to 533 (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;

package/dist/config.js

@@ -47,7 +47,7 @@ const DEFAULT_CONFIG = {
         budget: 1500,
         skipUnchanged: true,
         refreshTurns: 10,
-        promptRecall: false,
+        promptRecall: true,
         promptRecallMetric: 'jaccard',
         promptRecallThreshold: 0.04,
         promptRecallMinShared: 2,

package/dist/hooks.d.ts

@@ -156,7 +156,7 @@ export declare function codexHomeDir(home?: string, env?: Readonly<Record<string
 /** Codex counts as installed only when its config folder exists: Codex itself refuses a CODEX_HOME that is not a folder. */
 export declare function isCodexPresent(home?: string): boolean;
 /** Codex hashes each hook and skips new or changed ones until the user reviews them in `/hooks`, so the reminder says what they would trust. */
-export declare const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus the five most recent ones. Codex runs hippo's hooks only after you trust them once in `/hooks`.";
+export declare const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus up to 5 that match the prompt. Codex runs hippo's hooks only after you trust them once in `/hooks`.";
 /**
  * Default log path consumed by `hippo last-sleep`. Shared fallback when
  * a caller doesn't pass --path explicitly.

package/dist/hooks.js

@@ -134,7 +134,7 @@ export function isCodexPresent(home = homeDir()) {
     return fs.statSync(codexHomeDir(home), { throwIfNoEntry: false })?.isDirectory() === true;
 }
 /** Codex hashes each hook and skips new or changed ones until the user reviews them in `/hooks`, so the reminder says what they would trust. */
-export const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus the five most recent ones. Codex runs hippo's hooks only after you trust them once in `/hooks`.";
+export const CODEX_TRUST_LINE = "The per-prompt hook sends your pinned memories plus up to 5 that match the prompt. Codex runs hippo's hooks only after you trust them once in `/hooks`.";
 /**
  * Default log path consumed by `hippo last-sleep`. Shared fallback when
  * a caller doesn't pass --path explicitly.

package/dist/index.d.ts

@@ -21,4 +21,6 @@ export { importChatGPT, importClaude, importCursor, importGenericFile, importMar
 export { runFeatureEval, formatResult, resultToBaseline, detectRegressions, buildSyntheticCorpus, } from './eval-suite.js';
 export { computeSalience, SalienceDecision, SalienceResult, SalienceOptions, } from './salience.js';
 export { computeAmbientState, renderAmbientSummary, formatAmbientVector, AmbientState, } from './ambient.js';
+export { appendAuditEvent, queryAuditEvents, listAuditEventsAfter, AUDIT_OPS, type AuditEvent, type AuditOp, type QueryAuditOpts, type ListAuditAfterOpts, } from './audit.js';
+export { openHippoDb, openHippoDbReadOnly, closeHippoDb, type DatabaseSyncLike } from './db.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -34,4 +34,6 @@ export { runFeatureEval, formatResult, resultToBaseline, detectRegressions, buil
 export { computeSalience, } from './salience.js';
 // Pineal gland: ambient state vector
 export { computeAmbientState, renderAmbientSummary, formatAmbientVector, } from './ambient.js';
+export { appendAuditEvent, queryAuditEvents, listAuditEventsAfter, AUDIT_OPS, } from './audit.js';
+export { openHippoDb, openHippoDbReadOnly, closeHippoDb } from './db.js';
 //# sourceMappingURL=index.js.map

package/dist/mcp/server.d.ts

@@ -50,6 +50,7 @@ export interface McpContext {
     role?: 'admin' | 'member';
     /** EI2: scope grants for the HTTP-MCP caller's key. Absent for stdio (admin, needs none). */
     scopes?: readonly string[];
+    viaAuthResolver?: true;
     /**
      * Per-client key for state isolation under HTTP-MCP. For stdio: 'stdio-${pid}'
      * (one process = one client). For HTTP-SSE / HTTP MCP: hash(bearer + remoteAddr)

package/dist/mcp/server.js

@@ -25,9 +25,8 @@ import { recall as apiRecall, remember as apiRemember, outcome as apiOutcome, dr
 import { assertScopeRequestAllowed } from '../recall-scope.js';
 import { resolveProjectIdentity, classifyOriginProject, findHippoStoreDir } from '../project-identity.js';
 import { computePredictionBaserate } from '../predictions.js';
-import { appendAuditEvent } from '../audit.js';
+import { appendAuditEvent, auditQueryFields } from '../audit.js';
 import { RejectedValueError } from '../rejection.js';
-import { createHash } from 'node:crypto';
 import { detectAnchoring, hashQueryText, buildSessionKey, getOrCreateRing, appendRecall, snapshotRing, } from '../recall-history.js';
 import { detectAvailabilityBias } from '../availability.js';
 // v0.33 / J1 — Module-level per-(tenant, session) recall-history ring map
@@ -58,7 +57,10 @@ export function findHippoRoot(cwd = process.cwd(), opts) {
  * a member key never acts as admin through MCP.
  */
 function mcpActor(ctx) {
-    return { subject: ctx?.actor ?? 'mcp', role: ctx?.role ?? 'admin', scopes: ctx?.scopes };
+    const actor = { subject: ctx?.actor ?? 'mcp', role: ctx?.role ?? 'admin', scopes: ctx?.scopes };
+    if (ctx?.viaAuthResolver)
+        actor.viaAuthResolver = true;
+    return actor;
 }
 // MCP stdio transport spec: messages are newline-delimited JSON-RPC, no embedded newlines.
 // https://modelcontextprotocol.io/specification/.../basic/transports#stdio
@@ -738,10 +740,7 @@ async function executeTool(name, args, ctx) {
                             actor: ctx?.actor ?? 'mcp',
                             op: 'recall_anchor_skipped_no_session',
                             targetId: undefined,
-                            metadata: {
-                                query_hash: createHash('sha256').update(query).digest('hex').slice(0, 16),
-                                query_length: query.length,
-                            },
+                            metadata: auditQueryFields(query),
                         });
                     }
                     finally {

package/dist/server.d.ts

@@ -11,8 +11,22 @@ export interface ServerHandle {
      *  flow outside tests. */
     server?: import('node:http').Server;
 }
+/** Identity an {@link AuthResolver} vouches for. The core sanitises it before use. */
+export interface ResolvedBearer {
+    tenantId: string;
+    subject: string;
+    /** Not 'admin' means 'member'. Admin is tenant-only, yet can mint member API keys (POST /v1/auth/keys) that outlive IdP deprovisioning. */
+    role: 'admin' | 'member';
+    scopes?: readonly string[];
+}
+/** Sole judge of non-`hk_` bearer tokens: null is a 401; a throw or missed deadline is a 503, so throw only when upstream is down. */
+export type AuthResolver = (token: string) => ResolvedBearer | null | Promise<ResolvedBearer | null>;
 export interface ServeOpts {
     hippoRoot: string;
+    /** Runs on every request and SSE heartbeat, so keep it cache-backed; API keys never reach it. */
+    authResolver?: AuthResolver;
+    /** Deadline for one authResolver call; defaults to 5000 ms. */
+    authResolverTimeoutMs?: number;
     port?: number;
     host?: string;
     /** Stop and exit on SIGINT/SIGTERM. Only `hippo serve` owns the process, so only it sets this. */