@spinabot/brigade 0.1.1 → 1.0.0

package/dist/agents/memory/governance.js

@@ -0,0 +1,113 @@
+// src/agents/memory/governance.ts
+//
+// Tideline Step 24 — governance: purge (crypto-shred + cascade), retention TTL,
+// inspect, export.
+//
+//   • PURGE — hard-removes a fact (crypto-shred: the sealed content is gone, not
+//     archived) AND CASCADES along `sourcePointers`: any fact DERIVED from a
+//     purged one (a dream/extraction citation) is purged too, recursively. This
+//     is the "no zombie memories" guarantee — a purged fact can't resurrect
+//     through a derived citation in the next dream.
+//   • RETENTION — hard-purge facts older than a TTL (confirmed beliefs retained
+//     by default), cascading the same way.
+//   • INSPECT — a fact + its outbound links, backlinks, and provenance.
+//   • EXPORT — dump records (optionally one origin) for portability / GDPR.
+import { backlinksTo, linksFrom } from "./links.js";
+import { recordMatchesOriginFilter } from "./records.js";
+/** Reverse index: sourceId → ids of facts that cite it in `sourcePointers`. */
+function buildDerivedIndex(records) {
+    const derivedOf = new Map();
+    for (const r of records) {
+        for (const src of r.sourcePointers ?? []) {
+            const arr = derivedOf.get(src) ?? [];
+            arr.push(r.memoryId);
+            derivedOf.set(src, arr);
+        }
+    }
+    return derivedOf;
+}
+/**
+ * BFS the derivation tree from `seeds` along `sourcePointers` so a citation chain
+ * (A → B-derived-from-A → C-derived-from-B) is fully collapsed. Returns every id
+ * to remove. Shared by `purge` (global) and `applyRetention` (origin-bounded).
+ */
+function cascadeFrom(records, seeds) {
+    const derivedOf = buildDerivedIndex(records);
+    const toPurge = new Set();
+    const queue = [...seeds];
+    while (queue.length > 0) {
+        const id = queue.shift();
+        if (toPurge.has(id))
+            continue;
+        toPurge.add(id);
+        for (const d of derivedOf.get(id) ?? [])
+            if (!toPurge.has(d))
+                queue.push(d);
+    }
+    return toPurge;
+}
+/**
+ * Purge `seedIds` and everything transitively DERIVED from them (via
+ * `sourcePointers`). Crypto-shred: the records are hard-removed. Idempotent.
+ * The cascade is intentionally GLOBAL (cross-origin) — the direct purge action
+ * is "no zombie memories" at any cost. (Retention scopes its own cascade.)
+ */
+export function purge(store, seedIds) {
+    const seeds = typeof seedIds === "string" ? [seedIds] : seedIds;
+    return { purged: store.purge([...cascadeFrom(store.readAll(), seeds)]) };
+}
+/**
+ * Retention TTL — hard-purge facts whose transaction-time age exceeds `ttlMs`,
+ * cascading along sourcePointers. Confirmed beliefs are retained by default
+ * (a confirmed preference shouldn't expire just because it's old).
+ */
+export function applyRetention(store, opts) {
+    const now = opts.now ?? Date.now();
+    const keepConfirmed = opts.keepConfirmed ?? true;
+    const all = store.readAll();
+    const inOrigin = (r) => opts.origin === undefined || recordMatchesOriginFilter(r, opts.origin);
+    // A fact is PURGE-ELIGIBLE only when it is in-origin AND older than the TTL AND not
+    // a kept-confirmed belief. ORIGIN SCOPE: without it an owner-invoked retention would
+    // purge channel peers' facts wholesale (a cross-principal breach). Omitted ⇒ whole
+    // store (the internal/admin default).
+    const eligible = (r) => inOrigin(r) && now - r.createdAt > opts.ttlMs && !(keepConfirmed && r.status === "confirmed");
+    const expired = all.filter(eligible).map((r) => r.memoryId);
+    if (expired.length === 0)
+        return { purged: [] };
+    // Cascade along sourcePointers — but re-apply the SAME eligibility to every cascade
+    // member, NOT just origin. Otherwise a same-origin fact that merely CITES an expired
+    // seed is hard-purged even when it is itself CONFIRMED or WITHIN the TTL, silently
+    // breaking the keepConfirmed guarantee and the age contract (a brand-new fact that
+    // cited an old source would be destroyed). We keep the "no orphaned derivations"
+    // intent only among facts that are THEMSELVES expirable; a confirmed/young deriver is
+    // preserved (a kept orphan beats irreversibly shredding a still-valid belief).
+    const byId = new Map(all.map((r) => [r.memoryId, r]));
+    const bounded = [...cascadeFrom(all, expired)].filter((id) => {
+        const r = byId.get(id);
+        return r !== undefined && eligible(r);
+    });
+    if (bounded.length === 0)
+        return { purged: [] };
+    return { purged: store.purge(bounded) };
+}
+/** Full provenance view of one fact: links, backlinks, and the citation graph. */
+export function inspect(store, memoryId) {
+    const all = store.readAll();
+    const record = all.find((r) => r.memoryId === memoryId);
+    if (!record)
+        return undefined;
+    const derivedOf = buildDerivedIndex(all);
+    return {
+        record,
+        outbound: linksFrom(record),
+        backlinks: backlinksTo(all, memoryId),
+        derivedFrom: [...(record.sourcePointers ?? [])],
+        derives: derivedOf.get(memoryId) ?? [],
+    };
+}
+/** Export records — all, or scoped to one origin (portability / data-subject export). */
+export function exportMemory(store, opts = {}) {
+    const all = store.readAll();
+    return opts.origin ? all.filter((r) => recordMatchesOriginFilter(r, opts.origin)) : all;
+}
+//# sourceMappingURL=governance.js.map

