@spinabot/brigade 0.1.2 → 1.0.1

package/dist/agents/memory/hybrid.js

@@ -0,0 +1,184 @@
+/**
+ * Multi-signal recall fusion (Tideline v2) — the best MODEL-FREE recall we can
+ * do. Learned embeddings are NOT mandatory here: the (zero-dep, air-gap) HRR
+ * vector is just ONE signal, not the star. Robust recall comes from COMBINING a
+ * lexical workhorse with a fuzzy recovery lane:
+ *
+ *   WORKHORSE: BM25 × trust × decay (the v1 scorer) — exact lexical relevance,
+ *   down-weighted by provenance/confidence, faded by Ebbinghaus decay. Its hits
+ *   keep BM25's order, so fusion does NO HARM where lexical is already right.
+ *   RECOVERY: ONE vector-cosine lane over the {@link Embedder} seam, used ONLY to
+ *   surface facts BM25 MISSED entirely (appended BELOW every lexical hit, never
+ *   reordering them). With the bundled zero-dep HRR embedder (a bag-of-words
+ *   model) this lane is deliberately conservative — the `minSim` floor rejects
+ *   function-word noise, so model-free it rarely adds over BM25. Drop a LEARNED
+ *   embedder into the seam and the SAME lane does true synonymy recovery; that's
+ *   where it earns its keep. (A token-set Jaccard lane was removed: any shared
+ *   token already forces a BM25 hit, so it could never surface a miss — dead code.)
+ *   MODULATION (relevance × trust × decay): × trust(provenance × confidence) ×
+ *     effectiveScore(decay + importance) — applied to BOTH lanes.
+ *   DIVERSITY: MMR rerank — opt-in (λ<1) for context-block assembly;
+ *     OFF by default (λ=1) so single-fact recall isn't diversified.
+ *
+ * Origin isolation is the caller's job (pass active + origin-filtered candidates),
+ * same contract as `bm25Score`.
+ */
+import { effectiveScore } from "./decay.js";
+import { cosine } from "./embedder.js";
+import { bm25Score } from "./scoring.js";
+// Vector-lane floor. The bundled HRR embedder scores unrelated text ≈ 0 and
+// function-word-only overlap ≈ 0.2; 0.3 keeps that noise OUT (so model-free the
+// lane fires only on real multi-token overlap). A learned embedder, whose cosine
+// tracks meaning not tokens, clears this comfortably on true paraphrases.
+const DEFAULT_MIN_SIM = 0.3;
+// MMR OFF by default (λ=1 ⇒ pure relevance). Diversity is a CONTEXT-BLOCK concern
+// (assembling a varied prompt) not a fact-FINDING one — on single-relevant-fact
+// recall, diversifying only hurts ranking. No v1 caller opts in: recall() and
+// context() both run at the λ=1 default; λ<1 is exercised only by tests.
+// (Reconciles the plan's "λ=0.7": that 0.7 IS this opt-in — a deliberate DEFAULT of
+// 1.0 for fact recall, with 0.7 available per-call for multi-fact block assembly,
+// rather than diversifying single-fact lookups by default. A tuned default, not a gap.)
+const DEFAULT_MMR_LAMBDA = 1.0;
+/**
+ * TRUST multiplier from provenance. The operator (or legacy/
+ * undefined) is fully trusted; distilled/derived facts slightly less; external
+ * ingested content (tool/retrieved/compaction — the write-gate's "untrusted"
+ * set) is materially down-weighted so it can't dominate recall.
+ */
+const TRUST_BY_SOURCE = {
+    user_instruction: 1.0,
+    owner_message: 1.0,
+    extraction: 0.9,
+    dream: 0.85,
+    compaction: 0.85,
+    channel_message: 0.8,
+    tool_output: 0.65,
+    retrieved_document: 0.6,
+};
+function trustFactor(r) {
+    const base = r.sourceType ? (TRUST_BY_SOURCE[r.sourceType] ?? 0.9) : 1.0; // undefined/legacy ⇒ trusted
+    const conf = typeof r.confidence === "number" ? Math.max(0, Math.min(1, r.confidence)) : 1;
+    return base * conf;
+}
+export function recallHybrid(candidates, query, embedder, now = Date.now(), opts = {}) {
+    const limit = opts.limit && opts.limit > 0 ? opts.limit : 8;
+    // Per-embedder recovery floor: an explicit opt wins; else the embedder's own
+    // recommended floor (a noisy model-free HRR sets a HIGH one); else the default.
+    const minSim = opts.minSim ?? embedder.minSim ?? DEFAULT_MIN_SIM;
+    const lambda = opts.mmrLambda ?? DEFAULT_MMR_LAMBDA;
+    if (candidates.length === 0)
+        return [];
+    // ── PRIMARY: BM25 (the v1 scorer — damped decay baked in, the MRR-preserving
+    // order), × trust. Its hits keep their order; the recovery lanes below NEVER
+    // demote a BM25 hit, so the mix does NO HARM where lexical is already good. ──
+    const lex = bm25Score(candidates, query, now);
+    const lexIds = new Set(lex.map((s) => s.record.memoryId));
+    // ── RECOVERY lane: vector cosine over the embedder seam, used ONLY to surface
+    // facts BM25 MISSED (a recall boost, never a reorder of BM25's hits). ──
+    const qv = embedder.embed([query])[0] ?? [];
+    const vecRank = new Map();
+    candidates
+        .map((r) => ({ id: r.memoryId, sim: r.embedding && r.embedding.length === qv.length ? cosine(qv, r.embedding) : -1 }))
+        .filter((x) => x.sim >= minSim)
+        .sort((a, b) => b.sim - a.sim)
+        .forEach((x, i) => vecRank.set(x.id, i + 1));
+    // PRIMARY results: BM25 hits in BM25 order × trust. On clean/trusted data
+    // trust=1 ⇒ exactly BM25's order (no MRR regression); on real data trust
+    // intentionally demotes untrusted facts (the security/quality lever).
+    const primary = lex.map((s, i) => {
+        const id = s.record.memoryId;
+        return {
+            record: s.record,
+            score: s.score * trustFactor(s.record),
+            lexRank: i + 1,
+            ...(vecRank.has(id) ? { vecRank: vecRank.get(id) } : {}),
+        };
+    });
+    primary.sort((a, b) => b.score - a.score || b.record.createdAt - a.record.createdAt);
+    // RECOVERY results: facts BM25 MISSED, found by the vector lane — appended
+    // BELOW every primary hit (score strictly under the lowest primary), ordered
+    // by cosine rank and damped by trust × decay (so a stale recovered fact can't
+    // outrank a fresh one; `0.5 + 0.5·effectiveScore` keeps the damp in (0,1]).
+    const byId = new Map(candidates.map((r) => [r.memoryId, r]));
+    const minPrimary = primary.length ? (primary[primary.length - 1]?.score ?? 0) : 1;
+    const recovered = [...vecRank.keys()]
+        .filter((id) => !lexIds.has(id))
+        .map((id) => ({ id, rank: vecRank.get(id) ?? Number.POSITIVE_INFINITY }))
+        .sort((a, b) => a.rank - b.rank)
+        .map((x, i) => {
+        const record = byId.get(x.id);
+        if (!record)
+            return null;
+        const decayDamp = 0.5 + 0.5 * effectiveScore(record, now);
+        return {
+            record,
+            score: minPrimary * 0.5 * 0.9 ** i * trustFactor(record) * decayDamp,
+            vecRank: x.rank,
+        };
+    })
+        .filter((x) => x !== null);
+    // MMR diversity is OPT-IN (λ<1, for context-block assembly); default λ=1 = noop.
+    return mmrRerank([...primary, ...recovered], lambda, limit);
+}
+/**
+ * Maximal Marginal Relevance: greedily pick the highest-scored, then each next
+ * pick maximises `λ·relevance − (1−λ)·maxSimToSelected`, so near-duplicate facts
+ * don't crowd the top-k. Relevance is normalised to [0,1] so it's comparable to
+ * the cosine diversity term; similarity uses the HRR embeddings (0 when absent).
+ */
+function mmrRerank(scored, lambda, limit) {
+    if (scored.length <= 1)
+        return scored.slice(0, limit);
+    // Normalise by the GREATEST score (not scored[0]) so rel∈[0,1] regardless of
+    // input ordering; guard to 1 when all scores are ≤0 (pool is non-empty here).
+    const peak = Math.max(...scored.map((s) => s.score));
+    const maxScore = peak > 0 ? peak : 1;
+    const pool = scored.map((s) => ({ ...s, rel: s.score / maxScore }));
+    const selected = [];
+    while (selected.length < limit && pool.length > 0) {
+        let bestIdx = 0;
+        let bestVal = -Infinity;
+        for (let i = 0; i < pool.length; i++) {
+            const cand = pool[i];
+            if (!cand)
+                continue;
+            // The diversity term is weighted by (1−λ), so when λ≥1 (the default) it
+            // drops out entirely — skip the O(k²·d) pairwise cosine and use 0.
+            let maxSim = 0;
+            if (lambda < 1) {
+                for (const s of selected) {
+                    const sim = cand.record.embedding && s.record.embedding && cand.record.embedding.length === s.record.embedding.length
+                        ? cosine(cand.record.embedding, s.record.embedding)
+                        : 0;
+                    if (sim > maxSim)
+                        maxSim = sim;
+                }
+            }
+            const mmr = lambda * cand.rel - (1 - lambda) * maxSim;
+            if (mmr > bestVal) {
+                bestVal = mmr;
+                bestIdx = i;
+            }
+        }
+        const [picked] = pool.splice(bestIdx, 1);
+        if (picked)
+            selected.push(picked);
+    }
+    return selected.map(({ rel: _rel, ...s }) => s);
+}
+/** Async variant for a model-backed embedder: pre-embed the query once. */
+export async function recallHybridAsync(candidates, query, embedder, now = Date.now(), opts = {}) {
+    const qv = (await embedder.embed([query]))[0] ?? [];
+    // Preserve the embedder's recommended recovery-lane floor when rebuilding the
+    // pre-embedded stand-in: recallHybrid reads `embedder.minSim` off this wrapper,
+    // so omitting it would silently drop the per-embedder `minSim` contract (a
+    // no-op for every current embedder, which omit it; matters for a learned one).
+    const preEmbedded = {
+        id: embedder.id,
+        dims: embedder.dims,
+        ...(embedder.minSim !== undefined ? { minSim: embedder.minSim } : {}),
+        embed: () => [qv],
+    };
+    return recallHybrid(candidates, query, preEmbedded, now, opts);
+}
+//# sourceMappingURL=hybrid.js.map

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

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

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

