hippo-memory 1.67.0 → 1.68.0

package/dist/api/auth.d.ts

@@ -1,7 +1,6 @@
 import { type ApiKeyListItem, type ApiKeyListRow } from '../auth.js';
 import type { KeysetPosition } from '../keyset.js';
-import { type HippoStore } from '../store-port.js';
-import type { Context } from './types.js';
+import type { Context, StoreReply } from './types.js';
 export interface AuthCreateOpts {
     label?: string;
     /**
@@ -30,7 +29,7 @@ export interface AuthCreateResult {
  * Only an admin actor can mint (ForbiddenError otherwise), and a key never
  * outranks its minter: a resolver admin is tenant-only, so it mints members.
  */
-export declare function authCreate(ctx: Context, opts: AuthCreateOpts): AuthCreateResult;
+export declare function authCreate<C extends Context>(ctx: C, opts: AuthCreateOpts): StoreReply<C, AuthCreateResult>;
 export interface AuthCreateSelfOpts {
     label?: string;
     /** Days until the new key expires. */
@@ -42,8 +41,9 @@ export interface AuthCreateSelfResult extends AuthCreateResult {
     /** ISO time the key stops working. */
     expiresAt: string;
 }
-/** Mint a member key for the caller an auth resolver vouched for, whatever its role; the binary floor, the cap's revokes, the mint and its audit rows commit or fail together. */
-export declare function authCreateSelf(ctx: Context, opts: AuthCreateSelfOpts): AuthCreateSelfResult;
+/** Mint a member key for the caller an auth resolver vouched for, whatever its role; the binary floor, the cap's revokes, the mint and its audit rows commit or fail together.
+ *  With `ctx.store`, its keyWrites group runs that transaction; hippo.db is opened only when there is no store. */
+export declare function authCreateSelf<C extends Context>(ctx: C, opts: AuthCreateSelfOpts): StoreReply<C, AuthCreateSelfResult>;
 /**
  * List API keys visible to the calling tenant.
  *
@@ -52,27 +52,22 @@ export declare function authCreateSelf(ctx: Context, opts: AuthCreateSelfOpts):
  * scoped because future multi-tenant deployments will share a hippoRoot, and
  * tenant A must not see tenant B's keys. Read-only, so no audit emit.
  */
-export declare function authList(ctx: Context, opts: {
+export declare function authList<C extends Context>(ctx: C, opts: {
     active: boolean;
-}): ApiKeyListItem[];
-/** One page of the caller's tenant's keys, newest first, with the row ids a next-page cursor is built from. */
-export declare function authListRows(ctx: Context, opts: {
+}): StoreReply<C, ApiKeyListItem[]>;
+type KeyListOpts = {
     active: boolean;
     limit?: number;
     after?: KeysetPosition;
-}): ApiKeyListRow[];
+};
+/** One page of the caller's tenant's keys, newest first, with the row ids a next-page cursor is built from.
+ *  With `ctx.store`, its keyWrites group reads them; hippo.db is opened only when there is no store. */
+export declare function authListRows<C extends Context>(ctx: C, opts: KeyListOpts): StoreReply<C, ApiKeyListRow[]>;
 export interface AuthRevokeResult {
     ok: true;
     revokedAt: string;
 }
-/** A promise when `ctx` carries a store, since every store method is async; today's plain result when it carries none.
- *  hippoRoot keeps the second test off TypeScript's weak-type rule, which would fail a ctx that has no store key at all. */
-export type AuthRevokeReply<C extends Context> = C extends {
-    readonly store: HippoStore;
-} ? Promise<AuthRevokeResult> : C extends {
-    readonly hippoRoot: string;
-    readonly store?: undefined;
-} ? AuthRevokeResult : AuthRevokeResult | Promise<AuthRevokeResult>;
+export type AuthRevokeReply<C extends Context> = StoreReply<C, AuthRevokeResult>;
 /** Revoke a key in the caller's tenant: a member API key may revoke only itself, a resolver member only the keys it minted.
  *  With `ctx.store`, its keyAudit group revokes and writes the auth_revoke row; hippo.db is opened only when there is no store. */
 export declare function authRevoke<C extends Context>(ctx: C, keyId: string): AuthRevokeReply<C>;
@@ -89,4 +84,5 @@ export interface AuthGrantResult {
 export declare function authGrant(ctx: Context, keyId: string, scope: string): AuthGrantResult;
 /** Revoke `keyId`'s grant on `scope`. Same authorization and lookup rules as authGrant. */
 export declare function authUngrant(ctx: Context, keyId: string, scope: string): AuthGrantResult;
+export {};
 //# sourceMappingURL=auth.d.ts.map

package/dist/api/auth.js

@@ -2,31 +2,17 @@
 import { openHippoDb, closeHippoDb } from '../db.js';
 import { BadRequestError, ConflictError, ForbiddenError, NotFoundError } from '../api-errors.js';
 import { appendAuditEvent, reportAuditWriteFailure } from '../audit.js';
-import { createApiKey, forgetVerifiedKey, listApiKeyRows, listLiveOwnedKeyIds, revokeApiKey, grantScope, ungrantScope, } from '../auth.js';
+import { forgetVerifiedKey, insertApiKey, listApiKeyRows, mintApiKey, revokeApiKey, grantScope, ungrantScope, } from '../auth.js';
 import { DAY_MS } from '../dashboard-snapshot.js';
 import { isRestrictedScope } from '../recall-scope.js';
 import { requireGroup } from '../store-port.js';
+import { createAuditOf, createKeyAt, createSelfKeyAt } from '../store/key-writes.js';
 import { selectApiKeyOwner } from '../store/tenant-lookup.js';
 const API_KEY_SUBJECT = 'api_key:';
 /** The key id an API-key actor's subject names, or null for any other actor. */
 function keyIdOfSubject(subject) {
     return subject.startsWith(API_KEY_SUBJECT) ? subject.slice(API_KEY_SUBJECT.length) : null;
 }
-function inTransaction(db, fn) {
-    db.exec('BEGIN IMMEDIATE');
-    try {
-        const out = fn();
-        db.exec('COMMIT');
-        return out;
-    }
-    catch (err) {
-        try {
-            db.exec('ROLLBACK');
-        }
-        catch { /* keep the original error */ }
-        throw err;
-    }
-}
 /**
  * Mint a new API key. The new key is ALWAYS bound to `ctx.tenantId`. Callers
  * cannot override the tenant via the opts bag — a previous `tenantId` field
@@ -39,38 +25,56 @@ function inTransaction(db, fn) {
  * outranks its minter: a resolver admin is tenant-only, so it mints members.
  */
 export function authCreate(ctx, opts) {
+    // With a store, its keyWrites group stores the key and its auth_create row together, and hippo.db is never opened.
+    const reply = ctx.store ? createThroughStore(ctx, ctx.store, opts) : createOnHippoDb(ctx, opts);
+    // SAFETY: as in authRevoke, a C typed with a store gets the promise its path returns and a C that hides one gets the union.
+    return reply;
+}
+/** A key row in the caller's tenant, made here so only its hash ever reaches a store. */
+function newKey(ctx, fields) {
+    const { keyId, plaintext, keyHash } = mintApiKey();
+    return { plaintext, key: { ...fields, keyId, keyHash, tenantId: ctx.tenantId, createdAt: new Date().toISOString() } };
+}
+function adminKeyMint(ctx, opts) {
     if (ctx.actor.role !== 'admin') {
         throw new ForbiddenError('Only an admin key can create API keys');
     }
     if (ctx.actor.viaAuthResolver && opts.role === 'admin') {
         throw new ForbiddenError('A key minted through the auth resolver can only be a member key');
     }
+    const role = opts.role ?? (ctx.actor.viaAuthResolver ? 'member' : 'admin');
+    const label = opts.label ?? null;
+    const { plaintext, key } = newKey(ctx, { label, role, ownerSubject: null, expiresAt: null });
+    // The plaintext is NEVER logged; metadata carries label + role, keyId is non-secret.
+    return { plaintext, mint: { key, actor: ctx.actor.subject, metadata: { label, role } } };
+}
+function createResult({ key }, plaintext) {
+    return { keyId: key.keyId, plaintext, tenantId: key.tenantId, role: key.role };
+}
+async function createThroughStore(ctx, store, opts) {
+    const keyWrites = requireGroup(store, 'keyWrites');
+    const { plaintext, mint } = adminKeyMint(ctx, opts);
+    await keyWrites.createApiKey(mint);
+    return createResult(mint, plaintext);
+}
+function createOnHippoDb(ctx, opts) {
+    const { plaintext, mint } = adminKeyMint(ctx, opts);
     const db = openHippoDb(ctx.hippoRoot);
     try {
-        const role = opts.role ?? (ctx.actor.viaAuthResolver ? 'member' : 'admin');
-        const mint = () => createApiKey(db, { tenantId: ctx.tenantId, label: opts.label, role });
-        // The plaintext is NEVER logged; metadata carries label + role, keyId is non-secret.
-        const audit = (keyId) => appendAuditEvent(db, {
-            tenantId: ctx.tenantId, actor: ctx.actor.subject, op: 'auth_create', targetId: keyId, metadata: { label: opts.label ?? null, role },
-        });
         // A resolver admin's keys are found again only through their audit rows, so the key and its row commit together.
         if (ctx.actor.viaAuthResolver) {
-            const result = inTransaction(db, () => {
-                const minted = mint();
-                audit(minted.keyId);
-                return minted;
-            });
-            return { keyId: result.keyId, plaintext: result.plaintext, tenantId: ctx.tenantId, role };
+            createKeyAt(db, mint);
+            return createResult(mint, plaintext);
         }
-        const result = mint();
+        insertApiKey(db, mint.key);
         try {
-            audit(result.keyId);
+            appendAuditEvent(db, createAuditOf(mint));
         }
         catch (error) {
             // Audit must not crash a successful mint.
-            reportAuditWriteFailure('auth_create', String(error), result.keyId);
+            reportAuditWriteFailure('auth_create', String(error), mint.key.keyId);
         }
-        return { keyId: result.keyId, plaintext: result.plaintext, tenantId: ctx.tenantId, role };
+        return createResult(mint, plaintext);
     }
     finally {
         closeHippoDb(db);
@@ -86,34 +90,43 @@ function assertSelfMintOpts({ ttlDays, perSubject }) {
         throw new RangeError(`authCreateSelf: perSubject must be a whole number of at least 1, got ${String(perSubject)}`);
     }
 }
-/** Mint a member key for the caller an auth resolver vouched for, whatever its role; the binary floor, the cap's revokes, the mint and its audit rows commit or fail together. */
+/** Mint a member key for the caller an auth resolver vouched for, whatever its role; the binary floor, the cap's revokes, the mint and its audit rows commit or fail together.
+ *  With `ctx.store`, its keyWrites group runs that transaction; hippo.db is opened only when there is no store. */
 export function authCreateSelf(ctx, opts) {
+    const reply = ctx.store ? createSelfThroughStore(ctx, ctx.store, opts) : createSelfOnHippoDb(ctx, opts);
+    // SAFETY: as in authRevoke, a C typed with a store gets the promise its path returns and a C that hides one gets the union.
+    return reply;
+}
+function selfKeyMint(ctx, opts) {
     if (!ctx.actor.viaAuthResolver) {
         throw new ForbiddenError('Only a caller signed in through the auth resolver can mint its own key');
     }
     assertSelfMintOpts(opts);
-    const { tenantId, actor: { subject } } = ctx;
-    const now = Date.now();
-    const expiresAt = new Date(now + opts.ttlDays * DAY_MS).toISOString();
+    const { subject } = ctx.actor;
+    const label = opts.label ?? null;
+    const expiresAt = new Date(Date.now() + opts.ttlDays * DAY_MS).toISOString();
+    // Not destructured: a binding pattern makes TypeScript infer F as KeyFields and lose ownerSubject's string type.
+    const made = newKey(ctx, { label, role: 'member', ownerSubject: subject, expiresAt });
+    // Same op and actor as an admin mint, so a lookup by audit row finds this key too.
+    return { plaintext: made.plaintext, mint: { key: made.key, actor: subject, metadata: { label, role: 'member', self: true, expiresAt }, perSubject: opts.perSubject } };
+}
+function selfResult({ key }, plaintext) {
+    return { keyId: key.keyId, plaintext, tenantId: key.tenantId, role: 'member', expiresAt: key.expiresAt };
+}
+/** The store revokes the replaced keys without this process's verified-key cache, so they leave it here once the mint commits. */
+async function createSelfThroughStore(ctx, store, opts) {
+    const keyWrites = requireGroup(store, 'keyWrites');
+    const { plaintext, mint } = selfKeyMint(ctx, opts);
+    for (const keyId of await keyWrites.createSelfApiKey(mint))
+        forgetVerifiedKey(keyId);
+    return selfResult(mint, plaintext);
+}
+function createSelfOnHippoDb(ctx, opts) {
+    const { plaintext, mint } = selfKeyMint(ctx, opts);
     const db = openHippoDb(ctx.hippoRoot);
     try {
-        // IMMEDIATE takes the write lock before the count, so two mints for one subject cannot both see room under the cap.
-        const result = inTransaction(db, () => {
-            const live = listLiveOwnedKeyIds(db, tenantId, subject, now);
-            const replaced = live.slice(0, Math.max(0, live.length - opts.perSubject + 1));
-            const minted = createApiKey(db, { tenantId, label: opts.label, role: 'member', ownerSubject: subject, expiresAt });
-            for (const keyId of replaced) {
-                revokeApiKey(db, keyId);
-                appendAuditEvent(db, { tenantId, actor: subject, op: 'auth_revoke', targetId: keyId, metadata: { replacedBy: minted.keyId } });
-            }
-            // Same op and actor as an admin mint, so a lookup by audit row finds this key too.
-            appendAuditEvent(db, {
-                tenantId, actor: subject, op: 'auth_create', targetId: minted.keyId,
-                metadata: { label: opts.label ?? null, role: 'member', self: true, expiresAt },
-            });
-            return minted;
-        });
-        return { keyId: result.keyId, plaintext: result.plaintext, tenantId, role: 'member', expiresAt };
+        createSelfKeyAt(db, mint);
+        return selfResult(mint, plaintext);
     }
     finally {
         closeHippoDb(db);
@@ -128,30 +141,50 @@ export function authCreateSelf(ctx, opts) {
  * tenant A must not see tenant B's keys. Read-only, so no audit emit.
  */
 export function authList(ctx, opts) {
-    return authListRows(ctx, opts).map((r) => r.key);
+    const keysOf = (rows) => rows.map((r) => r.key);
+    const rows = listRows(ctx, opts);
+    // SAFETY: the promise comes back exactly when ctx has a store, as StoreReply says.
+    return (rows instanceof Promise ? rows.then(keysOf) : keysOf(rows));
 }
-/** One page of the caller's tenant's keys, newest first, with the row ids a next-page cursor is built from. */
+/** One page of the caller's tenant's keys, newest first, with the row ids a next-page cursor is built from.
+ *  With `ctx.store`, its keyWrites group reads them; hippo.db is opened only when there is no store. */
 export function authListRows(ctx, opts) {
+    // SAFETY: the promise comes back exactly when ctx has a store, as StoreReply says.
+    return listRows(ctx, opts);
+}
+function listRows(ctx, opts) {
+    return ctx.store ? listThroughStore(ctx, ctx.store, opts) : listOnHippoDb(ctx, opts);
+}
+async function listThroughStore(ctx, store, opts) {
+    const keyWrites = requireGroup(store, 'keyWrites');
+    const keyId = memberKeyIdOf(ctx.actor);
+    const filter = memberListFilter(ctx.actor, keyId === null ? undefined : (await store.findApiKey(keyId))?.ownerSubject);
+    return filter === null ? [] : keyWrites.listApiKeys({ ...opts, tenantId: ctx.tenantId, ...filter });
+}
+function listOnHippoDb(ctx, opts) {
     const db = openHippoDb(ctx.hippoRoot);
     try {
-        const filter = memberListFilter(db, ctx);
+        const keyId = memberKeyIdOf(ctx.actor);
+        const filter = memberListFilter(ctx.actor, keyId === null ? undefined : selectApiKeyOwner(db, keyId)?.ownerSubject);
         return filter === null ? [] : listApiKeyRows(db, { ...opts, tenantId: ctx.tenantId, ...filter });
     }
     finally {
         closeHippoDb(db);
     }
 }
+/** The key id of a member API key caller, whose owner decides what it lists; null for any other caller. */
+function memberKeyIdOf(actor) {
+    return actor.role === 'admin' || actor.viaAuthResolver ? null : keyIdOfSubject(actor.subject);
+}
 /** A member sees only the keys its person minted, or just its own key when that has no owner; an admin sees the whole tenant; null means no keys. */
-function memberListFilter(db, ctx) {
-    const { actor } = ctx;
+function memberListFilter(actor, owner) {
     if (actor.role === 'admin')
         return {};
     if (actor.viaAuthResolver)
         return { ownerSubject: actor.subject };
-    const keyId = keyIdOfSubject(actor.subject);
+    const keyId = memberKeyIdOf(actor);
     if (keyId === null)
         return null;
-    const owner = selectApiKeyOwner(db, keyId)?.ownerSubject;
     return owner ? { ownerSubject: owner } : { keyId };
 }
 /** Throws unless `ctx` may revoke `keyId`; a member gets one answer for a missing, foreign or unowned key, so it cannot probe key ids. */

package/dist/api/types.d.ts

@@ -25,6 +25,15 @@ export interface Context {
     actor: Actor;
     store?: HippoStore;
 }
+export type HippoDbContext = Context & {
+    store?: undefined;
+};
+export type StoreReply<C extends Context, R> = C extends {
+    readonly store: HippoStore;
+} ? Promise<R> : C extends {
+    readonly hippoRoot: string;
+    readonly store?: undefined;
+} ? R : R | Promise<R>;
 /**
  * Helper for building process-local Actor values (admin and host admin),
  * used by CLI and CLI-run connector Context constructors so the role

package/dist/auth.d.ts

@@ -23,6 +23,25 @@ export interface CreateApiKeyResult {
     keyId: string;
     plaintext: string;
 }
+/** A fresh key: the plaintext its caller sees once, and the scrypt hash a store keeps in its place. */
+export interface MintedApiKey extends CreateApiKeyResult {
+    keyHash: string;
+}
+export declare function mintApiKey(): MintedApiKey;
+/** One api_keys row as core hands it to a store: the hash of the secret, never the secret. */
+export interface NewApiKey {
+    readonly keyId: string;
+    readonly keyHash: string;
+    readonly tenantId: string;
+    readonly label: string | null;
+    readonly role: 'admin' | 'member';
+    readonly createdAt: string;
+    /** The auth-resolver subject a self-service key belongs to; null for a key an admin or the CLI mints. */
+    readonly ownerSubject: string | null;
+    /** ISO time the key stops working; null means it never expires. */
+    readonly expiresAt: string | null;
+}
+export declare function insertApiKey(db: DatabaseSyncLike, key: NewApiKey): void;
 export declare function createApiKey(db: DatabaseSyncLike, opts: CreateApiKeyOpts): CreateApiKeyResult;
 export interface ValidateResult {
     valid: boolean;

package/dist/auth.js

@@ -36,17 +36,25 @@ function verifyKey(plaintext, stored) {
     const actual = scryptSync(plaintext, salt, expected.length);
     return expected.length === actual.length && timingSafeEqual(expected, actual);
 }
-export function createApiKey(db, opts) {
+export function mintApiKey() {
     const keyId = `${API_KEY_PREFIX}${randBase32(ID_LEN)}`;
-    const secret = randBase32(SECRET_LEN);
-    const plaintext = `${keyId}.${secret}`;
-    const hash = hashKey(plaintext);
+    const plaintext = `${keyId}.${randBase32(SECRET_LEN)}`;
+    return { keyId, plaintext, keyHash: hashKey(plaintext) };
+}
+export function insertApiKey(db, key) {
     // openHippoDb runs runMigrations synchronously before returning the db handle,
     // so migration v26 (adds role column) is in place before this INSERT runs.
     // An older binary ignores expires_at and would honour an expired key, so the store shuts it out before the first one exists.
-    if (opts.expiresAt !== undefined)
+    if (key.expiresAt !== null)
         raiseMinBinary(db, EXPIRING_KEYS_MIN_BINARY);
-    db.prepare(`INSERT INTO api_keys (key_id, key_hash, tenant_id, label, created_at, role, owner_subject, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(keyId, hash, opts.tenantId, opts.label ?? null, new Date().toISOString(), opts.role ?? 'admin', opts.ownerSubject ?? null, opts.expiresAt ?? null);
+    db.prepare(`INSERT INTO api_keys (key_id, key_hash, tenant_id, label, created_at, role, owner_subject, expires_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(key.keyId, key.keyHash, key.tenantId, key.label, key.createdAt, key.role, key.ownerSubject, key.expiresAt);
+}
+export function createApiKey(db, opts) {
+    const { keyId, plaintext, keyHash } = mintApiKey();
+    insertApiKey(db, {
+        keyId, keyHash, tenantId: opts.tenantId, label: opts.label ?? null, role: opts.role ?? 'admin', createdAt: new Date().toISOString(),
+        ownerSubject: opts.ownerSubject ?? null, expiresAt: opts.expiresAt ?? null,
+    });
     return { keyId, plaintext };
 }
 /** The api_keys row for `keyId` with its scope grants; null when no row matches. */

package/dist/embeddings.d.ts

@@ -4,8 +4,10 @@
  * Falls back silently if the library is not installed.
  */
 import { MemoryEntry } from './memory.js';
+import { type DatabaseSyncLike } from './db.js';
 import { EMBEDDING_MODEL_META_KEY } from './vector-store.js';
 import { type EmbeddingProvider } from './embedding-provider.js';
+import type { HippoStore } from './store-port.js';
 export { EMBEDDING_MODEL_META_KEY };
 /**
  * Bump whenever `embeddingInputText`'s composition changes in a way that
@@ -73,10 +75,13 @@ export interface EmbeddingIndexState {
 export declare function indexedModel(state: EmbeddingIndexState): string | null;
 /** The one rebuild rule every store applies to its indexed model. */
 export declare function indexNeedsRebuild(indexed: string | null, providerId: string): boolean;
+/** Whether a vector write under the index identity `model` first drops the stored index, which another model built. */
+export declare function replacesIndex(state: EmbeddingIndexState, model: string): boolean;
 export declare function resolveIndexedEmbeddingModel(hippoRoot: string, index?: Record<string, number[]>): string | null;
 export declare function embeddingModelRequiresReindex(hippoRoot: string, model: string, index?: Record<string, number[]>): boolean;
 /** hippo.db's index state, the meta row and the EXISTS on one handle. */
 export declare function embeddingIndexStateAt(hippoRoot: string): EmbeddingIndexState;
+export declare function embeddingIndexStateOn(db: DatabaseSyncLike): EmbeddingIndexState;
 /**
  * Cosine similarity between two vectors. Handles unnormalized vectors.
  * Returns 0 for empty or mismatched vectors.
@@ -88,14 +93,9 @@ export declare function loadEmbeddingIndex(hippoRoot: string): Record<string, nu
 export declare function loadStoredVectors(hippoRoot: string, ids: readonly string[]): Map<string, number[]>;
 /** Replace every stored vector with `index`; `model` defaults to the stored index identity. */
 export declare function saveEmbeddingIndex(hippoRoot: string, index: Record<string, number[]>, model?: string): void;
-/**
- * Embed a single memory entry and cache the result in the embedding index.
- */
-export declare function embedMemory(hippoRoot: string, entry: MemoryEntry, model?: string): Promise<void>;
-/**
- * Embed all entries in hippoRoot that don't already have cached vectors.
- * Prunes orphaned embeddings for memories that no longer exist.
- * Returns the count of newly embedded entries. `provider` defaults to the store's configured one.
- */
-export declare function embedAll(hippoRoot: string, model?: string, provider?: EmbeddingProvider): Promise<number>;
+/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db. */
+export declare function embedMemory(hippoRoot: string, entry: MemoryEntry, model?: string, store?: HippoStore): Promise<void>;
+/** Embeds every entry with no cached vector, prunes vectors of deleted memories, and returns how many it embedded; `provider` defaults to the
+ *  configured one. With `store`, every tenant's memories with no vector for the provider's model go through its `vectorWrites`, never hippo.db. */
+export declare function embedAll(hippoRoot: string, model?: string, provider?: EmbeddingProvider, store?: HippoStore): Promise<number>;
 //# sourceMappingURL=embeddings.d.ts.map

package/dist/embeddings.js

@@ -16,6 +16,7 @@ import { resolveEmbeddingProvider } from './embedding-provider.js';
 import { DEFAULT_EMBEDDING_MODEL } from './local-embedding.js';
 import { redactSecretsStrict } from './secret-detect.js';
 import { log } from './log.js';
+import { StoreNotPortedError } from './db/sqlite-blocked.js';
 export { EMBEDDING_MODEL_META_KEY };
 /**
  * Bump whenever `embeddingInputText`'s composition changes in a way that
@@ -109,6 +110,11 @@ export function indexedModel(state) {
 export function indexNeedsRebuild(indexed, providerId) {
     return indexed !== null && indexed !== embeddingIndexIdentity(providerId);
 }
+/** Whether a vector write under the index identity `model` first drops the stored index, which another model built. */
+export function replacesIndex(state, model) {
+    const indexed = indexedModel(state);
+    return indexed !== null && indexed !== model;
+}
 export function resolveIndexedEmbeddingModel(hippoRoot, index) {
     const storedModel = loadStoredEmbeddingModel(hippoRoot);
     if (storedModel)
@@ -120,10 +126,13 @@ export function embeddingModelRequiresReindex(hippoRoot, model, index) {
 }
 /** hippo.db's index state, the meta row and the EXISTS on one handle. */
 export function embeddingIndexStateAt(hippoRoot) {
-    return withVectorDb(hippoRoot, (db) => ({
+    return withVectorDb(hippoRoot, embeddingIndexStateOn);
+}
+export function embeddingIndexStateOn(db) {
+    return {
         storedModel: getMeta(db, EMBEDDING_MODEL_META_KEY, '').trim() || null,
         hasVectors: hasStoredVectors(db),
-    }));
+    };
 }
 async function rebuildEmbeddingIndex(entries, provider) {
     const rebuilt = {};
@@ -273,12 +282,7 @@ async function acquireEmbedFileLock(hippoRoot) {
     }
 }
 async function withEmbedLock(hippoRoot, fn) {
-    let resolve;
-    const next = new Promise(r => { resolve = r; });
-    const prev = _embedWriteLock;
-    _embedWriteLock = next;
-    await prev;
-    try {
+    return withProcessEmbedLock(async () => {
         const release = await acquireEmbedFileLock(hippoRoot);
         try {
             return await fn();
@@ -286,6 +290,17 @@ async function withEmbedLock(hippoRoot, fn) {
         finally {
             release();
         }
+    });
+}
+// A store keeps each write whole in its own transaction, and a lock file in hippoRoot would not reach a worker on another host.
+async function withProcessEmbedLock(fn) {
+    let resolve;
+    const next = new Promise(r => { resolve = r; });
+    const prev = _embedWriteLock;
+    _embedWriteLock = next;
+    await prev;
+    try {
+        return await fn();
     }
     finally {
         resolve();
@@ -301,10 +316,79 @@ function warnEmbedFailureOnce(source, rawMessage) {
     const message = redactSecretsStrict(rawMessage).replace(/\s+/g, ' ').replace(/\.+$/, '');
     log.warn(`embedding failed (${source}): ${message}. Memories are stored without embeddings until this is fixed.`);
 }
-/**
- * Embed a single memory entry and cache the result in the embedding index.
- */
-export async function embedMemory(hippoRoot, entry, model) {
+// store-port.ts imports this module, so its requireGroup would close an import cycle.
+function vectorGroups(store) {
+    if (store.vectors === undefined)
+        throw new StoreNotPortedError(store.kind, 'vectors');
+    if (store.vectorWrites === undefined)
+        throw new StoreNotPortedError(store.kind, 'vectorWrites');
+    return [store.vectors, store.vectorWrites];
+}
+/** Writes one page's vectors, one writeVectors per tenant, and stops at the first refused write; `withParticles` seeds each memory's particle. */
+async function writeVectorPage(writes, write, page, vectors, withParticles) {
+    const byTenant = new Map();
+    page.forEach((entry, i) => {
+        const vector = vectors[i];
+        if (!vector || vector.length === 0)
+            return noteSkippedEmbedding(entry.id);
+        const row = withParticles ? { memoryId: entry.id, vector, particle: initializeParticle(entry, vector) } : { memoryId: entry.id, vector };
+        byTenant.set(entry.tenantId, [...(byTenant.get(entry.tenantId) ?? []), row]);
+    });
+    let written = 0;
+    for (const [tenantId, rows] of byTenant) {
+        const result = await writes.writeVectors({ ...write, tenantId, rows });
+        if (result.modelMismatch)
+            return { written, modelMismatch: true };
+        written += result.written;
+    }
+    return { written, modelMismatch: false };
+}
+const STORE_PAGE = 64;
+const OTHER_MODEL_INDEX = "the vector index was built by another embedding model; run 'hippo embed' to rebuild it";
+/** Embeds every memory with no vector under `model`, page by page, so a provider failure keeps the pages written; a rebuild reseeds the particles it drops. */
+async function backfillInStore(writes, provider, model, rebuild) {
+    let count = 0;
+    let afterId;
+    for (;;) {
+        const page = await writes.entriesWithoutVector({ model, afterId, limit: STORE_PAGE });
+        if (page.length === 0)
+            return count;
+        afterId = page[page.length - 1].id;
+        const vectors = await provider.embed(page.map((e) => embeddingInputText(e)), 'passage');
+        const result = await writeVectorPage(writes, { model, replaceIndex: rebuild }, page, vectors, rebuild);
+        // Another process rebuilt the index mid-run; every later page would be refused too, after paying the provider for it.
+        if (result.modelMismatch)
+            throw new Error(OTHER_MODEL_INDEX);
+        count += result.written;
+    }
+}
+/** embedAll on a store: a model change re-embeds every memory, and the first page written drops the old index. */
+async function embedAllInStore(store, provider) {
+    const [reads, writes] = vectorGroups(store);
+    const rebuild = indexNeedsRebuild(indexedModel(await reads.embeddingIndexState()), provider.id);
+    return backfillInStore(writes, provider, embeddingIndexIdentity(provider.id), rebuild);
+}
+/** embedMemory on a store; like the hippo.db path it resolves whatever fails. Unlike it, it leaves a model change to embedAll, so a stale
+ *  read here never drops another process's rebuild; the read only saves a paid embed call, as the write refuses another model itself. */
+function embedMemoryInStore(store, provider, entry) {
+    return withProcessEmbedLock(async () => {
+        const [reads, writes] = vectorGroups(store);
+        const model = embeddingIndexIdentity(provider.id);
+        try {
+            const refused = replacesIndex(await reads.embeddingIndexState(), model)
+                || (await writeVectorPage(writes, { model, replaceIndex: false }, [entry], await provider.embed([embeddingInputText(entry)], 'passage'), true)).modelMismatch;
+            if (refused)
+                warnEmbedFailureOnce('index', OTHER_MODEL_INDEX);
+        }
+        catch (err) {
+            warnEmbedFailureOnce(provider.kind, err instanceof Error ? err.message : String(err));
+        }
+    }).catch((err) => {
+        log.warn(`skipped embedding ${entry.id} (${err instanceof Error ? err.message : String(err)})`);
+    });
+}
+/** Embed a single memory entry and cache the result in the embedding index; with `store`, through its vectorWrites, never opening hippo.db. */
+export async function embedMemory(hippoRoot, entry, model, store) {
     let provider;
     try {
         provider = resolveEmbeddingProvider(hippoRoot, { model });
@@ -316,6 +400,8 @@ export async function embedMemory(hippoRoot, entry, model) {
     }
     if (!provider.isAvailable())
         return;
+    if (store)
+        return embedMemoryInStore(store, provider, entry);
     return withEmbedLock(hippoRoot, async () => {
         // embedMemory is best-effort: an embedding failure (API down / bad key / 5xx)
         // must not reject the caller's write — `getEmbedding` historically swallowed
@@ -418,16 +504,15 @@ async function backfillPending(hippoRoot, provider, pending, model) {
     }
     return { count, backfillError };
 }
-/**
- * Embed all entries in hippoRoot that don't already have cached vectors.
- * Prunes orphaned embeddings for memories that no longer exist.
- * Returns the count of newly embedded entries. `provider` defaults to the store's configured one.
- */
-export async function embedAll(hippoRoot, model, provider = resolveEmbeddingProvider(hippoRoot, { model })) {
+/** Embeds every entry with no cached vector, prunes vectors of deleted memories, and returns how many it embedded; `provider` defaults to the
+ *  configured one. With `store`, every tenant's memories with no vector for the provider's model go through its `vectorWrites`, never hippo.db. */
+export async function embedAll(hippoRoot, model, provider = resolveEmbeddingProvider(hippoRoot, { model }), store) {
     if (!provider.isAvailable()) {
         throwIfProviderKeyMissing(hippoRoot, provider);
         return 0;
     }
+    if (store)
+        return withProcessEmbedLock(() => embedAllInStore(store, provider));
     return withEmbedLock(hippoRoot, async () => {
         const identity = provider.id;
         // Host-wide by design. embedAll backfills vectors for all tenants'

package/dist/server/routes/admin.js

@@ -44,7 +44,7 @@ export async function handleCreateAuthKey({ req, res, opts }) {
     // bound to the caller's authenticated tenant (ctx.tenantId, resolved
     // from the Bearer token). Forwarding body.tenantId here would let
     // tenant A mint a key for tenant B — see authCreate doc comment.
-    const result = authCreate(ctx, {
+    const result = await authCreate(ctx, {
         label: labelRaw,
         role,
     });
@@ -68,7 +68,7 @@ export async function handleListAuthKeys({ req, res, opts, query }) {
     const limit = parseListLimit(query.get('limit'), MAX_AUTH_KEYS_PAGE, MAX_AUTH_KEYS_PAGE);
     const after = parseCursor(query.get('cursor'), 'integer', 'integer');
     const ctx = await buildContextWithAuth(req, opts);
-    const page = pageOf(authListRows(ctx, { active, limit: limit + 1, after }), limit, (r) => ({ key: r.rowId, id: r.rowId }));
+    const page = pageOf(await authListRows(ctx, { active, limit: limit + 1, after }), limit, (r) => ({ key: r.rowId, id: r.rowId }));
     setNextCursorHeader(res, page.nextCursor);
     sendJson(res, 200, page.items.map((r) => r.key));
     return;

package/dist/server.d.ts

@@ -11,8 +11,10 @@ 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 { 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 { hasGroup, sqliteStore, type HippoStore, type KeyAudit, type KeyListQuery, type KeyMint, type KeyRevoke, type KeyWrites, type RecallSearchArgs, type RecallWrites, type SelfKeyMint, type StoreGroup, type StoreGroups, type VectorReads, type VectorBackfillQuery, type VectorRowWrite, type VectorWrite, type VectorWriteResult, type VectorWrites, } from './store-port.js';
+export type { HippoDbContext, StoreReply } from './api/types.js';
+export type { ApiKeyListItem, ApiKeyListRow, ApiKeyRecord, ListApiKeysOpts, NewApiKey } from './auth.js';
+export type { KeysetPosition } from './keyset.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';
@@ -27,8 +29,9 @@ 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 { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, rankVectorRows, type VectorMatch, type VectorRow } from './vector-store.js';
+export { bufferToFloat32, float32ToBuffer } from './physics-state.js';
+export { replacesIndex } from './embeddings.js';
 export { OTHER_STORE_MARKER, OtherStoreFolderError, withSqliteAllowed } from './db.js';
 export { authCreate, type AuthCreateOpts, type AuthCreateResult } from './api.js';
 export { isSharedStore } from './config.js';

package/dist/server.js

@@ -48,9 +48,11 @@ export { captureSessionTexts } from './capture/session-texts.js';
 // An add-on serves from another database by passing serve() its own HippoStore.
 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';
+// An add-on store encodes, decodes and ranks vectors and particles with hippo.db's own code, and drops the index by its rule,
+// so both stores keep the same bytes and return the same ids in the same order.
+export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, rankVectorRows } from './vector-store.js';
+export { bufferToFloat32, float32ToBuffer } from './physics-state.js';
+export { replacesIndex } from './embeddings.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.
@@ -108,8 +110,8 @@ const V1_ROUTES = [
     { method: 'POST', path: '/v1/outcome', handler: handleApplyOutcome },
     { method: 'GET', path: '/v1/context', handler: handleGetContext },
     { method: 'POST', path: '/v1/sleep', handler: handleSleep },
-    { method: 'POST', path: '/v1/auth/keys', handler: handleCreateAuthKey },
-    { method: 'GET', path: '/v1/auth/keys', handler: handleListAuthKeys },
+    { method: 'POST', path: '/v1/auth/keys', storeReady: 'keyWrites', handler: handleCreateAuthKey },
+    { method: 'GET', path: '/v1/auth/keys', storeReady: 'keyWrites', handler: handleListAuthKeys },
     { 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 },

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

@@ -0,0 +1,9 @@
+import { type AppendAuditOpts } from '../audit.js';
+import { type DatabaseSyncLike } from '../db.js';
+import type { KeyMint, SelfKeyMint } from '../store-port.js';
+/** The auth_create row a mint writes; the plaintext never reaches it. */
+export declare function createAuditOf({ key, actor, metadata }: KeyMint): AppendAuditOpts;
+export declare function createKeyAt(db: DatabaseSyncLike, mint: KeyMint): void;
+/** IMMEDIATE takes the write lock before the count, so two mints for one owner cannot both see room under the cap. */
+export declare function createSelfKeyAt(db: DatabaseSyncLike, mint: SelfKeyMint): string[];
+//# sourceMappingURL=key-writes.d.ts.map

package/dist/store/key-writes.js

@@ -0,0 +1,30 @@
+// hippo.db's half of the KeyWrites store group.
+import { appendAuditEvent } from '../audit.js';
+import { insertApiKey, listLiveOwnedKeyIds, revokeApiKey } from '../auth.js';
+import { withWriteScope } from '../db.js';
+/** The auth_create row a mint writes; the plaintext never reaches it. */
+export function createAuditOf({ key, actor, metadata }) {
+    return { tenantId: key.tenantId, actor, op: 'auth_create', targetId: key.keyId, metadata };
+}
+export function createKeyAt(db, mint) {
+    withWriteScope(db, 'create_api_key', () => {
+        insertApiKey(db, mint.key);
+        appendAuditEvent(db, createAuditOf(mint));
+    });
+}
+/** IMMEDIATE takes the write lock before the count, so two mints for one owner cannot both see room under the cap. */
+export function createSelfKeyAt(db, mint) {
+    const { key, actor, perSubject } = mint;
+    return withWriteScope(db, 'create_self_api_key', () => {
+        const live = listLiveOwnedKeyIds(db, key.tenantId, key.ownerSubject, Date.parse(key.createdAt));
+        const replaced = live.slice(0, Math.max(0, live.length - perSubject + 1));
+        insertApiKey(db, key);
+        for (const keyId of replaced) {
+            revokeApiKey(db, keyId, key.createdAt);
+            appendAuditEvent(db, { tenantId: key.tenantId, actor, op: 'auth_revoke', targetId: keyId, metadata: { replacedBy: key.keyId } });
+        }
+        appendAuditEvent(db, createAuditOf(mint));
+        return replaced;
+    });
+}
+//# sourceMappingURL=key-writes.js.map

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

@@ -0,0 +1,6 @@
+import { type DatabaseSyncLike } from '../db.js';
+import type { MemoryEntry } from '../memory.js';
+import type { VectorBackfillQuery, VectorWrite, VectorWriteResult } from '../store-port.js';
+export declare function entriesWithoutVectorAt(db: DatabaseSyncLike, query: VectorBackfillQuery): MemoryEntry[];
+export declare function writeVectorsAt(db: DatabaseSyncLike, write: VectorWrite): VectorWriteResult;
+//# sourceMappingURL=vector-writes.d.ts.map

package/dist/store/vector-writes.js

@@ -0,0 +1,59 @@
+// hippo.db's half of the VectorWrites store group.
+import { setMeta, withWriteScope } from '../db.js';
+import { embeddingIndexStateOn, replacesIndex } from '../embeddings.js';
+import { float32ToBuffer } from '../physics-state.js';
+import { EMBEDDING_MODEL_META_KEY, upsertVectors } from '../vector-store.js';
+import { chunked } from './entry-reads.js';
+import { MEMORY_SELECT_COLUMNS, rowToEntry } from './rows.js';
+const MAX_BACKFILL_PAGE = 500;
+export function entriesWithoutVectorAt(db, query) {
+    if (!Number.isInteger(query.limit))
+        throw new RangeError('limit must be an integer');
+    const limit = Math.max(1, Math.min(query.limit, MAX_BACKFILL_PAGE));
+    const tenantClause = query.tenantId === undefined ? '' : ' AND tenant_id = ?';
+    const tenantArgs = query.tenantId === undefined ? [] : [query.tenantId];
+    // SAFETY: selects exactly MEMORY_SELECT_COLUMNS, matching MemoryRow's field set.
+    const rows = db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE id > ?${tenantClause}
+       AND NOT EXISTS (SELECT 1 FROM memory_vectors v WHERE v.memory_id = memories.id AND v.model = ?)
+     ORDER BY id LIMIT ?`).all(query.afterId ?? '', ...tenantArgs, query.model, limit);
+    return rows.map(rowToEntry);
+}
+function ownedIds(db, ids, tenantId) {
+    const owned = new Set();
+    for (const chunk of chunked([...new Set(ids)])) {
+        // SAFETY: the SELECT names one column, id.
+        const rows = db.prepare(`SELECT id FROM memories WHERE tenant_id = ? AND id IN (${chunk.map(() => '?').join(', ')})`).all(tenantId, ...chunk);
+        for (const row of rows)
+            owned.add(row.id);
+    }
+    return owned;
+}
+// savePhysicsState opens its own transaction and overwrites, so the first particle for a memory is inserted here instead.
+function insertNewParticles(db, rows) {
+    const stmt = db.prepare(`
+    INSERT INTO memory_physics (memory_id, position_blob, velocity_blob, mass, charge, temperature, last_simulation)
+    VALUES (?, ?, ?, ?, ?, ?, ?) ON CONFLICT(memory_id) DO NOTHING
+  `);
+    for (const { memoryId, particle: p } of rows) {
+        if (p)
+            stmt.run(memoryId, float32ToBuffer(p.position), float32ToBuffer(p.velocity), p.mass, p.charge, p.temperature, p.lastSimulation);
+    }
+}
+export function writeVectorsAt(db, write) {
+    return withWriteScope(db, 'write_vectors', () => {
+        const replaces = replacesIndex(embeddingIndexStateOn(db), write.model);
+        if (replaces && !write.replaceIndex)
+            return { written: 0, modelMismatch: true };
+        const owned = ownedIds(db, write.rows.map((r) => r.memoryId), write.tenantId);
+        const rows = write.rows.filter((r) => owned.has(r.memoryId) && r.vector.length > 0 && r.vector.every(Number.isFinite));
+        if (rows.length === 0)
+            return { written: 0, modelMismatch: false };
+        if (replaces)
+            db.exec('DELETE FROM memory_vectors; DELETE FROM memory_physics;');
+        const written = upsertVectors(db, rows.map((r) => [r.memoryId, r.vector]), write.model);
+        insertNewParticles(db, rows);
+        setMeta(db, EMBEDDING_MODEL_META_KEY, write.model);
+        return { written, modelMismatch: false };
+    });
+}
+//# sourceMappingURL=vector-writes.js.map

package/dist/store-port.d.ts

@@ -1,8 +1,9 @@
-import { type ApiKeyRecord } from './auth.js';
+import { type ApiKeyListRow, type ApiKeyRecord, type ListApiKeysOpts, type NewApiKey } from './auth.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 { JsonValue } from './json.js';
 import type { MemoryEntry } from './memory.js';
 import type { PhysicsParticle } from './physics.js';
 import { type PlanningFallacyEvidence } from './predictions/planning-fallacy.js';
@@ -48,6 +49,44 @@ export interface VectorReads {
     /** The particles of `ids` only; an empty list reads nothing. */
     physicsParticles(ids: readonly string[]): Promise<Map<string, PhysicsParticle>>;
 }
+/** One memory's vector, computed by the caller's embedding provider. */
+export interface VectorRowWrite {
+    readonly memoryId: string;
+    readonly vector: readonly number[];
+    /** Kept only when the memory has no particle yet, under `memoryId` whatever its own memoryId says. */
+    readonly particle?: PhysicsParticle;
+}
+export interface VectorWrite {
+    readonly tenantId: string;
+    /** The index identity the vectors were built by, `embeddingIndexIdentity(provider.id)`. */
+    readonly model: string;
+    /** Set only by embedAll's rebuild, so a write that read the index state before another process rebuilt it cannot drop that rebuild. */
+    readonly replaceIndex: boolean;
+    readonly rows: readonly VectorRowWrite[];
+}
+export interface VectorWriteResult {
+    readonly written: number;
+    /** True when another model built the index and `replaceIndex` is false; the store then keeps nothing and `written` is 0. */
+    readonly modelMismatch: boolean;
+}
+export interface VectorBackfillQuery {
+    readonly model: string;
+    /** Only ids above this one in byte order; unset starts at the first. */
+    readonly afterId?: string;
+    /** Clamped to 1..500; a non-integer rejects with RangeError `limit must be an integer`. */
+    readonly limit: number;
+    /** Every tenant when unset, since the backfill covers the whole store. */
+    readonly tenantId?: string;
+}
+/** The writes behind embed on write and the backfill: core computes each vector, the store only keeps it.
+ *  A store deletes a memory's vector and particle when the memory is deleted (hippo.db does it by trigger and foreign-key cascade). */
+export interface VectorWrites {
+    /** Memories of any kind with no vector stored under `query.model`, by id ascending in byte order. */
+    entriesWithoutVector(query: VectorBackfillQuery): Promise<MemoryEntry[]>;
+    /** In one transaction: refuses with `modelMismatch` if `replacesIndex` and not `replaceIndex`; else, when a row is writable (memory in `tenantId`, vector non-empty
+     *  and finite), drops every vector and particle if `replacesIndex`, keeps each writable row under `model` with its particle where none exists, sets `model`. No audit row. */
+    writeVectors(write: VectorWrite): Promise<VectorWriteResult>;
+}
 export interface KeyRevoke {
     readonly tenantId: string;
     readonly keyId: string;
@@ -63,11 +102,43 @@ export interface KeyAudit {
     /** 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>;
 }
+/** A key to insert and the actor and metadata of its auth_create row, whose tenant and target are the key's. Neither holds the plaintext. */
+export interface KeyMint {
+    readonly key: NewApiKey;
+    readonly actor: string;
+    readonly metadata: Readonly<Record<string, JsonValue>>;
+}
+export interface SelfKeyMint extends KeyMint {
+    readonly key: NewApiKey & {
+        readonly ownerSubject: string;
+        readonly expiresAt: string;
+    };
+    /** Live keys the owner may hold in the tenant once this one is in. */
+    readonly perSubject: number;
+}
+/** `listApiKeyRows`'s filters, always inside one tenant. */
+export interface KeyListQuery extends Omit<ListApiKeysOpts, 'tenantId'> {
+    readonly tenantId: string;
+}
+export interface KeyWrites {
+    /** Inserts the key and appends its auth_create row in one transaction; with either one failing, neither is written. A key id taken in any tenant
+     *  rejects, since keys are looked up by id alone. */
+    createApiKey(mint: KeyMint): Promise<void>;
+    /** One transaction, serialized per (tenant, owner) before the count (hippo.db BEGIN IMMEDIATE, Postgres pg_advisory_xact_lock on the pair): revoke at `key.createdAt`
+     *  the owner's oldest live keys in the key's tenant down to `perSubject - 1`, insert the key, append an auth_revoke row `{ replacedBy: <new key id> }` per revoked key,
+     *  then the auth_create row; resolves to the revoked ids. Live: unrevoked, expires_at null or Date.parse(expires_at) after createdAt (NaN counts as expired). */
+    createSelfApiKey(mint: SelfKeyMint): Promise<string[]>;
+    /** As `listApiKeyRows`: newest inserted first, each with its scope grants; `active` drops revoked rows and an expires_at not above now's toISOString. */
+    listApiKeys(query: KeyListQuery): Promise<ApiKeyListRow[]>;
+}
 /** 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;
+    readonly keyWrites: KeyWrites;
+    /** embedMemory and embedAll with a store need it and `vectors`. */
+    readonly vectorWrites: VectorWrites;
 }
 export type StoreGroup = 'base' | keyof StoreGroups;
 export declare function hasGroup(store: HippoStore, group: StoreGroup): boolean;

package/dist/store-port.js

@@ -1,5 +1,5 @@
 // The async seam the server reaches its store through, so an add-on can serve from a database other than hippo.db.
-import { readApiKeyRecord } from './auth.js';
+import { listApiKeyRows, readApiKeyRecord } from './auth.js';
 import { appendAuditEvent, listAuditEventsAfter } from './audit.js';
 import { closeHippoDb, openHippoDb, withWriteScope } from './db.js';
 import { StoreNotPortedError } from './db/sqlite-blocked.js';
@@ -10,11 +10,13 @@ import { planningFallacyEvidenceAt } from './predictions/planning-fallacy.js';
 import { writeRecallTrace } from './recall-trace.js';
 import { loadEntriesByIds, loadFreshRawMemories } from './store/entry-reads.js';
 import { auditHighIdAt, revokeKeyAt } from './store/key-audit.js';
+import { createKeyAt, createSelfKeyAt } from './store/key-writes.js';
 import { strengthenRetrievedInOwnTx } from './store/entry-writes.js';
 import { loadLatestHandoff } from './store/handoffs.js';
 import { updateStats } from './store/index-and-stats.js';
 import { loadRecallSearchEntries, loadVectorCandidateEntries } from './store/search-rows.js';
 import { listSessionEvents, loadActiveTaskSnapshot } from './store/sessions.js';
+import { entriesWithoutVectorAt, writeVectorsAt } from './store/vector-writes.js';
 import { recordTokenUse } from './token-ledger.js';
 export function hasGroup(store, group) {
     return group === 'base' || store[group] !== undefined;
@@ -98,9 +100,31 @@ export function sqliteStore(hippoRoot) {
             },
         },
         keyAudit: sqliteKeyAudit(hippoRoot),
+        keyWrites: sqliteKeyWrites(hippoRoot),
+        vectorWrites: {
+            async entriesWithoutVector(query) {
+                return onHandle(hippoRoot, (db) => entriesWithoutVectorAt(db, query));
+            },
+            async writeVectors(write) {
+                return onHandle(hippoRoot, (db) => writeVectorsAt(db, write));
+            },
+        },
         async close() { },
     };
 }
+function sqliteKeyWrites(hippoRoot) {
+    return {
+        async createApiKey(mint) {
+            onHandle(hippoRoot, (db) => createKeyAt(db, mint));
+        },
+        async createSelfApiKey(mint) {
+            return onHandle(hippoRoot, (db) => createSelfKeyAt(db, mint));
+        },
+        async listApiKeys(query) {
+            return onHandle(hippoRoot, (db) => listApiKeyRows(db, query));
+        },
+    };
+}
 function sqliteKeyAudit(hippoRoot) {
     return {
         async revokeApiKey(revoke) {

package/dist/version.d.ts

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export declare const PACKAGE_VERSION = "1.67.0";
+export declare const PACKAGE_VERSION = "1.68.0";
 /** The floor a store takes on its first expiring key: the first release with schema v53, set by hand in that release; scripts/check-expiring-keys-floor.mjs gates it. */
 export declare const EXPIRING_KEYS_MIN_BINARY = "1.64.0";
 /** The floor a store takes on its first session bind or owner snapshot: first release with v54; set by hand in that release. */

package/dist/version.js

@@ -16,7 +16,7 @@
  * an ESM `import` can resolve cleanly, and a hardcoded constant survives
  * any packager that drops .json files.
  */
-export const PACKAGE_VERSION = '1.67.0';
+export const PACKAGE_VERSION = '1.68.0';
 /** The floor a store takes on its first expiring key: the first release with schema v53, set by hand in that release; scripts/check-expiring-keys-floor.mjs gates it. */
 export const EXPIRING_KEYS_MIN_BINARY = '1.64.0';
 /** The floor a store takes on its first session bind or owner snapshot: first release with v54; set by hand in that release. */

package/extensions/openclaw-plugin/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
-  "version": "1.67.0",
+  "version": "1.68.0",
 
   "configSchema": {
     "type": "object",

package/extensions/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.67.0",
+  "version": "1.68.0",
   "type": "module",
   "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
   "main": "index.ts",

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
-  "version": "1.67.0",
+  "version": "1.68.0",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.67.0",
+  "version": "1.68.0",
   "description": "Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.",
   "mcpName": "io.github.kitfunso/hippo-memory",
   "type": "module",