@kinqs/brainrouter-mcp-server 0.3.4

package/dist/memory/pipeline/l2-scene.js

@@ -0,0 +1,140 @@
+import { L2_SCENE_SYSTEM_PROMPT, formatL2ScenePrompt } from "../prompts/l2-scene.js";
+import { L2_SCENE_CLUSTER_SYSTEM_PROMPT, formatSceneClusterPrompt } from "../prompts/l2-scene-cluster.js";
+import { L2_MAX_SCENES } from "../scheduler.js";
+import crypto from "node:crypto";
+async function canonicalizeSceneNames(params) {
+    const { userId, store, llmRunner } = params;
+    const sceneNames = store.getDistinctSceneNames(userId);
+    if (sceneNames.length < 2)
+        return;
+    try {
+        const rawCluster = await llmRunner.run({
+            prompt: formatSceneClusterPrompt(sceneNames),
+            systemPrompt: L2_SCENE_CLUSTER_SYSTEM_PROMPT,
+            taskId: "l2-scene-clustering",
+            timeoutMs: 45_000,
+        });
+        const jsonMatch = rawCluster.match(/\[[\s\S]*\]/);
+        if (!jsonMatch)
+            return;
+        const clusters = JSON.parse(jsonMatch[0]);
+        if (!Array.isArray(clusters))
+            return;
+        for (const cluster of clusters) {
+            const canonical = String(cluster.canonical || "").trim();
+            const aliases = Array.isArray(cluster.aliases) ? cluster.aliases.map((a) => String(a).trim()) : [];
+            if (!canonical || aliases.length === 0)
+                continue;
+            for (const alias of aliases) {
+                if (alias === canonical)
+                    continue;
+                store.renameSceneInL1Records(userId, alias, canonical);
+            }
+        }
+    }
+    catch (err) {
+        console.error(`[BrainRouter] Scene canonicalization failed for "${userId}":`, err.message);
+    }
+}
+/**
+ * L2 Scene Pipeline
+ * Groups L1 memories by scene_name and asks the LLM to produce
+ * a Markdown summary for each scene. Updates heat scores.
+ */
+export async function distillScenes(params) {
+    const { userId, store, llmRunner } = params;
+    // Run scene canonicalization/clustering pass to prevent cold-start fragmentation
+    await canonicalizeSceneNames({ userId, store, llmRunner });
+    // Decay all existing heat scores (each distillation cycle = time passing)
+    store.decayL2HeatScores(userId);
+    const sceneNames = store.getDistinctSceneNames(userId);
+    if (sceneNames.length === 0) {
+        return { scenesDistilled: 0, sceneNames: [] };
+    }
+    const now = new Date().toISOString();
+    const distilled = [];
+    // Fetch existing L2 scene names up-front so the prompt can avoid near-duplicates
+    const existingL2SceneNames = store.getTopL2Scenes(userId, 50).map(s => s.sceneName);
+    for (const sceneName of sceneNames) {
+        const l1s = store.getL1sByScene(userId, sceneName, 30);
+        if (l1s.length === 0)
+            continue;
+        let summaryMd;
+        try {
+            summaryMd = await llmRunner.run({
+                prompt: formatL2ScenePrompt(sceneName, l1s, existingL2SceneNames.filter(n => n !== sceneName)),
+                systemPrompt: L2_SCENE_SYSTEM_PROMPT,
+                taskId: "l2-scene-distillation",
+                timeoutMs: 60_000,
+            });
+        }
+        catch (err) {
+            console.error(`[BrainRouter] L2 scene distillation failed for "${sceneName}":`, err.message);
+            continue;
+        }
+        const existing = store.getL2SceneByName(userId, sceneName);
+        const record = {
+            id: existing?.id ?? `l2_${crypto.randomBytes(6).toString("hex")}`,
+            userId,
+            sceneName,
+            summaryMd: summaryMd.trim(),
+            heatScore: existing ? Math.min(100, existing.heatScore + 30) : 100,
+            lastActiveTime: now,
+            createdTime: existing?.createdTime ?? now,
+            updatedTime: now,
+        };
+        store.upsertL2Scene(record);
+        distilled.push(sceneName);
+    }
+    // Auto-merge cold scenes if we exceed the max threshold
+    await mergeScenes({ userId, store, llmRunner });
+    console.error(`[BrainRouter] L2 distilled ${distilled.length} scene(s) for user "${userId}".`);
+    return { scenesDistilled: distilled.length, sceneNames: distilled };
+}
+async function mergeScenes(params) {
+    const { userId, store, llmRunner } = params;
+    const sceneCount = store.getL2SceneCount(userId);
+    if (sceneCount < L2_MAX_SCENES)
+        return;
+    const overflow = sceneCount - L2_MAX_SCENES + 1;
+    const coldScenes = store.getColdL2Scenes(userId, overflow + 3);
+    // Need at least 2 cold scenes to meaningfully merge
+    if (coldScenes.length < 2)
+        return;
+    // Skip any existing [Archived] scene from the merge input — we'll update it separately
+    const archiveSceneName = "[Archived]";
+    const scenesToMerge = coldScenes.filter(s => s.sceneName !== archiveSceneName);
+    if (scenesToMerge.length < 2)
+        return;
+    const sceneSummaries = scenesToMerge.map(s => `## ${s.sceneName}\n${s.summaryMd}`).join("\n\n");
+    let unifiedSummary;
+    try {
+        unifiedSummary = await llmRunner.run({
+            prompt: `Merge the following old scene summaries into a single concise "Archived Scenes" overview.\n\n${sceneSummaries}\n\nOutput only the Markdown summary. Be concise — no preamble.`,
+            systemPrompt: L2_SCENE_SYSTEM_PROMPT,
+            taskId: "l2-scene-merge",
+            timeoutMs: 60_000,
+        });
+    }
+    catch (err) {
+        console.error(`[BrainRouter] L2 scene merge failed for "${userId}":`, err.message);
+        return;
+    }
+    const now = new Date().toISOString();
+    // Look up any pre-existing [Archived] scene
+    const existingArchive = store.getL2SceneByName(userId, archiveSceneName);
+    const record = {
+        id: existingArchive?.id ?? `l2_${crypto.randomBytes(6).toString("hex")}`,
+        userId,
+        sceneName: archiveSceneName,
+        summaryMd: unifiedSummary.trim(),
+        heatScore: 10,
+        lastActiveTime: now,
+        createdTime: existingArchive?.createdTime ?? now,
+        updatedTime: now,
+    };
+    store.upsertL2Scene(record);
+    const idsToDelete = scenesToMerge.map(s => s.id);
+    store.deleteL2Scenes(userId, idsToDelete);
+    console.error(`[BrainRouter] L2 auto-merge: merged ${idsToDelete.length} cold scenes into "${archiveSceneName}".`);
+}

