hippo-memory 1.68.0 → 1.69.0

package/README.md

@@ -844,7 +844,7 @@ For Codex, it adds two hooks to `$CODEX_HOME/hooks.json` (else `~/.codex/hooks.j
 
 **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.
 
-For GitHub Copilot, once `$COPILOT_HOME` (else `~/.copilot`) exists, `hippo setup` writes hippo's own `hooks/hippo.json`, adds a `hippo` server to `mcp-config.json` and puts a block in `copilot-instructions.md` that asks the agent to call `hippo_recall` and `hippo_remember`. The Copilot CLI, including its sessions inside VS Code, uses all four hooks, the server and the block. VS Code's Local agent runs only the session-start hook and reads neither of the other files, so it gets no pre-compact snapshot or end-of-session capture yet, and its recall tools need hippo added to VS Code's own `mcp.json`. The hooks, that `mcp.json` recipe and how to remove it all: [integrations/copilot.md](integrations/copilot.md).
+For GitHub Copilot, when `$COPILOT_HOME` (else `~/.copilot`) or a VS Code User folder exists, `hippo setup` writes hippo's own `hooks/hippo.json`. When the Copilot folder was there before setup, it also adds a `hippo` server to `mcp-config.json` and a block to `copilot-instructions.md`. The block asks the agent to call `hippo_recall` and `hippo_remember`. The Copilot CLI, including its sessions inside VS Code, uses the session-start, tool-failure, pre-compact and session-end hooks, the server and the block. VS Code's agent mode (the Local agent, VS Code 1.109.3 or later) reads the same hooks file. It gets session start, the pre-compact snapshot and a capture after every reply. Setup also adds hippo to VS Code's own `mcp.json` and writes `prompts/hippo.instructions.md`, so its recall tools and instructions work too. The hooks, the VS Code files and how to remove them: [integrations/copilot.md](integrations/copilot.md).
 
 ### What the hook adds (Claude Code example)
 

package/dist/agent-memories/copilot.d.ts

@@ -1,3 +1,5 @@
-import type { Adapter } from './types.js';
+import type { Adapter, AdapterContext } from './types.js';
+/** VS Code's user-data resolution: portable install first, then the app-data override, then the platform default. */
+export declare function vscodeDataFolders(ctx: Pick<AdapterContext, 'env' | 'home' | 'platform'>): string[];
 export declare const copilotAdapter: Adapter;
 //# sourceMappingURL=copilot.d.ts.map

package/dist/agent-memories/copilot.js

@@ -7,7 +7,7 @@ import { gitLayout } from './git.js';
 const PRODUCTS = ['Code', 'Code - Insiders'];
 const MEMORY_TOOL = ['github.copilot-chat', 'memory-tool', 'memories'];
 /** VS Code's user-data resolution: portable install first, then the app-data override, then the platform default. */
-function dataFolders(ctx) {
+export function vscodeDataFolders(ctx) {
     const { env, home, platform } = ctx;
     if (env.VSCODE_PORTABLE)
         return [path.join(env.VSCODE_PORTABLE, 'user-data')];
@@ -103,7 +103,7 @@ function projectContainers(data, ctx, matches, warnings) {
 export const copilotAdapter = {
     tool: 'copilot',
     list(ctx, scope) {
-        const data = dataFolders(ctx);
+        const data = vscodeDataFolders(ctx);
         const warnings = [];
         const found = [];
         if (scope === 'user') {

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

@@ -1,12 +1,22 @@
 import type { AmbientLoadResult } from '../store/candidates.js';
 import { type MemoryEntry } from '../memory.js';
+import type { ContextReads, HippoStore } from '../store-port.js';
 import { type HippoConfig } from '../config.js';
 import type { ProjectRef } from '../project-identity.js';
 import type { DeliveryObserver } from '../delivery-recorder.js';
 import type { ContextCost, ContextOpts, ContextResultEntry } from './context-types.js';
 import type { Context } from './types.js';
+/** One store getContext reads rows from: its base search and its context reads. */
+export interface ContextSource {
+    readonly store: HippoStore;
+    readonly reads: ContextReads;
+}
 /** What getContext resolved from opts and config before it read a row. */
 export interface ContextPlan {
+    /** The served store, else hippo.db under the root. */
+    local: ContextSource;
+    /** The served store when it is not hippo.db; then every read and write goes through it and no hippo.db opens. */
+    other: HippoStore | undefined;
     pinnedOnly: boolean;
     limit: number;
     includeRecent: number;

package/dist/api/context-select.js

@@ -241,7 +241,7 @@ export async function selectBySearch(ctx, plan, left, pools, admission) {
     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);
-    auditContextRecall(ctx, plan, results.length);
+    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
@@ -273,6 +273,7 @@ async function searchLocalRows(ctx, plan, left, minResults, localEntries, admit)
     const usePhysicsCtx = ctxConfig.physics?.enabled !== false;
     const localCost = cost && ((r) => price(r.entry, primaryIsGlobal));
     const vectorCandidates = contextVectorSpec(ctx, plan, admit);
+    const store = plan.local.store;
     const ctxResults = usePhysicsCtx
         ? await physicsSearch(query, localEntries, {
             budget: left,
@@ -282,6 +283,7 @@ async function searchLocalRows(ctx, plan, left, minResults, localEntries, admit)
             physicsConfig: ctxConfig.physics,
             scope: plan.activeScope,
             vectorCandidates,
+            store,
         })
         : await hybridSearch(query, localEntries, {
             budget: left,
@@ -290,6 +292,7 @@ async function searchLocalRows(ctx, plan, left, minResults, localEntries, admit)
             hippoRoot: ctx.hippoRoot,
             scope: plan.activeScope,
             vectorCandidates,
+            store,
         });
     return ctxResults.map((r) => ({
         entry: r.entry,
@@ -299,21 +302,21 @@ async function searchLocalRows(ctx, plan, left, minResults, localEntries, admit)
     }));
 }
 // Same 'recall' op api.recall emits; the pinned-only and no-query branches never search, so they never emit.
-function auditContextRecall(ctx, plan, resultCount) {
-    const ctxRecallMetadata = {
-        ...auditQueryFields(plan.query),
-        results: resultCount,
-        mode: 'context',
+async function auditContextRecall(ctx, plan, resultCount) {
+    const row = {
+        tenantId: ctx.tenantId,
+        actor: ctx.actor.subject,
+        op: 'recall',
+        metadata: { ...auditQueryFields(plan.query), results: resultCount, mode: 'context' },
     };
+    if (plan.other) {
+        await plan.other.appendAuditEvents([row]);
+        return;
+    }
     if (plan.hasLocal) {
         const localDb = openHippoDb(ctx.hippoRoot);
         try {
-            appendAuditEvent(localDb, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'recall',
-                metadata: ctxRecallMetadata,
-            });
+            appendAuditEvent(localDb, row);
         }
         finally {
             closeHippoDb(localDb);
@@ -322,12 +325,7 @@ function auditContextRecall(ctx, plan, resultCount) {
     if (plan.hasGlobal && !plan.primaryIsGlobal) {
         const globalDb = openHippoDb(plan.globalRoot);
         try {
-            appendAuditEvent(globalDb, {
-                tenantId: ctx.tenantId,
-                actor: ctx.actor.subject,
-                op: 'recall',
-                metadata: ctxRecallMetadata,
-            });
+            appendAuditEvent(globalDb, row);
         }
         finally {
             closeHippoDb(globalDb);

package/dist/api/context.js

@@ -1,12 +1,9 @@
 // Ambient context injection: the admission policy and getContext.
 import { isInitialized } from '../store/open.js';
 import { strengthenRetrieved } from '../store/entry-writes.js';
-import { loadRecallSearchEntries } from '../store/search-rows.js';
 import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../store/rows.js';
-import { loadAmbientCandidates, loadContextCandidates, } from '../store/candidates.js';
 import { loadIndex, saveIndex, updateStats } from '../store/index-and-stats.js';
-import { loadFreshActiveTaskSnapshot, listSessionEvents, SNAPSHOT_AMBIENT_MAX_AGE_MS } from '../store/sessions.js';
-import { loadLatestHandoff } from '../store/handoffs.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';
@@ -22,7 +19,7 @@ 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 { loadAmbientTallies } from '../ambient-store.js';
+import { requireGroup, sqliteStore, storeFor } from '../store-port.js';
 import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../recall-scope.js';
 import { finiteOr, selectBySearch, selectPinned, selectStrongest, } from './context-select.js';
 import { ownerOrSubject } from './types.js';
@@ -64,13 +61,27 @@ export function ambientSecretAdmit(e, currentProject) {
 }
 /** 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;
+/** 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.
-function loadAmbientEntries(hippoRoot, tenantId, pinnedOnly, recent, admit, window, recall, onQualityDrop) {
+// `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) {
+    const ownTenant = (e) => e.tenantId === tenantId;
     if (!pinnedOnly) {
         const rows = 'query' in window
-            ? loadRecallSearchEntries(hippoRoot, window.query, DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, window.exactScope, 'exact', false, window.project, window.ownScope)
-            : loadContextCandidates(hippoRoot, tenantId, window);
-        return { entries: rows.filter(admit) };
+            ? await source.store.searchRecallEntries(window.query, {
+                limit: DEFAULT_SEARCH_CANDIDATE_LIMIT,
+                tenantId,
+                requestedScope: window.exactScope,
+                explicitScopeMode: 'exact',
+                includeSuperseded: false,
+                originProjects: window.project,
+                ownScope: window.ownScope,
+            })
+            : await source.reads.contextCandidates(tenantId, window);
+        return { entries: rows.filter((e) => ownTenant(e) && admit(e)) };
     }
     // The quality floor runs on the recent-N slice AFTER this load, so the load
     // counts by it too, or it stops short of a store whose newest rows are junk.
@@ -82,7 +93,10 @@ function loadAmbientEntries(hippoRoot, tenantId, pinnedOnly, recent, admit, wind
         onQualityDrop?.(e);
         return false;
     };
-    return loadAmbientCandidates(hippoRoot, tenantId, recent.needed, admitAmbient, recall, recent.origins);
+    const loaded = await source.reads.ambientCandidates(tenantId, { recentNeeded: recent.needed, admit: admitAmbient, recall, origins: recent.origins });
+    // Pins and recent rows reach core only through the store's own call to admit, so core applies it again with the tenant.
+    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
@@ -107,10 +121,10 @@ export async function getContext(ctx, opts = {}) {
     if (budget <= 0) {
         return { entries: [], tokens: 0 };
     }
-    const plan = planContext(ctx, opts);
-    const sections = loadTaskSections(ctx, opts, plan, openBlockBudget(plan, opts, budget));
+    const plan = planContext(ctx, opts, sourceOf(storeFor(ctx)));
+    const sections = await loadTaskSections(ctx, opts, plan, openBlockBudget(plan, opts, budget));
     const admission = ambientAdmission(opts, plan, sections.shownHandoff);
-    const pools = loadPools(ctx, plan, admission, promptRecallRequest(opts, plan));
+    const pools = await loadPools(ctx, plan, admission, promptRecallRequest(opts, plan));
     const noSections = !sections.shownSnapshot && !sections.shownHandoff && sections.shownEvents.length === 0;
     if (!plan.promptRecallPending && pools.local.entries.length === 0 && pools.global.entries.length === 0 && noSections) {
         return { entries: [], tokens: 0 };
@@ -127,14 +141,14 @@ export async function getContext(ctx, opts = {}) {
     if (items.length === 0 && noSections) {
         // A query that found nothing is the coverage-gap signal, so it still gets a trace; pinned-only stays read-only.
         if (!plan.pinnedOnly)
-            traceEmptyContext(ctx, opts, plan.query);
+            await traceEmptyContext(ctx, opts, plan);
         return { entries: [], tokens: 0 };
     }
     // pinnedOnly is the UserPromptSubmit hot path — read-only so pinned
     // memories don't inflate retrieval_count or extend half_life every turn.
     const recorded = plan.pinnedOnly
         ? { items, ambientState: undefined }
-        : recordRetrieval(ctx, opts, plan, items, sections.activeSnapshot);
+        : await recordRetrieval(ctx, opts, plan, items, sections.activeSnapshot);
     return {
         entries: recorded.items,
         tokens,
@@ -152,16 +166,17 @@ 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) {
+function planContext(ctx, opts, local) {
     const pinnedOnly = opts.pinnedOnly === true;
+    const other = local.store.kind !== 'sqlite' ? local.store : undefined;
     // Global memories do not establish a project boundary for task state.
-    const hasLocal = isInitialized(ctx.hippoRoot);
+    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 && isInitialized(globalRoot);
+    const hasGlobal = !sharedStore && other === undefined && isInitialized(globalRoot);
     const primaryIsGlobal = isGlobalStoreRoot(ctx.hippoRoot);
     // 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.
@@ -181,6 +196,8 @@ function planContext(ctx, opts) {
         ? cost.entry({ entry, isGlobal, promptRecall, origin: entry.origin_project ?? null, category: classifyOriginProject(entry.origin_project, currentProject) })
         : estimateTokens(entry.content);
     return {
+        local,
+        other,
         pinnedOnly,
         limit: opts.limit ?? Number.POSITIVE_INFINITY,
         includeRecent: opts.includeRecent ?? 0,
@@ -227,30 +244,25 @@ function openBlockBudget(plan, opts, budget) {
 }
 const NO_TASK_STATE = { snapshot: null, handoff: null, events: [] };
 // Keyed on the RAW snapshot: a scope-hidden active session must not fall through to another session's ambient handoff.
-function loadRawTaskState(ctx, opts, plan) {
+async function loadRawTaskState(ctx, opts, plan) {
     if (!plan.hasLocalTaskState)
         return NO_TASK_STATE;
+    const { store, reads } = plan.local;
     // On a shared store task state is one person's, keyed by owner and project so it follows them into their next session.
     const key = plan.sharedStore
         ? { owner: ownerOrSubject(ctx.actor), project: projectNames(plan.currentProject) }
-        : undefined;
+        : null;
+    const block = await store.continuity(ctx.tenantId, 5, key);
     // Bounded read: an orphaned snapshot ages out of this ambient surface; the owner session's read stays unbounded.
-    const snapshot = loadFreshActiveTaskSnapshot(ctx.hippoRoot, ctx.tenantId, { sessionId: opts.currentSessionId }, key);
-    const sessionId = snapshot?.session_id;
-    const handoff = sessionId
-        ? loadLatestHandoff(ctx.hippoRoot, ctx.tenantId, sessionId, {}, key)
-        : loadLatestHandoff(ctx.hippoRoot, ctx.tenantId, undefined, {
-            unfinishedOnly: true,
-            maxAgeMs: SNAPSHOT_AMBIENT_MAX_AGE_MS,
-            // Scope is admitted in SQL so a newer denied row can't hide an older eligible one before LIMIT 1.
-            scopeFilter: 'default-deny',
-        }, key);
-    // Raw session id here too: each event is admitted on its own scope, same as recall and the CLI.
-    const events = sessionId ? listSessionEvents(ctx.hippoRoot, ctx.tenantId, { session_id: sessionId, limit: 5 }) : [];
-    return { snapshot, handoff, events };
+    const snapshot = freshActiveSnapshot(block.activeSnapshot, { sessionId: opts.currentSessionId });
+    // The block's handoff and events are the raw snapshot's session's, so they stand only while that snapshot is fresh.
+    if (snapshot?.session_id)
+        return { snapshot, handoff: block.sessionHandoff, events: block.recentSessionEvents };
+    // An unfinished handoff's scope is admitted in the read, so a newer denied row can't hide an older eligible one.
+    return { snapshot, handoff: await reads.unfinishedHandoff(ctx.tenantId, SNAPSHOT_AMBIENT_MAX_AGE_MS, key), events: [] };
 }
 // Sections print ahead of the memories, so they are paid first; one that does not fit is dropped, as an oversize entry is.
-function loadTaskSections(ctx, opts, plan, startLeft) {
+async function loadTaskSections(ctx, opts, plan, startLeft) {
     const { exactScope, ownScope, cost } = plan;
     let left = startLeft;
     const pays = (tokens) => {
@@ -260,7 +272,7 @@ function loadTaskSections(ctx, opts, plan, startLeft) {
         return true;
     };
     const rowScope = (r) => r?.scope ?? null;
-    const raw = loadRawTaskState(ctx, opts, plan);
+    const raw = await loadRawTaskState(ctx, opts, plan);
     // The same envelope rule ambientAdmitEntry applies to memory rows.
     const activeSnapshot = raw.snapshot && passesScopeFilterForRecall(rowScope(raw.snapshot), exactScope, ownScope) ? raw.snapshot : null;
     const sessionHandoff = raw.handoff && passesScopeFilterForRecall(rowScope(raw.handoff), exactScope, ownScope) ? raw.handoff : null;
@@ -296,7 +308,7 @@ function recentOrigins(plan) {
         return { names: projectNames(plan.currentProject).filter((n) => n !== ''), userGlobal: false };
     return plan.originProject && { names: plan.originProject, userGlobal: true };
 }
-function loadPools(ctx, plan, admission, recallRequest) {
+async function loadPools(ctx, plan, admission, recallRequest) {
     const { obs, pinnedOnly, primaryIsGlobal, hasGlobal, exactScope, ownScope } = plan;
     const recent = { needed: plan.includeRecent, origins: recentOrigins(plan) };
     const searches = plan.query !== '*' && !pinnedOnly;
@@ -316,10 +328,10 @@ function loadPools(ctx, plan, admission, recallRequest) {
         };
     // Tenant-scoped loads: never resolveTenantId({}) here.
     const local = plan.hasLocal
-        ? loadAmbientEntries(ctx.hippoRoot, ctx.tenantId, pinnedOnly, recent, loadAdmit, window, recallRequest, qualityDrop(primaryIsGlobal))
+        ? await loadAmbientEntries(plan.local, ctx.tenantId, pinnedOnly, recent, loadAdmit, poolAdmit, window, recallRequest, qualityDrop(primaryIsGlobal))
         : { entries: [] };
     const global = hasGlobal && !primaryIsGlobal
-        ? loadAmbientEntries(plan.globalRoot, ctx.tenantId, pinnedOnly, recent, loadAdmit, window, recallRequest, qualityDrop(true))
+        ? await loadAmbientEntries(sourceOf(sqliteStore(plan.globalRoot)), ctx.tenantId, pinnedOnly, recent, loadAdmit, poolAdmit, window, recallRequest, qualityDrop(true))
         : { entries: [] };
     return { local, global };
 }
@@ -345,31 +357,35 @@ function finalizeSelection(picked, plan) {
     obs?.selected(selected);
     return { items: selected, tokens };
 }
-// Never touches the index, so it cannot desync last_retrieval_ids from last_trace_id; fail-soft, never throws.
-function traceEmptyContext(ctx, opts, query) {
+// Never touches the index, so it cannot desync last_retrieval_ids from last_trace_id.
+async function traceEmptyContext(ctx, opts, plan) {
     // No snapshot in this branch, so the caller's own id is the only session to stamp.
-    writeRecallTraceAtRoot(ctx.hippoRoot, {
+    const trace = {
         tenantId: ctx.tenantId,
         sessionId: opts.currentSessionId || null,
         pipeline: 'context',
-        query,
+        query: plan.query,
         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.
+    try {
+        await plan.other.finishRecall({ goalLog: [], audit: [], trace });
+    }
+    catch (error) {
+        log.error(`recall trace write failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
 }
 /** Strengthens and marks the returned rows, then writes the trace and index together. */
-function recordRetrieval(ctx, opts, plan, selected, activeSnapshot) {
+async function recordRetrieval(ctx, opts, plan, selected, activeSnapshot) {
     const toUpdate = selected.map((s) => s.entry);
     const updatedEntries = markRetrieved(toUpdate);
-    const localIndex = loadIndex(ctx.hippoRoot);
     const retrievedIds = updatedEntries.map((u) => u.id);
-    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, {
+    const trace = {
         tenantId: ctx.tenantId,
         sessionId: opts.currentSessionId || activeSnapshot?.session_id || null,
         pipeline: 'context',
@@ -379,10 +395,11 @@ function recordRetrieval(ctx, opts, plan, selected, activeSnapshot) {
             memoryId: s.entry.id,
             score: s.score,
         })),
-    });
-    localIndex.last_trace_id = traceId !== null ? String(traceId) : null;
-    saveIndex(ctx.hippoRoot, localIndex);
-    updateStats(ctx.hippoRoot, { recalled: selected.length });
+    };
+    if (plan.other)
+        await recordOnStore(ctx, plan.other, retrievedIds, trace, selected.length);
+    else
+        recordOnHippoDb(ctx, plan, retrievedIds, trace, selected.length);
     // Replace selectedItems entries with markRetrieved-updated copies so
     // the returned ContextResult reflects post-recall state.
     const items = selected.map((s) => ({
@@ -390,12 +407,36 @@ function recordRetrieval(ctx, opts, plan, selected, activeSnapshot) {
         entry: updatedEntries.find((u) => u.id === s.entry.id) ?? s.entry,
     }));
     // Read after strengthenRetrieved commits, so the rows just retrieved count at their new strength.
-    return { items, ambientState: plan.config.ambient.enabled ? readAmbientState(ctx, plan) : undefined };
+    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);
 }
-function readAmbientState(ctx, plan) {
+async function readAmbientState(ctx, plan) {
     const filter = { exactScope: plan.exactScope, ownScope: plan.ownScope, project: plan.originProject, currentProject: projectNames(plan.currentProject), now: evalNow() };
-    const roots = [...(plan.hasLocal ? [ctx.hippoRoot] : []), ...(plan.hasGlobal && !plan.primaryIsGlobal ? [plan.globalRoot] : [])];
-    const tallies = roots.map((root) => loadAmbientTallies(root, ctx.tenantId, filter));
+    const sources = [
+        ...(plan.hasLocal ? [plan.local.reads] : []),
+        ...(plan.hasGlobal && !plan.primaryIsGlobal ? [sourceOf(sqliteStore(plan.globalRoot)).reads] : []),
+    ];
+    const tallies = [];
+    for (const reads of sources)
+        tallies.push(await reads.ambientTallies(ctx.tenantId, filter));
     const total = tallies.length > 0 ? tallies.reduce(addAmbientTallies) : undefined;
     return total && total.total > 0 ? ambientStateFromTallies(total) : undefined;
 }

package/dist/api/forget.d.ts

@@ -1,5 +1,5 @@
 import type { RejectedValueRow } from '../rejection.js';
-import type { Context } from './types.js';
+import type { Context, StoreReply } from './types.js';
 /**
  * Delete a memory by id. `deleteEntry` threads ctx.actor.subject into its internal
  * audit hook, so exactly one 'forget' event lands with the supplied actor.
@@ -14,7 +14,7 @@ export interface ForgetResult {
     ok: true;
     id: string;
 }
-export declare function forget(ctx: Context, id: string): ForgetResult;
+export declare function forget<C extends Context>(ctx: C, id: string): StoreReply<C, ForgetResult>;
 export interface RejectOpts {
     /** By-id form: reject the CURRENT content of an existing memory. */
     memoryId?: string;

package/dist/api/forget.js

@@ -4,9 +4,20 @@ import { BadRequestError, NotFoundError } from '../api-errors.js';
 import { deleteEntry } from '../store/delete-and-batch.js';
 import { updateStatsUnlessBusy } from '../store/index-and-stats.js';
 import { rejectValue, unrejectValue, listRejectionsForTenant } from '../reject-flow.js';
+import { requireGroup } from '../store-port.js';
 import { selectMemoryReach } from '../store/tenant-lookup.js';
 import { canTouchScope, personalScopeOf } from '../recall-scope.js';
 export function forget(ctx, id) {
+    const reply = ctx.store ? forgetThroughStore(ctx, ctx.store, id) : forgetOnHippoDb(ctx, id);
+    // SAFETY: a C typed with a store gets the promise its path returns; a wide C is typed as the union, which a caller has to await anyway.
+    return reply;
+}
+async function forgetThroughStore(ctx, store, id) {
+    const entryWrites = requireGroup(store, 'entryWrites');
+    await entryWrites.forget({ tenantId: ctx.tenantId, actor: ctx.actor.subject, ownScope: personalScopeOf(ctx.actor), id });
+    return { ok: true, id };
+}
+function forgetOnHippoDb(ctx, id) {
     const db = openHippoDb(ctx.hippoRoot);
     try {
         const reach = selectMemoryReach(db, id);

package/dist/api/outcome.d.ts

@@ -1,4 +1,4 @@
-import type { Context } from './types.js';
+import type { Context, StoreReply } from './types.js';
 /**
  * Apply a positive/negative outcome to a list of recently-recalled memory ids.
  * Used by the MCP `hippo_outcome` tool and the HTTP `POST /v1/outcome` route.
@@ -27,9 +27,9 @@ export interface OutcomeResult {
     applied: number;
     appliedIds: string[];
 }
-export declare function outcome(ctx: Context, ids: ReadonlyArray<string>, good: boolean, opts?: {
+export declare function outcome<C extends Context>(ctx: C, ids: ReadonlyArray<string>, good: boolean, opts?: {
     traceId?: number;
-}): OutcomeResult;
+}): StoreReply<C, OutcomeResult>;
 /**
  * Apply an outcome to the ids most recently returned by `recall()`.
  *
@@ -52,5 +52,5 @@ export interface OutcomeForLastRecallResult {
     applied: number;
     ids: string[];
 }
-export declare function outcomeForLastRecall(ctx: Context, good: boolean): OutcomeForLastRecallResult;
+export declare function outcomeForLastRecall<C extends Context>(ctx: C, good: boolean): StoreReply<C, OutcomeForLastRecallResult>;
 //# sourceMappingURL=outcome.d.ts.map

package/dist/api/outcome.js

@@ -4,11 +4,26 @@ import { openStore } from '../store/open.js';
 import { writeEntryOn } from '../store/entry-writes.js';
 import { selectEntriesByIds } from '../store/entry-reads.js';
 import { loadIndex } from '../store/index-and-stats.js';
-import { applyOutcome, CHURN_STALE_TAG } from '../memory.js';
+import { entryAfterOutcome } from '../memory.js';
 import { appendAuditEvent } from '../audit.js';
 import { recordTraceOutcome } from '../recall-trace.js';
-import { canTouchScope } from '../recall-scope.js';
+import { canTouchScope, personalScopeOf } from '../recall-scope.js';
+import { SqliteBlockedError } from '../db/sqlite-blocked.js';
+import { requireGroup } from '../store-port.js';
 export function outcome(ctx, ids, good, opts) {
+    const reply = ctx.store ? outcomeThroughStore(ctx, ctx.store, ids, good, opts) : outcomeOnHippoDb(ctx, ids, good, opts);
+    // SAFETY: a C typed with a store gets the promise its path returns; a wide C is typed as the union, which a caller has to await anyway.
+    return reply;
+}
+/** The rows and their audit rows commit together here; the trace link has no store method, since only the last-recall path sends one. */
+async function outcomeThroughStore(ctx, store, ids, good, opts) {
+    const entryWrites = requireGroup(store, 'entryWrites');
+    if (opts?.traceId !== undefined)
+        throw new Error('an outcome links its recall trace on hippo.db only, never through a store');
+    const appliedIds = await entryWrites.applyOutcome({ tenantId: ctx.tenantId, actor: ctx.actor.subject, ownScope: personalScopeOf(ctx.actor), ids, good });
+    return { applied: appliedIds.length, appliedIds };
+}
+function outcomeOnHippoDb(ctx, ids, good, opts) {
     const appliedIds = [];
     const db = openStore(ctx.hippoRoot);
     try {
@@ -17,10 +32,7 @@ export function outcome(ctx, ids, good, opts) {
             const entry = live.get(id);
             if (!entry || !canTouchScope(ctx.actor, entry.scope ?? null))
                 continue;
-            let updated = applyOutcome(entry, good);
-            if (good && updated.tags.includes(CHURN_STALE_TAG)) { // a good outcome reconfirms the entry
-                updated = { ...updated, tags: updated.tags.filter((t) => t !== CHURN_STALE_TAG) };
-            }
+            const updated = entryAfterOutcome(entry, good);
             writeEntryOn(db, ctx.hippoRoot, updated, { actor: ctx.actor.subject });
             live.set(id, updated); // a repeated id builds on its first outcome, as a fresh read would
             appendAuditEvent(db, {
@@ -50,6 +62,17 @@ export function outcome(ctx, ids, good, opts) {
     return { applied: appliedIds.length, appliedIds };
 }
 export function outcomeForLastRecall(ctx, good) {
+    const reply = ctx.store ? lastRecallUnderStore(ctx, ctx.store, good) : outcomeForLastRecallOnHippoDb({ ...ctx, store: undefined }, good);
+    // SAFETY: a C typed with a store gets the promise its path returns; a wide C is typed as the union, which a caller has to await anyway.
+    return reply;
+}
+/** The last recall's ids and trace sit in hippo.db's meta table, which only the CLI and context write, so no other store holds them. */
+async function lastRecallUnderStore(ctx, store, good) {
+    if (store.kind !== 'sqlite')
+        throw new SqliteBlockedError(store.kind);
+    return outcomeForLastRecallOnHippoDb({ ...ctx, store: undefined }, good);
+}
+function outcomeForLastRecallOnHippoDb(ctx, good) {
     const idx = loadIndex(ctx.hippoRoot);
     const ids = idx.last_retrieval_ids;
     if (ids.length === 0)

package/dist/api/promote.d.ts

@@ -1,5 +1,5 @@
 import { type DatabaseSyncLike } from '../db.js';
-import type { Context } from './types.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
@@ -26,7 +26,7 @@ export interface SupersedeResult {
     oldId: string;
     newId: string;
 }
-export declare function supersede(ctx: Context, oldId: string, newContent: string): SupersedeResult;
+export declare function supersede<C extends Context>(ctx: C, oldId: string, newContent: string): StoreReply<C, SupersedeResult>;
 /**
  * Archive a kind='raw' memory: snapshot into raw_archive, mark archived, delete.
  *
@@ -47,5 +47,5 @@ export interface ArchiveRawResult {
     ok: true;
     archivedAt: string;
 }
-export declare function archiveRaw(ctx: Context, id: string, reason: string, opts?: ArchiveRawOpts): ArchiveRawResult;
+export declare function archiveRaw<C extends Context>(ctx: C, id: string, reason: string, opts?: ArchiveRawOpts): StoreReply<C, ArchiveRawResult>;
 //# sourceMappingURL=promote.d.ts.map