hippo-memory 1.15.0 → 1.17.0

package/dist/graph-recall.js

@@ -0,0 +1,246 @@
+/**
+ * E3.2 multi-hop graph recall (docs/plans/2026-06-02-e3.2-multihop-recall.md).
+ *
+ * READ-ONLY consumer of the E3 graph substrate (entities/relations built by E3.1,
+ * guarded by E3.3). 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 E3.1 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 (the first two were forced by the verify-stage benchmark, the rest by
+ * codex review — all root-cause, not patches):
+ *  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 (codex review).
+ *  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 (codex review).
+ *
+ * No graph writes (only SELECTs via graph.ts read helpers + store reads), so the E3.3
+ * check-graph-writes lint permits this module living outside graph.ts.
+ */
+import { loadEntriesByIds } from './store.js';
+import { estimateTokens } from './search.js';
+import { loadEntitiesByMemoryId, loadEntitiesByIds, loadNeighborRelations, } from './graph.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;
+/** Default per-hop fanout cap (bounds blow-up on a future dense graph). */
+export const DEFAULT_MAX_NEIGHBORS = 25;
+/** Per-hop relevance discount: a graph hit inherits its origin seed's score, scaled down
+ *  1% per hop, so it ranks just below its seed and orders by hop-distance. */
+const HOP_DISCOUNT = 0.01;
+/** loadEntriesByIds caps each call at 500 ids; chunk to lose none on high fanout. */
+const LOAD_CHUNK = 500;
+/** Load memories by id in <=500-id chunks (loadEntriesByIds caps each call at 500). */
+function loadByIdsChunked(root, tenantId, ids) {
+    if (ids.length === 0)
+        return [];
+    const out = [];
+    for (let i = 0; i < ids.length; i += LOAD_CHUNK) {
+        out.push(...loadEntriesByIds(root, ids.slice(i, i + LOAD_CHUNK), tenantId));
+    }
+    return out;
+}
+/**
+ * Traverse one store's graph from the seeds present in it and accumulate new graph hits
+ * into `hitsByOrigin`. Mutates `seenMemoryIds` so a memory is surfaced at most once across
+ * stores. Pure reads.
+ */
+function produceHitsForRoot(root, baseResults, baseScoreByMemId, seenMemoryIds, hitsByOrigin, opts) {
+    const { hops, maxNeighbors, tenantId, includeSuperseded, 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));
+    if (seedEntities.length === 0)
+        return;
+    // BFS, both directions, up to `hops`. `visited` prevents re-expansion (cycle-safe).
+    // `originMemByEntityId` propagates the base-result memory id each reached node descends
+    // from (for adjacency placement + score inheritance).
+    const visitedEntityIds = new Set(seedEntities.map((e) => e.id));
+    const reached = new Map();
+    const originMemByEntityId = new Map();
+    for (const se of seedEntities)
+        originMemByEntityId.set(se.id, se.memoryId);
+    let frontier = seedEntities.map((e) => e.id);
+    for (let depth = 1; depth <= hops && frontier.length > 0; depth++) {
+        const frontierSet = new Set(frontier);
+        const rels = loadNeighborRelations(root, tenantId, frontier, {
+            limit: Math.max(maxNeighbors, maxNeighbors * frontier.length),
+        });
+        const nextFrontier = [];
+        for (const rel of rels) {
+            const fromIn = frontierSet.has(rel.fromEntityId);
+            const toIn = frontierSet.has(rel.toEntityId);
+            let neighborId;
+            let reacherId;
+            let direction;
+            if (fromIn && !toIn) {
+                neighborId = rel.toEntityId;
+                reacherId = rel.fromEntityId;
+                direction = 'to';
+            }
+            else if (toIn && !fromIn) {
+                neighborId = rel.fromEntityId;
+                reacherId = rel.toEntityId;
+                direction = 'from';
+            }
+            else
+                continue;
+            if (visitedEntityIds.has(neighborId))
+                continue;
+            visitedEntityIds.add(neighborId);
+            reached.set(neighborId, { hops: depth, relType: rel.relType, direction });
+            const origin = originMemByEntityId.get(reacherId);
+            if (origin !== undefined)
+                originMemByEntityId.set(neighborId, origin);
+            nextFrontier.push(neighborId);
+            if (nextFrontier.length >= maxNeighbors)
+                break; // per-hop fanout cap
+        }
+        frontier = nextFrontier;
+    }
+    if (reached.size === 0)
+        return;
+    // Reached entities -> source memory ids -> load DIRECTLY by id (chunked), not lexical.
+    const reachedEntities = loadEntitiesByIds(root, tenantId, [...reached.keys()]);
+    const needLoad = [...new Set(reachedEntities.map((e) => e.memoryId).filter((id) => !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]));
+    }
+    for (const ent of reachedEntities) {
+        const mem = loadedById.get(ent.memoryId);
+        if (!mem)
+            continue; // not found / wrong tenant / already in base
+        if (seenMemoryIds.has(mem.id))
+            continue; // another reached entity already added it
+        const via = reached.get(ent.id);
+        // 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.
+        const isSupersededEndpoint = via.relType === 'supersedes' && via.direction === 'to';
+        if (asOfDate) {
+            if (new Date(mem.valid_from) > asOfDate)
+                continue; // not yet valid at asOf
+            if (mem.superseded_by) {
+                const succVf = successorValidFrom.get(mem.superseded_by);
+                // Visible only while its successor was NOT yet valid at asOf (matches cmdRecall).
+                if (succVf && new Date(succVf) <= asOfDate)
+                    continue;
+            }
+        }
+        else if (!includeSuperseded && (mem.superseded_by || isSupersededEndpoint)) {
+            continue; // default recall drops superseded
+        }
+        const origin = originMemByEntityId.get(ent.id) ?? baseResults[0].entry.id;
+        const originScore = baseScoreByMemId.get(origin) ?? baseResults[baseResults.length - 1].score;
+        seenMemoryIds.add(mem.id);
+        const hit = {
+            entry: mem,
+            score: originScore * (1 - HOP_DISCOUNT * via.hops),
+            bm25: 0, cosine: 0,
+            tokens: estimateTokens(mem.content),
+            graphVia: via,
+        };
+        if (!hitsByOrigin.has(origin))
+            hitsByOrigin.set(origin, []);
+        hitsByOrigin.get(origin).push(hit);
+    }
+}
+/**
+ * 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.
+ */
+export function graphExpandRecall(baseResults, opts) {
+    const { hops, hippoRoot, globalRoot, tenantId } = opts;
+    if (hops <= 0 || baseResults.length === 0)
+        return baseResults;
+    const maxNeighbors = opts.maxNeighbors ?? DEFAULT_MAX_NEIGHBORS;
+    const budget = opts.budget ?? 4000;
+    const includeSuperseded = opts.includeSuperseded ?? false;
+    const asOfDate = opts.asOf ? new Date(opts.asOf) : null;
+    const minResults = opts.minResults ?? 1;
+    const baseScoreByMemId = new Map(baseResults.map((r) => [r.entry.id, r.score]));
+    const seenMemoryIds = new Set(baseResults.map((r) => r.entry.id));
+    const hitsByOrigin = new Map();
+    // 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, hitsByOrigin, {
+            hops, maxNeighbors, tenantId, includeSuperseded, asOfDate,
+        });
+    }
+    if (hitsByOrigin.size === 0)
+        return baseResults;
+    // Closer hops first within each origin group, then by inherited score.
+    for (const hits of hitsByOrigin.values()) {
+        hits.sort((a, b) => a.graphVia.hops - b.graphVia.hops || b.score - a.score);
+    }
+    const allHits = [...hitsByOrigin.values()].flat();
+    // 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; codex P2). They are kept regardless of budget;
+    // baseResults is score-ordered, so slice(0, N) is the top N.
+    const protectedCount = Math.min(Math.max(minResults, 1), baseResults.length);
+    const keep = new Set(baseResults.slice(0, protectedCount));
+    let usedTokens = [...keep].reduce((s, r) => s + r.tokens, 0);
+    for (const r of [...baseResults.slice(protectedCount), ...allHits].sort((a, b) => b.score - a.score)) {
+        if (usedTokens + r.tokens > budget)
+            continue;
+        usedTokens += r.tokens;
+        keep.add(r);
+    }
+    // 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 = [];
+    let emittedHit = false;
+    for (const r of baseResults) {
+        if (!keep.has(r))
+            continue;
+        merged.push(r);
+        for (const hit of hitsByOrigin.get(r.entry.id) ?? []) {
+            if (keep.has(hit)) {
+                merged.push(hit);
+                emittedHit = true;
+            }
+        }
+    }
+    return emittedHit ? merged : baseResults; // nothing new survived budget -> original base
+}
+//# sourceMappingURL=graph-recall.js.map