package/dist/memory/pipeline/l3-distiller.d.ts

@@ -0,0 +1,15 @@
+import type { IMemoryStore } from "@brainrouter/types";
+import type { LLMRunner } from "@brainrouter/types";
+/**
+ * L3 Persona Distillation Pipeline
+ * Scans ALL persona + instruction L1 memories across all sessions
+ * for a user and synthesizes a durable Narrative Profile.
+ */
+export declare function distillPersona(params: {
+    userId: string;
+    store: IMemoryStore;
+    llmRunner: LLMRunner;
+}): Promise<{
+    success: boolean;
+    personaMd?: string;
+}>;

package/dist/memory/pipeline/l3-distiller.js

@@ -0,0 +1,40 @@
+import { L3_PERSONA_SYSTEM_PROMPT, formatL3PersonaPrompt } from "../prompts/l3-persona.js";
+/**
+ * L3 Persona Distillation Pipeline
+ * Scans ALL persona + instruction L1 memories across all sessions
+ * for a user and synthesizes a durable Narrative Profile.
+ */
+export async function distillPersona(params) {
+    const { userId, store, llmRunner } = params;
+    // Cross-session: fetch all persona + instruction L1s for this user
+    const memories = store.getPersonaAndInstructionL1s(userId, 100);
+    if (memories.length === 0) {
+        console.error(`[BrainRouter] L3 skipped for "${userId}" — no persona/instruction memories yet.`);
+        return { success: false };
+    }
+    let personaMd;
+    try {
+        personaMd = await llmRunner.run({
+            prompt: formatL3PersonaPrompt(memories),
+            systemPrompt: L3_PERSONA_SYSTEM_PROMPT,
+            taskId: "l3-persona-distillation",
+            timeoutMs: 90_000,
+        });
+    }
+    catch (err) {
+        console.error(`[BrainRouter] L3 persona distillation failed for "${userId}":`, err.message);
+        return { success: false };
+    }
+    const now = new Date().toISOString();
+    const existing = store.getL3Persona(userId);
+    const record = {
+        userId,
+        personaMd: personaMd.trim(),
+        l1CountAtGeneration: memories.length,
+        createdTime: existing?.createdTime ?? now,
+        updatedTime: now,
+    };
+    store.upsertL3Persona(record);
+    console.error(`[BrainRouter] L3 persona updated for "${userId}" (${memories.length} L1s).`);
+    return { success: true, personaMd: personaMd.trim() };
+}

