hippo-memory 1.64.1 → 1.66.0

package/dist/server/routes/recall.js

@@ -3,185 +3,44 @@ import { dirname, resolve } from 'node:path';
 import { assertCallerProject, resolveProjectIdentity } from '../../project-identity.js';
 import { isSharedStore } from '../../config.js';
 import { assembleCost, contextCost, drillCost } from '../../context-render.js';
-import { closeHippoDb, openHippoDb } from '../../db.js';
-import { updateStats } from '../../store/index-and-stats.js';
-import { appendRecall, biasHintEnabled, buildSessionKey, getOrCreateRing, hashQueryText, snapshotRing } from '../../recall-history.js';
-import { appendAuditEvent, auditQueryFields } from '../../audit.js';
+import { storeFor } from '../../store-port.js';
+import { biasHintEnabled } from '../../recall-history.js';
 import { assemble, drillDown, getContext, recordTokens, retrieve } from '../../api.js';
-import { HttpError, MAX_ID_LEN, sendJson } from '../../http-util.js';
+import { httpParams, parseContextRequest, parseRecallRequest } from '../../api/recall-request.js';
+import { anchorSkippedRows, noteRecall, peekSessionRing, resetSessionRings, sessionRing } from '../../api/recall-record.js';
+import { HttpError, sendJson } from '../../http-util.js';
 import { buildContextWithAuth } from '../auth.js';
-import { parseListLimit, validateIdSegment } from '../validation.js';
-// Module-level per-(tenant, session) recall-history ring map
-// for the HTTP pipeline. Separate from CLI/MCP rings (per-
-// pipeline rings; no IPC). HTTP is the only caller that threads its
-// snapshot through opts.recallHistory to api.recall — api.recall's
-// anchoringHint on the returned RecallResult IS the user-visible hint
-// here (no separate compute needed).
-const sessionRecallHistoryHttp = new Map();
-/** Test-only: reset the module-level recall-history Map. Call from beforeEach. */
+import { validateIdSegment } from '../validation.js';
+/** Test-only: reset the HTTP recall rings. Call from beforeEach. */
 export function __resetSessionRecallHistoryHttp() {
-    sessionRecallHistoryHttp.clear();
+    resetSessionRings('http');
 }