package/dist/agents/memory/governance.js.map

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

package/dist/agents/memory/graph-export.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Memory Graph EXPORT — the data layer behind the "Memory Graph" dashboard view
+ * (nodes + typed edges + topic clusters + headline stats). A PURE function over a
+ * fact snapshot (host-import-free, so it travels with the brigade-tideline package);
+ * a gateway endpoint serves its output to the web UI. The force-directed LAYOUT is
+ * the frontend's job — this provides the graph, the clustering, and the counts.
+ */
+import { type MemoryLinkKind } from "./links.js";
+import type { MemoryRecord } from "./records.js";
+export type EdgeStrength = "strong" | "medium" | "weak";
+export interface GraphNode {
+    id: string;
+    /** a short content snippet for the node label */
+    label: string;
+    segment: string;
+    importance: number;
+    createdAt: number;
+    /** the community this node belongs to (links to a {@link GraphCluster}.id) */
+    clusterId: string;
+    sourceType?: string;
+}
+export interface GraphEdge {
+    from: string;
+    to: string;
+    kind: MemoryLinkKind;
+    strength: EdgeStrength;
+}
+export interface GraphCluster {
+    id: string;
+    /** the cluster's representative subject/snippet (an LLM topic-label is the enhancement) */
+    label: string;
+    size: number;
+}
+export interface MemoryGraphStats {
+    totalMemories: number;
+    connections: number;
+    clusters: number;
+    /** segment → count (the donut breakdown) */
+    byType: Record<string, number>;
+    /** memories created within the last 7 days (the "vs last 7 days" delta numerator) */
+    addedLast7d: number;
+}
+export interface MemoryGraphExport {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+    clusters: GraphCluster[];
+    stats: MemoryGraphStats;
+}
+/**
+ * Build the dashboard graph payload from a fact snapshot (e.g. `FactStore.readAll()`
+ * / `list({ limit })`). `maxNodes` caps the node set returned for the VISUALIZATION
+ * (top-importance first); the clusters + stats are always computed over the full
+ * active set. Active facts only — archived/pruned are excluded.
+ */
+export declare function exportMemoryGraph(records: readonly MemoryRecord[], opts?: {
+    now?: number;
+    maxNodes?: number;
+}): MemoryGraphExport;
+//# sourceMappingURL=graph-export.d.ts.map

package/dist/agents/memory/graph-export.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-export.d.ts","sourceRoot":"","sources":["../../../src/agents/memory/graph-export.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAa,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,SAAS;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,8EAA8E;IAC9E,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,SAAS;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,YAAY,CAAC;CACvB;AAED,MAAM,WAAW,YAAY;IAC5B,EAAE,EAAE,MAAM,CAAC;IACX,2FAA2F;IAC3F,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,gBAAgB;IAChC,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,qFAAqF;IACrF,WAAW,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IACjC,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,KAAK,EAAE,gBAAgB,CAAC;CACxB;AA8ED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAO,GAC5C,iBAAiB,CAmGnB"}