package/dist/memory/pipeline/neural-spark.d.ts

@@ -0,0 +1,27 @@
+import type { IMemoryStore } from "@kinqs/brainrouter-types";
+export interface SparkNode {
+    id: string;
+    potential: number;
+    fired: boolean;
+}
+export declare class NeuralSparkEngine {
+    private store;
+    private readonly threshold;
+    private readonly ltpStep;
+    private readonly decayFactor;
+    private readonly pruneThreshold;
+    constructor(store: IMemoryStore);
+    /**
+     * Propagates potentials from fired nodes to their neighbors.
+     * Runs a 2-hop BFS.
+     */
+    propagateSparks(userId: string, initialNodes: SparkNode[]): SparkNode[];
+    /**
+     * Hebbian Spine updates (LTP) for cited pairs
+     */
+    strengthenSpines(userId: string, citedIds: string[]): void;
+    /**
+     * Synaptic decay & pruning (LTD)
+     */
+    decayAndPrune(userId: string): void;
+}

package/dist/memory/pipeline/neural-spark.js

@@ -0,0 +1,78 @@
+export class NeuralSparkEngine {
+    store;
+    threshold = 0.70;
+    ltpStep = 0.15;
+    decayFactor = 0.90; // Default decay multiplier (LTD)
+    pruneThreshold = 0.10;
+    constructor(store) {
+        this.store = store;
+    }
+    /**
+     * Propagates potentials from fired nodes to their neighbors.
+     * Runs a 2-hop BFS.
+     */
+    propagateSparks(userId, initialNodes) {
+        const activeNodes = new Map(initialNodes.map(node => [node.id, { ...node, fired: false }]));
+        const queue = [];
+        // 1. Detect initial nodes crossing threshold
+        for (const node of initialNodes) {
+            if (node.potential >= this.threshold) {
+                const active = activeNodes.get(node.id);
+                active.fired = true;
+                queue.push(node.id);
+            }
+        }
+        // 2. Propagate potential (2-hop limit)
+        let hops = 0;
+        while (queue.length > 0 && hops < 2) {
+            const currentSize = queue.length;
+            for (let i = 0; i < currentSize; i++) {
+                const sourceId = queue.shift();
+                const sourceNode = activeNodes.get(sourceId);
+                // Retrieve connections (dendritic spines) from store
+                const connections = this.store.getConnectionsForSource(userId, sourceId);
+                for (const conn of connections) {
+                    let target = activeNodes.get(conn.targetId);
+                    if (!target) {
+                        target = { id: conn.targetId, potential: 0.0, fired: false };
+                        activeNodes.set(conn.targetId, target);
+                    }
+                    // Refractory check: if it already fired, don't excite it again
+                    if (target.fired)
+                        continue;
+                    // Propagate post-synaptic potential: source_potential * W_ij
+                    const psp = sourceNode.potential * conn.weight;
+                    target.potential = Math.min(1.0, target.potential + psp);
+                    // Firing check
+                    if (target.potential >= this.threshold) {
+                        target.fired = true;
+                        queue.push(target.id);
+                    }
+                }
+            }
+            hops++;
+        }
+        return Array.from(activeNodes.values());
+    }
+    /**
+     * Hebbian Spine updates (LTP) for cited pairs
+     */
+    strengthenSpines(userId, citedIds) {
+        if (citedIds.length < 2)
+            return;
+        const pairs = [];
+        for (let i = 0; i < citedIds.length; i++) {
+            for (let j = i + 1; j < citedIds.length; j++) {
+                pairs.push({ source: citedIds[i], target: citedIds[j] });
+            }
+        }
+        this.store.strengthenConnectionsBatch(userId, pairs, this.ltpStep);
+    }
+    /**
+     * Synaptic decay & pruning (LTD)
+     */
+    decayAndPrune(userId) {
+        this.store.decayConnections(userId, this.decayFactor);
+        this.store.pruneConnections(userId, this.pruneThreshold);
+    }
+}

