hippo-memory 1.72.0 → 2.0.0

package/dist/db/request-stores.js

@@ -1,7 +1,7 @@
 // One store handle per store for each request (HTTP call, MCP tool call, scoped CLI command), opened lazily and closed with it.
 import * as path from 'node:path';
 import { connectWithFacts, getHippoDbPath } from './connect.js';
-import { currentDeadline, currentRequestId, requestScopes } from '../util/request-scope.js';
+import { currentDeadline, currentRequestId, currentSignal, requestScopes } from '../util/request-scope.js';
 // Handles a scope owns, so closeHippoDb leaves them open for the rest of the request.
 const scopedHandles = new WeakSet();
 // process.exit skips every finally, so one exit listener closes the handles of scopes still open.
@@ -24,6 +24,7 @@ export class RequestStores {
     // Taken from the scope this one opens inside, so the request's log lines keep their id.
     requestId = currentRequestId();
     deadline = currentDeadline();
+    signal = currentSignal();
     setupDoneFor;
     #failFastWhenBusy;
     #handles = new Map();

package/dist/db/vector-store.js

@@ -3,6 +3,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { withWriteScope } from './busy.js';
 import { errorCode, errorFields, log } from '../util/log.js';
+import { placeholders } from '../util/sql.js';
 /** Legacy whole-file index; imported once into `memory_vectors`, then kept beside the store as a renamed backup. */
 const LEGACY_EMBEDDINGS_FILE = 'embeddings.json';
 export const EMBEDDING_MODEL_META_KEY = 'embedding_model';
@@ -66,7 +67,7 @@ function eachStoredVector(db, ids, take) {
     const unique = [...new Set(ids)];
     for (let i = 0; i < unique.length; i += ID_CHUNK) {
         const chunk = unique.slice(i, i + ID_CHUNK);
-        read(db.prepare(`SELECT memory_id, vector FROM memory_vectors WHERE memory_id IN (${chunk.map(() => '?').join(', ')})`).all(...chunk));
+        read(db.prepare(`SELECT memory_id, vector FROM memory_vectors WHERE memory_id IN (${placeholders(chunk.length)})`).all(...chunk));
     }
 }
 /** Vectors for `ids`, or every stored vector when `ids` is omitted. */

package/dist/doctor.d.ts

@@ -1,3 +1,4 @@
+import { type SpoolFs } from './capture/compaction-spool.js';
 /** Outcome of one check. `fail` makes `hippo doctor` exit 1. */
 export type DoctorStatus = 'pass' | 'warn' | 'fail' | 'info';
 /** One check in a {@link DoctorReport}. */
@@ -24,6 +25,8 @@ export interface DoctorOpts {
     version: string;
     nodeVersion?: string;
     now?: Date;
+    /** Stands in for the fs the spool check reads; a test makes one call fail. */
+    spoolFs?: SpoolFs;
 }
 /** Minimum Node.js version hippo supports (package.json engines). */
 export declare const MIN_NODE = "22.16.0";

package/dist/doctor.js

@@ -105,16 +105,16 @@ function sleepCheck(lastSleep, now) {
         : { id: 'sleep', status: 'pass', detail: `last sleep ${days === 0 ? 'today' : `${days} day${days === 1 ? '' : 's'} ago`}` };
 }
 /** Spool counts in their own try, so a spool that cannot be read never hides the database counts. */
-function readSpool(store, now) {
+function readSpool(store, now, spoolFs) {
     try {
-        return { counts: spoolCounts(store, now, REPLAY_AFTER_MS), unread: '' };
+        return { counts: spoolCounts(store, now, REPLAY_AFTER_MS, spoolFs), unread: '' };
     }
     catch (err) {
         return { counts: { waiting: 0, stale: 0, bad: 0 }, unread: `; spool not read: ${errorMessage(err)}` };
     }
 }
 /** Compaction records the PostCompact hook left unfinished and spool files a replay has not finished, which `hippo sleep` replays. */
-function compactionsCheck(compactions, store, now) {
+function compactionsCheck(compactions, store, now, spoolFs) {
     if (!compactions.ok) {
         return compactions.message.includes('no such table')
             ? { id: 'compactions', status: 'info', detail: 'no compaction records yet (hippo creates them on the next write)' }
@@ -122,7 +122,7 @@ function compactionsCheck(compactions, store, now) {
     }
     const { total, summarised, started } = compactions.value;
     const stuck = summarised + started;
-    const { counts: spool, unread } = readSpool(store, now);
+    const { counts: spool, unread } = readSpool(store, now, spoolFs);
     const spooled = spool.waiting + spool.stale + spool.bad > 0;
     const recorded = `${total} compaction${total === 1 ? '' : 's'} recorded, none stuck`;
     if (stuck === 0 && !spooled && unread === '')
@@ -260,7 +260,7 @@ function tokensCheck(tokens) {
     };
 }
 /** Checks that read the store's database; a store that cannot be opened becomes one failed schema check. */
-function databaseChecks(store, now) {
+function databaseChecks(store, now, spoolFs) {
     let health;
     try {
         health = readStoreHealth(store, {
@@ -284,7 +284,7 @@ function databaseChecks(store, now) {
         tokensCheck(health.tokens),
         failuresCheck(health.failures, health.schemaVersion),
         sleepCheck(health.lastSleep, now),
-        compactionsCheck(health.compactions, store, now),
+        compactionsCheck(health.compactions, store, now, spoolFs),
     ];
 }
 // Each hook and what it does, so a partial install says what is missing.
@@ -334,7 +334,7 @@ export function runDoctor(opts) {
     const { store, check } = storeCheck(local, globalRoot, hasGlobal);
     checks.push(check);
     if (store !== null)
-        checks.push(...databaseChecks(store, now));
+        checks.push(...databaseChecks(store, now, opts.spoolFs));
     const holdoutRateBp = store === null ? 0 : loadConfig(store).pilot.holdoutRateBp;
     if (holdoutRateBp > 0) {
         checks.push({

package/dist/embeddings/local.js

@@ -44,8 +44,8 @@ export function createLocalEmbedder(transformers = INSTALLED_TRANSFORMERS) {
                 return Array.from(output.data);
             }
             catch (err) {
-                // The caller sees `[]` and names the memory; a failed load already warned once for its backoff window.
-                log.debug(`local embedding failed: ${errorMessage(err)}`);
+                // The caller sees `[]` and names the memory; the first failure per model is told, the repeats go to debug.
+                log.warnThenDebug(`local-embed:${model}`, `local embedding with ${model} failed: ${errorMessage(err)}`, errorFields(err));
                 return [];
             }
         },

package/dist/embeddings/provider.js

@@ -229,15 +229,6 @@ class ApiEmbeddingProvider {
         }
     }
 }
-function readEmbeddingsConfig(hippoRoot) {
-    try {
-        return loadConfig(hippoRoot).embeddings;
-    }
-    catch {
-        // An unreadable config falls back to provider defaults; loadConfig warns on a bad parse.
-        return {};
-    }
-}
 /** Validate a user-supplied API base URL: HTTPS only (or explicit localhost). */
 function validateBaseUrl(url, fallback) {
     const candidate = url?.trim();
@@ -260,7 +251,7 @@ function validateBaseUrl(url, fallback) {
 /** Build the active embedding provider from config (or an explicit override). A missing key never throws here (it surfaces via `isAvailable()`);
  * only an invalid config (e.g. insecure apiBaseUrl) throws, deliberately loud, so hot-path callers wrap it. */
 export function resolveEmbeddingProvider(hippoRoot, opts = {}) {
-    const cfg = readEmbeddingsConfig(hippoRoot);
+    const cfg = loadConfig(hippoRoot).embeddings;
     const requested = opts.provider ?? cfg.provider ?? 'local';
     // An explicit embeddings.enabled=false hard-disables embedding for BOTH local
     // and API providers — for API this prevents unwanted paid off-box calls.

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

@@ -0,0 +1,37 @@
+export { hasGroup, sqliteStore, type AmbientCandidateRequest, type ContextReads, type EntryRemoval, type EntryTarget, type EntryWrite, type EntryWrites, type HippoStore, type KeyAudit, type KeyListQuery, type KeyMint, type KeyRevoke, type KeyWrites, type LastRecall, type LastRecallWrites, type OutcomeWrite, type RawArchive, type RecallSearchArgs, type RecallWrites, type SelfKeyMint, type StoreGroup, type StoreGroups, type SupersedeWrite, type VectorReads, type VectorBackfillQuery, type VectorRowWrite, type VectorWrite, type VectorWriteResult, type VectorWrites, } from '../store/index.js';
+export { entryAfterOutcome } from '../core/memory.js';
+export { rejectionDigest } from '../store/rejection.js';
+export { RejectedValueError } from '../core/api-errors.js';
+export { ownScopeTouches } from '../core/recall-scope.js';
+export type { HippoDbContext } from '../api/types.js';
+export type { ApiKeyListItem, ApiKeyListRow, ApiKeyRecord, ListApiKeysOpts, NewApiKey } from '../store/auth.js';
+export type { KeysetPosition } from '../util/keyset.js';
+export type { AppendAuditOpts, AuditEvent, ListAuditAfterOpts } from '../store/audit.js';
+export type { ContinuityBlock } from '../api/recall-types.js';
+export type { ActiveGoals, GetActiveGoalsOpts, Goal, GoalRecallLogRow, RetrievalPolicy } from '../store/goals.js';
+export type { MemoryEntry } from '../core/memory.js';
+export type { ClassResolution, PlanningFallacyEvidence } from '../store/planning-fallacy-evidence.js';
+export type { PredictionBaserate } from '../store/predictions.js';
+export type { RecallTraceInput } from '../store/recall-trace.js';
+export type { StrengthenOptions } from '../store/entry-writes.js';
+export type { OriginFilter, RecallScopeFilter, VectorCandidateSpec } from '../store/search-rows.js';
+export type { ContinuityKey } from '../store/sessions.js';
+export type { SessionEvent, TaskSnapshot } from '../store/rows.js';
+export type { SessionHandoff } from '../core/handoff.js';
+export type { AmbientLoadResult, AmbientRecallRequest, ContextCandidateFilter, RecentOrigins } from '../store/candidates.js';
+export type { AmbientStoreFilter } from '../store/ambient.js';
+export type { AmbientTallies } from '../core/ambient.js';
+export type { TokenUse } from '../store/token-ledger.js';
+export type { EmbeddingIndexState } from '../store/vector-index.js';
+export type { PhysicsParticle } from '../core/physics.js';
+export { StoreBusyError } from '../store/port.js';
+export { decodeVector, EMBEDDING_MODEL_META_KEY, encodeVector, rankVectorRows, type VectorMatch, type VectorRow } from '../db/vector-store.js';
+export { bufferToFloat32, float32ToBuffer } from '../util/vector-codec.js';
+export { replacesIndex } from '../store/vector-index.js';
+export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from '../core/recall-scope.js';
+export { SECRET_TAGS } from '../util/secret-detect.js';
+export { tallyAmbientEntries } from '../core/ambient.js';
+export { ftsTermParts, rarestFtsQuery } from '../core/prompt-recall.js';
+export { OTHER_STORE_MARKER } from '../db/index.js';
+export { isSharedStore } from '../core/config.js';
+//# sourceMappingURL=store-kit.d.ts.map

package/dist/entry/store-kit.js

@@ -0,0 +1,25 @@
+// The hippo-memory/store-kit subpath: the contract for a second HippoStore (port types, row types, hippo.db's rule helpers),
+// so a store built on it applies hippo.db's rules with the same code.
+// An add-on serves from another database by passing serve() its own HippoStore.
+export { hasGroup, sqliteStore, } from '../store/index.js';
+// An add-on store's entry writes apply an outcome, guard tombstones and check reach exactly as hippo.db does.
+export { entryAfterOutcome } from '../core/memory.js';
+export { rejectionDigest } from '../store/rejection.js';
+export { RejectedValueError } from '../core/api-errors.js';
+export { ownScopeTouches } from '../core/recall-scope.js';
+export { StoreBusyError } from '../store/port.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 '../db/vector-store.js';
+export { bufferToFloat32, float32ToBuffer } from '../util/vector-codec.js';
+export { replacesIndex } from '../store/vector-index.js';
+// An add-on's ContextReads applies hippo.db's scope, secret, tally and rarest-term rules with the same code.
+export { passesScopeFilterForRecall, RECALL_DEFAULT_DENY_SCOPES } from '../core/recall-scope.js';
+export { SECRET_TAGS } from '../util/secret-detect.js';
+export { tallyAmbientEntries } from '../core/ambient.js';
+export { ftsTermParts, rarestFtsQuery } from '../core/prompt-recall.js';
+// store copy --db writes the marker into the other store's folder.
+export { OTHER_STORE_MARKER } from '../db/index.js';
+// An add-on that serves a team store checks the flag before it starts.
+export { isSharedStore } from '../core/config.js';
+//# sourceMappingURL=store-kit.js.map

package/dist/entry/testing.d.ts

@@ -0,0 +1,6 @@
+export { _resetAblationCacheForTests } from '../core/ablation.js';
+export { _resetSharedStoreCacheForTests } from '../core/config.js';
+export { _resetLossAversionRatioCacheForTests } from '../core/memory.js';
+export { _resetSessionRecallHistoryMcpForTests } from '../mcp/session-state.js';
+export { __resetSessionRecallHistoryHttp } from '../server/routes/recall.js';
+//# sourceMappingURL=testing.d.ts.map

package/dist/entry/testing.js

@@ -0,0 +1,7 @@
+// Test seams for add-ons and hippo's own suite. Not for production code; no semver guarantee beyond the major version.
+export { _resetAblationCacheForTests } from '../core/ablation.js';
+export { _resetSharedStoreCacheForTests } from '../core/config.js';
+export { _resetLossAversionRatioCacheForTests } from '../core/memory.js';
+export { _resetSessionRecallHistoryMcpForTests } from '../mcp/session-state.js';
+export { __resetSessionRecallHistoryHttp } from '../server/routes/recall.js';
+//# sourceMappingURL=testing.js.map

package/dist/eval/judgment.js

@@ -99,7 +99,7 @@ async function judge(content, opts) {
         data = await readCappedJson(res, JUDGE_MAX_REPLY_BYTES);
     }
     catch (err) {
-        log.debug(`judge: unreadable response: ${errorMessage(err)}`);
+        log.warnThenDebug('judge-unreadable', `judge: unreadable response: ${errorMessage(err)}`, errorFields(err));
         return null;
     }
     const durable = answerNamed(data, 'durable').noul;

package/dist/hooks/json-hooks.js

@@ -7,6 +7,7 @@ import { claudeConfigDir, codexHomeDir, homeDir } from '../util/agent-homes.js';
 import { isJsonString, readJsonFile, isJsonObjectLiteral } from '../util/json.js';
 import { escapeRegex } from '../util/escape.js';
 import { writeFileAtomic } from '../util/atomic-write.js';
+import { errorMessage, log } from '../util/log.js';
 /** The paths for `target` under the current home directory; reads and writes nothing. */
 export function resolveJsonHookPaths(target) {
     const home = homeDir();
@@ -366,8 +367,11 @@ export function uninstallJsonHooks(target) {
     try {
         settings = readJsonFile(settingsPath);
     }
-    catch {
-        // Never rewrite a settings file we cannot parse; report nothing uninstalled.
+    catch (err) {
+        // Never rewrite a settings file we cannot parse; a read failure (permissions, a directory) is the caller's to see.
+        if (!(err instanceof SyntaxError))
+            throw new Error(`could not read ${settingsPath}: ${errorMessage(err)}`, { cause: err });
+        log.warn(`${settingsPath} is not valid JSON, so no hippo hooks were removed from it: ${err.message}`);
         return false;
     }
     if (!isJsonObjectLiteral(settings) || !isJsonObjectLiteral(settings.hooks))

package/dist/importers/core.js

@@ -3,7 +3,7 @@
 import { DEFAULT_TENANT_ID } from '../util/env.js';
 import { createMemory, Layer } from '../core/memory.js';
 import { writeEntry } from '../store/entry-writes.js';
-import { loadAllEntries } from '../store/entry-reads.js';
+import { loadEntryTextKeys } from '../store/entry-reads.js';
 import { duplicateKey, storedTextKeys } from '../util/same-text.js';
 import { getGlobalRoot, initGlobal } from '../sharing/global-store.js';
 import { withRequestStoresSync } from '../db/request-stores.js';
@@ -58,7 +58,7 @@ function openImportTarget(options) {
     if (options.global) {
         initGlobal();
     }
-    const keys = storedTextKeys(loadAllEntries(targetRoot, options.global ? undefined : options.tenantId));
+    const keys = storedTextKeys(loadEntryTextKeys(targetRoot, options.global ? undefined : options.tenantId));
     return { targetRoot, keys };
 }
 function skipReason(chunk, keys) {
@@ -95,7 +95,7 @@ function createImportEntry(chunk, source, allTags, options, baseHalfLifeDays) {
 /** Writes the entry, or on a dry run only probes the guard; false when a rejected value refuses it. */
 function writeOrProbeImport(targetRoot, entry, options) {
     if (options.dryRun)
-        return !rejectionGuardRefuses(targetRoot, entry.tenantId ?? DEFAULT_TENANT_ID, entry.id, entry.content);
+        return !rejectionGuardRefuses(targetRoot, entry.tenant_id ?? DEFAULT_TENANT_ID, entry.id, entry.content);
     // A rejection refuses one chunk, not the whole import, so siblings still land.
     try {
         writeEntry(targetRoot, entry);

package/dist/importers/vault.d.ts

@@ -1,5 +1,5 @@
 import { type ImportResult, type ImportOptions } from './core.js';
 /** Import a markdown vault FOLDER as `kind='raw'` memories.
  *  NOT re-entrant: idempotency rests on the in-memory `existing` Map loaded once, so two concurrent runs over one vault can double-insert. */
-export declare function importVault(folderPath: string, options: ImportOptions): ImportResult;
+export declare function importVault(folderPath: string, options: ImportOptions): Promise<ImportResult>;
 //# sourceMappingURL=vault.d.ts.map

package/dist/importers/vault.js

@@ -8,7 +8,7 @@ import { remember, archiveRaw, isPrivateScope } from '../api/index.js';
 import { assertClientScope } from '../core/recall-scope.js';
 import { RejectedValueError } from '../core/api-errors.js';
 import { rejectionGuardRefuses } from '../store/rejected-values.js';
-import { withRequestStoresSync } from '../db/request-stores.js';
+import { runWithRequestStores } from '../db/request-stores.js';
 import { loadConfig } from '../core/config.js';
 import { vetSecrets } from '../util/secret-detect.js';
 import { errorMessage, log } from '../util/log.js';
@@ -18,7 +18,7 @@ import { isJsonString } from '../util/json.js';
 import { escapeLike } from '../util/escape.js';
 /** Import a markdown vault FOLDER as `kind='raw'` memories.
  *  NOT re-entrant: idempotency rests on the in-memory `existing` Map loaded once, so two concurrent runs over one vault can double-insert. */
-export function importVault(folderPath, options) {
+export async function importVault(folderPath, options) {
     const hippoRoot = options.hippoRoot;
     const identity = vaultIdentityOrThrow(options);
     if (options.global) {
@@ -34,7 +34,7 @@ export function importVault(folderPath, options) {
     }
     return syncVaultFolder(folderPath, options, identity);
 }
-function syncVaultFolder(folderPath, options, { vaultName, scope }) {
+async function syncVaultFolder(folderPath, options, { vaultName, scope }) {
     const hippoRoot = options.hippoRoot;
     const tenantId = options.tenantId ?? DEFAULT_TENANT_ID;
     const extraTags = options.extraTags ?? [];
@@ -54,15 +54,15 @@ function syncVaultFolder(folderPath, options, { vaultName, scope }) {
     const run = {
         ctx, folderPath, vaultName, scope, extraTags, dryRun, existing, seen, baseHalfLifeDays, tally,
     };
-    const importNotes = () => {
+    const importNotes = async () => {
         for (const relpath of relpaths)
-            importVaultNote(run, relpath);
+            await importVaultNote(run, relpath);
     };
     // A dry run probes the rejection guard once per changed note; one scope lets every probe share a handle.
     if (dryRun)
-        withRequestStoresSync(importNotes);
+        await runWithRequestStores(importNotes);
     else
-        importNotes();
+        await importNotes();
     // Deletion-sync: an artifactRef in the Map but not seen this run vanished from the source, so archive its raw row.
     // Per-file archiveRaw, no outer SAVEPOINT: there is no cross-file idempotency row to commit atomically.
     for (const [artifactRef, rows] of existing) {
@@ -71,7 +71,7 @@ function syncVaultFolder(folderPath, options, { vaultName, scope }) {
         for (const row of rows) {
             tally.archived++; // count even in dryRun so the preview reflects destructive deletes
             if (!dryRun)
-                archiveRaw(ctx, row.id, `source_deleted:${artifactRef}`);
+                await archiveRaw(ctx, row.id, `source_deleted:${artifactRef}`);
         }
     }
     const { total, imported, skipped, rejected, archived, redacted, entries } = tally;
@@ -120,7 +120,7 @@ function loadVaultRows(hippoRoot, tenantId, vaultName) {
     }
     return existing;
 }
-function importVaultNote(run, relpath) {
+async function importVaultNote(run, relpath) {
     const { tally } = run;
     tally.total++;
     const artifactRef = `vault:${run.vaultName}:${relpath}`;
@@ -137,7 +137,7 @@ function importVaultNote(run, relpath) {
     // Empty or frontmatter-only note: nothing storable, and the content was deleted at source, so archive prior rows (the old body must not stay searchable)
     // and skip the write. Safe because remember() is skipped, so there is no archive-then-throw hazard; the note stays in `seen` so deletion-sync skips it.
     if (body.trim().length < 3) {
-        archivePriors(run, priors, `emptied:${artifactRef}`);
+        await archivePriors(run, priors, `emptied:${artifactRef}`);
         tally.skipped++;
         return;
     }
@@ -147,13 +147,13 @@ function importVaultNote(run, relpath) {
         tally.skipped++;
         return;
     }
-    writeChangedNote(run, artifactRef, priors, body, tags);
+    await writeChangedNote(run, artifactRef, priors, body, tags);
 }
-function writeChangedNote(run, artifactRef, priors, body, tags) {
+async function writeChangedNote(run, artifactRef, priors, body, tags) {
     const { ctx, tally } = run;
     // Changed file: archive EVERY old raw row for this ref (>1 only after a concurrent double-insert), then append the new one; NEVER supersede.
     // archiveRaw commits before remember() runs, so no double-live row; a crash between them self-heals on the next import.
-    archivePriors(run, priors, `changed:${artifactRef}`);
+    await archivePriors(run, priors, `changed:${artifactRef}`);
     // remember() owns the write; the `echo` from createMemory only fills the ImportResult, with its id reconciled to the row that landed.
     const content = vetSecrets(body, tags, true).content;
     const echo = createMemory(content, {
@@ -165,7 +165,7 @@ function writeChangedNote(run, artifactRef, priors, body, tags) {
         tenantId: ctx.tenantId,
         baseHalfLifeDays: run.baseHalfLifeDays,
     });
-    if (!storeVaultNote(run, echo, content, tags, artifactRef)) {
+    if (!(await storeVaultNote(run, echo, content, tags, artifactRef))) {
         tally.rejected++;
         return;
     }
@@ -185,11 +185,11 @@ function readVaultNote(run, relpath) {
         return null;
     }
 }
-function archivePriors(run, priors, reason) {
+async function archivePriors(run, priors, reason) {
     for (const p of priors) {
         run.tally.archived++; // count the would-be archive even in dryRun (true preview)
         if (!run.dryRun)
-            archiveRaw(run.ctx, p.id, reason);
+            await archiveRaw(run.ctx, p.id, reason);
     }
 }
 function vaultNoteTags(run, hashTag, fm, body) {
@@ -221,14 +221,14 @@ function vaultEnvelopeUnchanged(priors, tags, scope) {
         }));
 }
 /** Returns false when the rejection guard refuses the note; any other error propagates. */
-function storeVaultNote(run, echo, content, tags, artifactRef) {
+async function storeVaultNote(run, echo, content, tags, artifactRef) {
     // A dry run writes nothing; it asks the guard remember() uses, so its `rejected` count matches what a real run would refuse.
     if (run.dryRun)
         return !rejectionGuardRefuses(run.ctx.hippoRoot, run.ctx.tenantId, echo.id, echo.content);
     try {
         // A rejected note must not stop the scan or the deletion sync. Its priors are archived by now, so a rerun meets
         // the same refusal and counts it again.
-        const result = remember(run.ctx, {
+        const result = await remember(run.ctx, {
             content,
             kind: 'raw',
             artifactRef,

package/dist/index.d.ts

@@ -20,7 +20,7 @@ export { initStore } from './store/open.js';
 export { writeEntry } from './store/entry-writes.js';
 export { loadAllEntries, readEntry } from './store/entry-reads.js';
 export { deleteEntry } from './store/delete-and-batch.js';
-export { loadSearchEntries, loadRecallSearchEntries } from './store/search-rows.js';
+export { loadSearchEntries, loadRecallEntries, type RecallSearchEntriesOptions } from './store/search-rows.js';
 export { loadIndex, rebuildIndex, loadSessionDecayContext, SessionDecayContext } from './store/index-and-stats.js';
 export { saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, type ContinuityKey, } from './store/sessions.js';
 export { listMemoryConflicts, replaceDetectedConflicts, resolveConflict } from './store/conflicts.js';
@@ -36,7 +36,7 @@ export { isEmbeddingAvailable, getEmbedding } from './embeddings/local.js';
 export { cosineSimilarity } from './store/embeddings/index.js';
 export { embedMemory, embedAll } from './search/embed-memories.js';
 export { loadEmbeddingIndex, saveEmbeddingIndex } from './store/vector-index.js';
-export { captureError, extractLessons, partitionLessons, deduplicateLesson, runWatched, fetchGitLog, } from './learn/autolearn.js';
+export { captureError, extractLessons, partitionLessons, deduplicateLesson, runWatched, type RunWatchedOptions, fetchGitLog, } from './learn/autolearn.js';
 export { getGlobalRoot, initGlobal, promoteToGlobal } from './sharing/global-store.js';
 export { searchBoth, searchBothHybrid, HybridSearchOptions } from './sharing/search-both.js';
 export { syncGlobalToLocal } from './sharing/global-sync.js';

package/dist/index.js

@@ -21,7 +21,7 @@ export { initStore } from './store/open.js';
 export { writeEntry } from './store/entry-writes.js';
 export { loadAllEntries, readEntry } from './store/entry-reads.js';
 export { deleteEntry } from './store/delete-and-batch.js';
-export { loadSearchEntries, loadRecallSearchEntries } from './store/search-rows.js';
+export { loadSearchEntries, loadRecallEntries } from './store/search-rows.js';
 export { loadIndex, rebuildIndex, loadSessionDecayContext } from './store/index-and-stats.js';
 export { saveActiveTaskSnapshot, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, SNAPSHOT_AMBIENT_MAX_AGE_MS, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, } from './store/sessions.js';
 export { listMemoryConflicts, replaceDetectedConflicts, resolveConflict } from './store/conflicts.js';

package/dist/learn/autolearn.d.ts

@@ -23,9 +23,13 @@ export declare class RunWatchedTimeoutError extends Error {
     readonly stderr: string;
     constructor(deadlineMs: number, stderr: string);
 }
-/** Run a command in a shell, streaming stderr live; never pass text the caller did not write.
+export interface RunWatchedOptions {
+    /** Join argv with spaces and run it as one shell command line; only for text the caller wrote itself. */
+    shell?: boolean;
+}
+/** Run argv[0] with the rest as its arguments and no shell, so `;`, `&` and `$()` reach it literally; stderr streams live.
  *  Returns: { exitCode, stderr } with only the last 64 KiB of stderr; rejects with RunWatchedTimeoutError past `deadlineMs`. */
-export declare function runWatched(command: string, deadlineMs?: number): Promise<{
+export declare function runWatched(argv: readonly string[], deadlineMs?: number, opts?: RunWatchedOptions): Promise<{
     exitCode: number;
     stderr: string;
 }>;

package/dist/learn/autolearn.js

@@ -1,6 +1,7 @@
 /** Auto-learn from errors and git history.
  *  Agents learn from failures without explicit hippo remember calls. */
 import { execFileSync, spawn } from 'child_process';
+import { spawnArgv } from '../util/spawn-argv.js';
 import { createMemory, Layer, DEFAULT_HALF_LIFE_DAYS } from '../core/memory.js';
 import { loadAllEntries } from '../store/entry-reads.js';
 import { textOverlap } from '../util/tokenize.js';
@@ -112,20 +113,21 @@ export class RunWatchedTimeoutError extends Error {
         this.name = 'RunWatchedTimeoutError';
     }
 }
-/** Run a command in a shell, streaming stderr live; never pass text the caller did not write.
+/** Run argv[0] with the rest as its arguments and no shell, so `;`, `&` and `$()` reach it literally; stderr streams live.
  *  Returns: { exitCode, stderr } with only the last 64 KiB of stderr; rejects with RunWatchedTimeoutError past `deadlineMs`. */
-export function runWatched(command, deadlineMs = RUN_WATCHED_DEADLINE_MS) {
+export function runWatched(argv, deadlineMs = RUN_WATCHED_DEADLINE_MS, opts = {}) {
     return new Promise((resolve, reject) => {
-        // Use shell: true so the command string is handled by the shell as-is
-        const child = spawn(command, { shell: true, stdio: ['inherit', 'inherit', 'pipe'], windowsHide: true });
+        const options = { stdio: ['inherit', 'inherit', 'pipe'], windowsHide: true };
+        const child = opts.shell ? spawn(argv.join(' '), { ...options, windowsHide: true, shell: true }) : spawnArgv(argv, options);
         let tail = Buffer.alloc(0);
-        child.stderr.on('data', (chunk) => {
+        child.stderr?.on('data', (chunk) => {
             tail = Buffer.concat([tail, chunk]);
             if (tail.length > STDERR_TAIL_BYTES)
                 tail = tail.subarray(tail.length - STDERR_TAIL_BYTES);
             process.stderr.write(chunk);
         });
-        // SHORTCUT: kills the shell only; on Windows a grandchild can outlive it. A process-tree kill is the upgrade path.
+        // SHORTCUT: kills the direct child only (the shell or cmd.exe when there is one); on Windows a grandchild can outlive it.
+        // A process-tree kill is the upgrade path.
         const timer = setTimeout(() => {
             child.kill('SIGKILL');
             reject(new RunWatchedTimeoutError(deadlineMs, tail.toString('utf8')));

package/dist/learn/extract.js

@@ -118,7 +118,7 @@ function buildExtractedEntry(fact, source, inheritedTags, baseHalfLifeDays) {
             scope: source.scope,
             // Without it createMemory stamps 'default', and extracted facts leave
             // the tenant of the episodic memory they were extracted from.
-            tenantId: source.tenantId,
+            tenantId: source.tenant_id,
             baseHalfLifeDays,
         }), origin_project: source.origin_project };
 }

package/dist/learn/invalidation.d.ts

@@ -1,3 +1,4 @@
+import { type HippoStore } from '../store/port.js';
 import { type MemoryEntry } from '../core/memory.js';
 export interface InvalidationTarget {
     from: string;
@@ -28,7 +29,7 @@ export declare function extractInvalidationTarget(message: string): Invalidation
 export declare function invalidateMatching(hippoRoot: string, target: InvalidationTarget, tenantId?: string, options?: InvalidationOptions): InvalidationResult;
 /** invalidateMatching for a batch: matches against `live`, the caller's list of the tenant's rows, and keeps it current.
  *  Each match is read again before it is weakened, so a row another writer changed since the list was read is never written back stale. */
-export declare function invalidateMatchingAmong(hippoRoot: string, live: MemoryEntry[], target: InvalidationTarget, tenantId?: string): InvalidationResult;
+export declare function invalidateMatchingAmong(store: HippoStore, live: MemoryEntry[], target: InvalidationTarget, tenantId?: string): Promise<InvalidationResult>;
 export interface ChurnRefs {
     paths: string[];
     symbols: string[];

package/dist/learn/invalidation.js

@@ -1,6 +1,7 @@
 import { addTagToEntries, writeEntriesTogether } from '../store/entry-writes.js';
 import { confirmedOutcomeTimes } from '../store/audit.js';
-import { loadAllEntries, loadEntriesByIds, loadEntriesMentioning, readEntry } from '../store/entry-reads.js';
+import { loadAllEntries, loadEntriesMentioning, readEntry } from '../store/entry-reads.js';
+import { requireGroup } from '../store/port.js';
 import { chunked } from '../util/chunked.js';
 import { CHURN_STALE_TAG } from '../core/memory.js';
 import { GitReadError, gitLsFilesAtHead, fetchChurnWindowLog, gitGrepPresence, resolveCommitBefore, packageScriptsAt, } from './churn-git.js';
@@ -57,13 +58,17 @@ export function invalidateMatching(hippoRoot, target, tenantId, options) {
 }
 /** invalidateMatching for a batch: matches against `live`, the caller's list of the tenant's rows, and keeps it current.
  *  Each match is read again before it is weakened, so a row another writer changed since the list was read is never written back stale. */
-export function invalidateMatchingAmong(hippoRoot, live, target, tenantId) {
+export async function invalidateMatchingAmong(store, live, target, tenantId) {
     const seen = weakenMatches(live, target, { dryRun: true }).result;
     const ids = [...seen.targets, ...seen.skippedPinned];
-    // loadEntriesByIds reads at most 500 ids a call.
-    const fresh = new Map(chunked(ids, 500).flatMap((chunk) => loadEntriesByIds(hippoRoot, chunk, tenantId)).map((entry) => [entry.id, entry]));
+    const fresh = new Map();
+    // The port reads at most 500 ids a call.
+    for (const chunk of chunked(ids, 500))
+        for (const entry of await store.entriesByIds(chunk, tenantId))
+            fresh.set(entry.id, entry);
     const { result, weakened } = weakenMatches(ids.flatMap((id) => fresh.get(id) ?? []), target);
-    writeEntriesTogether(hippoRoot, weakened);
+    if (weakened.length > 0)
+        await requireGroup(store, 'lessonWrites').writeTogether(weakened);
     const byId = new Map(weakened.map((entry) => [entry.id, entry]));
     for (let i = 0; i < live.length; i++)
         live[i] = byId.get(live[i].id) ?? live[i];

package/dist/mcp/memory-tools.d.ts

@@ -1,5 +1,5 @@
 import { type ToolCall } from './protocol.js';
 export declare function runRememberTool({ args, ctx, hippoRoot, config, tenantId }: ToolCall): Promise<string>;
 export declare function runOutcomeTool({ args, ctx, hippoRoot, tenantId }: ToolCall): Promise<string>;
-export declare function runLearnTool({ args, ctx, hippoRoot, tenantId }: ToolCall): string;
+export declare function runLearnTool({ args, ctx, hippoRoot, tenantId }: ToolCall): Promise<string>;
 //# sourceMappingURL=memory-tools.d.ts.map

package/dist/mcp/memory-tools.js

@@ -1,5 +1,5 @@
 // Write-side tool handlers: hippo_remember, hippo_outcome and hippo_learn.
-import { storeFor } from '../store/index.js';
+import { hasGroup } from '../store/index.js';
 import { startAutoSleepIfDue } from '../api/auto-sleep.js';
 import { remember as apiRemember, outcome as apiOutcome, learn as apiLearn, MCP_LEARN } from '../api/index.js';
 import { mcpActor } from './protocol.js';
@@ -14,7 +14,6 @@ export async function runRememberTool({ args, ctx, hippoRoot, config, tenantId }
     if (args.tag)
         tags.push(String(args.tag));
     // Route through api/index.ts so audit_log captures the caller identity like CLI/REST: the auth-resolved ctx.actor under HTTP-MCP, 'mcp' for stdio.
-    // The entry is re-read to surface the half-life used in the MCP response.
     const apiCtx = {
         hippoRoot,
         tenantId,
@@ -27,14 +26,12 @@ export async function runRememberTool({ args, ctx, hippoRoot, config, tenantId }
         personal: args.personal === true,
         project: ctx?.project,
     });
-    const [entry] = await storeFor(apiCtx).entriesByIds([result.id], tenantId);
     // Auto-sleep runs on hippo.db, so another store skips it.
-    const allowed = (ctx?.store === undefined || ctx.store.kind === 'sqlite') && ctx?.autoSleep !== false;
+    const allowed = (ctx?.store === undefined || hasGroup(ctx.store, 'localFiles')) && ctx?.autoSleep !== false;
     startAutoSleepIfDue(hippoRoot, tenantId, config.autoSleep, allowed, ctx?.autoSleepRunner);
-    const halfLife = entry?.half_life_days ?? config.defaultHalfLifeDays;
-    const tagStr = entry?.tags.join(', ') || tags.join(', ') || 'none';
+    const tagStr = result.tags.join(', ') || 'none';
     const warnings = (result.warnings ?? []).map((w) => `\nWarning: ${w}`).join('');
-    return `Remembered [${result.id}] (half-life: ${halfLife}d, tags: ${tagStr})${warnings}`;
+    return `Remembered [${result.id}] (half-life: ${result.halfLifeDays}d, tags: ${tagStr})${warnings}`;
 }
 export async function runOutcomeTool({ args, ctx, hippoRoot, tenantId }) {
     const good = Boolean(args.good);
@@ -53,10 +50,10 @@ export async function runOutcomeTool({ args, ctx, hippoRoot, tenantId }) {
     const { applied } = await apiOutcome(apiCtx, ids, good);
     return `Applied ${good ? 'positive' : 'negative'} outcome to ${applied} memories`;
 }
-export function runLearnTool({ args, ctx, hippoRoot, tenantId }) {
+export async function runLearnTool({ args, ctx, hippoRoot, tenantId }) {
     const days = Number(args.days) || 7;
     // process.cwd() is the server's repo, not a remote caller's, so api learn refuses all but stdio and a host admin (mcpActor fails closed).
-    const result = apiLearn({ hippoRoot, tenantId, actor: mcpActor(ctx), store: ctx?.store }, { repoPath: process.cwd(), days, profile: MCP_LEARN });
+    const result = await apiLearn({ hippoRoot, tenantId, actor: mcpActor(ctx), store: ctx?.store }, { repoPath: process.cwd(), days, profile: MCP_LEARN });
     if (result.status === 'not-a-repo')
         return 'No git history found.';
     if (result.status === 'no-commits')