@spinabot/brigade 0.1.2 → 1.0.1

package/dist/agents/memory/extract.js

@@ -0,0 +1,571 @@
+/**
+ * Post-turn memory extraction — distillation algorithm run OFF the hot path.
+ *
+ * Design rationale (scalable / enterprise): the per-turn path stays at one
+ * model call; the expensive distillation happens in a debounced background
+ * sweep (driven by the long-lived gateway) that reads the NEW transcript
+ * turns since a cursor, distills them in ONE extraction call (many turns →
+ * one call), stores the resulting structured facts, and advances the
+ * cursor. We deliberately avoid the alternative of running an extraction
+ * LLM call after EVERY turn (≈2× model calls/turn, cost grows with
+ * volume).
+ *
+ * This module is the engine + cursor. The LLM call is INJECTED
+ * (`ExtractionLlm`) so the distillation logic is unit-testable without a
+ * provider; production builds the injectable via `makeExtractionLlm` (an
+ * isolated, tool-less, throwaway-transcript subagent). The gateway wires the
+ * debounced trigger (see server.ts).
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { createAgentSession, DefaultResourceLoader, SessionManager } from "@mariozechner/pi-coding-agent";
+import { createSubsystemLogger } from "../../logging/subsystem-logger.js";
+import { pickInitialThinkingLevel } from "../../core/model-caps.js";
+import { awaitFactsFlush, factsFlushErrorCount, workspaceIdFromDir } from "../../storage/facts-cache.js";
+import { tryGetRuntimeContext } from "../../storage/runtime-context.js";
+import { applyPersonaOverrideToSession } from "../../system-prompt/pi-injection.js";
+import { wrapStreamFnWithPayloadMutations } from "../payload-mutators.js";
+import { FactStore, MEMORY_SEGMENTS } from "./records.js";
+import { confineUntrustedSegment } from "./write-gate.js";
+import { balancedObjects } from "./json-scan.js";
+import { buildCandidateBlock, DEFAULT_CANDIDATE_K, fetchRelationshipCandidates, mapNewFactIds, pairToLinkArg, parseRelationshipRefs, RELATIONSHIP_PROMPT_FRAGMENT, resolveRelationshipPairs, } from "./relationship-extract.js";
+const log = createSubsystemLogger("memory/extract");
+let preCompactionHook;
+/**
+ * Register (or clear, with `undefined`) the hook that distils the about-to-be-
+ * compacted history. The gateway wires this at boot to a bounded extraction over
+ * the passed messages; unset elsewhere (tests, sub-agents) → a no-op. This closes
+ * the window where a fact lives ONLY in turns the compactor is about to swap for a
+ * summary — post-turn extraction + the reactive compaction guard catch the rest.
+ */
+export function setPreCompactionExtractionHook(fn) {
+    preCompactionHook = fn;
+}
+/**
+ * Fire the pre-compaction hook (if registered) over the caller's message SNAPSHOT —
+ * FIRE-AND-FORGET so compaction proceeds without turn latency and without racing
+ * the history replace (the snapshot is the hook's own immutable copy). Best-effort.
+ */
+export function runPreCompactionExtraction(args) {
+    const fn = preCompactionHook;
+    if (!fn)
+        return;
+    void Promise.resolve(fn(args)).catch(() => { });
+}
+/** Cursor store — tracks how many transcript messages we've already distilled. */
+const CURSOR_RELATIVE_PATH = path.join("memory", ".dreams", "extract-cursor.json");
+/** Extraction prompt — distills a BATCH of recent turns into durable facts. */
+export const EXTRACTION_PROMPT = `You are a memory-extraction subagent for a personal AI assistant.
+You are given a slice of recent conversation (one or more USER/ASSISTANT turns).
+Extract any DURABLE facts about the user or their world that are worth remembering long-term.
+
+Return STRICT JSON only — no prose, no markdown fences:
+{"facts":[{"content":"one clear self-contained sentence","segment":"identity|preference|correction|relationship|project|knowledge|context","importance":0.0,"corrects":"the prior belief, ONLY if segment=correction"}]}
+
+Rules:
+- Prefer few, high-quality facts over many trivial ones. Deduplicate within your output.
+- Skip anything transient ("I'm tired right now"). Context facts describe ongoing state, not momentary feelings.
+- Skip facts about YOU (the assistant) or the mechanics of the conversation.
+- Segments: identity = who the user is; preference = how they like things done; correction = the user FIXED a prior belief (set "corrects"); relationship = people in their life; project = their work / conventions / goals; knowledge = durable facts they told you; context = ongoing situational state.
+- Use "correction" (not preference/identity) when the user is fixing something rather than stating it fresh. "corrects" is ONLY for segment=correction.
+- Importance defaults by segment: identity 0.85, correction 0.80, relationship 0.75, preference 0.70, project 0.65, knowledge 0.60, context 0.40. Trust the defaults unless something is unusually important or trivial.
+- Return {"facts":[]} if nothing durable.
+Respond with ONLY the JSON object.${RELATIONSHIP_PROMPT_FRAGMENT}`;
+// `balancedObjects` lives in `./json-scan.js` (its own module) so `relationship-extract.ts`
+// can reuse it WITHOUT importing this file — that would form a load-time cycle, since
+// EXTRACTION_PROMPT above is built from relationship-extract.ts's prompt fragment at
+// module top level. Re-exported here so existing importers (skill-review,
+// skill-consolidate, consolidate) keep importing it from `extract.js` unchanged.
+export { balancedObjects };
+/**
+ * Parse the extraction model's reply AND report whether the model returned a valid
+ * reply ENVELOPE. Robust to prose-wrapped JSON, a trailing brace block, AND a
+ * leading stray object: scans every top-level balanced `{...}` and uses the FIRST
+ * that carries a `facts` array. Never throws.
+ *
+ * `parsedJson` is the load-bearing signal for cursor safety. It is TRUE only when
+ * the model returned a recognizable ENVELOPE — an object with a `facts` array
+ * (possibly empty), OR an empty object `{}` ("nothing to remember"). Both safely
+ * advance the cursor. It is FALSE for: an empty / truncated / non-JSON reply, AND
+ * for a MALFORMED-but-parseable reply that is NOT an envelope — a keyed object with
+ * no `facts` array (`{foo: 1}`, or a bare fact object `{content, segment}` from a
+ * model that dropped the envelope), or a top-level array `[{...}]` (whose inner
+ * objects parse but carry no `facts` key). Those latter cases may carry real,
+ * un-distilled content, so advancing past them would lose it forever — the caller
+ * (`runExtractionSweep`) HOLDS the cursor when FALSE and the next sweep retries.
+ */
+export function parseExtractionReply(text) {
+    if (!text)
+        return { facts: [], parsedJson: false };
+    let sawEnvelope = false; // a structured "nothing to extract" — an empty object {}
+    for (const block of balancedObjects(text)) {
+        let parsed;
+        try {
+            parsed = JSON.parse(block);
+        }
+        catch {
+            continue;
+        }
+        if (Array.isArray(parsed.facts)) {
+            const out = [];
+            for (const raw of parsed.facts) {
+                if (!raw || typeof raw !== "object")
+                    continue;
+                const f = raw;
+                if (typeof f.content !== "string" || f.content.trim().length === 0)
+                    continue;
+                if (typeof f.segment !== "string")
+                    continue;
+                out.push({
+                    content: f.content.trim(),
+                    segment: f.segment,
+                    importance: typeof f.importance === "number" ? f.importance : undefined,
+                    corrects: typeof f.corrects === "string" ? f.corrects : undefined,
+                });
+            }
+            return { facts: out, parsedJson: true };
+        }
+        // An EMPTY object {} is a structured "nothing to extract" — safe to advance.
+        // A NON-empty object lacking a `facts` array (e.g. `{foo:1}`, or a bare fact
+        // object the model emitted without the envelope, or the inner object of a
+        // top-level `[{...}]` array) is MALFORMED and may carry un-distilled content,
+        // so it is NOT an envelope: leave `sawEnvelope` false ⇒ the caller HOLDS.
+        if (parsed !== null && typeof parsed === "object" && Object.keys(parsed).length === 0)
+            sawEnvelope = true;
+    }
+    return { facts: [], parsedJson: sawEnvelope };
+}
+/** Parse the extraction model's reply into facts (back-compat thin wrapper —
+ *  drops the `parsedJson` signal; use {@link parseExtractionReply} when the
+ *  malformed-reply-vs-genuinely-empty distinction matters). Never throws. */
+export function parseExtractedFacts(text) {
+    return parseExtractionReply(text).facts;
+}
+/**
+ * Persist parsed facts to the FactStore. Skips unknown segments (rather than
+ * crashing), clamps importance via the store, and stamps `corrects` into
+ * metadata. Returns the number actually stored.
+ */
+export function storeExtractedFacts(workspaceDir, facts, sourceTurn, opts = {}) {
+    if (facts.length === 0)
+        return 0;
+    const store = new FactStore(workspaceDir);
+    // Auto-extraction is NEVER a direct owner statement — it is a distiller LLM's
+    // reading of an attacker-influenceable transcript. Tag it `extraction` (the
+    // write-gate's CONFINED tier) by default so a laundered "the user prefers X"
+    // can't become an authoritative owner fact or supersede one. The ORIGIN
+    // (owner vs channel) carries recall ISOLATION independently. An explicit
+    // caller-supplied sourceType still wins (e.g. a future trusted distiller).
+    const sourceType = opts.sourceType ?? "extraction";
+    const origin = opts.origin;
+    let stored = 0;
+    for (const f of facts) {
+        if (!MEMORY_SEGMENTS.includes(f.segment))
+            continue;
+        // IDEMPOTENCY (Fix 1): the distiller re-reads the SAME transcript turns the
+        // operator may have already taught via `write_memory`, and a reworded copy
+        // (segment `knowledge`, NO subjectKey) slips past write-time dedup's strict
+        // near-exact bar — piling a subject-less churn twin beside the rich original,
+        // which consolidation can then archive in place of the real one. So before
+        // creating anything, check whether an equivalent active same-origin fact
+        // already exists; if it does, REINFORCE it (more durable) and SKIP the new
+        // row — re-seeing a known fact is a no-op, not a duplicate. (`supersedes`/
+        // `corrects` distillations are NOT idempotency-skipped: those intend to
+        // replace a prior belief, handled by the write path.)
+        if (!f.corrects) {
+            const known = store.findEquivalentActive(f.content, origin);
+            if (known) {
+                store.reinforce(known.memoryId, { minConfidence: known.confidence });
+                continue;
+            }
+        }
+        // Confine rather than drop: an untrusted distillation proposing a
+        // protected segment (preference/identity/correction) lands as a descriptive
+        // `knowledge` evidence fact (kept, but down-weighted at recall and unable to
+        // pose as the operator's self-model). The write-gate is the hard backstop.
+        const segment = confineUntrustedSegment(sourceType, f.segment);
+        try {
+            store.write({
+                content: f.content,
+                segment,
+                ...(f.importance !== undefined ? { importance: f.importance } : {}),
+                ...(sourceTurn ? { sourceTurn } : {}),
+                // ORIGIN — the isolation stamp. Peer-derived extraction MUST carry the
+                // turn's CHANNEL origin (isolated by the origin filter) so it can't
+                // surface as the operator's own ground truth; owner-turn extraction
+                // passes the owner origin. Left undefined, a write resolves to OWNER.
+                ...(opts.origin ? { createdBy: opts.origin } : {}),
+                sourceType,
+                // `corrects` only belongs on a correction that SURVIVED confinement
+                // (a trusted source's correction); a confined→knowledge fact drops it.
+                ...(f.corrects && segment === "correction" ? { metadata: { corrects: f.corrects } } : {}),
+            });
+            stored += 1;
+        }
+        catch (err) {
+            // A BLOCKED write — the provenance write-gate (WriteGateError) or the
+            // content threat-scan (MemoryThreatError) rejected this distilled fact.
+            // Drop only THIS fact; the rest of the batch is independent and proceeds
+            // (aborting the loop would lose the clean facts too). Anything else is an
+            // unexpected fault — re-throw so it isn't silently swallowed.
+            const name = err instanceof Error ? err.name : "";
+            if (name === "MemoryThreatError" || name === "WriteGateError")
+                continue;
+            throw err;
+        }
+    }
+    return stored;
+}
+function cursorPath(workspaceDir) {
+    return path.join(workspaceDir, CURSOR_RELATIVE_PATH);
+}
+// Convex-mode cursor cache — keyed `${workspaceDir}|${sessionId}` and primed
+// lazily on first read (cursor misses default to 0, which is safe: the sweep
+// simply re-distils from the start and write-time dedup absorbs repeats).
+const convexCursorCache = new Map();
+let cursorFlushChain = Promise.resolve();
+/** Resolves when every cursor write enqueued so far reached the backend. */
+export function awaitCursorFlush() {
+    return cursorFlushChain;
+}
+/** Test-only. */
+export function __resetCursorCacheForTests() {
+    convexCursorCache.clear();
+    cursorFlushChain = Promise.resolve();
+}
+function readCursors(workspaceDir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(cursorPath(workspaceDir), "utf8"));
+        if (parsed && typeof parsed === "object" && parsed.cursors)
+            return parsed;
+    }
+    catch {
+        /* missing / corrupt → fresh */
+    }
+    return { version: 1, cursors: {} };
+}
+function writeCursor(workspaceDir, sessionId, processedCount) {
+    const rctx = tryGetRuntimeContext();
+    if (rctx?.mode === "convex") {
+        convexCursorCache.set(`${workspaceDir}|${sessionId}`, processedCount);
+        const store = rctx.store;
+        cursorFlushChain = cursorFlushChain
+            .then(() => store.memory.setExtractCursor(sessionId, processedCount))
+            .catch((err) => {
+            console.error(`brigade: extract-cursor write to convex failed — ${err.message}`);
+        });
+        return;
+    }
+    const file = readCursors(workspaceDir);
+    file.cursors[sessionId] = processedCount;
+    const p = cursorPath(workspaceDir);
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    const tmp = `${p}.tmp-${process.pid}-${Date.now().toString(36)}`;
+    try {
+        fs.writeFileSync(tmp, JSON.stringify(file), "utf8");
+        fs.renameSync(tmp, p);
+    }
+    catch (err) {
+        // Best-effort cleanup of the orphan tmp on any error before the
+        // rename — leaving stale `.tmp-…` files under .dreams/ would be
+        // visible noise on subsequent `ls` / git status. Re-throw after
+        // cleanup so the caller's existing best-effort logging still fires.
+        try {
+            fs.rmSync(tmp, { force: true });
+        }
+        catch {
+            // best-effort orphan-tmp cleanup
+        }
+        throw err;
+    }
+}
+export function getCursor(workspaceDir, sessionId) {
+    const rctx = tryGetRuntimeContext();
+    if (rctx?.mode === "convex") {
+        // Lazy: a miss reads as 0 and the async backfill primes the cache for
+        // the NEXT sweep. Re-distilling from 0 once is safe — write-time
+        // dedup absorbs repeated facts.
+        const key = `${workspaceDir}|${sessionId}`;
+        const cached = convexCursorCache.get(key);
+        if (cached !== undefined)
+            return cached;
+        void rctx.store.memory
+            .getExtractCursor(sessionId)
+            .then((n) => {
+            if (!convexCursorCache.has(key))
+                convexCursorCache.set(key, n);
+        })
+            .catch(() => { });
+        return 0;
+    }
+    return readCursors(workspaceDir).cursors[sessionId] ?? 0;
+}
+/**
+ * Distill the NEW transcript messages since this session's cursor into facts.
+ * Batches everything new into one LLM call, stores the result, advances the
+ * cursor. No-op (without an LLM call) when there's too little new content.
+ */
+export async function runExtractionSweep(args) {
+    const total = args.messages.length;
+    const storedCursor = getCursor(args.workspaceDir, args.sessionId);
+    // COMPACTION GUARD: the cursor is a raw index into `session.messages`, but Pi can
+    // REPLACE the history with a shorter summary (pre-emptive compaction at ~85% context
+    // — exactly the long, fact-rich sessions extraction matters most for). A stored
+    // cursor BEYOND the current length means that happened: re-scan from 0 so the
+    // post-compaction turns are still distilled (write-time dedup absorbs any repeats)
+    // instead of clamping to `total`, producing an empty slice, and permanently skipping
+    // every turn until the message count climbs back above the stale cursor.
+    const compacted = storedCursor > total;
+    const from = compacted ? 0 : storedCursor;
+    const fresh = args.messages.slice(from);
+    const minNew = args.minNewMessages ?? 2;
+    const conversation = flattenConversation(fresh);
+    // Need at least one real exchange worth of text.
+    if (fresh.length < minNew || conversation.trim().length === 0) {
+        // Correct a stale post-compaction cursor even when there's too little to distill,
+        // so it stops pointing past the (shrunken) transcript end on every later sweep.
+        if (compacted)
+            writeCursor(args.workspaceDir, args.sessionId, total);
+        return { ran: false, stored: 0, processedTo: compacted ? total : from };
+    }
+    // RELATIONSHIP EXTRACTION (no extra LLM call): append a BOUNDED candidate set of
+    // existing same-origin facts to the SAME extraction prompt, so the one extraction
+    // call ALSO returns `relationships` between {new facts ∪ candidates}. We fetch the
+    // top-K most-related existing facts via the existing hybrid recall (never the whole
+    // store) using the fresh transcript text as the query. Best-effort: a recall hiccup
+    // just yields no candidates (the model still relates new facts to each other).
+    let candidateBlock = "";
+    let candidateIds = new Set();
+    try {
+        const candidates = fetchRelationshipCandidates(new FactStore(args.workspaceDir), [conversation], args.origin, DEFAULT_CANDIDATE_K);
+        candidateBlock = buildCandidateBlock(candidates);
+        candidateIds = new Set(candidates.map((c) => c.memoryId));
+    }
+    catch {
+        /* no candidates → relationships limited to new↔new (still valuable) */
+    }
+    let reply = "";
+    try {
+        reply = await args.llm(conversation + candidateBlock);
+    }
+    catch (err) {
+        log.warn("extraction llm failed; cursor not advanced", {
+            sessionId: args.sessionId,
+            error: err instanceof Error ? err.message : String(err),
+        });
+        return { ran: false, stored: 0, processedTo: from };
+    }
+    const { facts, parsedJson } = parseExtractionReply(reply);
+    // ZERO-FACT GUARD: an empty / truncated / non-JSON reply (a transient distiller
+    // hiccup) is NOT the same as the model returning a structured "nothing to extract"
+    // (`{}` or `{facts: []}`). Advancing the cursor on the former would skip these
+    // turns FOREVER. Hold the cursor and let the next sweep retry (idempotent;
+    // write-time dedup absorbs any repeat). A structured empty reply (parsedJson=true,
+    // facts=[]) falls through and advances as before — re-distilling it wastes calls.
+    if (!parsedJson) {
+        log.warn("extraction reply was not parseable JSON; cursor NOT advanced (next sweep retries)", {
+            sessionId: args.sessionId,
+            replyChars: reply.length,
+        });
+        return { ran: false, stored: 0, processedTo: from };
+    }
+    const wsId = workspaceIdFromDir(args.workspaceDir);
+    const errorsBefore = factsFlushErrorCount(wsId);
+    const stored = storeExtractedFacts(args.workspaceDir, facts, args.sessionId, {
+        ...(args.origin ? { origin: args.origin } : {}),
+        ...(args.sourceType ? { sourceType: args.sourceType } : {}),
+    });
+    // CURSOR DURABILITY: in convex mode the facts write is enqueued ASYNC (the flush
+    // chain); advancing the cursor before it lands would SKIP those turns forever if the
+    // flush fails. Await the flush and only advance if it didn't error — otherwise leave
+    // the cursor put so the next sweep re-distils (idempotent; write-time dedup absorbs
+    // the repeat). In fs mode the chain is empty, so this awaits nothing and never trips.
+    await awaitFactsFlush();
+    if (factsFlushErrorCount(wsId) > errorsBefore) {
+        log.warn("extraction facts flush failed; cursor NOT advanced (next sweep retries)", { sessionId: args.sessionId });
+        return { ran: false, stored: 0, processedTo: from };
+    }
+    // SEMANTIC RELATIONSHIP EDGES — write the TYPED edges the SAME extraction reply
+    // proposed (no extra LLM call; gleaning is reserved for the on-demand relink to keep
+    // the per-turn path cheap). Map the just-written facts back to their stored memoryIds
+    // (in emission order, so `new:<i>` resolves correctly), then resolve+validate the
+    // model's pairs through the single chokepoint: both endpoints must be a REAL id (a
+    // written new fact OR a candidate that was in the prompt), no self-edges, strict type
+    // (closed taxonomy ∪ same_topic), reason mandatory, the strength filter, the
+    // same_topic quarantine cap, deduped. `linkRelated` is same-origin + idempotent, so
+    // this is origin-isolated and re-running adds nothing. Best-effort — never fails the
+    // sweep (the facts already landed; edges are additive connective tissue).
+    let relatesWritten = 0;
+    try {
+        const refs = parseRelationshipRefs(reply);
+        if (refs.length > 0) {
+            const store = new FactStore(args.workspaceDir);
+            const newFactIds = mapNewFactIds(store, facts.map((f) => f.content), args.origin);
+            const pairs = resolveRelationshipPairs(refs, newFactIds, candidateIds);
+            if (pairs.length > 0)
+                relatesWritten = store.linkRelated(pairs.map(pairToLinkArg));
+        }
+    }
+    catch {
+        /* edges are additive — a failure here never undoes the stored facts */
+    }
+    // Advance the cursor past everything we just considered (even if 0 stored —
+    // re-distilling the same turns would only waste calls).
+    writeCursor(args.workspaceDir, args.sessionId, total);
+    log.info("extraction sweep", {
+        sessionId: args.sessionId,
+        newMessages: fresh.length,
+        candidates: facts.length,
+        stored,
+        relates: relatesWritten,
+    });
+    return { ran: true, stored, processedTo: total };
+}
+/** Flatten Pi messages into "USER: …\n\nASSISTANT: …" text for the distiller. */
+export function flattenConversation(messages) {
+    const lines = [];
+    for (const m of messages) {
+        if (!m || typeof m !== "object")
+            continue;
+        const msg = m;
+        if (msg.role !== "user" && msg.role !== "assistant")
+            continue;
+        const text = flattenContent(msg.content).trim();
+        if (!text)
+            continue;
+        lines.push(`${msg.role === "user" ? "USER" : "ASSISTANT"}: ${text}`);
+    }
+    return lines.join("\n\n");
+}
+function flattenContent(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    const parts = [];
+    for (const block of content) {
+        if (typeof block === "string") {
+            parts.push(block);
+            continue;
+        }
+        if (block && typeof block === "object") {
+            const b = block;
+            if (b.type === "text" && typeof b.text === "string")
+                parts.push(b.text);
+        }
+    }
+    return parts.join("");
+}
+/**
+ * Default wall-clock cap on a single isolated-LLM call (extraction or
+ * consolidation sweep). 60s is generous for distillation prompts that return
+ * ≤ a few hundred tokens; without a cap, a stuck provider (a hung Anthropic
+ * request, a wedged local-Ollama, an unresponsive OpenRouter route) would
+ * leave the sweep flag set forever and silently kill all future extraction
+ * for that agent. Tunable via env for slower hosted models / debug runs.
+ */
+const MEMORY_LLM_TIMEOUT_MS_DEFAULT = 60_000;
+function getMemoryLlmTimeoutMs() {
+    const raw = process.env.BRIGADE_MEMORY_LLM_TIMEOUT_MS;
+    const parsed = raw ? Number(raw) : NaN;
+    // 5s floor so a misconfigured "0" / "1" doesn't preemptively kill every call.
+    return Number.isFinite(parsed) && parsed >= 5_000 ? parsed : MEMORY_LLM_TIMEOUT_MS_DEFAULT;
+}
+/** Marker thrown when a memory sweep LLM call exceeds its wall-clock cap. */
+export class MemoryLlmTimeoutError extends Error {
+    code = "memory-llm:timeout";
+    constructor(timeoutMs) {
+        super(`memory LLM call exceeded ${timeoutMs}ms timeout`);
+        this.name = "MemoryLlmTimeoutError";
+    }
+}
+/**
+ * Build an ISOLATED, tool-less subagent runner: a one-shot LLM call with
+ * `systemPrompt` pinned, run against a throwaway transcript (deleted after) so
+ * it never pollutes the real session. Reuses the resolved model/auth (inherits
+ * Pi's auth-aware streamFn — never replaced). Shared by the extraction sweep
+ * and the consolidation sweep; both cost one extra call per SWEEP, not per turn.
+ *
+ * Each call is bounded by `BRIGADE_MEMORY_LLM_TIMEOUT_MS` (default 60s) — on
+ * timeout the underlying session is aborted and `MemoryLlmTimeoutError` is
+ * thrown so the caller's existing catch path (which leaves the cursor put)
+ * surfaces a silent stall as a recoverable log line on the next sweep.
+ */
+export function makeIsolatedLlm(systemPrompt, args) {
+    return async (input) => {
+        // `inMemory()` skips ALL persistence (both modes) — the isolated sweep
+        // never touches disk. Convex mode additionally needs this so the sweep
+        // writes nothing under ~/.brigade.
+        const sessionManager = SessionManager.inMemory(args.workspaceDir);
+        try {
+            const { session } = await createAgentSession({
+                cwd: args.workspaceDir,
+                agentDir: args.agentDir,
+                authStorage: args.authStorage,
+                modelRegistry: args.modelRegistry,
+                model: args.model,
+                // Reasoning-aware: some models (Gemini 2.5 Pro, o-series) reject
+                // "off". Derive a safe level rather than hardcoding it.
+                thinkingLevel: pickInitialThinkingLevel(args.model),
+                tools: [],
+                customTools: [],
+                sessionManager,
+                resourceLoader: new DefaultResourceLoader({ cwd: args.workspaceDir, agentDir: args.agentDir }),
+            });
+            if (!session)
+                return "";
+            // Isolated sweeps create their OWN Pi session, so they miss the
+            // streamFn wrap the main agent-loop installs — without this, the
+            // extraction's OpenRouter call leaks Pi's default "pi" / pi.dev
+            // attribution (and skips the payload mutators) instead of reporting
+            // as Brigade. Wrap here too so EVERY OpenRouter request Brigade makes
+            // is attributed to Brigade.
+            wrapStreamFnWithPayloadMutations(session);
+            applyPersonaOverrideToSession(session, systemPrompt);
+            // Race the LLM call against a wall-clock timeout. On timeout we
+            // call `session.abort()` (Pi cancels the in-flight stream) and
+            // reject so the caller's existing catch path triggers (cursor
+            // stays put, throttle stamp unchanged, next sweep retries).
+            const timeoutMs = getMemoryLlmTimeoutMs();
+            let timer = null;
+            const timeoutPromise = new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    // Best-effort abort — Pi's abort() is documented to never
+                    // throw, but we defensively swallow so the rejection below
+                    // is what surfaces to the caller.
+                    void session.abort?.().catch(() => { });
+                    reject(new MemoryLlmTimeoutError(timeoutMs));
+                }, timeoutMs);
+                timer.unref?.();
+            });
+            try {
+                await Promise.race([session.prompt(input), timeoutPromise]);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+            return lastAssistantText(session);
+        }
+        finally {
+            // inMemory() session — nothing to clean up; entries die with the
+            // manager reference.
+        }
+    };
+}
+/**
+ * The extraction distiller — `makeIsolatedLlm` with the EXTRACTION_PROMPT pinned.
+ */
+export function makeExtractionLlm(args) {
+    return makeIsolatedLlm(EXTRACTION_PROMPT, args);
+}
+function lastAssistantText(session) {
+    const messages = session.messages;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (m?.role === "assistant")
+            return flattenContent(m.content);
+    }
+    return "";
+}
+//# sourceMappingURL=extract.js.map

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

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

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

