hippo-memory 1.52.1 → 1.52.3

package/README.md

@@ -628,7 +628,7 @@ hippo watch "npm run build"
 | `hippo dormant [<query>]` | List faded memories sleep kept instead of deleting |
 | `hippo dormant restore <id>` | Bring a dormant memory back to active memory |
 | `hippo dormant forget <id>` | Delete a dormant memory permanently |
-| `hippo doctor [--json]` | Check the install: Node, store, schema, sleep, agent hooks; each problem names its fix |
+| `hippo doctor [--json]` | Check the install: Node, store, schema, sleep, agent hooks; each problem names its fix. It never changes `hippo.db`, though SQLite may leave empty `hippo.db-wal` and `hippo.db-shm` files beside it |
 | `hippo support-bundle [--out <file>] [--include-logs]` | Write a redacted JSON file for a support ticket: versions, doctor checks, config, store counts and log names, never memory text; `--include-logs` adds each log's last 200 lines, which can quote it |
 | `hippo tokens [--days n]` | Estimated tokens of memory text handed to agents, per surface, and what skipping unchanged hook blocks saved |
 | `hippo failures [--days n]` | Failed tool calls the capture-error hook saw, by outcome, and how many errors first happened in another session |
@@ -963,6 +963,12 @@ The interesting problems:
 - **MemPalace-style spatial organization.** Could spatial structure (wings/halls/rooms) improve hippo's semantic layer?
 - **AAAK-style compression for semantic memories.** Lossless token compression for context injection.
 
+## Open source and commercial
+
+Hippo is open core, and the line is drawn by who pays. Everything an individual developer or a self-hosted team needs is in this repository under MIT: the CLI, the MCP server, hooks, connectors, the dashboard, tenants, API keys, roles, per-key scope grants, the audit log and zero-touch memory. Code published here stays MIT and stays here.
+
+A commercial edition for larger companies ships as a separate package under a commercial licence from KITFUNSO LTD. It adds SSO (OIDC and SAML sign-in), SCIM, an org admin view, the pilot report and telemetry join, SIEM export of the audit log, offline licence keys, hosted SaaS, and support with an SLA. Pull requests for those features belong there, not here; see [CONTRIBUTING.md](CONTRIBUTING.md).
+
 ## License
 
 MIT

package/dist/api.js

@@ -8,7 +8,7 @@
  */
 import { createHash } from 'node:crypto';
 import { openHippoDb, closeHippoDb } from './db.js';
-import { writeEntry, writeEntryDbOnly, strengthenRetrieved, stampOriginProject, writeEntryMirrors, readEntry, deleteEntry, loadRecallSearchEntries, loadRecallSearchEntriesFromDb, pickRarestFtsQuery, loadEntriesByIds, loadChildrenOf, loadFreshRawMemories, loadSessionRawMemories, countSessionRawMemories, DEFAULT_SEARCH_CANDIDATE_LIMIT, removeEntryMirrors, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, loadLatestHandoff, listSessionEvents, SNAPSHOT_AMBIENT_MAX_AGE_MS, loadIndex, saveIndex, loadAllEntries, loadAmbientCandidates, updateStats, isInitialized, markSummaryDirtyInTx, auditRejectionRefusal, } from './store.js';
+import { writeEntry, writeEntryDbOnly, strengthenRetrieved, stampOriginProject, writeEntryMirrors, readEntry, deleteEntry, loadRecallSearchEntries, loadEntriesByIds, loadChildrenOf, loadFreshRawMemories, loadSessionRawMemories, countSessionRawMemories, DEFAULT_SEARCH_CANDIDATE_LIMIT, removeEntryMirrors, loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, loadLatestHandoff, listSessionEvents, SNAPSHOT_AMBIENT_MAX_AGE_MS, loadIndex, saveIndex, loadAllEntries, loadAmbientCandidates, updateStats, isInitialized, markSummaryDirtyInTx, auditRejectionRefusal, } from './store.js';
 import { RejectedValueError } from './rejection.js';
 import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
 import { listDormantRows, readDormantSnapshot, deleteDormantRow, hasDormantRow, } from './dormant.js';
@@ -133,14 +133,14 @@ export function ambientSecretAdmit(e, currentProjectName) {
         return false;
     return origin === currentProjectName;
 }