-function parseFreshTail(query) {
-    // Surface the fresh-tail RecallOpts to HTTP callers so session-scoped
-    // fresh-tail and summary substitution are not JS-only.
-    const freshTailCountRaw = query.get('fresh_tail_count');
-    const freshTailCount = freshTailCountRaw === null ? undefined : Number(freshTailCountRaw);
-    if (freshTailCount !== undefined && (!Number.isFinite(freshTailCount) || freshTailCount < 0)) {
-        throw new HttpError(400, 'fresh_tail_count must be a non-negative number');
-    }
-    // Cap session_id length consistent with the
-    // rest of the API. Untrimmed strings round-trip through the SQL layer
-    // and through any downstream metric/log; 256 is generous for a session
-    // id and matches the rest of this file's id-shaped param parsers.
-    const freshTailSessionIdRaw = query.get('fresh_tail_session_id');
-    if (freshTailSessionIdRaw !== null && freshTailSessionIdRaw.length > MAX_ID_LEN) {
-        throw new HttpError(400, `fresh_tail_session_id exceeds ${MAX_ID_LEN}-character cap`);
-    }
-    const freshTailSessionId = freshTailSessionIdRaw && freshTailSessionIdRaw.length > 0
-        ? freshTailSessionIdRaw
-        : undefined;
-    return { freshTailCount, freshTailSessionId };
-}
-function parseSessionId(query) {
-    // session_id for the dlPFC goal-stack boost. 256-char cap mirrors
-    // fresh_tail_session_id (above). Trim then drop if empty so api.recall
-    // sees undefined when the param is omitted or whitespace-only.
-    const sessionIdRaw = query.get('session_id');
-    if (sessionIdRaw !== null && sessionIdRaw.length > MAX_ID_LEN) {
-        throw new HttpError(400, `session_id exceeds ${MAX_ID_LEN}-character cap`);
-    }
-    return sessionIdRaw && sessionIdRaw.trim().length > 0
-        ? sessionIdRaw.trim()
-        : undefined;
-}
-function parseRecallQuery(query) {
-    const q = query.get('q');
-    if (!q) {
-        throw new HttpError(400, 'q is required');
-    }
-    const limitRaw = query.get('limit');
-    const limit = limitRaw === null ? undefined : parseListLimit(limitRaw);
-    const mode = query.get('mode');
-    if (mode !== null && mode !== 'bm25' && mode !== 'hybrid' && mode !== 'physics') {
-        throw new HttpError(400, "mode must be 'bm25', 'hybrid', or 'physics'");
-    }
-    const scope = query.get('scope');
-    const includeContinuityRaw = query.get('include_continuity');
-    const includeContinuity = includeContinuityRaw === '1'
-        || includeContinuityRaw === 'true';
-    const { freshTailCount, freshTailSessionId } = parseFreshTail(query);
-    // Strict parse matching the includeContinuity convention, so values
-    // like `?summarize_overflow=banana` or an empty value do not turn it on.
-    const summarizeOverflowRaw = query.get('summarize_overflow');
-    const summarizeOverflow = summarizeOverflowRaw === null
-        ? undefined
-        : (summarizeOverflowRaw === '1' || summarizeOverflowRaw === 'true');
-    // recall() owns the shape rule (NaN, 0 and negatives throw invalid_scorer_window); the transport caps remote cost.
-    const scorerWindowRaw = query.get('scorer_window');
-    const scorerWindow = scorerWindowRaw === null ? undefined : Number(scorerWindowRaw);
-    if (scorerWindow !== undefined && scorerWindow > 1000) {
-        throw new HttpError(400, 'scorer_window must be <= 1000');
-    }
-    const sessionId = parseSessionId(query);
-    // Recall-trace: opt-in explain flag. When set, api.recall attaches the
-    // lifecycle re-ranking trace (goal-boost step on the api pipeline) +
-    // rerankPipeline:'api' to each result item; the field then rides on the
-    // serialized RecallResult. Mirrors the include_continuity convention.
-    const explainRaw = query.get('explain');
-    const explain = explainRaw === '1' || explainRaw === 'true';
-    return { q, limit, mode, scope, includeContinuity, freshTailCount, freshTailSessionId, summarizeOverflow, scorerWindow, sessionId, explain };
-}
-// HTTP per-pipeline anchoring detector. HTTP threads its
-// ring snapshot via opts.recallHistory so api.recall's own
-// anchoringHint compute path activates. Unlike CLI (which computes
-// its own hint separately because cmdRecall runs its own physics/
-// hybrid pipeline outside api.recall), HTTP's /v1/memories response
-// body IS api.recall's result directly. So the api.recall-computed
-// hint flows through. HIPPO_ANCHORING=off short-circuits.
-function snapshotSessionRing(ctx, hippoRoot, q, sessionId) {
-    let httpRecallHistory;
-    let httpRingKey;
-    if (biasHintEnabled('anchoring')) {
-        if (sessionId) {
-            // Do NOT mutate sessionRecallHistoryHttp before recall() preflight: a request
-            // that 400s would otherwise create-or-touch a ring and LRU-evict valid sessions.
-            httpRingKey = buildSessionKey(ctx.tenantId, sessionId);
-            const existingRing = sessionRecallHistoryHttp.get(httpRingKey);
-            httpRecallHistory = existingRing ? snapshotRing(existingRing) : [];
-        }
-        else {
-            // Telemetry: caller had no session_id so ring tracking skipped.
-            // Per the normal recall-audit convention (api.ts:854 stores
-            // SHA-256/16 hash of the query, NOT raw text), avoid retaining
-            // prompts in audit_log here too — query content can contain
-            // secrets, PII, or RTBF-restricted material. hashQueryText is a 32-bit
-            // FNV-1a, NOT a privacy hash, so use the recall audit's SHA-256/16 truncation.
-            const dbForAudit = openHippoDb(hippoRoot);
-            try {
-                appendAuditEvent(dbForAudit, {
-                    tenantId: ctx.tenantId,
-                    actor: ctx.actor.subject,
-                    op: 'recall_anchor_skipped_no_session',
-                    targetId: undefined,
-                    metadata: auditQueryFields(q),
-                });
-            }
-            finally {
-                closeHippoDb(dbForAudit);
-            }
-        }
-    }
-    return { httpRecallHistory, httpRingKey };
-}
-function recallExtraOpts(parsed, httpRecallHistory) {
-    const recallExtra = {};
-    if (parsed.freshTailCount !== undefined)
-        recallExtra.freshTailCount = parsed.freshTailCount;
-    if (parsed.freshTailSessionId !== undefined)
-        recallExtra.freshTailSessionId = parsed.freshTailSessionId;
-    if (parsed.summarizeOverflow !== undefined)
-        recallExtra.summarizeOverflow = parsed.summarizeOverflow;
-    if (parsed.scorerWindow !== undefined)
-        recallExtra.scorerWindow = parsed.scorerWindow;
-    if (parsed.sessionId !== undefined)
-        recallExtra.sessionId = parsed.sessionId;
-    if (httpRecallHistory !== undefined)
-        recallExtra.recallHistory = httpRecallHistory;
-    if (parsed.explain)
-        recallExtra.explain = parsed.explain;
-    return recallExtra;
+// HTTP threads the ring through opts.recallHistory, so the hint retrieve() returns is the one the caller sees.
+function recallHistoryFor(ctx, sessionId) {
+    return sessionId && biasHintEnabled('anchoring') ? peekSessionRing('http', ctx.tenantId, sessionId) : undefined;
 }
 // GET /v1/memories?q=...&limit=...&mode=...&scope=...&include_continuity=1
 export async function handleRecallMemories({ req, res, opts, query }) {
-    const parsed = parseRecallQuery(query);
-    const { q, includeContinuity, sessionId } = parsed;
+    const { opts: recallOpts, limit, mode, explain } = parseRecallRequest(httpParams(query));
+    const { query: q, includeContinuity, sessionId } = recallOpts;
     const ctx = await buildContextWithAuth(req, opts);
-    const { httpRecallHistory, httpRingKey } = snapshotSessionRing(ctx, opts.hippoRoot, q, sessionId);
-    const result = await retrieve(ctx, {
-        query: q,
-        limit: parsed.limit,
-        mode: parsed.mode ?? undefined,
-        scope: parsed.scope ?? undefined,
-        includeContinuity,
-        ...recallExtraOpts(parsed, httpRecallHistory),
-    });
-    // Append only after recall succeeds, so a 400 cannot LRU-evict valid sessions;
-    // anchoredOn feeds the cooldown logic for the NEXT recall on this session.
-    if (httpRingKey) {
-        const httpRing = getOrCreateRing(sessionRecallHistoryHttp, httpRingKey);
-        const topId = result.results[0]?.id ?? null;
-        appendRecall(httpRing, hashQueryText(q), topId, result.anchoringHint?.memoryId);
-    }
+    const recallHistory = recallHistoryFor(ctx, sessionId);
+    // Written first in the recall's own write, so a recall that fails leaves no row.
+    const leadingAudit = sessionId ? [] : anchorSkippedRows({ tenantId: ctx.tenantId, actor: ctx.actor.subject }, q);
+    const result = await retrieve(ctx, { ...recallOpts, limit, mode, explain, recallHistory, leadingAudit });
+    // The ring is created only after recall succeeds, so a 400 cannot LRU-evict a live session.
+    const ring = sessionRing('http', ctx.tenantId, sessionId);
+    if (ring)
+        noteRecall(ring, q, result.results[0]?.id ?? null, result.anchoringHint?.memoryId);
     // Each recall surface counts its own hits; api.recall is no chokepoint,
     // since the CLI never calls it and MCP shows the user a different band.
-    updateStats(opts.hippoRoot, { recalled: result.results.length });
+    await storeFor(ctx).bumpRecallStats(result.results.length);
     // Continuity payloads should never be cached. The caller is asking for
     // session-state-aware data; intermediaries must not reuse it across users.
     if (includeContinuity) {
         res.setHeader('Cache-Control', 'no-store');
     }
-    recordTokens(ctx, 'http_recall', { items: result.results.length, tokens: result.tokens + (result.continuityTokens ?? 0), sessionId: sessionId ?? null });
+    await recordTokens(ctx, 'http_recall', { items: result.results.length, tokens: result.tokens + (result.continuityTokens ?? 0), sessionId: sessionId ?? null });
     sendJson(res, 200, result);
     return;
 }
@@ -220,7 +79,7 @@ export async function handleAssembleSession({ req, res, opts, query }, assembleM
     if (scope !== undefined)
         assembleExtra.scope = scope;
     const result = assemble(ctx, assembleMatch.id, { ...assembleExtra, cost: assembleCost(assembleMatch.id) });
-    recordTokens(ctx, 'http_assemble', { items: result.items.length, tokens: result.tokens, sessionId: assembleMatch.id });
+    await recordTokens(ctx, 'http_assemble', { items: result.items.length, tokens: result.tokens, sessionId: assembleMatch.id });
     sendJson(res, 200, result);
     return;
 }
@@ -290,64 +149,14 @@ function contextReader(hippoRoot, query) {
 // via the Bearer. Pinned-only + '*' fallback skip the recall audit emit
 // (matches cmdContext); real-query hybrid search emits one 'recall' row.
 export async function handleGetContext({ req, res, opts, query }) {
-    const q = query.get('q') ?? undefined;
-    // DoS cap on q-param length. 1024 covers real multi-clause queries
-    // (pasted error messages, multi-stem searches) while bounding BM25
-    // tokenisation cost (~150 tokens worst case at 1024 chars).
-    if (q !== undefined && q.length > 1024) {
-        throw new HttpError(400, 'q exceeds 1024-character cap');
-    }
-    const budgetRaw = query.get('budget');
-    let budget;
-    if (budgetRaw !== null) {
-        budget = Number(budgetRaw);
-        if (!Number.isFinite(budget) || budget < 0) {
-            throw new HttpError(400, 'budget must be a non-negative number');
-        }
-    }
-    const limitRaw = query.get('limit');
-    let limit;
-    if (limitRaw !== null) {
-        limit = Number(limitRaw);
-        if (!Number.isFinite(limit) || limit <= 0) {
-            throw new HttpError(400, 'limit must be a positive number');
-        }
-    }
-    const pinnedOnlyRaw = query.get('pinned_only');
-    const pinnedOnly = pinnedOnlyRaw === '1' || pinnedOnlyRaw === 'true';
-    const scopeRaw = query.get('scope');
-    if (scopeRaw !== null && scopeRaw.length > MAX_ID_LEN) {
-        throw new HttpError(400, `scope exceeds ${MAX_ID_LEN}-character cap`);
-    }
-    const scope = scopeRaw === null ? undefined : scopeRaw;
-    const includeRecentRaw = query.get('include_recent');
-    let includeRecent;
-    if (includeRecentRaw !== null) {
-        includeRecent = Number(includeRecentRaw);
-        if (!Number.isFinite(includeRecent) || includeRecent < 0) {
-            throw new HttpError(400, 'include_recent must be a non-negative number');
-        }
-    }
-    // v39 memory scope isolation: cross_project=1|true re-includes
-    // other-project rows (tagged category 'cross-project' in the response).
-    // The partition identity comes from the SERVED STORE's location, not the
-    // daemon's process cwd - a daemon started from anywhere still isolates
-    // the project it serves.
-    const crossProjectRaw = query.get('cross_project');
-    const crossProject = crossProjectRaw === '1' || crossProjectRaw === 'true';
+    const parsed = parseContextRequest(httpParams(query));
     const ctx = await buildContextWithAuth(req, opts);
     const result = await getContext(ctx, {
-        q,
-        budget,
-        limit,
-        pinnedOnly,
-        scope,
-        includeRecent,
-        crossProject,
+        ...parsed,
         currentProject: contextReader(opts.hippoRoot, query),
         cost: contextCost('markdown', 'observe'), // clients render; the budget prices the block `hippo context` would print
     });
-    recordTokens(ctx, 'http_context', { items: result.entries.length, tokens: result.tokens });
+    await recordTokens(ctx, 'http_context', { items: result.entries.length, tokens: result.tokens });
     sendJson(res, 200, result);
     return;
 }

package/dist/server.d.ts

@@ -11,9 +11,25 @@ export { HttpError } from './http-util.js';
 export { promptHookContext, type CallerProject } from './prompt-hook.js';
 export type { JsonValue } from './json.js';
 export { captureSessionTexts, type SessionCaptureRequest, type SessionCaptureResult } from './capture/session-texts.js';
-export { sqliteStore, type HippoStore } from './store-port.js';
+export { sqliteStore, type HippoStore, type RecallSearchArgs, type RecallWrites, type VectorReads } from './store-port.js';
 export type { ApiKeyRecord } from './auth.js';
+export type { AppendAuditOpts } from './audit.js';
+export type { ContinuityBlock } from './api/recall-types.js';
+export type { ActiveGoals, GetActiveGoalsOpts, Goal, GoalRecallLogRow, RetrievalPolicy } from './goals.js';
+export type { MemoryEntry } from './memory.js';
+export type { ClassResolution, PlanningFallacyEvidence } from './predictions/planning-fallacy.js';
+export type { PredictionBaserate } from './predictions/store.js';
+export type { RecallTraceInput } from './recall-trace.js';
+export type { StrengthenOptions } from './store/entry-writes.js';
+export type { OriginFilter, RecallScopeFilter, VectorCandidateSpec } from './store/search-rows.js';
+export type { ContinuityKey } from './store/sessions.js';
+export type { TokenUse } from './token-ledger.js';
+export type { EmbeddingIndexState } from './embeddings.js';
+export type { PhysicsParticle } from './physics.js';
 export { StoreBusyError } from './db.js';
+export { decodeVector, EMBEDDING_MODEL_META_KEY, rankVectorRows, type VectorMatch, type VectorRow } from './vector-store.js';
+export { bufferToFloat32 } from './physics-state.js';
+export { OTHER_STORE_MARKER, OtherStoreFolderError, withSqliteAllowed } from './db.js';
 export { authCreate, type AuthCreateOpts, type AuthCreateResult } from './api.js';
 export { isSharedStore } from './config.js';
 export { ownerOrSubject } from './api.js';

package/dist/server.js

@@ -2,8 +2,9 @@ import { envPort, envRequireAuth, envV1Rps } from './env.js';
 import { createServer } from 'node:http';
 import { existsSync } from 'node:fs';
 import { detectServer, removePidfileIfOwned, writePidfile } from './server-detect.js';
-import { closeHippoDb, getHippoDbPath, isStoreBusy, openHippoDb, SERVER_DB_WAIT_MS, withBusyWait, withSqliteBlocked } from './db.js';
+import { closeHippoDb, getHippoDbPath, isStoreBusy, openHippoDb, outsideRequestStores, runWithRequestStores, SERVER_DB_WAIT_MS, withSqliteBlocked } from './db.js';
 import { sqliteStore } from './store-port.js';
+import { markSharedStore } from './config.js';
 import { auditWriteFailureCount } from './audit.js';
 import { PACKAGE_VERSION } from './version.js';
 import { errorFields, log } from './log.js';
@@ -11,7 +12,7 @@ import { createRateLimiter } from './rate-limit.js';
 import { authCreateSelf, authRevoke, RecallContractError } from './api.js';
 import { handleSlackEventsWebhook } from './connectors/slack/webhook.js';
 import { handleGitHubEventsWebhook } from './connectors/github/webhook.js';
-import { BodyTimeoutError, BodyTooLargeError, closeAfterReply, HttpError, JSON_HEADERS, sendJson } from './http-util.js';
+import { BodyTimeoutError, BodyTooLargeError, closeAfterReply, HttpError, JSON_HEADERS, sendJson, STORE_NOT_PORTED_MESSAGE } from './http-util.js';
 import { ForbiddenError } from './api-errors.js';
 import { buildContextWithAuth, isLoopback, LIMITER_MAX_KEYS, requireAuth } from './server/auth.js';
 import { enforceRateLimit } from './server/client-ip.js';
@@ -47,6 +48,11 @@ export { captureSessionTexts } from './capture/session-texts.js';
 // An add-on serves from another database by passing serve() its own HippoStore.
 export { sqliteStore } from './store-port.js';
 export { StoreBusyError } from './db.js';
+// An add-on store decodes and ranks with hippo.db's own code, so both return the same ids in the same order.
+export { decodeVector, EMBEDDING_MODEL_META_KEY, rankVectorRows } from './vector-store.js';
+export { bufferToFloat32 } from './physics-state.js';
+// store copy --db writes the marker and reads the old hippo.db under the waiver.
+export { OTHER_STORE_MARKER, OtherStoreFolderError, withSqliteAllowed } from './db.js';
 // An add-on's install step mints the first admin key into a store folder it names, which `hippo auth create` cannot reach.
 export { authCreate } from './api.js';
 // An add-on that serves a team store checks the flag before it starts.
@@ -92,7 +98,7 @@ const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
 const V1_ROUTES = [
     { method: 'POST', path: '/v1/memories', handler: handleCreateMemory },
     { method: 'GET', path: '/v1/graph', handler: handleGetGraph },
-    { method: 'GET', path: '/v1/memories', handler: handleRecallMemories },
+    { method: 'GET', path: '/v1/memories', storeReady: true, handler: handleRecallMemories },
     { method: 'GET', pattern: '/v1/sessions/:id/assemble', handler: handleAssembleSession },
     { method: 'GET', pattern: '/v1/recall/drill/:id', handler: handleDrillRecall },
     { method: 'POST', pattern: '/v1/memories/:id/archive', handler: handleArchiveMemory },
@@ -238,10 +244,9 @@ function dispatchPublicJson({ res, opts }, method, path) {
     res.end(text);
     return true;
 }
-const NOT_ON_STORE_MESSAGE = 'not available on this store';
 function assertSqliteStore(opts) {
     if (opts.store.kind !== 'sqlite')
-        throw new HttpError(501, NOT_ON_STORE_MESSAGE);
+        throw new HttpError(501, STORE_NOT_PORTED_MESSAGE);
 }
 /** Under another store, a route not yet ported answers 501 without running; the caller is checked first, so a bad key is still a 401. */
 async function refuseUnportedRoute(req, opts) {
@@ -264,12 +269,25 @@ async function handleRequest(req, res, opts, startedAt, streamSlots, limiter) {
     }
     enforceRateLimit(req, path, limiter);
     const routeRequest = { req, res, opts, query };
-    if (await dispatchV1Route(routeRequest, method, path))
+    if (await runWithRequestStores(() => dispatchScopedRoute(routeRequest, method, path), { busyWaitMs: SERVER_DB_WAIT_MS }))
         return;
-    if (dispatchPublicJson(routeRequest, method, path))
-        return;
-    if (await dispatchAddonRoute(routeRequest, method, path))
+    // Outside the request scope: the heartbeat timer outlives the request. Store-ready: the stream only authenticates, through the port.
+    if (method === 'GET' && path === '/mcp/stream') {
+        await handleMcpStream(req, res, opts, streamSlots);
         return;
+    }
+    res.writeHead(404, JSON_HEADERS);
+    res.end(JSON.stringify({ error: 'not found' }));
+}
+/** Every route that runs inside a request scope, so it opens each store once: the /v1 table, public JSON, add-on routes, the webhooks and POST /mcp. */
+async function dispatchScopedRoute(r, method, path) {
+    if (await dispatchV1Route(r, method, path))
+        return true;
+    if (dispatchPublicJson(r, method, path))
+        return true;
+    if (await dispatchAddonRoute(r, method, path))
+        return true;
+    const { req, res, opts } = r;
     if (method === 'POST' && path === '/v1/connectors/slack/events') {
         // Bearer auth deliberately skipped: this route is in PUBLIC_ROUTES and authenticates via the Slack HMAC signature.
         if (!isPublicRoute(method, path)) {
@@ -278,7 +296,7 @@ async function handleRequest(req, res, opts, startedAt, streamSlots, limiter) {
         }
         assertSqliteStore(opts);
         await handleSlackEventsWebhook({ req, res, opts });
-        return;
+        return true;
     }
     if (method === 'POST' && path === '/v1/connectors/github/events') {
         if (!isPublicRoute(method, path)) {
@@ -286,20 +304,14 @@ async function handleRequest(req, res, opts, startedAt, streamSlots, limiter) {
         }
         assertSqliteStore(opts);
         await handleGitHubEventsWebhook({ req, res, opts });
-        return;
+        return true;
     }
+    // Store-ready: under another store the MCP layer lists and runs only the tools ported to the port.
     if (method === 'POST' && path === '/mcp') {
-        await refuseUnportedRoute(req, opts);
         await handleMcpPost(req, res, opts);
-        return;
-    }
-    // Store-ready: the stream and its heartbeat only authenticate, and auth goes through the port.
-    if (method === 'GET' && path === '/mcp/stream') {
-        await handleMcpStream(req, res, opts, streamSlots);
-        return;
+        return true;
     }
-    res.writeHead(404, JSON_HEADERS);
-    res.end(JSON.stringify({ error: 'not found' }));
+    return false;
 }
 function sendHealth(req, res, startedAt) {
     // Loopback callers (detectServer's stale-pidfile probe reads version and
@@ -387,7 +399,8 @@ function createStoreHolder(hippoRoot, store) {
         if (heldDb || stopHolding || !existsSync(getHippoDbPath(hippoRoot)))
             return;
         try {
-            heldDb = openHippoDb(hippoRoot);
+            // The 'finish' listener can fire inside a request scope, which would close this connection with the request.
+            heldDb = outsideRequestStores(() => openHippoDb(hippoRoot));
         }
         catch (err) {
             stopHolding = true;
@@ -522,6 +535,9 @@ export async function serve(opts) {
         ...opts, routes, publicJsonBodies, store: opts.store ?? sqliteStore(opts.hippoRoot), callerLimiter, failedAuthLimiter,
     };
     const { kind } = served.store;
+    // A store other than hippo.db is a team's central server, so its folder's config.json must not decide shared-ness.
+    if (kind !== 'sqlite')
+        markSharedStore(opts.hippoRoot);
     const holder = createStoreHolder(opts.hippoRoot, served.store);
     const inflight = new Set();
     const server = createServer((req, res) => {
@@ -531,7 +547,7 @@ export async function serve(opts) {
         const requestId = resolveRequestId(req.headers['x-request-id']);
         requestIds.set(req, requestId);
         res.setHeader('X-Request-Id', requestId);
-        const run = () => withBusyWait(SERVER_DB_WAIT_MS, () => handleRequest(req, res, served, startedAt, streamSlots, limiter));
+        const run = () => handleRequest(req, res, served, startedAt, streamSlots, limiter);
         // A missed port under another store would otherwise create and write a hippo.db that store never reads.
         (kind === 'sqlite' ? run() : withSqliteBlocked(kind, run)).catch((err) => replyOrClose(req, res, err, requestId));
     });

package/dist/store/entry-writes.d.ts

@@ -36,6 +36,8 @@ export interface StrengthenOptions {
 /** Strengthen what a read returned: update only the four retrieval columns on the live row, never a stale copy.
  *  Best effort: a failure logs and never fails the read. Returns the ids found in this store. */
 export declare function strengthenRetrieved(hippoRoot: string, ids: readonly string[], opts: StrengthenOptions): Set<string>;
+/** strengthenRetrieved on an open handle that holds no transaction, so a recall's last writes share one handle. */
+export declare function strengthenRetrievedInOwnTx(db: DatabaseSyncLike, ids: readonly string[], opts: StrengthenOptions): Set<string>;
 /** strengthenRetrieved on the caller's handle, inside the caller's transaction. Throws; the caller decides. */
 export declare function strengthenRetrievedOn(db: DatabaseSyncLike, ids: readonly string[], opts: StrengthenOptions): Set<string>;
 /** Rewrites a live row's tags and its full-text row on the caller's transaction, with no audit row. */

package/dist/store/entry-writes.js

@@ -1,5 +1,5 @@
 import { markRetrieved } from '../memory.js';
-import { closeHippoDb, openHippoDb, withWriteScope } from '../db.js';
+import { closeHippoDb, openHippoDb, rethrowIfSqliteBlocked, withWriteScope } from '../db.js';
 import { RejectedValueError } from '../rejection.js';
 import { markSummaryDirtyInTx } from '../summary-dirty.js';
 import { log } from '../log.js';
@@ -73,30 +73,38 @@ export function writeEntryMirrors(hippoRoot, entry) {
 /** Strengthen what a read returned: update only the four retrieval columns on the live row, never a stale copy.
  *  Best effort: a failure logs and never fails the read. Returns the ids found in this store. */
 export function strengthenRetrieved(hippoRoot, ids, opts) {
-    const found = new Set();
     if (ids.length === 0 || opts.recallBoostAblated)
-        return found;
+        return new Set();
     let db;
     try {
         db = openHippoDb(hippoRoot);
-        db.exec('BEGIN IMMEDIATE');
-        for (const id of strengthenRetrievedOn(db, ids, opts))
-            found.add(id);
-        db.exec('COMMIT');
     }
     catch (error) {
-        try {
-            db?.exec('ROLLBACK');
-        }
-        catch { /* already rolled back; keep the original error */ }
-        log.warn(`retrieval stats not saved (${error instanceof Error ? error.message : String(error)})`);
-        found.clear();
+        rethrowIfSqliteBlocked(error);
+        warnStrengthenFailed(error);
+        return new Set();
+    }
+    try {
+        return strengthenRetrievedInOwnTx(db, ids, opts);
     }
     finally {
-        if (db)
-            closeHippoDb(db);
+        closeHippoDb(db);
     }
-    return found;
+}
+/** strengthenRetrieved on an open handle that holds no transaction, so a recall's last writes share one handle. */
+export function strengthenRetrievedInOwnTx(db, ids, opts) {
+    if (ids.length === 0 || opts.recallBoostAblated)
+        return new Set();
+    try {
+        return withWriteScope(db, 'strengthen_retrieved', () => strengthenRetrievedOn(db, ids, opts));
+    }
+    catch (error) {
+        warnStrengthenFailed(error);
+        return new Set();
+    }
+}
+function warnStrengthenFailed(error) {
+    log.warn(`retrieval stats not saved (${error instanceof Error ? error.message : String(error)})`);
 }
 /** strengthenRetrieved on the caller's handle, inside the caller's transaction. Throws; the caller decides. */
 export function strengthenRetrievedOn(db, ids, opts) {

package/dist/store/open.js

@@ -25,9 +25,10 @@ export function initStore(hippoRoot) {
 }
 /** One open connection with init done on it, for callers who used to pay for `initStore` + a second `openHippoDb`. */
 export function openStore(hippoRoot, opts) {
-    ensureMirrorDirectories(hippoRoot);
+    // Open first: a folder marked for another store must refuse before any mirror folder appears.
     const db = openHippoDb(hippoRoot, opts);
     try {
+        ensureMirrorDirectories(hippoRoot);
         const bootstrapped = bootstrapLegacyStore(db, hippoRoot);
         if (bootstrapped) {
             syncMirrorFiles(hippoRoot, db);

package/dist/store-port.d.ts

@@ -1,13 +1,99 @@
 import { type ApiKeyRecord } from './auth.js';
+import { type AppendAuditOpts } from './audit.js';
+import type { ContinuityBlock } from './api/recall-types.js';
+import { type EmbeddingIndexState } from './embeddings.js';
+import { type ActiveGoals, type GetActiveGoalsOpts, type GoalRecallLogRow } from './goals.js';
+import type { MemoryEntry } from './memory.js';
+import type { PhysicsParticle } from './physics.js';
+import { type PlanningFallacyEvidence } from './predictions/planning-fallacy.js';
+import { type RecallTraceInput } from './recall-trace.js';
+import { type StrengthenOptions } from './store/entry-writes.js';
+import { type OriginFilter, type VectorCandidateSpec } from './store/search-rows.js';
+import { type ContinuityKey } from './store/sessions.js';
+import { type TokenUse } from './token-ledger.js';
+/** The arguments of `loadRecallSearchEntries` after the query, by name. */
+export interface RecallSearchArgs {
+    readonly limit: number;
+    readonly tenantId?: string;
+    readonly requestedScope?: string;
+    readonly explicitScopeMode: 'exact' | 'additive';
+    readonly includeSuperseded: boolean;
+    readonly originProjects?: OriginFilter;
+    /** The caller's personal scope, which the default deny admits; undefined admits no personal row. */
+    readonly ownScope: string | undefined;
+}
+/** Everything one recall writes once its reply is decided, so a store writes it on one connection. */
+export interface RecallWrites {
+    /** Insert or ignore on (memory_id, goal_id), so the first row wins, a duplicate inside this batch included. First drop a row
+     *  whose memory_id is in no memories row of this store, whatever that row's tenant, as `localGoalRecallRows` does. */
+    readonly goalLog: readonly GoalRecallLogRow[];
+    /** In the order they happened. */
+    readonly audit: readonly AppendAuditOpts[];
+    readonly trace?: RecallTraceInput;
+    /** Nothing when `recallBoostAblated`. Each id found, in `tenantId` when set, gets the retrieval_count, last_retrieved,
+     *  half_life_days and strength `markRetrieved` computes from the row read before any update, so a repeated id moves once. */
+    readonly strengthen?: {
+        readonly ids: readonly string[];
+        readonly opts: StrengthenOptions;
+    };
+}
+/** The reads behind recall's vector arm, one group a store sets in full as `HippoStore.vectors` or leaves unset. */
+export interface VectorReads {
+    /** The stored model and whether any vector exists, in one snapshot. */
+    embeddingIndexState(): Promise<EmbeddingIndexState>;
+    storedVectors(ids: readonly string[]): Promise<Map<string, number[]>>;
+    /** The `spec.limit ?? 50` rows nearest `queryVector` by `rankVectorRows` among those where the tenant matches (when set), kind is not 'archived', a superseded row
+     *  shows only with `includeSuperseded`, scope follows `RecallScopeFilter`, and origin is '' or listed (when `spec.origin` is set). */
+    nearestEntries(queryVector: readonly number[], spec: VectorCandidateSpec): Promise<MemoryEntry[]>;
+    /** The particles of `ids` only; an empty list reads nothing. */
+    physicsParticles(ids: readonly string[]): Promise<Map<string, PhysicsParticle>>;
+}
 /** What `serve()` reads and writes through. Each method is atomic and no transaction spans an await, since SQLite's lock wait blocks the event loop; a lock timeout throws `StoreBusyError`. */
 export interface HippoStore {
     /** 'sqlite' is hippo.db under the served root. Under any other kind, an unported route answers 501 and a hippo.db open inside a request throws. */
     readonly kind: string;
     /** The api_keys row for `keyId` with its scope grants, revoked or not; null when no row matches. */
     findApiKey(keyId: string): Promise<ApiKeyRecord | null>;
+    /** Recall candidates in `loadRecallSearchEntries` order: FTS, then LIKE, then every row in scope. */
+    searchRecallEntries(query: string, args: RecallSearchArgs): Promise<MemoryEntry[]>;
+    /** The rows among the first 500 ids, a tenant narrowing them, ordered by created, then content, then id, all ascending,
+     *  as `loadEntriesByIds` does; the input order is ignored. */
+    entriesByIds(ids: readonly string[], tenantId?: string): Promise<MemoryEntry[]>;
+    /** The session's active goals and their policies, read together so a goal and its policy never disagree. */
+    activeGoals(opts: GetActiveGoalsOpts): Promise<ActiveGoals>;
+    /** The first `count` (at most 200) unsuperseded raw rows a tenant, a non-empty session id and non-null `origins` (those projects and
+     *  user-global rows) must narrow, by created descending, then content and id ascending, as `loadFreshRawMemories` does. */
+    freshRawEntries(count: number, tenantId: string | undefined, sessionId: string | undefined, origins: readonly string[] | null): Promise<MemoryEntry[]>;
+    /** The newest active snapshot a non-null `key` must narrow to one owner and project (null only on an unshared hippo.db), then for its session
+     *  the newest handoff (same key) and `eventLimit` newest events returned oldest first, each tie broken by the larger id; the caller applies scope. */
+    continuity(tenantId: string, eventLimit: number, key: ContinuityKey | null): Promise<ContinuityBlock>;
+    /** Resolves a forward claim's tokens to one class and reads its baserate, writing no audit row. */
+    planningFallacyEvidence(tenantId: string, classQueryTokens: readonly string[]): Promise<PlanningFallacyEvidence>;
+    /** Appends the rows in order, all or none. */
+    appendAuditEvents(events: readonly AppendAuditOpts[]): Promise<void>;
+    /** Writes the goal log and audit rows in one transaction and rejects with none written if it fails. Then the trace and
+     *  the strengthen, each on its own: a failure there logs and still resolves, since the reply is already decided. */
+    finishRecall(writes: RecallWrites): Promise<void>;
+    /** Adds `recalled` to the one store-wide total_recalled counter, no tenant; the SQLite store also rewrites stats.json. */
+    bumpRecallStats(recalled: number): Promise<void>;
+    /** One token-ledger row. Throws, so the caller decides whether a ledger failure matters. */
+    recordTokens(use: TokenUse): Promise<void>;
+    /** Unset on a store built before them, where hybrid and physics recall under an embedding provider answer 501. */
+    readonly vectors?: VectorReads;
     /** Releases the store's connections; `serve()` closes only a store it made itself. */
     close(): Promise<void>;
 }
-/** The built-in store: today's synchronous hippo.db functions behind the port, one handle per call, so close has nothing to release. */
-export declare function sqliteStore(hippoRoot: string): HippoStore;
+/** The store a request runs on: the served one, else hippo.db under its root, as the CLI and SDK callers have it. */
+export declare function storeFor(ctx: {
+    readonly hippoRoot: string;
+    readonly store?: HippoStore;
+}): HippoStore;
+/** The built-in store: today's synchronous hippo.db functions behind the port, each call on its own short-lived handles, so close has nothing to release. */
+export declare function sqliteStore(hippoRoot: string): HippoStore & {
+    readonly vectors: VectorReads;
+};
+/** sqliteStore's continuity read, for the synchronous recall that cannot await the port. */
+export declare function continuityAt(hippoRoot: string, tenantId: string, eventLimit: number, key: ContinuityKey | null): ContinuityBlock;
+/** sqliteStore's finishRecall, for the synchronous recall that cannot await the port. */
+export declare function finishRecallAt(hippoRoot: string, writes: RecallWrites): void;
 //# sourceMappingURL=store-port.d.ts.map