package/dist/agents/memory/graph-export.js

@@ -0,0 +1,181 @@
+/**
+ * Memory Graph EXPORT — the data layer behind the "Memory Graph" dashboard view
+ * (nodes + typed edges + topic clusters + headline stats). A PURE function over a
+ * fact snapshot (host-import-free, so it travels with the brigade-tideline package);
+ * a gateway endpoint serves its output to the web UI. The force-directed LAYOUT is
+ * the frontend's job — this provides the graph, the clustering, and the counts.
+ */
+import { linksFrom } from "./links.js";
+const DAY_MS = 86_400_000;
+/** Edge strength by kind → the UI's strong/medium/weak line styles. Definitive
+ *  lifecycle edges + genuine conflicts = strong; derivation/support + the typed
+ *  factual taxonomy = medium; generic/thematic association = weak. */
+function strengthOf(kind) {
+    switch (kind) {
+        case "supersedes":
+        case "transition":
+        case "corrects":
+        case "contradicts":
+        case "contrasts_with": // a genuine tension/conflict reads as a strong, review-worthy edge
+            return "strong";
+        case "derived_from":
+        case "supports":
+        // the typed factual taxonomy — real, directly-supported relationships
+        case "causes":
+        case "caused_by":
+        case "part_of":
+        case "precedes":
+        case "follows":
+        case "enables":
+        case "blocks":
+        case "co_constrains":
+        case "located_at":
+        case "uses":
+        case "works_on":
+        case "relates_to":
+            return "medium";
+        default:
+            return "weak"; // relates, same_topic (thematic/quarantined)
+    }
+}
+const STRENGTH_WEIGHT = { strong: 1, medium: 0.6, weak: 0.3 };
+/** Deterministic weighted label-propagation community detection over the typed-link
+ *  graph (undirected, edge weight = strength). Lightweight + dependency-free; returns
+ *  node id → community-representative id. A heavier Louvain/Leiden pass or an LLM
+ *  topic-label is the enhancement; this gives stable communities for the dashboard. */
+function detectCommunities(nodeIds, adjacency) {
+    const label = new Map(nodeIds.map((id) => [id, id]));
+    const order = [...nodeIds].sort(); // fixed order ⇒ deterministic result
+    for (let iter = 0; iter < 20; iter++) {
+        let changed = false;
+        for (const id of order) {
+            const nbrs = adjacency.get(id);
+            if (!nbrs || nbrs.length === 0)
+                continue;
+            const tally = new Map();
+            for (const { to, w } of nbrs) {
+                const l = label.get(to);
+                if (l !== undefined)
+                    tally.set(l, (tally.get(l) ?? 0) + w);
+            }
+            let best = label.get(id);
+            let bestW = -1;
+            for (const [l, w] of [...tally].sort((a, b) => a[0].localeCompare(b[0]))) {
+                // tie-break by label string (the sort above) ⇒ deterministic winner
+                if (w > bestW) {
+                    bestW = w;
+                    best = l;
+                }
+            }
+            if (best !== label.get(id)) {
+                label.set(id, best);
+                changed = true;
+            }
+        }
+        if (!changed)
+            break;
+    }
+    return label;
+}
+function snippet(content, max = 48) {
+    const s = content.trim().replace(/\s+/g, " ");
+    return s.length <= max ? s : `${s.slice(0, max - 1)}…`;
+}
+/**
+ * Build the dashboard graph payload from a fact snapshot (e.g. `FactStore.readAll()`
+ * / `list({ limit })`). `maxNodes` caps the node set returned for the VISUALIZATION
+ * (top-importance first); the clusters + stats are always computed over the full
+ * active set. Active facts only — archived/pruned are excluded.
+ */
+export function exportMemoryGraph(records, opts = {}) {
+    const now = opts.now ?? Date.now();
+    const active = records.filter((r) => r.lifecycle === "active");
+    const activeIds = new Set(active.map((r) => r.memoryId));
+    // Edges (target must also be active — no dangling) + an undirected weighted
+    // adjacency for community detection. Dedupe the EXPORTED edges by unordered
+    // pair+kind so a bidirectional `relates` shows as one line, not two.
+    const adjacency = new Map();
+    const addAdj = (a, b, w) => {
+        let arr = adjacency.get(a);
+        if (!arr) {
+            arr = [];
+            adjacency.set(a, arr);
+        }
+        arr.push({ to: b, w });
+    };
+    const seenEdge = new Set();
+    const edges = [];
+    for (const r of active) {
+        for (const link of linksFrom(r)) {
+            if (!activeIds.has(link.target))
+                continue;
+            const strength = strengthOf(link.kind);
+            const w = STRENGTH_WEIGHT[strength];
+            addAdj(r.memoryId, link.target, w);
+            addAdj(link.target, r.memoryId, w);
+            const [x, y] = r.memoryId < link.target ? [r.memoryId, link.target] : [link.target, r.memoryId];
+            const key = `${x}|${y}|${link.kind}`;
+            if (seenEdge.has(key))
+                continue;
+            seenEdge.add(key);
+            edges.push({ from: r.memoryId, to: link.target, kind: link.kind, strength });
+        }
+    }
+    // Communities over the full active graph.
+    const community = detectCommunities(active.map((r) => r.memoryId), adjacency);
+    // Cluster summary: group by community, label by the highest-importance member.
+    const byCommunity = new Map();
+    for (const r of active) {
+        const c = community.get(r.memoryId) ?? r.memoryId;
+        let arr = byCommunity.get(c);
+        if (!arr) {
+            arr = [];
+            byCommunity.set(c, arr);
+        }
+        arr.push(r);
+    }
+    const clusters = [...byCommunity.entries()]
+        .map(([id, members]) => {
+        const rep = [...members].sort((a, b) => b.importance - a.importance || a.memoryId.localeCompare(b.memoryId))[0];
+        return { id, label: rep.subjectKey?.trim() || snippet(rep.content), size: members.length };
+    })
+        .sort((a, b) => b.size - a.size || a.id.localeCompare(b.id));
+    // Nodes for the viz: cap to maxNodes by importance (clusters/stats use the full set).
+    const maxNodes = opts.maxNodes && opts.maxNodes > 0 ? opts.maxNodes : active.length;
+    const vizRecords = active.length <= maxNodes
+        ? active
+        : [...active]
+            .sort((a, b) => b.importance - a.importance || a.memoryId.localeCompare(b.memoryId))
+            .slice(0, maxNodes);
+    const vizIds = new Set(vizRecords.map((r) => r.memoryId));
+    const nodes = vizRecords.map((r) => ({
+        id: r.memoryId,
+        label: snippet(r.content),
+        segment: r.segment,
+        importance: r.importance,
+        createdAt: r.createdAt,
+        clusterId: community.get(r.memoryId) ?? r.memoryId,
+        ...(r.sourceType !== undefined ? { sourceType: r.sourceType } : {}),
+    }));
+    // Trim edges to the viz subset (both endpoints must be in vizIds).
+    // stats.connections uses the full `edges` count — only the rendered graph is trimmed.
+    const vizEdges = edges.filter((e) => vizIds.has(e.from) && vizIds.has(e.to));
+    // Stats over the FULL active set.
+    const byType = {};
+    for (const r of active)
+        byType[r.segment] = (byType[r.segment] ?? 0) + 1;
+    const addedLast7d = active.filter((r) => now - r.createdAt <= 7 * DAY_MS).length;
+    return {
+        nodes,
+        edges: vizEdges,
+        clusters,
+        stats: {
+            totalMemories: active.length,
+            connections: edges.length,
+            clusters: clusters.length,
+            byType,
+            addedLast7d,
+        },
+    };
+}
+//# sourceMappingURL=graph-export.js.map

