hippo-memory 1.71.0 → 1.72.0

package/dist/embeddings/transformers.js

@@ -0,0 +1,89 @@
+// The optional Transformers.js package, and a bounded load of a model from it, shared by the local embedder and the cross-encoder.
+import { MINUTE_MS } from '../util/time.js';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import { errorCode, errorMessage } from '../util/log.js';
+const _require = createRequire(import.meta.url);
+// Importing both loads two onnxruntime-node builds whose finalizers can double-free on exit, so one is picked:
+// the maintained package hippo ships, with Xenova only as a fallback a user installed.
+const TRANSFORMERS_PACKAGES = ['@huggingface/transformers', '@xenova/transformers'];
+/** The installed package to import, or null when neither is installed. */
+export function resolveTransformersPackage() {
+    for (const name of TRANSFORMERS_PACKAGES) {
+        const url = entryUrl(name);
+        if (url)
+            return { name, url };
+    }
+    return null;
+}
+function entryUrl(name) {
+    try {
+        return import.meta.resolve(name);
+    }
+    catch {
+        // import.meta.resolve is missing under some module runners (vitest's included), so the require-based resolve stands in there.
+        try {
+            return pathToFileURL(_require.resolve(name)).href;
+        }
+        catch {
+            return null; // not installed; the caller tries the next package
+        }
+    }
+}
+/** The package's module namespace, typed by the parts the caller reads; null when neither package is installed. */
+export async function importTransformers() {
+    const pkg = resolveTransformersPackage();
+    if (!pkg)
+        return null;
+    try {
+        return { name: pkg.name, mod: await import(/* @vite-ignore */ pkg.url) };
+    }
+    catch (err) {
+        // A Node error's code (ERR_MODULE_NOT_FOUND and the like) says more than its message alone.
+        const code = errorCode(err);
+        throw new Error(`transformers import failed (${pkg.name}): ${code ? `${code} ` : ''}${errorMessage(err)}`, { cause: err });
+    }
+}
+// A quantized MiniLM is about 23 MB, so two minutes is a 1.5 Mbit/s link; a load from disk takes about a second.
+// The backoff matches the reranker outage warning's repeat window, so each window has one attempt and one warning.
+export const MODEL_LOAD_POLICY = { timeoutMs: 2 * MINUTE_MS, backoffMs: 5 * MINUTE_MS };
+/** One load per key at a time, bounded by the policy's timeout; `onFailure` hears each failed attempt, so once per backoff window. */
+export function createModelLoads(policy, onFailure) {
+    const loaded = new Map();
+    const inFlight = new Map();
+    const failed = new Map();
+    const attempt = (key, start) => new Promise((resolve, reject) => {
+        const timer = setTimeout(() => reject(new Error(`${key} did not load within ${policy.timeoutMs / 1000} s`)), policy.timeoutMs);
+        timer.unref();
+        Promise.resolve().then(start).then((model) => {
+            clearTimeout(timer);
+            loaded.set(key, model);
+            failed.delete(key);
+            resolve(model);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err instanceof Error ? err : new Error(errorMessage(err)));
+        });
+    });
+    return {
+        load(key, start) {
+            const model = loaded.get(key);
+            if (model !== undefined)
+                return Promise.resolve(model);
+            const pending = inFlight.get(key);
+            if (pending)
+                return pending;
+            const failure = failed.get(key);
+            if (failure && Date.now() < failure.until)
+                return Promise.reject(failure.error);
+            const next = attempt(key, start).catch((err) => {
+                failed.set(key, { error: err, until: Date.now() + policy.backoffMs });
+                onFailure?.(key, err);
+                throw err;
+            }).finally(() => inFlight.delete(key));
+            inFlight.set(key, next);
+            return next;
+        },
+    };
+}
+//# sourceMappingURL=transformers.js.map

package/dist/entry/session-text.d.ts

@@ -3,5 +3,5 @@ export { scrubForSharing } from '../capture/share-scrub.js';
 export { transcriptWorkingState, WORKING_STATE_CAPS } from '../capture/working-state.js';
 export { lessonFromFailure, failureReport, type FailureReport } from '../capture/failure-reading.js';
 export { collectHandoffEvidence } from '../capture/handoff-evidence.js';
-export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../capture/compaction-items.js';
+export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../util/compaction-items.js';
 //# sourceMappingURL=session-text.d.ts.map

package/dist/entry/session-text.js

@@ -5,5 +5,5 @@ export { scrubForSharing } from '../capture/share-scrub.js';
 export { transcriptWorkingState, WORKING_STATE_CAPS } from '../capture/working-state.js';
 export { lessonFromFailure, failureReport } from '../capture/failure-reading.js';
 export { collectHandoffEvidence } from '../capture/handoff-evidence.js';
-export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../capture/compaction-items.js';
+export { compactSummaryBody, parseCompactionItems, COMPACTION_ITEM_MAX_CHARS, COMPACTION_ITEM_ROW_CAP } from '../util/compaction-items.js';
 //# sourceMappingURL=session-text.js.map

package/dist/eval/eval-suite.js