@@ -0,0 +1,45 @@
+import { type MemoryLink, type MemoryLinkKind } from "./links.js";
+import { FactStore, type MemoryRecord, type RecordOriginFilter } from "./records.js";
+export interface PurgeResult {
+    /** Every id hard-removed — the seed(s) plus the sourcePointers cascade. */
+    purged: string[];
+}
+/**
+ * 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 declare function purge(store: FactStore, seedIds: string | readonly string[]): PurgeResult;
+/**
+ * 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 declare function applyRetention(store: FactStore, opts: {
+    ttlMs: number;
+    now?: number;
+    keepConfirmed?: boolean;
+    origin?: RecordOriginFilter;
+}): PurgeResult;
+export interface InspectResult {
+    record: MemoryRecord;
+    /** This fact's outbound edges (explicit links ∪ mirrored supersedes). */
+    outbound: MemoryLink[];
+    /** Inbound edges across the corpus. */
+    backlinks: Array<{
+        from: string;
+        kind: MemoryLinkKind;
+    }>;
+    /** Source ids this fact was derived from (its citations). */
+    derivedFrom: string[];
+    /** Ids of facts derived FROM this one (its citers — the cascade set). */
+    derives: string[];
+}
+/** Full provenance view of one fact: links, backlinks, and the citation graph. */
+export declare function inspect(store: FactStore, memoryId: string): InspectResult | undefined;
+/** Export records — all, or scoped to one origin (portability / data-subject export). */
+export declare function exportMemory(store: FactStore, opts?: {
+    origin?: RecordOriginFilter;
+}): MemoryRecord[];
+//# sourceMappingURL=governance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"governance.d.ts","sourceRoot":"","sources":["../../../src/agents/memory/governance.ts"],"names":[],"mappings":"AAeA,OAAO,EAA0B,KAAK,UAAU,EAAE,KAAK,cAAc,EAAE,MAAM,YAAY,CAAC;AAC1F,OAAO,EAAE,SAAS,EAA6B,KAAK,YAAY,EAAE,KAAK,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEhH,MAAM,WAAW,WAAW;IAC3B,2EAA2E;IAC3E,MAAM,EAAE,MAAM,EAAE,CAAC;CACjB;AAiCD;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,GAAG,WAAW,CAGxF;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAC7B,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,kBAAkB,CAAA;CAAE,GACzF,WAAW,CA2Bb;AAED,MAAM,WAAW,aAAa;IAC7B,MAAM,EAAE,YAAY,CAAC;IACrB,yEAAyE;IACzE,QAAQ,EAAE,UAAU,EAAE,CAAC;IACvB,uCAAuC;IACvC,SAAS,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,cAAc,CAAA;KAAE,CAAC,CAAC;IACzD,6DAA6D;IAC7D,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,yEAAyE;IACzE,OAAO,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,kFAAkF;AAClF,wBAAgB,OAAO,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAYrF;AAED,yFAAyF;AACzF,wBAAgB,YAAY,CAAC,KAAK,EAAE,SAAS,EAAE,IAAI,GAAE;IAAE,MAAM,CAAC,EAAE,kBAAkB,CAAA;CAAO,GAAG,YAAY,EAAE,CAGzG"}