package/dist/agents/memory/graph-export.js.map

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

package/dist/agents/memory/graph-recall.d.ts

@@ -0,0 +1,42 @@
+import { type Embedder } from "./embedder.js";
+import type { MemoryRecord } from "./records.js";
+export interface GraphRecallOpts {
+    limit?: number;
+    /** How many top hybrid hits seed the walk (default 4). */
+    seedCount?: number;
+    /** Hop decay δ (default 0.5). */
+    hopDecay?: number;
+    /** Max hops (default 2). */
+    maxHops?: number;
+    /** Per-node fan-out cap (default 10). */
+    fanOut?: number;
+    /** RRF constant (default 60). */
+    rrfK?: number;
+    minSim?: number;
+    /** Force the walk on/off (skips the route-gate) — for eval/tests. */
+    forceWalk?: boolean;
+}
+export interface GraphRecallResult {
+    record: MemoryRecord;
+    score: number;
+    /** True when this fact was pulled in by the graph walk (not a seed). */
+    viaGraph: boolean;
+    hop?: number;
+}
+/**
+ * Graph-augmented recall. `active` MUST be the origin-filtered, active
+ * (non-superseded) candidate set. Returns top-k fused results; when the
+ * route-gate declines, returns the pure hybrid ranking (single-fact flat).
+ */
+/**
+ * ASYNC graph recall — pre-embeds the query (so a LEARNED async embedder works),
+ * wraps it in a sync embedder, then runs the UNCHANGED sync {@link recallWithGraph}
+ * (whose internal `recallHybrid` then uses the pre-embedded query). The pre-embed
+ * trick (same as `recallHybridAsync`) keeps the graph walk sync — no refactor.
+ * With the sync HRR default, awaiting a sync embed is a no-op → identical result;
+ * with a learned embedder this is what delivers true-synonymy graph recall on the
+ * live auto-recall path.
+ */
+export declare function recallWithGraphAsync(active: readonly MemoryRecord[], query: string, opts?: GraphRecallOpts, now?: number, embedder?: Embedder): Promise<GraphRecallResult[]>;
+export declare function recallWithGraph(active: readonly MemoryRecord[], query: string, opts?: GraphRecallOpts, now?: number, embedder?: Embedder): GraphRecallResult[];
+//# sourceMappingURL=graph-recall.d.ts.map

