@kinqs/brainrouter-mcp-server 0.3.4

package/dist/memory/llm-semaphore.js

@@ -0,0 +1,81 @@
+/**
+ * Global semaphore that caps simultaneous LLM calls leaving this process.
+ *
+ * Why this exists: a single user turn can trigger an avalanche of LLM calls
+ * inside the MCP child — cognitive extraction, contradiction detection (one
+ * per existing record neighbour), graph extraction, focus-shift detection,
+ * plus the 5-min sweeper backfilling old sensory rows. Add the CLI's chat
+ * call hitting the SAME LM Studio endpoint and you can easily fire 10+
+ * concurrent requests at one local GPU. On consumer hardware that triggers
+ * either (a) LM Studio's auto-unload to free VRAM, (b) OOM, or (c) request
+ * queue overflow — all of which surface to BrainRouter as "Model is
+ * unloaded" or 500 errors.
+ *
+ * The fix is to serialize. This module exposes a simple promise-queue
+ * semaphore with a configurable cap. Default is 2: one slot for the
+ * user-facing extraction (foreground), one for opportunistic background
+ * work (graph / contradiction / sweeper). Cloud deployments with a real
+ * API backend (OpenAI, OpenRouter) can crank this up via the env var.
+ *
+ * Env knob:
+ *   BRAINROUTER_LLM_MAX_CONCURRENT  (default 2; values < 1 disable the cap)
+ */
+const DEFAULT_CAP = 2;
+function resolveCap() {
+    const raw = process.env.BRAINROUTER_LLM_MAX_CONCURRENT;
+    if (!raw)
+        return DEFAULT_CAP;
+    const parsed = parseInt(raw, 10);
+    if (!Number.isFinite(parsed) || parsed < 1)
+        return Number.POSITIVE_INFINITY;
+    return parsed;
+}
+let cap = resolveCap();
+let inFlight = 0;
+const waiters = [];
+/**
+ * Acquire one slot. Returns a release function the caller must invoke when
+ * the LLM call finishes (success OR failure). Use it like:
+ *
+ *   const release = await acquireLLMSlot();
+ *   try { ...llm call... } finally { release(); }
+ */
+export async function acquireLLMSlot() {
+    if (!Number.isFinite(cap)) {
+        // Cap disabled — passthrough.
+        return () => { };
+    }
+    if (inFlight < cap) {
+        inFlight++;
+        return makeRelease();
+    }
+    // Otherwise wait in line.
+    await new Promise((resolve) => waiters.push(resolve));
+    inFlight++;
+    return makeRelease();
+}
+function makeRelease() {
+    let released = false;
+    return () => {
+        if (released)
+            return;
+        released = true;
+        inFlight = Math.max(0, inFlight - 1);
+        const next = waiters.shift();
+        if (next)
+            next();
+    };
+}
+/** Exposed for tests / diagnostics. */
+export function getSemaphoreState() {
+    return { cap, inFlight, queued: waiters.length };
+}
+/**
+ * Allow tests (or a future /config tool) to reset the cap and clear waiters
+ * without restarting the process.
+ */
+export function resetSemaphoreForTests() {
+    cap = resolveCap();
+    inFlight = 0;
+    waiters.length = 0;
+}

package/dist/memory/memory-type-config.d.ts

@@ -0,0 +1,11 @@
+import type { MemoryTaskIntent, MemoryType } from "@kinqs/brainrouter-types";
+export interface TypeConfig {
+    halfLifeDays: number | null;
+    defaultConfidence: number;
+    requiresEvidence: boolean;
+    intentAffinity: Partial<Record<MemoryTaskIntent, number>>;
+}
+export declare const TYPE_CONFIGS: Record<MemoryType, TypeConfig>;
+export declare function getMemoryTypeConfig(type: string): TypeConfig;
+export declare function detectTaskIntent(query: string): MemoryTaskIntent;
+export declare function extractFilePathHints(text: string): string[];

package/dist/memory/memory-type-config.js