package/dist/graph-recall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-recall.js","sourceRoot":"","sources":["../src/graph-recall.ts"],"names":[],"mappings":"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"}

package/dist/graph.d.ts

@@ -0,0 +1,137 @@
+/**
+ * E3.3 graph layer over consolidated state - the graph-on-consolidated guard.
+ * (docs/plans/2026-06-01-e3-graph-guard.md).
+ *
+ * A graph of canonical `entities` (person/project/customer/system/policy/decision) and
+ * `relations` (owns/supersedes/depends-on/blocked-by/references) sits ON TOP OF
+ * consolidated memories. The hard rule: the graph NEVER indexes the raw layer - every
+ * entity and relation references a memory whose `kind IN ('distilled','superseded')`,
+ * never `kind='raw'`. Enforced at the DB level (CHECK on source_kind/kind + BEFORE
+ * INSERT and BEFORE UPDATE triggers that tie source_kind/kind to the FK'd memory's
+ * actual kind and enforce tenant-match - relations also reject cross-tenant edges), so
+ * the forbidden state is unrepresentable regardless of code path. These helpers
+ * surface the same guard as clear throws BEFORE hitting the trigger backstop.
+ *
+ * Scope (E3.3 first slice): the substrate + the guard + a thin insert/load/enqueue
+ * API. The `graph_extraction_queue` is the interface the deferred `hippo sleep`
+ * enqueue-hook + E3.1 entity extraction will call. No operator surface (CLI/HTTP/SDK)
+ * until E3.2 multi-hop recall.
+ */
+export type EntityType = 'person' | 'project' | 'customer' | 'system' | 'policy' | 'decision';
+export type RelationType = 'owns' | 'supersedes' | 'depends-on' | 'blocked-by' | 'references';
+export type GraphQueueStatus = 'pending' | 'processed' | 'skipped';
+/** The consolidated source kinds the graph is permitted to index (never 'raw'). */
+export type SourceKind = 'distilled' | 'superseded';
+export declare const GRAPH_ENTITY_TYPES: ReadonlySet<EntityType>;
+export declare const GRAPH_RELATION_TYPES: ReadonlySet<RelationType>;
+export declare const VALID_QUEUE_STATES: ReadonlySet<GraphQueueStatus>;
+export declare const MAX_ENTITY_NAME_LEN = 512;
+export interface Entity {
+    id: number;
+    tenantId: string;
+    entityType: EntityType;
+    name: string;
+    /** The consolidated source memory this entity was extracted from. */
+    memoryId: string;
+    sourceKind: SourceKind;
+    createdAt: string;
+}
+export interface Relation {
+    id: number;
+    tenantId: string;
+    fromEntityId: number;
+    toEntityId: number;
+    relType: RelationType;
+    memoryId: string;
+    sourceKind: SourceKind;
+    createdAt: string;
+}
+export interface GraphQueueItem {
+    id: number;
+    tenantId: string;
+    memoryId: string;
+    kind: SourceKind;
+    status: GraphQueueStatus;
+    enqueuedAt: string;
+    processedAt: string | null;
+}
+export interface InsertEntityOpts {
+    entityType: EntityType;
+    name: string;
+    /** A consolidated (distilled/superseded) memory; raw is rejected. */
+    memoryId: string;
+}
+export interface InsertRelationOpts {
+    fromEntityId: number;
+    toEntityId: number;
+    relType: RelationType;
+    /** A consolidated (distilled/superseded) memory; raw is rejected. */
+    memoryId: string;
+}
+/**
+ * Insert a graph entity extracted from a consolidated memory. Throws if the source
+ * memory is missing / cross-tenant / raw (the DB trigger is the backstop).
+ */
+export declare function insertEntity(hippoRoot: string, tenantId: string, opts: InsertEntityOpts): Entity;
+/**
+ * Insert a graph relation between two entities, sourced from a consolidated memory.
+ * Both entities must exist in the same tenant; the source memory must be consolidated.
+ */
+export declare function insertRelation(hippoRoot: string, tenantId: string, opts: InsertRelationOpts): Relation;
+export declare function loadEntityById(hippoRoot: string, tenantId: string, id: number): Entity | null;
+export declare function loadEntities(hippoRoot: string, tenantId: string, opts?: {
+    entityType?: EntityType;
+    limit?: number;
+}): Entity[];
+export declare function loadRelations(hippoRoot: string, tenantId: string, opts?: {
+    fromEntityId?: number;
+    limit?: number;
+}): Relation[];
+/**
+ * Map consolidated source memory ids -> their graph entities. The SEED step of E3.2
+ * multi-hop recall (recall result memory ids -> entities to traverse from). Tenant-
+ * scoped, read-only; chunks the IN-list under the SQLite variable cap.
+ */
+export declare function loadEntitiesByMemoryId(hippoRoot: string, tenantId: string, memoryIds: string[]): Entity[];
+/**
+ * Load entities by their primary ids. Resolves the entity rows reached during the BFS
+ * (whose `memory_id` maps back to a recall result). Tenant-scoped, read-only.
+ */
+export declare function loadEntitiesByIds(hippoRoot: string, tenantId: string, ids: number[]): Entity[];
+/**
+ * All relations touching ANY of `entityIds` in EITHER direction (from OR to) — the
+ * per-hop neighbour query for E3.2 multi-hop traversal. ONE query for the whole frontier
+ * (not one per node): this is the bidirectional read `loadRelations` (from-only) lacks,
+ * and avoids an N+1 across BFS frontier nodes. `limit` caps rows for the frontier and
+ * must be a non-negative integer (the raw `LIMIT ?` rejects a fractional value).
+ */
+export declare function loadNeighborRelations(hippoRoot: string, tenantId: string, entityIds: number[], opts?: {
+    limit?: number;
+}): Relation[];
+/**
+ * Enqueue a consolidated memory for later graph extraction. Rejects a raw / missing /
+ * cross-tenant memory (the DB trigger is the backstop). The producer hook in
+ * `hippo sleep` is deferred (E3.1); this is the API it will call.
+ */
+export declare function enqueueExtraction(hippoRoot: string, tenantId: string, memoryId: string): GraphQueueItem;
+export declare function loadExtractionQueue(hippoRoot: string, tenantId: string, opts?: {
+    status?: GraphQueueStatus;
+    limit?: number;
+}): GraphQueueItem[];
+/**
+ * Mark a queue item terminal (processed | skipped). Only `status`/`processed_at`
+ * change, so the consolidated-source guard trigger (which fires on
+ * memory_id/kind/tenant_id changes) is not involved. CAS on the current status to a
+ * non-terminal 'pending'.
+ */
+export declare function markExtractionProcessed(hippoRoot: string, tenantId: string, id: number, status?: 'processed' | 'skipped'): GraphQueueItem;
+/**
+ * Delete ALL entities for a tenant (relations cascade via the from/to FKs). Returns
+ * the number of entities deleted. The rebuild primitive for graph extraction: the
+ * deterministic graph is a pure derived function of the consolidated objects, so an
+ * extract clears then re-derives. Lives in graph.ts (the sole sanctioned graph
+ * writer), so the E3.3 CI lint permits this `DELETE FROM entities`. Does NOT touch
+ * graph_extraction_queue (the enqueue-hook's domain).
+ */
+export declare function clearGraph(hippoRoot: string, tenantId: string): number;
+//# sourceMappingURL=graph.d.ts.map

package/dist/graph.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph.d.ts","sourceRoot":"","sources":["../src/graph.ts"],"names":[],"mappings":"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"}