package/dist/memory/pipeline/skill-prewarm.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Skill Pre-warming Pipeline
+ *
+ * Tracks persistent skill activation potential. When a skill potential crosses
+ * the configured threshold, its registered extraction hints are proactively
+ * injected into `appendSystemContext` as a `<skill-prewarm>` block.
+ *
+ * This is opt-in via BRAINROUTER_PREWARM_ENABLED=true (disabled by default).
+ */
+import type { IMemoryStore } from "@kinqs/brainrouter-types";
+export interface PrewarmResult {
+    skillName: string;
+    potential: number;
+    hints: string;
+}
+export interface SkillActivationConfig {
+    halfLifeMinutes: number;
+    minTurnDecay: number;
+    threshold: number;
+    spikeAmount: number;
+    maxPotential: number;
+}
+export declare function decayPotential(params: {
+    potential: number;
+    lastDecayTime: string;
+    now?: Date;
+    halfLifeMinutes?: number;
+    minTurnDecay?: number;
+}): number;
+/**
+ * Increase a skill's activation potential after explicit skill use.
+ *
+ * The existing potential is decayed up to `now`, then the spike is applied and
+ * capped. The result is persisted so activation survives process restarts.
+ */
+export declare function spikeSkill(params: {
+    userId: string;
+    skillName: string;
+    store: IMemoryStore;
+    now?: Date;
+    config?: Partial<SkillActivationConfig>;
+}): {
+    skillName: string;
+    potential: number;
+    lastDecayTime: string;
+} | null;
+/**
+ * Detect which skills qualify for pre-warming based on persistent activation potential.
+ * Returns an array of skill names and their hints, sorted by potential.
+ */
+export declare function detectPrewarmSkills(params: {
+    userId: string;
+    store: IMemoryStore;
+    threshold?: number;
+    excludeSkill?: string;
+    now?: Date;
+    config?: Partial<SkillActivationConfig>;
+}): PrewarmResult[];
+/**
+ * Build the `<skill-prewarm>` block for injection into `appendSystemContext`.
+ * Returns an empty string if no skills qualify.
+ */
+export declare function buildPrewarmBlock(prewarmResults: PrewarmResult[]): string;

package/dist/memory/pipeline/skill-prewarm.js

