hippo-memory 1.65.0 → 1.67.0

package/dist/search/physics-search.js

@@ -1,20 +1,20 @@
 import { calculateStrength } from '../memory.js';
 import { estimateTokens } from '../token-ledger.js';
 import { evalNow, isRecallBoostAblated } from '../ablation.js';
-import { embeddingModelRequiresReindex } from '../embeddings.js';
+import { indexedModel, indexNeedsRebuild } from '../embeddings.js';
 import { resolveEmbeddingProvider } from '../embedding-provider.js';
 import { physicsScore as computePhysicsScores, computeMass } from '../physics.js';
 import { DEFAULT_PHYSICS_CONFIG } from '../physics-config.js';
-import { loadPhysicsState } from '../physics-state.js';
-import { openHippoDb, closeHippoDb, rethrowIfSqliteBlocked } from '../db.js';
+import { rethrowIfSqliteBlocked } from '../db.js';
 import { compareScoredResults } from '../compare.js';
 import { log } from '../log.js';
+import { sqliteStore } from '../store-port.js';
 import { churnStaleFactor, summaryMultipliers, summaryScoring } from './boosts.js';
 import { addDagFields, ageInDays } from './breakdown.js';
 import { fitBudget } from './finalize.js';
 import { hybridSearch } from './hybrid.js';
 import { currentEntries } from './as-of.js';