@@ -0,0 +1,13 @@
+/**
+ * Brigade memory — public re-exports.
+ *
+ * Re-exports the core memory surface for external consumers (e.g. the
+ * Tideline public package and downstream packages). Internal Brigade call
+ * sites (tools, agent-loop, gateway) import directly from the per-file
+ * modules to keep circular imports easy to spot and avoid barrel indirection.
+ */
+export { FactStore, FACTS_RELATIVE_PATH, MEMORY_SEGMENTS, SEGMENT_DEFAULTS, clampImportance, makeMemoryId, type ListFilter, type MemoryLifecycle, type MemoryRecord, type MemorySegment, type MemoryTier, type NewFact, } from "./records.js";
+export { BrigadeMemoryPathError, FileMemoryStore, scoreChunk, splitIntoChunks, tokenize, type BrigadeStorage, type MemoryReadOptions, type MemoryReadResult, type MemorySearchOptions, type MemorySearchResult, type MemoryStatus, } from "./storage.js";
+export { buildAutoRecallBlock } from "./auto-recall.js";
+export { createDefaultMemoryCapability, isDefaultMemoryCapability, resolveActiveMemoryCapability, type DefaultMemoryCapability, type DefaultMemoryHit, } from "./plugin-runtime.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACN,SAAS,EACT,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,KAAK,UAAU,EACf,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,OAAO,GACZ,MAAM,cAAc,CAAC;AAEtB,OAAO,EACN,sBAAsB,EACtB,eAAe,EACf,UAAU,EACV,eAAe,EACf,QAAQ,EACR,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,mBAAmB,EACxB,KAAK,kBAAkB,EACvB,KAAK,YAAY,GACjB,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,EACN,6BAA6B,EAC7B,yBAAyB,EACzB,6BAA6B,EAC7B,KAAK,uBAAuB,EAC5B,KAAK,gBAAgB,GACrB,MAAM,qBAAqB,CAAC"}

