hippo-memory 1.68.0 → 1.70.0

package/dist/{judgment.js → eval/judgment.js}

@@ -1,9 +1,8 @@
 /** Typed judgment over capture candidates via TypeSafe's Jev (System One).
  *  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 { envTypesafeApiKey } from './env.js';
-import { fetchWithRetry } from './http-retry.js';
-import { log } from './log.js';
+import { fetchWithRetry } from '../util/http-retry.js';
+import { errorMessage, log } from '../util/log.js';
 const ENDPOINT = 'https://api.typesafe.ai/v1/systemone';
 const DEFAULT_MODEL = 'jev-1.13.0';
 const MAX_CONCURRENCY = 8;
@@ -36,10 +35,6 @@ const QUESTIONS = {
 };
 const KINDS = ['error', 'decision', 'convention', 'preference', 'trivia'];
 const VALENCES = ['critical', 'negative', 'positive', 'neutral'];
-/** Absent key means hippo keeps its pre-Jev behaviour and makes no HTTP call. */
-export function judgmentApiKey() {
-    return envTypesafeApiKey();
-}
 function oneOf(value, allowed) {
     return allowed.find((option) => option === value) ?? null;
 }
@@ -68,7 +63,7 @@ async function post(content, opts) {
         }, { timeoutMs: JUDGE_TIMEOUT_MS, fetchFn: opts.fetcher });
     }
     catch (err) {
-        log.debug(`judge: request failed: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`judge: request failed: ${errorMessage(err)}`);
         return null;
     }
     return res.ok ? res : null;
@@ -90,7 +85,7 @@ export async function judge(content, opts) {
         data = await res.json();
     }
     catch (err) {
-        log.debug(`judge: unreadable response: ${err instanceof Error ? err.message : String(err)}`);
+        log.debug(`judge: unreadable response: ${errorMessage(err)}`);
         return null;
     }
     const durable = data.answers?.durable?.noul;

package/dist/extensions/openclaw-plugin/index.js

@@ -226,9 +226,8 @@ export default function register(api) {
         async execute(_id, params) {
             const cfg = getConfig(api);
             const budget = params.budget ?? cfg.budget ?? 1500;
-            const framing = cfg.framing ?? 'observe';
             const hippoCwd = resolveHippoCwdFromContext(api, ctx, cfg.root);
-            const result = runHippo(['recall', params.query, '--budget', String(budget), '--framing', framing], hippoCwd);
+            const result = runHippo(['recall', params.query, '--budget', String(budget)], hippoCwd);
             return { content: [{ type: 'text', text: result || 'No relevant memories found.' }] };
         },
     }));

package/dist/graph/delta.d.ts

@@ -1,4 +1,5 @@
-import type { GraphTxDb, EntityType, RelationType, SourceObjectRef } from './types.js';
+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;
@@ -38,7 +39,7 @@ export type GraphOp = {
 };
 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: GraphTxDb, tenantId: string, desired: DesiredGraph): GraphOp[];
+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 readGraphDelta(hippoRoot: string, tenantId: string, desired: DesiredGraph): GraphOp[];
 //# sourceMappingURL=delta.d.ts.map

package/dist/graph/delta.js

@@ -1,5 +1,4 @@
-// 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 { openHippoDb, closeHippoDb } from '../db.js';
+import { loadStoredGraph, storedGraphOn } 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);
@@ -15,17 +14,12 @@ function provenanceOf(memoryId, kinds) {
     const kind = memoryId === null ? undefined : kinds.get(memoryId);
     return kind === undefined ? '|distilled' : `${memoryId}|${kind}`;
 }
-function memoryKindsOf(db, desired) {
+function memoryIdsOf(desired) {
     const ids = new Set();
     for (const row of [...desired.entities, ...desired.relations])
         if (row.memoryId !== null)
             ids.add(row.memoryId);
-    if (ids.size === 0)
-        return new Map();
-    // SAFETY: the SELECT names exactly the two columns of the row type.
-    const rows = db.prepare(`SELECT id, kind FROM memories WHERE id IN (SELECT value FROM json_each(?))`)
-        .all(JSON.stringify([...ids]));
-    return new Map(rows.map((r) => [r.id, r.kind]));
+    return [...ids];
 }
 function firstByKey(rows, keyOf) {
     const out = new Map();
@@ -86,24 +80,16 @@ function diffRelations(stored, desired, keptKeyById, kinds) {
             inserts.push({ op: 'insertRelation', relation });
     return [...deletes, ...inserts];
 }
+function deltaOf(stored, desired) {
+    const entityDelta = diffEntities(stored.entities, desired.entities, 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) {
-    const kinds = memoryKindsOf(db, desired);
-    // SAFETY: the SELECT names exactly the columns of StoredEntity.
-    const entities = db.prepare(`SELECT id, entity_type, name, memory_id, source_kind, source_object_type, source_object_id FROM entities WHERE tenant_id = ? ORDER BY id`).all(tenantId);
-    // SAFETY: the SELECT names exactly the columns of StoredRelation.
-    const relations = db.prepare(`SELECT id, from_entity_id, to_entity_id, rel_type, memory_id, source_kind, source_object_type, source_object_id FROM relations WHERE tenant_id = ? ORDER BY id`).all(tenantId);
-    const entityDelta = diffEntities(entities, desired.entities, kinds);
-    return [...entityDelta.ops, ...diffRelations(relations, desired.relations, entityDelta.keptKeyById, kinds)];
+    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. */
 export function readGraphDelta(hippoRoot, tenantId, desired) {
-    const db = openHippoDb(hippoRoot);
-    try {
-        return graphDelta(db, tenantId, desired);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    return deltaOf(loadStoredGraph(hippoRoot, tenantId, memoryIdsOf(desired)), desired);
 }
 //# sourceMappingURL=delta.js.map

package/dist/{graph-extract.d.ts → graph/extract.d.ts}

@@ -7,7 +7,7 @@
  * entities + `supersedes` relations from decisions /
  * policies / customer_notes / project_briefs (the four object types whose kind maps to the
  * `entity_type` enum), then write only their difference from the stored rows. All writes go
- * through the src/graph/write.ts consolidated-source guard; this module issues no raw SQL.
+ * through the src/store/graph-writes.ts consolidated-source guard; this module issues no raw SQL.
  *
  * Pass 3 adds the
  * first CROSS-OBJECT relations: a deterministic NAME-MATCH heuristic that emits a
@@ -19,9 +19,9 @@
  * skill/incident/process entities (not in the entity_type enum - needs a migration); the
  * `hippo sleep` enqueue-hook.
  */
-import { type EntityType } from './graph/types.js';
-import { type DesiredGraph } from './graph/delta.js';
-import { type WriteBudget } from './write-budget.js';
+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 whose active or superseded
  *  set exceeds this is truncated; `ExtractResult.truncated` records it so the
  *  incompleteness is observable rather than silent. */
@@ -62,7 +62,7 @@ export interface ExtractRow {
     /** The successor's object id (Y) when this row (X) is superseded; null otherwise. */
     supersededBy: number | null;
 }
-/** One object type's loaded rows. */
+/** One object type's rows, loaded and normalised. */
 export interface LoadedType {
     entityType: EntityType;
     rows: ExtractRow[];
@@ -85,4 +85,4 @@ export declare function extractGraph(hippoRoot: string, tenantId: string): Extra
 /** 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>;
-//# sourceMappingURL=graph-extract.d.ts.map
+//# sourceMappingURL=extract.d.ts.map

package/dist/{graph-extract.js → graph/extract.js}

@@ -7,7 +7,7 @@
  * entities + `supersedes` relations from decisions /
  * policies / customer_notes / project_briefs (the four object types whose kind maps to the
  * `entity_type` enum), then write only their difference from the stored rows. All writes go
- * through the src/graph/write.ts consolidated-source guard; this module issues no raw SQL.
+ * through the src/store/graph-writes.ts consolidated-source guard; this module issues no raw SQL.
  *
  * Pass 3 adds the
  * first CROSS-OBJECT relations: a deterministic NAME-MATCH heuristic that emits a
@@ -19,17 +19,18 @@
  * skill/incident/process entities (not in the entity_type enum - needs a migration); the
  * `hippo sleep` enqueue-hook.
  */
-import { applyGraphOps, runGraphRebuildTransaction } from './graph/write.js';
-import { MAX_ENTITY_NAME_LEN } from './graph/types.js';
-import { graphDelta, readGraphDelta } from './graph/delta.js';
-import { WRITE_BUDGET } from './write-budget.js';
-import { SLEEP_DB_WAIT_MS } from './db.js';
-import { loadDecisions } from './decisions.js';
-import { loadPolicies } from './policies.js';
-import { loadCustomerNotes } from './customer-notes.js';
-import { loadProjectBriefs } from './project-briefs.js';
-import { assertTenantId } from './tenant.js';
-import { escapeRegex } from './escape.js';
+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';
+import { WRITE_BUDGET } from '../util/write-budget.js';
+import { SLEEP_DB_WAIT_MS } from '../db/index.js';
+import { loadDecisions } from '../objects/decisions.js';
+import { loadPolicies } from '../objects/policies.js';
+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 whose active or superseded
  *  set exceeds this is truncated; `ExtractResult.truncated` records it so the
  *  incompleteness is observable rather than silent. */
@@ -72,51 +73,35 @@ function pairKey(a, b) {
     return a < b ? `${a}:${b}` : `${b}:${a}`;
 }
 /**
- * Load a type's ACTIVE + SUPERSEDED rows (excluding `closed` = retired), normalised.
- * Calls the loader once per status so MAX_EXTRACT_PER_TYPE is a per-status budget
- * (closed rows never consume it). Sets `hitCap` when either status load is full.
+ * Close over one loader's row type so the table below holds uniform functions without erasing it.
+ * Loads ACTIVE + SUPERSEDED rows (excluding `closed` = retired) in one call per status, so
+ * MAX_EXTRACT_PER_TYPE is a per-status budget; `hitCap` is set when either load is full.
  */
-function loadType(hippoRoot, tenantId, entityType, 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-loadFn, 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-nameOf, 
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-textOf) {
-    const rows = [];
-    let hitCap = false;
-    for (const status of ['active', 'superseded']) {
-        const loaded = loadFn(hippoRoot, tenantId, { status, limit: MAX_EXTRACT_PER_TYPE });
-        if (loaded.length === MAX_EXTRACT_PER_TYPE)
-            hitCap = true;
-        for (const r of loaded) {
-            // SAFETY: loadFn is always one of loadDecisions/loadPolicies/loadCustomerNotes/
-            // loadProjectBriefs (wired in GRAPH_SOURCES); every one of their row
-            // types declares id: number, memoryId: string | null, supersededBy: number | null.
-            // `any` here is the deliberate type-erasure boundary (see eslint-disable above)
-            // that lets one loop handle all four object row shapes.
-            rows.push({
-                entityType,
-                e2Id: r.id,
-                name: nameOf(r),
-                searchText: textOf(r),
-                memoryId: (r.memoryId ?? null),
-                supersededBy: (r.supersededBy ?? null),
-            });
+function source(entityType, load, nameOf, textOf) {
+    return (hippoRoot, tenantId) => {
+        const rows = [];
+        let hitCap = false;
+        for (const status of ['active', 'superseded']) {
+            const loaded = load(hippoRoot, 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 });
+            }
         }
-    }
-    return { entityType, rows, hitCap };
+        return { entityType, rows, hitCap };
+    };
 }
 const GRAPH_SOURCES = [
-    { entityType: 'decision', loadFn: loadDecisions, nameOf: (r) => r.decisionText, textOf: (r) => [r.decisionText, r.context].filter(Boolean).join(' ') },
-    { entityType: 'policy', loadFn: loadPolicies, nameOf: (r) => r.policyName, textOf: (r) => [r.policyName, r.policyText].filter(Boolean).join(' ') },
-    { entityType: 'customer', loadFn: loadCustomerNotes, nameOf: (r) => r.customer, textOf: (r) => [r.customer, r.note].filter(Boolean).join(' ') },
-    { entityType: 'project', loadFn: loadProjectBriefs, nameOf: (r) => r.repo, textOf: (r) => [r.repo, r.summary].filter(Boolean).join(' ') },
+    source('decision', loadDecisions, (r) => r.decisionText, (r) => [r.decisionText, r.context].filter(Boolean).join(' ')),
+    source('policy', loadPolicies, (r) => r.policyName, (r) => [r.policyName, r.policyText].filter(Boolean).join(' ')),
+    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) {
     assertTenantId('loadGraphSources', tenantId);
-    return GRAPH_SOURCES.map((src) => loadType(hippoRoot, tenantId, src.entityType, src.loadFn, src.nameOf, src.textOf));
+    return GRAPH_SOURCES.map((load) => load(hippoRoot, 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) {
@@ -261,7 +246,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), 0, { holdMs: Infinity }).skipped);
+    const skipped = runGraphRebuildTransaction(hippoRoot, tenantId, (txDb) => applyGraphOps(txDb, hippoRoot, 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
@@ -278,11 +263,11 @@ 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, hippoRoot, tenantId, ops, { from, holdMs: budget.holdMs, clock: budget.clock }), { busyWaitMs: SLEEP_DB_WAIT_MS });
         committedAt = budget.clock();
         next = chunk.next;
         skipped += chunk.skipped;
     }
     return resultOf(derived, skipped);
 }
-//# sourceMappingURL=graph-extract.js.map
+//# sourceMappingURL=extract.js.map

package/dist/{graph-recall.d.ts → graph/recall.d.ts}

@@ -1,4 +1,4 @@
-import { type ResultCost, type SearchResult } from './search/types.js';
+import { type ResultCost, type SearchResult } from '../core/search-types.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 declare const MAX_HOPS = 3;
@@ -52,4 +52,4 @@ export interface GraphExpandOpts {
  * graph is empty, no seed maps to an entity, or nothing new survives the filters/budget.
  */
 export declare function graphExpandRecall(baseResults: SearchResult[], opts: GraphExpandOpts): SearchResult[];
-//# sourceMappingURL=graph-recall.d.ts.map
+//# sourceMappingURL=recall.d.ts.map

package/dist/{graph-recall.js → graph/recall.js}

@@ -35,12 +35,12 @@
  * No graph writes (only SELECTs via graph.ts read helpers + store reads), so the
  * check-graph-writes lint permits this module living outside graph.ts.
  */
-import { loadEntriesByIds } from './store/entry-reads.js';
-import { DEFAULT_RECALL_BUDGET } from './search/types.js';
-import { estimateTokens } from './token-ledger.js';
-import { compareEntryIdentity } from './compare.js';
-import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations } from './graph/read.js';
-import { passesCliRecallScopeFilter, passesScopeFilterForRecall } from './recall-scope.js';
+import { loadEntriesByIds } from '../store/entry-reads.js';
+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';
 /** 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;
@@ -142,7 +142,8 @@ function passesRecallFilters(mem, via, successorValidFrom, opts) {
 }
 /** Traverse one store's graph from its seeds into `hitsByOrigin`. Pure reads; mutates `seenMemoryIds`
  *  and `seenContent` so a memory, or a share/promote copy of it, surfaces at most once across stores. */
-function produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds, seenContent, hitsByOrigin, opts) {
+function produceHitsForRoot(root, baseResults, accumulators, opts) {
+    const { baseScoreByMemId, seenMemoryIds, seenContent, hitsByOrigin } = accumulators;
     const { hops, maxNeighbors, tenantId, asOfDate } = opts;
     // Seeds = graph entities (in THIS store) whose source memory is a base result.
     const seedEntities = loadEntitiesByMemoryId(root, tenantId, baseResults.map((r) => r.entry.id));
@@ -151,22 +152,9 @@ function produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds,
     const { reached, originMemByEntityId } = walkRelations(root, tenantId, seedEntities, hops, maxNeighbors);
     if (reached.size === 0)
         return;
-    // Reached entities -> source memory ids -> load DIRECTLY by id (chunked), not lexical.
-    // A mirror-less reached entity (memoryId === null) has no memory to load: drop its null
-    // id BEFORE it reaches loadByIdsChunked / the Set<string> (it cannot be recall-surfaced;
-    // it stays in entities/relations for graph extract / visualization).
     const reachedEntities = loadEntitiesByIds(root, tenantId, [...reached.keys()]);
-    const needLoad = [...new Set(reachedEntities
-            .map((e) => e.memoryId)
-            .filter((id) => id !== null && !seenMemoryIds.has(id)))];
-    const loadedById = new Map(loadByIdsChunked(root, tenantId, needLoad).map((m) => [m.id, m]));
-    // For the bi-temporal as-of rule on a superseded reached row we need its successor's
-    // valid_from. Batch-load the successors referenced by the loaded rows.
-    let successorValidFrom = new Map();
-    if (asOfDate) {
-        const succIds = [...new Set([...loadedById.values()].map((m) => m.superseded_by).filter((id) => !!id))];
-        successorValidFrom = new Map(loadByIdsChunked(root, tenantId, succIds).map((m) => [m.id, m.valid_from]));
-    }
+    const loadedById = loadReachedMemories(root, tenantId, reachedEntities, seenMemoryIds);
+    const successorValidFrom = loadSuccessorValidFrom(root, tenantId, loadedById, asOfDate);
     for (const ent of reachedEntities) {
         if (ent.memoryId === null)
             continue; // mirror-less node: not recall-surfaced
@@ -184,18 +172,39 @@ function produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds,
         const originScore = baseScoreByMemId.get(origin) ?? baseResults[baseResults.length - 1].score;
         seenMemoryIds.add(mem.id);
         seenContent.add(mem.content);
-        const hit = {
-            entry: mem,
-            score: originScore * (1 - HOP_DISCOUNT * via.hops),
-            bm25: 0, cosine: 0,
-            tokens: estimateTokens(mem.content),
-            graphVia: via,
-        };
+        const hit = buildGraphHit(mem, via, originScore);
         if (!hitsByOrigin.has(origin))
             hitsByOrigin.set(origin, []);
         hitsByOrigin.get(origin).push(hit);
     }
 }
+function buildGraphHit(mem, via, originScore) {
+    return {
+        entry: mem,
+        score: originScore * (1 - HOP_DISCOUNT * via.hops),
+        bm25: 0, cosine: 0,
+        tokens: estimateTokens(mem.content),
+        graphVia: via,
+    };
+}
+// Reached entities -> source memory ids -> load DIRECTLY by id (chunked), not lexical.
+// A mirror-less reached entity (memoryId === null) has no memory to load: drop its null
+// id BEFORE it reaches loadByIdsChunked / the Set<string> (it cannot be recall-surfaced;
+// it stays in entities/relations for graph extract / visualization).
+function loadReachedMemories(root, tenantId, reachedEntities, seenMemoryIds) {
+    const needLoad = [...new Set(reachedEntities
+            .map((e) => e.memoryId)
+            .filter((id) => id !== null && !seenMemoryIds.has(id)))];
+    return new Map(loadByIdsChunked(root, tenantId, needLoad).map((m) => [m.id, m]));
+}
+// For the bi-temporal as-of rule on a superseded reached row we need its successor's
+// valid_from. Batch-load the successors referenced by the loaded rows.
+function loadSuccessorValidFrom(root, tenantId, loadedById, asOfDate) {
+    if (!asOfDate)
+        return new Map();
+    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 the graph `hops` edges out from
  * the seed results' entities (across the local AND global stores). Each graph hit is
@@ -211,10 +220,8 @@ export function graphExpandRecall(baseResults, opts) {
     if (hops <= 0 || baseResults.length === 0)
         return baseResults;
     const maxNeighbors = opts.maxNeighbors ?? DEFAULT_MAX_NEIGHBORS;
-    const budget = opts.budget ?? DEFAULT_RECALL_BUDGET;
     const includeSuperseded = opts.includeSuperseded ?? false;
     const asOfDate = opts.asOf ? new Date(opts.asOf) : null;
-    const minResults = opts.minResults ?? 1;
     const recallScope = opts.recallScope ?? {};
     const baseScoreByMemId = new Map(baseResults.map((r) => [r.entry.id, r.score]));
     const seenMemoryIds = new Set(baseResults.map((r) => r.entry.id));
@@ -223,12 +230,18 @@ export function graphExpandRecall(baseResults, opts) {
     // Expand against each distinct store the seeds may live in (local + global).
     const roots = globalRoot && globalRoot !== hippoRoot ? [hippoRoot, globalRoot] : [hippoRoot];
     for (const root of roots) {
-        produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds, seenContent, hitsByOrigin, {
+        produceHitsForRoot(root, baseResults, { baseScoreByMemId, seenMemoryIds, seenContent, hitsByOrigin }, {
             hops, maxNeighbors, tenantId, includeSuperseded, asOfDate, recallScope,
         });
     }
     if (hitsByOrigin.size === 0)
         return baseResults;
+    sortHitsWithinOrigin(hitsByOrigin);
+    const allHits = [...hitsByOrigin.values()].flat();
+    const keep = selectWithinBudget(baseResults, allHits, opts);
+    return mergeKeptHits(baseResults, hitsByOrigin, keep);
+}
+function sortHitsWithinOrigin(hitsByOrigin) {
     // Closer hops first within each origin group, then by inherited score.
     // Hops asc and score desc are both true primary keys (unchanged);
     // compareEntryIdentity is only the TAIL for a same-hop, same-score tie.
@@ -237,11 +250,14 @@ export function graphExpandRecall(baseResults, opts) {
             const byHops = a.graphVia.hops - b.graphVia.hops;
             if (byHops !== 0)
                 return byHops;
-            const byScore = b.score - a.score;
+            const byScore = compareScoresDesc(a.score, b.score);
             return byScore !== 0 ? byScore : compareEntryIdentity(a.entry, b.entry);
         });
     }
-    const allHits = [...hitsByOrigin.values()].flat();
+}
+function selectWithinBudget(baseResults, allHits, opts) {
+    const budget = opts.budget ?? DEFAULT_RECALL_BUDGET;
+    const minResults = opts.minResults ?? 1;
     // Budget SELECTION by score (not by position): a high-value graph hit (it inherits its
     // origin seed's relevance) must be able to win a token slot over a low-score lexical
     // distractor — otherwise a tight --budget keeps the noise and drops the memory --hops
@@ -259,13 +275,16 @@ export function graphExpandRecall(baseResults, opts) {
     let usedTokens = [...keep].reduce((s, r) => s + price(r), 0);
     // PLAIN stable score sort on purpose: both input lists are already deterministically
     // ordered, and a base-vs-graph-hit tie keeps the BASE result first (the concat order).
-    for (const r of [...baseResults.slice(protectedCount), ...allHits].sort((a, b) => b.score - a.score)) {
+    for (const r of [...baseResults.slice(protectedCount), ...allHits].sort((a, b) => compareScoresDesc(a.score, b.score))) {
         const tokens = price(r);
         if (usedTokens + tokens > budget)
             continue;
         usedTokens += tokens;
         keep.add(r);
     }
+    return keep;
+}
+function mergeKeptHits(baseResults, hitsByOrigin, keep) {
     // DISPLAY order: base order preserved (it may be MMR-diversified); each kept new hit
     // placed directly after the seed it descends from. Hits emit ONLY under a kept seed.
     const merged = [];
@@ -283,4 +302,4 @@ export function graphExpandRecall(baseResults, opts) {
     }
     return emittedHit ? merged : baseResults; // nothing new survived budget -> original base
 }
-//# sourceMappingURL=graph-recall.js.map
+//# sourceMappingURL=recall.js.map

package/dist/{graph-stream.d.ts → graph/stream.d.ts}

@@ -23,7 +23,7 @@
  * absolute magnitude is washed out by fusion. Do not tune the scale expecting a
  * fused-score effect — only the induced order matters.
  */
-import type { MemoryEntry } from './memory.js';
+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;
 /** Default per-hop multiplicative decay applied to the seed strength. */
@@ -67,4 +67,4 @@ export declare function selectGraphSeeds(bm25Ranked: ReadonlyArray<number>, cosi
  * entity, or nothing reached is in-pool — the caller then skips the 3rd fusion list.
  */
 export declare function graphRankStream(entries: ReadonlyArray<MemoryEntry>, seeds: ReadonlyArray<GraphSeed>, opts: GraphStreamOpts): number[];
-//# sourceMappingURL=graph-stream.d.ts.map
+//# sourceMappingURL=stream.d.ts.map

package/dist/{graph-stream.js → graph/stream.js}

@@ -1,5 +1,5 @@
-import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations } from './graph/read.js';
-import { MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from './graph-recall.js';
+import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations } from '../store/graph-reads.js';
+import { MAX_HOPS, DEFAULT_MAX_NEIGHBORS } from './recall.js';
 /** Default hops expanded from each seed (MVP; hard cap MAX_HOPS=3 reused from graph-recall). */
 export const DEFAULT_GRAPH_HOPS = 2;
 /** Default per-hop multiplicative decay applied to the seed strength. */
@@ -63,7 +63,8 @@ function bestStrengthAtDepth(rels, frontierSet, visited, frontierStrength, origi
     return bestStrengthThisDepth;
 }
 /** BFS from the seed entities: entityId -> best originSeedStrength x decay^depth over every reached entity. */
-function reachedEntityScores(root, tenantId, seedIds, originStrength, hops, decay, maxNeighbors) {
+function reachedEntityScores(root, tenantId, seedIds, originStrength, options) {
+    const { hops, decay, maxNeighbors } = options;
     const visited = new Set(seedIds); // seeds never re-reached
     const reachedScore = new Map(); // entityId -> best score
     let frontier = seedIds;
@@ -104,7 +105,8 @@ function reachedEntityScores(root, tenantId, seedIds, originStrength, hops, deca
  * carried UNCHANGED along each BFS path; the per-hop decay is applied as decay^depth so
  * a neighbour's score = originSeedStrength x decay^(graph distance).
  */
-function accumulateForRoot(root, seeds, entries, memIdToIndex, graphScore, hops, decay, maxNeighbors, tenantId) {
+function accumulateForRoot(root, seeds, entries, options) {
+    const { memIdToIndex, graphScore, hops, decay, maxNeighbors, tenantId } = options;
     if (seeds.length === 0)
         return;
     // The strongest seed strength per source memory id (a memId could appear once, but
@@ -127,7 +129,7 @@ function accumulateForRoot(root, seeds, entries, memIdToIndex, graphScore, hops,
         const st = strengthByMemId.get(e.memoryId) ?? 0;
         originStrength.set(e.id, Math.max(originStrength.get(e.id) ?? 0, st));
     }
-    const reachedScore = reachedEntityScores(root, tenantId, seedEntities.map((e) => e.id), originStrength, hops, decay, maxNeighbors);
+    const reachedScore = reachedEntityScores(root, tenantId, seedEntities.map((e) => e.id), originStrength, { hops, decay, maxNeighbors });
     if (reachedScore.size === 0)
         return;
     // Reached entity ids -> source memory ids -> in-pool entry indices.
@@ -166,7 +168,7 @@ export function graphRankStream(entries, seeds, opts) {
         ? [opts.hippoRoot, opts.globalRoot]
         : [opts.hippoRoot];
     for (const root of roots) {
-        accumulateForRoot(root, seeds, entries, memIdToIndex, graphScore, hops, decay, maxNeighbors, opts.tenantId);
+        accumulateForRoot(root, seeds, entries, { memIdToIndex, graphScore, hops, decay, maxNeighbors, tenantId: opts.tenantId });
     }
     // Seed-exclusion guard: graphScore is keyed by entryIndex
     // GLOBALLY across roots, but each root's BFS visited-set is per-root, so a memory that
@@ -182,4 +184,4 @@ export function graphRankStream(entries, seeds, opts) {
         return d !== 0 ? d : a - b; // score desc, then index asc (deterministic)
     });
 }
-//# sourceMappingURL=graph-stream.js.map
+//# sourceMappingURL=stream.js.map

package/dist/{graph-view.d.ts → graph/view.d.ts}

@@ -2,12 +2,13 @@
  * Graph observability and visualization, READ-ONLY over the entity/relation
  * graph.
  *
- * This module only READS the graph (`loadEntities` / `loadRelations`) and renders
+ * This module only READS the graph (through the store's graph reads) and renders
  * view-models; it issues no INSERT/UPDATE/DELETE, so `scripts/check-graph-writes.mjs`
  * stays green. Used by the CLI (`hippo graph show` / `hippo graph view`) and the
  * HTTP `GET /v1/graph` route, which all build the same `GraphModel`.
  */
-import { type EntityType, type RelationType } from './graph/types.js';
+import type { GraphRows } from '../store/port.js';
+import type { EntityType, RelationType } from '../store/graph-rows.js';
 export interface GraphNode {
     id: number;
     type: EntityType;
@@ -38,6 +39,8 @@ export declare function buildGraphModel(hippoRoot: string, tenantId: string, opt
     limit?: number;
     canRead?: (scope: string | null) => boolean;
 }): GraphModel;
+/** The reply model of the rows a store read: an edge with an endpoint outside the node set is dropped. */
+export declare function graphModelOf({ entities, relations, truncated }: GraphRows): GraphModel;
 /**
  * Deterministic Fruchterman-Reingold-style force layout. Seeded circular init +
  * fixed iterations, NO `Math.random`, so the same model always yields the same
@@ -70,4 +73,4 @@ export declare function renderGraphHtml(model: GraphModel): string;
  * `text` field (Obsidian renders/sanitizes them).
  */
 export declare function renderGraphCanvas(model: GraphModel): string;
-//# sourceMappingURL=graph-view.d.ts.map
+//# sourceMappingURL=view.d.ts.map