@@ -0,0 +1,127 @@
+/**
+ * Skill Pre-warming Pipeline
+ *
+ * Tracks persistent skill activation potential. When a skill potential crosses
+ * the configured threshold, its registered extraction hints are proactively
+ * injected into `appendSystemContext` as a `<skill-prewarm>` block.
+ *
+ * This is opt-in via BRAINROUTER_PREWARM_ENABLED=true (disabled by default).
+ */
+function parseNumber(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : fallback;
+}
+function getActivationConfig(overrides = {}) {
+    const halfLifeMinutes = overrides.halfLifeMinutes
+        ?? parseNumber(process.env.BRAINROUTER_SKILL_HALF_LIFE_MINUTES, 10);
+    const minTurnDecay = overrides.minTurnDecay
+        ?? parseNumber(process.env.BRAINROUTER_SKILL_MIN_TURN_DECAY, 0.05);
+    const threshold = overrides.threshold
+        ?? parseNumber(process.env.BRAINROUTER_SKILL_PREWARM_THRESHOLD, 0.3);
+    const spikeAmount = overrides.spikeAmount
+        ?? parseNumber(process.env.BRAINROUTER_SKILL_SPIKE_AMOUNT, 1.0);
+    const maxPotential = overrides.maxPotential
+        ?? parseNumber(process.env.BRAINROUTER_SKILL_MAX_POTENTIAL, 4.0);
+    return {
+        halfLifeMinutes: halfLifeMinutes > 0 ? halfLifeMinutes : 10,
+        minTurnDecay: minTurnDecay >= 0 && minTurnDecay < 1 ? minTurnDecay : 0.05,
+        threshold: threshold >= 0 ? threshold : 0.3,
+        spikeAmount: spikeAmount >= 0 ? spikeAmount : 1.0,
+        maxPotential: maxPotential > 0 ? maxPotential : 4.0,
+    };
+}
+export function decayPotential(params) {
+    const config = getActivationConfig({
+        halfLifeMinutes: params.halfLifeMinutes,
+        minTurnDecay: params.minTurnDecay,
+    });
+    const lastDecayMs = Date.parse(params.lastDecayTime);
+    if (!Number.isFinite(params.potential) || params.potential <= 0)
+        return 0;
+    const nowMs = (params.now ?? new Date()).getTime();
+    const elapsedMinutes = Number.isFinite(lastDecayMs)
+        ? Math.max(0, (nowMs - lastDecayMs) / 60_000)
+        : 0;
+    const lambda = Math.log(2) / config.halfLifeMinutes;
+    const timeDecayed = params.potential * Math.exp(-lambda * elapsedMinutes);
+    const turnDecayed = params.potential * (1 - config.minTurnDecay);
+    return Math.max(0, Math.min(timeDecayed, turnDecayed));
+}
+/**
+ * Increase a skill's activation potential after explicit skill use.
+ *
+ * The existing potential is decayed up to `now`, then the spike is applied and
+ * capped. The result is persisted so activation survives process restarts.
+ */
+export function spikeSkill(params) {
+    const skillName = params.skillName.trim();
+    if (!skillName)
+        return null;
+    const config = getActivationConfig(params.config);
+    const now = params.now ?? new Date();
+    const nowIso = now.toISOString();
+    const existing = params.store
+        .getSkillActivations(params.userId)
+        .find((record) => record.skillName === skillName);
+    const decayed = existing
+        ? decayPotential({
+            potential: existing.potential,
+            lastDecayTime: existing.lastDecayTime,
+            now,
+            halfLifeMinutes: config.halfLifeMinutes,
+            minTurnDecay: config.minTurnDecay,
+        })
+        : 0;
+    const potential = Math.min(config.maxPotential, decayed + config.spikeAmount);
+    const activation = { skillName, potential, lastDecayTime: nowIso };
+    params.store.upsertSkillActivations(params.userId, [activation]);
+    return activation;
+}
+/**
+ * Detect which skills qualify for pre-warming based on persistent activation potential.
+ * Returns an array of skill names and their hints, sorted by potential.
+ */
+export function detectPrewarmSkills(params) {
+    const { userId, store, excludeSkill, } = params;
+    const config = getActivationConfig({ ...params.config, threshold: params.threshold });
+    const now = params.now ?? new Date();
+    const activations = store.getSkillActivations(userId);
+    if (activations.length === 0)
+        return [];
+    const decayedActivations = activations.map((activation) => ({
+        skillName: activation.skillName,
+        potential: decayPotential({
+            potential: activation.potential,
+            lastDecayTime: activation.lastDecayTime,
+            now,
+            halfLifeMinutes: config.halfLifeMinutes,
+            minTurnDecay: config.minTurnDecay,
+        }),
+        lastDecayTime: activation.lastDecayTime,
+    }));
+    const results = [];
+    for (const activation of decayedActivations) {
+        if (activation.skillName === excludeSkill)
+            continue;
+        if (activation.potential < config.threshold)
+            continue;
+        const hints = store.getSkillHints(activation.skillName);
+        if (!hints)
+            continue; // No hints registered — nothing useful to inject
+        results.push({ skillName: activation.skillName, potential: activation.potential, hints });
+    }
+    results.sort((a, b) => b.potential - a.potential || a.skillName.localeCompare(b.skillName));
+    return results;
+}
+/**
+ * Build the `<skill-prewarm>` block for injection into `appendSystemContext`.
+ * Returns an empty string if no skills qualify.
+ */
+export function buildPrewarmBlock(prewarmResults) {
+    if (prewarmResults.length === 0)
+        return "";
+    const sections = prewarmResults.map(({ skillName, potential, hints }) => `  [${skillName}] (activation ${potential.toFixed(2)})\n  ${hints.split("\n").join("\n  ")}`);
+    return `<skill-prewarm>\n  Skills detected as currently active — hints pre-loaded:\n\n${sections.join("\n\n---\n\n")}\n</skill-prewarm>`;
+}

package/dist/memory/pipeline/task-queue.d.ts

