hippo-memory 1.70.0 → 1.71.0

package/dist/graph/recall.js

@@ -1,40 +1,6 @@
-/**
- * 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';
@@ -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)

package/dist/graph/view.d.ts

@@ -1,12 +1,5 @@
-/**
- * Graph observability and visualization, READ-ONLY over the entity/relation
- * graph.
- *
- * 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`.
- */
+/** Graph observability and visualization, READ-ONLY over the entity/relation graph (no writes, so `scripts/check-graph-writes.mjs` stays green).
+ *  Shared by `hippo graph show|view` and the HTTP `GET /v1/graph` route, which all build the same `GraphModel`. */
 import type { GraphRows } from '../store/port.js';
 import type { EntityType, RelationType } from '../store/graph-rows.js';
 export interface GraphNode {
@@ -28,12 +21,8 @@ export interface GraphModel {
 }
 /** Default bound for the CLI viewer / show so an unbounded set is never laid out. */
 export declare const DEFAULT_VIEW_LIMIT = 500;
-/**
- * Build the view-model from the graph (reads only). With `opts.entity`, returns a
- * focus subgraph: every entity whose name === entity, plus their 1-hop neighbours,
- * plus the edges among that union. Dangling edges (an endpoint outside the node
- * set) are always dropped.
- */
+/** Build the view-model (reads only); with `opts.entity`, a focus subgraph of the entities named so plus their 1-hop neighbours.
+ *  Dangling edges (an endpoint outside the node set) are always dropped. */
 export declare function buildGraphModel(hippoRoot: string, tenantId: string, opts?: {
     entity?: string;
     limit?: number;
@@ -41,12 +30,8 @@ export declare function buildGraphModel(hippoRoot: string, tenantId: string, opt
 }): 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
- * positions (testable, stable output). Non-finite coordinates from a degenerate
- * step are clamped to the viewport centre; all positions are clamped in-bounds.
- */
+/** Deterministic Fruchterman-Reingold-style force layout: seeded circular init, fixed iterations, no `Math.random`, so one model gives the same positions.
+ *  Non-finite coordinates are clamped to the viewport centre and all positions to the bounds. */
 export declare function layoutGraph(model: GraphModel, opts?: {
     width?: number;
     height?: number;
@@ -57,20 +42,9 @@ export declare function layoutGraph(model: GraphModel, opts?: {
 }>;
 /** HTML-escape for SVG text / title / markup content (XSS guard). */
 export declare function escapeHtml(s: string): string;
-/**
- * Render the model as a SELF-CONTAINED, dependency-free, offline interactive HTML
- * node-link diagram. Positions are computed server-side (deterministic). User
- * strings are escaped per sink: SVG `<text>`/`<title>` via `escapeHtml`; the model
- * is inlined in a `<script type="application/json">` block with `<`/`>`/`&`
- * unicode-escaped so a `</script>` inside an entity name cannot break out (the
- * client `JSON.parse`s it back and never `innerHTML`s a user string).
- */
+/** Render the model as a self-contained, offline interactive HTML node-link diagram with server-side deterministic positions.
+ *  The model is inlined as `<script type="application/json">` with `<`, `>`, `&` unicode-escaped so a `</script>` in an entity name cannot break out. */
 export declare function renderGraphHtml(model: GraphModel): string;
-/**
- * Render the model as a JSON Canvas (jsoncanvas.org) document — `nodes[]` of
- * type `text` positioned by the same deterministic layout, `edges[]` linking
- * them by id. Opens natively in Obsidian. Pure JSON; entity names live in the
- * `text` field (Obsidian renders/sanitizes them).
- */
+/** Render the model as a JSON Canvas (jsoncanvas.org) document: `text` nodes at the same deterministic layout positions, `edges[]` linking them by id. */
 export declare function renderGraphCanvas(model: GraphModel): string;
 //# sourceMappingURL=view.d.ts.map

package/dist/graph/view.js

@@ -1,24 +1,13 @@
-/**
- * Graph observability and visualization, READ-ONLY over the entity/relation
- * graph.
- *
- * 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`.
- */
+/** Graph observability and visualization, READ-ONLY over the entity/relation graph (no writes, so `scripts/check-graph-writes.mjs` stays green).
+ *  Shared by `hippo graph show|view` and the HTTP `GET /v1/graph` route, which all build the same `GraphModel`. */
 import { withGraphReadSnapshot } from '../store/graph-reads.js';
 import { graphViewRows } from '../store/graph-view-rows.js';
 const DEFAULT_LAYOUT_ITERATIONS = 300;
 const NODE_LABEL_MAX_CHARS = 22;
 /** Default bound for the CLI viewer / show so an unbounded set is never laid out. */
 export const DEFAULT_VIEW_LIMIT = 500;
-/**
- * Build the view-model from the graph (reads only). With `opts.entity`, returns a
- * focus subgraph: every entity whose name === entity, plus their 1-hop neighbours,
- * plus the edges among that union. Dangling edges (an endpoint outside the node
- * set) are always dropped.
- */
+/** Build the view-model (reads only); with `opts.entity`, a focus subgraph of the entities named so plus their 1-hop neighbours.
+ *  Dangling edges (an endpoint outside the node set) are always dropped. */
 export function buildGraphModel(hippoRoot, tenantId, opts = {}) {
     const limit = opts.limit ?? DEFAULT_VIEW_LIMIT;
     // One read snapshot, so a concurrent graph rebuild cannot make the model mix old entity ids with new relation ids.
@@ -105,12 +94,8 @@ function applyDisplacement(nodes, pos, disp, temp, width, height) {
         p.y = Math.max(20, Math.min(height - 20, ny));
     });
 }
-/**
- * Deterministic Fruchterman-Reingold-style force layout. Seeded circular init +
- * fixed iterations, NO `Math.random`, so the same model always yields the same
- * positions (testable, stable output). Non-finite coordinates from a degenerate
- * step are clamped to the viewport centre; all positions are clamped in-bounds.
- */
+/** Deterministic Fruchterman-Reingold-style force layout: seeded circular init, fixed iterations, no `Math.random`, so one model gives the same positions.
+ *  Non-finite coordinates are clamped to the viewport centre and all positions to the bounds. */
 export function layoutGraph(model, opts = {}) {
     const width = opts.width ?? LAYOUT_W;
     const height = opts.height ?? LAYOUT_H;
@@ -150,10 +135,8 @@ const NODE_COLORS = {
     person: '#3b82f6',
     system: '#64748b',
 };
-// Client script: pan (drag bg), zoom (wheel), click-to-highlight a node's edges +
-// neighbours. Reads the inlined model via JSON.parse (never innerHTML), so user
-// strings never reach an HTML sink here. No template literals / `${}` so it nests
-// safely inside this module's own template strings.
+// Client script: pan, zoom, click-to-highlight. It reads the inlined model via JSON.parse (never innerHTML)
+// and uses no template literals or `${}`, so it nests in this module's template strings.
 const CLIENT_JS = [
     "(function(){",
     "  var svg=document.getElementById('g');",
@@ -231,14 +214,8 @@ function renderLegend(model) {
         .map((t) => `<span style="color:${nodeColor(t)}">●</span> ${escapeHtml(t)}`)
         .join('  ');
 }
-/**
- * Render the model as a SELF-CONTAINED, dependency-free, offline interactive HTML
- * node-link diagram. Positions are computed server-side (deterministic). User
- * strings are escaped per sink: SVG `<text>`/`<title>` via `escapeHtml`; the model
- * is inlined in a `<script type="application/json">` block with `<`/`>`/`&`
- * unicode-escaped so a `</script>` inside an entity name cannot break out (the
- * client `JSON.parse`s it back and never `innerHTML`s a user string).
- */
+/** Render the model as a self-contained, offline interactive HTML node-link diagram with server-side deterministic positions.
+ *  The model is inlined as `<script type="application/json">` with `<`, `>`, `&` unicode-escaped so a `</script>` in an entity name cannot break out. */
 export function renderGraphHtml(model) {
     const pos = layoutGraph(model);
     const edgeSvg = renderEdgeSvg(model, pos);
@@ -262,12 +239,7 @@ export function renderGraphHtml(model) {
         '</body></html>',
     ].join('\n');
 }
-/**
- * Render the model as a JSON Canvas (jsoncanvas.org) document — `nodes[]` of
- * type `text` positioned by the same deterministic layout, `edges[]` linking
- * them by id. Opens natively in Obsidian. Pure JSON; entity names live in the
- * `text` field (Obsidian renders/sanitizes them).
- */
+/** Render the model as a JSON Canvas (jsoncanvas.org) document: `text` nodes at the same deterministic layout positions, `edges[]` linking them by id. */
 export function renderGraphCanvas(model) {
     const pos = layoutGraph(model, { width: 2400, height: 1600 });
     const nodes = model.nodes.map((node) => {

package/dist/hooks/codex-wrapper.js

@@ -1,7 +1,7 @@
 import { envPath } from '../util/env.js';
 import * as fs from 'fs';
 import * as path from 'path';
-import { fileURLToPath } from 'url';
+import { PACKAGE_ROOT } from '../core/package-root.js';
 import { errorMessage, log } from '../util/log.js';
 import { HIPPO_CODEX_WRAPPER_MARKER, homeDir, codexHomeDir, ensureDir } from './shared.js';
 import { isJsonString } from '../util/json.js';
@@ -68,7 +68,7 @@ function isCodexWrapperMetadataValid(metadata) {
         isHippoCodexWrapperFile(metadata.commandPath));
 }
 function resolveHippoCliPath() {
-    return fileURLToPath(new URL('../bin/hippo.js', import.meta.url));
+    return path.join(PACKAGE_ROOT, 'bin', 'hippo.js');
 }
 function quoteForShell(value) {
     return `"${value.replace(/(["\\$`])/g, '\\$1')}"`;

package/dist/hooks/copilot.js

@@ -77,7 +77,8 @@ function hippoCommand() {
 export const COPILOT_CLI_MCP = { key: 'mcpServers', server: () => ({ type: 'local', command: hippoCommand(), args: ['mcp'], env: {}, tools: ['*'] }) };
 /** VS Code's mcp.json keeps stdio servers under "servers"; it has no "mcpServers" key. */
 export const VSCODE_MCP = { key: 'servers', server: () => ({ type: 'stdio', command: hippoCommand(), args: ['mcp'] }) };
-/** Only a server hippo wrote counts as hippo's: another command, other args, or any key or value setup does not write (an env you added) makes it the user's. */
+/** Only a server hippo wrote counts as hippo's: another command, other args, or
+ * any key or value setup does not write (an env you added) makes it the user's. */
 function isHipposServer(entry, host) {
     if (!isJsonObjectLiteral(entry) || !('command' in entry) || !('args' in entry))
         return false;

package/dist/hooks/hook-blocks.d.ts

@@ -2,11 +2,15 @@ export declare const HOOK_MARKERS: {
     start: string;
     end: string;
 };
-export declare const HOOKS: Record<string, {
+export interface HookSpec {
     file: string;
     content: string;
     description: string;
-}>;
+}
+export interface HookTable {
+    [agent: string]: HookSpec;
+}
+export declare const HOOKS: HookTable;
 /** The first hippo block in `text` and the agent whose current or shipped text it is; `owner` is undefined for an edited block. */
 export declare function hippoBlock(text: string): {
     start: number;