@spinabot/brigade 0.1.2 → 1.0.1

package/dist/agents/memory/relationship-extract.js

@@ -0,0 +1,454 @@
+/**
+ * Semantic relationship extraction — the LLM-judged TYPED edges that turn the
+ * memory graph into a web linked by MEANING, not by the structural subjectKey/hub
+ * taxonomy.
+ *
+ * The problem this solves: the vault renders Map → topic-hub(subjectKey) → fact.
+ * Facts link UP to their hub but never to EACH OTHER by meaning, and the model-free
+ * embedder rarely fires a synonymy bridge. The renderer ALREADY turns a record's
+ * typed edges into `## Related` `[[wikilinks]]` — the missing piece was that nothing
+ * was MINTING real edges between semantically-related facts. The model does it here.
+ *
+ * RESEARCH-BACKED DESIGN (GraphRAG / Mem0 / Graphiti-Zep / LangChain
+ * LLMGraphTransformer / Neo4j; PKM: Zettelkasten, Matuschak, Nick Milo). The field's
+ * consensus, applied here:
+ *   • TYPED vocabulary (a CLOSED set: causes/part_of/co_constrains/uses/… — see
+ *     EXTRACTOR_FACTUAL_KINDS in links.ts) beats a single generic `relates`.
+ *   • Each edge carries a REASON (justification → precision) + a STRENGTH 1-5 (the
+ *     post-filter axis). Reason is MANDATORY.
+ *   • A hard GATE: link only on a DIRECT, STATED basis — never on a shared topic /
+ *     keyword / category / same-person co-occurrence. Plus a MULTI-VALUED guard
+ *     (different objects of the same relation are NOT a contradiction).
+ *   • Thematic / same-domain pairs (dark-mode ~ Obsidian "both tooling") are an
+ *     over-linking risk → kept in a SEPARATE, capped, low-strength `same_topic` lane
+ *     (the vault renders these in their own "## Same area" section), never mingled
+ *     with the strong factual edges.
+ *   • A GLEANING pass (one extra turn: "did you miss any directly-supported links?")
+ *     for recall, capped at one pass and used in the on-demand relink.
+ *
+ * TWO entry points, ONE judgement core:
+ *   1. Post-turn (incremental) — `buildCandidateBlock` + `resolveRelationshipPairs`.
+ *      The post-turn extraction sweep appends a BOUNDED candidate set (top-K most-
+ *      related existing same-origin facts, via hybrid recall) to the SAME extraction
+ *      prompt and parses a `relationships` array out of the SAME reply. No extra
+ *      per-turn LLM round-trip — the relationships ride the one extraction call.
+ *      (Gleaning is OPTIONAL here to keep the per-turn path cheap.)
+ *   2. On-demand (`runRelinkPass`) — a one-shot owner-gated maintenance pass over an
+ *      origin's ACTIVE facts: identify ALL genuine relationships and write the edges,
+ *      so the operator can populate real edges on their CURRENT facts immediately.
+ *      Cost-bounded (windowed batches + a hard fact cap), idempotent, and it runs the
+ *      GLEANING follow-up per window.
+ *
+ * HARD INVARIANTS (enforced in `resolveRelationshipPairs`, the single chokepoint):
+ *   • NO FABRICATION — a pair is emitted only when BOTH endpoints resolve to a
+ *     memoryId that EXISTS in the considered set. A hallucinated id is dropped.
+ *   • NO SELF-EDGES — a == b is dropped.
+ *   • STRICT TYPE — an edge whose `type` is not in the taxonomy (the closed factual
+ *     set ∪ `same_topic`) is dropped. Reason MANDATORY (an edge with no reason is
+ *     dropped). STRENGTH filter: a factual edge below MIN_FACTUAL_STRENGTH is dropped;
+ *     `same_topic` is forced to the thematic ceiling and CAPPED per fact.
+ *   • ORIGIN-SCOPED — the considered set is pre-filtered to ONE origin by the caller,
+ *     and `linkRelated` is same-origin by contract; an edge can never relate
+ *     owner↔channel.
+ *   • DEDUPED — duplicate/mirror pairs collapse; `linkRelated` is itself idempotent
+ *     (it skips an edge already present), so re-running writes nothing new.
+ */
+import { isExtractorFactualKind } from "./links.js";
+import { balancedObjects } from "./json-scan.js";
+/* ───────────────────────── strength / cap policy ───────────────────────── */
+/** Minimum strength (1-5) a FACTUAL edge must reach to be written. Below this the
+ *  edge is dropped (the post-filter that turns the model's strength judgement into
+ *  precision). 3 = "moderately supported" — weaker claims are noise. */
+export const MIN_FACTUAL_STRENGTH = 3;
+/** Thematic ceiling: a `same_topic` edge is ALWAYS clamped to at most this strength
+ *  (it is a same-domain hint, not a strong relation — its claimed strength is
+ *  irrelevant). Low by design so the vault renders it as the weak thematic link it is. */
+export const SAME_TOPIC_STRENGTH = 2;
+/** Max `same_topic` (thematic) edges kept PER fact in one resolution — few per fact,
+ *  so a same-domain pair can appear honestly without webbing everything together. */
+export const MAX_SAME_TOPIC_PER_FACT = 2;
+/* ───────────────────────── shared prompt fragment + parsing ───────────────────────── */
+/** The GATE — the precision instruction, shared by the per-turn fragment and the
+ *  relink prompt. Kept verbatim-ish per the design so both paths judge identically. */
+const RELATIONSHIP_GATE = [
+    "Create an edge ONLY if there is a DIRECT, STATED basis AND surfacing one fact would",
+    "genuinely help when looking at the other. Do NOT link two facts merely because they",
+    "share a topic, category, keyword, or are about the same person — mere co-occurrence is",
+    "NOT a relationship. (Example to REJECT: vegetarian + lives-in-Bangalore — no direct",
+    "basis. Example to KEEP: vegetarian + peanut-allergy — both are dietary constraints that",
+    "co-apply.) MULTI-VALUED GUARD: two facts that are DIFFERENT OBJECTS of the same relation",
+    '(e.g. "owns a dog" and "owns a cat") are NOT a contradiction — do not mark them contrasts_with.',
+].join("\n");
+/** The TYPED taxonomy lines (closed set, one-line definitions) shared by both prompts. */
+const RELATIONSHIP_TAXONOMY = [
+    "Each edge MUST have a TYPE from this CLOSED set (use the most specific that fits):",
+    "  • causes / caused_by — one fact is the reason for / a consequence of the other.",
+    "  • part_of — one fact is a component or member of the other.",
+    "  • precedes / follows — one happens before / after the other (sequence or schedule).",
+    "  • enables / blocks — one makes the other possible / prevents it.",
+    "  • co_constrains — two CONSTRAINTS that co-apply (e.g. two dietary rules, two limits).",
+    "  • located_at — one fact is situated at/in the other (place or region).",
+    "  • uses / works_on — one fact uses/depends on, or concerns work on, the other.",
+    "  • contrasts_with — a genuine tension/contradiction between the two (flagged for review).",
+    "  • relates_to — DISCOURAGED generic fallback; use ONLY with an especially strong reason.",
+    "  • same_topic — THEMATIC / same-domain only (e.g. two unrelated tooling preferences). Use",
+    "    this — NOT a factual type — whenever the only link is a shared area/category.",
+].join("\n");
+/**
+ * The relationship half of the extraction output schema, appended to the
+ * EXTRACTION_PROMPT so the model returns relationships in the SAME reply as the
+ * facts (no second call). The model references NEW facts by their 0-based index in
+ * the `facts` array it is emitting (`"new:0"`) and EXISTING candidate facts by the
+ * `id` shown in the candidate block (`"mem_…"`).
+ */
+export const RELATIONSHIP_PROMPT_FRAGMENT = [
+    "",
+    "ALSO identify GENUINE, DIRECTLY-SUPPORTED relationships between facts — relate facts you",
+    "are emitting now to EACH OTHER and to any EXISTING facts listed under EXISTING FACTS below.",
+    "",
+    RELATIONSHIP_GATE,
+    "",
+    RELATIONSHIP_TAXONOMY,
+    "",
+    'Each edge is {"a":<ref>,"b":<ref>,"type":<one of the types above>,"reason":<short why, MANDATORY>,"strength":<1-5>}.',
+    "  • Reference a fact you are emitting now as \"new:<index>\" (0-based index into your facts array).",
+    "  • Reference an EXISTING fact by the id shown in EXISTING FACTS (e.g. \"mem_ab12\"). NEVER invent an id.",
+    "  • strength 1-5 = how direct/important the link is. Reserve 4-5 for strongly-stated links.",
+    "  • No self-pairs. Prefer FEW high-quality edges over many. A `same_topic` edge is always weak.",
+    "",
+    "Extend the SAME JSON object with a \"relationships\" array:",
+    '{"facts":[…],"relationships":[{"a":"new:0","b":"mem_ab12","type":"co_constrains","reason":"both are dietary constraints","strength":4}]}',
+    'Omit "relationships" or use [] if there are no genuine relationships.',
+].join("\n");
+/**
+ * The full prompt for the ON-DEMAND relink pass (no new facts — only existing ones).
+ * The model is given the numbered fact set and returns typed relationship edges
+ * referencing the printed ids ONLY. Tool-less; one call per batch window.
+ */
+export const RELINK_PROMPT = [
+    "You are a memory-graph linker for a personal AI assistant.",
+    "You are given a numbered list of the user's stored facts (each with an id and content).",
+    "Identify GENUINE, DIRECTLY-SUPPORTED relationships between PAIRS of these facts.",
+    "",
+    RELATIONSHIP_GATE,
+    "",
+    RELATIONSHIP_TAXONOMY,
+    "",
+    "Return STRICT JSON only — no prose, no markdown fences:",
+    '{"relationships":[{"a":"<id>","b":"<id>","type":"<type>","reason":"short why","strength":1-5}]}',
+    "",
+    "Rules:",
+    "  • Use ONLY the ids printed in the list. NEVER invent an id. No self-pairs. Deduplicate.",
+    "  • Every edge needs a TYPE from the closed set above and a MANDATORY reason. Prefer FEW high-quality edges.",
+    '  • Return {"relationships":[]} if nothing is genuinely related.',
+    "Respond with ONLY the JSON object.",
+].join("\n");
+/** The GLEANING follow-up — one extra turn asking the model to add any DIRECTLY-
+ *  supported edges it missed, in the SAME format. Capped at one pass (the caller does
+ *  not recurse). Recall booster; the gate still applies. */
+export const GLEANING_PROMPT = [
+    "Did you miss any DIRECTLY-SUPPORTED connections between the SAME facts (same ids)?",
+    "Apply the same gate: a direct, stated basis — never a mere shared topic/keyword/person.",
+    'Add ONLY new edges in the SAME JSON format ({"relationships":[{"a","b","type","reason","strength"}]}).',
+    'If there are none, reply exactly {"relationships":[]}.',
+].join("\n");
+/** A coerced strength in 1..5, or undefined when absent/garbage. */
+function coerceStrength(v) {
+    if (typeof v !== "number" || !Number.isFinite(v))
+        return undefined;
+    const n = Math.round(v);
+    return Math.max(1, Math.min(5, n));
+}
+/**
+ * Parse a `relationships` array out of a model reply. Robust to prose/fences and a
+ * leading stray object (same scan as {@link balancedObjects}): uses the FIRST top-
+ * level balanced object that carries a `relationships` array. Never throws; returns
+ * [] when absent. Drops malformed entries (missing/empty `a` or `b`). The `type`,
+ * `reason`, and `strength` fields are carried through verbatim — strict TYPE
+ * validation + the reason/strength gate live in {@link resolveRelationshipPairs}
+ * (the single chokepoint), so this stays a pure parser.
+ */
+export function parseRelationshipRefs(text) {
+    if (!text)
+        return [];
+    for (const block of balancedObjects(text)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(block);
+        }
+        catch {
+            continue;
+        }
+        if (Array.isArray(parsed.relationships)) {
+            const out = [];
+            for (const raw of parsed.relationships) {
+                if (!raw || typeof raw !== "object")
+                    continue;
+                const r = raw;
+                if (typeof r.a !== "string" || typeof r.b !== "string")
+                    continue;
+                const a = r.a.trim();
+                const b = r.b.trim();
+                if (!a || !b)
+                    continue;
+                const strength = coerceStrength(r.strength);
+                out.push({
+                    a,
+                    b,
+                    ...(typeof r.type === "string" ? { type: r.type.trim() } : {}),
+                    ...(typeof r.reason === "string" ? { reason: r.reason } : {}),
+                    ...(strength !== undefined ? { strength } : {}),
+                });
+            }
+            return out;
+        }
+    }
+    return [];
+}
+/* ───────────────────────── bounded candidate retrieval ───────────────────────── */
+/** Default cap on how many existing facts seed the per-turn relationship judgement.
+ *  Small + high-signal: the model relates NEW facts to the most-related existing ones,
+ *  NOT to the whole store (which would blow the prompt + cost on a large vault). */
+export const DEFAULT_CANDIDATE_K = 10;
+/**
+ * Fetch a BOUNDED candidate set of existing ACTIVE same-origin facts most related to
+ * the new facts, by reusing the existing hybrid recall (BM25 ⊕ vector) — NEVER the
+ * whole store. We query with the concatenated new-fact text and take the top-K. The
+ * candidate set is origin-filtered (peer facts never seed an owner turn's judgement).
+ * Returns at most `k` records; passive (markAccessed:false — seeding the graph must
+ * not reinforce decay on the candidates).
+ */
+export function fetchRelationshipCandidates(store, newFactContents, origin, k = DEFAULT_CANDIDATE_K) {
+    const query = newFactContents.join("\n").trim();
+    if (!query)
+        return [];
+    const limit = k > 0 ? k : DEFAULT_CANDIDATE_K;
+    return store
+        .recall(query, { limit, markAccessed: false, ...(origin !== undefined ? { origin } : {}) })
+        .map(({ score: _score, ...rec }) => rec);
+}
+/**
+ * Render the candidate set as the EXISTING FACTS block appended to the extraction
+ * prompt. Each line is `[<id>] <content>` so the model can reference an existing fact
+ * by its real memoryId. Returns "" when there are no candidates (the prompt then just
+ * relates new facts to each other). Content is truncated defensively for prompt size.
+ */
+export function buildCandidateBlock(candidates) {
+    if (candidates.length === 0)
+        return "";
+    const lines = candidates.map((r) => `[${r.memoryId}] ${r.content.slice(0, 200)}`);
+    return ["", "EXISTING FACTS (relate the new facts to these where genuinely related):", ...lines].join("\n");
+}
+/**
+ * Resolve model-returned relationship refs into validated, TYPED `{a,b,kind,reason,
+ * strength}` edges — THE single place every guard lives.
+ *
+ *   • `newFactIds[i]` maps `"new:<i>"` → the memoryId of the i-th NEW fact actually
+ *     written this turn (undefined entries — a fact that deduped/was-blocked and has
+ *     no row — make that ref unresolvable, so it's dropped). For the on-demand relink
+ *     pass there are no new facts; pass `[]`.
+ *   • `existingIds` is the set of memoryIds the model was allowed to reference (the
+ *     candidate set for the per-turn path; the batch window for relink). An `"mem_…"`
+ *     ref is accepted ONLY if it is in this set — a hallucinated id is dropped.
+ *
+ * The guards, in order:
+ *   1. NO FABRICATION / NO SELF-EDGE — both endpoints resolve to a real, DISTINCT id.
+ *   2. STRICT TYPE — `type` must be a strong factual kind OR `same_topic`; anything
+ *      else (absent, unknown, or a store-minted lifecycle kind the model must not
+ *      mint) is dropped.
+ *   3. REASON MANDATORY — an edge with no non-empty reason is dropped.
+ *   4. STRENGTH FILTER — a FACTUAL edge below {@link MIN_FACTUAL_STRENGTH} is dropped
+ *      (default strength {@link MIN_FACTUAL_STRENGTH} when the model omitted it, so a
+ *      typed+reasoned edge isn't lost on a missing score); a `same_topic` edge is
+ *      forced to {@link SAME_TOPIC_STRENGTH} regardless of the claimed value.
+ *   5. SAME_TOPIC QUARANTINE CAP — at most {@link MAX_SAME_TOPIC_PER_FACT} thematic
+ *      edges may touch any one fact (highest-strength-then-stable first).
+ *   6. DEDUPE — order-independent on the unordered (a,b) pair; the FIRST surviving
+ *      edge for a pair wins (a factual edge beats a later same_topic on the same pair,
+ *      since the model is told to prefer the specific type).
+ *
+ * Origin isolation is the caller's job (the considered set is pre-filtered to one
+ * origin) and is additionally guaranteed by `linkRelated` being same-origin by contract.
+ */
+export function resolveRelationshipPairs(refs, newFactIds, existingIds) {
+    const resolve = (ref) => {
+        if (ref.startsWith("new:")) {
+            const idx = Number.parseInt(ref.slice(4), 10);
+            if (!Number.isInteger(idx) || idx < 0 || idx >= newFactIds.length)
+                return undefined;
+            return newFactIds[idx]; // may be undefined (a fact with no written row) → dropped
+        }
+        // An EXISTING-fact reference: accept ONLY an id actually in the considered set.
+        return existingIds.has(ref) ? ref : undefined;
+    };
+    // Order-independent pair key WITHOUT a NUL byte (a raw NUL has bitten this codebase
+    // twice). A `mem_…` id is `[a-z0-9_]` only, so a literal "|" is a printable separator
+    // that can never occur INSIDE an id — two distinct ids can't collide on it.
+    const pairKey = (a, b) => (a < b ? `${a}|${b}` : `${b}|${a}`);
+    const seen = new Set();
+    const sameTopicDeg = new Map();
+    const deg = (id) => sameTopicDeg.get(id) ?? 0;
+    const out = [];
+    for (const ref of refs) {
+        const a = resolve(ref.a);
+        const b = resolve(ref.b);
+        if (!a || !b || a === b)
+            continue; // (1) no fabrication, no self-edge
+        // (2) STRICT TYPE — must be a strong factual kind OR the thematic same_topic.
+        const type = ref.type ?? "";
+        const isSameTopic = type === "same_topic";
+        const isFactual = isExtractorFactualKind(type);
+        if (!isSameTopic && !isFactual)
+            continue; // absent / unknown / store-minted-only → drop
+        // (3) REASON MANDATORY.
+        const reason = (ref.reason ?? "").trim();
+        if (!reason)
+            continue;
+        // (4) STRENGTH FILTER / clamp.
+        let strength;
+        if (isSameTopic) {
+            strength = SAME_TOPIC_STRENGTH; // thematic edges are weak by definition
+        }
+        else {
+            // A typed+reasoned factual edge with NO score defaults to the floor (kept),
+            // but an explicit score below the floor is dropped (the precision filter).
+            strength = ref.strength ?? MIN_FACTUAL_STRENGTH;
+            if (strength < MIN_FACTUAL_STRENGTH)
+                continue;
+        }
+        const key = pairKey(a, b);
+        if (seen.has(key))
+            continue; // (6) dedupe (order-independent); first survivor wins
+        // (5) SAME_TOPIC QUARANTINE CAP — cap thematic degree per endpoint.
+        if (isSameTopic && (deg(a) >= MAX_SAME_TOPIC_PER_FACT || deg(b) >= MAX_SAME_TOPIC_PER_FACT))
+            continue;
+        seen.add(key);
+        if (isSameTopic) {
+            sameTopicDeg.set(a, deg(a) + 1);
+            sameTopicDeg.set(b, deg(b) + 1);
+        }
+        out.push({ a, b, kind: type, reason, strength });
+    }
+    return out;
+}
+/** Map a {@link ResolvedPair} to the `linkRelated` edge-arg shape (kept tiny so both
+ *  entry points write edges identically). */
+export function pairToLinkArg(p) {
+    return { a: p.a, b: p.b, kind: p.kind, reason: p.reason, strength: p.strength };
+}
+/**
+ * Map the facts JUST written this turn back to their stored memoryIds, in the SAME
+ * order as the `facts` array the model emitted — so `"new:<i>"` resolves to the right
+ * record. We look each content up via the store's idempotency probe
+ * ({@link FactStore.findEquivalentActive}), which finds the active same-origin record a
+ * content corresponds to (the row write/dedup/reinforce landed on). A content with no
+ * active row (blocked by the write-gate, or confined+dropped) maps to `undefined` →
+ * its `"new:<i>"` refs are dropped downstream.
+ */
+export function mapNewFactIds(store, contents, origin) {
+    return contents.map((c) => store.findEquivalentActive(c, origin)?.memoryId);
+}
+/* ───────────────────────── on-demand relink pass ───────────────────────── */
+/** Default window size for the relink pass — how many facts go into ONE LLM call.
+ *  Keeps a single prompt bounded; large active sets are processed in successive
+ *  windows so cost grows linearly (and capped by {@link RELINK_MAX_FACTS}). */
+export const RELINK_WINDOW = 40;
+/** Hard cap on how many active facts a single relink invocation considers, so the
+ *  cost of one operator click is bounded even on a very large vault. The most recent
+ *  facts are kept (most likely to be the ones the operator cares to link now). */
+export const RELINK_MAX_FACTS = 200;
+let relinkLlmFactory;
+/** Register (or clear, with `undefined`) the boot-wired relink-LLM factory. */
+export function setRelinkLlmFactory(fn) {
+    relinkLlmFactory = fn;
+}
+/** Resolve the relink LLM for an agent via the boot-wired factory (if any). */
+export function resolveRelinkLlm(agentId) {
+    try {
+        return relinkLlmFactory?.(agentId);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Render a window of facts as the numbered block the relink prompt consumes — each
+ * line `[<id>] <content>`. Same `[id] content` shape as the per-turn candidate block,
+ * so the model references facts by real memoryId.
+ */
+function renderRelinkBlock(records) {
+    return records.map((r) => `[${r.memoryId}] ${r.content.slice(0, 200)}`).join("\n");
+}
+/**
+ * One-shot LLM pass that identifies ALL genuine TYPED relationships among an origin's
+ * ACTIVE facts and writes the edges. The operator's "populate real edges on my CURRENT
+ * facts now" action.
+ *
+ * COST-BOUNDED: considers at most {@link RELINK_MAX_FACTS} active facts (most-recent
+ * first), processed in {@link RELINK_WINDOW}-sized windows — one PRIMARY LLM call per
+ * window (plus an optional GLEANING follow-up unless `glean:false`), so cost is linear
+ * and capped. IDEMPOTENT: every edge goes through {@link FactStore.linkRelated}, which
+ * dedupes against existing edges, so re-running adds nothing already present (and the
+ * model's own dupes collapse in {@link resolveRelationshipPairs}).
+ *
+ * ORIGIN-SCOPED: operates on a single `origin` (the tool passes the owner origin);
+ * the considered set is origin-filtered and `linkRelated` is same-origin by contract,
+ * so no edge can ever relate owner↔channel.
+ *
+ * Best-effort per window: a window whose LLM call throws or returns garbage simply
+ * contributes no edges (logged by the caller if desired) — the rest still run. The
+ * gleaning follow-up is best-effort too (a throw there leaves the primary edges intact).
+ */
+export async function runRelinkPass(args) {
+    const windowSize = args.windowSize && args.windowSize > 0 ? args.windowSize : RELINK_WINDOW;
+    const maxFacts = args.maxFacts && args.maxFacts > 0 ? args.maxFacts : RELINK_MAX_FACTS;
+    const glean = args.glean !== false;
+    // Active, origin-scoped facts, most-recent first (FactStore.list already sorts
+    // newest-first), capped. The cap keeps one operator click bounded on a huge vault.
+    const active = args.store.list({ origin: args.origin }).slice(0, maxFacts);
+    if (active.length < 2)
+        return { edgesWritten: 0, considered: active.length, windows: 0 };
+    let edgesWritten = 0;
+    let windows = 0;
+    for (let i = 0; i < active.length; i += windowSize) {
+        const window = active.slice(i, i + windowSize);
+        if (window.length < 2)
+            break; // a lone trailing fact has nothing to pair
+        const windowIds = new Set(window.map((r) => r.memoryId));
+        windows += 1;
+        const block = renderRelinkBlock(window);
+        // PRIMARY pass.
+        let reply = "";
+        try {
+            reply = await args.llm(block);
+        }
+        catch {
+            continue; // best-effort: a wedged window contributes no edges
+        }
+        // No new facts in the relink pass → newFactIds is empty; every ref must resolve
+        // to an id printed in THIS window (no fabrication, no cross-window leak).
+        const pairs = resolveRelationshipPairs(parseRelationshipRefs(reply), [], windowIds);
+        if (pairs.length > 0) {
+            edgesWritten += args.store.linkRelated(pairs.map(pairToLinkArg), args.maxPerRecord !== undefined ? { maxPerRecord: args.maxPerRecord } : {});
+        }
+        // GLEANING follow-up (one extra turn, capped at one) — recall booster. We pass the
+        // block + the prior reply + the gleaning instruction so the model adds only MISSED
+        // edges in the same format. Best-effort + idempotent (linkRelated dedupes), so it
+        // can only ADD directly-supported edges, never undo or duplicate the primary ones.
+        if (glean) {
+            let gleanReply = "";
+            try {
+                gleanReply = await args.llm(`${block}\n\nYou previously replied:\n${reply}\n\n${GLEANING_PROMPT}`);
+            }
+            catch {
+                gleanReply = ""; // a wedged gleaning turn leaves the primary edges intact
+            }
+            const gleanPairs = resolveRelationshipPairs(parseRelationshipRefs(gleanReply), [], windowIds);
+            if (gleanPairs.length > 0) {
+                edgesWritten += args.store.linkRelated(gleanPairs.map(pairToLinkArg), args.maxPerRecord !== undefined ? { maxPerRecord: args.maxPerRecord } : {});
+            }
+        }
+    }
+    return { edgesWritten, considered: active.length, windows };
+}
+//# sourceMappingURL=relationship-extract.js.map

package/dist/agents/memory/relationship-extract.js.map

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

package/dist/agents/memory/rerank.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Rerank seam + contextual-retrieval helper (Tideline v2, step 16).
+ *
+ * The cheap hybrid recall (BM25 primary ⊕ one HRR vector recovery lane × trust × decay) returns a good
+ * top-k fast. RERANKING is an OPT-IN, OFF-THE-HOT-PATH refinement: a stronger
+ * model (a BGE cross-encoder, or an LLM-judge) reorders that small top-k by deep
+ * query↔fact relevance for precision-at-fixed-recall. Default = identity (no
+ * model, no change) — so recall stays model-free unless a reranker is wired.
+ *
+ * Contextual retrieval: embed a fact WITH light context (its segment)
+ * so the vector captures more than the bare text. Opt-in helper here; embed-on-
+ * write can adopt it without changing the recall API.
+ */
+import type { MemoryRecord } from "./records.js";
+export type RerankHit = MemoryRecord & {
+    score: number;
+};
+/** Reorders recall hits by deeper relevance. Sync or async (a model may await). */
+export type Reranker = (query: string, candidates: readonly RerankHit[]) => RerankHit[] | Promise<RerankHit[]>;
+/** The default — NO reranking (model-free; recall order is unchanged). */
+export declare const identityReranker: Reranker;
+/** Plug a model-backed reranker (cross-encoder / LLM-judge) into the seam. */
+export declare function setReranker(r: Reranker): void;
+/**
+ * Apply the active (or a given) reranker to recall results. OFF the hot path —
+ * call only when precision-at-fixed-recall matters (the model cost is per-query
+ * over a SMALL top-k, not per-fact). Best-effort: a reranker error falls back to
+ * the original order.
+ */
+export declare function rerank(query: string, candidates: readonly RerankHit[], reranker?: Reranker): Promise<RerankHit[]>;
+/**
+ * Contextual-retrieval embed text — prepend light context (the segment) to the
+ * content so the embedding carries more signal than the bare fact. Opt-in:
+ * `embed-on-write` can switch to this without touching the recall API.
+ */
+export declare function contextualEmbedText(record: Pick<MemoryRecord, "segment" | "content">): string;
+//# sourceMappingURL=rerank.d.ts.map

package/dist/agents/memory/rerank.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rerank.d.ts","sourceRoot":"","sources":["../../../src/agents/memory/rerank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEzD,mFAAmF;AACnF,MAAM,MAAM,QAAQ,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,SAAS,SAAS,EAAE,KAAK,SAAS,EAAE,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC;AAE/G,0EAA0E;AAC1E,eAAO,MAAM,gBAAgB,EAAE,QAAkD,CAAC;AAGlF,8EAA8E;AAC9E,wBAAgB,WAAW,CAAC,CAAC,EAAE,QAAQ,GAAG,IAAI,CAE7C;AAED;;;;;GAKG;AACH,wBAAsB,MAAM,CAC3B,KAAK,EAAE,MAAM,EACb,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,QAAQ,GAAE,QAAoB,GAC5B,OAAO,CAAC,SAAS,EAAE,CAAC,CAMtB;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,SAAS,GAAG,SAAS,CAAC,GAAG,MAAM,CAE7F"}

package/dist/agents/memory/rerank.js

@@ -0,0 +1,43 @@
+/**
+ * Rerank seam + contextual-retrieval helper (Tideline v2, step 16).
+ *
+ * The cheap hybrid recall (BM25 primary ⊕ one HRR vector recovery lane × trust × decay) returns a good
+ * top-k fast. RERANKING is an OPT-IN, OFF-THE-HOT-PATH refinement: a stronger
+ * model (a BGE cross-encoder, or an LLM-judge) reorders that small top-k by deep
+ * query↔fact relevance for precision-at-fixed-recall. Default = identity (no
+ * model, no change) — so recall stays model-free unless a reranker is wired.
+ *
+ * Contextual retrieval: embed a fact WITH light context (its segment)
+ * so the vector captures more than the bare text. Opt-in helper here; embed-on-
+ * write can adopt it without changing the recall API.
+ */
+/** The default — NO reranking (model-free; recall order is unchanged). */
+export const identityReranker = (_query, candidates) => [...candidates];
+let _reranker = identityReranker;
+/** Plug a model-backed reranker (cross-encoder / LLM-judge) into the seam. */
+export function setReranker(r) {
+    _reranker = r;
+}
+/**
+ * Apply the active (or a given) reranker to recall results. OFF the hot path —
+ * call only when precision-at-fixed-recall matters (the model cost is per-query
+ * over a SMALL top-k, not per-fact). Best-effort: a reranker error falls back to
+ * the original order.
+ */
+export async function rerank(query, candidates, reranker = _reranker) {
+    try {
+        return await reranker(query, candidates);
+    }
+    catch {
+        return [...candidates];
+    }
+}
+/**
+ * Contextual-retrieval embed text — prepend light context (the segment) to the
+ * content so the embedding carries more signal than the bare fact. Opt-in:
+ * `embed-on-write` can switch to this without touching the recall API.
+ */
+export function contextualEmbedText(record) {
+    return `[${record.segment}] ${record.content}`;
+}
+//# sourceMappingURL=rerank.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rerank.js","sourceRoot":"","sources":["../../../src/agents/memory/rerank.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AASH,0EAA0E;AAC1E,MAAM,CAAC,MAAM,gBAAgB,GAAa,CAAC,MAAM,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC;AAElF,IAAI,SAAS,GAAa,gBAAgB,CAAC;AAC3C,8EAA8E;AAC9E,MAAM,UAAU,WAAW,CAAC,CAAW;IACtC,SAAS,GAAG,CAAC,CAAC;AACf,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAC3B,KAAa,EACb,UAAgC,EAChC,WAAqB,SAAS;IAE9B,IAAI,CAAC;QACJ,OAAO,MAAM,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC;IAC1C,CAAC;IAAC,MAAM,CAAC;QACR,OAAO,CAAC,GAAG,UAAU,CAAC,CAAC;IACxB,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAiD;IACpF,OAAO,IAAI,MAAM,CAAC,OAAO,KAAK,MAAM,CAAC,OAAO,EAAE,CAAC;AAChD,CAAC"}

package/dist/agents/memory/scoring.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Tideline v1 recall scoring (build Step 8) — the SHARED lexical scorer.
+ *
+ * ONE pure scorer, run identically in BOTH modes — over the fs `FactStore`'s
+ * records OR the convex hydrated cache — so recall ranking is **cross-mode
+ * parity by construction** (the 0.2 lock). We use an IN-APP BM25 rather than
+ * `node:sqlite` FTS5 deliberately: the SAME code must rank in both modes, and
+ * sqlite-fs + in-app-convex would be two different rankers, breaking
+ * by-construction parity. `node:sqlite` FTS5 stays a deferred fs-side SCALE
+ * optimization — at single-user scale a full in-app pass is microseconds.
+ *
+ * `bm25Score` = Okapi BM25 (k1, b) over tokenized content, MODULATED by a
+ * damped `effectiveScore` (`0.5 + 0.5 * effectiveScore`) so recency/importance
+ * shape the ranking without overriding a >2× relevance gap. `linearScanScore`
+ * is the OLD crude term-overlap, kept as the
+ * explicit linear-floor BASELINE. Both take records the CALLER has already
+ * filtered to active + origin-matching — origin isolation is enforced upstream
+ * (records.ts / capabilities.ts), never bypassed here.
+ */
+import type { MemoryRecord } from "./records.js";
+/**
+ * Lowercase Unicode word tokens (shared by docs + queries), minus stopwords.
+ * Splits on any run of non-word characters via the Unicode letter/number
+ * classes (`\p{L}\p{N}`) rather than an ASCII-only `[a-z0-9]` class, so
+ * non-Latin scripts (CJK, Cyrillic, Greek, Arabic, Hebrew, …) tokenize instead
+ * of being silently discarded — an ASCII-only delimiter class made non-Latin
+ * facts unrecallable (empty token list → no BM25 match). The stopword set stays
+ * intentionally ASCII-only (non-Latin tokens simply aren't members). Note: a
+ * space-less script (e.g. CJK) yields one whole-run token, so it matches by
+ * exact phrase rather than per-word — partial-substring matching would need a
+ * dedicated n-gram path.
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Why a record scored what it did (recall transparency, build Step 11).
+ * Populated only on demand (`bm25Score(..., { breakdown: true })` /
+ * `FactStore.explainRecall`) so the hot recall path stays allocation-free and
+ * cross-mode score parity is unaffected. Reconciles exactly:
+ * `score === bm25 * modulator`; on the DEFAULT modulate path
+ * `modulator === 0.5 + 0.5 * effective` (with `modulate: false` the modulator
+ * is `1`, so `score === bm25`).
+ */
+export interface ScoreBreakdown {
+    /** Raw Okapi BM25 relevance, before the decay/importance modulator. */
+    bm25: number;
+    /** Query terms (post-stopword) that actually matched this record. */
+    matchedTerms: string[];
+    /**
+     * `effectiveScore(record)` = decay × importance × recall-reinforcement,
+     * clamped to [0, 1]. The reinforcement factor lifts repeatedly-accessed
+     * facts (so recall reinforces what gets recalled).
+     */
+    effective: number;
+    /**
+     * The modulator applied to {@link bm25}. With `modulate: false` it is `1`
+     * (so `score === bm25`); on the DEFAULT path it is the damped
+     * `0.5 + 0.5 * effective`, in [0.5, 1].
+     */
+    modulator: number;
+    /** Final score (=== {@link ScoredRecord.score}). */
+    score: number;
+}
+export interface ScoredRecord {
+    record: MemoryRecord;
+    score: number;
+    /** Present only when scored with `{ breakdown: true }` — explains the rank. */
+    breakdown?: ScoreBreakdown;
+}
+/**
+ * OLD term-overlap (distinct matched query terms / query length) — the
+ * explicit linear-scan FLOOR. Records must be pre-filtered (active + origin).
+ * Ties broken by importance then recency, matching the pre-BM25 ordering.
+ */
+export declare function linearScanScore(records: readonly MemoryRecord[], query: string): ScoredRecord[];
+/**
+ * Okapi BM25 over the records' content, MODULATED by a damped `effectiveScore`
+ * (decay + importance) — relevance dominates, recency/importance shapes ties.
+ * Records must be pre-filtered (active + origin). IDF is computed over the
+ * given set; records matching no query term are dropped. Ranked descending.
+ */
+export declare function bm25Score(records: readonly MemoryRecord[], query: string, now?: number, opts?: {
+    breakdown?: boolean;
+    modulate?: boolean;
+}): ScoredRecord[];
+//# sourceMappingURL=scoring.d.ts.map