hippo-memory 1.71.0 → 2.0.0

package/dist/api/recall-pipeline.js

@@ -3,20 +3,20 @@
 import { evalNow } from '../core/ablation.js';
 import { oneCopyPerMemory } from './context-select.js';
 import { compareEntryIdentity, compareScoresDesc } from '../core/compare.js';
-import { isEmbeddingAvailable } from '../store/embeddings/local.js';
+import { isEmbeddingAvailable } from '../embeddings/local.js';
 import { activeGoalsWithPolicies } from '../store/goals.js';
 import { boostByGoals } from '../search/goal-boost.js';
 import { graphExpandRecall } from '../graph/recall.js';
 import { DEFAULT_GRAPH_STREAM_WEIGHT } from '../graph/stream.js';
 import { Layer } from '../core/memory.js';
 import { multihopSearch } from '../search/multihop.js';
-import { passesCliRecallScopeFilter } from '../store/recall-scope.js';
+import { passesCliRecallScopeFilter } from '../core/recall-scope.js';
 import { currentEntries } from '../search/as-of.js';
 import { STRENGTH_RANK_FLOOR, STRENGTH_RANK_SPAN } from '../search/boosts.js';
-import { hybridSearch } from '../search/hybrid.js';
-import { physicsSearch } from '../search/physics-search.js';
-import { searchBothHybrid } from '../sharing/search-both.js';
-import { loadRecallSearchEntries, recallScopeFilter } from '../store/search-rows.js';
+import { hybridSearch, vectorSourceOf } from '../search/hybrid.js';
+import { searchByEngine } from '../search/engine.js';
+import { rankBothStores } from '../sharing/search-both.js';
+import { loadRecallEntries, recallScopeFilter } from '../store/search-rows.js';
 import { isJsonNumber } from '../util/json.js';
 import { textOverlap, tokenize as tokenizeQuery } from '../util/tokenize.js';
 /** Ranks memories for a query as `hippo recall` does, through the `limit` slice. Reads stores, embeddings and physics state; writes and prints nothing
@@ -65,10 +65,9 @@ function loadRecallPool(ctx, opts) {
     // An explicit --scope unlocks that envelope scope; the regex-only `<source>:private:*` deny is the JS half below.
     const requested = opts.explicitScope || undefined;
     const loadSuperseded = opts.includeSuperseded || Boolean(opts.asOf);
-    let local = loadRecallSearchEntries(ctx.hippoRoot, opts.query, undefined, ctx.tenantId, requested, 'additive', loadSuperseded);
-    let global = ctx.globalRoot
-        ? loadRecallSearchEntries(ctx.globalRoot, opts.query, undefined, ctx.tenantId, requested, 'additive', loadSuperseded)
-        : [];
+    const load = { tenantId: ctx.tenantId, requestedScope: requested, explicitScopeMode: 'additive', includeSuperseded: loadSuperseded };
+    let local = loadRecallEntries(ctx.hippoRoot, opts.query, load);
+    let global = ctx.globalRoot ? loadRecallEntries(ctx.globalRoot, opts.query, load) : [];
     // SQL-excluded rows are pre-candidate, so the total is taken before the JS filters, which normally drop nothing.
     const total = local.length + global.length;
     const passes = (e) => passesCliRecallScopeFilter(e.scope ?? null, requested);
@@ -98,7 +97,7 @@ async function searchPool(ctx, opts, pool) {
         });
     }
     if (search.multihop) {
-        // Unlike searchBothHybrid below, multihop ranks one pooled list, so a shared memory's two copies both compete.
+        // Unlike rankBothStores below, multihop ranks one pooled list, so a shared memory's two copies both compete.
         const allEntries = oneCopyPerMemory(pool.local, pool.global, evalNow()).flat();
         return multihopSearch(query, allEntries, { budget, cost, hippoRoot: ctx.hippoRoot, minResults, includeSuperseded, asOf });
     }
@@ -109,24 +108,24 @@ async function searchPool(ctx, opts, pool) {
         includeSuperseded: includeSuperseded || Boolean(asOf),
         admit: (e) => passesCliRecallScopeFilter(e.scope ?? null, requested),
     };
-    if (search.usePhysics && !globalRoot) {
-        // Explain leaves minResults and includeSuperseded out to hold its output steady; asOf must reach physics or later rows leak.
-        const temporal = explain ? { asOf } : { minResults, includeSuperseded, asOf };
-        return physicsSearch(query, pool.local, {
-            budget, cost, hippoRoot: ctx.hippoRoot, physicsConfig: search.physicsConfig, scope, explain, vectorCandidates, ...temporal
-        });
-    }
     if (globalRoot) {
-        // searchBothHybrid reloads candidates itself, so the scope rule is passed in rather than inherited from the pool.
-        return searchBothHybrid(query, ctx.hippoRoot, globalRoot, {
+        // The pool already holds searchBothHybrid's additive-scope load for each store, so rank it rather than read both stores again.
+        return rankBothStores(query, { local: ctx.hippoRoot, global: globalRoot }, { local: pool.local, global: pool.global }, vectorCandidates, {
             budget, cost, explain, mmr, mmrLambda, localBump: search.localBump, minResults, scope, tenantId: ctx.tenantId,
             includeSuperseded, asOf,
-            recallScope: opts.explicitScope ? { requested: opts.explicitScope, additive: true } : {},
         });
     }
-    return hybridSearch(query, pool.local, {
-        budget, cost, hippoRoot: ctx.hippoRoot, explain, mmr, mmrLambda, minResults, scope, includeSuperseded, asOf, vectorCandidates
-    });
+    const physics = search.usePhysics ? search.physicsConfig : null;
+    // Physics takes no MMR; explain drops minResults and includeSuperseded to hold its output steady; asOf must reach physics or later rows leak.
+    const tuning = !physics ? { mmr, mmrLambda, minResults, includeSuperseded, asOf } : explain ? { asOf } : { minResults, includeSuperseded, asOf };
+    return searchByEngine(hippoDbSource(ctx.hippoRoot), query, pool.local, physics, { budget, cost, scope, explain, vectorCandidates, ...tuning });
+}
+/** The CLI core holds no store: it ranks on hippo.db under its root, as its loads above do. */
+function hippoDbSource(hippoRoot) {
+    const source = vectorSourceOf({ hippoRoot });
+    if (!source)
+        throw new Error('The CLI ranking core needs a hippo root to rank on');
+    return source;
 }
 /** Adds memories reached by walking the entity graph out from the lexical seeds. */
 function expandGraph(ctx, opts, graph, state) {

package/dist/api/recall-request.js

@@ -1,6 +1,6 @@
 // The recall and context input rules in one copy, so MCP and HTTP reject the same inputs with the same messages.
 import { BadRequestError } from '../core/api-errors.js';
-import { MAX_ID_LEN } from '../util/http-util.js';
+import { MAX_ID_LEN } from '../util/limits.js';
 import { isJsonString } from '../util/json.js';
 const MAX_RECALL_LIMIT = 1000;
 // recall() owns the shape rule for scorer_window (invalid_scorer_window); this cap bounds remote cost.

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

@@ -5,6 +5,7 @@ import type { PlanningFallacyHint, PlanningFallacyOutput, PlanningFallacyWatchin
 import type { AnchoringHint, RecallHistorySnapshot } from './recall-history.js';
 import type { AvailabilityHint } from './availability.js';
 import type { AppendAuditOpts } from '../store/audit.js';
+import type { HippoStore } from '../store/port.js';
 import type { CallerProject } from './prompt-hook.js';
 import type { RankRecallOpts, RankRecallResult } from './recall-pipeline.js';
 import type { RecallRecording } from './recall-finish.js';
@@ -60,9 +61,10 @@ export interface RecallOpts {
 }
 interface CliCoreRanking {
     rank: Omit<RankRecallOpts, 'query' | 'sessionId' | 'goalTag'>;
-    /** A second store searched beside `ctx.hippoRoot`. */
+    /** A second store searched beside `ctx.hippoRoot`; its recall rows go to `globalStore`, else hippo.db under `globalRoot`. */
     sources?: {
         globalRoot?: string;
+        globalStore?: HippoStore;
     };
     /** Receives each operator note when ranking reaches it. */
     note?: (line: string) => void;

package/dist/api/recall.d.ts

@@ -1,8 +1,5 @@
 import type { RecallOpts, RecallResult } from './recall-types.js';
 import { type Context } from './types.js';
-/** Reads hippo.db directly, never `ctx.store`, because it is synchronous (another store would throw `SqliteBlockedError`).
- *  It never writes `last_retrieval_ids` (contract lock: tests/api-recall-no-side-effects.test.ts). */
-export declare function recall(ctx: Context, opts: RecallOpts): RecallResult;
 /** The one recall entry: ranks with the ranker `opts` names, then writes the recall, and records it in full for a surface that sets `recordAs`.
  *  Only the CLI core ranker writes last_retrieval_ids (contract lock). */
 export declare function retrieve(ctx: Context, opts: RecallOpts): Promise<RecallResult>;

package/dist/api/recall.js

@@ -1,14 +1,12 @@
-// Read path: recall (sync) and retrieve (async, adds the vector arm).
+// Read path: retrieve, the one recall entry.
 import { envRequireSessionScopedFreshTail } from '../util/env.js';
 import { DEFAULT_SEARCH_CANDIDATE_LIMIT } from '../store/rows.js';
 import { recallScopeFilter } from '../store/search-rows.js';
 import { estimateTokens } from '../util/token-text.js';
 import { formatHandoffEvidenceLine } from '../core/handoff.js';
 import { boostByGoals } from '../search/goal-boost.js';
-import { storeFor } from '../store/index.js';
-import { sqliteSyncStore } from '../store/sqlite/store.js';
-import { hybridSearch } from '../search/hybrid.js';
-import { physicsSearch } from '../search/physics-search.js';
+import { storeFor } from '../store/sqlite/store.js';
+import { searchByEngine } from '../search/engine.js';
 import { churnStaleFactor } from '../search/boosts.js';
 import { compareEntryIdentity } from '../core/compare.js';
 import { dropHeldCopies, duplicateKey, storedTextKeys } from '../util/same-text.js';
@@ -17,26 +15,12 @@ import { classifyOriginProject, projectNames } from '../core/project-identity.js
 import { decidePlanningFallacy, detectPlanningClaim } from '../predictions/planning-fallacy.js';
 import { detectAnchoring, hashQueryText, biasHintEnabled } from './recall-history.js';
 import { detectAvailabilityBias } from './availability.js';
-import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../store/recall-scope.js';
+import { passesScopeFilterForRecall, assertScopeRequestAllowed, personalScopeOf } from '../core/recall-scope.js';
 import { ownerOrSubject, RecallContractError } from './types.js';
 import { anchoringRows, availabilityRows, callerOf, recallAuditMetadata, recallAuditRow, strengthenOf } from './recall-record.js';
 import { retrieveWithCliCore } from './recall-core.js';
 import { recallLead, recordShownRecall } from './recall-finish.js';
 const DEFAULT_RECALL_LIMIT = 10;
-/** Reads hippo.db directly, never `ctx.store`, because it is synchronous (another store would throw `SqliteBlockedError`).
- *  It never writes `last_retrieval_ids` (contract lock: tests/api-recall-no-side-effects.test.ts). */
-export function recall(ctx, opts) {
-    // A member key may not unlock a private or quarantined scope by naming it.
-    assertScopeRequestAllowed(ctx.actor, opts.scope);
-    const windowSize = recallWindowSize(opts);
-    const own = personalScopeOf(ctx.actor) ?? undefined;
-    const store = sqliteSyncStore(ctx.hippoRoot);
-    const all = store.searchRecallEntries(opts.query, recallSearchArgs(ctx, opts, windowSize, own));
-    const plan = planRecall(ctx, opts, all, own);
-    const { result, writes } = composeRecall(ctx, opts, { windowSize, all, plan, reads: readRecallSync(store, ctx, opts, plan) });
-    store.finishRecall({ ...writes, audit: [...(opts.leadingAudit ?? []), ...writes.audit] });
-    return result;
-}
 function recallOrigin(opts) {
     return opts.project ? projectNames(opts.project) : undefined;
 }
@@ -79,23 +63,28 @@ function shownBand(opts, result) {
 async function retrieveBand(ctx, store, opts, windowSize, own) {
     let candidates = await store.searchRecallEntries(opts.query, recallSearchArgs(ctx, opts, windowSize, own));
     if (opts.mode === 'hybrid' || opts.mode === 'physics') {
-        const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, scope: opts.scope ?? null, vectorCandidates: recallVectorSpec(ctx, opts, own), store };
-        const ranked = await rankPool(ctx, opts, candidates, searchOpts);
+        const searchOpts = { budget: Infinity, scope: opts.scope ?? null, vectorCandidates: recallVectorSpec(ctx, opts, own) };
+        const ranked = await searchByEngine({ root: ctx.hippoRoot, store }, opts.query, candidates, physicsFor(ctx, opts), searchOpts);
         const rankedIds = new Set(ranked.map((r) => r.entry.id));
         candidates = [...ranked.map((r) => r.entry), ...candidates.filter((e) => !rankedIds.has(e.id))];
     }
     const plan = planRecall(ctx, opts, candidates, own);
-    const { result, writes } = composeRecall(ctx, opts, { windowSize, all: candidates, plan, reads: await readRecall(store, ctx, opts, plan) });
+    const reads = await readRecall(store, ctx, opts, plan);
+    const { result, writes } = composeRecall(ctx, opts, { windowSize, all: candidates, plan, reads });
+    await finishBandRecall(store, ctx, opts, writes, result.results.map((r) => r.id));
+    return result;
+}
+/** The one recall write: the caller's leading audit rows go first, and the ids shown are the ones strengthened. */
+async function finishBandRecall(store, ctx, opts, writes, shownIds) {
     await store.finishRecall({
-        ...writes, audit: [...(opts.leadingAudit ?? []), ...writes.audit], strengthen: strengthenOf(ctx, result.results.map((r) => r.id))
+        ...writes,
+        audit: [...(opts.leadingAudit ?? []), ...writes.audit],
+        strengthen: strengthenOf(ctx, shownIds),
     });
-    return result;
 }
-/** The ranked pool: physics when `mode` says so, hybrid otherwise; each caller supplies its own search options. */
-function rankPool(ctx, opts, pool, searchOpts) {
-    return opts.mode === 'physics'
-        ? physicsSearch(opts.query, pool, { ...searchOpts, physicsConfig: loadConfig(ctx.hippoRoot).physics })
-        : hybridSearch(opts.query, pool, searchOpts);
+/** `mode` names the engine: physics with the store's config, hybrid otherwise. */
+function physicsFor(ctx, opts) {
+    return opts.mode === 'physics' ? loadConfig(ctx.hippoRoot).physics : null;
 }
 /** The recall load's arguments: exact scope, current rows only, the caller's project and personal scope. */
 function recallSearchArgs(ctx, opts, limit, own) {
@@ -127,8 +116,8 @@ async function retrieveFromStore(ctx, opts, windowSize, show, own) {
     const loaded = await store.searchRecallEntries(opts.query, recallSearchArgs(ctx, opts, Math.max(windowSize, SHOW_RANKED_LEXICAL_WINDOW), own));
     const pool = loaded.filter((e) => passesScopeFilterForRecall(e.scope ?? null, opts.scope, own));
     // No scope option: the scope boost follows HIPPO_SCOPE and the skill env, as MCP recall always ranked.
-    const searchOpts = { budget: Infinity, hippoRoot: ctx.hippoRoot, vectorCandidates: recallVectorSpec(ctx, opts, own), store };
-    let ranked = await rankPool(ctx, opts, pool, searchOpts);
+    const searchOpts = { budget: Infinity, vectorCandidates: recallVectorSpec(ctx, opts, own) };
+    let ranked = await searchByEngine({ root: ctx.hippoRoot, store }, opts.query, pool, physicsFor(ctx, opts), searchOpts);
     // One goal read serves both boosts; the ranked list's log rows come first, so its scores win the log's first-write.
     const goals = opts.sessionId && !opts.goalTag ? await store.activeGoals({ sessionId: opts.sessionId, tenantId: ctx.tenantId }) : null;
     let rankedLog = [];
@@ -140,27 +129,26 @@ async function retrieveFromStore(ctx, opts, windowSize, show, own) {
     const window = ranked.slice(0, windowSize).map((r) => r.entry);
     const bandOpts = { ...opts, suppressRecallTrace: true };
     const plan = planRecall(ctx, bandOpts, window, own);
-    const { result, writes } = composeRecall(ctx, bandOpts, {
-        windowSize, all: window, plan, reads: await readRecall(store, ctx, bandOpts, plan, goals), auditBand: false
-    });
+    const reads = await readRecall(store, ctx, bandOpts, plan, goals);
+    const { result, writes } = composeRecall(ctx, bandOpts, { windowSize, all: window, plan, reads, auditBand: false });
     // Rows the vector arm added count as candidates too.
     const inPool = new Set(pool.map((e) => e.id));
     const candidates = [...pool, ...ranked.map((r) => r.entry).filter((e) => !inPool.has(e.id))];
     const shown = show({ ranked, pool: candidates, droppedByScope: loaded.length - pool.length }, result);
     const scores = new Map(ranked.map((r) => [r.entry.id, r.score]));
     const shownRow = recallAuditRow(callerOf(ctx), 'recall', undefined, recallAuditMetadata(opts.query, shown.ids.length));
-    await store.finishRecall({
+    const trace = opts.suppressRecallTrace ? undefined : {
+        tenantId: ctx.tenantId,
+        sessionId: opts.sessionId ?? null,
+        pipeline: 'mcp',
+        query: opts.query,
+        results: shown.ids.map((id) => ({ memoryId: id, score: scores.get(id) ?? 0 })),
+    };
+    await finishBandRecall(store, ctx, opts, {
         goalLog: [...rankedLog, ...writes.goalLog],
-        audit: [...(opts.leadingAudit ?? []), ...writes.audit, shownRow, ...shown.audit],
-        trace: opts.suppressRecallTrace ? undefined : {
-            tenantId: ctx.tenantId,
-            sessionId: opts.sessionId ?? null,
-            pipeline: 'mcp',
-            query: opts.query,
-            results: shown.ids.map((id) => ({ memoryId: id, score: scores.get(id) ?? 0 })),
-        },
-        strengthen: strengthenOf(ctx, shown.ids),
-    });
+        audit: [...writes.audit, shownRow, ...shown.audit],
+        trace,
+    }, shown.ids);
     return result;
 }
 /** Contract preflight: throws before any store-touching work. */
@@ -198,27 +186,17 @@ function planRecall(ctx, opts, all, own) {
         claim: detectPlanningClaim(opts.query),
     };
 }
-/** The plan's reads on the synchronous store, for the recall that cannot await the port. */
-function readRecallSync(store, ctx, opts, plan) {
-    const { tenantId } = ctx;
-    const freshCount = opts.freshTailCount ?? 0;
-    return {
-        goals: plan.goalBoost ? store.activeGoals({ sessionId: plan.goalBoost.sessionId, tenantId }) : null,
-        parents: plan.overflow.size > 0 ? store.entriesByIds([...plan.overflow.keys()], tenantId) : [],
-        freshRaws: freshCount > 0 ? store.freshRawEntries(freshCount, tenantId, opts.freshTailSessionId, recallOrigin(opts) ?? null) : [],
-        continuity: opts.includeContinuity ? store.continuity(tenantId, CONTINUITY_EVENT_LIMIT, continuityKey(ctx, opts)) : undefined,
-        planning: plan.claim ? store.planningFallacyEvidence(tenantId, plan.claim.classQueryTokens) : null,
-    };
-}
 /** The plan's reads through the store; `goals` already read by the caller skips that read. */
 async function readRecall(store, ctx, opts, plan, goals) {
     const { tenantId } = ctx;
     const freshCount = opts.freshTailCount ?? 0;
+    const parentIds = plan.overflow.size > 0 ? [...plan.overflow.keys()] : null;
+    const continuity = opts.includeContinuity ? { key: continuityKey(ctx, opts) } : null;
     return {
         goals: goals !== undefined ? goals : plan.goalBoost ? await store.activeGoals({ sessionId: plan.goalBoost.sessionId, tenantId }) : null,
-        parents: plan.overflow.size > 0 ? await store.entriesByIds([...plan.overflow.keys()], tenantId) : [],
+        parents: parentIds ? await store.entriesByIds(parentIds, tenantId) : [],
         freshRaws: freshCount > 0 ? await store.freshRawEntries(freshCount, tenantId, opts.freshTailSessionId, recallOrigin(opts) ?? null) : [],
-        continuity: opts.includeContinuity ? await store.continuity(tenantId, CONTINUITY_EVENT_LIMIT, continuityKey(ctx, opts)) : undefined,
+        continuity: continuity ? await store.continuity(tenantId, CONTINUITY_EVENT_LIMIT, continuity.key) : undefined,
         planning: plan.claim ? await store.planningFallacyEvidence(tenantId, plan.claim.classQueryTokens) : null,
     };
 }
@@ -461,19 +439,19 @@ function scopeContinuity(block, opts, own) {
 function continuityTokensOf(c) {
     const filteredSnapshot = c.activeSnapshot;
     const filteredHandoff = c.sessionHandoff;
-    const tokenize = (s) => s ? estimateTokens(s) : 0;
-    return tokenize(filteredSnapshot?.task) +
-        tokenize(filteredSnapshot?.summary) +
-        tokenize(filteredSnapshot?.next_step) +
-        tokenize(filteredHandoff?.summary) +
-        tokenize(filteredHandoff?.nextAction) +
-        (filteredHandoff?.artifacts ?? []).reduce((acc, a) => acc + tokenize(a), 0) +
-        (filteredHandoff?.constraints ?? []).reduce((acc, c) => acc + tokenize(c), 0) +
-        tokenize(filteredHandoff?.evidence ? formatHandoffEvidenceLine(filteredHandoff.evidence) : null) +
-        tokenize(filteredHandoff?.outcome) +
-        tokenize(filteredHandoff?.targetRuntime) +
-        tokenize(filteredHandoff?.cardId) +
-        c.recentSessionEvents.reduce((acc, e) => acc + tokenize(e.content), 0);
+    const tokenCount = (s) => s ? estimateTokens(s) : 0;
+    return tokenCount(filteredSnapshot?.task) +
+        tokenCount(filteredSnapshot?.summary) +
+        tokenCount(filteredSnapshot?.next_step) +
+        tokenCount(filteredHandoff?.summary) +
+        tokenCount(filteredHandoff?.nextAction) +
+        (filteredHandoff?.artifacts ?? []).reduce((acc, a) => acc + tokenCount(a), 0) +
+        (filteredHandoff?.constraints ?? []).reduce((acc, c) => acc + tokenCount(c), 0) +
+        tokenCount(filteredHandoff?.evidence ? formatHandoffEvidenceLine(filteredHandoff.evidence) : null) +
+        tokenCount(filteredHandoff?.outcome) +
+        tokenCount(filteredHandoff?.targetRuntime) +
+        tokenCount(filteredHandoff?.cardId) +
+        c.recentSessionEvents.reduce((acc, e) => acc + tokenCount(e.content), 0);
 }
 // A pure read of the caller's recallHistory snapshot against this top-1. HIPPO_ANCHORING=off skips even the detect
 // call; CLI paths pass no history (cmdRecall computes its own hint), so the hint stays absent there.

package/dist/api/remember-local.d.ts

@@ -1,4 +1,5 @@
 import type { ConfidenceLevel, Layer, MemoryEntry, MemoryKind } from '../core/memory.js';
+import { type EmbedOutcome } from '../search/embed-memories.js';
 import type { HippoDbContext } from './types.js';
 /** One write by a caller in this process, every field already parsed and checked by it. */
 export interface LocalRememberInput {
@@ -23,10 +24,12 @@ export interface StartedWeak {
     readonly reason: string;
     readonly strength: number;
 }
-/** `stored` carries the row as the store holds it after the write; `skipped` is the gate dropping the write, with nothing stored or counted. */
+/** `stored` carries the row as the store holds it after the write, and `embedding`, which settles with whether the row reached the vector index
+ *  (a caller may ignore it; a failure is also logged). `skipped` is the gate dropping the write, with nothing stored or counted. */
 export type LocalRememberOutcome = {
     readonly status: 'stored';
     readonly entry: MemoryEntry;
+    readonly embedding: Promise<EmbedOutcome>;
     readonly startedWeak?: StartedWeak;
 } | {
     readonly status: 'skipped';
@@ -34,7 +37,7 @@ export type LocalRememberOutcome = {
     readonly score: number;
 };
 /** One local write on hippo.db: gate, write, read-back, counter, then the embedding, started and never awaited. A refused value throws as `remember` does. */
-export declare function rememberLocally(ctx: HippoDbContext, input: LocalRememberInput): LocalRememberOutcome;
+export declare function rememberLocally(ctx: HippoDbContext, input: LocalRememberInput): Promise<LocalRememberOutcome>;
 /** What a caller asks of fact extraction. The key comes from the caller, which read it from its own environment. */
 export interface FactExtractionRequest {
     /** The caller asked for extraction (`--extract`); the store's config can turn it on without that. */

package/dist/api/remember-local.js

@@ -4,10 +4,10 @@
 import { loadConfig } from '../core/config.js';
 import { computeSalience } from '../core/salience.js';
 import { loadNewestEntries, schemaFitInStore } from '../store/candidates.js';
-import { embedMemory } from '../store/embeddings/index.js';
+import { embedMemory } from '../search/embed-memories.js';
 import { loadAllEntries, readEntry } from '../store/entry-reads.js';
 import { updateStats } from '../store/index-and-stats.js';
-import { errorMessage } from '../util/log.js';
+import { errorMessage, log } from '../util/log.js';
 import { remember } from './remember.js';
 const WEAK_HALF_LIFE_FACTOR = 0.5;
 /** The gate's verdict on one write, or null where it does not judge: the store has it off, or the write is pinned or forced. */
@@ -34,14 +34,23 @@ function storedEntry(ctx, id) {
         throw new Error(`memory ${id} was written but cannot be read back`);
     return entry;
 }
+/** Best-effort and slow (a model load or a network call), so the caller is not held for it; a row left out of the index is logged. */
+function indexInBackground(hippoRoot, entry) {
+    return embedMemory(hippoRoot, entry).then((outcome) => {
+        if (outcome === 'failed') {
+            log.warn(`memory ${entry.id} is stored but not in the vector index, so recall by meaning will miss it; run 'hippo embed' to index it`);
+        }
+        return outcome;
+    });
+}
 /** One local write on hippo.db: gate, write, read-back, counter, then the embedding, started and never awaited. A refused value throws as `remember` does. */
-export function rememberLocally(ctx, input) {
+export async function rememberLocally(ctx, input) {
     const schemaFit = schemaFitInStore(ctx.hippoRoot, ctx.tenantId, input.content, input.fitTags ?? input.tags);
     const verdict = salienceVerdict(ctx, input);
     if (verdict?.decision === 'skip')
         return { status: 'skipped', reason: verdict.reason, score: verdict.score };
     const startedWeak = verdict?.decision === 'start_weak' ? { reason: verdict.reason, strength: verdict.score } : undefined;
-    const { id } = remember(ctx, {
+    const { id } = await remember(ctx, {
         content: input.content,
         kind: input.kind,
         scope: input.scope,
@@ -59,9 +68,8 @@ export function rememberLocally(ctx, input) {
     });
     const entry = storedEntry(ctx, id);
     updateStats(ctx.hippoRoot, { remembered: 1 });
-    // Best-effort and slow (a model load or a network call), so the caller is not held for it.
-    void embedMemory(ctx.hippoRoot, entry);
-    return startedWeak ? { status: 'stored', entry, startedWeak } : { status: 'stored', entry };
+    const embedding = indexInBackground(ctx.hippoRoot, entry);
+    return startedWeak ? { status: 'stored', entry, embedding, startedWeak } : { status: 'stored', entry, embedding };
 }
 /** Extracts facts from a row just stored and stores them beside it. Best-effort: a failure is named in the result, never thrown. */
 export async function extractRememberedFacts(ctx, entry, request) {

package/dist/api/remember.d.ts

@@ -1,6 +1,6 @@
 import type { ConnectorEvent } from '../store/port.js';
 import { type ConfidenceLevel, type Layer, type MemoryKind, type TraceOutcome } from '../core/memory.js';
-import type { Context, StoreReply } from './types.js';
+import type { Context } from './types.js';
 /** Row fields the caller's own process decides, as the CLI does from its flags and its salience gate. */
 export interface RememberLocal {
     layer?: Layer;
@@ -23,7 +23,8 @@ export interface RememberOpts {
     owner?: string;
     artifactRef?: string;
     tags?: string[];
-    /** The connector event this write answers. The store logs it in the memory's own transaction; an event logged before stores nothing and answers `duplicate`. */
+    /** The connector event this write answers. The store logs it in the memory's own transaction; an event logged before stores nothing and
+     * answers `duplicate`. */
     event?: ConnectorEvent;
     /** Connector-ingested content an agent doesn't control; gates detectInstruction. CLI/HTTP/MCP never set this. */
     untrusted?: boolean;
@@ -41,6 +42,9 @@ export interface RememberResult {
     id: string;
     kind: MemoryKind;
     tenantId: string;
+    /** The row as written, so a caller can show it without reading it back. */
+    halfLifeDays: number;
+    tags: string[];
     /** Set only when untrusted content was flagged and quarantined instead of stored under its requested scope. */
     quarantined?: {
         reason: string;
@@ -54,5 +58,5 @@ export interface RememberResult {
 }
 /** Store one memory: the store's entryWrites group writes the row and its one remember audit row, under the caller's subject.
  *  A write that carries a connector event or untrusted content goes through connectorWrites, which commits its companion rows with it. */
-export declare function remember<C extends Context>(ctx: C, opts: RememberOpts): StoreReply<C, RememberResult>;
+export declare function remember(ctx: Context, opts: RememberOpts): Promise<RememberResult>;
 //# sourceMappingURL=remember.d.ts.map

package/dist/api/remember.js

@@ -7,8 +7,9 @@ import { loadConfig } from '../core/config.js';
 import { vetSecrets } from '../util/secret-detect.js';
 import { assertCallerProject } from '../core/project-identity.js';
 import { BadRequestError } from '../core/api-errors.js';
-import { assertClientScope, personalScopeOf } from '../store/recall-scope.js';
-import { andThen, notPorted, onStore } from './on-store.js';
+import { assertClientScope, personalScopeOf } from '../core/recall-scope.js';
+import { requireGroup } from '../store/index.js';
+import { storeFor } from '../store/sqlite/store.js';
 /** The scope a write lands in: the caller's own personal scope when asked for, else the client's, which may not be a personal one. */
 function rememberScope(ctx, opts) {
     if (!opts.personal) {
@@ -21,7 +22,8 @@ function rememberScope(ctx, opts) {
         throw new BadRequestError('send personal or scope, not both');
     const own = personalScopeOf(ctx.actor);
     if (own === null) {
-        throw new BadRequestError('personal memories need a key its owner minted, or a sign-in; owner ids over 239 characters or with control characters cannot hold them');
+        throw new BadRequestError('personal memories need a key its owner minted, or a sign-in; owner ids over 239 characters or with control characters cannot ' +
+            'hold them');
     }
     return own;
 }
@@ -59,7 +61,7 @@ function weakened(entry, weaken) {
 }
 function rememberResult(ctx, prepared, written) {
     const { entry, detection, warnings } = prepared;
-    const result = { id: entry.id, kind: entry.kind, tenantId: ctx.tenantId };
+    const result = { id: entry.id, kind: entry.kind, tenantId: ctx.tenantId, halfLifeDays: entry.half_life_days, tags: [...entry.tags] };
     if (detection.flagged)
         result.quarantined = { reason: detection.reason ?? 'unknown' };
     if (warnings.length > 0)
@@ -74,17 +76,18 @@ function quarantineOf({ requestedScope, detection }) {
 }
 /** Store one memory: the store's entryWrites group writes the row and its one remember audit row, under the caller's subject.
  *  A write that carries a connector event or untrusted content goes through connectorWrites, which commits its companion rows with it. */
-export function remember(ctx, opts) {
-    return onStore(ctx, (port) => {
-        const entryWrites = port.entryWrites ?? notPorted(port, 'entryWrites');
-        const prepared = prepareRemember(ctx, opts);
-        // A store writes origin_project as given, so the served folder's fallback is stamped here.
-        const write = { entry: stampOriginProject(ctx.hippoRoot, prepared.entry), actor: ctx.actor.subject };
-        if (opts.untrusted !== true && opts.event === undefined)
-            return andThen(entryWrites.writeEntry(write), () => rememberResult(ctx, prepared));
-        const connectorWrites = port.connectorWrites ?? notPorted(port, 'connectorWrites');
-        const written = connectorWrites.writeConnectorEntry({ ...write, event: opts.event, quarantine: quarantineOf(prepared) });
-        return andThen(written, (outcome) => rememberResult(ctx, prepared, outcome));
-    });
+export async function remember(ctx, opts) {
+    const store = storeFor(ctx);
+    const entryWrites = requireGroup(store, 'entryWrites');
+    const prepared = prepareRemember(ctx, opts);
+    // A store writes origin_project as given, so the served folder's fallback is stamped here.
+    const write = { entry: stampOriginProject(ctx.hippoRoot, prepared.entry), actor: ctx.actor.subject };
+    if (opts.untrusted !== true && opts.event === undefined) {
+        await entryWrites.writeEntry(write);
+        return rememberResult(ctx, prepared);
+    }
+    const connectorWrites = requireGroup(store, 'connectorWrites');
+    const written = await connectorWrites.writeConnectorEntry({ ...write, event: opts.event, quarantine: quarantineOf(prepared) });
+    return rememberResult(ctx, prepared, written);
 }
 //# sourceMappingURL=remember.js.map

package/dist/api/session-end.d.ts

@@ -0,0 +1,46 @@
+import type { HandoffEvidence } from '../core/handoff.js';
+import type { TaskSnapshot } from '../store/rows.js';
+import type { Context } from './types.js';
+/** What closing one ended session needs from the host; the two readers run only when the handoff is written. */
+export interface SessionClose {
+    sessionId: string | null;
+    /** A reply's end, not the session's: the handoff is updated in place and the snapshot stays for the next compaction. */
+    turn: boolean;
+    /** The transcript's working state, or null with no readable transcript. */
+    workingState: () => Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null;
+    evidence: () => HandoffEvidence;
+    /** One line to the session-end log. */
+    log: (line: string) => void;
+}
+/** Writes the session's handoff, then closes its snapshot unless `turn`; each step logs its own failure and never throws.
+ *  The handoff goes first, while the snapshot writeSessionEndHandoff reads is still active. */
+export declare function closeEndedSession(ctx: Context, close: SessionClose): void;
+/** Books the ending session's re-reads in each store its ledger rows can land in (`ctx.hippoRoot` and global); returns the log lines. */
+export declare function bookSessionRereads(ctx: Context, transcriptPath: string | undefined, sessionId: string | null): Promise<string[]>;
+/** The block a compaction lost: the fresh task snapshot and its session trail, or null with none or another session's snapshot. */
+export declare function compactResumeBlock(ctx: Context, payloadSessionId: string | null): string | null;
+/** What one session-end run needs from its host; the host owns sleep, transcript reading and capture, this module owns the order. */
+export interface SessionEndWork<Scan> {
+    mode: 'turn' | 'full';
+    hippoRoot: string;
+    tenantId: string;
+    sessionId: string | null;
+    transcriptPath: string | undefined;
+    /** Builds the call context for one store root. */
+    contextFor: (root: string) => Context;
+    /** The store the run captures into: the project store, else global. */
+    storeRoot: () => string;
+    /** One line to the session-end log; `startFresh` restarts the file. */
+    log: (line: string, opts?: {
+        startFresh?: boolean;
+    }) => void;
+    sleep: () => Promise<void>;
+    readScan: (log: (line: string) => void) => Scan | null;
+    capture: (store: string, scan: Scan | null) => void;
+    digest: (scan: Scan | null, log: (line: string) => void) => void;
+    workingState: (log: (line: string) => void) => ReturnType<SessionClose['workingState']>;
+    evidence: () => HandoffEvidence;
+}
+/** Books re-reads, sleeps, captures, digests and closes one ended session, in that order. */
+export declare function sessionEndWork<Scan>(w: SessionEndWork<Scan>): Promise<void>;
+//# sourceMappingURL=session-end.d.ts.map