package/dist/agents/memory/graph-recall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"graph-recall.d.ts","sourceRoot":"","sources":["../../../src/agents/memory/graph-recall.ts"],"names":[],"mappings":"AAsBA,OAAO,EAAsB,KAAK,QAAQ,EAAE,MAAM,eAAe,CAAC;AAElE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,WAAW,eAAe;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,0DAA0D;IAC1D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iCAAiC;IACjC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iCAAiC;IACjC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,SAAS,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IACjC,MAAM,EAAE,YAAY,CAAC;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,QAAQ,EAAE,OAAO,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;CACb;AA8BD;;;;GAIG;AACH;;;;;;;;GAQG;AACH,wBAAsB,oBAAoB,CACzC,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,eAAoB,EAC1B,GAAG,GAAE,MAAmB,EACxB,QAAQ,GAAE,QAA+B,GACvC,OAAO,CAAC,iBAAiB,EAAE,CAAC,CAe9B;AAED,wBAAgB,eAAe,CAC9B,MAAM,EAAE,SAAS,YAAY,EAAE,EAC/B,KAAK,EAAE,MAAM,EACb,IAAI,GAAE,eAAoB,EAC1B,GAAG,GAAE,MAAmB,EACxB,QAAQ,GAAE,QAA+B,GACvC,iBAAiB,EAAE,CAsFrB"}

package/dist/agents/memory/graph-recall.js