@@ -0,0 +1,65 @@
+const DEFAULT_TYPE_CONFIG = {
+    halfLifeDays: 30,
+    defaultConfidence: 0.65,
+    requiresEvidence: false,
+    intentAffinity: {},
+};
+export const TYPE_CONFIGS = {
+    persona: { halfLifeDays: 180, defaultConfidence: 0.7, requiresEvidence: false, intentAffinity: {} },
+    episodic: { halfLifeDays: 30, defaultConfidence: 0.65, requiresEvidence: false, intentAffinity: {} },
+    instruction: { halfLifeDays: null, defaultConfidence: 0.85, requiresEvidence: false, intentAffinity: {} },
+    skill_context: { halfLifeDays: 7, defaultConfidence: 0.65, requiresEvidence: false, intentAffinity: {} },
+    tool_preference: { halfLifeDays: 90, defaultConfidence: 0.7, requiresEvidence: false, intentAffinity: { build: 1.05 } },
+    codebase_fact: { halfLifeDays: 60, defaultConfidence: 0.65, requiresEvidence: false, intentAffinity: { build: 1.15, refactor: 1.1 } },
+    api_contract: { halfLifeDays: 90, defaultConfidence: 0.75, requiresEvidence: true, intentAffinity: { review: 1.2, security: 1.15, build: 1.1 } },
+    data_model: { halfLifeDays: 90, defaultConfidence: 0.75, requiresEvidence: true, intentAffinity: { review: 1.2, security: 1.15, build: 1.1 } },
+    dependency_constraint: { halfLifeDays: 120, defaultConfidence: 0.75, requiresEvidence: false, intentAffinity: { build: 1.1, refactor: 1.1 } },
+    environment_constraint: { halfLifeDays: 120, defaultConfidence: 0.75, requiresEvidence: false, intentAffinity: { build: 1.1, debug: 1.1 } },
+    architecture_decision: { halfLifeDays: 180, defaultConfidence: 0.8, requiresEvidence: false, intentAffinity: { build: 1.2, plan: 1.15, refactor: 1.1 } },
+    implementation_decision: { halfLifeDays: 90, defaultConfidence: 0.75, requiresEvidence: false, intentAffinity: { build: 1.2, refactor: 1.1 } },
+    design_constraint: { halfLifeDays: 120, defaultConfidence: 0.75, requiresEvidence: false, intentAffinity: { build: 1.1, review: 1.1 } },
+    security_policy: { halfLifeDays: 180, defaultConfidence: 0.8, requiresEvidence: true, intentAffinity: { security: 1.3, review: 1.2 } },
+    performance_baseline: { halfLifeDays: 45, defaultConfidence: 0.75, requiresEvidence: true, intentAffinity: { performance: 1.3, review: 1.1 } },
+    bug_finding: { halfLifeDays: 45, defaultConfidence: 0.7, requiresEvidence: false, intentAffinity: { debug: 1.3, review: 1.1 } },
+    debug_trace: { halfLifeDays: 30, defaultConfidence: 0.7, requiresEvidence: false, intentAffinity: { debug: 1.3 } },
+    fix_summary: { halfLifeDays: 60, defaultConfidence: 0.75, requiresEvidence: false, intentAffinity: { debug: 1.15, build: 1.1 } },
+    verification_result: { halfLifeDays: 45, defaultConfidence: 0.75, requiresEvidence: false, intentAffinity: { test: 1.25, performance: 1.15, debug: 1.1 } },
+    failed_attempt: { halfLifeDays: 45, defaultConfidence: 0.7, requiresEvidence: false, intentAffinity: { debug: 1.25 } },
+    regression_risk: { halfLifeDays: 90, defaultConfidence: 0.75, requiresEvidence: false, intentAffinity: { review: 1.25, test: 1.15 } },
+    task_state: { halfLifeDays: 14, defaultConfidence: 0.75, requiresEvidence: false, intentAffinity: { plan: 1.3, build: 1.1 } },
+    handover_note: { halfLifeDays: 21, defaultConfidence: 0.75, requiresEvidence: false, intentAffinity: { plan: 1.25, build: 1.1 } },
+    blocked_reason: { halfLifeDays: 21, defaultConfidence: 0.75, requiresEvidence: false, intentAffinity: { plan: 1.2, debug: 1.1 } },
+    review_comment: { halfLifeDays: 45, defaultConfidence: 0.7, requiresEvidence: false, intentAffinity: { review: 1.3 } },
+    release_note: { halfLifeDays: 90, defaultConfidence: 0.7, requiresEvidence: false, intentAffinity: { release: 1.3 } },
+    source_evidence: { halfLifeDays: 120, defaultConfidence: 0.8, requiresEvidence: false, intentAffinity: { review: 1.1, security: 1.1 } },
+    artifact_reference: { halfLifeDays: 90, defaultConfidence: 0.7, requiresEvidence: false, intentAffinity: { plan: 1.1, build: 1.1 } },
+    file_history: { halfLifeDays: 90, defaultConfidence: 0.75, requiresEvidence: false, intentAffinity: { debug: 1.15, refactor: 1.2, review: 1.1 } },
+    command_knowledge: { halfLifeDays: 90, defaultConfidence: 0.75, requiresEvidence: false, intentAffinity: { debug: 1.2, performance: 1.15, test: 1.1 } },
+};
+export function getMemoryTypeConfig(type) {
+    return TYPE_CONFIGS[type] ?? DEFAULT_TYPE_CONFIG;
+}
+export function detectTaskIntent(query) {
+    const q = query.toLowerCase();
+    if (/\b(debug|bug|error|fail|failing|failure|repro|crash|stack|traceback|exception|panic|segfault|undefined|null)\b/.test(q))
+        return "debug";
+    if (/\b(review|audit|risk|regression|pr|pull request|code review|lgtm|approve)\b/.test(q))
+        return "review";
+    if (/\b(test|spec|coverage|vitest|jest|benchmark result|assertion|expect|describe|it\()\b/.test(q))
+        return "test";
+    if (/\b(plan|task|roadmap|todo|handover|blocked|next|sprint|milestone|backlog)\b/.test(q))
+        return "plan";
+    if (/\b(refactor|cleanup|simplify|migration|deprecate|rename|extract|move|reorganize|restructure)\b/.test(q))
+        return "refactor";
+    if (/\b(security|auth|permission|secret|token|vulnerability|xss|injection|csrf|rbac|oauth|jwt|sanitize|escape)\b/.test(q))
+        return "security";
+    if (/\b(performance|latency|throughput|slow|benchmark|r@5|token savings|optimize|cache|memory leak|profil|bottleneck)\b/.test(q))
+        return "performance";
+    if (/\b(release|ship|launch|deploy|changelog|version|tag|publish|hotfix)\b/.test(q))
+        return "release";
+    return "build";
+}
+export function extractFilePathHints(text) {
+    const matches = text.match(/(?:[\w.-]+\/)+[\w.-]+\.\w+|[\w.-]+\.(?:ts|tsx|js|jsx|json|md|sql|py|go|rs)/g) ?? [];
+    return [...new Set(matches.map((m) => m.replace(/^["'`]|["'`]$/g, "")))];
+}

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

@@ -0,0 +1,7 @@
+import type { IMemoryStore } from "@kinqs/brainrouter-types";
+import type { LLMRunner, CognitiveRecord } from "@kinqs/brainrouter-types";
+export declare function detectContradictions(params: {
+    newRecord: CognitiveRecord;
+    store: IMemoryStore;
+    llmRunner: LLMRunner;
+}): Promise<void>;

package/dist/memory/pipeline/cognitive-contradiction.js

@@ -0,0 +1,59 @@
+import { COGNITIVE_CONTRADICTION_PROMPT } from "../prompts/cognitive-contradiction.js";
+import crypto from "node:crypto";
+export async function detectContradictions(params) {
+    const { newRecord, store, llmRunner } = params;
+    // 1. Search for potentially related memories
+    const candidates = store.searchCognitiveFts(newRecord.userId, newRecord.content, 5);
+    const evaluations = [];
+    const _parsedContradictionTimeout = parseInt(process.env.BRAINROUTER_CONTRADICTION_TIMEOUT_MS || "", 10);
+    const contradictionTimeoutMs = isNaN(_parsedContradictionTimeout) ? 60000 : _parsedContradictionTimeout;
+    for (const candidate of candidates) {
+        // Don't compare with self
+        if (candidate.record_id === newRecord.id)
+            continue;
+        const prompt = COGNITIVE_CONTRADICTION_PROMPT
+            .replace("{{newContent}}", newRecord.content)
+            .replace("{{existingContent}}", candidate.content);
+        try {
+            const response = await llmRunner.run({
+                prompt,
+                taskId: `contradiction-check-${newRecord.id}-${candidate.record_id}`,
+                timeoutMs: contradictionTimeoutMs
+            });
+            const jsonMatch = response.match(/\{[\s\S]*\}/);
+            if (!jsonMatch)
+                continue;
+            const data = JSON.parse(jsonMatch[0]);
+            if (data.isContradiction && data.confidence > 0.7) {
+                evaluations.push({
+                    candidate,
+                    isContradiction: true,
+                    confidence: data.confidence,
+                    kind: data.kind || "genuine_conflict",
+                    reason: data.reason
+                });
+            }
+        }
+        catch (e) {
+            console.error(`[BrainRouter] Contradiction check failed for ${newRecord.id} vs ${candidate.record_id}:`, e.message);
+        }
+    }
+    const hasTemporalUpdate = evaluations.some(ev => ev.kind === "temporal_update");
+    for (const ev of evaluations) {
+        if (hasTemporalUpdate) {
+            console.error(`[BrainRouter] TEMPORAL UPDATE DETECTED (transition): Superseding memory ${ev.candidate.record_id} with new memory ${newRecord.id}`);
+            store.invalidateCognitiveRecord(newRecord.userId, ev.candidate.record_id, newRecord.id);
+        }
+        else {
+            console.error(`[BrainRouter] CONTRADICTION DETECTED: ${newRecord.id} vs ${ev.candidate.record_id}`);
+            store.upsertContradiction({
+                id: `conflict_${crypto.randomBytes(4).toString("hex")}`,
+                userId: newRecord.userId,
+                recordIdA: ev.candidate.record_id,
+                recordIdB: newRecord.id,
+                reason: ev.reason,
+                confidence: ev.confidence
+            });
+        }
+    }
+}

package/dist/memory/pipeline/cognitive-dedup.d.ts

@@ -0,0 +1,23 @@
+import type { CognitiveRecord } from "@kinqs/brainrouter-types";
+import type { IMemoryStore } from "@kinqs/brainrouter-types";
+/**
+ * Result of the deduplication process
+ */
+export interface DedupResult {
+    /** Memories that are unique and should be stored */
+    uniqueRecords: CognitiveRecord[];
+    /** Memories that were identified as exact duplicates and dropped */
+    droppedCount: number;
+}
+/**
+ * Proactively deduplicate extracted memories against the existing memory store
+ * before they are stored.
+ *
+ * Uses exact/near-exact string matching to prevent identical noisy facts
+ * from accumulating in the store.
+ */
+export declare function deduplicateMemories(params: {
+    records: CognitiveRecord[];
+    store: IMemoryStore;
+    userId: string;
+}): Promise<DedupResult>;

package/dist/memory/pipeline/cognitive-dedup.js

@@ -0,0 +1,38 @@
+/**
+ * Proactively deduplicate extracted memories against the existing memory store
+ * before they are stored.
+ *
+ * Uses exact/near-exact string matching to prevent identical noisy facts
+ * from accumulating in the store.
+ */
+export async function deduplicateMemories(params) {
+    const { records, store, userId } = params;
+    if (records.length === 0) {
+        return { uniqueRecords: [], droppedCount: 0 };
+    }
+    const uniqueRecords = [];
+    let droppedCount = 0;
+    for (const newRecord of records) {
+        // 1. Keyword search to find potentially identical memories
+        // We only need top 3 to see if there is an exact match
+        const candidates = store.searchCognitiveFts(userId, newRecord.content, 3);
+        let isDuplicate = false;
+        for (const candidate of candidates) {
+            if (candidate.content.trim().toLowerCase() === newRecord.content.trim().toLowerCase()) {
+                isDuplicate = true;
+                break;
+            }
+        }
+        if (isDuplicate) {
+            console.log(`[BrainRouter] Dropped exact duplicate memory: "${newRecord.content}"`);
+            droppedCount++;
+        }
+        else {
+            uniqueRecords.push(newRecord);
+        }
+    }
+    return {
+        uniqueRecords,
+        droppedCount
+    };
+}

package/dist/memory/pipeline/cognitive-extractor.d.ts

@@ -0,0 +1,21 @@
+import type { SensoryRecord, CognitiveRecord, LLMRunner } from "@kinqs/brainrouter-types";
+export interface CognitiveExtractionResult {
+    success: boolean;
+    extractedCount: number;
+    records: CognitiveRecord[];
+    sceneNames: string[];
+    errorMessage?: string;
+}
+export declare function extractCognitiveMemories(params: {
+    messages: SensoryRecord[];
+    userId: string;
+    sessionKey: string;
+    sessionId: string;
+    llmRunner: LLMRunner;
+    maxMessagesPerExtraction?: number;
+    maxBackgroundMessages?: number;
+    previousSceneName?: string;
+    existingSceneNames?: string[];
+    activeSkill?: string;
+    skillHints?: string;
+}): Promise<CognitiveExtractionResult>;

package/dist/memory/pipeline/cognitive-extractor.js

@@ -0,0 +1,183 @@
+import { EXTRACT_MEMORIES_SYSTEM_PROMPT, formatExtractionPrompt } from "../prompts/cognitive-extraction.js";
+import { getMemoryTypeConfig } from "../memory-type-config.js";
+import crypto from "node:crypto";
+const ALLOWED_MEMORY_TYPES = new Set([
+    "persona", "episodic", "instruction", "skill_context", "tool_preference",
+    "codebase_fact", "api_contract", "data_model", "dependency_constraint",
+    "environment_constraint", "architecture_decision", "implementation_decision",
+    "design_constraint", "security_policy", "performance_baseline", "bug_finding",
+    "debug_trace", "fix_summary", "verification_result", "failed_attempt",
+    "regression_risk", "task_state", "handover_note", "blocked_reason",
+    "review_comment", "release_note", "source_evidence", "artifact_reference",
+    "file_history", "command_knowledge",
+]);
+const ALLOWED_SOURCE_KINDS = new Set([
+    "", "user_instruction", "source_file", "command_output", "test_result",
+    "model_inference", "prior_memory",
+]);
+const ALLOWED_VERIFICATION_STATUSES = new Set([
+    "", "verified", "unverified", "stale",
+]);
+function shouldExtractCognitive(text) {
+    if (!text)
+        return false;
+    const clean = text.trim();
+    if (clean.length < 3)
+        return false;
+    if (/^[^a-zA-Z\u4e00-\u9fa5]+$/.test(clean))
+        return false;
+    return true;
+}
+export async function extractCognitiveMemories(params) {
+    const { messages, userId, sessionKey, sessionId, llmRunner, maxMessagesPerExtraction = 10, maxBackgroundMessages = 5, previousSceneName, existingSceneNames, activeSkill, skillHints } = params;
+    if (messages.length === 0) {
+        return { success: true, extractedCount: 0, records: [], sceneNames: [] };
+    }
+    const qualifiedMessages = messages.filter((m) => shouldExtractCognitive(m.messageText));
+    if (qualifiedMessages.length === 0) {
+        return { success: true, extractedCount: 0, records: [], sceneNames: [] };
+    }
+    const newMessages = qualifiedMessages.slice(-maxMessagesPerExtraction);
+    const bgEndIdx = qualifiedMessages.length - newMessages.length;
+    const backgroundMessages = bgEndIdx > 0
+        ? qualifiedMessages.slice(Math.max(0, bgEndIdx - maxBackgroundMessages), bgEndIdx)
+        : [];
+    const userPrompt = formatExtractionPrompt({
+        newMessages,
+        backgroundMessages,
+        previousSceneName,
+        existingSceneNames,
+        activeSkill,
+        skillHints
+    });
+    let rawResult;
+    try {
+        rawResult = await llmRunner.run({
+            prompt: userPrompt,
+            systemPrompt: EXTRACT_MEMORIES_SYSTEM_PROMPT,
+            taskId: "cognitive-extraction",
+            timeoutMs: 120_000
+        });
+    }
+    catch (err) {
+        const errorMessage = err instanceof Error ? err.message : String(err);
+        const code = err?.code;
+        if (code === "LLM_NOT_CONFIGURED") {
+            // Expected, non-fatal: no LLM is configured server-side. Skip cognitive
+            // extraction silently; sensory records are still persisted by the caller.
+            return { success: false, extractedCount: 0, records: [], sceneNames: [], errorMessage: "LLM not configured; cognitive extraction skipped." };
+        }
+        console.error("[BrainRouter] LLM extraction failed:", err);
+        return { success: false, extractedCount: 0, records: [], sceneNames: [], errorMessage };
+    }
+    const parsedScenes = parseExtractionResult(rawResult);
+    const records = [];
+    const sceneNames = [];
+    const nowStr = new Date().toISOString();
+    for (const scene of parsedScenes) {
+        sceneNames.push(scene.scene_name);
+        for (const mem of scene.memories) {
+            const config = getMemoryTypeConfig(mem.type);
+            records.push({
+                id: `cognitive_${sessionKey}_${Date.now()}_${crypto.randomBytes(4).toString("hex")}`,
+                userId,
+                sessionKey,
+                sessionId,
+                content: mem.content,
+                type: mem.type,
+                priority: mem.priority,
+                sceneName: scene.scene_name,
+                skillTag: mem.skill_tag || activeSkill || "",
+                halfLifeDays: config.halfLifeDays,
+                supersededBy: null,
+                timestampStr: "",
+                timestampStart: "",
+                timestampEnd: "",
+                createdTime: nowStr,
+                updatedTime: nowStr,
+                metadata: mem.metadata,
+                confidence: mem.confidence ?? config.defaultConfidence,
+                status: "active",
+                sourceKind: mem.sourceKind,
+                verificationStatus: mem.verificationStatus,
+                repoPaths: mem.repoPaths,
+                filePaths: mem.filePaths,
+                commands: mem.commands,
+                citationCount: 0,
+                lastCitedAt: null,
+                neverCitedCount: 0,
+                archived: false,
+            });
+        }
+    }
+    return {
+        success: true,
+        extractedCount: records.length,
+        records,
+        sceneNames
+    };
+}
+function parseExtractionResult(raw) {
+    try {
+        let cleaned = raw.trim();
+        if (cleaned.startsWith("\`\`\`")) {
+            cleaned = cleaned.replace(/^\`\`\`(?:json)?\s*\n?/, "").replace(/\n?\`\`\`\s*$/, "");
+        }
+        const match = cleaned.match(/\[[\s\S]*\]/);
+        if (!match)
+            return [];
+        const parsed = JSON.parse(match[0]);
+        if (!Array.isArray(parsed))
+            return [];
+        const scenes = [];
+        for (const item of parsed) {
+            if (!item || typeof item !== "object")
+                continue;
+            const s = item;
+            const memories = Array.isArray(s.memories) ? s.memories.map((m) => ({
+                content: String(m.content || ""),
+                type: parseMemoryType(m.type),
+                priority: clampNumber(m.priority, 0, 100, 50),
+                skill_tag: m.skill_tag ? String(m.skill_tag) : undefined,
+                confidence: typeof m.confidence === "number" ? clampNumber(m.confidence, 0, 1, 0.65) : undefined,
+                sourceKind: parseSourceKind(m.sourceKind ?? m.source_kind),
+                verificationStatus: parseVerificationStatus(m.verificationStatus ?? m.verification_status),
+                repoPaths: parseStringArray(m.repoPaths ?? m.repo_paths),
+                filePaths: parseStringArray(m.filePaths ?? m.file_paths),
+                commands: parseStringArray(m.commands),
+                metadata: m.metadata && typeof m.metadata === "object" ? m.metadata : {}
+            })).filter((m) => m.content.length > 0) : [];
+            scenes.push({
+                scene_name: String(s.scene_name || "Unknown Focus Scene"),
+                memories
+            });
+        }
+        return scenes;
+    }
+    catch (err) {
+        console.error("[BrainRouter] Failed to parse extraction result", err);
+        return [];
+    }
+}
+function parseMemoryType(value) {
+    const candidate = String(value || "");
+    return ALLOWED_MEMORY_TYPES.has(candidate) ? candidate : "episodic";
+}
+function parseSourceKind(value) {
+    const candidate = String(value || "");
+    return ALLOWED_SOURCE_KINDS.has(candidate) ? candidate : "model_inference";
+}
+function parseVerificationStatus(value) {
+    const candidate = String(value || "");
+    return ALLOWED_VERIFICATION_STATUSES.has(candidate) ? candidate : "unverified";
+}
+function parseStringArray(value) {
+    if (!Array.isArray(value))
+        return [];
+    return [...new Set(value.map((item) => String(item).trim()).filter(Boolean))];
+}
+function clampNumber(value, min, max, fallback) {
+    return typeof value === "number" && Number.isFinite(value)
+        ? Math.min(max, Math.max(min, value))
+        : fallback;
+}

package/dist/memory/pipeline/contextual-focus-builder.d.ts

@@ -0,0 +1,13 @@
+import type { IMemoryStore } from "@kinqs/brainrouter-types";
+import type { LLMRunner } from "@kinqs/brainrouter-types";
+/**
+ * Distills and updates Focus Scenes by grouping CognitiveRecords.
+ */
+export declare function distillFocusScenes(params: {
+    userId: string;
+    store: IMemoryStore;
+    llmRunner: LLMRunner;
+}): Promise<{
+    focusDistilled: number;
+    sceneNames: string[];
+}>;

package/dist/memory/pipeline/contextual-focus-builder.js

@@ -0,0 +1,135 @@
+import { FOCUS_SCENE_SYSTEM_PROMPT, formatFocusScenePrompt } from "../prompts/focus-scene.js";
+import { FOCUS_SCENE_CLUSTER_SYSTEM_PROMPT, formatFocusSceneClusterPrompt } from "../prompts/focus-scene-cluster.js";
+import { MAX_FOCUS_SCENES } from "../scheduler.js";
+import crypto from "node:crypto";
+async function canonicalizeFocusNames(params) {
+    const { userId, store, llmRunner } = params;
+    const sceneNames = store.getDistinctSceneNames(userId);
+    if (sceneNames.length < 2)
+        return;
+    try {
+        const rawCluster = await llmRunner.run({
+            prompt: formatFocusSceneClusterPrompt(sceneNames),
+            systemPrompt: FOCUS_SCENE_CLUSTER_SYSTEM_PROMPT,
+            taskId: "focus-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.renameFocusInCognitiveRecords(userId, alias, canonical);
+            }
+        }
+    }
+    catch (err) {
+        console.error(`[BrainRouter] Focus scene canonicalization failed for "${userId}":`, err.message);
+    }
+}
+/**
+ * Distills and updates Focus Scenes by grouping CognitiveRecords.
+ */
+export async function distillFocusScenes(params) {
+    const { userId, store, llmRunner } = params;
+    // Run scene canonicalization/clustering pass to prevent cold-start fragmentation
+    await canonicalizeFocusNames({ userId, store, llmRunner });
+    // Decay all existing heat scores (each distillation cycle = time passing)
+    store.decayContextualFocusHeatScores(userId);
+    const sceneNames = store.getDistinctSceneNames(userId);
+    if (sceneNames.length === 0) {
+        return { focusDistilled: 0, sceneNames: [] };
+    }
+    const now = new Date().toISOString();
+    const distilled = [];
+    // Fetch existing focus scenes up-front so the prompt can avoid near-duplicates
+    const existingFocusNames = store.getTopContextualFocus(userId, 50).map(s => s.sceneName);
+    for (const sceneName of sceneNames) {
+        const cognitives = store.getCognitivesByFocus(userId, sceneName, 30);
+        if (cognitives.length === 0)
+            continue;
+        let summaryMd;
+        try {
+            summaryMd = await llmRunner.run({
+                prompt: formatFocusScenePrompt(sceneName, cognitives, existingFocusNames.filter(n => n !== sceneName)),
+                systemPrompt: FOCUS_SCENE_SYSTEM_PROMPT,
+                taskId: "focus-scene-distillation",
+                timeoutMs: 60_000,
+            });
+        }
+        catch (err) {
+            console.error(`[BrainRouter] Focus scene distillation failed for "${sceneName}":`, err.message);
+            continue;
+        }
+        const existing = store.getContextualFocusByName(userId, sceneName);
+        const record = {
+            id: existing?.id ?? `focus_${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.upsertContextualFocus(record);
+        distilled.push(sceneName);
+    }
+    // Auto-merge cold scenes if we exceed the max threshold
+    await mergeFocusScenes({ userId, store, llmRunner });
+    console.error(`[BrainRouter] Distilled ${distilled.length} focus scene(s) for user "${userId}".`);
+    return { focusDistilled: distilled.length, sceneNames: distilled };
+}
+async function mergeFocusScenes(params) {
+    const { userId, store, llmRunner } = params;
+    const focusCount = store.getContextualFocusCount(userId);
+    if (focusCount < MAX_FOCUS_SCENES)
+        return;
+    const overflow = focusCount - MAX_FOCUS_SCENES + 1;
+    const coldScenes = store.getColdContextualFocus(userId, overflow + 3);
+    if (coldScenes.length < 2)
+        return;
+    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 focus scene summaries into a single concise "Archived Focus Scenes" overview.\n\n${sceneSummaries}\n\nOutput only the Markdown summary. Be concise — no preamble.`,
+            systemPrompt: FOCUS_SCENE_SYSTEM_PROMPT,
+            taskId: "focus-scene-merge",
+            timeoutMs: 60_000,
+        });
+    }
+    catch (err) {
+        console.error(`[BrainRouter] Focus scene merge failed for "${userId}":`, err.message);
+        return;
+    }
+    const now = new Date().toISOString();
+    const existingArchive = store.getContextualFocusByName(userId, archiveSceneName);
+    const record = {
+        id: existingArchive?.id ?? `focus_${crypto.randomBytes(6).toString("hex")}`,
+        userId,
+        sceneName: archiveSceneName,
+        summaryMd: unifiedSummary.trim(),
+        heatScore: 10,
+        lastActiveTime: now,
+        createdTime: existingArchive?.createdTime ?? now,
+        updatedTime: now,
+    };
+    store.upsertContextualFocus(record);
+    const idsToDelete = scenesToMerge.map(s => s.id);
+    store.deleteContextualFocus(userId, idsToDelete);
+    console.error(`[BrainRouter] Focus auto-merge: merged ${idsToDelete.length} cold focus scenes into "${archiveSceneName}".`);
+}

package/dist/memory/pipeline/focus-direction-shift.d.ts

@@ -0,0 +1,10 @@
+import type { CognitiveRecord, ContextualFocusRecord, LLMRunner } from "@kinqs/brainrouter-types";
+export declare function detectFocusShift(params: {
+    activeScene: ContextualFocusRecord;
+    newCognitiveRecords: CognitiveRecord[];
+    llmRunner: LLMRunner;
+}): Promise<{
+    shift: boolean;
+    confidence: number;
+    reason: string;
+}>;