hippo-memory 1.70.0 → 1.71.0

package/dist/api/instruction-detect.js

@@ -5,10 +5,19 @@ const INSTRUCTION_PATTERNS = [
     { name: 'chat-role-markup', re: /<\|im_start\|>|<\|system\|>|\[INST\]|<\/?system>|###\s*system\s*:/i },
     { name: 'system-prompt-reference', re: /\b(?:(?:override|ignore|bypass|replace|reveal)\b[^.\n]{0,40}\b(?:system prompt|developer message)|(?:system prompt|developer message)\b[^.\n]{0,40}\b(?:override|ignore|bypass|replace|reveal))\b/i },
     // "always"/"never" alone (ordinary PR prose) doesn't flag without an agent-facing target nearby too.
-    { name: 'standing-order', re: /\b(?:from now on|whenever you|always|never)\b[^.\n]{0,50}\b(?:you must|(?:the ai|the assistant|the agent|claude|copilot)\s+(?:must|should|will)\b)/i },
+    {
+        name: 'standing-order',
+        re: /\b(?:from now on|whenever you|always|never)\b[^.\n]{0,50}\b(?:you must|(?:the ai|the assistant|the agent|claude|copilot)\s+(?:must|should|will)\b)/i
+    },
     { name: 'concealment', re: /\b(?:do not|never|don't)\b[^.\n]{0,40}\b(?:tell|mention|reveal)\b[^.\n]{0,40}\bthe user\b/i },
-    { name: 'remote-script-exec', re: /\b(?:curl|wget)\b[^\n|]{0,80}\|\s*(?:sudo\s+)?(?:sh|bash|zsh)\b|\biex\s*\(\s*(?:iwr|invoke-webrequest|new-object\s+net\.webclient)/i },
-    { name: 'exfiltration', re: /\b(?:send|post|upload|exfiltrate)\b[^.\n]{0,40}\b(?:secrets?|tokens?|api[- ]?keys?|credentials?|env(?:ironment)? variables?)\b/i },
+    {
+        name: 'remote-script-exec',
+        re: /\b(?:curl|wget)\b[^\n|]{0,80}\|\s*(?:sudo\s+)?(?:sh|bash|zsh)\b|\biex\s*\(\s*(?:iwr|invoke-webrequest|new-object\s+net\.webclient)/i
+    },
+    {
+        name: 'exfiltration',
+        re: /\b(?:send|post|upload|exfiltrate)\b[^.\n]{0,40}\b(?:secrets?|tokens?|api[- ]?keys?|credentials?|env(?:ironment)? variables?)\b/i
+    },
     { name: 'unicode-tag-chars', re: /[\u{E0000}-\u{E007F}]/u },
 ];
 // A stray zero-width char has legitimate uses (ZWJ); only a run of 3+ adjacent ones reads as smuggling.
@@ -22,8 +31,10 @@ const NAMED_REFERENCES = new Map([['amp', '&'], ['lt', '<'], ['gt', '>'], ['quot
 const INVISIBLE_RE = /[\u034F\u00AD\u180E\u200B-\u200F\u202A-\u202E\u2060-\u2064\u2066-\u2069\uFEFF]/g;
 // Cyrillic, then Greek, letters drawn like a c e i j o p s x y; closed at those, so Russian or Greek prose folds into no phrase a pattern names.
 const LOOKALIKES = new Map([
-    ['\u0430', 'a'], ['\u0441', 'c'], ['\u0435', 'e'], ['\u0456', 'i'], ['\u0458', 'j'], ['\u043E', 'o'], ['\u0440', 'p'], ['\u0455', 's'], ['\u0445', 'x'], ['\u0443', 'y'],
-    ['\u0410', 'A'], ['\u0421', 'C'], ['\u0415', 'E'], ['\u0406', 'I'], ['\u0408', 'J'], ['\u041E', 'O'], ['\u0420', 'P'], ['\u0405', 'S'], ['\u0425', 'X'], ['\u0423', 'Y'],
+    ['\u0430', 'a'], ['\u0441', 'c'], ['\u0435', 'e'], ['\u0456', 'i'], ['\u0458', 'j'], ['\u043E', 'o'], ['\u0440', 'p'], ['\u0455', 's'],
+    ['\u0445', 'x'], ['\u0443', 'y'],
+    ['\u0410', 'A'], ['\u0421', 'C'], ['\u0415', 'E'], ['\u0406', 'I'], ['\u0408', 'J'], ['\u041E', 'O'], ['\u0420', 'P'], ['\u0405', 'S'],
+    ['\u0425', 'X'], ['\u0423', 'Y'],
     ['\u03B1', 'a'], ['\u03B5', 'e'], ['\u03B9', 'i'], ['\u03F3', 'j'], ['\u03BF', 'o'], ['\u03C1', 'p'], ['\u03C7', 'x'], ['\u03B3', 'y'],
     ['\u0391', 'A'], ['\u0395', 'E'], ['\u0399', 'I'], ['\u037F', 'J'], ['\u039F', 'O'], ['\u03A1', 'P'], ['\u03A7', 'X'], ['\u03A5', 'Y'],
 ]);

package/dist/api/ledger-db.d.ts

@@ -7,7 +7,8 @@ export interface LedgerRootOpts {
 }
 /** `hippoRoot` when it holds a store, else the global store (the prompt hook fires where no local one exists), else null. */
 export declare function ledgerRoot(hippoRoot: string, opts?: LedgerRootOpts): string | null;
-/** Says why a ledger row did not land, at the level its class earns: busy warns once through noteStoreBusy, absent is debug with no stack, unexpected warns once with the error class and stack. */
+/** Says why a ledger row did not land, at the level its class earns: busy warns once through
+ * noteStoreBusy, absent is debug with no stack, unexpected warns once with the error class and stack. */
 export declare function noteLedgerRowSkipped<E>(error: E): void;
 /** Books one row in ledgerRoot's store, best-effort. */
 export declare function bookTokenUse(hippoRoot: string, use: TokenUse, opts?: LedgerRootOpts): void;

package/dist/api/ledger-db.js

@@ -1,7 +1,7 @@
 // The store the token ledger writes to for a caller's root; context, recall and the session hooks share it.
 import { isSqliteBusy, noteStoreBusy } from '../db/index.js';
 import { errorFields, errorMessage, log } from '../util/log.js';
-import { getGlobalRoot } from '../sharing/shared.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
 import { lastSentOnSurface, recordLedgerTurn } from '../store/ledger-turn.js';
 import { isInitialized, onHandle } from '../store/open.js';
 import { sqliteSyncStore } from '../store/sqlite/store.js';
@@ -17,7 +17,8 @@ export function ledgerRoot(hippoRoot, opts) {
 // SQLite's result codes for a hippo.db it cannot read: a corrupt image, and a file that is no database.
 const SQLITE_CORRUPT = 11;
 const SQLITE_NOTADB = 26;
-/** The one rule for a skipped ledger row. `absent` is a store with no token_ledger table or a hippo.db SQLite cannot read; the command that owns the store reports that, and a hook must stay quiet about it. */
+/** The one rule for a skipped ledger row. `absent` is a store with no token_ledger table or a hippo.db
+ * SQLite cannot read; the command that owns the store reports that, and a hook must stay quiet about it. */
 function ledgerSkipClass(error) {
     if (isSqliteBusy(error))
         return 'busy';
@@ -26,7 +27,8 @@ function ledgerSkipClass(error) {
         return 'absent';
     return errorMessage(error).includes('no such table: token_ledger') ? 'absent' : 'unexpected';
 }
-/** Says why a ledger row did not land, at the level its class earns: busy warns once through noteStoreBusy, absent is debug with no stack, unexpected warns once with the error class and stack. */
+/** Says why a ledger row did not land, at the level its class earns: busy warns once through
+ * noteStoreBusy, absent is debug with no stack, unexpected warns once with the error class and stack. */
 export function noteLedgerRowSkipped(error) {
     const skip = ledgerSkipClass(error);
     if (skip === 'busy') {

package/dist/api/memories.d.ts

@@ -0,0 +1,5 @@
+import type { MemoryEntry } from '../core/memory.js';
+import type { Context } from './types.js';
+/** The row `id` in the caller's tenant, or null when it is missing or another tenant's. */
+export declare function getMemory(ctx: Context, id: string): Promise<MemoryEntry | null>;
+//# sourceMappingURL=memories.d.ts.map

package/dist/api/memories.js

@@ -0,0 +1,7 @@
+import { storeFor } from '../store/index.js';
+/** The row `id` in the caller's tenant, or null when it is missing or another tenant's. */
+export async function getMemory(ctx, id) {
+    const [entry] = await storeFor(ctx).entriesByIds([id], ctx.tenantId);
+    return entry ?? null;
+}
+//# sourceMappingURL=memories.js.map

package/dist/api/objects.d.ts

@@ -0,0 +1,9 @@
+import type { SavableDescriptor } from '../objects/descriptor.js';
+import type { ObjectByKind, SavableKind } from '../store/object-types.js';
+import type { Objects } from '../store/port.js';
+import type { Context } from './types.js';
+/** The request store's object group; the dispatcher has already answered 501 for a store without it. */
+export declare function objectsOf(ctx: Context): Objects;
+/** Saves through the request's store as the authenticated caller. */
+export declare function saveFor<K extends SavableKind, W>(ctx: Context, d: SavableDescriptor<K, W>, write: W): Promise<ObjectByKind[K]>;
+//# sourceMappingURL=objects.d.ts.map

package/dist/api/objects.js

@@ -0,0 +1,11 @@
+import { saveObject } from '../objects/lifecycle.js';
+import { requireGroup, storeFor } from '../store/index.js';
+/** The request store's object group; the dispatcher has already answered 501 for a store without it. */
+export function objectsOf(ctx) {
+    return requireGroup(storeFor(ctx), 'objects');
+}
+/** Saves through the request's store as the authenticated caller. */
+export function saveFor(ctx, d, write) {
+    return saveObject(objectsOf(ctx), d, { hippoRoot: ctx.hippoRoot, tenantId: ctx.tenantId, actor: ctx.actor.subject }, write);
+}
+//# sourceMappingURL=objects.js.map

package/dist/api/on-store.js

@@ -12,7 +12,8 @@ export function andThen(reply, next) {
 export function notPorted(port, group) {
     throw new StoreNotPortedError(port.kind, group);
 }
-/** A served store's stand-in for SqliteLocal. The last recall sits in hippo.db's meta table, so only a store that is hippo.db keeps and reads it, on `hippoRoot`. */
+/** A served store's stand-in for SqliteLocal. The last recall sits in hippo.db's
+ * meta table, so only a store that is hippo.db keeps and reads it, on `hippoRoot`. */
 function servedLocal(store, hippoRoot) {
     if (store.kind === 'sqlite')
         return { ...sqliteLocal(hippoRoot), ...REFUSED_ON_A_STORE };
@@ -21,7 +22,7 @@ function servedLocal(store, hippoRoot) {
         applyOutcomeToLastRecall() {
             throw new SqliteBlockedError(store.kind);
         },
-        finishLastRecall: (writes) => store.finishRecall(writes),
+        finishLastRecall: (writes) => store.finishRecall(writes).then(() => null),
     };
 }
 /** Runs `run` on `ctx.store`, where a throw rejects, else on hippo.db under `ctx.hippoRoot`, where it throws. The store path never reads `hippoRoot`.
@@ -30,7 +31,8 @@ export function onStore(ctx, run) {
     const { store } = ctx;
     // No await before `run`: an add-on relies on the first port call starting inside this call.
     const reply = store ? (async () => run(store, servedLocal(store, ctx.hippoRoot)))() : run(sqliteSyncStore(ctx.hippoRoot), sqliteLocal(ctx.hippoRoot));
-    // SAFETY: the store path is an async function's Promise and hippo.db's port calls answer values, so the Promise comes back exactly when ctx has a store, as StoreReply says.
+    // SAFETY: the store path is an async function's Promise and hippo.db's port calls answer
+    // values, so the Promise comes back exactly when ctx has a store, as StoreReply says.
     return reply;
 }
 //# sourceMappingURL=on-store.js.map

package/dist/api/predictions.d.ts

@@ -0,0 +1,9 @@
+import type { Prediction, PredictionBaserate } from '../store/predictions.js';
+import type { PredictionClose, PredictionSave, Predictions } from '../store/port.js';
+import type { Context } from './types.js';
+export declare function savePrediction(ctx: Context, input: PredictionSave): Promise<Prediction>;
+export declare function listPredictions(ctx: Context, query: Parameters<Predictions['listPredictions']>[1]): Promise<Prediction[]>;
+export declare function predictionBaserate(ctx: Context, classTag: string): Promise<PredictionBaserate>;
+export declare function predictionById(ctx: Context, id: number): Promise<Prediction | null>;
+export declare function closePrediction(ctx: Context, id: number, close: PredictionClose): Promise<Prediction>;
+//# sourceMappingURL=predictions.d.ts.map

package/dist/api/predictions.js

@@ -0,0 +1,18 @@
+import { requireGroup, storeFor } from '../store/index.js';
+const predictionsOf = (ctx) => requireGroup(storeFor(ctx), 'predictions');
+export async function savePrediction(ctx, input) {
+    return predictionsOf(ctx).savePrediction(ctx.tenantId, input, ctx.actor.subject);
+}
+export async function listPredictions(ctx, query) {
+    return predictionsOf(ctx).listPredictions(ctx.tenantId, query);
+}
+export async function predictionBaserate(ctx, classTag) {
+    return predictionsOf(ctx).predictionBaserate(ctx.tenantId, classTag, ctx.actor.subject);
+}
+export async function predictionById(ctx, id) {
+    return predictionsOf(ctx).predictionById(ctx.tenantId, id);
+}
+export async function closePrediction(ctx, id, close) {
+    return predictionsOf(ctx).closePrediction(ctx.tenantId, id, close, ctx.actor.subject);
+}
+//# sourceMappingURL=predictions.js.map

package/dist/api/promote.d.ts

@@ -1,33 +1,29 @@
 import type { ConnectorEvent } from '../store/port.js';
+import { type Layer } from '../core/memory.js';
 import type { Context, StoreReply } from './types.js';
-/**
- * Copy a local memory into the global store. Mirrors `cmdPromote` in cli.ts:
- * the `writeEntry` inside `promoteToGlobal` emits a 'remember' on the global
- * db; we add a 'promote' audit event on the global db so the user-facing
- * intent stays distinct from the underlying upsert.
- *
- * Note: `promoteToGlobal` does not currently take a tenantId override — it
- * reads the entry from the local root via `readEntry` (no tenant filter) and
- * preserves the entry's existing tenantId on the global side.
- */
+/** Copies a local memory into the global store; the inner writeEntry emits 'remember' there, and we add a 'promote' audit event so intent stays distinct.
+ * promoteToGlobal reads via `readEntry` with no tenant filter and keeps the entry's existing tenantId on the global side. */
 export interface PromoteResult {
     ok: true;
     sourceId: string;
     globalId: string;
 }
 export declare function promote(ctx: Context, id: string): PromoteResult;
-/**
- * Replace an old memory with new content, chaining old.superseded_by = new.id.
- * Mirrors `cmdSupersede` in cli.ts minus the flag-driven layer/tag/pin
- * overrides: the CLI handler resolves those so the API stays minimal.
- */
+/** Replace an old memory with new content, chaining old.superseded_by = new.id; the store commits both rows and the audit row together. */
 export interface SupersedeResult {
     ok: true;
     oldId: string;
     newId: string;
 }
-export declare function supersede<C extends Context>(ctx: C, oldId: string, newContent: string): StoreReply<C, SupersedeResult>;
-/** Archive a kind='raw' memory: its metadata moves to raw_archive and the row is deleted. The store writes the one archive_raw audit row, under the caller's subject. */
+/** What the successor takes instead of the old row's value. Never set from a request body: the CLI fills it from its flags. */
+export interface SupersedeOverrides {
+    layer?: Layer;
+    tags?: string[];
+    pinned?: boolean;
+}
+export declare function supersede<C extends Context>(ctx: C, oldId: string, newContent: string, overrides?: SupersedeOverrides): StoreReply<C, SupersedeResult>;
+/** Archive a kind='raw' memory: its metadata moves to raw_archive and the row is
+ * deleted. The store writes the one archive_raw audit row, under the caller's subject. */
 export interface ArchiveRawOpts {
     /** The connector event this archive answers. The store logs it in the archive's own transaction, so a redelivery finds it logged. */
     event?: ConnectorEvent;

package/dist/api/promote.js

@@ -1,29 +1,18 @@
 // Promote to the global store, supersede with a successor, and archive raw memories.
-import { openHippoDb, closeHippoDb } from '../db/index.js';
 import { ConflictError, NotFoundError } from '../core/api-errors.js';
 import { stampOriginProject } from '../store/entry-row.js';
 import { createSuccessor } from '../core/memory.js';
-import { promoteToGlobal } from '../sharing/shared.js';
+import { promoteToGlobal } from '../sharing/global-store.js';
 import { loadConfig } from '../core/config.js';
 import { andThen, notPorted, onStore } from './on-store.js';
-import { selectMemoryReach } from '../store/tenant-lookup.js';
+import { memoryReach } from '../store/tenant-lookup.js';
 import { canTouchScope, personalScopeOf } from '../store/recall-scope.js';
 export function promote(ctx, id) {
-    // Tenant scope: promoteToGlobal reads the entry from the local root via
-    // readEntry without a tenant filter, so a Bearer for tenant A could
-    // promote tenant B's row by guessing or leaking the id. Pre-check the
-    // row's tenant_id and deny cross-tenant access with the same not-found
-    // wording archiveRaw uses (no info leak about whether the id exists in
-    // another tenant).
-    const ownerDb = openHippoDb(ctx.hippoRoot);
-    try {
-        const reach = selectMemoryReach(ownerDb, id);
-        if (reach?.tenantId !== ctx.tenantId || !canTouchScope(ctx.actor, reach.scope)) {
-            throw new NotFoundError(`memory not found: ${id}`);
-        }
-    }
-    finally {
-        closeHippoDb(ownerDb);
+    // promoteToGlobal reads without a tenant filter, so pre-check the row's tenant_id and deny cross-tenant access with archiveRaw's not-found wording
+    // (no leak about whether the id exists in another tenant).
+    const reach = memoryReach(ctx.hippoRoot, id);
+    if (reach?.tenantId !== ctx.tenantId || !canTouchScope(ctx.actor, reach.scope)) {
+        throw new NotFoundError(`memory not found: ${id}`);
     }
     // The 'promote' row commits with the global copy, so no write follows the commit and a busy store fails the whole promote.
     const globalEntry = promoteToGlobal(ctx.hippoRoot, id, {
@@ -33,13 +22,16 @@ export function promote(ctx, id) {
     });
     return { ok: true, sourceId: id, globalId: globalEntry.id };
 }
-export function supersede(ctx, oldId, newContent) {
+export function supersede(ctx, oldId, newContent, overrides = {}) {
     return onStore(ctx, (port) => {
         const entryWrites = port.entryWrites ?? notPorted(port, 'entryWrites');
         return andThen(port.entriesByIds([oldId], ctx.tenantId), ([old]) => {
             const newEntry = createSuccessor(assertSupersedable(ctx, oldId, old ?? null), newContent, {
                 tenantId: ctx.tenantId,
                 baseHalfLifeDays: loadConfig(ctx.hippoRoot).defaultHalfLifeDays,
+                layer: overrides.layer,
+                tags: overrides.tags,
+                pinned: overrides.pinned,
             });
             // A store writes origin_project as given, so the served folder's fallback is stamped here.
             const successor = stampOriginProject(ctx.hippoRoot, newEntry);

package/dist/api/prompt-hook.d.ts

@@ -58,10 +58,10 @@ interface PromptHookOpts {
 }
 /** The caps on a hook caller's session id and project names, so a caller other than an HTTP route is bounded too. */
 export declare function assertCallerIds(sessionId: string, project: CallerProject): void;
-/** The text `hippo context --pinned-only --include-recent 5 --format additional-context` prints for this session, read on `ctx`'s store for the caller's project, leaving out an unchanged static block only when `printedHash` matches it.
- *  `arm` is the raw ledger arm (`hippo` or `holdout`), null at rate 0; a holdout session gets an empty stdout. `staticHash` is the hash to echo back: null with no static block, for a sub-agent or a holdout.
- *  Scope detection (HIPPO_SCOPE and skill env vars) and delivery-ledger events are CLI-only.
- *  Throws BadRequestError past the input caps, and on a shared store for a project assertCallerProject refuses, before any arm is booked. */
+/** The text `hippo context --pinned-only --include-recent 5 --format additional-context` prints for this session, read on `ctx`'s store for its project.
+ * Omits an unchanged static block only when `printedHash` matches; `arm` is the ledger arm (`hippo` or `holdout`, null at rate 0); a holdout gets empty stdout.
+ * `staticHash` is the hash to echo back (null with no static block, a sub-agent or a holdout). Scope detection and delivery-ledger events are CLI-only.
+ * Throws BadRequestError past the input caps, and on a shared store for a project assertCallerProject refuses, before any arm is booked. */
 export declare function promptHookContext(ctx: Context, req: PromptHookRequest, opts?: PromptHookOpts): Promise<{
     arm: PilotArm | null;
     stdout: string;

package/dist/api/prompt-hook.js

@@ -1,5 +1,6 @@
 // The per-prompt hook's block and ledger rows, rendered here for `hippo context` and for promptHookContext (a remote hook route's call).
-// promptHookContext keeps the server-side copy of the CLI's getContext flags (cli/context.ts); the CLI parity case in tests/prompt-hook-context.test.ts is all that ties the two.
+// promptHookContext keeps the server-side copy of the CLI's getContext flags (cli/context.ts);
+// the CLI parity case in tests/prompt-hook-context.test.ts is all that ties the two.
 import { getContext } from './index.js';
 import { BadRequestError } from '../core/api-errors.js';
 import { isSharedStore, loadConfig } from '../core/config.js';
@@ -12,7 +13,8 @@ import { assertCallerProject, MAX_PROJECT_ALIASES } from '../core/project-identi
 import { writeDeliveryEventAtRoot } from '../store/recall-trace.js';
 import { hookPayloadString, isSubagentPayload, shouldSkipUnchanged, } from '../store/token-ledger.js';
 import { blockHash, estimateTokens } from '../util/token-text.js';
-import { errorMessage } from '../util/log.js';
+import { errorMessage, log } from '../util/log.js';
+import { DEFAULT_CONTEXT_BUDGET } from './context.js';
 /** With `write`, stores on the token ledger's connection (same store); without it, opens its own. A second flush is a no-op. */
 export function flushDeliveryRecorder(rec, write) {
     if (rec === null)
@@ -21,8 +23,7 @@ export function flushDeliveryRecorder(rec, write) {
         rec.flush(write ?? ((input) => writeDeliveryEventAtRoot(rec.root, input)));
     }
     catch (error) {
-        // The hook's one-line stderr contract pins this exact text, so it bypasses the leveled logger.
-        console.error(`[hippo] delivery ledger write failed:${errorMessage(error)}`);
+        log.error(`delivery ledger write failed: ${errorMessage(error)}`);
     }
 }
 /** A Copilot sessionStart reply's wrapper, picked by the sender's casing: stdin.ts keeps a camelCase `sessionId`, which only the Copilot harness sends. */
@@ -143,7 +144,7 @@ function recordAdditionalContextRows(view, surface, staticPart, recallPart) {
 }
 // The flags HIPPO_PINNED_INJECT_COMMAND gives the local hook; the CLI parity test fails if the two drift.
 const HOOK_INCLUDE_RECENT = 5;
-const HOOK_BUDGET = 1500;
+const HOOK_BUDGET = DEFAULT_CONTEXT_BUDGET;
 const HOOK_FRAMING = 'observe';
 // blockHash's shape (token-ledger.ts).
 const BLOCK_HASH_RE = /^[0-9a-f]{16}$/;
@@ -162,10 +163,10 @@ function assertPromptHookRequest(req) {
         throw new BadRequestError('printed hash: 16 lowercase hex characters');
     }
 }
-/** The text `hippo context --pinned-only --include-recent 5 --format additional-context` prints for this session, read on `ctx`'s store for the caller's project, leaving out an unchanged static block only when `printedHash` matches it.
- *  `arm` is the raw ledger arm (`hippo` or `holdout`), null at rate 0; a holdout session gets an empty stdout. `staticHash` is the hash to echo back: null with no static block, for a sub-agent or a holdout.
- *  Scope detection (HIPPO_SCOPE and skill env vars) and delivery-ledger events are CLI-only.
- *  Throws BadRequestError past the input caps, and on a shared store for a project assertCallerProject refuses, before any arm is booked. */
+/** The text `hippo context --pinned-only --include-recent 5 --format additional-context` prints for this session, read on `ctx`'s store for its project.
+ * Omits an unchanged static block only when `printedHash` matches; `arm` is the ledger arm (`hippo` or `holdout`, null at rate 0); a holdout gets empty stdout.
+ * `staticHash` is the hash to echo back (null with no static block, a sub-agent or a holdout). Scope detection and delivery-ledger events are CLI-only.
+ * Throws BadRequestError past the input caps, and on a shared store for a project assertCallerProject refuses, before any arm is booked. */
 export async function promptHookContext(ctx, req, opts = {}) {
     assertPromptHookRequest(req);
     const { sessionId, payload } = req;

package/dist/api/recall-cli.d.ts

@@ -0,0 +1,55 @@
+import { confidenceFacets } from '../core/memory.js';
+import type { ResultCost, SearchResult } from '../core/search-types.js';
+import type { RerankerFn } from '../rerankers/types.js';
+import { explainMatch } from '../search/explain.js';
+import type { ContinuityBlock } from '../store/port.js';
+import type { Context } from './types.js';
+export { DEFAULT_MAX_NEIGHBORS, MAX_HOPS } from '../graph/recall.js';
+/** The global store beside this one, whether this one is it, and the scope that boosts rows. */
+export interface CliRecallSetting {
+    readonly globalRoot: string;
+    readonly primaryIsGlobal: boolean;
+    readonly activeScope: string | null;
+}
+/** The active scope merges `--scope` with the detected one, which only boosts. */
+export declare function cliRecallSetting(ctx: Context, explicitScope: string | null): CliRecallSetting;
+export interface CliRecallOrigin {
+    readonly globalOn: boolean;
+    /** True when a ranked row came from the global store: this store is it, or the global store is on and this one lacks the id. */
+    readonly isGlobal: (id: string) => boolean;
+}
+export declare function cliRecallOrigin(ctx: Context, setting: CliRecallSetting): CliRecallOrigin;
+/** The active snapshot, its session's latest handoff and last five events, each kept only when its scope passes. */
+export declare function loadCliRecallContinuity(ctx: Context, setting: CliRecallSetting, wanted: boolean): ContinuityBlock;
+export interface CliRecallRerankerPick {
+    readonly fn: RerankerFn;
+    readonly defaultTopK: number;
+}
+/** The reranker a `--reranker` name picks and the top-k it takes by default; an unknown name throws, a blank one picks none. */
+export declare function cliRecallReranker(name: string): CliRecallRerankerPick | null;
+/** The ranked rows a print budget holds, best first; the first `floor` stay whatever they cost. */
+export declare function fitRecallRows(ranked: SearchResult[], budget: number, floor: number, cost: ResultCost): SearchResult[];
+/** One result row; the optional keys are set in the order the JSON prints them. */
+export interface RecallJsonRow {
+    id: string;
+    score: number;
+    strength: SearchResult['entry']['strength'];
+    tokens: number;
+    tags: SearchResult['entry']['tags'];
+    content: string;
+    layer: SearchResult['entry']['layer'];
+    trace_outcome?: SearchResult['entry']['trace_outcome'];
+    superseded?: boolean;
+    superseded_by?: SearchResult['entry']['superseded_by'];
+    graphVia?: SearchResult['graphVia'];
+    confidence?: ReturnType<typeof confidenceFacets>['tier'];
+    aged_out?: ReturnType<typeof confidenceFacets>['agedOut'];
+    source?: 'global' | 'local';
+    reason?: ReturnType<typeof explainMatch>['reason'];
+    bm25?: SearchResult['bm25'];
+    cosine?: SearchResult['cosine'];
+    envelope?: ReturnType<typeof explainMatch>['envelope'];
+    rerankTrace?: SearchResult['rerankTrace'];
+}
+export declare function recallJsonRow(r: SearchResult, query: string, showWhy: boolean, isGlobal: boolean): RecallJsonRow;
+//# sourceMappingURL=recall-cli.d.ts.map

package/dist/api/recall-cli.js

@@ -0,0 +1,94 @@
+// What the `hippo recall` verb reads beside its ranking core: the stores it searches, the resume packet and the JSON rows.
+import { confidenceFacets, Layer } from '../core/memory.js';
+import { isGlobalStoreRoot } from '../core/project-identity.js';
+import { getReranker } from '../rerankers/index.js';
+import { isClefModel } from '../rerankers/clef.js';
+import { JEV_DEFAULT_TOP_K } from '../rerankers/jev.js';
+import { explainMatch } from '../search/explain.js';
+import { fitBudget } from '../search/finalize.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
+import { detectScope } from '../sharing/scope.js';
+import { loadLatestHandoff } from '../store/handoffs.js';
+import { loadIndex } from '../store/index-and-stats.js';
+import { isInitialized } from '../store/open.js';
+import { passesScopeFilterForRecall } from '../store/recall-scope.js';
+import { listSessionEvents, loadActiveTaskSnapshot } from '../store/sessions.js';
+export { DEFAULT_MAX_NEIGHBORS, MAX_HOPS } from '../graph/recall.js';
+/** The active scope merges `--scope` with the detected one, which only boosts. */
+export function cliRecallSetting(ctx, explicitScope) {
+    return { globalRoot: getGlobalRoot(), primaryIsGlobal: isGlobalStoreRoot(ctx.hippoRoot), activeScope: explicitScope || detectScope() };
+}
+export function cliRecallOrigin(ctx, setting) {
+    const localIndex = loadIndex(ctx.hippoRoot);
+    const globalOn = isInitialized(setting.globalRoot);
+    return { globalOn, isGlobal: (id) => setting.primaryIsGlobal || (globalOn && !localIndex.entries[id]) };
+}
+/** The active snapshot, its session's latest handoff and last five events, each kept only when its scope passes. */
+export function loadCliRecallContinuity(ctx, setting, wanted) {
+    if (!wanted || setting.primaryIsGlobal)
+        return { activeSnapshot: null, sessionHandoff: null, recentSessionEvents: [] };
+    const { hippoRoot, tenantId } = ctx;
+    const rawSnapshot = loadActiveTaskSnapshot(hippoRoot, tenantId);
+    const sessionId = rawSnapshot?.session_id ?? undefined;
+    const rawHandoff = sessionId ? loadLatestHandoff(hippoRoot, tenantId, sessionId) : null;
+    const rawEvents = sessionId ? listSessionEvents(hippoRoot, tenantId, { session_id: sessionId, limit: 5 }) : [];
+    // The same shared scope rule as api.recall; the active scope merges --scope and detectScope().
+    const effectiveScope = setting.activeScope || undefined;
+    const passes = (r) => passesScopeFilterForRecall(r.scope ?? null, effectiveScope);
+    return {
+        activeSnapshot: rawSnapshot && passes(rawSnapshot) ? rawSnapshot : null,
+        sessionHandoff: rawHandoff && passes(rawHandoff) ? rawHandoff : null,
+        recentSessionEvents: rawEvents.filter(passes),
+    };
+}
+/** The reranker a `--reranker` name picks and the top-k it takes by default; an unknown name throws, a blank one picks none. */
+export function cliRecallReranker(name) {
+    const fn = getReranker(name);
+    if (!fn)
+        return null;
+    return { fn, defaultTopK: name === 'jev' || isClefModel(name) ? JEV_DEFAULT_TOP_K : 50 };
+}
+/** The ranked rows a print budget holds, best first; the first `floor` stay whatever they cost. */
+export function fitRecallRows(ranked, budget, floor, cost) {
+    return fitBudget(ranked, budget, floor, cost);
+}
+export function recallJsonRow(r, query, showWhy, isGlobal) {
+    const base = {
+        id: r.entry.id,
+        score: r.score,
+        strength: r.entry.strength,
+        tokens: r.tokens,
+        tags: r.entry.tags,
+        content: r.entry.content,
+        layer: r.entry.layer,
+    };
+    if (r.entry.layer === Layer.Trace) {
+        base.trace_outcome = r.entry.trace_outcome;
+    }
+    if (r.entry.superseded_by) {
+        base.superseded = true;
+        base.superseded_by = r.entry.superseded_by;
+    }
+    if (r.graphVia) {
+        base.graphVia = r.graphVia;
+    }
+    if (showWhy) {
+        const explanation = explainMatch(query, r);
+        const facets = confidenceFacets(r.entry);
+        base.confidence = facets.tier;
+        base.aged_out = facets.agedOut;
+        base.source = isGlobal ? 'global' : 'local';
+        base.reason = explanation.reason;
+        base.bm25 = r.bm25;
+        base.cosine = r.cosine;
+        if (explanation.envelope) {
+            base.envelope = explanation.envelope;
+        }
+        // The ordered lifecycle re-ranking steps, so a caller can see why a row moved.
+        if (r.rerankTrace && r.rerankTrace.length > 0) {
+            base.rerankTrace = r.rerankTrace;
+        }
+    }
+    return base;
+}
+//# sourceMappingURL=recall-cli.js.map

package/dist/api/recall-core.js

@@ -8,7 +8,7 @@ import { saveIndex } from '../store/index-and-stats.js';
 import { sqliteStore } from '../store/index.js';
 import { estimateTokens } from '../util/token-text.js';
 import { callerOf, recallAuditMetadata, recallAuditRow, strengthenOf } from './recall-record.js';
-import { recordTokens } from './tokens.js';
+import { RECALL_RECORDING, recordShownRecall } from './recall-finish.js';
 // entriesByIds reads at most this many ids a call.
 const ID_READ_CHUNK = 500;
 export async function retrieveWithCliCore(ctx, opts, core) {
@@ -69,10 +69,19 @@ async function recordShown(ctx, store, opts, core, done) {
         // The second store logs that it was searched, and strengthens only the rows the first does not hold.
         if (second !== undefined)
             await finishOrReport(sqliteStore(second), { goalLog: [], audit: [recallRow], strengthen: strengthenOf(ctx, heldElsewhere) });
-        await traceAndMark(ctx, store, opts, core, shown.results);
+        traceAndMark(ctx, opts, core, shown.results);
     }
-    // The ledger books the text the caller prints, and it prints whether or not the record was written.
-    await recordTokens(ctx, 'recall', { items: ids.length, tokens: shown.tokens, sessionId: core.hostSessionId ?? null });
+    // The caller prints whether or not the record was written, so the ring and the ledger still take this list; `written` holds back the count.
+    await recordShownRecall(ctx, store, RECALL_RECORDING.cli, {
+        query: opts.query,
+        sessionId: opts.sessionId,
+        topId: ids[0] ?? null,
+        anchoredOn: shown.anchoredOn,
+        items: ids.length,
+        tokens: shown.tokens,
+        ledgerSessionId: core.hostSessionId ?? null,
+        written: audited,
+    });
 }
 // The caller has ranked and is about to print, so a failed audit write is logged and counted, never thrown.
 async function finishOrReport(store, writes) {
@@ -93,7 +102,7 @@ async function idsNotHeld(store, ids, tenantId) {
     }
     return ids.filter((id) => !held.has(id));
 }
-async function traceAndMark(ctx, store, opts, core, shown) {
+function traceAndMark(ctx, opts, core, shown) {
     // An empty list is traced too, so a coverage gap still reaches the training corpus.
     const traceId = writeRecallTraceAtRoot(ctx.hippoRoot, {
         tenantId: ctx.tenantId,
@@ -107,6 +116,5 @@ async function traceAndMark(ctx, store, opts, core, shown) {
         return;
     // One write for both markers, so `hippo outcome` never pairs these ids with an older trace.
     saveIndex(ctx.hippoRoot, { last_retrieval_ids: shown.map((r) => r.entry.id), last_trace_id: traceId !== null ? String(traceId) : null });
-    await store.bumpRecallStats(shown.length);
 }
 //# sourceMappingURL=recall-core.js.map

package/dist/api/recall-finish.d.ts

@@ -0,0 +1,53 @@
+import type { AppendAuditOpts } from '../store/audit.js';
+import type { HippoStore } from '../store/index.js';
+import type { TokenSurface } from '../store/token-ledger.js';
+import { type RecallHistorySnapshot } from './recall-history.js';
+import { type RecallSurface } from './recall-record.js';
+import type { Context } from './types.js';
+/** How one surface's recall is recorded. The surfaces differ in these three values and in the list they hand over, nowhere else. */
+export interface RecallRecording {
+    /** Whose session rings the recall reads and feeds. */
+    readonly ring: RecallSurface;
+    /** The label of its token ledger row. */
+    readonly ledger: TokenSurface;
+    /** 'every': an empty list still reaches the stats write, which then only rewrites stats.json; 'shown': an empty list skips it. */
+    readonly stats: 'every' | 'shown';
+}
+/** The surfaces `retrieve` records in full. MCP is pending: src/mcp still feeds its own ring and books its own ledger row, and counts no stats. */
+export declare const RECALL_RECORDING: {
+    readonly http: {
+        readonly ring: "http";
+        readonly ledger: "http_recall";
+        readonly stats: "every";
+    };
+    readonly cli: {
+        readonly ring: "cli";
+        readonly ledger: "recall";
+        readonly stats: "shown";
+    };
+};
+/** What a recorded recall takes into ranking. */
+export interface RecallLead {
+    readonly recallHistory: RecallHistorySnapshot | undefined;
+    readonly leadingAudit: readonly AppendAuditOpts[];
+}
+/** For a surface whose hint `retrieve` judges: the session's history, or the row saying the recall named no session. */
+export declare function recallLead(ctx: Context, how: RecallRecording, query: string, sessionId: string | undefined): RecallLead;
+/** The list a recall showed, as its ranker counted and priced it. */
+export interface ShownList {
+    readonly query: string;
+    /** The recall's session, which keys the ring. */
+    readonly sessionId: string | undefined;
+    readonly topId: string | null;
+    /** The memory this recall's anchoring hint named; the next recall's cooldown reads it. */
+    readonly anchoredOn: string | undefined;
+    readonly items: number;
+    readonly tokens: number;
+    /** The session the ledger row names: the recall's own on HTTP, the host agent's on the CLI. */
+    readonly ledgerSessionId: string | null;
+    /** False when the audit rows could not be written and the caller answers anyway. */
+    readonly written: boolean;
+}
+/** Runs after the recall's own write, in this order: the ring, then the counter, then the ledger. */
+export declare function recordShownRecall(ctx: Context, store: HippoStore, how: RecallRecording, shown: ShownList): Promise<void>;
+//# sourceMappingURL=recall-finish.d.ts.map