hippo-memory 1.70.0 → 1.72.0

package/dist/eval/judgment.js

@@ -2,14 +2,26 @@
  *  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';
 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. */
+function answerNamed(reply, name) {
+    const answers = isJsonObject(reply) ? reply.answers : undefined;
+    const answer = isJsonObject(answers) ? answers[name] : undefined;
+    return isJsonObject(answer) ? answer : {};
+}
 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',
@@ -36,7 +48,7 @@ const QUESTIONS = {
 const KINDS = ['error', 'decision', 'convention', 'preference', 'trivia'];
 const VALENCES = ['critical', 'negative', 'positive', 'neutral'];
 function oneOf(value, allowed) {
-    return allowed.find((option) => option === value) ?? null;
+    return isJsonString(value) ? allowed.find((option) => option === value) ?? null : null;
 }
 /** `verified` is unreachable: that tier means a human or a test confirmed it. */
 function toConfidenceTier(kindConfidence) {
@@ -63,14 +75,19 @@ 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. */
-export async function judge(content, opts) {
+async function judge(content, opts) {
     const trimmed = content.trim();
     if (trimmed.length < 3)
         return null;
@@ -79,21 +96,19 @@ export async function judge(content, opts) {
         return null;
     let data;
     try {
-        // SAFETY: the documented Jev response is `{ answers: { <name>: Answer } }`
-        // keyed by the question names posted above; every field read below is
-        // optional-chained and range-checked before use, so a lie here returns null.
-        data = await res.json();
+        data = await readCappedJson(res, JUDGE_MAX_REPLY_BYTES);
     }
     catch (err) {
         log.debug(`judge: unreadable response: ${errorMessage(err)}`);
         return null;
     }
-    const durable = data.answers?.durable?.noul;
-    const kind = oneOf(data.answers?.kind?.choice, KINDS);
-    const valence = oneOf(data.answers?.valence?.choice, VALENCES);
-    if (durable === undefined || durable < 0 || durable > 1 || !kind || !valence)
+    const durable = answerNamed(data, 'durable').noul;
+    const kindAnswer = answerNamed(data, 'kind');
+    const kind = oneOf(kindAnswer.choice, KINDS);
+    const valence = oneOf(answerNamed(data, 'valence').choice, VALENCES);
+    if (!isJsonNumber(durable) || durable < 0 || durable > 1 || !kind || !valence)
         return null;
-    const kindConfidence = data.answers?.kind?.confidence ?? 0;
+    const kindConfidence = isJsonNumber(kindAnswer.confidence) ? kindAnswer.confidence : 0;
     return { durable, kind, valence, confidence: toConfidenceTier(kindConfidence), kindConfidence };
 }
 /** Judge many candidates under a bounded concurrency pool, order preserved. */

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

@@ -280,7 +280,7 @@ export default function register(api) {
     // --- Tool: hippo_outcome ---
     api.registerTool((ctx) => ({
         name: 'hippo_outcome',
-        description: 'Report whether recalled memories were useful. Strengthens good memories (+5 days half-life) and weakens bad ones (-3 days). Call after completing work.',
+        description: "Report whether recalled memories were useful. Good outcomes slow a memory's decay and bad ones speed it up, in proportion to its record. Call after completing work.",
         parameters: {
             type: 'object',
             properties: {

package/dist/graph/extract.d.ts

@@ -1,34 +1,12 @@
-/**
- * Deterministic entity extraction.
- *
- * Populates the graph from the already-structured consolidated first-class object tables -
- * NO NLP, no precision gate for entities + supersedes. The graph is a pure derived
- * function of the current object state, so `extractGraph` is an idempotent REBUILD: derive
- * 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/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
- * `references` edge when one consolidated object's text contains another entity's name.
- * It is conservative (word-boundary, length-bounded, ambiguity-guarded, per-source
- * capped); its precision is measured + reported, not assumed.
- *
- * Deferred (follow-ups): NLP prose-extraction (semantic depends-on / blocked-by / owns);
- * skill/incident/process entities (not in the entity_type enum - needs a migration); the
- * `hippo sleep` enqueue-hook.
- */
+/** 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 whose active or superseded
- *  set exceeds this is truncated; `ExtractResult.truncated` records it so the
- *  incompleteness is observable rather than silent. */
+/** 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). */
+/** 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). */
 export declare const MIN_REF_NAME_LEN = 4;
 export declare const MAX_REF_NAME_LEN = 80;
 /** Per-source cap so one object cannot explode the graph with references edges. */

package/dist/graph/extract.js

@@ -1,24 +1,5 @@
-/**
- * Deterministic entity extraction.
- *
- * Populates the graph from the already-structured consolidated first-class object tables -
- * NO NLP, no precision gate for entities + supersedes. The graph is a pure derived
- * function of the current object state, so `extractGraph` is an idempotent REBUILD: derive
- * 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/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
- * `references` edge when one consolidated object's text contains another entity's name.
- * It is conservative (word-boundary, length-bounded, ambiguity-guarded, per-source
- * capped); its precision is measured + reported, not assumed.
- *
- * Deferred (follow-ups): NLP prose-extraction (semantic depends-on / blocked-by / owns);
- * skill/incident/process entities (not in the entity_type enum - needs a migration); the
- * `hippo sleep` enqueue-hook.
- */
+/** 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';
@@ -31,14 +12,10 @@ 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. */
+/** 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;
-// --- Pass 3 (cross-object references) tunables ------------------------------------
-/** 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). */
+/** 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). */
 export const MIN_REF_NAME_LEN = 4;
 export const MAX_REF_NAME_LEN = 80;
 /** Per-source cap so one object cannot explode the graph with references edges. */
@@ -72,11 +49,8 @@ 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 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.
- */
+/** 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) => {
         const rows = [];
@@ -127,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.
@@ -246,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
@@ -263,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.d.ts

@@ -17,9 +17,8 @@ export interface GraphExpandOpts {
     tenantId: string;
     /** Mirror the recall handler's hard filters when re-loading graph-reached rows. */
     includeSuperseded?: boolean;
-    /** ISO date; bi-temporal as-of filter applied to graph-reached rows (full rule, matching
-     *  cmdRecall: a row is visible if valid_from <= asOf AND, when superseded, its successor
-     *  was not yet valid at asOf). */
+    /** ISO date; bi-temporal as-of filter applied to graph-reached rows, matching cmdRecall:
+     *  visible if valid_from <= asOf and, when superseded, its successor was not yet valid at asOf. */
     asOf?: string;
     /** Token budget for the augmented set (defaults to DEFAULT_RECALL_BUDGET, matching recall). */
     budget?: number;
@@ -28,28 +27,16 @@ 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 envelope scope rule applied to graph-REACHED memories (the injected
-     *  rows), mirroring shared.ts SearchBothOptions.recallScope. Omitted = default-deny
-     *  (private + quarantine scopes excluded, NULL passes) — the fail-closed default for
-     *  bare/SDK callers. { requested, additive: true } = CLI --scope unlock semantics
-     *  (passesCliRecallScopeFilter); additive false/absent with requested set = api
-     *  exact-narrowing semantics (passesScopeFilterForRecall). Base results are the
-     *  caller's responsibility (they passed through the caller's own scope filter). */
+    /** 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). */
     recallScope?: {
         requested?: string;
         additive?: boolean;
         ownScope?: string;
     };
 }
-/**
- * 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
- * inserted directly after the base result it descends from, scored just below that seed;
- * the base list's own order is preserved. Token-budget-bounded; deduped against the base
- * set and across stores.
- *
- * No-op (returns `baseResults` unchanged) when `hops <= 0`, there are no base results, the
- * graph is empty, no seed maps to an entity, or nothing new survives the filters/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,46 +1,12 @@
-/**
- * Multi-hop graph recall.
- *
- * READ-ONLY consumer of the graph substrate (entities/relations built by graph-extract,
- * guarded by the graph-on-consolidated triggers). Given the lexical recall seeds, walk the relations graph up to N
- * hops and surface the memories of reached entities that the lexical search did not
- * already return.
- *
- * Relation-type-AGNOSTIC: it walks whatever edges exist. Today the graph holds only
- * `supersedes` edges (so a 1-hop walk surfaces a supersession-linked predecessor/
- * successor a lexical search may miss); the moment extraction emits cross-object edges
- * (owns/depends-on/blocked-by/references) the SAME traversal lights up cross-entity
- * multi-hop with zero rework here.
- *
- * Design points:
- *  1. Graph-reached memories are loaded DIRECTLY by id (tenant-scoped PK fetch), NOT
- *     intersected with the recall handler's candidate set — that set is lexically
- *     prefiltered (loadSearchRows filters by query tokens), so intersecting would exclude
- *     exactly the lexically-orthogonal neighbours graph recall exists to surface. We
- *     re-apply the recall HARD filters to the directly-loaded rows: the FULL bi-temporal
- *     as-of rule (valid_from <= asOf AND, for a superseded row, successor.valid_from >
- *     asOf — same as cmdRecall) and the default superseded-drop. SCOPE is intentionally
- *     NOT re-applied: the CLI caller (cmdRecall) does not hard-filter scope either (it
- *     only soft-boosts it). Rows are tenant-scoped + archived-excluded (loadEntriesByIds).
- *  2. A graph hit inherits its origin seed's relevance (minus a per-hop discount) and is
- *     placed adjacent to that seed; budget selection is by score so a high-value hit wins
- *     a token slot over a noise distractor. Dead-last appending made the feature do
- *     nothing at realistic budgets.
- *  3. BOTH the local and global stores are expanded — a global seed's entities/relations
- *     live under the global root, so graph recall must traverse each seed in the store its
- *     graph lives in.
- *  4. By-id loads are chunked at 500 (loadEntriesByIds caps at 500/call), so a high-fanout
- *     traversal (--hops 3 --max-neighbors 200 -> up to 600 ids) loses none.
- *
- * 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.
- */
+/** 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';
 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;
@@ -63,14 +29,10 @@ 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` prevents re-expansion (cycle-safe).
-    // `originMemByEntityId` propagates the base-result memory id each reached node descends
-    // from (for adjacency placement + 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/pruned has a null memoryId; the map
-    // tolerates null so traversal still propagates origin, and the null is dropped before
-    // any memory load below (a mirror-less node has no memory to surface).
+    // 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);
@@ -117,11 +79,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;
-    // A node reached as the `to` endpoint of a `supersedes` edge IS the superseded
-    // (older) version — the graph is the authoritative signal (the memory mirror's
-    // `superseded_by` is NOT set by `hippo decide`, only the decisions table is). By
-    // default recall shows current truth, so drop it unless --include-superseded; the
-    // `from` endpoint (the newer successor) is always kept.
+    // 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) {
         if (new Date(mem.valid_from) > asOfDate)
@@ -187,10 +146,8 @@ function buildGraphHit(mem, via, originScore) {
         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).
+// 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
             .map((e) => e.memoryId)
@@ -205,16 +162,8 @@ 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 the graph `hops` edges out from
- * the seed results' entities (across the local AND global stores). Each graph hit is
- * inserted directly after the base result it descends from, scored just below that seed;
- * the base list's own order is preserved. Token-budget-bounded; deduped against the base
- * set and across stores.
- *
- * No-op (returns `baseResults` unchanged) when `hops <= 0`, there are no base results, the
- * graph is empty, no seed maps to an entity, or nothing new survives the filters/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)
@@ -242,9 +191,7 @@ export function graphExpandRecall(baseResults, 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.
+    // 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;
@@ -258,17 +205,8 @@ function sortHitsWithinOrigin(hitsByOrigin) {
 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
-    // surfaced. The greedy pack uses `continue` (not `break`), so a hit's origin seed is
-    // NOT guaranteed kept just because the hit is; the DISPLAY loop guards that (a hit is
-    // emitted ONLY under a kept seed, never orphaned). At least one result is always kept.
-    // (NOTE: at a tight budget a new graph hit can displace a weakly-scored base result;
-    // aggregate recall stays >= baseline, the displaced item is the lowest-value one.)
-    // Protect the top --min-results base rows from eviction (graph expansion must not
-    // violate the recall min-results floor). They are kept regardless of budget;
-    // baseResults is score-ordered, so slice(0, N) is the top N.
+    // 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,30 +1,8 @@
-/**
- * Graph-retrieval ranked-list stream for RRF fusion.
- *
- * READ-ONLY consumer of the entity/relation graph. Produces a ranked list of
- * `entries[]` indices ordered by graph
- * proximity to the strong lexical seeds, for use as a 3rd fusion input to `rrfFuse`
- * beside BM25 + dense (src/search.ts hybridSearch, scoring:'rrf').
- *
- * DISTINCT from graph-recall.ts: that INJECTS out-of-pool neighbours post-hoc; this
- * RE-RANKS within the already-filtered candidate pool. It only assigns ranks to
- * entries that are (a) graph-reached from a seed AND (b) present in `entries[]`. Seeds
- * themselves are never scored (they already rank via BM25/dense; scoring them would
- * double-count and dilute the orthogonal graph signal).
- *
- * Reuses the BFS traversal shape from graph-recall.ts (loadEntitiesByMemoryId
- * seeds -> loadNeighborRelations BFS both directions, per-hop fanout cap, visited set
- * -> loadEntitiesByIds to resolve reached -> memoryId). Expands across the local AND
- * global stores. Pure reads (SELECTs only via graph.ts helpers), so the
- * check-graph-writes lint permits this module living outside graph.ts.
- *
- * The graph stream's score scale (1/lexRank seed strength x decay^hops) only sets the
- * WITHIN-graph-stream ORDERING; RRF then re-ranks the list by 1/(k + graphRank), so the
- * absolute magnitude is washed out by fusion. Do not tune the scale expecting a
- * fused-score effect — only the induced order matters.
- */
+/** 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). */
+/** 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. */
 export declare const DEFAULT_GRAPH_DECAY = 0.5;
@@ -52,19 +30,9 @@ 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 the
- * BM25 and dense ranked lists), with strength = 1/(bestRank + 1). Pure; exported for
- * direct unit testing. A candidate present in either ranked list is eligible.
- */
+/** 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 ordered by graph
- * proximity (desc) to the lexical `seeds`. Only graph-reached, in-pool, non-seed
- * indices appear; the rest are absent (-> rrfFuse absentRank). Pure reads.
- *
- * Returns `[]` when there are no seeds/entries, the graph is empty, no seed maps to an
- * entity, or nothing reached is in-pool — the caller then 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

package/dist/graph/stream.js

@@ -1,6 +1,6 @@
 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). */
+/** 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. */
 export const DEFAULT_GRAPH_DECAY = 0.5;
@@ -9,11 +9,7 @@ export const DEFAULT_GRAPH_SEED_COUNT = 10;
 /** Recommended RRF weight for the graph stream — a CLI-only convenience default. The
  *  library `graphStream.weight` option stays REQUIRED (opt-in is explicit). */
 export const DEFAULT_GRAPH_STREAM_WEIGHT = 0.5;
-/**
- * Pick the top `seedCount` candidates by best lexical rank (lowest position across the
- * BM25 and dense ranked lists), with strength = 1/(bestRank + 1). Pure; exported for
- * direct unit testing. A candidate present in either ranked list is eligible.
- */
+/** Pick the top `seedCount` candidates by best lexical rank (lowest position across BM25 and dense), strength = 1/(bestRank + 1). Pure. */
 export function selectGraphSeeds(bm25Ranked, cosineRanked, seedCount) {
     if (seedCount <= 0)
         return [];
@@ -33,11 +29,8 @@ export function selectGraphSeeds(bm25Ranked, cosineRanked, seedCount) {
         .slice(0, seedCount)
         .map(([index, best]) => ({ index, strength: 1 / (best + 1) }));
 }
-// Pass 1: accumulate the STRONGEST reaching-seed strength per new neighbour across ALL
-// relations at this depth BEFORE committing any to `visited`. Marking a node
-// visited mid-loop would lock it to whichever relation SQLite returned first, so a later
-// edge from a STRONGER lexical seed would be dropped and the neighbour mis-scored. A node
-// already in `visited` was committed at an earlier (shorter) depth and keeps that score.
+// Pass 1: take the STRONGEST reaching-seed strength per new neighbour across ALL relations at this depth before committing any to `visited`;
+// marking mid-loop would lock a node to whichever relation SQLite returned first and drop a stronger seed's later edge.
 function bestStrengthAtDepth(rels, frontierSet, visited, frontierStrength, originStrength) {
     const bestStrengthThisDepth = new Map();
     for (const rel of rels) {
@@ -98,13 +91,8 @@ function reachedEntityScores(root, tenantId, seedIds, originStrength, options) {
     }
     return reachedScore;
 }
-/**
- * Accumulate per-entryIndex graph-proximity scores from ONE store's graph into
- * `graphScore`. Pure reads. `seeds` are the lexical seeds (index + strength); only the
- * seeds whose entities live in THIS store are expanded. The origin seed strength is
- * 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).
- */
+/** Accumulate per-entryIndex graph-proximity scores from ONE store's graph into `graphScore`; only seeds whose entities live in THIS store are expanded.
+ *  A neighbour's score = originSeedStrength x decay^(graph distance); the seed strength is carried unchanged along each BFS path. */
 function accumulateForRoot(root, seeds, entries, options) {
     const { memIdToIndex, graphScore, hops, decay, maxNeighbors, tenantId } = options;
     if (seeds.length === 0)
@@ -119,9 +107,7 @@ function accumulateForRoot(root, seeds, entries, options) {
     const seedEntities = loadEntitiesByMemoryId(root, tenantId, [...strengthByMemId.keys()]);
     if (seedEntities.length === 0)
         return;
-    // entityId -> origin seed strength (carried unchanged along the path). A seed entity is
-    // loaded by memory id, so its memoryId is non-null here; the guard keeps the widened
-    // (string | null) type honest (a null-memory entity is not a lexical seed).
+    // entityId -> origin seed strength. Seeds load by memory id so memoryId is non-null here; the guard keeps the widened (string | null) type honest.
     const originStrength = new Map();
     for (const e of seedEntities) {
         if (e.memoryId === null)
@@ -146,14 +132,8 @@ function accumulateForRoot(root, seeds, entries, options) {
         graphScore.set(idx, Math.max(graphScore.get(idx) ?? 0, score));
     }
 }
-/**
- * Produce the graph-retrieval ranked list: `entries[]` indices ordered by graph
- * proximity (desc) to the lexical `seeds`. Only graph-reached, in-pool, non-seed
- * indices appear; the rest are absent (-> rrfFuse absentRank). Pure reads.
- *
- * Returns `[]` when there are no seeds/entries, the graph is empty, no seed maps to an
- * entity, or nothing reached is in-pool — the caller then 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 function graphRankStream(entries, seeds, opts) {
     if (seeds.length === 0 || entries.length === 0)
         return [];
@@ -170,11 +150,8 @@ export function graphRankStream(entries, seeds, opts) {
     for (const root of roots) {
         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
-    // is a seed in one store could be reached as a neighbour in the other store and pick up
-    // a score via max(). Drop every seed index so the "seeds are never scored by the graph
-    // stream" invariant holds across roots, not just within a single store's traversal.
+    // Seed-exclusion guard: graphScore is keyed by entryIndex across roots but each root's visited-set is per-root, so a seed in one store
+    // could score as a neighbour in the other; drop every seed index so "seeds are never graph-scored" holds across roots.
     for (const s of seeds)
         graphScore.delete(s.index);
     if (graphScore.size === 0)