-import { vectorCandidatesOutside } from './vector.js';
+import { requireVectorReads, vectorCandidatesOutside } from './vector.js';
 import { DEFAULT_RECALL_BUDGET } from './types.js';
 /** Scores memories by gravity, momentum and cluster amplification; rows without physics state rank through hybridSearch. */
 export async function physicsSearch(query, entries, options = {}) {
@@ -27,11 +27,14 @@ export async function physicsSearch(query, entries, options = {}) {
     if (options.asOf)
         return hybridSearch(query, entries, options);
     const root = options.hippoRoot;
-    const queryVector = await physicsQueryVector(query, root, options.queryEmbedding);
+    const store = options.store ?? sqliteStore(root);
+    const queryVector = await physicsQueryVector(query, root, store, options.queryEmbedding);
     if (!queryVector)
         return hybridSearch(query, entries, options);
-    const pool = currentEntries(withVectorCandidates(root, entries, queryVector, options.vectorCandidates), options);
-    const physicsMap = loadCandidateParticles(root, pool);
+    // Checked here too, since a caller's own query vector skips the check inside physicsQueryVector.
+    const reads = requireVectorReads(store);
+    const pool = currentEntries(await withVectorCandidates(reads, entries, queryVector, options.vectorCandidates), options);
+    const physicsMap = await loadCandidateParticles(reads, pool);
     if (!physicsMap)
         return hybridSearch(query, pool, options);
     const pools = splitByParticle(pool, physicsMap, queryVector, now);
@@ -45,13 +48,15 @@ export async function physicsSearch(query, entries, options = {}) {
     return fitBudget(merged, options.budget ?? DEFAULT_RECALL_BUDGET, options.minResults ?? 1, options.cost);
 }
 /** The caller's vector, else the provider's; null sends the caller to hybridSearch. */
-async function physicsQueryVector(query, root, given) {
+async function physicsQueryVector(query, root, store, given) {
     if (given && given.length > 0)
         return given;
     // Physics scores against particle positions, not the stored vector index, so a pruned index must not block it.
     try {
         const provider = resolveEmbeddingProvider(root);
-        if (!provider.isAvailable() || embeddingModelRequiresReindex(root, provider.id))
+        if (!provider.isAvailable())
+            return null;
+        if (indexNeedsRebuild(indexedModel(await requireVectorReads(store).embeddingIndexState()), provider.id))
             return null;
         const [vec] = await provider.embed([query], 'query');
         return vec && vec.length > 0 ? vec : null;
@@ -62,11 +67,11 @@ async function physicsQueryVector(query, root, given) {
         return null;
     }
 }
-function withVectorCandidates(root, entries, queryVector, spec) {
+async function withVectorCandidates(reads, entries, queryVector, spec) {
     if (!spec)
         return entries;
     try {
-        return [...entries, ...vectorCandidatesOutside(root, entries, queryVector, spec)];
+        return [...entries, ...await vectorCandidatesOutside(reads, entries, queryVector, spec)];
     }
     catch (err) {
         rethrowIfSqliteBlocked(err);
@@ -75,15 +80,9 @@ function withVectorCandidates(root, entries, queryVector, spec) {
     }
 }
 /** Particles for the candidate rows only, so one tenant's search never reads every tenant's physics state. */
-function loadCandidateParticles(root, pool) {
+async function loadCandidateParticles(reads, pool) {
     try {
-        const db = openHippoDb(root);
-        try {
-            return loadPhysicsState(db, pool.map((e) => e.id));
-        }
-        finally {
-            closeHippoDb(db);
-        }
+        return await reads.physicsParticles(pool.map((e) => e.id));
     }
     catch (err) {
         rethrowIfSqliteBlocked(err);

package/dist/search/vector.d.ts

@@ -1,5 +1,6 @@
 import type { MemoryEntry } from '../memory.js';
-import { type VectorCandidateSpec } from '../store/search-rows.js';
+import type { VectorCandidateSpec } from '../store/search-rows.js';
+import { type HippoStore, type VectorReads } from '../store-port.js';
 import { type CurrentnessOptions } from './as-of.js';
 /** hybridSearch's vector arm: which rows it may add, plus the caller's JS admission rules (exact private regex, entry filters). */
 export type HybridVectorCandidates = VectorCandidateSpec & {
@@ -16,9 +17,13 @@ export interface VectorArm {
 export interface VectorArmOptions extends CurrentnessOptions {
     hippoRoot?: string;
     vectorCandidates?: HybridVectorCandidates;
+    /** Where vectors are read; hippo.db under `hippoRoot` when unset. */
+    store?: HippoStore;
 }
+/** The store's vector reads; a store without them answers 501, as any unported path does. */
+export declare function requireVectorReads(store: HippoStore): VectorReads;
 /** The nearest admitted rows not already in `entries`. */
-export declare function vectorCandidatesOutside(hippoRoot: string, entries: readonly MemoryEntry[], queryVector: readonly number[], spec: HybridVectorCandidates): MemoryEntry[];
+export declare function vectorCandidatesOutside(reads: VectorReads, entries: readonly MemoryEntry[], queryVector: readonly number[], spec: HybridVectorCandidates): Promise<MemoryEntry[]>;
 /** Embeds the query and loads stored vectors; any failure leaves BM25 to rank alone. */
 export declare function resolveVectorArm(query: string, entries: MemoryEntry[], options: VectorArmOptions): Promise<VectorArm>;
 export interface DenseScores {

package/dist/search/vector.js

@@ -1,18 +1,29 @@
-import { cosineSimilarity, embeddingModelRequiresReindex, hasEmbeddings, loadStoredVectors } from '../embeddings.js';
-import { loadVectorCandidateEntries } from '../store/search-rows.js';
+import { cosineSimilarity, indexedModel, indexNeedsRebuild } from '../embeddings.js';
 import { resolveEmbeddingProvider } from '../embedding-provider.js';
 import { rethrowIfSqliteBlocked } from '../db.js';
 import { log } from '../log.js';
+import { requireGroup, sqliteStore } from '../store-port.js';
 import { redactSecretsStrict } from '../secret-detect.js';
 import { currentEntries } from './as-of.js';
 // Search runs on every hook prompt, so one line per reason per process says why vectors went unused without flooding stderr.
 function warnBm25Fallback(reason, detail) {
     log.once(`search.bm25-fallback.${reason}`, 'warn', `hybrid search fell back to BM25 only: ${redactSecretsStrict(detail)}`);
 }
+function reindexHint(storeKind) {
+    const why = 'the embedding index was built by another model or is being rebuilt';
+    // `hippo embed` writes only hippo.db, so another store gets its vectors by a rebuild from it.
+    return storeKind === 'sqlite'
+        ? `${why}; run 'hippo embed'`
+        : `${why}; run 'hippo embed' on the SQLite store, then rebuild the '${storeKind}' database from it`;
+}
+/** The store's vector reads; a store without them answers 501, as any unported path does. */
+export function requireVectorReads(store) {
+    return requireGroup(store, 'vectors');
+}
 /** The nearest admitted rows not already in `entries`. */
-export function vectorCandidatesOutside(hippoRoot, entries, queryVector, spec) {
+export async function vectorCandidatesOutside(reads, entries, queryVector, spec) {
     const inPool = new Set(entries.map((e) => e.id));
-    return loadVectorCandidateEntries(hippoRoot, queryVector, spec).filter((e) => !inPool.has(e.id) && (spec.admit?.(e) ?? true));
+    return (await reads.nearestEntries(queryVector, spec)).filter((e) => !inPool.has(e.id) && (spec.admit?.(e) ?? true));
 }
 /** Embeds the query and loads stored vectors; any failure leaves BM25 to rank alone. */
 export async function resolveVectorArm(query, entries, options) {
@@ -32,14 +43,17 @@ async function fillVectorArm(arm, query, root, options) {
     const provider = resolveEmbeddingProvider(root);
     if (!provider.isAvailable())
         return;
-    if (embeddingModelRequiresReindex(root, provider.id)) {
-        warnBm25Fallback('reindex', "the embedding index was built by another model or is being rebuilt; run 'hippo embed'");
+    const store = options.store ?? sqliteStore(root);
+    const reads = requireVectorReads(store);
+    const index = await reads.embeddingIndexState();
+    if (indexNeedsRebuild(indexedModel(index), provider.id)) {
+        warnBm25Fallback('reindex', reindexHint(store.kind));
         return;
     }
     const spec = options.vectorCandidates;
-    const vectors = loadStoredVectors(root, arm.entries.map((e) => e.id));
+    const vectors = await reads.storedVectors(arm.entries.map((e) => e.id));
     // Only spend a (possibly paid, off-box) query embedding when there is a stored vector this search can use.
-    if (vectors.size === 0 && !(spec !== undefined && hasEmbeddings(root)))
+    if (vectors.size === 0 && !(spec !== undefined && index.hasVectors))
         return;
     const [vec] = await provider.embed([query], 'query');
     arm.queryVector = vec ?? [];
@@ -47,11 +61,11 @@ async function fillVectorArm(arm, query, root, options) {
         warnBm25Fallback('empty-query-vector', 'the embedding provider returned no vector for the query');
         return;
     }
-    const added = spec ? vectorCandidatesOutside(root, arm.entries, arm.queryVector, spec) : [];
+    const added = spec ? await vectorCandidatesOutside(reads, arm.entries, arm.queryVector, spec) : [];
     if (added.length > 0) {
         arm.addedRows = true;
         arm.entries = currentEntries([...arm.entries, ...added], options);
-        for (const [id, v] of loadStoredVectors(root, added.map((e) => e.id)))
+        for (const [id, v] of await reads.storedVectors(added.map((e) => e.id)))
             vectors.set(id, v);
     }
     arm.embeddingIndex = Object.fromEntries(vectors);

package/dist/server/routes/admin.js

@@ -79,7 +79,7 @@ export async function handleListAuthKeys({ req, res, opts, query }) {
 export async function handleRevokeAuthKey({ req, res, opts }, keyMatch) {
     validateIdSegment(keyMatch.keyId, 'key id');
     const ctx = await buildContextWithAuth(req, opts);
-    const result = authRevoke(ctx, keyMatch.keyId);
+    const result = await authRevoke(ctx, keyMatch.keyId);
     sendJson(res, 200, result);
     return;
 }

package/dist/server/routes/recall.js

@@ -16,21 +16,18 @@ export function __resetSessionRecallHistoryHttp() {
     resetSessionRings('http');
 }
 // HTTP threads the ring through opts.recallHistory, so the hint retrieve() returns is the one the caller sees.
-async function recallHistoryFor(ctx, q, sessionId) {
-    if (!biasHintEnabled('anchoring'))
-        return undefined;
-    if (sessionId)
-        return peekSessionRing('http', ctx.tenantId, sessionId);
-    await storeFor(ctx).appendAuditEvents(anchorSkippedRows({ tenantId: ctx.tenantId, actor: ctx.actor.subject }, q));
-    return undefined;
+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 { opts: recallOpts, limit, mode, explain } = parseRecallRequest(httpParams(query));
     const { query: q, includeContinuity, sessionId } = recallOpts;
     const ctx = await buildContextWithAuth(req, opts);
-    const recallHistory = await recallHistoryFor(ctx, q, sessionId);
-    const result = await retrieve(ctx, { ...recallOpts, limit, mode, explain, recallHistory });
+    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)

package/dist/server/types.d.ts

@@ -2,7 +2,7 @@ import type { IncomingMessage, ServerResponse } from 'node:http';
 import type { Context } from '../api.js';
 import type { JsonValue } from '../json.js';
 import type { RateLimiter } from '../rate-limit.js';
-import type { HippoStore } from '../store-port.js';
+import type { HippoStore, StoreGroup } from '../store-port.js';
 export interface ServerHandle {
     port: number;
     url: string;
@@ -28,10 +28,11 @@ export interface AddonCall {
     readonly ctx: Context;
     readonly body: Readonly<Record<string, JsonValue>>;
 }
-/** A POST /v1 route an add-on mounts through serve(): core authenticates and parses first, then sends the returned value as 200 JSON. */
+/** A POST /v1 route an add-on mounts through serve(): core authenticates and parses first, then sends the returned value as 200 JSON. Under another store it runs only when that store has its `storeReady` group. */
 export interface AddonRoute {
     readonly path: string;
     readonly handler: (call: AddonCall) => Promise<JsonValue>;
+    readonly storeReady?: StoreGroup;
 }
 export interface RateLimitSpec {
     ratePerSec: number;
@@ -76,10 +77,10 @@ export interface RouteRequest {
     opts: ResolvedServeOpts;
     query: URLSearchParams;
 }
-/** One /v1 route: an exact path, a matchPath pattern, or a regex, each paired with the handler for one method. `storeReady` routes run under any store. */
+/** One /v1 route: an exact path, a matchPath pattern, or a regex, each paired with the handler for one method. Under another store it runs only when that store has its `storeReady` group. */
 export type Route = {
     method: string;
-    storeReady?: true;
+    storeReady?: StoreGroup;
 } & ({
     path: string;
     handler: (r: RouteRequest) => Promise<void>;

package/dist/server.d.ts

@@ -1,7 +1,7 @@
-import { type Actor, authCreateSelf, type AuthCreateSelfOpts, type AuthCreateSelfResult, authRevoke, type Context } from './api.js';
-import { ForbiddenError } from './api-errors.js';
+import { type Actor, authCreateSelf, type AuthCreateSelfOpts, type AuthCreateSelfResult, authRevoke, type AuthRevokeReply, type AuthRevokeResult, type Context } from './api.js';
+import { ForbiddenError, NotFoundError } from './api-errors.js';
 import type { ServeOpts, ServerHandle } from './server/types.js';
-export { authCreateSelf, authRevoke, ForbiddenError, type AuthCreateSelfOpts, type AuthCreateSelfResult, type Context, type Actor };
+export { authCreateSelf, authRevoke, ForbiddenError, NotFoundError, type AuthCreateSelfOpts, type AuthCreateSelfResult, type AuthRevokeReply, type AuthRevokeResult, type Context, type Actor, };
 export { isCrossSite, LOOPBACK_HOST_HEADER } from './http-util.js';
 export { __resetSessionRecallHistoryHttp } from './server/routes/recall.js';
 export { clientIpForRateLimit } from './server/client-ip.js';
@@ -11,9 +11,9 @@ 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, type RecallSearchArgs, type RecallWrites } from './store-port.js';
+export { hasGroup, sqliteStore, type HippoStore, type KeyAudit, type KeyRevoke, type RecallSearchArgs, type RecallWrites, type StoreGroup, type StoreGroups, type VectorReads, } from './store-port.js';
 export type { ApiKeyRecord } from './auth.js';
-export type { AppendAuditOpts } from './audit.js';
+export type { AppendAuditOpts, AuditEvent, ListAuditAfterOpts } 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';
@@ -21,10 +21,15 @@ export type { ClassResolution, PlanningFallacyEvidence } from './predictions/pla
 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 } from './store/search-rows.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

@@ -3,17 +3,17 @@ import { createServer } from 'node:http';
 import { existsSync } from 'node:fs';
 import { detectServer, removePidfileIfOwned, writePidfile } from './server-detect.js';
 import { closeHippoDb, getHippoDbPath, isStoreBusy, openHippoDb, outsideRequestStores, runWithRequestStores, SERVER_DB_WAIT_MS, withSqliteBlocked } from './db.js';
-import { sqliteStore } from './store-port.js';
+import { hasGroup, 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';
 import { createRateLimiter } from './rate-limit.js';
-import { authCreateSelf, authRevoke, RecallContractError } from './api.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, STORE_NOT_PORTED_MESSAGE } from './http-util.js';
-import { ForbiddenError } from './api-errors.js';
+import { ForbiddenError, NotFoundError } from './api-errors.js';
 import { buildContextWithAuth, isLoopback, LIMITER_MAX_KEYS, requireAuth } from './server/auth.js';
 import { enforceRateLimit } from './server/client-ip.js';
 import { drainAndClose } from './server/lifecycle.js';
@@ -33,7 +33,7 @@ import { handleAssembleSession, handleDrillRecall, handleGetContext, handleRecal
 import { handleCloseSkill, handleCreateSkill, handleExportSkills, handleGetSkill, handleListSkills, handleSupersedeSkill } from './server/routes/skills.js';
 import { parseJsonBody } from './server/validation.js';
 // Add-on packages mint and revoke keys through these without importing the whole api surface.
-export { authCreateSelf, authRevoke, ForbiddenError };
+export { authCreateSelf, authRevoke, ForbiddenError, NotFoundError, };
 // Published on the hippo-memory/server subpath before they moved to http-util.ts, so they stay exported here.
 export { isCrossSite, LOOPBACK_HOST_HEADER } from './http-util.js';
 // The code behind these lives in src/server/; this subpath keeps exporting them.
@@ -46,8 +46,13 @@ export { promptHookContext } from './prompt-hook.js';
 // A session-end route stores the turns its caller read from a transcript on the caller's own machine.
 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 { hasGroup, 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.
@@ -93,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', storeReady: true, handler: handleRecallMemories },
+    { method: 'GET', path: '/v1/memories', storeReady: 'base', 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 },
@@ -105,7 +110,7 @@ const V1_ROUTES = [
     { method: 'POST', path: '/v1/sleep', handler: handleSleep },
     { method: 'POST', path: '/v1/auth/keys', handler: handleCreateAuthKey },
     { method: 'GET', path: '/v1/auth/keys', handler: handleListAuthKeys },
-    { method: 'DELETE', pattern: '/v1/auth/keys/:keyId', handler: handleRevokeAuthKey },
+    { method: 'DELETE', pattern: '/v1/auth/keys/:keyId', storeReady: 'keyAudit', handler: handleRevokeAuthKey },
     { method: 'GET', path: '/v1/quarantine', handler: handleListQuarantine },
     { method: 'POST', pattern: '/v1/quarantine/:id/approve', handler: handleApproveQuarantine },
     { method: 'POST', pattern: '/v1/quarantine/:id/reject', handler: handleRejectQuarantine },
@@ -172,8 +177,7 @@ async function dispatchV1Route(r, method, path) {
         const run = routeMatches(route, method, path);
         if (run === null)
             continue;
-        if (!route.storeReady)
-            await refuseUnportedRoute(r.req, r.opts);
+        await refuseUnportedRoute(r.req, r.opts, route.storeReady);
         await run(r);
         return true;
     }
@@ -224,7 +228,7 @@ async function dispatchAddonRoute({ req, res, opts }, method, path) {
     const route = method === 'POST' ? opts.routes?.find((r) => r.path === path) : undefined;
     if (!route)
         return false;
-    await refuseUnportedRoute(req, opts);
+    await refuseUnportedRoute(req, opts, route.storeReady);
     const ctx = await buildContextWithAuth(req, opts);
     const body = await parseJsonBody(req, ctx);
     sendJson(res, 200, await route.handler({ ctx, body }));
@@ -243,9 +247,9 @@ function assertSqliteStore(opts) {
     if (opts.store.kind !== 'sqlite')
         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) {
-    if (opts.store.kind === 'sqlite')
+/** Under another store, a route that names no group, or one the store lacks, answers 501 without running; the caller is checked first, so a bad key is still a 401. */
+async function refuseUnportedRoute(req, opts, group) {
+    if (opts.store.kind === 'sqlite' || (group !== undefined && hasGroup(opts.store, group)))
         return;
     await requireAuth(req, opts);
     assertSqliteStore(opts);
@@ -514,7 +518,7 @@ export async function serve(opts) {
     const host = opts.host ?? '127.0.0.1';
     const requestedPort = opts.port ?? Number(envPort() ?? 6789);
     // A frozen copy, so a route the caller adds or renames after boot never skips the check below.
-    const routes = Object.freeze((opts.routes ?? []).map(({ path, handler }) => Object.freeze({ path, handler })));
+    const routes = Object.freeze((opts.routes ?? []).map(({ path, handler, storeReady }) => Object.freeze(storeReady === undefined ? { path, handler } : { path, handler, storeReady })));
     assertAddonRoutes(routes);
     const publicJsonBodies = assertPublicJson(opts.publicJson ?? {});
     const { perAddress: limiter, callerLimiter, failedAuthLimiter } = bootLimiters(opts.rateLimits);

package/dist/stdin.d.ts

@@ -9,4 +9,9 @@ export interface BoundedStdin {
  * idle (default 1000ms, or `HIPPO_STDIN_WAIT_MS`), refreshed on each chunk
  * so a slow but real write is not cut off, and capped at `waitMs * 10`. */
 export declare function readStdinBounded(waitMs?: number): Promise<BoundedStdin>;
+/** A hook payload with Copilot's camelCase fields copied to the snake_case keys hippo reads. The camelCase keys stay,
+ * so the sessionStart reply can follow the sender's casing; text that needs no change comes back exactly as sent. */
+export declare function normaliseHookPayload(text: string | undefined): string | undefined;
+/** The stdin read every hook verb uses: {@link readStdinBounded}, with the payload passed through {@link normaliseHookPayload}. */
+export declare function readHookStdin(waitMs?: number): Promise<BoundedStdin>;
 //# sourceMappingURL=stdin.d.ts.map

package/dist/stdin.js

@@ -1,4 +1,6 @@
 import { envStdinWaitMs } from './env.js';
+import { isJsonObject } from './hooks/shared.js';
+import { isJsonString } from './json.js';
 function defaultWaitMs() {
     return envStdinWaitMs() ?? 1000;
 }
@@ -39,4 +41,64 @@ export function readStdinBounded(waitMs = defaultWaitMs()) {
         stdin.once('error', done);
     });
 }
+// The Copilot harness's camelCase hook fields and the snake_case keys every hippo payload reader looks up.
+const CAMEL_TO_SNAKE = [
+    ['sessionId', 'session_id'],
+    ['transcriptPath', 'transcript_path'],
+    ['toolName', 'tool_name'],
+    ['hookEventName', 'hook_event_name'],
+    ['customInstructions', 'custom_instructions'],
+];
+/** Copilot sends `toolArgs` as the model's raw JSON string; Claude Code and VS Code send `tool_input` already parsed. */
+function parsedToolArgs(value) {
+    if (!isJsonString(value))
+        return value;
+    try {
+        // SAFETY: JSON.parse returns a JSON value by definition.
+        return JSON.parse(value);
+    }
+    catch {
+        // Arguments that are not JSON stay the string the model wrote.
+        return value;
+    }
+}
+/** The snake_case keys a payload lacks, filled from its camelCase twins; a snake_case key already present wins. */
+function snakeCaseFields(payload) {
+    const added = {};
+    for (const [camel, snake] of CAMEL_TO_SNAKE) {
+        if (camel in payload && !(snake in payload))
+            added[snake] = payload[camel];
+    }
+    if ('toolArgs' in payload && !('tool_input' in payload))
+        added.tool_input = parsedToolArgs(payload.toolArgs);
+    const error = payload.error;
+    // An error object gives its message, so readers that expect the documented string still get one.
+    if (isJsonObject(error) && isJsonString(error.message))
+        added.error = error.message;
+    return added;
+}
+/** A hook payload with Copilot's camelCase fields copied to the snake_case keys hippo reads. The camelCase keys stay,
+ * so the sessionStart reply can follow the sender's casing; text that needs no change comes back exactly as sent. */
+export function normaliseHookPayload(text) {
+    if (text === undefined || text.trim() === '')
+        return text;
+    let payload;
+    try {
+        // SAFETY: JSON.parse returns a JSON value by definition.
+        payload = JSON.parse(text.trim());
+    }
+    catch {
+        // Not JSON: each reader already treats that as a malformed payload, so it passes through untouched.
+        return text;
+    }
+    if (!isJsonObject(payload))
+        return text;
+    const added = snakeCaseFields(payload);
+    return Object.keys(added).length === 0 ? text : JSON.stringify({ ...payload, ...added });
+}
+/** The stdin read every hook verb uses: {@link readStdinBounded}, with the payload passed through {@link normaliseHookPayload}. */
+export async function readHookStdin(waitMs) {
+    const read = await readStdinBounded(waitMs);
+    return { text: normaliseHookPayload(read.text), timedOut: read.timedOut };
+}
 //# sourceMappingURL=stdin.js.map

package/dist/store/key-audit.d.ts

@@ -0,0 +1,6 @@
+import { type DatabaseSyncLike } from '../db.js';
+import type { KeyRevoke } from '../store-port.js';
+/** The revoke and its audit row commit together, so a failed audit write leaves the key live and the caller sees the error. */
+export declare function revokeKeyAt(db: DatabaseSyncLike, revoke: KeyRevoke): string;
+export declare function auditHighIdAt(db: DatabaseSyncLike): number;
+//# sourceMappingURL=key-audit.d.ts.map

package/dist/store/key-audit.js

@@ -0,0 +1,25 @@
+// hippo.db's half of the KeyAudit store group.
+import { NotFoundError } from '../api-errors.js';
+import { appendAuditEvent } from '../audit.js';
+import { revokeApiKey } from '../auth.js';
+import { withWriteScope } from '../db.js';
+import { selectApiKeyOwner } from './tenant-lookup.js';
+/** The revoke and its audit row commit together, so a failed audit write leaves the key live and the caller sees the error. */
+export function revokeKeyAt(db, revoke) {
+    return withWriteScope(db, 'revoke_api_key', () => {
+        const row = selectApiKeyOwner(db, revoke.keyId);
+        if (!row || row.tenantId !== revoke.tenantId)
+            throw new NotFoundError(`Unknown key_id: ${revoke.keyId}`);
+        if (row.revokedAt)
+            return row.revokedAt;
+        revokeApiKey(db, revoke.keyId, revoke.at);
+        appendAuditEvent(db, { tenantId: row.tenantId, actor: revoke.actor, op: 'auth_revoke', targetId: revoke.keyId });
+        return revoke.at;
+    });
+}
+export function auditHighIdAt(db) {
+    // SAFETY: the SELECT names one column, seq; `.get` returns undefined before audit_log's first row.
+    const row = db.prepare("SELECT seq FROM sqlite_sequence WHERE name = 'audit_log'").get();
+    return row?.seq ?? 0;
+}
+//# sourceMappingURL=key-audit.js.map

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,12 +1,14 @@
 import { type ApiKeyRecord } from './auth.js';
-import { type AppendAuditOpts } from './audit.js';
+import { type AppendAuditOpts, type AuditEvent, type ListAuditAfterOpts } 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 } from './store/search-rows.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. */
@@ -35,8 +37,44 @@ export interface RecallWrites {
         readonly opts: StrengthenOptions;
     };
 }
+/** The reads behind recall's vector arm. */
+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>>;
+}
+export interface KeyRevoke {
+    readonly tenantId: string;
+    readonly keyId: string;
+    readonly actor: string;
+    readonly at: string;
+}
+export interface KeyAudit {
+    /** Sets revoked_at to `at` and appends one auth_revoke row (the key's tenant, `actor`, the key id) in one transaction, then resolves to `at`. A revoked
+     *  key resolves to its own revoked_at and writes nothing; a key missing from `tenantId` rejects with NotFoundError `Unknown key_id: <keyId>`. */
+    revokeApiKey(revoke: KeyRevoke): Promise<string>;
+    /** As `listAuditEventsAfter`: rows above `afterId` in ascending id order, with its RangeErrors, limit clamp and tenant filter. */
+    auditEventsAfter(opts: ListAuditAfterOpts): Promise<AuditEvent[]>;
+    /** The highest audit id ever assigned, pruned rows included, 0 before the first; a tail that sees it drop knows the log was restored. */
+    auditHighId(): Promise<number>;
+}
+/** The optional groups: a store sets each one whole or leaves it unset, and a route or MCP tool names the one it needs. */
+export interface StoreGroups {
+    /** Unset on a store built before them, where hybrid and physics recall under an embedding provider answer 501. */
+    readonly vectors: VectorReads;
+    readonly keyAudit: KeyAudit;
+}
+export type StoreGroup = 'base' | keyof StoreGroups;
+export declare function hasGroup(store: HippoStore, group: StoreGroup): boolean;
+/** The group's methods; a store without them throws StoreNotPortedError, which answers 501 as any unported path does. */
+export declare function requireGroup<G extends keyof StoreGroups>(store: HippoStore, group: G): StoreGroups[G];
 /** 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 {
+export interface HippoStore extends Partial<StoreGroups> {
     /** '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. */
@@ -74,7 +112,7 @@ export declare function storeFor(ctx: {
     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;
+export declare function sqliteStore(hippoRoot: string): HippoStore & StoreGroups;
 /** 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. */