@kinqs/brainrouter-mcp-server 0.3.4 → 0.3.6

package/dist/index.js

@@ -14,6 +14,17 @@
 //     Runs an Express HTTP server. Connect via serverUrl in tool config.
 //     Usage: node dist/index.js --root /path/to/project --http --port 3747
 //
+//   init subcommand
+//     Scaffold ~/.config/brainrouter/server.env from the bundled
+//     .env.example and exit. Run this once after a global install.
+//     Usage: brainrouter-mcp init
+//
+// CRITICAL: import order matters. `init` may exit the process before
+// anything else loads (for `brainrouter-mcp init`). `env-loader` runs next
+// and sets process.env from the right .env file before any module body
+// reads env vars (sqlite/embedding/extractor all do at load time).
+import './init.js';
+import './env-loader.js';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
@@ -91,7 +102,7 @@ const PORT = parseInt(parseFlag('--port') ?? '3747', 10);
 function buildMcpServer(registry, options) {
     const defaultUserId = options?.defaultUserId ?? STDIO_DEFAULT_USER_ID;
     const isAdmin = options?.isAdmin ?? false;
-    const server = new Server({ name: 'brainrouter-mcp-server', version: '0.3.4' }, { capabilities: { tools: {} } });
+    const server = new Server({ name: 'brainrouter-mcp-server', version: '0.3.5' }, { capabilities: { tools: {} } });
     // ── Tool list ──────────────────────────────────────────────────────────────
     server.setRequestHandler(ListToolsRequestSchema, async () => ({
         tools: [

package/dist/init.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/init.js

@@ -0,0 +1,64 @@
+// Side-effect module: imported FIRST in src/index.ts (before env-loader).
+//
+// Handles the `brainrouter-mcp init` subcommand by scaffolding a user-editable
+// .env file at ~/.config/brainrouter/server.env from the package's bundled
+// .env.example, then exiting. Never returns control when invoked.
+//
+// This solves the global-install UX gap: a user who runs
+// `npm install -g @kinqs/brainrouter-mcp-server` has no obvious place to put
+// their LLM credentials. `brainrouter-mcp init` creates the file in a known
+// user-writable location that env-loader.ts then auto-finds.
+//
+// If the file already exists, init prints the path so the user knows where
+// to edit it — but does NOT overwrite (don't clobber a user's real config).
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import url from 'node:url';
+function runInit() {
+    const userConfigDir = path.join(os.homedir(), '.config', 'brainrouter');
+    const userEnvFile = path.join(userConfigDir, 'server.env');
+    // .env.example sits at the package root (one level above src/ in source,
+    // one level above dist/ after build, both layouts work in the installed
+    // tarball because the `files` allowlist in package.json includes it).
+    const here = path.dirname(url.fileURLToPath(import.meta.url));
+    const exampleCandidates = [
+        path.resolve(here, '..', '.env.example'), // dist/init.js → ../.env.example
+        path.resolve(here, '..', '..', '.env.example'), // src/init.ts (dev) → ../../.env.example
+    ];
+    const examplePath = exampleCandidates.find((p) => fs.existsSync(p));
+    if (!examplePath) {
+        process.stderr.write(`init: couldn't find .env.example bundled with the package.\n` +
+            `Checked:\n${exampleCandidates.map((p) => `  ${p}`).join('\n')}\n` +
+            `This is a packaging bug — please file an issue at ` +
+            `https://github.com/kinqsradiollc/BrainRouter/issues\n`);
+        process.exit(1);
+    }
+    if (fs.existsSync(userEnvFile)) {
+        process.stdout.write(`init: ${userEnvFile} already exists — not overwriting.\n` +
+            `Edit it with: $EDITOR ${userEnvFile}\n` +
+            `(Or compare against the latest template at ${examplePath})\n`);
+        process.exit(0);
+    }
+    fs.mkdirSync(userConfigDir, { recursive: true });
+    fs.copyFileSync(examplePath, userEnvFile);
+    // Tighten perms — this file will hold API keys + a JWT secret.
+    try {
+        fs.chmodSync(userEnvFile, 0o600);
+    }
+    catch { /* best effort */ }
+    process.stdout.write(`init: created ${userEnvFile}\n` +
+        `\n` +
+        `Next steps:\n` +
+        `  1. Edit it:                 $EDITOR ${userEnvFile}\n` +
+        `  2. Set BRAINROUTER_LLM_API_KEY (required for cognitive extraction)\n` +
+        `  3. Change BRAINROUTER_ADMIN_PASSWORD and BRAINROUTER_JWT_SECRET\n` +
+        `  4. Start the server:        brainrouter-mcp --http --port 3747\n` +
+        `\n` +
+        `The server auto-finds this file via ~/.config/brainrouter/server.env\n` +
+        `(or set BRAINROUTER_ENV_FILE=/some/other/path to override).\n`);
+    process.exit(0);
+}
+if (process.argv.includes('init')) {
+    runInit();
+}

package/dist/memory/engine.js

@@ -3,6 +3,7 @@ import { MemoryCapturePipeline } from "./capture.js";
 import { MemoryRecallPipeline } from "./recall.js";
 import { EmbeddingService } from "./store/embedding.js";
 import { RerankerService } from "./store/reranker.js";
+import { RelevanceJudgeService } from "./store/relevance-judge.js";
 import { scanSkillsForHints } from "./skill-hints-loader.js";
 import { distillFocusScenes } from "./pipeline/contextual-focus-builder.js";
 import { distillCoreIdentity } from "./pipeline/identity-distiller.js";
@@ -172,6 +173,25 @@ export class MemoryEngine {
                 ? parseInt(process.env.BRAINROUTER_RERANKER_TOP_N, 10)
                 : undefined,
         });
+        // Relevance judge sits behind a flag (off by default) — opt in with
+        // BRAINROUTER_RELEVANCE_JUDGE_ENABLED=true. Falls back to the shared
+        // BRAINROUTER_LLM_* settings unless explicitly overridden so a single
+        // LLM credential covers extraction, synthesis, and judging.
+        const relevanceJudge = new RelevanceJudgeService({
+            enabled: process.env.BRAINROUTER_RELEVANCE_JUDGE_ENABLED === "true",
+            endpoint: process.env.BRAINROUTER_RELEVANCE_JUDGE_ENDPOINT
+                ?? process.env.BRAINROUTER_LLM_ENDPOINT,
+            apiKey: process.env.BRAINROUTER_RELEVANCE_JUDGE_API_KEY
+                ?? process.env.BRAINROUTER_LLM_API_KEY,
+            model: process.env.BRAINROUTER_RELEVANCE_JUDGE_MODEL
+                ?? process.env.BRAINROUTER_LLM_MODEL,
+            maxCandidates: process.env.BRAINROUTER_RELEVANCE_JUDGE_MAX_CANDIDATES
+                ? parseInt(process.env.BRAINROUTER_RELEVANCE_JUDGE_MAX_CANDIDATES, 10)
+                : undefined,
+            timeoutMs: process.env.BRAINROUTER_RELEVANCE_JUDGE_TIMEOUT_MS
+                ? parseInt(process.env.BRAINROUTER_RELEVANCE_JUDGE_TIMEOUT_MS, 10)
+                : undefined,
+        });
         this.store.initVec(embeddingService.getDimensions());
         if (embeddingService.isReady()) {
             void this.store.reembedStaleRecords((text) => embeddingService.embed(text)).then((count) => {
@@ -183,7 +203,7 @@ export class MemoryEngine {
             });
         }
         this.capturePipeline = new MemoryCapturePipeline(this.store, this.extractionRunner, embeddingService, 1);
-        this.recallPipeline = new MemoryRecallPipeline(this.store, embeddingService, rerankerService);
+        this.recallPipeline = new MemoryRecallPipeline(this.store, embeddingService, rerankerService, relevanceJudge);
         this.startExtractionSweeper();
     }
     async ensureSeedAdminUser() {

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

@@ -126,7 +126,7 @@ function parseExtractionResult(raw) {
         const match = cleaned.match(/\[[\s\S]*\]/);
         if (!match)
             return [];
-        const parsed = JSON.parse(match[0]);
+        const parsed = parseJsonWithEscapeRepair(match[0]);
         if (!Array.isArray(parsed))
             return [];
         const scenes = [];
@@ -159,6 +159,24 @@ function parseExtractionResult(raw) {
         return [];
     }
 }
+// LLMs frequently emit JSON where string values contain backslashes that
+// aren't valid JSON escapes — Windows paths (\users), regex literals,
+// LaTeX (\section), or shell snippets. JSON.parse rejects the entire
+// payload on the first bad escape, so we'd drop an otherwise-good batch
+// of memories over one stray backslash. Once the first parse has failed,
+// preserve ambiguous backslashes literally; otherwise valid JSON escapes
+// like \b, \f, \n, \r, \t, or \uXXXX can silently corrupt paths.
+function parseJsonWithEscapeRepair(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        if (!(err instanceof SyntaxError))
+            throw err;
+        const repaired = raw.replace(/\\(?!["\\\/])/g, "\\\\");
+        return JSON.parse(repaired);
+    }
+}
 function parseMemoryType(value) {
     const candidate = String(value || "");
     return ALLOWED_MEMORY_TYPES.has(candidate) ? candidate : "episodic";

package/dist/memory/recall.d.ts

@@ -2,6 +2,7 @@ import type { IMemoryStore } from "@kinqs/brainrouter-types";
 import type { RecallResult } from "@kinqs/brainrouter-types";
 import type { EmbeddingService } from "./store/embedding.js";
 import type { RerankerService } from "./store/reranker.js";
+import type { RelevanceJudgeService } from "./store/relevance-judge.js";
 /**
  * Optional filters applied to the candidate pool after RRF but before
  * neural-spark propagation and reranking. Filters never *add* records — they
@@ -27,7 +28,8 @@ export declare class MemoryRecallPipeline {
     private store;
     private embeddingService;
     private rerankerService;
-    constructor(store: IMemoryStore, embeddingService: EmbeddingService, rerankerService: RerankerService);
+    private relevanceJudge?;
+    constructor(store: IMemoryStore, embeddingService: EmbeddingService, rerankerService: RerankerService, relevanceJudge?: RelevanceJudgeService | undefined);
     recall(params: {
         userId: string;
         sessionKey: string;

package/dist/memory/recall.js

@@ -51,10 +51,12 @@ export class MemoryRecallPipeline {
     store;
     embeddingService;
     rerankerService;
-    constructor(store, embeddingService, rerankerService) {
+    relevanceJudge;
+    constructor(store, embeddingService, rerankerService, relevanceJudge) {
         this.store = store;
         this.embeddingService = embeddingService;
         this.rerankerService = rerankerService;
+        this.relevanceJudge = relevanceJudge;
     }
     async recall(params) {
         const startTime = Date.now();
@@ -270,6 +272,35 @@ export class MemoryRecallPipeline {
                 console.error("[BrainRouter] Reranker failed during recall, falling back to RRF:", e.message);
             }
         }
+        // Stage 4 — LLM Relevance Judge (semantic approve/reject gate)
+        //
+        // The reranker orders candidates by a learned relevance score but never
+        // *filters* — so a memory that shares vocabulary with the query but is
+        // about a different subject still makes the cut. The judge fixes that by
+        // asking a fast LLM "is each of these actually relevant?" and dropping
+        // the rejects. On any failure we keep the reranker output unchanged so a
+        // flaky judge call never breaks recall.
+        let judgeUsed = false;
+        let judgeApproved = 0;
+        let judgeRejected = 0;
+        let judgeVerdicts;
+        if (this.relevanceJudge?.isReady() && topResults.length > 0) {
+            try {
+                const judgeCandidates = topResults.map(r => ({
+                    id: r.record.record_id,
+                    content: r.record.content,
+                }));
+                const judgeResult = await this.relevanceJudge.judge({ query, candidates: judgeCandidates });
+                judgeUsed = true;
+                judgeVerdicts = judgeResult.verdicts;
+                judgeApproved = judgeResult.approvedIndices.length;
+                judgeRejected = topResults.length - judgeApproved;
+                topResults = judgeResult.approvedIndices.map((i) => topResults[i]);
+            }
+            catch (e) {
+                console.error("[BrainRouter] Relevance judge failed during recall, keeping reranker output:", e.message);
+            }
+        }
         // 5. Format for context
         const memoryLines = topResults.map(({ record }) => {
             const tag = record.scene_name ? `${record.type}|${record.scene_name}` : record.type;
@@ -279,7 +310,13 @@ export class MemoryRecallPipeline {
             }
             return line;
         });
-        const prependContext = `<relevant-memories>\n  The following memories are relevant to this query. Reference only if helpful:\n\n  ${memoryLines.join("\n  ")}\n</relevant-memories>`;
+        // If the judge rejected everything, skip the prepend block entirely —
+        // an empty <relevant-memories> tag is worse than no tag because it
+        // implies "we looked and nothing helped," which the agent should infer
+        // from the absence of the block.
+        const prependContext = memoryLines.length > 0
+            ? `<relevant-memories>\n  The following memories are relevant to this query. Reference only if helpful:\n\n  ${memoryLines.join("\n  ")}\n</relevant-memories>`
+            : undefined;
         // Build appendSystemContext with Contextual Focus Navigation + tools guide
         const topScenes = this.store.getTopContextualFocus(userId, 3);
         let appendSystemContext = "";
@@ -329,9 +366,10 @@ export class MemoryRecallPipeline {
             recordId: r.record.record_id,
             skillTag: r.record.skill_tag
         }));
-        const recallStrategy = vecResults.length > 0
+        const baseStrategy = vecResults.length > 0
             ? (usedReranker ? "hybrid+rerank" : "hybrid")
             : (usedReranker ? "keyword+rerank" : (filePathResults.length > 0 ? "keyword+file" : "keyword"));
+        const recallStrategy = judgeUsed ? `${baseStrategy}+judge` : baseStrategy;
         const durationMs = Date.now() - startTime;
         const recallExplanation = {
             ftsHits: ftsResults.length,
@@ -342,6 +380,10 @@ export class MemoryRecallPipeline {
             typeBoosts,
             skillBoostApplied,
             rerankerUsed: usedReranker,
+            judgeUsed,
+            judgeApproved,
+            judgeRejected,
+            judgeVerdicts,
             graphExpansion: hasGraphExpansion,
             citationBoosts,
             durationMs,
@@ -388,6 +430,9 @@ export class MemoryRecallPipeline {
                     vecHits: explanation?.vecHits ?? 0,
                     intentDetected: explanation?.intentDetected ?? "none",
                     rerankerUsed: explanation?.rerankerUsed ?? false,
+                    judgeUsed: explanation?.judgeUsed ?? false,
+                    judgeApproved: explanation?.judgeApproved ?? 0,
+                    judgeRejected: explanation?.judgeRejected ?? 0,
                 },
             });
         }

package/dist/memory/store/relevance-judge.d.ts

@@ -0,0 +1,51 @@
+import type { RelevanceJudgeServiceConfig, RelevanceVerdict } from "@kinqs/brainrouter-types";
+export interface JudgeCandidate {
+    /** Stable id used for logging — typically the memory's record_id. */
+    id: string;
+    /** Memory content the judge will read. */
+    content: string;
+}
+export interface JudgeResult {
+    /** Verdicts in the order returned by the judge. */
+    verdicts: RelevanceVerdict[];
+    /** Indices the judge approved as relevant. */
+    approvedIndices: number[];
+}
+/**
+ * LLM-as-judge stage that approves or rejects retrieved memories based on
+ * actual semantic relevance to the user query — sits between the reranker and
+ * context formatting, dropping candidates that share keywords but aren't
+ * genuinely about the query subject.
+ *
+ * Failure mode is "skip the gate": if the call errors out, callers fall back
+ * to the unfiltered reranker output. We never want a flaky judge call to
+ * crash a recall.
+ */
+export declare class RelevanceJudgeService {
+    private readonly enabled;
+    private readonly endpoint;
+    private readonly apiKey;
+    private readonly model;
+    private readonly maxCandidates;
+    private readonly timeoutMs;
+    private readonly ready;
+    constructor(config: RelevanceJudgeServiceConfig);
+    isReady(): boolean;
+    getMaxCandidates(): number;
+    /**
+     * Grade a batch of candidates against the query. Returns verdicts and the
+     * subset of indices approved as relevant. Throws on transport/parsing
+     * failure — callers are expected to fall back to pre-judge results.
+     */
+    judge(params: {
+        query: string;
+        candidates: JudgeCandidate[];
+    }): Promise<JudgeResult>;
+    /**
+     * Defensive JSON parse — strips code fences, picks the first valid JSON
+     * object/array, and tolerates either {"verdicts":[…]} or a bare array.
+     * Returns one verdict per candidate; missing entries default to "rejected"
+     * so a malformed response can't silently approve everything.
+     */
+    private parseVerdicts;
+}

package/dist/memory/store/relevance-judge.js

@@ -0,0 +1,196 @@
+import { fetchWithExternalRetry } from "../retry.js";
+import { acquireLLMSlot } from "../llm-semaphore.js";
+/**
+ * LLM-as-judge stage that approves or rejects retrieved memories based on
+ * actual semantic relevance to the user query — sits between the reranker and
+ * context formatting, dropping candidates that share keywords but aren't
+ * genuinely about the query subject.
+ *
+ * Failure mode is "skip the gate": if the call errors out, callers fall back
+ * to the unfiltered reranker output. We never want a flaky judge call to
+ * crash a recall.
+ */
+export class RelevanceJudgeService {
+    enabled;
+    endpoint;
+    apiKey;
+    model;
+    maxCandidates;
+    timeoutMs;
+    ready;
+    constructor(config) {
+        this.enabled = config.enabled ?? false;
+        this.endpoint = config.endpoint ?? "https://api.openai.com/v1/chat/completions";
+        this.apiKey = config.apiKey ?? "";
+        this.model = config.model ?? "gpt-4o-mini";
+        this.maxCandidates = Math.max(1, config.maxCandidates ?? 10);
+        this.timeoutMs = Math.max(1000, config.timeoutMs ?? 15_000);
+        this.ready = this.enabled && !!this.apiKey;
+        if (this.enabled && !this.apiKey) {
+            console.error("[BrainRouter] Relevance judge enabled but no API key set. Stage 4 judging will be skipped.");
+        }
+    }
+    isReady() {
+        return this.ready;
+    }
+    getMaxCandidates() {
+        return this.maxCandidates;
+    }
+    /**
+     * Grade a batch of candidates against the query. Returns verdicts and the
+     * subset of indices approved as relevant. Throws on transport/parsing
+     * failure — callers are expected to fall back to pre-judge results.
+     */
+    async judge(params) {
+        if (!this.ready) {
+            throw new Error("RelevanceJudgeService is not ready (disabled or missing API key)");
+        }
+        if (params.candidates.length === 0) {
+            return { verdicts: [], approvedIndices: [] };
+        }
+        const candidates = params.candidates.slice(0, this.maxCandidates);
+        const safeQuery = params.query.length > 800 ? params.query.slice(0, 800) + "…" : params.query;
+        const candidateBlock = candidates
+            .map((c, i) => {
+            const text = c.content.length > 600 ? c.content.slice(0, 600) + "…" : c.content;
+            return `[${i}] ${text.replace(/\s+/g, " ").trim()}`;
+        })
+            .join("\n");
+        const systemPrompt = [
+            "You are a strict relevance judge for a memory retrieval system.",
+            "For each candidate memory, decide whether it is actually relevant to the user's query.",
+            "A memory is RELEVANT only if it provides information that directly helps answer, contextualize, or inform the query.",
+            "It is NOT relevant if it merely shares keywords, is about a different subject, or is generic background.",
+            "When in doubt, reject — false positives pollute the agent's context window.",
+            "Respond with strict JSON only, no prose.",
+        ].join(" ");
+        const userPrompt = [
+            `Query: ${safeQuery}`,
+            "",
+            "Candidates:",
+            candidateBlock,
+            "",
+            "Respond with exactly this JSON shape:",
+            `{"verdicts":[{"index":0,"relevant":true,"reason":"…"}, …]}`,
+            "Include one verdict per candidate. Keep each reason under 120 chars.",
+        ].join("\n");
+        const doFetch = () => fetchWithExternalRetry(this.endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": `Bearer ${this.apiKey}`,
+            },
+            // Deliberately omitting `response_format` — OpenAI accepts
+            // `{type:"json_object"}`, but LM Studio / llama.cpp-style backends
+            // reject anything except `json_schema` or `text` with a 400, and
+            // Ollama / vLLM each have their own quirks. The system prompt is
+            // explicit about strict-JSON output and the parser below strips
+            // code fences + tolerates surrounding prose, so dropping the hint
+            // is cheaper than per-provider branching.
+            body: JSON.stringify({
+                model: this.model,
+                messages: [
+                    { role: "system", content: systemPrompt },
+                    { role: "user", content: userPrompt },
+                ],
+                temperature: 0,
+            }),
+            signal: AbortSignal.timeout(this.timeoutMs),
+        }, {
+            label: "Relevance Judge API",
+        });
+        const release = await acquireLLMSlot();
+        let raw;
+        try {
+            let res = await doFetch();
+            // LM Studio quirk: idle models auto-unload and the first call after
+            // unload returns 400 with "Model is unloaded" / "No models loaded".
+            // The backend then loads the model in the background, so a retry
+            // ~1.5s later usually succeeds. Mirrors ModelLLMRunner in engine.ts.
+            if (res.status === 400) {
+                const errorBody = await res.text();
+                if (/model\s+(is\s+)?unloaded|model\s+not\s+loaded|no\s+models?\s+loaded/i.test(errorBody)) {
+                    await new Promise((resolve) => setTimeout(resolve, 1500));
+                    res = await doFetch();
+                    if (!res.ok) {
+                        const retryBody = await res.text().catch(() => "(no body)");
+                        throw new Error(`Relevance Judge API failed after LM Studio reload retry: HTTP ${res.status} ${res.statusText} - ${retryBody}`);
+                    }
+                }
+                else {
+                    throw new Error(`Relevance Judge API failed: HTTP ${res.status} ${res.statusText} - ${errorBody}`);
+                }
+            }
+            else if (!res.ok) {
+                const err = await res.text().catch(() => "(no body)");
+                throw new Error(`Relevance Judge API failed: HTTP ${res.status} ${res.statusText} - ${err}`);
+            }
+            const data = await res.json();
+            if (data?.error) {
+                const errMsg = typeof data.error === "string" ? data.error : (data.error.message ?? JSON.stringify(data.error).slice(0, 400));
+                throw new Error(`Relevance Judge endpoint returned an error envelope: ${errMsg}`);
+            }
+            const choice = data?.choices?.[0];
+            const content = choice?.message?.content ?? choice?.delta?.content;
+            if (typeof content !== "string") {
+                throw new Error(`Relevance Judge returned no usable content. Response: ${JSON.stringify(data).slice(0, 400)}`);
+            }
+            raw = content;
+        }
+        finally {
+            release();
+        }
+        const parsed = this.parseVerdicts(raw, candidates.length);
+        const approvedIndices = [];
+        for (const v of parsed) {
+            if (v.relevant && v.index >= 0 && v.index < candidates.length) {
+                approvedIndices.push(v.index);
+            }
+        }
+        return { verdicts: parsed, approvedIndices };
+    }
+    /**
+     * Defensive JSON parse — strips code fences, picks the first valid JSON
+     * object/array, and tolerates either {"verdicts":[…]} or a bare array.
+     * Returns one verdict per candidate; missing entries default to "rejected"
+     * so a malformed response can't silently approve everything.
+     */
+    parseVerdicts(raw, candidateCount) {
+        let text = raw.trim();
+        text = text.replace(/^```(?:json)?\s*/i, "").replace(/```\s*$/i, "").trim();
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            const objMatch = text.match(/\{[\s\S]*\}/);
+            const arrMatch = text.match(/\[[\s\S]*\]/);
+            const candidate = objMatch?.[0] ?? arrMatch?.[0];
+            if (!candidate) {
+                throw new Error(`Relevance Judge produced non-JSON output: ${text.slice(0, 200)}`);
+            }
+            parsed = JSON.parse(candidate);
+        }
+        const list = Array.isArray(parsed)
+            ? parsed
+            : Array.isArray(parsed?.verdicts) ? parsed.verdicts : [];
+        const byIndex = new Map();
+        for (const item of list) {
+            if (!item || typeof item !== "object")
+                continue;
+            const index = Number(item.index);
+            if (!Number.isFinite(index))
+                continue;
+            byIndex.set(index, {
+                index,
+                relevant: Boolean(item.relevant),
+                reason: typeof item.reason === "string" ? item.reason.slice(0, 200) : "",
+            });
+        }
+        const out = [];
+        for (let i = 0; i < candidateCount; i++) {
+            out.push(byIndex.get(i) ?? { index: i, relevant: false, reason: "no verdict returned" });
+        }
+        return out;
+    }
+}

package/dist/memory/working/canvas.js

@@ -24,6 +24,17 @@ export function buildAnnotatedCanvas(steps, activeNodeId) {
     for (let index = 1; index < steps.length; index += 1) {
         lines.push(`  ${steps[index - 1].nodeId} --> ${steps[index].nodeId}`);
     }
+    // Reasoning steps ("Why: …" decisions emitted via memory_working_offload
+    // with kind:"reasoning") get a dashed border so the audit trail is
+    // visually separable from tool_output and compressed_summary nodes when
+    // a human (or the dashboard) inspects canvas.mmd. Emitted before the
+    // active-node fill so the active highlight overrides the dashed style
+    // when the same node happens to be both.
+    for (const step of steps) {
+        if (step.kind === "reasoning") {
+            lines.push(`  style ${step.nodeId} stroke-dasharray:4 4,stroke:#9f7aea,stroke-width:2px`);
+        }
+    }
     if (activeNodeId && steps.some((step) => step.nodeId === activeNodeId)) {
         lines.push(`  style ${activeNodeId} fill:#2b6cb0,stroke:#3182ce,stroke-width:2px,color:#fff`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kinqs/brainrouter-mcp-server",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "BrainRouter MCP server — the cognitive memory engine. Exposes recall, capture, focus scenes, persona, contradictions, skills, and graph queries as MCP tools for any MCP-speaking agent.",
   "type": "module",
   "main": "dist/index.js",
@@ -45,7 +45,7 @@
     "gray-matter": "^4.0.3",
     "sqlite-vec": "^0.1.9",
     "zod": "^3.22.4",
-    "@kinqs/brainrouter-types": "^0.3.4"
+    "@kinqs/brainrouter-types": "^0.3.6"
   },
   "engines": {
     "node": ">=22.0.0"

package/dist/memory/config.d.ts

@@ -1,2 +0,0 @@
-export type BrainRouterLlmMode = "server" | "agent";
-export declare function getBrainRouterLlmMode(): BrainRouterLlmMode;

package/dist/memory/config.js

@@ -1,3 +0,0 @@
-export function getBrainRouterLlmMode() {
-    return process.env.BRAINROUTER_LLM_MODE === "agent" ? "agent" : "server";
-}

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

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

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

@@ -1,66 +0,0 @@
-import { L1_CONTRADICTION_PROMPT } from "../prompts/l1-contradiction.js";
-import crypto from "node:crypto";
-export async function detectContradictions(params) {
-    const { newRecord, store, llmRunner } = params;
-    // 1. Search for potentially related memories
-    // We use keyword search on the content of the new record to find similar existing ones
-    const candidates = store.searchL1Fts(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;
-        // Only compare if they are of the same type or both are episodic/persona
-        // (instructions don't usually contradict episodic facts)
-        const prompt = L1_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
-            });
-            // Simple JSON extraction (flexible for local models)
-            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);
-        }
-    }
-    // If ANY evaluation is a temporal_update, then the entire batch of contradictions represents a temporal transition!
-    const hasTemporalUpdate = evaluations.some(ev => ev.kind === "temporal_update");
-    for (const ev of evaluations) {
-        if (hasTemporalUpdate) {
-            // Treat all conflicting old records as superseded by the new record
-            console.error(`[BrainRouter] TEMPORAL UPDATE DETECTED (transition): Superseding memory ${ev.candidate.record_id} with new memory ${newRecord.id}`);
-            store.invalidateL1Record(newRecord.userId, ev.candidate.record_id, newRecord.id);
-        }
-        else {
-            // Genuine conflict
-            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
-            });
-        }
-    }
-}