hippo-memory 1.69.0 → 1.71.0

package/dist/api/context-select.js

@@ -1,18 +1,18 @@
 // getContext's selection stages: the pinned-only branch, the strongest-first branch and the search branch.
-import { openHippoDb, closeHippoDb } from '../db.js';
 import { recallScopeFilter } from '../store/search-rows.js';
-import { loadIndex } from '../store/index-and-stats.js';
-import { calculateStrength } from '../memory.js';
-import { appendAuditEvent, auditQueryFields } from '../audit.js';
-import { isWorthSurfacing } from '../memory-quality.js';
-import { rankBothStores } from '../shared.js';
-import { evalNow } from '../ablation.js';
+import { heldIdLookup } from '../store/entry-reads.js';
+import { calculateStrength } from '../core/memory.js';
+import { auditQueryFields, recordAuditEvent } from '../store/audit.js';
+import { isWorthSurfacing } from '../core/memory-quality.js';
+import { rankBothStores } from '../sharing/search-both.js';
+import { evalNow } from '../core/ablation.js';
 import { hybridSearch } from '../search/hybrid.js';
 import { physicsSearch } from '../search/physics-search.js';
-import { DEFAULT_LOCAL_BUMP } from '../search/types.js';
-import { compareScoredResults } from '../compare.js';
-import { scopeMatch } from '../scope.js';
-import { promptTokens, contentTokens, gatePromptRecall, } from '../prompt-recall.js';
+import { DEFAULT_LOCAL_BUMP } from '../core/search-types.js';
+import { compareScoredResults } from '../core/compare.js';
+import { scopeMatch } from '../sharing/scope.js';
+import { scopeBoostFor } from '../search/boosts.js';
+import { promptTokens, contentTokens, gatePromptRecall, } from '../core/prompt-recall.js';
 const GLOBAL_DISCOUNT = 1 / DEFAULT_LOCAL_BUMP;
 // Share and promote copy a memory to the global store under a new id, so equal content is the only link.
 // A pinned copy wins, then the stronger one after the ranking's own global discount; a tie keeps the local copy.