@@ -5,6 +5,7 @@ import { search } from '../search/bm25-search.js';
 import { multihopSearch } from '../search/multihop.js';
 import { mrr, recallAtK, ndcgAtK } from './eval.js';
 import { DAY_MS } from '../util/time.js';
+import { pct } from '../util/format.js';
 const BASE_DATE = new Date('2026-01-15T10:00:00Z');
 function dateOffset(days) {
     const d = new Date(BASE_DATE.getTime() + days * DAY_MS);
@@ -51,19 +52,24 @@ function addDirectRecall(entries, cases) {
 }
 /** Extraction preference: extracted facts should rank above raw source. */
 function addExtractionPreference(entries, cases) {
-    entries.push(mem('ep-src-1', 'speaker:Alice: So we had this big meeting yesterday about the deployment pipeline and Bob mentioned that the staging environment is using Kubernetes 1.28 and we should upgrade to 1.30 before the end of Q2 because of the security patches', {
+    entries.push(mem('ep-src-1', 'speaker:Alice: So we had this big meeting yesterday about the deployment pipeline and Bob mentioned that the staging environment is ' +
+        'using Kubernetes 1.28 and we should upgrade to 1.30 before the end of Q2 because of the security patches', {
         created: dateOffset(10), tags: ['speaker:Alice', 'topic:infrastructure', 'session:meeting-1'],
     }), mem('ep-ext-1', 'The staging environment runs Kubernetes 1.28 and needs to be upgraded to 1.30 before end of Q2 for security patches', {
         created: dateOffset(10), layer: Layer.Semantic, tags: ['speaker:Alice', 'topic:infrastructure', 'extracted'],
         extracted_from: 'ep-src-1',
-    }), mem('ep-src-2', 'speaker:Bob: Yeah and the thing about the monitoring is that we switched from Datadog to Grafana last month and the alerting rules still need to be migrated, Carol was supposed to handle that but she has been busy with the frontend rewrite', {
+    }), mem('ep-src-2', 'speaker:Bob: Yeah and the thing about the monitoring is that we switched from Datadog to Grafana last month and the alerting rules ' +
+        'still need to be migrated, Carol was supposed to handle that but she has been busy with the frontend rewrite', {
         created: dateOffset(11), tags: ['speaker:Bob', 'topic:monitoring', 'session:meeting-1'],
-    }), mem('ep-ext-2', 'The team switched from Datadog to Grafana last month but alerting rules have not been migrated yet. Carol is responsible but blocked by the frontend rewrite.', {
+    }), mem('ep-ext-2', 'The team switched from Datadog to Grafana last month but alerting rules have not been migrated yet. Carol is responsible but blocked ' +
+        'by the frontend rewrite.', {
         created: dateOffset(11), layer: Layer.Semantic, tags: ['speaker:Bob', 'topic:monitoring', 'extracted'],
         extracted_from: 'ep-src-2',
-    }), mem('ep-src-3', 'speaker:Carol: The login page redesign is almost done, I just need to wire up the OAuth2 PKCE flow with the new identity provider and write the integration tests', {
+    }), mem('ep-src-3', 'speaker:Carol: The login page redesign is almost done, I just need to wire up the OAuth2 PKCE flow with the new identity provider and ' +
+        'write the integration tests', {
         created: dateOffset(12), tags: ['speaker:Carol', 'topic:auth', 'session:meeting-2'],
-    }), mem('ep-ext-3', 'Carol is nearly done with the login page redesign. Remaining work: wire up OAuth2 PKCE flow with the new identity provider and write integration tests.', {
+    }), mem('ep-ext-3', 'Carol is nearly done with the login page redesign. Remaining work: wire up OAuth2 PKCE flow with the new identity provider and write ' +
+        'integration tests.', {
         created: dateOffset(12), layer: Layer.Semantic, tags: ['speaker:Carol', 'topic:auth', 'extracted'],
         extracted_from: 'ep-src-3',
     }));
@@ -89,7 +95,8 @@ function addDagDrilldown(entries, cases) {
     }), mem('dag-child-3', 'Batch API endpoint /reports/generate takes 8 seconds because it runs synchronously instead of using a job queue', {
         created: dateOffset(15), layer: Layer.Semantic, tags: ['topic:api-performance', 'extracted'],
         dag_level: 1,
-    }), mem('dag-summary-1', 'API performance issues: /users degraded to 300ms (permissions check), /orders spiked to 500ms (missing index), /reports takes 8s (needs job queue)', {
+    }), mem('dag-summary-1', 'API performance issues: /users degraded to 300ms (permissions check), /orders spiked to 500ms (missing index), /reports takes 8s ' +
+        '(needs job queue)', {
         created: dateOffset(16), layer: Layer.Semantic, tags: ['topic:api-performance'],
         dag_level: 2, dag_parent_id: undefined,
     }));
@@ -171,7 +178,8 @@ function addMultiHop(entries, cases) {
         created: dateOffset(26), tags: ['speaker:Bob', 'topic:payments'],
     }), mem('mh-3', 'speaker:Alice fixed the Stripe webhook by switching to the production secret key. Payment confirmations now arrive within 2 seconds.', {
         created: dateOffset(27), tags: ['speaker:Alice', 'topic:payments'],
-    }), mem('mh-4', 'speaker:Carol reported that the billing dashboard shows incorrect revenue numbers because it reads from the payments_raw table instead of payments_reconciled.', {
+    }), mem('mh-4', 'speaker:Carol reported that the billing dashboard shows incorrect revenue numbers because it reads from the payments_raw table instead of ' +
+        'payments_reconciled.', {
         created: dateOffset(28), tags: ['speaker:Carol', 'topic:billing'],
     }));
     cases.push({
@@ -286,9 +294,6 @@ export function resultToBaseline(result) {
         overall: result.overall,
     };
 }
-function pct(n) {
-    return (n * 100).toFixed(1) + '%';
-}
 function pad(s, w) {
     return s.padEnd(w);
 }
@@ -315,7 +320,8 @@ export function formatResult(result, baseline) {
             vsBaseline = deltaStr(delta);
             verdict = delta < -REGRESSION_THRESHOLD ? 'REGRESS' : 'PASS';
         }
-        lines.push(`${pad(feat.category, 24)} | ${pad(pct(feat.mrr), 8)} | ${pad(pct(feat.recallAt5), 8)} | ${pad(pct(feat.ndcgAt5), 8)} | ${pad(vsBaseline, 12)} | ${verdict}`);
+        const cells = [pad(feat.category, 24), pad(pct(feat.mrr), 8), pad(pct(feat.recallAt5), 8), pad(pct(feat.ndcgAt5), 8), pad(vsBaseline, 12), verdict];
+        lines.push(cells.join(' | '));
     }
     lines.push('');
     lines.push(`Overall: MRR ${pct(result.overall.mrr)} | R@5 ${pct(result.overall.recallAt5)} | NDCG@5 ${pct(result.overall.ndcgAt5)}`);

package/dist/eval/eval.js

@@ -2,7 +2,7 @@
  *  It exists so MMR lambda, embedding weights and scoring tweaks are tuned against evidence instead of intuition. */
 import { hybridSearch } from '../search/hybrid.js';
 import { searchBothHybrid } from '../sharing/search-both.js';
-import { isInitialized } from '../store/open.js';
+import { isInitialized } from '../core/project-identity.js';
 // Generous so metrics are not truncated.
 const DEFAULT_EVAL_BUDGET = 100_000;
 const QUERY_WORDS = 8;

package/dist/eval/judgment.js

@@ -2,7 +2,7 @@
  *  Regex picks WHAT is a candidate; it cannot say what is worth keeping, so
  *  every captured memory currently lands on a flat schema_fit of 0.5. */
 import { fetchWithRetry } from '../util/http-retry.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { readCappedJson } from '../util/capped-json.js';
 import { isJsonNumber, isJsonObject, isJsonString } from '../util/json.js';
 const ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
@@ -19,7 +19,9 @@ function answerNamed(reply, name) {
 const QUESTIONS = {
     durable: {
         type: 'noul',
-        instructions: 'This text was extracted from an AI coding agent transcript as a candidate memory. It is worth storing long-term only if it would still be useful to a future agent working on this codebase weeks from now: a durable preference, a convention, a decision with a reason, or a gotcha that will recur. Transient chatter, one-off status, restatements of code already in the repo, and anything only true inside this one session are not worth storing.',
+        instructions: 'This text was extracted from an AI coding agent transcript as a candidate memory. It is worth storing long-term only if it would still be useful to ' +
+            'a future agent working on this codebase weeks from now: a durable preference, a convention, a decision with a reason, or a gotcha that will recur. ' +
+            'Transient chatter, one-off status, restatements of code already in the repo, and anything only true inside this one session are not worth storing.',
     },
     kind: {
         type: 'choice',
@@ -73,10 +75,15 @@ async function post(content, opts) {
         }, { timeoutMs: JUDGE_TIMEOUT_MS, fetchFn: opts.fetcher });
     }
     catch (err) {
-        log.debug(`judge: request failed: ${errorMessage(err)}`);
+        log.warn(`judge: request failed: ${errorMessage(err)}`, errorFields(err));
         return null;
     }
-    return res.ok ? res : null;
+    if (res.ok)
+        return res;
+    // The body is the server's reply, never the request, so it cannot hold the key.
+    const snippet = (await res.text().catch(() => '')).slice(0, 200);
+    log.warn('judge: non-2xx reply', { status: res.status, body: snippet });
+    return null;
 }
 /** `null` on any failure, so a Jev outage degrades capture to today's
  *  behaviour instead of blocking the write. */

package/dist/graph/extract.js

@@ -101,7 +101,7 @@ function deriveEntities(loaded) {
         pass.byType[entityType] = 0;
         for (const row of rows) {
             pass.allRows.push(row);
-            // Names are uncapped at source; trimming on both sides of the cap gives the exact name insertEntity stores.
+            // Names are uncapped at source; trimming on both sides of the cap gives the exact name insertEntityRow stores.
             const name = (row.name ?? '').trim().slice(0, MAX_ENTITY_NAME_LEN).trim();
             const key = keyOf(row.entityType, row.e2Id);
             // A row seen twice was superseded between the two status loads; its first sighting stands.
@@ -220,7 +220,7 @@ export function extractGraph(hippoRoot, tenantId) {
     // Loaded first: opening a second connection under the rebuild's BEGIN IMMEDIATE dead-locks ('database is locked').
     const derived = deriveGraph(loadGraphSources(hippoRoot, tenantId));
     // Diffed and applied under one lock, so two concurrent rebuilds serialize instead of both inserting a missing row.
-    const skipped = runGraphRebuildTransaction(hippoRoot, tenantId, (txDb) => applyGraphOps(txDb, hippoRoot, tenantId, graphDelta(txDb, tenantId, derived), { from: 0, holdMs: Infinity }).skipped);
+    const skipped = runGraphRebuildTransaction(hippoRoot, tenantId, (txDb) => applyGraphOps(txDb, tenantId, graphDelta(txDb, tenantId, derived), { from: 0, holdMs: Infinity }).skipped);
     return resultOf(derived, skipped);
 }
 /** extractGraph for sleep: diffs outside the lock, then applies in transactions of about `budget.holdMs` with a pause
@@ -237,7 +237,7 @@ export async function extractGraphChunked(hippoRoot, tenantId, budget = WRITE_BU
             await budget.pause(committedAt);
         const from = next;
         // Sleep's wait, not a server request's 250 ms: each chunk is a fresh BEGIN IMMEDIATE a hook's write could otherwise fail.
-        const chunk = runGraphRebuildTransaction(hippoRoot, tenantId, (txDb) => applyGraphOps(txDb, hippoRoot, tenantId, ops, { from, holdMs: budget.holdMs, clock: budget.clock }), { busyWaitMs: SLEEP_DB_WAIT_MS });
+        const chunk = runGraphRebuildTransaction(hippoRoot, tenantId, (txDb) => applyGraphOps(txDb, tenantId, ops, { from, holdMs: budget.holdMs, clock: budget.clock }), { busyWaitMs: SLEEP_DB_WAIT_MS });
         committedAt = budget.clock();
         next = chunk.next;
         skipped += chunk.skipped;

package/dist/graph/recall.js

@@ -6,7 +6,7 @@ import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
 import { estimateTokens } from '../util/token-text.js';
 import { compareEntryIdentity, compareScoresDesc } from '../core/compare.js';
 import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations } from '../store/graph-reads.js';
-import { passesCliRecallScopeFilter, passesScopeFilterForRecall } from '../store/recall-scope.js';
+import { passesCliRecallScopeFilter, passesScopeFilterForRecall } from '../core/recall-scope.js';
 /** Hard cap on `--hops` (a higher value just walks more of a finite graph; this bounds
  *  worst-case work and keeps the flag honest). */
 export const MAX_HOPS = 3;

package/dist/graph/view.js

@@ -146,15 +146,23 @@ const CLIENT_JS = [
     "  var panning=false,sx=0,sy=0;",
     "  svg.addEventListener('mousedown',function(e){if(e.target.closest('.node'))return;panning=true;sx=e.clientX;sy=e.clientY;});",
     "  window.addEventListener('mouseup',function(){panning=false;});",
-    "  window.addEventListener('mousemove',function(e){if(!panning)return;var r=svg.getBoundingClientRect();var k=view.w/r.width;view.x-=(e.clientX-sx)*k;view.y-=(e.clientY-sy)*k;sx=e.clientX;sy=e.clientY;apply();});",
-    "  svg.addEventListener('wheel',function(e){e.preventDefault();var r=svg.getBoundingClientRect();var mx=view.x+(e.clientX-r.left)/r.width*view.w;var my=view.y+(e.clientY-r.top)/r.height*view.h;var f=e.deltaY<0?0.9:1.1;view.x=mx-(mx-view.x)*f;view.y=my-(my-view.y)*f;view.w*=f;view.h*=f;apply();},{passive:false});",
-    "  var data={};try{data=JSON.parse(document.getElementById('graph-data').textContent);}catch(_){}",
+    "  window.addEventListener('mousemove',function(e){if(!panning)return;var r=svg.getBoundingClientRect();var " +
+        "k=view.w/r.width;view.x-=(e.clientX-sx)*k;view.y-=(e.clientY-sy)*k;sx=e.clientX;sy=e.clientY;apply();});",
+    "  svg.addEventListener('wheel',function(e){e.preventDefault();var r=svg.getBoundingClientRect();var mx=view.x+(e.clientX-r.left)/r.width*view.w;var " +
+        "my=view.y+(e.clientY-r.top)/r.height*view.h;var " +
+        "f=e.deltaY<0?0.9:1.1;view.x=mx-(mx-view.x)*f;view.y=my-(my-view.y)*f;view.w*=f;view.h*=f;apply();},{passive:false});",
+    "  var data={};try{data=JSON.parse(document.getElementById('graph-data').textContent);}",
+    "  catch(e){console.error('hippo graph: embedded model is not valid JSON',e);}",
     "  var adj={};(data.edges||[]).forEach(function(e){(adj[e.from]=adj[e.from]||[]).push(e.to);(adj[e.to]=adj[e.to]||[]).push(e.from);});",
     "  var active=null;",
-    "  document.querySelectorAll('.node').forEach(function(g){g.addEventListener('click',function(ev){ev.stopPropagation();var id=g.getAttribute('data-id');if(active===id){clearHi();active=null;return;}active=id;highlight(id);});});",
+    "  document.querySelectorAll('.node').forEach(function(g){g.addEventListener('click',function(ev){ev.stopPropagation();var " +
+        "id=g.getAttribute('data-id');if(active===id){clearHi();active=null;return;}active=id;highlight(id);});});",
     "  svg.addEventListener('click',function(){clearHi();active=null;});",
     "  function clearHi(){svg.classList.remove('focused');document.querySelectorAll('.hi').forEach(function(el){el.classList.remove('hi');});}",
-    "  function highlight(id){clearHi();svg.classList.add('focused');var keep={};keep[id]=1;(adj[id]||[]).forEach(function(n){keep[n]=1;});document.querySelectorAll('.node').forEach(function(g){if(keep[g.getAttribute('data-id')])g.classList.add('hi');});document.querySelectorAll('.edge').forEach(function(l){if(l.getAttribute('data-from')===id||l.getAttribute('data-to')===id)l.classList.add('hi');});}",
+    "  function highlight(id){clearHi();svg.classList.add('focused');var " +
+        "keep={};keep[id]=1;(adj[id]||[]).forEach(function(n){keep[n]=1;});document.querySelectorAll('.node').forEach(" +
+        "function(g){if(keep[g.getAttribute('data-id')])g.classList.add('hi');});document.querySelectorAll('.edge').forEach(" +
+        "function(l){if(l.getAttribute('data-from')===id||l.getAttribute('data-to')===id)l.classList.add('hi');});}",
     "})();",
 ].join("\n");
 const STYLE = [

package/dist/graph/write.d.ts

@@ -6,7 +6,7 @@ export interface ApplyGraphOpsResult {
 }
 /** Applies `ops` from index `opts.from` on the caller's open transaction and stops at the first op boundary past `opts.holdMs`.
  *  Returns where the next chunk starts and how many ops were skipped as stale. */
-export declare function applyGraphOps(db: DatabaseSyncLike, hippoRoot: string, tenantId: string, ops: readonly GraphOp[], opts: {
+export declare function applyGraphOps(db: DatabaseSyncLike, tenantId: string, ops: readonly GraphOp[], opts: {
     readonly from: number;
     readonly holdMs: number;
     readonly clock?: () => number;

package/dist/graph/write.js

@@ -1,19 +1,19 @@
 // Applies a rebuild's op list on the caller's transaction. The statements and the consolidated-source guard sit in the store's graph writers.
 import { assertTenantId } from '../store/tenant.js';
 import { clock } from '../util/write-budget.js';
-import { deleteEntityRow, deleteRelationRow, entityIdBySource, insertEntity, insertRelation, objectInForce, relationPresent, updateEntity } from '../store/graph-writes.js';
-function insertDesiredRelation(db, hippoRoot, tenantId, rel) {
+import { deleteEntityRow, deleteRelationRow, entityIdBySource, insertEntityRow, insertRelationRow, objectInForce, relationPresent, updateEntityRow } from '../store/graph-writes.js';
+function insertDesiredRelation(db, tenantId, rel) {
     const fromEntityId = entityIdBySource(db, tenantId, rel.from.entityType, rel.from.sourceObject);
     const toEntityId = entityIdBySource(db, tenantId, rel.to.entityType, rel.to.sourceObject);
     if (fromEntityId === undefined || toEntityId === undefined || !objectInForce(db, tenantId, rel.sourceObject))
         return false;
     if (relationPresent(db, tenantId, fromEntityId, toEntityId, rel.relType))
         return false;
-    insertRelation(hippoRoot, tenantId, { fromEntityId, toEntityId, relType: rel.relType, memoryId: rel.memoryId, sourceObject: rel.sourceObject }, db);
+    insertRelationRow(db, tenantId, { fromEntityId, toEntityId, relType: rel.relType, memoryId: rel.memoryId, sourceObject: rel.sourceObject });
     return true;
 }
 /** Applies one op; false when a writer since the diff made it stale, which the next run's diff repairs. */
-function applyGraphOp(db, hippoRoot, tenantId, op) {
+function applyGraphOp(db, tenantId, op) {
     switch (op.op) {
         case 'deleteEntity':
             deleteEntityRow(db, tenantId, op.id);
@@ -24,27 +24,27 @@ function applyGraphOp(db, hippoRoot, tenantId, op) {
         case 'updateEntity':
             if (!objectInForce(db, tenantId, op.entity.sourceObject))
                 return false;
-            return updateEntity(hippoRoot, tenantId, op.id, op.entity, db) !== null;
+            return updateEntityRow(db, tenantId, op.id, op.entity) !== null;
         case 'insertEntity':
             // A mirrorless object closed since the load is never enqueued again, so a stale insert would stay for good.
             if (!objectInForce(db, tenantId, op.entity.sourceObject) || entityIdBySource(db, tenantId, op.entity.entityType, op.entity.sourceObject) !== undefined)
                 return false;
-            insertEntity(hippoRoot, tenantId, op.entity, db);
+            insertEntityRow(db, tenantId, op.entity);
             return true;
         case 'insertRelation':
-            return insertDesiredRelation(db, hippoRoot, tenantId, op.relation);
+            return insertDesiredRelation(db, tenantId, op.relation);
     }
 }
 /** Applies `ops` from index `opts.from` on the caller's open transaction and stops at the first op boundary past `opts.holdMs`.
  *  Returns where the next chunk starts and how many ops were skipped as stale. */
-export function applyGraphOps(db, hippoRoot, tenantId, ops, opts) {
+export function applyGraphOps(db, tenantId, ops, opts) {
     assertTenantId('applyGraphOps', tenantId);
     const now = opts.clock ?? clock;
     const begunAt = now();
     let next = opts.from;
     let skipped = 0;
     while (next < ops.length) {
-        if (!applyGraphOp(db, hippoRoot, tenantId, ops[next]))
+        if (!applyGraphOp(db, tenantId, ops[next]))
             skipped += 1;
         next += 1;
         if (now() - begunAt >= opts.holdMs)

package/dist/hooks/codex-session.js

@@ -1,6 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import { isJsonString } from '../util/json.js';
+import { errorMessage, log } from '../util/log.js';
 function collectFiles(dir) {
     if (!fs.existsSync(dir))
         return [];
@@ -42,8 +43,8 @@ function readCodexSessionIdsFromHistoryDelta(historyPath, startOffsetBytes) {
                 ordered.push(sessionId);
             }
         }
-        catch {
-            // ignore malformed JSONL lines
+        catch (err) {
+            log.warn(`codex history ${historyPath}: skipped a malformed JSONL line (${errorMessage(err)})`);
         }
     }
     return ordered;

package/dist/hooks/codex-wrapper.js

@@ -3,7 +3,8 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { PACKAGE_ROOT } from '../core/package-root.js';
 import { errorMessage, log } from '../util/log.js';
-import { HIPPO_CODEX_WRAPPER_MARKER, homeDir, codexHomeDir, ensureDir } from './shared.js';
+import { HIPPO_CODEX_WRAPPER_MARKER, ensureDir } from './shared.js';
+import { homeDir, codexHomeDir } from '../util/agent-homes.js';
 import { isJsonString } from '../util/json.js';
 import { writeFileAtomic } from '../util/atomic-write.js';
 export function resolveCodexWrapperPaths() {

package/dist/hooks/json-hooks.js

@@ -2,7 +2,8 @@
  * OpenCode rejects the JSON-hook schema (no `hooks` key), so it gets a TS plugin (OPENCODE_PLUGIN_SOURCE); see installCodexHooks, installCopilotHooks. */
 import * as fs from 'fs';
 import * as path from 'path';
-import { HIPPO_SLEEP_MARKER, HIPPO_LAST_SLEEP_MARKER, HIPPO_CAPTURE_MARKER, HIPPO_SESSION_END_MARKER, HIPPO_PINNED_INJECT_MARKER, HIPPO_PINNED_INJECT_COMMAND, HIPPO_PRE_COMPACT_MARKER, HIPPO_COMPACT_RESUME_MARKER, HIPPO_CAPTURE_ERROR_MARKER, HIPPO_POST_COMPACT_MARKER, homeDir, claudeConfigDir, codexHomeDir, copilotHooksFile, defaultPreCompactLogPath } from './shared.js';
+import { HIPPO_SLEEP_MARKER, HIPPO_LAST_SLEEP_MARKER, HIPPO_CAPTURE_MARKER, HIPPO_SESSION_END_MARKER, HIPPO_PINNED_INJECT_MARKER, HIPPO_PINNED_INJECT_COMMAND, HIPPO_PRE_COMPACT_MARKER, HIPPO_COMPACT_RESUME_MARKER, HIPPO_CAPTURE_ERROR_MARKER, HIPPO_POST_COMPACT_MARKER, copilotHooksFile, defaultPreCompactLogPath } from './shared.js';
+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';
@@ -348,7 +349,8 @@ function warnKeptHippoHandlers(settingsPath, hooks) {
     });
     if (kept.length === 0)
         return;
-    process.stderr.write(`hippo kept these hook handlers in ${settingsPath} because they do not start with a hippo command; remove any that are hippo's by hand: ${kept.map((c) => JSON.stringify(c)).join(', ')}\n`);
+    process.stderr.write(`hippo kept these hook handlers in ${settingsPath} because they do not start with a hippo command; ` +
+        `remove any that are hippo's by hand: ${kept.map((c) => JSON.stringify(c)).join(', ')}\n`);
 }
 /** Removes hippo's own hook handlers from `target`'s settings file and keeps every other handler; true when the file changed. */
 export function uninstallJsonHooks(target) {

package/dist/hooks/opencode.js

@@ -1,6 +1,6 @@
 import * as fs from 'fs';
 import * as path from 'path';
-import { homeDir } from './shared.js';
+import { homeDir } from '../util/agent-homes.js';
 import { writeFileAtomic } from '../util/atomic-write.js';
 import { isJsonString, isJsonObjectLiteral } from '../util/json.js';
 const HIPPO_OPENCODE_PLUGIN_MARKER = 'HIPPO_OPENCODE_PLUGIN_V1';
@@ -20,12 +20,15 @@ export const HippoPlugin = async ({ $ }) => {
       if (typeof $ !== "function") return;
       try {
         if (event.type === "session.idle") {
-          await $\`hippo session-end\`.quiet().nothrow();
+          const r = await $\`hippo session-end\`.quiet().nothrow();
+          if (r && r.exitCode !== 0) console.error("[hippo] session-end exited " + r.exitCode);
         } else if (event.type === "session.created") {
-          await $\`hippo last-sleep\`.quiet().nothrow();
+          const r = await $\`hippo last-sleep\`.quiet().nothrow();
+          if (r && r.exitCode !== 0) console.error("[hippo] last-sleep exited " + r.exitCode);
         }
-      } catch {
-        // hippo CLI not on PATH or other failure — never crash the host session.
+      } catch (err) {
+        // hippo CLI not on PATH or other failure: never crash the host session.
+        console.error("[hippo] plugin hook failed: " + (err && err.message ? err.message : err));
       }
     },
   };

package/dist/hooks/shared.d.ts

@@ -17,15 +17,9 @@ export declare const HIPPO_PRE_COMPACT_MARKER = "hippo pre-compact";
 export declare const HIPPO_COMPACT_RESUME_MARKER = "hippo compact-resume";
 export declare const HIPPO_CAPTURE_ERROR_MARKER = "hippo capture-error";
 export declare const HIPPO_POST_COMPACT_MARKER = "hippo post-compact";
-export declare function homeDir(): string;
-/** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
-export declare function codexHomeDir(home?: string, env?: Readonly<Record<string, string | undefined>>): string;
 /** Copilot's config folder: $COPILOT_HOME, else ~/.copilot under os.homedir(), as the
  * Copilot apps resolve it (a HOME that differs from the profile must not move it). */
 export declare function copilotHomeDir(home?: string, env?: Readonly<Record<string, string | undefined>>): string;
-/** Claude Code's config folder, where it reads settings.json: $CLAUDE_CONFIG_DIR when set and non-empty, else
- * ~/.claude under os.homedir(), as Claude Code does (a HOME that differs from the profile must not move it). */
-export declare function claudeConfigDir(home?: string, env?: Readonly<Record<string, string | undefined>>): string;
 /** Codex counts as installed only when its config folder exists: Codex itself refuses a CODEX_HOME that is not a folder. */
 export declare function isCodexPresent(home?: string): boolean;
 /** hippo's own hooks file, in the hooks folder the Copilot CLI reads. */

package/dist/hooks/shared.js

@@ -1,8 +1,8 @@
-import { envHomeDir, processEnv } from '../util/env.js';
+import { processEnv } from '../util/env.js';
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
-import { vscodeDataFolders } from '../agent-memories/copilot.js';
+import { claudeConfigDir, codexHomeDir, homeDir, vscodeDataFolders } from '../util/agent-homes.js';
 export const HIPPO_SLEEP_MARKER = 'hippo sleep';
 export const HIPPO_LAST_SLEEP_MARKER = 'hippo last-sleep';
 export const HIPPO_CAPTURE_MARKER = 'hippo capture --last-session';
@@ -14,23 +14,11 @@ export const HIPPO_PRE_COMPACT_MARKER = 'hippo pre-compact';
 export const HIPPO_COMPACT_RESUME_MARKER = 'hippo compact-resume';
 export const HIPPO_CAPTURE_ERROR_MARKER = 'hippo capture-error';
 export const HIPPO_POST_COMPACT_MARKER = 'hippo post-compact';
-export function homeDir() {
-    return envHomeDir() || os.homedir();
-}
-/** Codex's config folder: $CODEX_HOME, else ~/.codex, as the Codex hooks docs describe. */
-export function codexHomeDir(home = homeDir(), env = processEnv()) {
-    return env.CODEX_HOME || path.join(home, '.codex');
-}
 /** Copilot's config folder: $COPILOT_HOME, else ~/.copilot under os.homedir(), as the
  * Copilot apps resolve it (a HOME that differs from the profile must not move it). */
 export function copilotHomeDir(home = os.homedir(), env = processEnv()) {
     return env.COPILOT_HOME || path.join(home, '.copilot');
 }
-/** Claude Code's config folder, where it reads settings.json: $CLAUDE_CONFIG_DIR when set and non-empty, else
- * ~/.claude under os.homedir(), as Claude Code does (a HOME that differs from the profile must not move it). */
-export function claudeConfigDir(home = os.homedir(), env = processEnv()) {
-    return env.CLAUDE_CONFIG_DIR || path.join(home, '.claude');
-}
 /** Codex counts as installed only when its config folder exists: Codex itself refuses a CODEX_HOME that is not a folder. */
 export function isCodexPresent(home = homeDir()) {
     return fs.statSync(codexHomeDir(home), { throwIfNoEntry: false })?.isDirectory() === true;
@@ -90,7 +78,8 @@ export function detectInstalledTools() {
             kind: 'wrapper',
             notes: 'memory hooks in hooks.json, and wraps the detected codex launcher for session-end consolidation'
         },
-        { name: 'copilot', configDir: copilotHomeDir(), detected: isCopilotPresent(), kind: 'json-hook', notes: 'hooks in hooks/hippo.json, the MCP server in mcp-config.json and a block in copilot-instructions.md; for VS Code, the server in each User mcp.json and prompts/hippo.instructions.md' },
+        { name: 'copilot', configDir: copilotHomeDir(), detected: isCopilotPresent(), kind: 'json-hook', notes: 'hooks in hooks/hippo.json, the MCP server in ' +
+                'mcp-config.json and a block in copilot-instructions.md; for VS Code, the server in each User mcp.json and prompts/hippo.instructions.md' },
         {
             name: 'cursor',
             configDir: '~/.cursor',

package/dist/importers/core.js

@@ -7,7 +7,7 @@ import { loadAllEntries } 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';
-import { RejectedValueError } from '../store/rejection.js';
+import { RejectedValueError } from '../core/api-errors.js';
 import { rejectionGuardRefuses } from '../store/rejected-values.js';
 import { loadConfig } from '../core/config.js';
 import { vetSecrets } from '../util/secret-detect.js';

package/dist/importers/sources.js

@@ -2,6 +2,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { importEntries } from './core.js';
 import { splitMarkdownFrontmatter, collectMarkdownFiles } from './markdown-parse.js';
+import { errorMessage, log } from '../util/log.js';
 import { isJsonString, isJsonObject } from '../util/json.js';
 /** Coerce one imported record (string, `{content|text: ...}` object, or
  *  anything else) into the plain-text memory chunk it represents. */
@@ -29,8 +30,8 @@ function parseChatGPTFile(filePath) {
                 return parsed.map(extractMemoryText).filter(Boolean);
             }
         }
-        catch {
-            // Fall through to plain text
+        catch (err) {
+            log.warn(`import: ${filePath} is not valid JSON (${errorMessage(err)}); reading it as plain text`);
         }
     }
     // Plain text: one memory per line
@@ -116,8 +117,8 @@ function parseClaudeFile(filePath) {
                 return parsed.map(extractMemoryText).filter(Boolean);
             }
         }
-        catch {
-            // Fall through to markdown
+        catch (err) {
+            log.warn(`import: ${filePath} is not valid JSON (${errorMessage(err)}); reading it as markdown`);
         }
     }
     // Markdown file: strip hippo block and split

package/dist/importers/vault.js

@@ -5,8 +5,8 @@ import { createHash } from 'node:crypto';
 import { createMemory } from '../core/memory.js';
 import { loadVaultRawRows } from '../store/entry-reads.js';
 import { remember, archiveRaw, isPrivateScope } from '../api/index.js';
-import { assertClientScope } from '../store/recall-scope.js';
-import { RejectedValueError } from '../store/rejection.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 { loadConfig } from '../core/config.js';
@@ -82,18 +82,20 @@ function vaultIdentityOrThrow(options) {
     // sharing a basename collide on the same `vault:<name>:*` prefix and the sync archived the first one's rows.
     const vaultName = options.name?.trim();
     if (!vaultName) {
-        throw new Error('importVault requires an explicit vault name (options.name): it is the identity key for source-deletion sync and must not be inferred from the folder basename.');
+        throw new Error('importVault requires an explicit vault name (options.name): it is the identity key for source-deletion sync and must not be inferred from the folder ' +
+            'basename.');
     }
     if (vaultName.includes(':')) {
         // ':' delimits the artifactRef (vault:<name>:<relpath>); a name containing it lets another vault's prefix scan over-match and archive its rows.
         throw new Error(`vault name must not contain ':' (artifactRef delimiter): ${vaultName}`);
     }
     const scope = options.scope ?? null;
-    // Privacy guard: recall only default-denies scopes shaped `<source>:private:*` (isPrivateScope in src/store/recall-scope.ts), so a bare `private`
+    // Privacy guard: recall only default-denies scopes shaped `<source>:private:*` (isPrivateScope in src/core/recall-scope.ts), so a bare `private`
     // alias would be returned to no-scope callers. Reject any scope naming a `private` segment that is not a valid `<source>:private:*`.
     assertClientScope(scope);
     if (scope !== null && scope.split(':').includes('private') && !isPrivateScope(scope)) {
-        throw new Error(`vault scope '${scope}' is not recognized as private by recall (only '<source>:private:*' scopes are default-denied). Use a source-prefixed scope such as 'vault:private:${vaultName}'.`);
+        throw new Error(`vault scope '${scope}' is not recognized as private by recall (only '<source>:private:*' scopes are default-denied). ` +
+            `Use a source-prefixed scope such as 'vault:private:${vaultName}'.`);
     }
     return { vaultName, scope };
 }

package/dist/index.d.ts

@@ -32,8 +32,9 @@ export { consolidate } from './consolidate/sleep.js';
 export { ConsolidationResult } from './consolidate/run.js';
 export { sleep, type SleepOpts, type SleepResult } from './api/sleep.js';
 export { strengthBucket } from './consolidate/dedupe.js';
-export { isEmbeddingAvailable, getEmbedding } from './store/embeddings/local.js';
-export { cosineSimilarity, embedMemory, embedAll, } from './store/embeddings/index.js';
+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 { getGlobalRoot, initGlobal, promoteToGlobal } from './sharing/global-store.js';