hippo-memory 2.0.0 → 2.1.0

package/dist/eval/eval.d.ts

@@ -78,8 +78,14 @@ export interface EvalComparison {
     onlyInBaseline: string[];
     onlyInCurrent: string[];
 }
-/** Compute pairwise deltas between a baseline and a current eval summary, matching cases by EvalCase.id; mismatches land in the onlyIn arrays. */
+/**
+ * Compute pairwise deltas between a baseline and a current eval summary, matching cases by EvalCase.id; mismatches land
+ * in the onlyIn arrays.
+ */
 export declare function compareSummaries(baseline: EvalSummary, current: EvalSummary): EvalComparison;
-/** For each memory, use its first 8 content words as a trivial query and expect that memory back: a smoke test for recall. */
+/**
+ * For each memory, use its first 8 content words as a trivial query and expect that memory back: a smoke test for
+ * recall.
+ */
 export declare function bootstrapCorpus(entries: MemoryEntry[], maxCases?: number): EvalCase[];
 //# sourceMappingURL=eval.d.ts.map

package/dist/eval/eval.js

@@ -101,7 +101,10 @@ function rankForCase(query, entries, options, useBothStores) {
             mmrLambda: options.mmrLambda,
         });
 }
-/** Compute pairwise deltas between a baseline and a current eval summary, matching cases by EvalCase.id; mismatches land in the onlyIn arrays. */
+/**
+ * Compute pairwise deltas between a baseline and a current eval summary, matching cases by EvalCase.id; mismatches land
+ * in the onlyIn arrays.
+ */
 export function compareSummaries(baseline, current) {
     const aggregate = {
         mrr: current.meanMrr - baseline.meanMrr,
@@ -145,7 +148,10 @@ export function compareSummaries(baseline, current) {
         onlyInCurrent: [...curById.keys()].filter((id) => !baseById.has(id)),
     };
 }
-/** For each memory, use its first 8 content words as a trivial query and expect that memory back: a smoke test for recall. */
+/**
+ * For each memory, use its first 8 content words as a trivial query and expect that memory back: a smoke test for
+ * recall.
+ */
 export function bootstrapCorpus(entries, maxCases = 50) {
     const cases = [];
     for (const e of entries) {

package/dist/eval/judgment.js

@@ -3,14 +3,18 @@
  *  every captured memory currently lands on a flat schema_fit of 0.5. */
 import { fetchWithRetry } from '../util/http-retry.js';
 import { errorFields, errorMessage, log } from '../util/log.js';
-import { readCappedJson } from '../util/capped-json.js';
+import { readCappedJson, readCappedText } from '../util/capped-json.js';
 import { isJsonNumber, isJsonObject, isJsonString } from '../util/json.js';
 const ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
 const DEFAULT_MODEL = 'jev-1.13.0';
 const MAX_CONCURRENCY = 8;
 // An honest reply is three short answers, a few hundred bytes; 1 MiB leaves room for a verbose envelope.
 const JUDGE_MAX_REPLY_BYTES = 1024 * 1024;
-/** One named answer of a Jev reply `{ answers: { <name>: Answer } }`; an empty object when the reply has none of that shape. */
+const JUDGE_MAX_ERROR_BYTES = 4096;
+/**
+ * One named answer of a Jev reply `{ answers: { <name>: Answer } }`; an empty object when the reply has none of that
+ * shape.
+ */
 function answerNamed(reply, name) {
     const answers = isJsonObject(reply) ? reply.answers : undefined;
     const answer = isJsonObject(answers) ? answers[name] : undefined;
@@ -19,9 +23,12 @@ 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',
@@ -81,7 +88,10 @@ async function post(content, opts) {
     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);
+    const snippet = (await readCappedText(res, JUDGE_MAX_ERROR_BYTES).catch((err) => {
+        log.debug(`judge: error body unreadable: ${errorMessage(err)}`, errorFields(err));
+        return '';
+    })).slice(0, 200);
     log.warn('judge: non-2xx reply', { status: res.status, body: snippet });
     return null;
 }

package/dist/graph/delta.d.ts

@@ -1,45 +1,12 @@
-import type { DatabaseSyncLike } from '../db/index.js';
-import type { EntityType, RelationType, SourceObjectRef } from '../store/graph-rows.js';
-/** What names an object-derived entity across rebuilds; v38 has no UNIQUE on it, so the diff keeps one row per key. */
-export interface NaturalKey {
-    readonly entityType: EntityType;
-    readonly sourceObject: SourceObjectRef;
-}
-export interface DesiredEntity extends NaturalKey {
-    readonly name: string;
-    readonly memoryId: string | null;
-}
-export interface DesiredRelation {
-    readonly from: NaturalKey;
-    readonly to: NaturalKey;
-    readonly relType: RelationType;
-    readonly memoryId: string | null;
-    readonly sourceObject: SourceObjectRef;
-}
-export interface DesiredGraph {
-    readonly entities: readonly DesiredEntity[];
-    readonly relations: readonly DesiredRelation[];
-}
-export type GraphOp = {
-    readonly op: 'deleteEntity';
-    readonly id: number;
-} | {
-    readonly op: 'updateEntity';
-    readonly id: number;
-    readonly entity: DesiredEntity;
-} | {
-    readonly op: 'insertEntity';
-    readonly entity: DesiredEntity;
-} | {
-    readonly op: 'deleteRelation';
-    readonly id: number;
-} | {
-    readonly op: 'insertRelation';
-    readonly relation: DesiredRelation;
-};
+import type { DesiredEntity, DesiredGraph, DesiredRelation, GraphOp, NaturalKey, StoredGraph } from '../store/graph-rows.js';
+export type { DesiredEntity, DesiredGraph, DesiredRelation, GraphOp, NaturalKey };
 export declare function entityKey(k: NaturalKey): string;
-/** Ops that turn the stored graph into `desired`, in apply order; reads only, and keeps the lowest id per natural key. */
-export declare function graphDelta(db: DatabaseSyncLike, tenantId: string, desired: DesiredGraph): GraphOp[];
-/** graphDelta on its own connection and outside any write lock; the apply re-checks each op against what changed since. */
+export declare function memoryIdsOf(desired: DesiredGraph): string[];
+/** The diff itself: pure, so the store reads the rows and this decides the ops. */
+export declare function diffGraph(stored: StoredGraph, desired: DesiredGraph): GraphOp[];
+/**
+ * Ops that turn the stored graph into `desired`, in apply order; read outside any write lock, so the apply re-checks
+ * each op against what changed since. Keeps the lowest id per natural key.
+ */
 export declare function readGraphDelta(hippoRoot: string, tenantId: string, desired: DesiredGraph): GraphOp[];
 //# sourceMappingURL=delta.d.ts.map

package/dist/graph/delta.js

@@ -1,4 +1,6 @@
-import { loadStoredGraph, storedGraphOn } from '../store/graph-reads.js';
+// Diffs the derived graph against the stored rows, so a rebuild writes only what changed and an entity keeps the id its
+// relations hang on.
+import { loadStoredGraph } from '../store/graph-reads.js';
 const keyText = (entityType, objectType, objectId) => `${entityType}|${objectType}:${objectId}`;
 export function entityKey(k) {
     return keyText(k.entityType, k.sourceObject.type, k.sourceObject.id);
@@ -14,7 +16,7 @@ function provenanceOf(memoryId, kinds) {
     const kind = memoryId === null ? undefined : kinds.get(memoryId);
     return kind === undefined ? '|distilled' : `${memoryId}|${kind}`;
 }
-function memoryIdsOf(desired) {
+export function memoryIdsOf(desired) {
     const ids = new Set();
     for (const row of [...desired.entities, ...desired.relations])
         if (row.memoryId !== null)
@@ -47,7 +49,8 @@ function diffEntities(stored, desired, kinds) {
         const row = kept.get(key);
         if (!row)
             inserts.push({ op: 'insertEntity', entity });
-        else if (row.name !== entity.name || `${row.memory_id ?? ''}|${row.source_kind}` !== provenanceOf(entity.memoryId, kinds)) {
+        else if (row.name !== entity.name ||
+            `${row.memory_id ?? ''}|${row.source_kind}` !== provenanceOf(entity.memoryId, kinds)) {
             updates.push({ op: 'updateEntity', id: row.id, entity });
         }
     }
@@ -80,16 +83,19 @@ function diffRelations(stored, desired, keptKeyById, kinds) {
             inserts.push({ op: 'insertRelation', relation });
     return [...deletes, ...inserts];
 }
-function deltaOf(stored, desired) {
+/** The diff itself: pure, so the store reads the rows and this decides the ops. */
+export function diffGraph(stored, desired) {
     const entityDelta = diffEntities(stored.entities, desired.entities, stored.kinds);
-    return [...entityDelta.ops, ...diffRelations(stored.relations, desired.relations, entityDelta.keptKeyById, stored.kinds)];
+    return [
+        ...entityDelta.ops,
+        ...diffRelations(stored.relations, desired.relations, entityDelta.keptKeyById, stored.kinds),
+    ];
 }
-/** Ops that turn the stored graph into `desired`, in apply order; reads only, and keeps the lowest id per natural key. */
-export function graphDelta(db, tenantId, desired) {
-    return deltaOf(storedGraphOn(db, tenantId, memoryIdsOf(desired)), desired);
-}
-/** graphDelta on its own connection and outside any write lock; the apply re-checks each op against what changed since. */
+/**
+ * Ops that turn the stored graph into `desired`, in apply order; read outside any write lock, so the apply re-checks
+ * each op against what changed since. Keeps the lowest id per natural key.
+ */
 export function readGraphDelta(hippoRoot, tenantId, desired) {
-    return deltaOf(loadStoredGraph(hippoRoot, tenantId, memoryIdsOf(desired)), desired);
+    return diffGraph(loadStoredGraph(hippoRoot, tenantId, memoryIdsOf(desired)), desired);
 }
 //# sourceMappingURL=delta.js.map

package/dist/graph/extract.d.ts

@@ -1,9 +1,12 @@
-/** Deterministic entity extraction: the graph is a pure function of the consolidated object tables (decisions, policies, customer_notes, project_briefs).
- *  Writes go through the src/store/graph-writes.ts consolidated-source guard. Pass 3 adds `references` edges by a conservative name-match heuristic. */
+/** Deterministic entity extraction: the graph is a pure function of the consolidated object tables
+ *  (decisions, policies, customer_notes, project_briefs). Writes go through the src/store/graph-writes.ts
+ *  consolidated-source guard. Pass 3 adds `references` edges by a conservative name-match heuristic. */
 import { type EntityType } from '../store/graph-rows.js';
 import { type DesiredGraph } from './delta.js';
 import { type WriteBudget } from '../util/write-budget.js';
-/** Per-type load cap (the loaders default to 100); a type over it is truncated and `ExtractResult.truncated` records that. */
+import type { Objects } from '../store/port.js';
+/** Per-type load cap (the loaders default to 100); a type over it is truncated and
+ *  `ExtractResult.truncated` records that. */
 export declare const MAX_EXTRACT_PER_TYPE = 10000;
 /** A target entity name must be in [MIN, MAX] chars to be matched: MIN skips short, generic words; MAX skips prose
  *  (a decision's prose name is never a target, only a source). */
@@ -47,8 +50,8 @@ export interface LoadedType {
     /** True when either status load filled MAX_EXTRACT_PER_TYPE. */
     hitCap: boolean;
 }
-/** Every source type's rows, each read on its own connection; callers load before any write lock is taken. */
-export declare function loadGraphSources(hippoRoot: string, tenantId: string): LoadedType[];
+/** Every source type's rows; callers load before any write lock is taken. */
+export declare function loadGraphSources(objects: Objects, tenantId: string): Promise<LoadedType[]>;
 /** The graph the loaded objects imply, plus the counts ExtractResult reports. */
 export interface DerivedGraph extends DesiredGraph {
     byType: Record<string, number>;
@@ -59,8 +62,8 @@ export interface DerivedGraph extends DesiredGraph {
 export declare function deriveGraph(loaded: readonly LoadedType[]): DerivedGraph;
 /** Idempotent rebuild of the tenant's graph from its consolidated objects, in one transaction; safe to re-run.
  *  Returns the derived counts and which types hit the per-type cap. */
-export declare function extractGraph(hippoRoot: string, tenantId: string): ExtractResult;
+export declare function extractGraph(objects: Objects, hippoRoot: string, tenantId: string): Promise<ExtractResult>;
 /** extractGraph for sleep: diffs outside the lock, then applies in transactions of about `budget.holdMs` with a pause
  *  between them. A run stopped between chunks leaves a mixed graph that the next run's diff finishes. */
-export declare function extractGraphChunked(hippoRoot: string, tenantId: string, budget?: WriteBudget): Promise<ExtractResult>;
+export declare function extractGraphChunked(objects: Objects, hippoRoot: string, tenantId: string, budget?: WriteBudget): Promise<ExtractResult>;
 //# sourceMappingURL=extract.d.ts.map

package/dist/graph/extract.js

@@ -1,9 +1,9 @@
-/** Deterministic entity extraction: the graph is a pure function of the consolidated object tables (decisions, policies, customer_notes, project_briefs).
- *  Writes go through the src/store/graph-writes.ts consolidated-source guard. Pass 3 adds `references` edges by a conservative name-match heuristic. */
-import { applyGraphOps } from './write.js';
-import { runGraphRebuildTransaction } from '../store/graph-writes.js';
-import { MAX_ENTITY_NAME_LEN } from '../store/graph-rows.js';
-import { graphDelta, readGraphDelta } from './delta.js';
+/** Deterministic entity extraction: the graph is a pure function of the consolidated object tables
+ *  (decisions, policies, customer_notes, project_briefs). Writes go through the src/store/graph-writes.ts
+ *  consolidated-source guard. Pass 3 adds `references` edges by a conservative name-match heuristic. */
+import { applyGraphOps, rebuildGraphUnderLock } from '../store/graph-apply.js';
+import { MAX_ENTITY_NAME_LEN, } from '../store/graph-rows.js';
+import { diffGraph, memoryIdsOf, readGraphDelta, } from './delta.js';
 import { WRITE_BUDGET } from '../util/write-budget.js';
 import { SLEEP_DB_WAIT_MS } from '../db/index.js';
 import { loadDecisions } from '../objects/decisions.js';
@@ -12,7 +12,8 @@ import { loadCustomerNotes } from '../objects/customer-notes.js';
 import { loadProjectBriefs } from '../objects/project-briefs.js';
 import { assertTenantId } from '../store/tenant.js';
 import { escapeRegex } from '../util/escape.js';
-/** Per-type load cap (the loaders default to 100); a type over it is truncated and `ExtractResult.truncated` records that. */
+/** Per-type load cap (the loaders default to 100); a type over it is truncated and
+ *  `ExtractResult.truncated` records that. */
 export const MAX_EXTRACT_PER_TYPE = 10000;
 /** A target entity name must be in [MIN, MAX] chars to be matched: MIN skips short, generic words; MAX skips prose
  *  (a decision's prose name is never a target, only a source). */
@@ -49,18 +50,26 @@ function sourceObjectOf(entityType, e2Id) {
 function pairKey(a, b) {
     return a < b ? `${a}:${b}` : `${b}:${a}`;
 }
-/** Close over one loader's row type so the table below holds uniform functions. Loads ACTIVE and SUPERSEDED rows (not `closed`),
- *  one call per status, so MAX_EXTRACT_PER_TYPE is a per-status budget; `hitCap` is set when either load is full. */
+/** Close over one loader's row type so the table below holds uniform functions. Loads ACTIVE and SUPERSEDED rows
+ *  (not `closed`), one call per status, so MAX_EXTRACT_PER_TYPE is a per-status budget; `hitCap` is set when
+ *  either load is full. */
 function source(entityType, load, nameOf, textOf) {
-    return (hippoRoot, tenantId) => {
+    return async (objects, tenantId) => {
         const rows = [];
         let hitCap = false;
         for (const status of ['active', 'superseded']) {
-            const loaded = load(hippoRoot, tenantId, { status, limit: MAX_EXTRACT_PER_TYPE });
+            const loaded = await load(objects, tenantId, { status, limit: MAX_EXTRACT_PER_TYPE });
             if (loaded.length === MAX_EXTRACT_PER_TYPE)
                 hitCap = true;
             for (const r of loaded) {
-                rows.push({ entityType, e2Id: r.id, name: nameOf(r), searchText: textOf(r), memoryId: r.memoryId, supersededBy: r.supersededBy });
+                rows.push({
+                    entityType,
+                    e2Id: r.id,
+                    name: nameOf(r),
+                    searchText: textOf(r),
+                    memoryId: r.memoryId,
+                    supersededBy: r.supersededBy,
+                });
             }
         }
         return { entityType, rows, hitCap };
@@ -72,10 +81,10 @@ const GRAPH_SOURCES = [
     source('customer', loadCustomerNotes, (r) => r.customer, (r) => [r.customer, r.note].filter(Boolean).join(' ')),
     source('project', loadProjectBriefs, (r) => r.repo, (r) => [r.repo, r.summary].filter(Boolean).join(' ')),
 ];
-/** Every source type's rows, each read on its own connection; callers load before any write lock is taken. */
-export function loadGraphSources(hippoRoot, tenantId) {
+/** Every source type's rows; callers load before any write lock is taken. */
+export async function loadGraphSources(objects, tenantId) {
     assertTenantId('loadGraphSources', tenantId);
-    return GRAPH_SOURCES.map((load) => load(hippoRoot, tenantId));
+    return Promise.all(GRAPH_SOURCES.map((load) => load(objects, tenantId)));
 }
 /** The tenant's graph as a pure function of its loaded objects; the write side diffs it against what is stored. */
 export function deriveGraph(loaded) {
@@ -83,7 +92,12 @@ export function deriveGraph(loaded) {
     const supersedes = deriveSupersedes(pass);
     const references = deriveReferences(pass.created, supersedes.supersededPairs, pass.truncated);
     return {
-        entities: pass.created.map((e) => ({ entityType: e.entityType, sourceObject: e.sourceObject, name: e.name, memoryId: e.memoryId })),
+        entities: pass.created.map((e) => ({
+            entityType: e.entityType,
+            sourceObject: e.sourceObject,
+            name: e.name,
+            memoryId: e.memoryId,
+        })),
         relations: [...supersedes.relations, ...references],
         byType: pass.byType,
         truncated: pass.truncated,
@@ -201,33 +215,45 @@ function deriveReferences(created, supersededPairs, truncated) {
                 break;
         }
         for (const target of targets.values()) {
-            relations.push({ from: naturalKeyOf(src), to: naturalKeyOf(target), relType: 'references', memoryId: src.memoryId, sourceObject: src.sourceObject });
+            relations.push({
+                from: naturalKeyOf(src),
+                to: naturalKeyOf(target),
+                relType: 'references',
+                memoryId: src.memoryId,
+                sourceObject: src.sourceObject,
+            });
         }
     }
     return relations;
 }
 function resultOf(derived, skipped) {
     const { entities, relations, references, byType, truncated } = derived;
-    const result = { entities: entities.length, relations: relations.length, references, byType, truncated };
+    const result = {
+        entities: entities.length,
+        relations: relations.length,
+        references,
+        byType,
+        truncated,
+    };
     if (skipped > 0)
         result.skipped = skipped;
     return result;
 }
 /** Idempotent rebuild of the tenant's graph from its consolidated objects, in one transaction; safe to re-run.
  *  Returns the derived counts and which types hit the per-type cap. */
-export function extractGraph(hippoRoot, tenantId) {
+export async function extractGraph(objects, hippoRoot, tenantId) {
     assertTenantId('extractGraph', tenantId);
     // Loaded first: opening a second connection under the rebuild's BEGIN IMMEDIATE dead-locks ('database is locked').
-    const derived = deriveGraph(loadGraphSources(hippoRoot, tenantId));
+    const derived = deriveGraph(await loadGraphSources(objects, 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, tenantId, graphDelta(txDb, tenantId, derived), { from: 0, holdMs: Infinity }).skipped);
+    const skipped = rebuildGraphUnderLock(hippoRoot, tenantId, memoryIdsOf(derived), (stored) => diffGraph(stored, derived));
     return resultOf(derived, skipped);
 }
 /** extractGraph for sleep: diffs outside the lock, then applies in transactions of about `budget.holdMs` with a pause
  *  between them. A run stopped between chunks leaves a mixed graph that the next run's diff finishes. */
-export async function extractGraphChunked(hippoRoot, tenantId, budget = WRITE_BUDGET) {
+export async function extractGraphChunked(objects, hippoRoot, tenantId, budget = WRITE_BUDGET) {
     assertTenantId('extractGraphChunked', tenantId);
-    const derived = deriveGraph(loadGraphSources(hippoRoot, tenantId));
+    const derived = deriveGraph(await loadGraphSources(objects, tenantId));
     const ops = readGraphDelta(hippoRoot, tenantId, derived);
     let next = 0;
     let skipped = 0;
@@ -236,8 +262,14 @@ export async function extractGraphChunked(hippoRoot, tenantId, budget = WRITE_BU
         if (next > 0)
             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, tenantId, ops, { from, holdMs: budget.holdMs, clock: budget.clock }), { busyWaitMs: SLEEP_DB_WAIT_MS });
+        // 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 = applyGraphOps(hippoRoot, 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.d.ts

@@ -27,16 +27,24 @@ export interface GraphExpandOpts {
     /** The recall --min-results floor: this many top base rows are kept regardless of
      *  budget, so graph expansion never violates the floor. Defaults to 1. */
     minResults?: number;
-    /** Recall-side scope rule applied to graph-REACHED memories only (base results already passed the caller), mirroring HybridSearchOptions.recallScope.
+    /**
+     * Recall-side scope rule applied to graph-REACHED memories only (base results already passed the caller), mirroring
+     * HybridSearchOptions.recallScope.
      *  Omitted = default-deny (private and quarantine excluded, NULL passes), the fail-closed default for SDK callers.
-     *  { requested, additive: true } is CLI --scope unlock (passesCliRecallScopeFilter); otherwise exact narrowing (passesScopeFilterForRecall). */
+     * { requested, additive: true } is CLI --scope unlock (passesCliRecallScopeFilter); otherwise exact narrowing
+     * (passesScopeFilterForRecall).
+     */
     recallScope?: {
         requested?: string;
         additive?: boolean;
         ownScope?: string;
     };
 }
-/** Augment `baseResults` with memories reached by walking `hops` graph edges from the seeds across local AND global stores, each placed after its seed.
- *  Returns `baseResults` unchanged when `hops <= 0`, there are no base results, or nothing new survives the filters and the token budget. */
+/**
+ * Augment `baseResults` with memories reached by walking `hops` graph edges from the seeds across local AND global
+ * stores, each placed after its seed.
+ * Returns `baseResults` unchanged when `hops <= 0`, there are no base results, or nothing new survives the filters and
+ * the token budget.
+ */
 export declare function graphExpandRecall(baseResults: SearchResult[], opts: GraphExpandOpts): SearchResult[];
 //# sourceMappingURL=recall.d.ts.map

package/dist/graph/recall.js

@@ -1,6 +1,11 @@
-/** Multi-hop graph recall: a READ-ONLY walk of the relations graph from the lexical seeds, surfacing reached entities' memories the lexical search missed.
- *  Reached rows load by id (not intersected with the lexically prefiltered candidates), then the recall hard filters are re-applied.
- *  Hits inherit their seed's score minus a per-hop discount; both stores are expanded; no writes, so check-graph-writes permits it outside graph.ts. */
+/**
+ * Multi-hop graph recall: a READ-ONLY walk of the relations graph from the lexical seeds, surfacing reached entities'
+ * memories the lexical search missed.
+ * Reached rows load by id (not intersected with the lexically prefiltered candidates), then the recall hard filters are
+ * re-applied.
+ * Hits inherit their seed's score minus a per-hop discount; both stores are expanded; no writes, so check-graph-writes
+ * permits it outside graph.ts.
+ */
 import { loadEntriesByIds } from '../store/entry-reads.js';
 import { DEFAULT_RECALL_BUDGET } from '../core/search-types.js';
 import { estimateTokens } from '../util/token-text.js';
@@ -29,10 +34,12 @@ function loadByIdsChunked(root, tenantId, ids) {
 }
 /** BFS, both directions, up to `hops`: each reached entity's via, and the base memory it descends from. */
 function walkRelations(root, tenantId, seedEntities, hops, maxNeighbors) {
-    // `visited` makes expansion cycle-safe; `originMemByEntityId` carries each node's base-result memory id for adjacency placement and score inheritance.
+    // `visited` makes expansion cycle-safe; `originMemByEntityId` carries each node's base-result memory id for adjacency
+    // placement and score inheritance.
     const visitedEntityIds = new Set(seedEntities.map((e) => e.id));
     const reached = new Map();
-    // A seed/reached entity whose mirror was forgotten or pruned has a null memoryId; traversal still propagates origin and the null is dropped before any load.
+    // A seed/reached entity whose mirror was forgotten or pruned has a null memoryId; traversal still propagates origin
+    // and the null is dropped before any load.
     const originMemByEntityId = new Map();
     for (const se of seedEntities)
         originMemByEntityId.set(se.id, se.memoryId);
@@ -79,7 +86,8 @@ function walkRelations(root, tenantId, seedEntities, hops, maxNeighbors) {
 /** The recall hard filters (as-of, superseded, scope) re-applied to a directly loaded graph-reached row. */
 function passesRecallFilters(mem, via, successorValidFrom, opts) {
     const { includeSuperseded, asOfDate, recallScope } = opts;
-    // The `to` endpoint of a `supersedes` edge IS the superseded version; the graph is authoritative because `hippo decide` does not set `superseded_by`.
+    // The `to` endpoint of a `supersedes` edge IS the superseded version; the graph is authoritative because `hippo
+    // decide` does not set `superseded_by`.
     // Drop it unless --include-superseded; the newer `from` endpoint is always kept.
     const isSupersededEndpoint = via.relType === 'supersedes' && via.direction === 'to';
     if (asOfDate) {
@@ -96,7 +104,8 @@ function passesRecallFilters(mem, via, successorValidFrom, opts) {
         return false; // default recall drops superseded
     }
     return recallScope.additive
-        ? passesCliRecallScopeFilter(mem.scope ?? null, recallScope.requested) || passesScopeFilterForRecall(mem.scope ?? null, undefined, recallScope.ownScope)
+        ? passesCliRecallScopeFilter(mem.scope ?? null, recallScope.requested) ||
+            passesScopeFilterForRecall(mem.scope ?? null, undefined, recallScope.ownScope)
         : passesScopeFilterForRecall(mem.scope ?? null, recallScope.requested, recallScope.ownScope);
 }
 /** Traverse one store's graph from its seeds into `hitsByOrigin`. Pure reads; mutates `seenMemoryIds`
@@ -146,7 +155,8 @@ function buildGraphHit(mem, via, originScore) {
         graphVia: via,
     };
 }
-// Reached entities -> source memory ids -> load by id (chunked). A mirror-less entity (memoryId === null) has no memory to surface,
+// Reached entities -> source memory ids -> load by id (chunked). A mirror-less entity (memoryId === null) has no memory
+// to surface,
 // so drop its null id before it reaches loadByIdsChunked.
 function loadReachedMemories(root, tenantId, reachedEntities, seenMemoryIds) {
     const needLoad = [...new Set(reachedEntities
@@ -162,8 +172,12 @@ function loadSuccessorValidFrom(root, tenantId, loadedById, asOfDate) {
     const succIds = [...new Set([...loadedById.values()].map((m) => m.superseded_by).filter((id) => !!id))];
     return new Map(loadByIdsChunked(root, tenantId, succIds).map((m) => [m.id, m.valid_from]));
 }
-/** Augment `baseResults` with memories reached by walking `hops` graph edges from the seeds across local AND global stores, each placed after its seed.
- *  Returns `baseResults` unchanged when `hops <= 0`, there are no base results, or nothing new survives the filters and the token budget. */
+/**
+ * Augment `baseResults` with memories reached by walking `hops` graph edges from the seeds across local AND global
+ * stores, each placed after its seed.
+ * Returns `baseResults` unchanged when `hops <= 0`, there are no base results, or nothing new survives the filters and
+ * the token budget.
+ */
 export function graphExpandRecall(baseResults, opts) {
     const { hops, hippoRoot, globalRoot, tenantId } = opts;
     if (hops <= 0 || baseResults.length === 0)
@@ -191,7 +205,8 @@ export function graphExpandRecall(baseResults, opts) {
     return mergeKeptHits(baseResults, hitsByOrigin, keep);
 }
 function sortHitsWithinOrigin(hitsByOrigin) {
-    // Closer hops first within each origin group, then by inherited score; compareEntryIdentity only breaks same-hop, same-score ties.
+    // Closer hops first within each origin group, then by inherited score; compareEntryIdentity only breaks same-hop,
+    // same-score ties.
     for (const hits of hitsByOrigin.values()) {
         hits.sort((a, b) => {
             const byHops = a.graphVia.hops - b.graphVia.hops;
@@ -205,8 +220,10 @@ function sortHitsWithinOrigin(hitsByOrigin) {
 function selectWithinBudget(baseResults, allHits, opts) {
     const budget = opts.budget ?? DEFAULT_RECALL_BUDGET;
     const minResults = opts.minResults ?? 1;
-    // Budget selection is by score, not position, so a high-value graph hit can beat a low-score lexical distractor; the greedy pack uses `continue`,
-    // so the DISPLAY loop emits a hit only under a kept seed. The top --min-results base rows are never evicted; at least one result is kept.
+    // Budget selection is by score, not position, so a high-value graph hit can beat a low-score lexical distractor; the
+    // greedy pack uses `continue`,
+    // so the DISPLAY loop emits a hit only under a kept seed. The top --min-results base rows are never evicted; at least
+    // one result is kept.
     const protectedCount = Math.min(Math.max(minResults, 1), baseResults.length);
     const keep = new Set(baseResults.slice(0, protectedCount));
     const price = opts.cost ?? ((r) => r.tokens);

package/dist/graph/stream.d.ts

@@ -1,6 +1,11 @@
-/** Graph-retrieval ranked-list stream for RRF fusion: READ-ONLY, ranks `entries[]` indices by graph proximity to the strong lexical seeds.
- *  Unlike graph recall it only re-ranks in-pool, graph-reached, non-seed entries; scoring seeds would double-count BM25/dense.
- *  The score scale only sets the order inside this stream (RRF re-ranks by 1/(k + graphRank)), so do not tune it for a fused-score effect. */
+/**
+ * Graph-retrieval ranked-list stream for RRF fusion: READ-ONLY, ranks `entries[]` indices by graph proximity to the
+ * strong lexical seeds.
+ * Unlike graph recall it only re-ranks in-pool, graph-reached, non-seed entries; scoring seeds would double-count
+ * BM25/dense.
+ * The score scale only sets the order inside this stream (RRF re-ranks by 1/(k + graphRank)), so do not tune it for a
+ * fused-score effect.
+ */
 import type { MemoryEntry } from '../core/memory.js';
 /** Default hops expanded from each seed (MVP; hard cap MAX_HOPS=3 reused from graph recall). */
 export declare const DEFAULT_GRAPH_HOPS = 2;
@@ -30,9 +35,16 @@ export interface GraphStreamOpts {
     /** Per-hop fanout cap. Default DEFAULT_MAX_NEIGHBORS. */
     maxNeighbors?: number;
 }
-/** Pick the top `seedCount` candidates by best lexical rank (lowest position across BM25 and dense), strength = 1/(bestRank + 1). Pure. */
+/**
+ * Pick the top `seedCount` candidates by best lexical rank (lowest position across BM25 and dense), strength =
+ * 1/(bestRank + 1). Pure.
+ */
 export declare function selectGraphSeeds(bm25Ranked: ReadonlyArray<number>, cosineRanked: ReadonlyArray<number>, seedCount: number): GraphSeed[];
-/** Produce the graph-retrieval ranked list: `entries[]` indices by graph proximity (desc) to the lexical `seeds`; absent indices fall to rrfFuse absentRank.
- *  Returns `[]` when there are no seeds/entries, the graph is empty, or nothing reached is in-pool, so the caller skips the 3rd fusion list. */
+/**
+ * Produce the graph-retrieval ranked list: `entries[]` indices by graph proximity (desc) to the lexical `seeds`; absent
+ * indices fall to rrfFuse absentRank.
+ * Returns `[]` when there are no seeds/entries, the graph is empty, or nothing reached is in-pool, so the caller skips
+ * the 3rd fusion list.
+ */
 export declare function graphRankStream(entries: ReadonlyArray<MemoryEntry>, seeds: ReadonlyArray<GraphSeed>, opts: GraphStreamOpts): number[];
 //# sourceMappingURL=stream.d.ts.map