@@ -51,9 +51,8 @@ export function selectPinned(opts, plan, left, pools, admission) {
     const [localPool, globalPool] = oneCopyPerMemory(localEntries, globalEntries, nowP);
     obs?.dropMissing([...localEntries, ...globalEntries], [...localPool, ...globalPool], 'load', 'duplicate');
     const picked = { items: [], ids: new Set(), used: 0 };
-    // Pinned entries are explicit user intent, the recent-N list an automatic
-    // backfill. Both loops share ONE budget and the recent loop runs first, so
-    // pins are ranked here and reserve their share before it can spend.
+    // Pinned entries are explicit intent, the recent-N list an automatic backfill; both share ONE budget and the recent loop runs first,
+    // so pins are ranked here and reserve their share before it can spend.
     const pinnedLocal = localPool.filter((e) => e.pinned);
     const pinnedGlobal = globalPool.filter((e) => e.pinned);
     const rankedPinned = rankPinned(plan, pinnedLocal, pinnedGlobal, nowP);
@@ -61,10 +60,10 @@ export function selectPinned(opts, plan, left, pools, admission) {
     // Prompt recall gates the backfill on the prompt instead of recency.
     if (plan.promptRecallPending) {
         const candidates = () => promptRecallCandidates(plan, pools, admission.admit, rankedPinned, nowP);
-        backfillFromPrompt(opts, plan, pinnedCfg, candidates, picked, recentBudget);
+        backfillFromPrompt(opts, plan, { pinnedCfg, candidates, picked, recentBudget });
     }
     else if (plan.includeRecent > 0) {
-        backfillRecent(plan, localPool, globalPool, picked, recentBudget, nowP);
+        backfillRecent(plan, { localPool, globalPool, picked, recentBudget, nowP });
     }
     admitWithinBudget(rankedPinned, picked, effBudget, obs);
     return picked.items;
@@ -75,11 +74,10 @@ function rankPinned(plan, pinnedLocal, pinnedGlobal, nowP) {
         ...pinnedGlobal.map((e) => ({ entry: e, isGlobal: true })),
     ]
         .map(({ entry, isGlobal }) => {
-        const scopeSig = scopeMatch(entry.tags, plan.activeScope);
-        const sBst = scopeSig === 1 ? 1.5 : scopeSig === -1 ? 0.5 : 1.0;
+        const scopeBoost = scopeBoostFor(scopeMatch(entry.tags, plan.activeScope));
         return {
             entry,
-            score: calculateStrength(entry, nowP) * (isGlobal ? GLOBAL_DISCOUNT : 1) * sBst,
+            score: calculateStrength(entry, nowP) * (isGlobal ? GLOBAL_DISCOUNT : 1) * scopeBoost,
             tokens: plan.price(entry, isGlobal),
             isGlobal,
         };
@@ -115,12 +113,15 @@ function admitWithinBudget(rows, picked, budget, obs) {
         picked.used += r.tokens;
     }
 }
-function backfillFromPrompt(opts, plan, pinnedCfg, candidates, picked, recentBudget) {
+// Overlap a candidate needs with the prompt when the config sets none.
+const DEFAULT_PROMPT_RECALL_THRESHOLD = 0.04;
+function backfillFromPrompt(opts, plan, options) {
+    const { pinnedCfg, candidates, picked, recentBudget } = options;
     const rawMetric = pinnedCfg.pinnedInject.promptRecallMetric;
     const metric = rawMetric === 'cosine' ? 'cosine' : 'jaccard';
     const gate = {
         metric,
-        threshold: finiteOr(pinnedCfg.pinnedInject.promptRecallThreshold, 0.04, 0),
+        threshold: finiteOr(pinnedCfg.pinnedInject.promptRecallThreshold, DEFAULT_PROMPT_RECALL_THRESHOLD, 0),
         minShared: finiteOr(pinnedCfg.pinnedInject.promptRecallMinShared, 2, 0),
         maxItems: finiteOr(pinnedCfg.pinnedInject.promptRecallMaxItems, 5, 1),
     };
@@ -182,7 +183,8 @@ function promptRecallCandidates(plan, pools, admit, rankedPinned, nowP) {
     }
     return candidateItems;
 }
-function backfillRecent(plan, localPool, globalPool, picked, recentBudget, nowP) {
+function backfillRecent(plan, options) {
+    const { localPool, globalPool, picked, recentBudget, nowP } = options;
     const recent = [
         ...localPool.map((entry) => ({ entry, isGlobal: plan.primaryIsGlobal })),
         ...globalPool.map((entry) => ({ entry, isGlobal: true })),
@@ -239,17 +241,19 @@ export function selectStrongest(plan, left, pools) {
 export async function selectBySearch(ctx, plan, left, pools, admission) {
     const minResults = plan.cost ? 0 : undefined; // a priced block skips an oversize top hit too, so the budget bounds it
     const results = plan.hasGlobal && !plan.primaryIsGlobal
-        ? await searchBothStores(ctx, plan, left, minResults, pools, admission.bothStoresAdmit)
-        : await searchLocalRows(ctx, plan, left, minResults, pools.local.entries, admission.admit);
+        ? await searchBothStores(ctx, plan, { left, minResults, pools, admit: admission.bothStoresAdmit })
+        : await searchLocalRows(ctx, plan, { left, minResults, localEntries: pools.local.entries, admit: admission.admit });
     await auditContextRecall(ctx, plan, results.length);
     return results;
 }
-// The pools were admitted at load, before ranking, dedupe and budget: a post-filter would let an excluded row fill the
-// budget or shadow its admitted duplicate.
-async function searchBothStores(ctx, plan, left, minResults, pools, admit) {
+async function searchBothStores(ctx, plan, options) {
+    const { left, minResults, pools, admit } = options;
     const { cost, price } = plan;
-    const localIndex = loadIndex(ctx.hippoRoot);
-    const isGlobalHit = (e) => !localIndex.entries[e.id];
+    // A local pool row is local by construction; sync keeps a global row's id on its local copy, so the global pool is looked up.
+    const poolIds = (pool) => [...pool.entries, ...(pool.recall ?? [])].map((e) => e.id);
+    const localIds = new Set(poolIds(pools.local));
+    const alsoLocal = heldIdLookup(ctx.hippoRoot, ctx.tenantId, poolIds(pools.global).filter((id) => !localIds.has(id)));
+    const isGlobalHit = (e) => !localIds.has(e.id) && !alsoLocal(e.id);
     const roots = { local: ctx.hippoRoot, global: plan.globalRoot };
     const merged = await rankBothStores(plan.query, roots, { local: pools.local.entries, global: pools.global.entries }, contextVectorSpec(ctx, plan, admit), {
         budget: left,
@@ -268,7 +272,8 @@ async function searchBothStores(ctx, plan, left, minResults, pools, admit) {
 function contextVectorSpec(ctx, plan, admit) {
     return { tenantId: ctx.tenantId, scope: recallScopeFilter(plan.exactScope, 'exact', plan.ownScope), includeSuperseded: false, admit };
 }
-async function searchLocalRows(ctx, plan, left, minResults, localEntries, admit) {
+async function searchLocalRows(ctx, plan, options) {
+    const { left, minResults, localEntries, admit } = options;
     const { cost, price, primaryIsGlobal, query, config: ctxConfig } = plan;
     const usePhysicsCtx = ctxConfig.physics?.enabled !== false;
     const localCost = cost && ((r) => price(r.entry, primaryIsGlobal));
@@ -313,23 +318,9 @@ async function auditContextRecall(ctx, plan, resultCount) {
         await plan.other.appendAuditEvents([row]);
         return;
     }
-    if (plan.hasLocal) {
-        const localDb = openHippoDb(ctx.hippoRoot);
-        try {
-            appendAuditEvent(localDb, row);
-        }
-        finally {
-            closeHippoDb(localDb);
-        }
-    }
-    if (plan.hasGlobal && !plan.primaryIsGlobal) {
-        const globalDb = openHippoDb(plan.globalRoot);
-        try {
-            appendAuditEvent(globalDb, row);
-        }
-        finally {
-            closeHippoDb(globalDb);
-        }
-    }
+    if (plan.hasLocal)
+        recordAuditEvent(ctx.hippoRoot, row);
+    if (plan.hasGlobal && !plan.primaryIsGlobal)
+        recordAuditEvent(plan.globalRoot, row);
 }
 //# sourceMappingURL=context-select.js.map

package/dist/api/context-types.d.ts

@@ -1,20 +1,11 @@
 import type { TaskSnapshot, SessionEvent } from '../store/rows.js';
-import type { SessionHandoff } from '../handoff.js';
-import type { MemoryEntry } from '../memory.js';
-import type { DeliveryObserver } from '../delivery-recorder.js';
-import type { AmbientState } from '../ambient.js';
-import type { ProjectRef } from '../project-identity.js';
-/**
- * Options for `getContext` — assemble a budget-bounded context bundle
- * (recalled memories + active task snapshot + handoff + recent events).
- *
- * Named `getContext` (not `context`) to avoid collision with the `Context`
- * interface above and the ubiquitous `ctx: Context` convention. Follows the
- * existing `getEntry` naming pattern in store.ts.
- *
- * Rendering opts (`format`, `framing`, `rendered`) and host-side opts (`auto`) stay in the CLI,
- * because its print helpers are shared with `cmdRecall` / `cmdSnapshot` / `cmdHandoffShow`.
- */
+import type { SessionHandoff } from '../core/handoff.js';
+import type { MemoryEntry } from '../core/memory.js';
+import type { DeliveryObserver } from '../store/delivery-recorder.js';
+import type { AmbientState } from '../core/ambient.js';
+import type { ProjectRef } from '../core/project-identity.js';
+/** Options for `getContext`: a budget-bounded bundle of recalled memories, active task snapshot, handoff and recent events.
+ * Rendering opts (`format`, `framing`, `rendered`) and host-side opts (`auto`) stay in the CLI, whose print helpers are shared. */
 export interface ContextOpts {
     q?: string;
     /** Default 1500 tokens. */
@@ -24,30 +15,16 @@ export interface ContextOpts {
     scope?: string;
     /** Envelope scope to match exactly, as in `recall`: admits that scope even when private, after the actor's scope check. */
     exactScope?: string;
-    /** With `pinnedOnly`, also inject the N most recent writes that pass the
-     *  quality floor (`isWorthSurfacing`). Filtering happens BEFORE
-     *  the take-N, so a caller asking for 5 gets 5 qualifying entries rather
-     *  than 5-minus-junk; pinned entries bypass the floor. Entries are only
-     *  skipped for this read, never mutated or deleted. Ignored when
-     *  `pinnedOnly` is false — no other path reads it. */
+    /** With `pinnedOnly`, also inject the N most recent writes that pass the quality floor (`isWorthSurfacing`); pinned entries bypass it.
+     *  Filtering happens BEFORE the take-N, so asking for 5 gets 5 qualifying entries. Ignored when `pinnedOnly` is false. */
     includeRecent?: number;
-    /** v39 memory scope isolation: re-include other-project memories that the
-     *  origin partition excludes by default. They come back tagged
-     *  `category: 'cross-project'` so renderers can demarcate them. */
+    /** Re-include other-project memories the origin partition excludes by default; they come back tagged `category: 'cross-project'`. */
     crossProject?: boolean;
-    /** The active project for the origin partition ('' = not in a project): a
-     *  name, or an identity whose rows may also carry its legacy folder name.
-     *  Defaults to `resolveProjectIdentity(process.cwd())`; surfaces whose
-     *  process cwd is not the caller's project (HTTP server) should pass it. */
+    /** The active project for the origin partition ('' = not in a project): a name, or an identity whose rows may carry its legacy folder name.
+     *  Defaults to `resolveProjectIdentity(process.cwd())`; surfaces whose cwd is not the caller's project (HTTP server) should pass it. */
     currentProject?: ProjectRef;
-    /** The calling
-     *  session's id. Stamped on this call's recall trace, and the owner-match input to
-     *  `loadFreshActiveTaskSnapshot` — when it strictly equals the active
-     *  snapshot's `session_id`, the read is unbounded (same-session
-     *  continuity); otherwise the snapshot must pass the freshness bound to
-     *  surface. Absent (undefined/null/'') never short-circuits as a match;
-     *  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. */
+    /** The calling session's id, stamped on this call's recall trace. When it strictly equals the active snapshot's `session_id` the read is unbounded;
+     *  otherwise the snapshot must pass the freshness bound. Absent (undefined/null/'') never matches. Host-resolved, so this stays host-agnostic. */
     currentSessionId?: string | null;
     /** Raw hook-payload prompt; only the pinned-only branch reads it, gated on `pinnedInject.promptRecall`. */
     prompt?: string;
@@ -83,9 +60,7 @@ export interface ContextResultEntry {
     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'
-     *  entries only appear when ContextOpts.crossProject was set (or isolation
-     *  is disabled). */
+    /** How the origin relates to the active project; 'cross-project' appears only when `crossProject` was set (or isolation is disabled). */
     category?: 'project' | 'user-global' | 'cross-project';
 }
 export interface ContextResult {

package/dist/api/context.d.ts

@@ -1,32 +1,13 @@
-import { type MemoryEntry } from '../memory.js';
-import { type ProjectRef } from '../project-identity.js';
+import { type MemoryEntry } from '../core/memory.js';
+import { type ProjectRef } from '../core/project-identity.js';
 import type { ContextOpts, ContextResult } from './context-types.js';
 import { type Context } from './types.js';
 export { oneCopyPerMemory } from './context-select.js';
-/**
- * The secret half of the ambient policy on its own, for callers
- * that apply their own scope rule. A flagged row is only admitted inside its owning project;
- * flagged rows with no project origin never ambient-inject.
- */
+/** The secret half of the ambient policy alone, for callers with their own scope rule: a flagged row is admitted only inside its owning project. */
 export declare function ambientSecretAdmit(e: MemoryEntry, currentProject: ProjectRef): boolean;
-/** Most rows per store a no-query context reads; past it, ranking and ambientState see the strongest by decay. */
-export declare const CONTEXT_CANDIDATE_CAP = 2000;
-/**
- * Assemble a context bundle: recalled memories (pinned-only / strength-sorted
- * fallback / hybrid search) + active task snapshot + session handoff + recent
- * session events. Budget-bounded, tenant-scoped. Mutates `last_retrieval_ids`
- * + emits a 'recall' audit row for non-pinned, non-'*' queries.
- *
- * Behaves like the pre-extraction `cmdContext` data-loading + selection
- * pipeline. CLI presentation (markdown / json / additional-context rendering)
- * stays in `cli.ts`.
- *
- * Tenant scope: all `loadAllEntries` / snapshot / handoff / events reads use
- * `ctx.tenantId`. Cross-tenant rows are filtered out.
- *
- * @returns An empty result (`entries: []`, snapshot/handoff/events undefined)
- * when there's nothing to surface (no memories AND no snapshot AND no handoff
- * AND no recent events).
- */
+/** Tokens a context block may use when the caller sets no budget; the hook command and the CLI default match it. */
+export declare const DEFAULT_CONTEXT_BUDGET = 1500;
+/** Assembles a budget-bounded, tenant-scoped context bundle; mutates `last_retrieval_ids` and emits a 'recall' audit row for non-pinned, non-'*' queries.
+ * Returns an empty result when there are no memories, snapshot, handoff or recent events. CLI rendering stays in `cli.ts`. */
 export declare function getContext(ctx: Context, opts?: ContextOpts): Promise<ContextResult>;
 //# sourceMappingURL=context.d.ts.map

package/dist/api/context.js

@@ -1,42 +1,31 @@
 // Ambient context injection: the admission policy and getContext.
 import { isInitialized } from '../store/open.js';
-import { strengthenRetrieved } from '../store/entry-writes.js';
 import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../store/rows.js';
-import { loadIndex, saveIndex, updateStats } from '../store/index-and-stats.js';
 import { freshActiveSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS } from '../store/sessions.js';
-import { estimateTokens } from '../token-ledger.js';
-import { markRetrieved, COMPACTION_MEMORY_TAG } from '../memory.js';
-import { isWorthSurfacing } from '../memory-quality.js';
-import { getGlobalRoot } from '../shared.js';
-import { writeRecallTraceAtRoot } from '../recall-trace.js';
-import { evalNow, isRecallBoostAblated } from '../ablation.js';
-import { dropHeldCopies } from '../same-text.js';
-import { BadRequestError } from '../api-errors.js';
-import { isSharedStore, loadConfig } from '../config.js';
-import { log } from '../log.js';
-import { resolveProjectIdentity, classifyOriginProject, isGlobalStoreRoot, projectId, projectNames } from '../project-identity.js';
-import { promptTokens } from '../prompt-recall.js';
-import { detectSecret } from '../secret-detect.js';
-import { isSessionDigestRow } from '../session-digest.js';
-import { addAmbientTallies, ambientStateFromTallies } from '../ambient.js';
-import { requireGroup, sqliteStore, storeFor } from '../store-port.js';
-import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../recall-scope.js';
+import { estimateTokens } from '../util/token-text.js';
+import { markRetrieved, COMPACTION_MEMORY_TAG } from '../core/memory.js';
+import { isWorthSurfacing } from '../core/memory-quality.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
+import { evalNow } from '../core/ablation.js';
+import { dropHeldCopies } from '../util/same-text.js';
+import { BadRequestError } from '../core/api-errors.js';
+import { isSharedStore, loadConfig } from '../core/config.js';
+import { rethrowIfSqliteBlocked } from '../db/index.js';
+import { errorMessage, log } from '../util/log.js';
+import { resolveProjectIdentity, classifyOriginProject, isGlobalStoreRoot, projectId, projectNames } from '../core/project-identity.js';
+import { promptTokens } from '../core/prompt-recall.js';
+import { detectSecret } from '../util/secret-detect.js';
+import { isSessionDigestRow } from '../core/session-digest-row.js';
+import { addAmbientTallies, ambientStateFromTallies } from '../core/ambient.js';
+import { requireGroup, sqliteStore, storeFor } from '../store/index.js';
+import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../store/recall-scope.js';
 import { finiteOr, selectBySearch, selectPinned, selectStrongest, } from './context-select.js';
+import { andThen, onStore } from './on-store.js';
+import { strengthenOf } from './recall-record.js';
 import { ownerOrSubject } from './types.js';
 export { oneCopyPerMemory } from './context-select.js';
-/**
- * v39: the single ambient-injection admission policy, shared by getContext
- * and the CLI-side ambient-state summary so the two cannot drift.
- *
- * - Secret veto is UNCONDITIONAL: neither crossProject nor
- *   contextProjectIsolation:false re-includes secrets. A flagged row only
- *   injects inside its owning project; flagged rows with no project origin
- *   (''/null) never ambient-inject at all. Explicit recall is unaffected -
- *   recalling a secret is a deliberate act.
- * - Envelope parity: private/quarantine scopes never inject unless `exactScope` names one.
- * - Origin partition: other-project rows are excluded unless
- *   `includeCrossProject`.
- */
+/** The single ambient-injection admission policy, shared by getContext and the CLI ambient-state summary so they cannot drift.
+ * Secret veto is unconditional (flagged rows inject only in their own project); private scopes need `exactScope`, other projects `includeCrossProject`. */
 function ambientAdmitEntry(e, currentProject, includeCrossProject, exactScope, own) {
     if (!ambientSecretAdmit(e, currentProject))
         return false;
@@ -46,11 +35,7 @@ function ambientAdmitEntry(e, currentProject, includeCrossProject, exactScope, o
         return true;
     return classifyOriginProject(e.origin_project, currentProject) !== 'cross-project';
 }
-/**
- * The secret half of the ambient policy on its own, for callers
- * that apply their own scope rule. A flagged row is only admitted inside its owning project;
- * flagged rows with no project origin never ambient-inject.
- */
+/** The secret half of the ambient policy alone, for callers with their own scope rule: a flagged row is admitted only inside its owning project. */
 export function ambientSecretAdmit(e, currentProject) {
     if (!detectSecret(e).flagged)
         return true;
@@ -59,15 +44,17 @@ export function ambientSecretAdmit(e, currentProject) {
         return false;
     return projectNames(currentProject).includes(origin);
 }
+/** Tokens a context block may use when the caller sets no budget; the hook command and the CLI default match it. */
+export const DEFAULT_CONTEXT_BUDGET = 1500;
 /** Most rows per store a no-query context reads; past it, ranking and ambientState see the strongest by decay. */
-export const CONTEXT_CANDIDATE_CAP = 2000;
+const CONTEXT_CANDIDATE_CAP = 2000;
 /** A store's base search and context reads; a store without the group throws StoreNotPortedError. */
 function sourceOf(store) {
     return { store, reads: requireGroup(store, 'contextReads') };
 }
-// The pinned-only branch needs pins and recent-N candidates, not the corpus; `recent` and `recall` apply there only.
-// `recheck` is `admit` without the delivery observer, so a row checked twice is not refused twice in the ledger.
-async function loadAmbientEntries(source, tenantId, pinnedOnly, recent, admit, recheck, window, recall, onQualityDrop) {
+// The pinned-only branch needs pins and recent-N candidates, not the corpus.
+async function loadAmbientEntries(source, tenantId, options) {
+    const { pinnedOnly, recent, admit, recheck, window, recall, onQualityDrop } = options;
     const ownTenant = (e) => e.tenantId === tenantId;
     if (!pinnedOnly) {
         const rows = 'query' in window
@@ -98,25 +85,10 @@ async function loadAmbientEntries(source, tenantId, pinnedOnly, recent, admit, r
     const entries = loaded.entries.filter((e) => ownTenant(e) && recheck(e));
     return loaded.recall ? { entries, recall: loaded.recall.filter(ownTenant) } : { entries };
 }
-/**
- * Assemble a context bundle: recalled memories (pinned-only / strength-sorted
- * fallback / hybrid search) + active task snapshot + session handoff + recent
- * session events. Budget-bounded, tenant-scoped. Mutates `last_retrieval_ids`
- * + emits a 'recall' audit row for non-pinned, non-'*' queries.
- *
- * Behaves like the pre-extraction `cmdContext` data-loading + selection
- * pipeline. CLI presentation (markdown / json / additional-context rendering)
- * stays in `cli.ts`.
- *
- * Tenant scope: all `loadAllEntries` / snapshot / handoff / events reads use
- * `ctx.tenantId`. Cross-tenant rows are filtered out.
- *
- * @returns An empty result (`entries: []`, snapshot/handoff/events undefined)
- * when there's nothing to surface (no memories AND no snapshot AND no handoff
- * AND no recent events).
- */
+/** Assembles a budget-bounded, tenant-scoped context bundle; mutates `last_retrieval_ids` and emits a 'recall' audit row for non-pinned, non-'*' queries.
+ * Returns an empty result when there are no memories, snapshot, handoff or recent events. CLI rendering stays in `cli.ts`. */
 export async function getContext(ctx, opts = {}) {
-    const budget = opts.budget ?? 1500;
+    const budget = opts.budget ?? DEFAULT_CONTEXT_BUDGET;
     assertScopeRequestAllowed(ctx.actor, opts.exactScope);
     if (budget <= 0) {
         return { entries: [], tokens: 0 };
@@ -166,18 +138,29 @@ function warnIsolationIgnored(hippoRoot) {
     isolationWarned.add(hippoRoot);
     log.warn(`${hippoRoot}: "contextProjectIsolation": false is ignored on a shared store; a read opts in with cross_project.`);
 }
-function planContext(ctx, opts, local) {
-    const pinnedOnly = opts.pinnedOnly === true;
+/** Which stores this read can draw on, and what kind the primary one is. */
+function storesInReach(ctx, opts, local) {
     const other = local.store.kind !== 'sqlite' ? local.store : undefined;
     // Global memories do not establish a project boundary for task state.
     const hasLocal = other !== undefined || isInitialized(ctx.hippoRoot);
-    const query = (opts.q ?? '').trim() || '*';
     const globalRoot = getGlobalRoot();
     // The store's own flag counts too, so no surface can read a shared store as its owner.
     const sharedStore = opts.sharedStore === true || isSharedStore(ctx.hippoRoot);
     // A store serving many people is not its operator's, so the operator's own global store stays out.
     const hasGlobal = !sharedStore && other === undefined && isInitialized(globalRoot);
     const primaryIsGlobal = isGlobalStoreRoot(ctx.hippoRoot);
+    return { other, hasLocal, globalRoot, sharedStore, hasGlobal, primaryIsGlobal };
+}
+/** Prices one entry against the budget: the caller's cost model when it gave one, else a token estimate. */
+function entryPricer(cost, currentProject) {
+    return (entry, isGlobal, promptRecall) => cost
+        ? cost.entry({ entry, isGlobal, promptRecall, origin: entry.origin_project ?? null, category: classifyOriginProject(entry.origin_project, currentProject) })
+        : estimateTokens(entry.content);
+}
+function planContext(ctx, opts, local) {
+    const pinnedOnly = opts.pinnedOnly === true;
+    const { other, hasLocal, globalRoot, sharedStore, hasGlobal, primaryIsGlobal } = storesInReach(ctx, opts, local);
+    const query = (opts.q ?? '').trim() || '*';
     // opts.scope is only the tag boost, opts.exactScope the envelope request; other-project memories are
     // excluded unless the caller asks for them (crossProject) or isolation is disabled.
     const config = loadConfig(ctx.hippoRoot);
@@ -192,9 +175,7 @@ function planContext(ctx, opts, local) {
     // Decided before the ambient loads so the pinned-only FTS candidate query can share their connection.
     const promptRecallPending = pinnedOnly && Boolean(opts.prompt?.trim()) && config.pinnedInject.promptRecall === true;
     const cost = opts.cost;
-    const price = (entry, isGlobal, promptRecall) => cost
-        ? cost.entry({ entry, isGlobal, promptRecall, origin: entry.origin_project ?? null, category: classifyOriginProject(entry.origin_project, currentProject) })
-        : estimateTokens(entry.content);
+    const price = entryPricer(cost, currentProject);
     return {
         local,
         other,
@@ -238,6 +219,8 @@ function openBlockBudget(plan, opts, budget) {
     obs?.facts({ projectName: projectId(plan.currentProject), budgetTokens: blockBudget, promptRecall: promptRecallPending });
     if (pinnedOnly && !config.pinnedInject.enabled)
         obs?.disabled();
+    if (!pinnedOnly)
+        obs?.queried(plan.query);
     return cost
         ? Math.max(0, blockBudget - cost.fixed(blockBudget, { cross: plan.includeCrossProject, promptRecall: promptRecallPending, ambient: !pinnedOnly && config.ambient.enabled }))
         : blockBudget;
@@ -327,17 +310,24 @@ async function loadPools(ctx, plan, admission, recallRequest) {
             now: evalNow(),
         };
     // Tenant-scoped loads: never resolveTenantId({}) here.
+    const read = { pinnedOnly, recent, admit: loadAdmit, recheck: poolAdmit, window, recall: recallRequest };
     const local = plan.hasLocal
-        ? await loadAmbientEntries(plan.local, ctx.tenantId, pinnedOnly, recent, loadAdmit, poolAdmit, window, recallRequest, qualityDrop(primaryIsGlobal))
+        ? await loadAmbientEntries(plan.local, ctx.tenantId, { ...read, onQualityDrop: qualityDrop(primaryIsGlobal) })
         : { entries: [] };
     const global = hasGlobal && !primaryIsGlobal
-        ? await loadAmbientEntries(sourceOf(sqliteStore(plan.globalRoot)), ctx.tenantId, pinnedOnly, recent, loadAdmit, poolAdmit, window, recallRequest, qualityDrop(true))
+        ? await loadAmbientEntries(sourceOf(sqliteStore(plan.globalRoot)), ctx.tenantId, { ...read, onQualityDrop: qualityDrop(true) })
         : { entries: [] };
     return { local, global };
 }
 /** The `limit` cut, then the held-copy drop, then each entry's origin annotation. */
 function finalizeSelection(picked, plan) {
     const { obs } = plan;
+    // Ranking reports nothing itself, so its results are offered here and the cuts below can name what they drop.
+    if (!plan.pinnedOnly && obs) {
+        const pool = plan.query === '*' ? 'strength' : 'search';
+        obs.offer(picked.filter((r) => r.isGlobal !== true).map((r) => r.entry), false, pool);
+        obs.offer(picked.filter((r) => r.isGlobal === true).map((r) => r.entry), true, pool);
+    }
     let selected = picked;
     if (plan.limit < selected.length) {
         const cut = selected.slice(0, plan.limit);
@@ -368,16 +358,13 @@ async function traceEmptyContext(ctx, opts, plan) {
         explainMode: false,
         results: [],
     };
-    if (!plan.other) {
-        writeRecallTraceAtRoot(ctx.hippoRoot, trace);
-        return;
-    }
-    // The empty reply is already decided, so a lost trace logs as the hippo.db write does rather than failing the call.
+    // The empty reply is already decided, so a lost trace is logged and the call still answers.
     try {
-        await plan.other.finishRecall({ goalLog: [], audit: [], trace });
+        await onStore(ctx, (port) => port.finishRecall({ goalLog: [], audit: [], trace }));
     }
     catch (error) {
-        log.error(`recall trace write failed: ${error instanceof Error ? error.message : String(error)}`);
+        rethrowIfSqliteBlocked(error);
+        log.error(`recall trace write failed: ${errorMessage(error)}`);
     }
 }
 /** Strengthens and marks the returned rows, then writes the trace and index together. */
@@ -396,10 +383,12 @@ async function recordRetrieval(ctx, opts, plan, selected, activeSnapshot) {
             score: s.score,
         })),
     };
-    if (plan.other)
-        await recordOnStore(ctx, plan.other, retrievedIds, trace, selected.length);
-    else
-        recordOnHippoDb(ctx, plan, retrievedIds, trace, selected.length);
+    const writes = { goalLog: [], audit: [], trace, strengthen: strengthenOf(ctx, retrievedIds) };
+    // hippo.db keeps the ids as its last recall, which feeds only outcomeForLastRecall, and it alone reads a second root.
+    await onStore(ctx, (port, local) => andThen(local.finishLastRecall(writes, plan.hasGlobal ? plan.globalRoot : undefined), (traceId) => {
+        plan.obs?.traced(traceId);
+        return port.bumpRecallStats(selected.length);
+    }));
     // Replace selectedItems entries with markRetrieved-updated copies so
     // the returned ContextResult reflects post-recall state.
     const items = selected.map((s) => ({
@@ -409,25 +398,6 @@ async function recordRetrieval(ctx, opts, plan, selected, activeSnapshot) {
     // Read after strengthenRetrieved commits, so the rows just retrieved count at their new strength.
     return { items, ambientState: plan.config.ambient.enabled ? await readAmbientState(ctx, plan) : undefined };
 }
-function recordOnHippoDb(ctx, plan, retrievedIds, trace, recalled) {
-    const localIndex = loadIndex(ctx.hippoRoot);
-    const strengthenedHere = strengthenRetrieved(ctx.hippoRoot, retrievedIds, { recallBoostAblated: isRecallBoostAblated() });
-    if (plan.hasGlobal)
-        strengthenRetrieved(plan.globalRoot, retrievedIds.filter((id) => !strengthenedHere.has(id)), { recallBoostAblated: isRecallBoostAblated() });
-    localIndex.last_retrieval_ids = retrievedIds;
-    // Trace first on its own short-lived connection, then fold its id into localIndex so one saveIndex moves
-    // last_retrieval_ids and last_trace_id in lockstep; a failed trace write stores null, never a stale id.
-    const traceId = writeRecallTraceAtRoot(ctx.hippoRoot, trace);
-    localIndex.last_trace_id = traceId !== null ? String(traceId) : null;
-    saveIndex(ctx.hippoRoot, localIndex);
-    updateStats(ctx.hippoRoot, { recalled });
-}
-// The index's last-recall ids feed only outcomeForLastRecall, which no other store serves, so they are not written here.
-async function recordOnStore(ctx, store, retrievedIds, trace, recalled) {
-    const strengthen = { ids: retrievedIds, opts: { tenantId: ctx.tenantId, recallBoostAblated: isRecallBoostAblated() } };
-    await store.finishRecall({ goalLog: [], audit: [], trace, strengthen });
-    await store.bumpRecallStats(recalled);
-}
 async function readAmbientState(ctx, plan) {
     const filter = { exactScope: plan.exactScope, ownScope: plan.ownScope, project: plan.originProject, currentProject: projectNames(plan.currentProject), now: evalNow() };
     const sources = [

package/dist/api/dormant.d.ts

@@ -1,29 +1,13 @@
-import { type DormantMemory, type ListDormantOpts } from '../dormant.js';
-import { type MemoryEntry } from '../memory.js';
+import { type DormantMemory, type ListDormantOpts } from '../store/dormant.js';
+import { type MemoryEntry } from '../core/memory.js';
 import type { Context } from './types.js';
-/**
- * A tenant's dormant memories (src/dormant.ts): what sleep moved out of
- * active memory instead of deleting, when `dormant.enabled` is on. Newest
- * first; `opts.query` keeps rows containing every term (case-insensitive).
- */
+/** A tenant's dormant memories (src/store/dormant.ts): what sleep moved out of active memory when `dormant.enabled` is on. Newest first;
+ * `opts.query` keeps rows containing every term (case-insensitive). */
 export declare function listDormant(ctx: Context, opts?: ListDormantOpts): DormantMemory[];
-/**
- * Bring a dormant memory back into active memory. It returns as if just
- * recalled, with a full half-life. A row audit repair set aside returns
- * `verified`, so no quality check judges it again. Every other field is the
- * snapshot taken when it went dormant.
- *
- * Throws when the tenant has no dormant memory with that id (another
- * tenant's id, or another person's personal row, reads the same way), when a live memory already holds the id,
- * and RejectedValueError when the value has been rejected since. On any
- * throw the dormant copy stays where it is.
- */
+/** Restores a dormant memory as if just recalled, with a full half-life; a row set aside by audit repair returns `verified`.
+ * Throws if the tenant has no such dormant id or a live memory holds it, and RejectedValueError if the value was since rejected (the dormant copy stays). */
 export declare function restoreDormant(ctx: Context, id: string): MemoryEntry;
-/**
- * Permanently delete a dormant memory: the explicit "forget it for good"
- * that dormant storage leaves to the user. Throws when the tenant has no
- * dormant memory with that id.
- */
+/** Permanently deletes a dormant memory, the explicit "forget it for good"; throws when the tenant has no dormant memory with that id. */
 export declare function forgetDormant(ctx: Context, id: string): void;
 /** Whether the tenant holds a dormant memory with this id that the caller may touch (for "not found" hints). */
 export declare function isDormant(ctx: Context, id: string): boolean;