package/dist/agents/memory/index.js

@@ -0,0 +1,13 @@
+/**
+ * Brigade memory — public re-exports.
+ *
+ * Re-exports the core memory surface for external consumers (e.g. the
+ * Tideline public package and downstream packages). Internal Brigade call
+ * sites (tools, agent-loop, gateway) import directly from the per-file
+ * modules to keep circular imports easy to spot and avoid barrel indirection.
+ */
+export { FactStore, FACTS_RELATIVE_PATH, MEMORY_SEGMENTS, SEGMENT_DEFAULTS, clampImportance, makeMemoryId, } from "./records.js";
+export { BrigadeMemoryPathError, FileMemoryStore, scoreChunk, splitIntoChunks, tokenize, } from "./storage.js";
+export { buildAutoRecallBlock } from "./auto-recall.js";
+export { createDefaultMemoryCapability, isDefaultMemoryCapability, resolveActiveMemoryCapability, } from "./plugin-runtime.js";
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agents/memory/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACN,SAAS,EACT,mBAAmB,EACnB,eAAe,EACf,gBAAgB,EAChB,eAAe,EACf,YAAY,GAOZ,MAAM,cAAc,CAAC;AAEtB,OAAO,EACN,sBAAsB,EACtB,eAAe,EACf,UAAU,EACV,eAAe,EACf,QAAQ,GAOR,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,EACN,6BAA6B,EAC7B,yBAAyB,EACzB,6BAA6B,GAG7B,MAAM,qBAAqB,CAAC"}

package/dist/agents/memory/json-scan.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Tiny shared helper for pulling JSON objects out of an LLM reply — extracted to its
+ * OWN module so both `extract.ts` and `relationship-extract.ts` can use it WITHOUT
+ * importing each other (which would form a load-time cycle: extract.ts builds
+ * EXTRACTION_PROMPT from relationship-extract.ts's prompt fragment at module top level,
+ * so relationship-extract.ts must not depend on extract.ts being initialized first).
+ */
+/** ALL top-level BALANCED `{...}` objects in `text`, in order (string-aware: braces
+ *  inside JSON strings don't count). Replaces a greedy first-to-LAST `{...}` match that
+ *  grabbed any trailing brace block AND a single-object scan that let a LEADING stray
+ *  object (`{}`, a reasoning artifact) shadow the real `{"facts":[…]}` after it — both
+ *  failure modes returned [] and advanced the cursor past un-distilled facts. */
+export declare function balancedObjects(text: string): string[];
+//# sourceMappingURL=json-scan.d.ts.map

package/dist/agents/memory/json-scan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-scan.d.ts","sourceRoot":"","sources":["../../../src/agents/memory/json-scan.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;iFAIiF;AACjF,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CA2BtD"}

package/dist/agents/memory/json-scan.js