@@ -0,0 +1,54 @@
+/**
+ * BrainRouter — Background Task Queue (Optimization C)
+ *
+ * Decouples L2 scene distillation and L3 persona distillation from the hot
+ * path of capture(). These are the most expensive, non-latency-critical steps.
+ *
+ * Graph extraction (Opt B) fires immediately as fire-and-forget — it is NOT queued.
+ * Contradiction detection (Opt A) also fires immediately as fire-and-forget.
+ *
+ * Flush triggers:
+ *   1. Lazy — called by recall() when the user is idle (lastCapture > idleThresholdMs)
+ *   2. Explicit — engine.flush(userId) called directly
+ *   3. Disabled — BRAINROUTER_ASYNC_PIPELINE=false keeps old fire-and-forget behaviour
+ */
+import type { SqliteMemoryStore } from "../store/sqlite.js";
+import type { LLMRunner } from "../types.js";
+export type TaskType = "l2_scene" | "l3_persona";
+export interface PendingTask {
+    id: string;
+    userId: string;
+    taskType: TaskType;
+    /** JSON-encoded payload specific to the task type */
+    payload: string;
+    createdAt: string;
+}
+/** Is the async pipeline enabled? Default: true. Set to "false" to use old fire-and-forget. */
+export declare function isAsyncPipelineEnabled(): boolean;
+/**
+ * Enqueue a task in the persistent SQLite queue instead of firing it immediately.
+ * Safe to call from the capture hot path — synchronous SQLite insert, no I/O wait.
+ */
+export declare function enqueueTask(store: SqliteMemoryStore, task: {
+    userId: string;
+    taskType: TaskType;
+    payload: Record<string, unknown>;
+}): void;
+export interface FlushResult {
+    userId: string;
+    tasksProcessed: number;
+    tasksFailed: number;
+    durationMs: number;
+}
+/**
+ * Process all pending L2/L3 tasks for a user in FIFO order.
+ *
+ * Re-entrant safe: if a flush is already in progress for this userId, the existing
+ * promise is returned instead of starting a second flush.
+ */
+export declare function flushPendingTasks(userId: string, store: SqliteMemoryStore, synthesisRunner: LLMRunner): Promise<FlushResult>;
+/**
+ * Returns true if the user has been idle long enough that pre-recall flushing
+ * won't noticeably delay the response.
+ */
+export declare function isUserIdle(store: SqliteMemoryStore, userId: string): boolean;

package/dist/memory/pipeline/task-queue.js