-// The pinned-only branch needs pins and recent-N candidates, not the corpus.
-function loadAmbientEntries(hippoRoot, tenantId, pinnedOnly, includeRecent, admit) {
+// The pinned-only branch needs pins and recent-N candidates, not the corpus; `recall` applies there only.
+function loadAmbientEntries(hippoRoot, tenantId, pinnedOnly, includeRecent, admit, recall) {
     if (!pinnedOnly)
-        return loadAllEntries(hippoRoot, tenantId).filter(admit);
+        return { entries: loadAllEntries(hippoRoot, tenantId).filter(admit) };
     // DF3's quality floor runs on the recent-N slice AFTER this load, so the load
     // counts by it too, or it stops short of a store whose newest rows are junk.
     const admitAmbient = (e) => admit(e) && (e.pinned || isContentWorthStoring(e.content));
-    return loadAmbientCandidates(hippoRoot, tenantId, includeRecent, admitAmbient);
+    return loadAmbientCandidates(hippoRoot, tenantId, includeRecent, admitAmbient, recall);
 }
 export function remember(ctx, opts) {
     const detection = opts.untrusted ? detectInstruction(opts.content) : { flagged: false, reason: null };
@@ -1491,6 +1491,7 @@ export function auditList(ctx, opts) {
         closeHippoDb(db);
     }
 }
+const finiteOr = (v, dflt, min) => Number.isFinite(v) && v >= min ? v : dflt;
 /**
  * Assemble a context bundle: recalled memories (pinned-only / strength-sorted
  * fallback / hybrid search) + active task snapshot + session handoff + recent
@@ -1540,13 +1541,24 @@ export async function getContext(ctx, opts = {}) {
     // secrets, so WHICH rows reach this predicate is what loadAmbientEntries cares
     // about below.
     const admit = (e) => !e.superseded_by && ambientAdmit(e);
-    // Tenant-scoped loads (v1.11.1 lesson: NEVER resolveTenantId({}) here).
-    let localEntries = hasLocal
-        ? loadAmbientEntries(ctx.hippoRoot, ctx.tenantId, pinnedOnly, includeRecent, admit)
-        : [];
-    let globalEntries = hasGlobal
-        ? loadAmbientEntries(globalRoot, ctx.tenantId, pinnedOnly, includeRecent, admit)
+    // Z1: decided before the ambient loads so the FTS candidate query below (pinned-only
+    // branch) can piggyback on that connection instead of opening its own.
+    const promptRecallPending = pinnedOnly && Boolean(opts.prompt?.trim()) && config.pinnedInject.promptRecall === true;
+    const promptRecallTerms = promptRecallPending && config.pinnedInject.enabled
+        ? Array.from(promptTokens(opts.prompt ?? ''))
         : [];
+    const recallRequest = promptRecallTerms.length > 0
+        ? { terms: promptRecallTerms, limit: Math.floor(finiteOr(config.pinnedInject.promptRecallCandidates, 100, 1)) }
+        : undefined;
+    // Tenant-scoped loads (v1.11.1 lesson: NEVER resolveTenantId({}) here).
+    const localLoad = hasLocal
+        ? loadAmbientEntries(ctx.hippoRoot, ctx.tenantId, pinnedOnly, includeRecent, admit, recallRequest)
+        : { entries: [] };
+    const globalLoad = hasGlobal
+        ? loadAmbientEntries(globalRoot, ctx.tenantId, pinnedOnly, includeRecent, admit, !isGlobalStoreRoot(ctx.hippoRoot) ? recallRequest : undefined)
+        : { entries: [] };
+    let localEntries = localLoad.entries;
+    let globalEntries = globalLoad.entries;
     // Computed below, after markRetrieved runs, so avgStrength reflects the
     // post-retrieval strengths rather than a stale pre-mutation snapshot.
     let ambientState;
@@ -1588,8 +1600,6 @@ export async function getContext(ctx, opts = {}) {
             limit: 5,
         }).filter((e) => passesScopeFilterForRecall(rowScope(e), undefined))
         : [];
-    const promptRecallPending = pinnedOnly && Boolean(opts.prompt?.trim())
-        && loadConfig(ctx.hippoRoot).pinnedInject.promptRecall === true;
     if (!promptRecallPending &&
         localEntries.length === 0 &&
         globalEntries.length === 0 &&
@@ -1659,49 +1669,21 @@ export async function getContext(ctx, opts = {}) {
         // the safe direction and is not worth extra bookkeeping to recover.
         const recentBudget = Math.max(0, effBudget - pinnedReserve);
         // Z1: gate the backfill on the prompt instead of recency (docs/plans/2026-09-26-z1-prompt-recall.md).
-        const promptRecallOn = Boolean(opts.prompt?.trim()) && pinnedCfg.pinnedInject.promptRecall === true;
+        const promptRecallOn = promptRecallPending;
         if (promptRecallOn) {
             const rawMetric = pinnedCfg.pinnedInject.promptRecallMetric;
             const metric = rawMetric === 'cosine' ? 'cosine' : 'jaccard';
-            // Config values come from JSON with no runtime type check; Number.isFinite also rejects a string there.
-            const finiteOr = (v, dflt, min) => Number.isFinite(v) && v >= min ? v : dflt;
             const gate = {
                 metric,
                 threshold: finiteOr(pinnedCfg.pinnedInject.promptRecallThreshold, 0.04, 0),
                 minShared: finiteOr(pinnedCfg.pinnedInject.promptRecallMinShared, 2, 0),
                 maxItems: finiteOr(pinnedCfg.pinnedInject.promptRecallMaxItems, 5, 1),
             };
-            const candidateLimit = Math.floor(finiteOr(pinnedCfg.pinnedInject.promptRecallCandidates, 100, 1));
             const p = promptTokens(opts.prompt ?? '');
             if (p.size > 0) {
-                const promptTermList = Array.from(p);
-                // One open connection per store instead of loadRecallSearchEntries's own
-                // initStore+open/close per call: store is already initialized (hasLocal/hasGlobal).
-                let localCandidates = [];
-                if (hasLocal) {
-                    const localDb = openHippoDb(ctx.hippoRoot);
-                    try {
-                        const ftsQuery = pickRarestFtsQuery(localDb, promptTermList);
-                        // An empty query would load the oldest rows, not matches.
-                        if (ftsQuery)
-                            localCandidates = loadRecallSearchEntriesFromDb(localDb, ftsQuery, candidateLimit, ctx.tenantId, undefined, 'exact', false);
-                    }
-                    finally {
-                        closeHippoDb(localDb);
-                    }
-                }
-                let globalCandidates = [];
-                if (hasGlobal && !isGlobalStoreRoot(ctx.hippoRoot)) {
-                    const globalDb = openHippoDb(globalRoot);
-                    try {
-                        const ftsQuery = pickRarestFtsQuery(globalDb, promptTermList);
-                        if (ftsQuery)
-                            globalCandidates = loadRecallSearchEntriesFromDb(globalDb, ftsQuery, candidateLimit, ctx.tenantId, undefined, 'exact', false);
-                    }
-                    finally {
-                        closeHippoDb(globalDb);
-                    }
-                }
+                // Candidates came off the ambient load's own connection (recallRequest above), not a fresh open.
+                const localCandidates = localLoad.recall ?? [];
+                const globalCandidates = globalLoad.recall ?? [];
                 const seenCandidateIds = new Set();
                 const candidateItems = [];
                 // Local wins the id collision (a global row synced into the local store).

package/dist/capture-error.js

@@ -2,7 +2,7 @@
 // stored, because error memories decay slowly and would crowd out real lessons; what is stored stays `observed`
 // until outcome feedback confirms it. Every failure, stored or not, goes to the failure log (ROADMAP CD13).
 import { createMemory } from './memory.js';
-import { writeEntry, loadAllEntries } from './store.js';
+import { writeEntry, loadContentsWithTag } from './store.js';
 import { loadConfig } from './config.js';
 import { closeHippoDb, openHippoDb } from './db.js';
 import { recordFailure } from './failure-log.js';
@@ -94,7 +94,7 @@ function logFailure(hippoRoot, tenantId, payload, lesson, outcome) {
 }
 function storeLesson(hippoRoot, tenantId, text) {
     const sig = failureSignature(text);
-    const repeat = loadAllEntries(hippoRoot, tenantId).some((e) => e.tags.includes('auto-captured') && failureSignature(e.content) === sig);
+    const repeat = loadContentsWithTag(hippoRoot, tenantId, 'auto-captured').some((content) => failureSignature(content) === sig);
     if (repeat)
         return 'duplicate';
     const entry = createMemory(text, {

package/dist/cli.js

@@ -6472,17 +6472,28 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
             },
         };
         process.stdout.write(JSON.stringify(payload));
-        if (finalStatic) {
-            withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
-                tenantId: ctx.tenantId, sessionId: currentSessionId, surface, event: 'inject',
-                items: staticItems.length, tokens: estimateTokens(finalStatic), hash: blockHash(finalStatic),
-            }));
-        }
-        if (recallBlock) {
-            withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
-                tenantId: ctx.tenantId, sessionId: currentSessionId, surface: 'hook_recall', event: 'inject',
-                items: recallItems.length, tokens: estimateTokens(recallBlock), hash: blockHash(recallBlock),
-            }));
+        if (finalStatic || recallBlock) {
+            // One connection for both rows; each insert in its own try so one failing doesn't skip the other.
+            withLedgerDb(hippoRoot, (db) => {
+                if (finalStatic) {
+                    try {
+                        recordTokenUse(db, {
+                            tenantId: ctx.tenantId, sessionId: currentSessionId, surface, event: 'inject',
+                            items: staticItems.length, tokens: estimateTokens(finalStatic), hash: blockHash(finalStatic),
+                        });
+                    }
+                    catch { /* best effort; see withLedgerDb doc comment */ }
+                }
+                if (recallBlock) {
+                    try {
+                        recordTokenUse(db, {
+                            tenantId: ctx.tenantId, sessionId: currentSessionId, surface: 'hook_recall', event: 'inject',
+                            items: recallItems.length, tokens: estimateTokens(recallBlock), hash: blockHash(recallBlock),
+                        });
+                    }
+                    catch { /* best effort; see withLedgerDb doc comment */ }
+                }
+            });
         }
     }
     else {

package/dist/db.js

@@ -2819,9 +2819,10 @@ function backfillFtsIndex(db) {
     // SAFETY: this get() result's shape matches the single aliased `c` column
     // named in the SELECT above.
     const memCount = db.prepare(`SELECT COUNT(*) AS c FROM memories`).get()?.c ?? 0;
-    // SAFETY: this get() result's shape matches the single aliased `c` column
-    // named in the SELECT above.
-    const ftsCount = db.prepare(`SELECT COUNT(*) AS c FROM memories_fts`).get()?.c ?? 0;
+    // SAFETY: this get() result's shape matches the single aliased `c` column named in the SELECT above.
+    // memories_fts_docsize is FTS5's cheaper one-row-per-document shadow table; fall back for a foreign-built index.
+    const ftsTable = tableExists(db, 'memories_fts_docsize') ? 'memories_fts_docsize' : 'memories_fts';
+    const ftsCount = db.prepare(`SELECT COUNT(*) AS c FROM ${ftsTable}`).get()?.c ?? 0;
     if (memCount === ftsCount)
         return;
     db.exec(`

package/dist/half-life-migration.js

@@ -20,7 +20,7 @@
  * (7 days when never recorded) to the configured `defaultHalfLifeDays`.
  */
 import { deriveHalfLife } from './memory.js';
-import { initStore, selectAllEntries, HALF_LIFE_BASE_META_KEY } from './store.js';
+import { openStore, selectAllEntries, HALF_LIFE_BASE_META_KEY } from './store.js';
 import { openHippoDb, closeHippoDb, getMeta, setMeta } from './db.js';
 import { appendAuditEvent } from './audit.js';
 /** The base every store used before the base was recorded. */
@@ -65,8 +65,7 @@ function readBase(db) {
 export function migrateDefaultHalfLife(hippoRoot, to, opts = {}) {
     const dryRun = opts.dryRun ?? false;
     const noop = (from) => ({ from, to, rescaled: 0, kept: 0, dryRun, halfLives: new Map() });
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // Plan, write, audit and record the base under one write lock, so a concurrent write or sleep cannot interleave.
         if (!dryRun)

package/dist/reject-flow.js

@@ -11,11 +11,11 @@
  * raw-archive.ts and dormant.ts. Nothing imports FROM this file except
  * cli.ts and api.ts, so it introduces no cycle.
  */
-import { openHippoDb, closeHippoDb } from './db.js';
+import { closeHippoDb } from './db.js';
 import { appendAuditEvent } from './audit.js';
 import { archiveRawMemory } from './raw-archive.js';
 import { purgeDormantByDigest } from './dormant.js';
-import { initStore, deleteEntryCore, purgeMirrorBestEffort, } from './store.js';
+import { openStore, deleteEntryCore, purgeMirrorBestEffort, } from './store.js';
 import { rejectionDigest, normalizeValueForRejection, insertRejectedValue, deleteRejectedValue, listRejectedValues, } from './rejection.js';
 /**
  * `hippo reject` / `api.reject` core flow. ONE connection, one transaction:
@@ -46,8 +46,7 @@ export function rejectValue(opts) {
         // and pollute the listing.
         throw new Error('reject --value requires non-empty content.');
     }
-    initStore(opts.hippoRoot);
-    const db = openHippoDb(opts.hippoRoot);
+    const db = openStore(opts.hippoRoot);
     try {
         let content;
         if (opts.memoryId !== undefined) {
@@ -170,8 +169,7 @@ export function unrejectValue(hippoRoot, tenantId, digestOrPrefix, actor) {
     if (digestOrPrefix.trim().length === 0) {
         return { status: 'not_found' };
     }
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const all = listRejectedValues(db, tenantId);
         const matches = all.filter((r) => r.digest.startsWith(digestOrPrefix));
@@ -201,8 +199,7 @@ export function unrejectValue(hippoRoot, tenantId, digestOrPrefix, actor) {
 }
 /** `hippo rejections` / `api.listRejections` — list tombstones for a tenant. */
 export function listRejectionsForTenant(hippoRoot, tenantId) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         return listRejectedValues(db, tenantId);
     }

package/dist/secret-detect.d.ts

@@ -38,6 +38,6 @@ export declare function detectSecret(entry: {
  * CS1 pre-compact snapshot fields — can scrub it in place instead.
  */
 export declare function redactSecrets(text: string): string;
-/** Stricter redaction for text that leaves the machine: no co-occurrence guard, plus Bearer headers and JWTs. */
+/** Stricter redaction for text that leaves the machine: no co-occurrence guard, plus Bearer and Basic auth headers and JWTs. */
 export declare function redactSecretsStrict(text: string): string;
 //# sourceMappingURL=secret-detect.d.ts.map

package/dist/secret-detect.js

@@ -28,6 +28,13 @@ const SECRET_PATTERNS = [
     { name: 'slack-token', re: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/ },
     { name: 'stripe-key', re: /\b[sr]k_(?:live|test)_[A-Za-z0-9]{16,}\b/ },
     { name: 'google-api-key', re: /\bAIza[0-9A-Za-z_-]{35}\b/ },
+    // hk_ is hippo's own API key (src/auth.ts); npm, Hugging Face, GitLab and Slack webhook shapes follow gitleaks' rules.
+    { name: 'hippo-api-key', re: /\bhk_[a-z2-7]{24}\.[a-z2-7]{32}\b/ },
+    { name: 'npm-token', re: /\bnpm_[A-Za-z0-9]{36}\b/ },
+    { name: 'huggingface-token', re: /\bhf_[A-Za-z]{34}\b/ },
+    { name: 'gitlab-token', re: /\bglpat-[\w-]{20,}/ },
+    { name: 'google-oauth-token', re: /\bya29\.[\w-]{20,}/ },
+    { name: 'slack-webhook', re: /\bhooks\.slack\.com\/(?:services|workflows|triggers)\/[A-Za-z0-9+/]{43,56}/ },
     { name: 'private-key-block', re: /-----BEGIN [A-Z ]*PRIVATE KEY-----/ },
     // sk-... (OpenAI/Anthropic style) and sk_<vendor>_... shapes. Both require
     // a key-ish noun somewhere in the content (co-occurrence guard) so prose
@@ -51,6 +58,7 @@ const CO_OCCURRENCE_GUARDED = new Set(['sk-style-key', 'sk-underscore-key']);
 // redactSecretsStrict-only: too noisy for whole-entry memory scanning, worth hiding once text leaves the machine.
 const STRICT_ONLY_PATTERNS = [
     /\bbearer\s+[A-Za-z0-9._~+/-]{16,}=*/gi,
+    /\bauthorization["']?\s*[:=]\s*["']?basic\s+[A-Za-z0-9+/]{8,}={0,2}/gi,
     /\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]*/g,
 ];
 /**
@@ -82,7 +90,7 @@ export function detectSecret(entry) {
 export function redactSecrets(text) {
     return redactText(text, false);
 }
-/** Stricter redaction for text that leaves the machine: no co-occurrence guard, plus Bearer headers and JWTs. */
+/** Stricter redaction for text that leaves the machine: no co-occurrence guard, plus Bearer and Basic auth headers and JWTs. */
 export function redactSecretsStrict(text) {
     return redactText(text, true);
 }

package/dist/store.d.ts

@@ -109,6 +109,8 @@ export declare function assertNonEmpty<T>(arr: readonly T[], name: string): void
 export declare function getHippoRoot(cwd?: string, opts?: ResolveProjectIdentityOpts): string;
 export declare function isInitialized(hippoRoot: string): boolean;
 export declare function initStore(hippoRoot: string): void;
+/** One open connection with init done on it, for callers who used to pay for `initStore` + a second `openHippoDb`. */
+export declare function openStore(hippoRoot: string): DatabaseSyncLike;
 /** `meta` key holding the default half-life base a store's memories are on (src/half-life-migration.ts). */
 export declare const HALF_LIFE_BASE_META_KEY = "default_half_life_base";
 /**
@@ -411,7 +413,16 @@ export declare function batchWriteAndDelete(hippoRoot: string, toWrite: MemoryEn
 export declare function loadAllEntries(hippoRoot: string, tenantId?: string): MemoryEntry[];
 /** Every memory row on an open connection, so a caller can read inside its own transaction. */
 export declare function selectAllEntries(db: DatabaseSyncLike, tenantId?: string): MemoryEntry[];
-export declare function loadAmbientCandidates(hippoRoot: string, tenantId: string, recentNeeded: number, admit: (e: MemoryEntry) => boolean): MemoryEntry[];
+export declare function loadContentsWithTag(hippoRoot: string, tenantId: string, tag: string): string[];
+export interface AmbientRecallRequest {
+    terms: string[];
+    limit: number;
+}
+export interface AmbientLoadResult {
+    entries: MemoryEntry[];
+    recall?: MemoryEntry[];
+}
+export declare function loadAmbientCandidates(hippoRoot: string, tenantId: string, recentNeeded: number, admit: (e: MemoryEntry) => boolean, recall?: AmbientRecallRequest): AmbientLoadResult;
 /**
  * Load likely search candidates directly from SQLite.
  * Uses FTS5 when available, falls back to LIKE matching, then full-store fallback.

package/dist/store.js

@@ -114,6 +114,10 @@ export function isInitialized(hippoRoot) {
     return fs.existsSync(path.join(hippoRoot, 'hippo.db'));
 }
 export function initStore(hippoRoot) {
+    closeHippoDb(openStore(hippoRoot));
+}
+/** One open connection with init done on it, for callers who used to pay for `initStore` + a second `openHippoDb`. */
+export function openStore(hippoRoot) {
     ensureMirrorDirectories(hippoRoot);
     const db = openHippoDb(hippoRoot);
     try {
@@ -122,9 +126,16 @@ export function initStore(hippoRoot) {
             syncMirrorFiles(hippoRoot, db);
         }
         recordHalfLifeBaseForNewStore(db);
+        return db;
     }
-    finally {
-        closeHippoDb(db);
+    catch (error) {
+        try {
+            closeHippoDb(db);
+        }
+        catch {
+            // Best effort only; surface the original init error.
+        }
+        throw error;
     }
 }
 /** `meta` key holding the default half-life base a store's memories are on (src/half-life-migration.ts). */
@@ -1112,8 +1123,7 @@ function syncMirrorFiles(hippoRoot, db) {
 }
 /** Load the derived index from SQLite. Read-only: index.json is only ever written by `rebuildIndex`. */
 export function loadIndex(hippoRoot) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         return buildIndexFromDb(db);
     }
@@ -1132,8 +1142,7 @@ export function loadIndex(hippoRoot) {
  * is left untouched; only `rebuildIndex` writes it.
  */
 export function saveIndex(hippoRoot, index) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN');
         try {
@@ -1205,10 +1214,9 @@ function stampOriginProjectForImport(hippoRoot, entry) {
     };
 }
 export function writeEntry(hippoRoot, entry, opts) {
-    initStore(hippoRoot);
-    const stamped = stampOriginProject(hippoRoot, entry);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
+        const stamped = stampOriginProject(hippoRoot, entry);
         writeEntryDbOnly(db, stamped, opts);
         opts?.afterCommit?.();
         writeEntryMirrors(hippoRoot, stamped);
@@ -1287,8 +1295,7 @@ export function writeEntryMirrors(hippoRoot, entry) {
  * legacy single-tenant callers and the writeEntry/readEntry round-trip.
  */
 export function readEntry(hippoRoot, id, tenantId) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
@@ -1311,8 +1318,7 @@ export function loadEntriesByIds(hippoRoot, ids, tenantId) {
     if (ids.length === 0)
         return [];
     const capped = ids.slice(0, 500);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const placeholders = capped.map(() => '?').join(',');
         // T2: no ORDER BY meant row order followed SQLite's IN(...) scan order
@@ -1384,8 +1390,7 @@ export function strengthenRetrieved(hippoRoot, ids, tenantId) {
 export function loadSessionRawMemories(hippoRoot, sessionId, tenantId, cap) {
     if (!sessionId)
         return [];
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const params = [];
         let sql = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE kind = 'raw' AND source_session_id = ? AND superseded_by IS NULL`;
@@ -1430,8 +1435,7 @@ export function loadSessionRawMemories(hippoRoot, sessionId, tenantId, cap) {
 export function countSessionRawMemories(hippoRoot, sessionId, tenantId, scope) {
     if (!sessionId)
         return 0;
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const params = [];
         let sql = `SELECT COUNT(*) AS c FROM memories WHERE kind = 'raw' AND source_session_id = ? AND superseded_by IS NULL`;
@@ -1484,8 +1488,7 @@ export function loadFreshRawMemories(hippoRoot, count, tenantId, sessionId) {
     if (count <= 0)
         return [];
     const capped = Math.min(count, 200);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const params = [];
         let sql = `SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE kind = 'raw' AND superseded_by IS NULL`;
@@ -1518,8 +1521,7 @@ export function loadFreshRawMemories(hippoRoot, count, tenantId, sessionId) {
  * Used by `drillDown` (Task 3).
  */
 export function loadChildrenOf(hippoRoot, parentId, tenantId) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: both branches select exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
@@ -1587,8 +1589,7 @@ export function deleteEntryCore(db, id, opts) {
  * existing caller.
  */
 export function deleteEntry(hippoRoot, id, opts) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const result = deleteEntryCore(db, id, opts);
         if (!result)
@@ -1622,8 +1623,7 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
     const dormantMoves = opts?.dormant ?? [];
     if (toWrite.length === 0 && toDeleteIds.length === 0 && dormantMoves.length === 0)
         return [];
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // BEGIN IMMEDIATE (codex delta-review P2): the AT1 tombstone probes below
         // READ before the first write. Under a deferred BEGIN, that read pins a
@@ -1789,8 +1789,7 @@ export function batchWriteAndDelete(hippoRoot, toWrite, toDeleteIds, opts) {
  * paths that surface results to a user MUST pass a resolved tenant.
  */
 export function loadAllEntries(hippoRoot, tenantId) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         return selectAllEntries(db, tenantId);
     }
@@ -1807,15 +1806,26 @@ export function selectAllEntries(db, tenantId) {
         : db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories ORDER BY created ASC, id ASC`).all();
     return rows.map(rowToEntry);
 }
+// Content of every tenant row tagged `tag`, without reading the rest of the store.
+// `instr` is a substring prefilter over the raw JSON; `includes` below re-checks exactly.
+export function loadContentsWithTag(hippoRoot, tenantId, tag) {
+    const db = openStore(hippoRoot);
+    try {
+        /** SAFETY: rows' shape matches the two columns named in the SELECT below. */
+        const rows = db.prepare(`SELECT content, tags_json FROM memories WHERE tenant_id = ? AND instr(tags_json, ?) > 0`).all(tenantId, JSON.stringify(tag));
+        return rows.filter((r) => parseJsonArray(r.tags_json).includes(tag)).map((r) => r.content);
+    }
+    finally {
+        closeHippoDb(db);
+    }
+}
 // The pins plus the `recentNeeded` newest rows that pass `admit`, for ambient
-// injection. One connection: opening one costs ~5.8ms on a warm 1896-row store,
-// so a second handle loses more than the narrower scan saves.
-export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit) {
-    initStore(hippoRoot);
+// injection. One connection; `recall` piggybacks the Z1 FTS query on it too.
+export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit, recall) {
     // A SQL LIMIT takes an integer; the Array.slice this replaced truncated one,
     // and include_recent is any non-negative finite number at the HTTP edge.
     const needed = Math.trunc(recentNeeded);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: every `where` below starts from MEMORY_SELECT_COLUMNS' table.
         const run = (where, params) => db.prepare(`SELECT ${MEMORY_SELECT_COLUMNS} FROM memories WHERE ${where}`).all(...params).map(rowToEntry);
@@ -1843,10 +1853,17 @@ export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit)
         }
         // loadAllEntries' order: rankedPinned's comparator can tie and Array.sort
         // is stable, so input order is load-bearing downstream.
-        return [...byId.values()].sort((a, b) => {
+        const entries = [...byId.values()].sort((a, b) => {
             const byCreated = a.created.localeCompare(b.created);
             return byCreated !== 0 ? byCreated : a.id.localeCompare(b.id);
         });
+        if (!recall)
+            return { entries };
+        const ftsQuery = pickRarestFtsQuery(db, recall.terms);
+        const recallEntries = ftsQuery
+            ? loadRecallSearchEntriesFromDb(db, ftsQuery, recall.limit, tenantId, undefined, 'exact', false)
+            : [];
+        return { entries, recall: recallEntries };
     }
     finally {
         closeHippoDb(db);
@@ -1860,8 +1877,7 @@ export function loadAmbientCandidates(hippoRoot, tenantId, recentNeeded, admit)
  * by tenant_id. Cross-tenant memories never surface. Omitted = no filter.
  */
 export function loadSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         return loadSearchRows(db, query, limit, tenantId).map(rowToEntry);
     }
@@ -1894,8 +1910,7 @@ export function loadSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDI
  * undefined as "no tenant filter" for legacy callers.
  */
 export function loadRecallSearchEntries(hippoRoot, query, limit = DEFAULT_SEARCH_CANDIDATE_LIMIT, tenantId, requestedScope, explicitScopeMode = 'exact', includeSuperseded = true) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         return loadRecallSearchEntriesFromDb(db, query, limit, tenantId, requestedScope, explicitScopeMode, includeSuperseded);
     }
@@ -1941,8 +1956,7 @@ export function pickRarestFtsQuery(db, terms, maxTerms = RAREST_TERM_COUNT) {
  * Rebuild mirrors from SQLite, importing any legacy markdown files not already present.
  */
 export function rebuildIndex(hippoRoot) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: rows' shape matches the single `id` column selected above.
         const existingIds = new Set(db.prepare(`SELECT id FROM memories`).all().map((row) => row.id));
@@ -1993,8 +2007,7 @@ export function rebuildIndex(hippoRoot) {
     }
 }
 export function updateStats(hippoRoot, delta) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // One atomic statement per counter, and only for counters the caller
         // named: the read-modify-write this replaces both lost increments to a
@@ -2021,8 +2034,7 @@ export function updateStats(hippoRoot, delta) {
     }
 }
 export function loadStats(hippoRoot) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         return buildStatsFromDb(db);
     }
@@ -2031,8 +2043,7 @@ export function loadStats(hippoRoot) {
     }
 }
 export function appendConsolidationRun(hippoRoot, run) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.prepare(`INSERT INTO consolidation_runs(timestamp, decayed, merged, removed) VALUES (?, ?, ?, ?)`).run(run.timestamp, run.decayed, run.merged, run.removed);
         pruneConsolidationRuns(db, 50);
@@ -2044,8 +2055,7 @@ export function appendConsolidationRun(hippoRoot, run) {
 }
 /** Rows a tenant created since the last sleep (runs are host-wide), looking back at most 24 hours. */
 export function countCreatedSinceLastSleep(hippoRoot, tenantId, now = new Date()) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const dayAgo = new Date(now.getTime() - 86_400_000).toISOString();
         const row = db.prepare(`SELECT COUNT(*) AS n FROM memories WHERE tenant_id = ?
@@ -2061,8 +2071,7 @@ export function countCreatedSinceLastSleep(hippoRoot, tenantId, now = new Date()
  * Uses consolidation_runs timestamps to compute session intervals.
  */
 export function loadSessionDecayContext(hippoRoot) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // Get recent consolidation timestamps (last 20)
         // SAFETY: rows' shape matches the single `timestamp` column above.
@@ -2089,8 +2098,7 @@ export function loadSessionDecayContext(hippoRoot) {
  * Increment the sleep counter. Called after each consolidation run.
  */
 export function incrementSleepCount(hippoRoot) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const current = Number(getMeta(db, 'sleep_count', '0')) || 0;
         setMeta(db, 'sleep_count', String(current + 1));
@@ -2127,8 +2135,7 @@ export function assertTenantId(fnName, value) {
 }
 export function saveActiveTaskSnapshot(hippoRoot, tenantId, snapshot) {
     assertTenantId('saveActiveTaskSnapshot', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     const now = new Date().toISOString();
     try {
         db.exec('BEGIN');
@@ -2167,8 +2174,7 @@ export function saveActiveTaskSnapshot(hippoRoot, tenantId, snapshot) {
 }
 export function loadActiveTaskSnapshot(hippoRoot, tenantId) {
     assertTenantId('loadActiveTaskSnapshot', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: row's shape matches the ten columns named in the SELECT above.
         const row = db.prepare(`
@@ -2243,8 +2249,7 @@ export function loadFreshActiveTaskSnapshot(hippoRoot, tenantId, opts = {}) {
 }
 export function clearActiveTaskSnapshot(hippoRoot, tenantId, clearedStatus = 'cleared') {
     assertTenantId('clearActiveTaskSnapshot', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     const now = new Date().toISOString();
     try {
         // SAFETY: active's shape matches the single `id` column selected above.
@@ -2272,8 +2277,7 @@ export function clearActiveTaskSnapshot(hippoRoot, tenantId, clearedStatus = 'cl
  */
 export function closeTaskSnapshotsForSession(hippoRoot, tenantId, sessionId, status = 'session-ended') {
     assertTenantId('closeTaskSnapshotsForSession', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     const now = new Date().toISOString();
     try {
         const result = db.prepare(`UPDATE task_snapshots SET status = ?, updated_at = ? WHERE status = 'active' AND tenant_id = ? AND session_id = ?`).run(status, now, tenantId, sessionId);
@@ -2285,8 +2289,7 @@ export function closeTaskSnapshotsForSession(hippoRoot, tenantId, sessionId, sta
 }
 export function appendSessionEvent(hippoRoot, tenantId, event) {
     assertTenantId('appendSessionEvent', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     const now = new Date().toISOString();
     // v1.2: scope is wired through. Default-deny in api.recall + cmdRecall
     // continuity reads applies to slack:private:* and 'unknown:legacy' rows.
@@ -2326,8 +2329,7 @@ export function appendSessionEvent(hippoRoot, tenantId, event) {
 }
 export function listSessionEvents(hippoRoot, tenantId, options = {}) {
     assertTenantId('listSessionEvents', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const clauses = ['tenant_id = ?'];
         const params = [tenantId];
@@ -2363,8 +2365,7 @@ export function listSessionEvents(hippoRoot, tenantId, options = {}) {
  */
 export function findPromotableSessions(hippoRoot, tenantId, sinceMs) {
     assertTenantId('findPromotableSessions', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: rows' shape matches the single `session_id` column selected
         // above.
@@ -2384,8 +2385,7 @@ export function findPromotableSessions(hippoRoot, tenantId, sinceMs) {
  */
 export function traceExistsForSession(hippoRoot, tenantId, session_id) {
     assertTenantId('traceExistsForSession', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const row = db.prepare(`
       SELECT 1 FROM memories
@@ -2399,8 +2399,7 @@ export function traceExistsForSession(hippoRoot, tenantId, session_id) {
     }
 }
 export function listMemoryConflicts(hippoRoot, status = 'open', tenantId) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // v0.28 — '*' is a sentinel meaning "no status filter, return all rows".
         // Pre-v0.28 callers (cli/mcp/dashboard) always passed 'open' or default,
@@ -2458,8 +2457,7 @@ export function listMemoryConflicts(hippoRoot, status = 'open', tenantId) {
     }
 }
 export function replaceDetectedConflicts(hippoRoot, detected, detectedAt = new Date().toISOString()) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN');
         // Tenant guard (E2): a conflict is meaningful only within one tenant.
@@ -2574,8 +2572,7 @@ export function replaceDetectedConflicts(hippoRoot, detected, detectedAt = new D
  * Returns the resolved conflict, or null if not found.
  */
 export function resolveConflict(hippoRoot, conflictId, keepId, forgetLoser = false, tenantId, opts) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     // When tenantId is set, the conflict lookup requires BOTH members in-tenant
     // and every memories mutation carries AND tenant_id = ?. A cross-tenant probe
     // then returns null, indistinguishable from a bad id. Omitted tenantId =
@@ -2798,8 +2795,7 @@ const HANDOFF_COLUMNS = 'id, session_id, repo_root, task_id, summary, next_actio
  */
 export function saveSessionHandoff(hippoRoot, tenantId, handoff) {
     assertTenantId('saveSessionHandoff', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     const now = new Date().toISOString();
     // v1.2: scope is wired through. Read-side default-deny in api.recall +
     // cmdRecall continuity excludes slack:private:* and 'unknown:legacy'.
@@ -2827,8 +2823,7 @@ export function saveSessionHandoff(hippoRoot, tenantId, handoff) {
 /** Load the most recent handoff, optionally filtered by session ID. */
 export function loadLatestHandoff(hippoRoot, tenantId, sessionId, opts = {}) {
     assertTenantId('loadLatestHandoff', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const conditions = ['tenant_id = ?'];
         const params = [tenantId];
@@ -2872,8 +2867,7 @@ export function loadLatestHandoff(hippoRoot, tenantId, sessionId, opts = {}) {
  */
 export function loadHandoffById(hippoRoot, tenantId, id) {
     assertTenantId('loadHandoffById', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: row's shape matches HANDOFF_COLUMNS.
         const row = db.prepare(`
@@ -2890,8 +2884,7 @@ export function loadHandoffById(hippoRoot, tenantId, id) {
 /** Stamp the outcome on a session's newest handoff, only if it has none yet. Returns rows changed. */
 export function stampHandoffOutcome(hippoRoot, tenantId, sessionId, outcome) {
     assertTenantId('stampHandoffOutcome', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const result = db.prepare(`
       UPDATE session_handoffs SET outcome = ?
@@ -3059,8 +3052,7 @@ export function createCard(hippoRoot, tenantId, input) {
     if (input.budget !== undefined && !(Number.isSafeInteger(input.budget) && input.budget > 0)) {
         throw new Error(`Invalid budget: ${input.budget} (expected a positive integer)`);
     }
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const dependsOn = [...new Set(input.dependsOn ?? [])];
         let id = '';
@@ -3112,8 +3104,7 @@ export function createCard(hippoRoot, tenantId, input) {
 /** Returns the card row for id, or null if it does not exist under this tenant. */
 export function loadCard(hippoRoot, tenantId, id) {
     assertTenantId('loadCard', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         return loadCardRow(db, tenantId, id);
     }
@@ -3124,8 +3115,7 @@ export function loadCard(hippoRoot, tenantId, id) {
 /** Lists cards for this tenant, optionally filtered to one status, newest-updated first. */
 export function listCards(hippoRoot, tenantId, opts = {}) {
     assertTenantId('listCards', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const conditions = ['tenant_id = ?'];
         const params = [tenantId];
@@ -3146,8 +3136,7 @@ export function listCards(hippoRoot, tenantId, opts = {}) {
 /** Returns this card's parent and child ids from card_deps. */
 export function loadCardDeps(hippoRoot, tenantId, id) {
     assertTenantId('loadCardDeps', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: rows' shape matches the single `parent` column named in the SELECT below.
         const parents = db.prepare(`SELECT parent FROM card_deps WHERE tenant_id = ? AND child = ?`).all(tenantId, id).map((r) => r.parent);
@@ -3162,8 +3151,7 @@ export function loadCardDeps(hippoRoot, tenantId, id) {
 /** Returns this card's run history, most recent first. */
 export function loadCardRuns(hippoRoot, tenantId, id) {
     assertTenantId('loadCardRuns', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: rows' shape matches CardRunRow.
         const rows = db.prepare(`
@@ -3179,8 +3167,7 @@ export function loadCardRuns(hippoRoot, tenantId, id) {
 /** Returns this card's comments, most recent first. */
 export function loadCardComments(hippoRoot, tenantId, id) {
     assertTenantId('loadCardComments', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: rows' shape matches CardCommentRow.
         const rows = db.prepare(`
@@ -3196,8 +3183,7 @@ export function loadCardComments(hippoRoot, tenantId, id) {
 /** Read side of the card <-> handoff round trip: the newest handoff filed against this card. */
 export function loadLatestHandoffForCard(hippoRoot, tenantId, cardId) {
     assertTenantId('loadLatestHandoffForCard', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: row's shape matches HANDOFF_COLUMNS.
         const row = db.prepare(`
@@ -3216,8 +3202,7 @@ export function claimCard(hippoRoot, tenantId, id, runtime, sessionId) {
     if (runtime.trim() === '') {
         throw new Error('runtime must not be empty');
     }
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN IMMEDIATE');
         let runId = 0;
@@ -3259,8 +3244,7 @@ export function claimCard(hippoRoot, tenantId, id, runtime, sessionId) {
 export function heartbeatCard(hippoRoot, tenantId, id, runId) {
     assertTenantId('heartbeatCard', tenantId);
     assertRunId(runId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN IMMEDIATE');
         try {
@@ -3298,8 +3282,7 @@ export function blockCard(hippoRoot, tenantId, id, reason, runId) {
     }
     if (runId !== undefined)
         assertRunId(runId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN IMMEDIATE');
         try {
@@ -3336,8 +3319,7 @@ export function reviewCard(hippoRoot, tenantId, id, runId) {
     assertTenantId('reviewCard', tenantId);
     if (runId !== undefined)
         assertRunId(runId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN IMMEDIATE');
         try {
@@ -3373,8 +3355,7 @@ export function completeCard(hippoRoot, tenantId, id, outcome, runId) {
     }
     if (runId !== undefined)
         assertRunId(runId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN IMMEDIATE');
         let promotedChildren = [];
@@ -3430,8 +3411,7 @@ export function completeCard(hippoRoot, tenantId, id, outcome, runId) {
 /** Returns to ready every running card of the tenant whose lease has expired or is missing: clears its assignee, closes its live run as 'reclaimed' and leaves its handoffs alone, all in one write transaction. Returns the reclaimed card ids in id order. */
 export function reclaimExpiredCards(hippoRoot, tenantId) {
     assertTenantId('reclaimExpiredCards', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('BEGIN IMMEDIATE');
         try {
@@ -3468,8 +3448,7 @@ export function addCardComment(hippoRoot, tenantId, cardId, author, body) {
     if (body.trim() === '') {
         throw new Error('body must not be empty');
     }
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         return insertCardComment(db, tenantId, cardId, author, body);
     }
@@ -3496,8 +3475,7 @@ export function addCardComment(hippoRoot, tenantId, cardId, author, body) {
  */
 export function loadDirtySummaries(hippoRoot, tenantId) {
     assertTenantId('loadDirtySummaries', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
@@ -3566,8 +3544,7 @@ export function markSummaryDirtyInTx(db, summaryId, tenantId, actor) {
  */
 export function markSummaryDirty(hippoRoot, summaryId, tenantId, actor = 'cli') {
     assertTenantId('markSummaryDirty', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // v0.30 / E5: widened dag_level=2 -> IN (2, 3). RETURNING dag_level reads
         // actual level in same round trip.
@@ -3614,8 +3591,7 @@ export function markSummaryDirty(hippoRoot, summaryId, tenantId, actor = 'cli')
  * tenant-scoped via summary.tenantId.
  */
 export function loadAllL2Summaries(hippoRoot) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
@@ -3644,8 +3620,7 @@ export function loadAllL2Summaries(hippoRoot) {
  * HIPPO_DAG_REBUILD_CAP takes most-recently-changed summaries first.
  */
 export function loadAllDirtySummaries(hippoRoot) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
@@ -3671,8 +3646,7 @@ export function loadAllDirtySummaries(hippoRoot) {
  */
 export function loadChildrenOfSummary(hippoRoot, summaryId, tenantId) {
     assertTenantId('loadChildrenOfSummary', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // SAFETY: this query selects exactly MEMORY_SELECT_COLUMNS, matching
         // MemoryRow's field set.
@@ -3705,8 +3679,7 @@ export function loadChildrenOfSummary(hippoRoot, summaryId, tenantId) {
  */
 export function applyRebuildResult(hippoRoot, summary, patch) {
     assertTenantId('applyRebuildResult', summary.tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         db.exec('SAVEPOINT rebuild_summary');
         try {
@@ -3853,8 +3826,7 @@ export function applyRebuildResult(hippoRoot, summary, patch) {
  */
 export function clearSummaryDirtyAfterBuild(hippoRoot, summaryId, tenantId, actor = 'cli', source = 'buildDag-clean') {
     assertTenantId('clearSummaryDirtyAfterBuild', tenantId);
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         // v0.30 / E5: widened dag_level=2 -> IN (2, 3). RETURNING dag_level reads
         // actual level so audit metadata stays accurate without an extra SELECT.

package/dist/support-bundle.js

@@ -1,7 +1,8 @@
-/** `hippo support-bundle`: one redacted JSON snapshot for a support ticket. Read-only; never touches memory content. */
+/** `hippo support-bundle`: one redacted JSON snapshot for a support ticket. Read-only (SQLite may leave empty -wal and -shm files); never touches memory content. */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+import { pathToFileURL } from 'url';
 import { findHippoStoreDir, isGlobalStoreRoot, realpathOrResolve } from './project-identity.js';
 import { getGlobalRoot } from './shared.js';
 import { isInitialized } from './store.js';
@@ -189,18 +190,11 @@ function nativeRealPathKey(p) {
         return null;
     }
 }
-// Longest first: where one home form nests in another (a test home under the real one), swap the longer.
-function collectHomeForms(home, probes) {
-    const forms = new Set();
-    const add = (s) => { if (s.length >= 3)
-        forms.add(s); };
+function collectHomeAliases(home, probes) {
+    const aliases = new Set();
     for (const base of [home, realpathOrResolve(home), os.homedir(), realpathOrResolve(os.homedir())]) {
-        add(base);
-        add(path.resolve(base));
-        if (process.platform === 'win32') {
-            add(base.replace(/\\/g, '/'));
-            add(path.resolve(base).replace(/\\/g, '/'));
-        }
+        aliases.add(base);
+        aliases.add(path.resolve(base));
     }
     // The alias (e.g. a short-name temp root) can sit above the probe itself, so walk ancestors and
     // compare native realpaths rather than checking each probe alone.
@@ -209,34 +203,56 @@ function collectHomeForms(home, probes) {
         let dir = path.resolve(probe);
         for (;;) {
             const key = nativeRealPathKey(dir);
-            if (key !== null && homeKeys.has(key)) {
-                add(dir);
-                if (process.platform === 'win32')
-                    add(dir.replace(/\\/g, '/'));
-            }
+            if (key !== null && homeKeys.has(key))
+                aliases.add(dir);
             const parent = path.dirname(dir);
             if (parent === dir)
                 break;
             dir = parent;
         }
     }
-    const seen = new Set();
-    const deduped = [];
-    for (const f of [...forms].sort((a, b) => b.length - a.length)) {
-        const key = process.platform === 'win32' ? f.toLowerCase() : f;
-        if (seen.has(key))
-            continue;
-        seen.add(key);
-        deduped.push(f);
-    }
-    return deduped;
+    return aliases;
+}
+// Node's own encoding, so it matches file URLs and ESM stack frames; a drive path's URL gains a leading slash.
+function fileUrlPath(p) {
+    const pathname = pathToFileURL(p).pathname;
+    return /^\/[A-Za-z]:/.test(pathname) ? pathname.slice(1) : pathname;
+}
+// A home turns up as a path, as a file URL's percent-encoded path, and as a Claude Code project folder name.
+const HOME_SPELLINGS = [
+    (p) => p,
+    fileUrlPath,
+    (p) => p.replace(/[^A-Za-z0-9]/g, '-'),
+];
+// A Windows separator can be written \, / or JSON-escaped (\\ in a log line quoting JSON), so any of them matches.
+function spellingPattern(spelling) {
+    if (process.platform !== 'win32')
+        return escapeRegExp(spelling);
+    return spelling.split(/[\\/]+/).map(escapeRegExp).join('(?:\\\\+|/)');
 }
-function replaceHomeForms(text, forms) {
-    if (forms.length === 0)
-        return text;
-    // Stop only before another name character: "<home> now" and "<home>." swap, a longer user name ("<home>ty") does not.
-    const re = new RegExp(`(?:${forms.map(escapeRegExp).join('|')})(?![\\p{L}\\p{N}_])`, process.platform === 'win32' ? 'giu' : 'gu');
-    return text.replace(re, '~');
+/** One pattern for every alias of the home in every spelling, or null when none is long enough to swap safely. */
+function buildHomePattern(home, probes) {
+    const spellings = new Set();
+    for (const alias of collectHomeAliases(home, probes)) {
+        for (const spell of HOME_SPELLINGS) {
+            const s = spell(alias);
+            if (s.length >= 3)
+                spellings.add(s);
+        }
+    }
+    // Longest first: where one home nests in another (a test home under the real one), swap the longer.
+    const patterns = new Map();
+    for (const s of [...spellings].sort((a, b) => b.length - a.length)) {
+        const pattern = spellingPattern(s);
+        const key = process.platform === 'win32' ? pattern.toLowerCase() : pattern;
+        if (!patterns.has(key))
+            patterns.set(key, pattern);
+    }
+    if (patterns.size === 0)
+        return null;
+    // Whole names only: "<home> now" and "<home>." swap; "<home>ty", or "web-app" for a home of /app, do not.
+    const alternatives = [...patterns.values()].join('|');
+    return new RegExp(`(?<![\\p{L}\\p{N}_])(?:${alternatives})(?![\\p{L}\\p{N}_])`, process.platform === 'win32' ? 'giu' : 'gu');
 }
 const URL_RE = /\b[a-z][a-z0-9+.-]*:\/\/[^\s"'<>]+/gi;
 function redactUrlsInString(text) {
@@ -255,37 +271,40 @@ function redactUrlsInString(text) {
         }
     });
 }
-function redactString(text, homeForms) {
-    return replaceHomeForms(redactSecretsStrict(redactUrlsInString(text)), homeForms);
+function redactString(text, homePattern) {
+    const scrubbed = redactSecretsStrict(redactUrlsInString(text));
+    return homePattern === null ? scrubbed : scrubbed.replace(homePattern, '~');
 }
-function redactStrings(value, homeForms) {
+function redactStrings(value, homePattern) {
     if (isJsonString(value))
-        return redactString(value, homeForms);
+        return redactString(value, homePattern);
     if (Array.isArray(value))
-        return value.map((v) => redactStrings(v, homeForms));
+        return value.map((v) => redactStrings(v, homePattern));
     if (isJsonObject(value)) {
         const out = {};
         for (const [k, v] of Object.entries(value))
-            out[k] = redactStrings(v, homeForms);
+            out[k] = redactStrings(v, homePattern);
         return out;
     }
     return value;
 }
 /** Read-only: builds one redacted support-ticket snapshot. Never reads a memory content column. */
 export function buildSupportBundle(opts) {
+    // Before doctor: its read-only open leaves an empty -wal that the store's file list would then report.
+    const stores = buildStores(opts);
     const bundle = {
         format: 'hippo-support-bundle/1',
         createdAt: opts.now.toISOString(),
         hippo: opts.version,
         runtime: buildRuntime(),
         doctor: JSON.parse(JSON.stringify(runDoctor(opts))),
-        stores: buildStores(opts),
+        stores,
         env: listSetEnvNames(),
         logs: buildLogsSection(opts),
     };
     // Store paths found from the working folder arrive resolved; the global root arrives as HIPPO_HOME was typed, and log lines
     // often quote the temp folder, which usually sits under the home.
-    const redacted = redactStrings(bundle, collectHomeForms(opts.home, [getGlobalRoot(), os.tmpdir()]));
+    const redacted = redactStrings(bundle, buildHomePattern(opts.home, [getGlobalRoot(), os.tmpdir()]));
     // SAFETY: the value built above is always a JsonObject; redactStrings preserves object shape.
     return redacted;
 }

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.52.1";
+export declare const PACKAGE_VERSION = "1.52.3";
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export declare function compareSemver(a: string, b: string): number;
 //# sourceMappingURL=version.d.ts.map

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.52.1';
+export const PACKAGE_VERSION = '1.52.3';
 /** Compares plain x.y.z versions, positive if a > b; tags throw so the rollback guard never misfires silently. */
 export function compareSemver(a, b) {
     const parse = (v) => {

package/dist/working-memory.js

@@ -5,8 +5,8 @@
  * importance-ranked, and automatically evicted when the buffer
  * exceeds WM_MAX_ENTRIES per scope.
  */
-import { openHippoDb, closeHippoDb } from './db.js';
-import { initStore } from './store.js';
+import { closeHippoDb } from './db.js';
+import { openStore } from './store.js';
 export const WM_MAX_ENTRIES = 20;
 function rowToItem(row) {
     let metadata = {};
@@ -38,8 +38,7 @@ function rowToItem(row) {
  * Returns the new row ID.
  */
 export function wmPush(hippoRoot, opts) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const now = new Date().toISOString();
         const importance = opts.importance ?? 0;
@@ -89,8 +88,7 @@ export function wmPush(hippoRoot, opts) {
  * Read working memory entries, sorted by importance DESC.
  */
 export function wmRead(hippoRoot, opts) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const clauses = [];
         const params = [];
@@ -124,8 +122,7 @@ export function wmRead(hippoRoot, opts) {
  * Clear (delete) working memory entries. Returns the count deleted.
  */
 export function wmClear(hippoRoot, opts) {
-    initStore(hippoRoot);
-    const db = openHippoDb(hippoRoot);
+    const db = openStore(hippoRoot);
     try {
         const clauses = [];
         const params = [];

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

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Biologically-inspired memory for AI agents. Decay by default, retrieval strengthening, sleep consolidation.",
-  "version": "1.52.1",
+  "version": "1.52.3",
 
   "configSchema": {
     "type": "object",

package/extensions/openclaw-plugin/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.52.1",
+  "version": "1.52.3",
   "type": "module",
   "description": "Hippo Memory plugin for OpenClaw - biologically-inspired agent memory",
   "main": "index.ts",

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "hippo-memory",
   "name": "Hippo Memory",
   "description": "Biologically-inspired memory for AI agents. Decay by default, retrieval strengthening, sleep consolidation.",
-  "version": "1.52.1",
+  "version": "1.52.3",
   "configSchema": {
     "type": "object",
     "additionalProperties": false,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hippo-memory",
-  "version": "1.52.1",
+  "version": "1.52.3",
   "description": "Biologically-inspired memory for AI agents. Zero runtime deps, SQLite, MCP server, and an opt-in hosted TypeSafe Jev reranker. Decay, retrieval strengthening, consolidation.",
   "mcpName": "io.github.kitfunso/hippo-memory",
   "type": "module",