@@ -0,0 +1,47 @@
+/**
+ * Tiny shared helper for pulling JSON objects out of an LLM reply — extracted to its
+ * OWN module so both `extract.ts` and `relationship-extract.ts` can use it WITHOUT
+ * importing each other (which would form a load-time cycle: extract.ts builds
+ * EXTRACTION_PROMPT from relationship-extract.ts's prompt fragment at module top level,
+ * so relationship-extract.ts must not depend on extract.ts being initialized first).
+ */
+/** ALL top-level BALANCED `{...}` objects in `text`, in order (string-aware: braces
+ *  inside JSON strings don't count). Replaces a greedy first-to-LAST `{...}` match that
+ *  grabbed any trailing brace block AND a single-object scan that let a LEADING stray
+ *  object (`{}`, a reasoning artifact) shadow the real `{"facts":[…]}` after it — both
+ *  failure modes returned [] and advanced the cursor past un-distilled facts. */
+export function balancedObjects(text) {
+    const out = [];
+    let depth = 0;
+    let inStr = false;
+    let esc = false;
+    let start = -1;
+    for (let i = 0; i < text.length; i++) {
+        const c = text[i];
+        if (inStr) {
+            if (esc)
+                esc = false;
+            else if (c === "\\")
+                esc = true;
+            else if (c === '"')
+                inStr = false;
+            continue;
+        }
+        if (c === '"')
+            inStr = true;
+        else if (c === "{") {
+            if (depth === 0)
+                start = i;
+            depth++;
+        }
+        else if (c === "}" && depth > 0) {
+            depth--;
+            if (depth === 0 && start >= 0) {
+                out.push(text.slice(start, i + 1));
+                start = -1;
+            }
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=json-scan.js.map

package/dist/agents/memory/json-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"json-scan.js","sourceRoot":"","sources":["../../../src/agents/memory/json-scan.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH;;;;iFAIiF;AACjF,MAAM,UAAU,eAAe,CAAC,IAAY;IAC3C,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,IAAI,KAAK,GAAG,KAAK,CAAC;IAClB,IAAI,GAAG,GAAG,KAAK,CAAC;IAChB,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC;IACf,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,IAAI,KAAK,EAAE,CAAC;YACX,IAAI,GAAG;gBAAE,GAAG,GAAG,KAAK,CAAC;iBAChB,IAAI,CAAC,KAAK,IAAI;gBAAE,GAAG,GAAG,IAAI,CAAC;iBAC3B,IAAI,CAAC,KAAK,GAAG;gBAAE,KAAK,GAAG,KAAK,CAAC;YAClC,SAAS;QACV,CAAC;QACD,IAAI,CAAC,KAAK,GAAG;YAAE,KAAK,GAAG,IAAI,CAAC;aACvB,IAAI,CAAC,KAAK,GAAG,EAAE,CAAC;YACpB,IAAI,KAAK,KAAK,CAAC;gBAAE,KAAK,GAAG,CAAC,CAAC;YAC3B,KAAK,EAAE,CAAC;QACT,CAAC;aAAM,IAAI,CAAC,KAAK,GAAG,IAAI,KAAK,GAAG,CAAC,EAAE,CAAC;YACnC,KAAK,EAAE,CAAC;YACR,IAAI,KAAK,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;gBAC/B,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;gBACnC,KAAK,GAAG,CAAC,CAAC,CAAC;YACZ,CAAC;QACF,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

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

@@ -0,0 +1,92 @@
+/**
+ * The links substrate — typed edges between memories (Tideline build Step 7,
+ * the graph half of the dual-track spine).
+ *
+ * A fact can point at other facts: a correction supersedes a prior belief, an
+ * extracted fact is `derived_from` its source, two facts may `contradict`. v1
+ * STORES and DERIVES these edges (the substrate); multi-hop graph TRAVERSAL
+ * (following links during recall to pull in related context) is deliberately
+ * v2 — the field + the read primitives land now so the data accrues and the
+ * v2 traversal has something to walk.
+ *
+ * Storage note: `supersedes[]` stays the supersede MECHANISM (it drives
+ * archiving in `FactStore.write`); we do NOT duplicate it into `links[]` at
+ * write time. Instead {@link linksFrom} mirrors it into a `supersedes` edge at
+ * READ time so a graph view is complete without a migration or double-write.
+ */
+import type { MemoryRecord } from "./records.js";
+/**
+ * Typed edge kinds. `supersedes` is derived from the record's `supersedes[]`;
+ * the rest are explicit (written into `links[]`). Surfaced, not auto-resolved —
+ * a `contradicts` edge flags a conflict for consolidation, it doesn't pick a
+ * winner.
+ *
+ * The vocabulary is split into THREE bands (the research-backed
+ * relationship-extraction design — TYPED + JUSTIFIED + STRENGTH-SCORED edges with
+ * a strict "direct basis" gate):
+ *   • MECHANISM/lifecycle edges (`supersedes`/`transition`/`corrects`/`contradicts`)
+ *     are minted by the store itself (supersede chains, slot replacement) — NOT by
+ *     the relationship extractor.
+ *   • STRONG FACTUAL edges (`causes`…`relates_to`) are the closed set the LLM
+ *     extractor may emit, each requiring a direct stated basis + a reason + strength.
+ *   • THEMATIC `same_topic` is the QUARANTINED over-linking lane: same-domain pairs
+ *     (dark-mode ~ Obsidian) are allowed but capped, low-strength, and rendered in a
+ *     SEPARATE "## Same area" section so they never masquerade as strong relations.
+ */
+export type MemoryLinkKind = "supersedes" | "transition" | "corrects" | "derived_from" | "supports" | "causes" | "caused_by" | "part_of" | "precedes" | "follows" | "enables" | "blocks" | "co_constrains" | "located_at" | "uses" | "works_on" | "contrasts_with" | "contradicts" | "relates_to" | "same_topic" | "relates";
+/** Runtime list of every {@link MemoryLinkKind} — the strict-validation basis for
+ *  the relationship extractor (an out-of-taxonomy `type` from the model is dropped)
+ *  and for keeping the convex `LinkKind` validators (schema.ts + memory.ts) in sync.
+ *  A typo/extra value is a COMPILE error via the `satisfies` clause below. */
+export declare const MEMORY_LINK_KINDS: readonly ["supersedes", "transition", "corrects", "derived_from", "supports", "causes", "caused_by", "part_of", "precedes", "follows", "enables", "blocks", "co_constrains", "located_at", "uses", "works_on", "contrasts_with", "contradicts", "relates_to", "same_topic", "relates"];
+/** True if `k` is a known link kind (strict-validation gate for model output). */
+export declare function isMemoryLinkKind(k: string): k is MemoryLinkKind;
+/**
+ * The closed set of STRONG FACTUAL edge kinds the LLM relationship extractor is
+ * allowed to emit. Excludes the store-minted lifecycle edges (supersedes/
+ * transition/corrects/derived_from/supports — the store owns those), the thematic
+ * `same_topic` lane (its own quarantined handling), and the legacy `relates` (a
+ * derivation-pass kind for synonymy/bridges, never extractor output). `relates_to`
+ * is IN the set but discouraged (the prompt asks for an especially strong reason).
+ */
+export declare const EXTRACTOR_FACTUAL_KINDS: readonly ["causes", "caused_by", "part_of", "precedes", "follows", "enables", "blocks", "co_constrains", "located_at", "uses", "works_on", "contrasts_with", "relates_to"];
+/** True if `k` is a strong FACTUAL kind the extractor may emit (excludes
+ *  `same_topic`, store-minted lifecycle kinds, and legacy `relates`). */
+export declare function isExtractorFactualKind(k: string): k is MemoryLinkKind;
+/** Directed inverse of an edge kind, for the REVERSE endpoint of a bidirectional
+ *  write (causes↔caused_by, precedes↔follows). A SYMMETRIC kind is its own inverse
+ *  (co_constrains, contrasts_with, contradicts, same_topic, relates, relates_to, uses,
+ *  works_on, located_at) so it mirrors unchanged. `enables`/`blocks` have no clean
+ *  English inverse — the reverse endpoint records the same kind (the pair is still a
+ *  genuine, explainable edge from either side). Store-minted lifecycle kinds aren't
+ *  passed through here (linkRelated is the typed-association writer). */
+export declare function inverseLinkKind(kind: MemoryLinkKind): MemoryLinkKind;
+export interface MemoryLink {
+    kind: MemoryLinkKind;
+    /** `memoryId` of the linked fact. */
+    target: string;
+    /** WHY this edge exists — the model's one-line justification (chain-of-thought →
+     *  higher precision). Optional + additive: persisted for explainable rendering
+     *  (`- <kind>: [[target]] — <reason>`); store-minted edges (supersede/transition)
+     *  carry none. */
+    reason?: string;
+    /** Edge strength 1..5 (the post-filter axis). Factual edges below the strength
+     *  threshold are dropped at extraction time; `same_topic` is admitted only at low
+     *  strength + capped. Optional + additive; store-minted edges carry none. */
+    strength?: number;
+}
+/**
+ * All outbound edges of a record — explicit `links[]` UNION the `supersedes[]`
+ * mirrored as `supersedes` edges, deduped. This is the canonical "edges of this
+ * node" view; storage keeps the two arrays separate (see module note).
+ */
+export declare function linksFrom(record: Pick<MemoryRecord, "links" | "supersedes">): MemoryLink[];
+/**
+ * Inbound edges to `targetId` across the corpus — the BACKLINKS. The substrate's
+ * read primitive; v2 multi-hop recall walks these to pull related context.
+ */
+export declare function backlinksTo(records: readonly MemoryRecord[], targetId: string): Array<{
+    from: string;
+    kind: MemoryLinkKind;
+}>;
+//# sourceMappingURL=links.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"links.d.ts","sourceRoot":"","sources":["../../../src/agents/memory/links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,MAAM,cAAc,GAEvB,YAAY,GACZ,YAAY,GACZ,UAAU,GACV,cAAc,GACd,UAAU,GAEV,QAAQ,GACR,WAAW,GACX,SAAS,GACT,UAAU,GACV,SAAS,GACT,SAAS,GACT,QAAQ,GACR,eAAe,GACf,YAAY,GACZ,MAAM,GACN,UAAU,GACV,gBAAgB,GAChB,aAAa,GACb,YAAY,GAEZ,YAAY,GAEZ,SAAS,CAAC;AAEb;;;8EAG8E;AAC9E,eAAO,MAAM,iBAAiB,wRAsBgB,CAAC;AAI/C,kFAAkF;AAClF,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,cAAc,CAE/D;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB,4KAcU,CAAC;AAI/C;yEACyE;AACzE,wBAAgB,sBAAsB,CAAC,CAAC,EAAE,MAAM,GAAG,CAAC,IAAI,cAAc,CAErE;AAED;;;;;;yEAMyE;AACzE,wBAAgB,eAAe,CAAC,IAAI,EAAE,cAAc,GAAG,cAAc,CAepE;AAED,MAAM,WAAW,UAAU;IAC1B,IAAI,EAAE,cAAc,CAAC;IACrB,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf;;;sBAGkB;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;iFAE6E;IAC7E,QAAQ,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,OAAO,GAAG,YAAY,CAAC,GAAG,UAAU,EAAE,CAkB1F;AAED;;;GAGG;AACH,wBAAgB,WAAW,CAC1B,OAAO,EAAE,SAAS,YAAY,EAAE,EAChC,QAAQ,EAAE,MAAM,GACd,KAAK,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,cAAc,CAAA;CAAE,CAAC,CAQ/C"}

package/dist/agents/memory/links.js

@@ -0,0 +1,140 @@
+/**
+ * The links substrate — typed edges between memories (Tideline build Step 7,
+ * the graph half of the dual-track spine).
+ *
+ * A fact can point at other facts: a correction supersedes a prior belief, an
+ * extracted fact is `derived_from` its source, two facts may `contradict`. v1
+ * STORES and DERIVES these edges (the substrate); multi-hop graph TRAVERSAL
+ * (following links during recall to pull in related context) is deliberately
+ * v2 — the field + the read primitives land now so the data accrues and the
+ * v2 traversal has something to walk.
+ *
+ * Storage note: `supersedes[]` stays the supersede MECHANISM (it drives
+ * archiving in `FactStore.write`); we do NOT duplicate it into `links[]` at
+ * write time. Instead {@link linksFrom} mirrors it into a `supersedes` edge at
+ * READ time so a graph view is complete without a migration or double-write.
+ */
+/** Runtime list of every {@link MemoryLinkKind} — the strict-validation basis for
+ *  the relationship extractor (an out-of-taxonomy `type` from the model is dropped)
+ *  and for keeping the convex `LinkKind` validators (schema.ts + memory.ts) in sync.
+ *  A typo/extra value is a COMPILE error via the `satisfies` clause below. */
+export const MEMORY_LINK_KINDS = [
+    "supersedes",
+    "transition",
+    "corrects",
+    "derived_from",
+    "supports",
+    "causes",
+    "caused_by",
+    "part_of",
+    "precedes",
+    "follows",
+    "enables",
+    "blocks",
+    "co_constrains",
+    "located_at",
+    "uses",
+    "works_on",
+    "contrasts_with",
+    "contradicts",
+    "relates_to",
+    "same_topic",
+    "relates",
+];
+const MEMORY_LINK_KIND_SET = new Set(MEMORY_LINK_KINDS);
+/** True if `k` is a known link kind (strict-validation gate for model output). */
+export function isMemoryLinkKind(k) {
+    return MEMORY_LINK_KIND_SET.has(k);
+}
+/**
+ * The closed set of STRONG FACTUAL edge kinds the LLM relationship extractor is
+ * allowed to emit. Excludes the store-minted lifecycle edges (supersedes/
+ * transition/corrects/derived_from/supports — the store owns those), the thematic
+ * `same_topic` lane (its own quarantined handling), and the legacy `relates` (a
+ * derivation-pass kind for synonymy/bridges, never extractor output). `relates_to`
+ * is IN the set but discouraged (the prompt asks for an especially strong reason).
+ */
+export const EXTRACTOR_FACTUAL_KINDS = [
+    "causes",
+    "caused_by",
+    "part_of",
+    "precedes",
+    "follows",
+    "enables",
+    "blocks",
+    "co_constrains",
+    "located_at",
+    "uses",
+    "works_on",
+    "contrasts_with",
+    "relates_to",
+];
+const EXTRACTOR_FACTUAL_KIND_SET = new Set(EXTRACTOR_FACTUAL_KINDS);
+/** True if `k` is a strong FACTUAL kind the extractor may emit (excludes
+ *  `same_topic`, store-minted lifecycle kinds, and legacy `relates`). */
+export function isExtractorFactualKind(k) {
+    return EXTRACTOR_FACTUAL_KIND_SET.has(k);
+}
+/** Directed inverse of an edge kind, for the REVERSE endpoint of a bidirectional
+ *  write (causes↔caused_by, precedes↔follows). A SYMMETRIC kind is its own inverse
+ *  (co_constrains, contrasts_with, contradicts, same_topic, relates, relates_to, uses,
+ *  works_on, located_at) so it mirrors unchanged. `enables`/`blocks` have no clean
+ *  English inverse — the reverse endpoint records the same kind (the pair is still a
+ *  genuine, explainable edge from either side). Store-minted lifecycle kinds aren't
+ *  passed through here (linkRelated is the typed-association writer). */
+export function inverseLinkKind(kind) {
+    switch (kind) {
+        case "causes":
+            return "caused_by";
+        case "caused_by":
+            return "causes";
+        case "precedes":
+            return "follows";
+        case "follows":
+            return "precedes";
+        case "part_of":
+            return "part_of"; // membership reads both ways for recall (component ↔ whole)
+        default:
+            return kind; // symmetric / inverse-less kinds mirror unchanged
+    }
+}
+/**
+ * All outbound edges of a record — explicit `links[]` UNION the `supersedes[]`
+ * mirrored as `supersedes` edges, deduped. This is the canonical "edges of this
+ * node" view; storage keeps the two arrays separate (see module note).
+ */
+export function linksFrom(record) {
+    const mirrored = (record.supersedes ?? []).map((target) => ({ kind: "supersedes", target }));
+    // Dedup by kind|target ONLY — reason/strength don't change EDGE IDENTITY (the
+    // graph still draws one line). When two entries collide, KEEP the one carrying a
+    // reason (the explainable render) so a later reason-less write can't blank it.
+    const byKey = new Map();
+    const order = [];
+    for (const l of [...(record.links ?? []), ...mirrored]) {
+        const key = `${l.kind}|${l.target}`;
+        const prior = byKey.get(key);
+        if (!prior) {
+            byKey.set(key, l);
+            order.push(key);
+        }
+        else if (!prior.reason && l.reason) {
+            byKey.set(key, l); // upgrade to the reason-bearing duplicate (identity unchanged)
+        }
+    }
+    return order.map((k) => byKey.get(k));
+}
+/**
+ * Inbound edges to `targetId` across the corpus — the BACKLINKS. The substrate's
+ * read primitive; v2 multi-hop recall walks these to pull related context.
+ */
+export function backlinksTo(records, targetId) {
+    const out = [];
+    for (const r of records) {
+        for (const l of linksFrom(r)) {
+            if (l.target === targetId)
+                out.push({ from: r.memoryId, kind: l.kind });
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=links.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"links.js","sourceRoot":"","sources":["../../../src/agents/memory/links.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAiDH;;;8EAG8E;AAC9E,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAChC,YAAY;IACZ,YAAY;IACZ,UAAU;IACV,cAAc;IACd,UAAU;IACV,QAAQ;IACR,WAAW;IACX,SAAS;IACT,UAAU;IACV,SAAS;IACT,SAAS;IACT,QAAQ;IACR,eAAe;IACf,YAAY;IACZ,MAAM;IACN,UAAU;IACV,gBAAgB;IAChB,aAAa;IACb,YAAY;IACZ,YAAY;IACZ,SAAS;CACoC,CAAC;AAE/C,MAAM,oBAAoB,GAAwB,IAAI,GAAG,CAAC,iBAAiB,CAAC,CAAC;AAE7E,kFAAkF;AAClF,MAAM,UAAU,gBAAgB,CAAC,CAAS;IACzC,OAAO,oBAAoB,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACtC,QAAQ;IACR,WAAW;IACX,SAAS;IACT,UAAU;IACV,SAAS;IACT,SAAS;IACT,QAAQ;IACR,eAAe;IACf,YAAY;IACZ,MAAM;IACN,UAAU;IACV,gBAAgB;IAChB,YAAY;CACiC,CAAC;AAE/C,MAAM,0BAA0B,GAAwB,IAAI,GAAG,CAAC,uBAAuB,CAAC,CAAC;AAEzF;yEACyE;AACzE,MAAM,UAAU,sBAAsB,CAAC,CAAS;IAC/C,OAAO,0BAA0B,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAC1C,CAAC;AAED;;;;;;yEAMyE;AACzE,MAAM,UAAU,eAAe,CAAC,IAAoB;IACnD,QAAQ,IAAI,EAAE,CAAC;QACd,KAAK,QAAQ;YACZ,OAAO,WAAW,CAAC;QACpB,KAAK,WAAW;YACf,OAAO,QAAQ,CAAC;QACjB,KAAK,UAAU;YACd,OAAO,SAAS,CAAC;QAClB,KAAK,SAAS;YACb,OAAO,UAAU,CAAC;QACnB,KAAK,SAAS;YACb,OAAO,SAAS,CAAC,CAAC,4DAA4D;QAC/E;YACC,OAAO,IAAI,CAAC,CAAC,kDAAkD;IACjE,CAAC;AACF,CAAC;AAiBD;;;;GAIG;AACH,MAAM,UAAU,SAAS,CAAC,MAAkD;IAC3E,MAAM,QAAQ,GAAiB,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;IAC3G,8EAA8E;IAC9E,iFAAiF;IACjF,+EAA+E;IAC/E,MAAM,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC5C,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC;QACxD,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;QACpC,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAC7B,IAAI,CAAC,KAAK,EAAE,CAAC;YACZ,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;YAClB,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACjB,CAAC;aAAM,IAAI,CAAC,KAAK,CAAC,MAAM,IAAI,CAAC,CAAC,MAAM,EAAE,CAAC;YACtC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,CAAC,+DAA+D;QACnF,CAAC;IACF,CAAC;IACD,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAE,CAAC,CAAC;AACxC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,WAAW,CAC1B,OAAgC,EAChC,QAAgB;IAEhB,MAAM,GAAG,GAAkD,EAAE,CAAC;IAC9D,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACzB,KAAK,MAAM,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC;YAC9B,IAAI,CAAC,CAAC,MAAM,KAAK,QAAQ;gBAAE,GAAG,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;QACzE,CAAC;IACF,CAAC;IACD,OAAO,GAAG,CAAC;AACZ,CAAC"}

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

@@ -0,0 +1,18 @@
+import { type ContradictionCandidate } from "./contradiction.js";
+/**
+ * The CHEAP, no-LLM memory-hygiene sweep for ONE workspace: decay-GC (age/archive/prune)
+ * + curator (per-origin confirm of repeated beliefs + near-duplicate merge + change-gated
+ * Obsidian-vault re-render). This mirrors the post-turn quiet-window block in the gateway
+ * (server.ts), extracted so a boot-seeded wall-clock driver can run it on an IDLE gateway —
+ * where no turn ever fires the post-turn path, so facts would otherwise never age or
+ * consolidate. Zero model cost; idempotent; safe to call on a cadence.
+ *
+ * The throttled LLM consolidation (`runConsolidation`, 1 model call) is intentionally NOT
+ * here — it needs auth + rides the per-turn path; this driver covers the deterministic
+ * hygiene that an idle gateway must not skip.
+ *
+ * Each stage is independently guarded so one workspace's failure can't abort the others
+ * (the caller loops over every agent workspace).
+ */
+export declare function runMemoryMaintenance(workspaceDir: string, onError?: (stage: "decay-gc" | "curator" | "contradictions", err: unknown) => void, onContradictions?: (pairs: ContradictionCandidate[]) => void): void;
+//# sourceMappingURL=maintenance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"maintenance.d.ts","sourceRoot":"","sources":["../../../src/agents/memory/maintenance.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,sBAAsB,EAAsB,MAAM,oBAAoB,CAAC;AAKrF;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CACnC,YAAY,EAAE,MAAM,EACpB,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,UAAU,GAAG,SAAS,GAAG,gBAAgB,EAAE,GAAG,EAAE,OAAO,KAAK,IAAI,EAClF,gBAAgB,CAAC,EAAE,CAAC,KAAK,EAAE,sBAAsB,EAAE,KAAK,IAAI,GAC1D,IAAI,CAqCN"}

package/dist/agents/memory/maintenance.js

@@ -0,0 +1,66 @@
+import { join } from "node:path";
+import { findContradictions } from "./contradiction.js";
+import { runCurator } from "./curator.js";
+import { runDecayGc } from "./decay.js";
+import { FactStore, originBucketKey } from "./records.js";
+/**
+ * The CHEAP, no-LLM memory-hygiene sweep for ONE workspace: decay-GC (age/archive/prune)
+ * + curator (per-origin confirm of repeated beliefs + near-duplicate merge + change-gated
+ * Obsidian-vault re-render). This mirrors the post-turn quiet-window block in the gateway
+ * (server.ts), extracted so a boot-seeded wall-clock driver can run it on an IDLE gateway —
+ * where no turn ever fires the post-turn path, so facts would otherwise never age or
+ * consolidate. Zero model cost; idempotent; safe to call on a cadence.
+ *
+ * The throttled LLM consolidation (`runConsolidation`, 1 model call) is intentionally NOT
+ * here — it needs auth + rides the per-turn path; this driver covers the deterministic
+ * hygiene that an idle gateway must not skip.
+ *
+ * Each stage is independently guarded so one workspace's failure can't abort the others
+ * (the caller loops over every agent workspace).
+ */
+export function runMemoryMaintenance(workspaceDir, onError, onContradictions) {
+    try {
+        runDecayGc(workspaceDir);
+    }
+    catch (err) {
+        onError?.("decay-gc", err);
+    }
+    try {
+        // `evictMinAgeMs: Infinity` matches the post-turn block: eviction is left to
+        // runDecayGc above (no double-GC); the curator only confirms + merges + re-renders.
+        runCurator(new FactStore(workspaceDir), {
+            dream: { evictMinAgeMs: Number.POSITIVE_INFINITY },
+            vaultDir: join(workspaceDir, "memory-vault"),
+        });
+    }
+    catch (err) {
+        onError?.("curator", err);
+    }
+    // Surface (do NOT auto-invalidate) possible contradictions — same-subject, divergent-claim
+    // pairs a human should review. Scoped PER ORIGIN: a pair across two principals isn't a real
+    // contradiction. Log-only; resolution stays a deliberate operator/dream action. Only computed
+    // when a consumer wants them (the daily driver passes a logger).
+    if (onContradictions) {
+        try {
+            const active = new FactStore(workspaceDir).list();
+            const buckets = new Map();
+            for (const r of active) {
+                const k = originBucketKey(r);
+                const arr = buckets.get(k);
+                if (arr)
+                    arr.push(r);
+                else
+                    buckets.set(k, [r]);
+            }
+            const found = [];
+            for (const bucket of buckets.values())
+                found.push(...findContradictions(bucket));
+            if (found.length > 0)
+                onContradictions(found);
+        }
+        catch (err) {
+            onError?.("contradictions", err);
+        }
+    }
+}
+//# sourceMappingURL=maintenance.js.map