@@ -0,0 +1,117 @@
+/**
+ * BrainRouter — Background Task Queue (Optimization C)
+ *
+ * Decouples L2 scene distillation and L3 persona distillation from the hot
+ * path of capture(). These are the most expensive, non-latency-critical steps.
+ *
+ * Graph extraction (Opt B) fires immediately as fire-and-forget — it is NOT queued.
+ * Contradiction detection (Opt A) also fires immediately as fire-and-forget.
+ *
+ * Flush triggers:
+ *   1. Lazy — called by recall() when the user is idle (lastCapture > idleThresholdMs)
+ *   2. Explicit — engine.flush(userId) called directly
+ *   3. Disabled — BRAINROUTER_ASYNC_PIPELINE=false keeps old fire-and-forget behaviour
+ */
+import { distillScenes } from "./l2-scene.js";
+import { distillPersona } from "./l3-distiller.js";
+// ─── Config ───────────────────────────────────────────────────────────────────
+/** Flush pending tasks before recall if last capture was more than this many ms ago. */
+const IDLE_THRESHOLD_MS = parseInt(process.env.BRAINROUTER_FLUSH_IDLE_MS ?? String(30_000), // default: 30s idle
+10);
+/** Is the async pipeline enabled? Default: true. Set to "false" to use old fire-and-forget. */
+export function isAsyncPipelineEnabled() {
+    return process.env.BRAINROUTER_ASYNC_PIPELINE !== "false";
+}
+// ─── Enqueue ──────────────────────────────────────────────────────────────────
+/**
+ * Enqueue a task in the persistent SQLite queue instead of firing it immediately.
+ * Safe to call from the capture hot path — synchronous SQLite insert, no I/O wait.
+ */
+export function enqueueTask(store, task) {
+    const id = `task_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`;
+    store.upsertPendingTask({
+        id,
+        userId: task.userId,
+        taskType: task.taskType,
+        payload: JSON.stringify(task.payload),
+        createdAt: new Date().toISOString(),
+    });
+}
+// ─── Flush ────────────────────────────────────────────────────────────────────
+/** Active flush promises per userId to prevent concurrent flushes */
+const flushInProgress = new Map();
+/**
+ * Process all pending L2/L3 tasks for a user in FIFO order.
+ *
+ * Re-entrant safe: if a flush is already in progress for this userId, the existing
+ * promise is returned instead of starting a second flush.
+ */
+export async function flushPendingTasks(userId, store, synthesisRunner) {
+    const existing = flushInProgress.get(userId);
+    if (existing)
+        return existing;
+    const flushPromise = _doFlush(userId, store, synthesisRunner);
+    flushInProgress.set(userId, flushPromise);
+    try {
+        return await flushPromise;
+    }
+    finally {
+        flushInProgress.delete(userId);
+    }
+}
+async function _doFlush(userId, store, synthesisRunner) {
+    const start = Date.now();
+    const tasks = store.getPendingTasks(userId);
+    if (tasks.length === 0) {
+        return { userId, tasksProcessed: 0, tasksFailed: 0, durationMs: 0 };
+    }
+    let processed = 0;
+    let failed = 0;
+    // Process l2_scene and l3_persona in FIFO order.
+    // Deduplicate consecutive same-type tasks (e.g., 10 queued l2_scene → run once).
+    let lastTaskType = null;
+    for (const task of tasks) {
+        try {
+            if (task.taskType === lastTaskType) {
+                // Skip duplicate consecutive task of same type — one distillation run is sufficient
+                store.deletePendingTask(task.id);
+                continue;
+            }
+            switch (task.taskType) {
+                case "l2_scene":
+                    await distillScenes({ userId, store, llmRunner: synthesisRunner });
+                    break;
+                case "l3_persona":
+                    await distillPersona({ userId, store, llmRunner: synthesisRunner });
+                    break;
+            }
+            lastTaskType = task.taskType;
+            processed++;
+        }
+        catch (err) {
+            console.error(`[BrainRouter] Flush: task ${task.taskType} failed:`, err.message);
+            failed++;
+        }
+        finally {
+            store.deletePendingTask(task.id);
+        }
+    }
+    return {
+        userId,
+        tasksProcessed: processed,
+        tasksFailed: failed,
+        durationMs: Date.now() - start,
+    };
+}
+// ─── Idle Check ───────────────────────────────────────────────────────────────
+/**
+ * Returns true if the user has been idle long enough that pre-recall flushing
+ * won't noticeably delay the response.
+ */
+export function isUserIdle(store, userId) {
+    const state = store.getSchedulerState(userId);
+    if (!state.lastCaptureAt)
+        return true; // never captured = trivially idle
+    const idleMs = Date.now() - new Date(state.lastCaptureAt).getTime();
+    return idleMs >= IDLE_THRESHOLD_MS;
+}

package/dist/memory/prompts/cognitive-contradiction.d.ts

@@ -0,0 +1 @@
+export declare const COGNITIVE_CONTRADICTION_PROMPT = "\nYou are the Contradiction & Temporal Update Detector for a dual-process cognitive memory engine.\nYour task is to compare a NEWLY EXTRACTED memory with an EXISTING RELEVANT memory and determine if they contradict, supersede, or update each other.\n\nNEW MEMORY:\n\"{{newContent}}\"\n\nEXISTING MEMORY:\n\"{{existingContent}}\"\n\nRULES:\n1. Determine if they overlap or conflict. If there is no overlap/conflict, set \"isContradiction\" to false.\n2. If they conflict or override, classify the relationship into one of two kinds:\n   - \"temporal_update\": The new memory is a deliberate update, change of mind, transition, or correction to the old memory (e.g. \"User lives in SF\" vs \"User moved to NYC\", or \"User wants pnpm\" vs \"User changed package manager to regular npm\"). This means the new memory actively supersedes the old one.\n   - \"genuine_conflict\": The statements are logically incompatible, absolute claims that cannot both be true, and it is NOT a simple update or transition (e.g. \"User was born in 1990\" vs \"User was born in 1995\", or conflicting rules without a clear indication that one was meant to update the other).\n3. Provide a clear reason and a confidence score.\n\nRespond ONLY with a JSON object:\n{\n  \"isContradiction\": boolean,\n  \"kind\": \"temporal_update\" | \"genuine_conflict\" | null,\n  \"reason\": \"Brief explanation if isContradiction is true, else null\",\n  \"confidence\": number (0.0 to 1.0)\n}\n";