@@ -0,0 +1,165 @@
+// src/agents/memory/graph-recall.ts
+//
+// Tideline Step 20 — graph-augmented recall (the gated spreading-activation walk).
+//
+// Pipeline: ROUTE-gate → SEED (hybrid) → SPREAD ≤2 hops → degree-normalize →
+// 3-way RRF (lexical ⊕ vector ⊕ graph) → drop superseded → top-k.
+//
+//   • ROUTE-gate — the walk engages ONLY for multi-hop / temporal intent (query
+//     markers, OR ≥2 seeds that are graph-connected). A plain single-fact query
+//     skips the walk entirely → IDENTICAL to recallHybrid (the "single-fact flat,
+//     no regression" guarantee is the gate, not luck).
+//   • SPREAD — bounded BFS from the seeds over the graph (δ per hop, fan-out cap).
+//   • degree-normalize — hub nodes (high degree) are down-weighted so a popular
+//     fact can't dominate the graph lane.
+//   • 3-way RRF — reciprocal-rank fusion of the lexical rank, the vector rank,
+//     and the graph-activation rank; a fact absent from a lane simply doesn't
+//     score in it (standard RRF).
+//
+// ORIGIN SAFETY: the caller passes an already origin-filtered candidate set, so
+// the graph is per-origin and every hop stays in-origin (Step 19 invariant).
+import { buildGraph, neighbors, spread } from "./graph.js";
+import { getDefaultEmbedder } from "./embedder.js";
+import { recallHybrid } from "./hybrid.js";
+const TEMPORAL = /\b(when|before|after|previously|used to|history|changed|evolved|became|earlier|originally|since|ago|no longer|anymore)\b/i;
+const RELATIONAL = /\b(related|because|due to|led to|connected|linked|associated|caused|reason|affect|depend)\b/i;
+/** ROUTE-gate: should the spreading walk engage for this query? Multi-hop /
+ *  temporal intent only — a single-fact query returns false so recall is left
+ *  exactly as the hybrid produced it. */
+function shouldWalk(query, seedIds, g) {
+    if (TEMPORAL.test(query) || RELATIONAL.test(query))
+        return true;
+    // Otherwise walk only if the SEEDS themselves are graph-connected (the query
+    // pulled multiple facts that link to each other → multi-hop context exists).
+    const seedSet = new Set(seedIds);
+    for (const id of seedIds) {
+        for (const n of neighbors(g, id)) {
+            if (seedSet.has(n))
+                return true; // an edge BETWEEN two seeds
+        }
+    }
+    return false;
+}
+/** RRF contribution: 1 / (k + rank). */
+function rrf(rank, k) {
+    return 1 / (k + rank);
+}
+/**
+ * Graph-augmented recall. `active` MUST be the origin-filtered, active
+ * (non-superseded) candidate set. Returns top-k fused results; when the
+ * route-gate declines, returns the pure hybrid ranking (single-fact flat).
+ */
+/**
+ * ASYNC graph recall — pre-embeds the query (so a LEARNED async embedder works),
+ * wraps it in a sync embedder, then runs the UNCHANGED sync {@link recallWithGraph}
+ * (whose internal `recallHybrid` then uses the pre-embedded query). The pre-embed
+ * trick (same as `recallHybridAsync`) keeps the graph walk sync — no refactor.
+ * With the sync HRR default, awaiting a sync embed is a no-op → identical result;
+ * with a learned embedder this is what delivers true-synonymy graph recall on the
+ * live auto-recall path.
+ */
+export async function recallWithGraphAsync(active, query, opts = {}, now = Date.now(), embedder = getDefaultEmbedder()) {
+    const qv = (await embedder.embed([query]))[0] ?? [];
+    // Carry the embedder's optional recovery-lane floor onto the sync shim so the
+    // wrapper stays transparent: recallHybrid resolves `minSim` as
+    // `opts.minSim ?? embedder.minSim ?? 0.3`, so dropping it here would silently
+    // fall back to 0.3 for any learned embedder that sets its own floor — a
+    // different vector-recovery lane than the sync path on the same query. With the
+    // sync HRR default (no minSim) this spread is a literal no-op → identical result.
+    const preEmbedded = {
+        id: embedder.id,
+        dims: embedder.dims,
+        ...(embedder.minSim !== undefined ? { minSim: embedder.minSim } : {}),
+        embed: () => [qv],
+    };
+    return recallWithGraph(active, query, opts, now, preEmbedded);
+}
+export function recallWithGraph(active, query, opts = {}, now = Date.now(), embedder = getDefaultEmbedder()) {
+    const limit = opts.limit && opts.limit > 0 ? opts.limit : 8;
+    const seedCount = opts.seedCount ?? 4;
+    const hopDecay = opts.hopDecay ?? 0.5;
+    const maxHops = opts.maxHops ?? 2;
+    const fanOut = opts.fanOut ?? 10;
+    const rrfK = opts.rrfK ?? 60;
+    // Bi-temporal valid-time gate (matches FactStore.recall/search and the eval
+    // oracle): a fact whose future-dated `validTo` has now passed is excluded even
+    // though its lifecycle is still "active". Applied at ENTRY so the seeds, the
+    // graph, and the fused set are all gated identically — no expired fact can leak
+    // into the model's pre-turn context via any lane (lexical / vector / graph).
+    const fresh = active.filter((r) => r.validTo === undefined || r.validTo > now);
+    // SEED — hybrid recall over the full candidate set (it owns lexical + vector).
+    const seedHybridOpts = { limit: Math.max(limit, seedCount * 2) };
+    if (opts.minSim !== undefined)
+        seedHybridOpts.minSim = opts.minSim;
+    const seed = recallHybrid(fresh, query, embedder, now, seedHybridOpts);
+    if (seed.length === 0)
+        return [];
+    const seedIds = seed.slice(0, seedCount).map((s) => s.record.memoryId);
+    const g = buildGraph(fresh);
+    // ROUTE-gate — single-fact / non-relational → return the pure hybrid order.
+    if (!opts.forceWalk && !shouldWalk(query, seedIds, g)) {
+        return seed.slice(0, limit).map((s) => ({ record: s.record, score: s.score, viaGraph: false }));
+    }
+    // SPREAD from the seeds (bounded).
+    const hops = spread(g, seedIds, { maxHops, fanOut });
+    // Lane ranks. Lexical + vector come from the hybrid seed (its order encodes
+    // the BM25-primary ⊕ vector-recovery rank); the graph lane is the spread,
+    // degree-normalized and hop-decayed.
+    const lexRank = new Map();
+    const vecRank = new Map();
+    seed.forEach((s) => {
+        // LEXICAL lane: ONLY actual BM25 primaries (recallHybrid sets `lexRank` for
+        // primaries alone). A vector-RECOVERY fact — one BM25 MISSED — has lexRank
+        // undefined; it must NOT be injected into the lexical lane via a positional
+        // fallback (the old `?? i + 1`), or it gets double-counted (lexical ⊕ vector) and
+        // can out-rank a genuine lexical hit. It scores only in the vector lane below.
+        if (s.lexRank !== undefined)
+            lexRank.set(s.record.memoryId, s.lexRank);
+        if (s.vecRank !== undefined)
+            vecRank.set(s.record.memoryId, s.vecRank);
+    });
+    const graphWeight = new Map();
+    for (const [id, hop] of hops) {
+        // EXCLUDE the hop-0 seeds: they already rank via lex⊕vec, so they must NOT
+        // also enter the graph lane (degree-normalisation there could demote a
+        // genuine top lexical hit). The graph lane only ranks DISCOVERED facts
+        // (hop ≥ 1), which then fuse in alongside — never reordering the seeds
+        // among themselves. "No harm where lexical is already right."
+        if (hop === 0)
+            continue;
+        const degree = neighbors(g, id).length;
+        // δ^hop, down-weighted by degree so a hub doesn't dominate the graph lane.
+        graphWeight.set(id, hopDecay ** hop / Math.sqrt(1 + degree));
+    }
+    const graphRank = new Map();
+    [...graphWeight.entries()]
+        .sort((a, b) => b[1] - a[1])
+        .forEach(([id], i) => graphRank.set(id, i + 1));
+    // 3-way RRF over the union of all lanes' ids.
+    const ids = new Set([...lexRank.keys(), ...vecRank.keys(), ...graphRank.keys()]);
+    const byId = new Map(fresh.map((r) => [r.memoryId, r]));
+    const fused = [];
+    for (const id of ids) {
+        const record = byId.get(id);
+        if (!record || record.lifecycle !== "active")
+            continue; // drop superseded
+        let score = 0;
+        if (lexRank.has(id))
+            score += rrf(lexRank.get(id), rrfK);
+        if (vecRank.has(id))
+            score += rrf(vecRank.get(id), rrfK);
+        if (graphRank.has(id))
+            score += rrf(graphRank.get(id), rrfK);
+        const isSeed = lexRank.has(id) || vecRank.has(id);
+        fused.push({
+            record,
+            score,
+            viaGraph: !isSeed,
+            ...(hops.has(id) ? { hop: hops.get(id) } : {}),
+        });
+    }
+    // Tie-break by recency (deterministic — no clock/random in the sort).
+    fused.sort((a, b) => b.score - a.score || b.record.createdAt - a.record.createdAt);
+    return fused.slice(0, limit);
+}
+//# sourceMappingURL=graph-recall.js.map

package/dist/agents/memory/graph-recall.js.map

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