@kinqs/brainrouter-mcp-server 0.3.5 → 0.3.6

package/.env.example

@@ -1,26 +1,37 @@
-# BrainRouter MCP server — environment
+# BrainRouter MCP server — environment template
 #
-# Copy to brainrouter/.env. Loaded automatically by `dotenv/config` when the
-# MCP server starts (the CLI sets the spawned child's cwd to this folder so
-# stdio-launched MCPs also pick it up).
+# Copy to `brainrouter/.env`. Loaded automatically by `dotenv/config` when
+# the MCP server starts. The CLI sets the spawned child's cwd to this
+# folder so stdio-launched MCPs also pick it up.
 #
 # This file is for MCP-SERVER concerns only:
-#   - cognitive extraction / synthesis LLM
-#   - embedding provider
-#   - reranker provider
-#   - memory engine knobs (decay, sweeper, focus, identity)
-#   - server auth (JWT, admin seed, CORS)
+#   1. LLM credentials & endpoint        (shared by every LLM-driven step)
+#   2. Retrieval pipeline stages         (embeddings, reranker, judge)
+#   3. Memory engine knobs               (storage, decay, distillation, sweeper)
+#   4. Skill pre-warming
+#   5. Server auth                       (JWT, admin seed, CORS, HTTP MCP key)
 #
 # CLI agent knobs (sandbox, tool loop limits, web search, etc.) live in
-# brainrouter-cli/.env.example. Keep them separate so the two processes
+# `brainrouter-cli/.env.example`. Keep them separate so the two processes
 # can be configured independently.
-
-# ==========================================
-# LLM (cognitive extraction + synthesis)
-# ==========================================
-# Used by L1 extraction, contradiction checks, graph extraction, L2 scenes,
-# L3 persona synthesis. Falls back to OPENAI_API_KEY.
-BRAINROUTER_LLM_API_KEY=your_api_key_here
+#
+# All values in this template are blank placeholders. Fill in only what
+# you actually need — most settings have sensible defaults.
+
+
+# =============================================================================
+# 1. LLM (cognitive extraction + synthesis + judging)
+# =============================================================================
+# Shared credential and endpoint for every LLM-driven step on the MCP side:
+#   - cognitive extraction   (turn raw conversation into structured memories)
+#   - contradiction checks   (detect when a new memory conflicts with an old one)
+#   - graph extraction       (pull entities + relations into the knowledge graph)
+#   - focus-scene summaries  (group related memories under a scene heading)
+#   - persona synthesis      (cross-session identity / "who is this user")
+#   - relevance judging      (Stage 3 of retrieval — see section 2 below)
+#
+# Falls back to OPENAI_API_KEY when BRAINROUTER_LLM_API_KEY is unset.
+BRAINROUTER_LLM_API_KEY=
 
 # OpenAI-compatible chat-completions endpoint.
 # Examples:
@@ -29,116 +40,155 @@ BRAINROUTER_LLM_API_KEY=your_api_key_here
 #   LM Studio:  http://localhost:1234/v1/chat/completions
 #   Ollama:     http://localhost:11434/v1/chat/completions
 BRAINROUTER_LLM_ENDPOINT=https://api.openai.com/v1/chat/completions
-
 BRAINROUTER_LLM_MODEL=gpt-4o-mini
 
-# Optional model split.
+# Optional per-task model split. Both inherit BRAINROUTER_LLM_MODEL.
+#   - EXTRACTION_MODEL: high-volume, can be cheap/local
+#   - SYNTHESIS_MODEL: lower-volume but benefits from smarter models
 # BRAINROUTER_EXTRACTION_MODEL=gpt-4o-mini
 # BRAINROUTER_SYNTHESIS_MODEL=gpt-4o
 
-# Per-call timeout for MCP-side LLM calls. Default: 120000.
+# Per-call timeout for MCP-side LLM calls. Default 120000 (2 min).
 # BRAINROUTER_LLM_TIMEOUT_MS=120000
 
 # Cap on concurrent in-flight LLM calls FROM THE MCP PROCESS.
-# Default: 2 (set to 1 on consumer hardware running LM Studio with a single model).
+# Default 2. Set to 1 on consumer hardware running LM Studio with a single
+# model; raise to 10+ for cloud APIs.
 # BRAINROUTER_LLM_MAX_CONCURRENT=2
 
-# ==========================================
-# Embeddings (vector search)
-# ==========================================
-# Falls back to BRAINROUTER_LLM_API_KEY when omitted.
-# Vector search is disabled if no key is available.
+
+# =============================================================================
+# 2. Retrieval pipeline (three optional stages)
+# =============================================================================
+# Each stage layers on top of the always-on FTS5 keyword search. Add them in
+# order — every stage raises relevance but also adds latency.
+#
+#   Stage 1: Embeddings   — semantic vector recall (fused with keyword via RRF)
+#   Stage 2: Reranker     — cross-encoder reorders the candidate pool
+#   Stage 3: Judge        — LLM approves/rejects each finalist for relevance
+#
+# Skip any stage by leaving its credentials unset.
+
+# --- Stage 1: Embeddings ----------------------------------------------------
+# Vector search runs when an embedding key is available; otherwise the
+# pipeline falls back to keyword-only. Falls back to BRAINROUTER_LLM_API_KEY
+# when BRAINROUTER_EMBEDDING_API_KEY is unset.
 # BRAINROUTER_EMBEDDING_API_KEY=
 BRAINROUTER_EMBEDDING_ENDPOINT=https://api.openai.com/v1/embeddings
 BRAINROUTER_EMBEDDING_MODEL=text-embedding-3-small
 BRAINROUTER_EMBEDDING_DIMENSIONS=1536
 
-# ==========================================
-# Reranker (optional)
-# ==========================================
-# Disabled unless a key is present.
+# --- Stage 2: Reranker (optional) -------------------------------------------
+# Cross-encoder rescores the candidate pool. Disabled unless a key is set.
+# Compatible with Cohere /v1/rerank or any vLLM-style /v1/rerank endpoint.
 # BRAINROUTER_RERANKER_API_KEY=
 # BRAINROUTER_RERANKER_ENDPOINT=https://api.cohere.com/v1/rerank
 # BRAINROUTER_RERANKER_MODEL=rerank-english-v3.0
 # BRAINROUTER_RERANKER_TOP_N=10
 
-# ==========================================
-# Storage
-# ==========================================
+# --- Stage 3: Relevance judge (optional, off by default) --------------------
+# LLM-as-judge gate that runs AFTER the reranker and drops candidates that
+# aren't actually relevant to the query. The reranker only re-orders; it
+# never filters — so a memory sharing vocabulary with the query but about
+# a different subject still makes it through. The judge fixes that.
+#
+# Adds one extra LLM call per recall: ~500ms-1s on a small/fast model.
+# Falls back to BRAINROUTER_LLM_* unless explicitly overridden, so a single
+# credential covers extraction, synthesis, and judging by default.
+# BRAINROUTER_RELEVANCE_JUDGE_ENABLED=true
+# BRAINROUTER_RELEVANCE_JUDGE_API_KEY=
+# BRAINROUTER_RELEVANCE_JUDGE_ENDPOINT=https://api.openai.com/v1/chat/completions
+# BRAINROUTER_RELEVANCE_JUDGE_MODEL=gpt-4o-mini
+# Max candidates sent to the judge in a single batched call. Default 10.
+# BRAINROUTER_RELEVANCE_JUDGE_MAX_CANDIDATES=10
+# Per-call timeout in ms. Default 15000.
+# BRAINROUTER_RELEVANCE_JUDGE_TIMEOUT_MS=15000
+
+
+# =============================================================================
+# 3. Memory engine
+# =============================================================================
+
+# --- Storage paths ----------------------------------------------------------
 # SQLite memory store path. Default: ~/.brainrouter/memory.db.
-# BRAINROUTER_MEMORY_DB=/Users/you/.brainrouter/memory.db
-
+# BRAINROUTER_MEMORY_DB=/path/to/memory.db
 # Override per-user state root. Default: ~/.brainrouter.
 # BRAINROUTER_HOME=/path/to/state
-
 # Workspace root when MCP --root is omitted.
 # BRAINROUTER_LOCAL_ROOT=/path/to/your/project
 
-# ==========================================
-# Memory engine
-# ==========================================
-# Set false to disable GraphRAG (2-hop entity expansion). Default: true.
+# --- Knowledge graph + contradictions ---------------------------------------
+# Disable GraphRAG (2-hop entity expansion) by setting to false. Default true.
 # BRAINROUTER_GRAPH_ENABLED=true
 # BRAINROUTER_GRAPH_TIMEOUT_MS=120000
 # BRAINROUTER_CONTRADICTION_TIMEOUT_MS=60000
 
-# Memories recalled this many times without citation are auto-archived.
-# 0 disables. Default: 10.
+# --- ACE feedback (auto-archive uncited memories) ---------------------------
+# Memories surfaced in recall this many times without being cited by the
+# agent get auto-archived. 0 disables. Default 10.
 # BRAINROUTER_ACE_ARCHIVE_THRESHOLD=10
 
-# Focus-scene distillation trigger (new records before scenes rebuild).
+# --- Distillation triggers --------------------------------------------------
+# Focus-scene summary — groups related cognitives under a scene heading.
+# Fires once every N new cognitive records.
 # BRAINROUTER_FOCUS_TRIGGER_N=10
 # BRAINROUTER_MAX_FOCUS_SCENES=20
 
-# Identity (persona) distillation trigger.
+# Persona synthesis — cross-session identity summary ("who is this user").
+# Fires once every N new cognitive records.
 # BRAINROUTER_IDENTITY_TRIGGER_N=50
+# In-memory persona cache lifetime. Default 3600000 (1h).
 # BRAINROUTER_PERSONA_CACHE_TTL_MS=3600000
 
-# ==========================================
-# Skill pre-warming
-# ==========================================
-# BRAINROUTER_PREWARM_ENABLED=false
+# --- Extraction backlog sweeper ---------------------------------------------
+# Background job that runs cognitive extraction over sensory rows the
+# per-turn extractor missed (errored, skipped, or interrupted).
+# BRAINROUTER_DISABLE_EXTRACTION_SWEEPER=true
+# BRAINROUTER_EXTRACTION_SWEEP_INTERVAL_MS=300000   # floor: 30000
+# BRAINROUTER_EXTRACTION_SWEEP_MIN_AGE_MS=120000
+# BRAINROUTER_EXTRACTION_MAX_FAILURES=5
+
+
+# =============================================================================
+# 4. Skill pre-warming (optional, off by default)
+# =============================================================================
+# Memetic skill activation — repeatedly invoking a skill heats it up so its
+# memory hints get pre-injected into context. Half-life decay keeps cold
+# skills from polluting the prompt.
+# BRAINROUTER_PREWARM_ENABLED=true
 # BRAINROUTER_SKILL_HALF_LIFE_MINUTES=10
 # BRAINROUTER_SKILL_MIN_TURN_DECAY=0.05
 # BRAINROUTER_SKILL_PREWARM_THRESHOLD=0.3
 # BRAINROUTER_SKILL_SPIKE_AMOUNT=1.0
 # BRAINROUTER_SKILL_MAX_POTENTIAL=4.0
 
-# ==========================================
-# Extraction backlog sweeper
-# ==========================================
-# BRAINROUTER_DISABLE_EXTRACTION_SWEEPER=false
-# BRAINROUTER_EXTRACTION_SWEEP_INTERVAL_MS=300000   # floored at 30000
-# BRAINROUTER_EXTRACTION_SWEEP_MIN_AGE_MS=120000
-# BRAINROUTER_EXTRACTION_MAX_FAILURES=5
 
-# ==========================================
-# Server auth
-# ==========================================
+# =============================================================================
+# 5. Server auth (HTTP MCP + dashboard)
+# =============================================================================
+# Only needed if you run the HTTP MCP transport or the web dashboard.
+# Stdio MCP (the default transport) doesn't use any of these.
+
 # Seeded admin (used when the users table is empty and by scripts/setup-admin.js).
 BRAINROUTER_DEFAULT_ADMIN_USER_ID=admin
 BRAINROUTER_ADMIN_EMAIL=admin@example.com
-BRAINROUTER_ADMIN_PASSWORD=change_me_before_use
+# Set on first boot to seed the admin password — leave blank afterward.
+BRAINROUTER_ADMIN_PASSWORD=
 
-# JWT signing key for dashboard sessions.
-# Generate one with:
+# JWT signing key for dashboard sessions. Generate with:
 #   node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
-# If unset, the server generates a random secret per boot — sessions do not survive restarts.
-BRAINROUTER_JWT_SECRET=replace_with_a_long_random_secret
+# If unset, the server generates a random secret per boot and sessions do
+# not survive restarts.
+BRAINROUTER_JWT_SECRET=
 # BRAINROUTER_JWT_EXPIRES_SECS=86400
 
 # Dashboard CORS allowlist.
 BRAINROUTER_CORS_ORIGIN=http://localhost:3000
 
-# API key for HTTP MCP transport clients. Usually set in the client config,
-# not here. Reset with: npm run setup:admin -- --reset --userId admin.
-# BRAINROUTER_API_KEY=br_your_api_key
+# API key for HTTP MCP transport clients. Usually configured in the client,
+# not here. Reset with: npm run setup:admin -- --reset --userId admin
+# BRAINROUTER_API_KEY=
 
 # Stdio fallback user id when no authenticated user mapping is available.
 # Prefer BRAINROUTER_API_KEY instead.
 # BRAINROUTER_USER_ID=default
-
-# ==========================================
-# Dashboard (read by web/, not by this server)
-# ==========================================
-# NEXT_PUBLIC_API_URL=http://localhost:3747

package/dist/__tests__/cognitive-extractor.test.js

@@ -0,0 +1,112 @@
+import { describe, expect, it } from "vitest";
+import { extractCognitiveMemories } from "../memory/pipeline/cognitive-extractor.js";
+function makeMessage(messageText) {
+    const recordedAt = new Date().toISOString();
+    return {
+        id: "sensory_test",
+        userId: "user_test",
+        sessionKey: "session_test",
+        sessionId: "session_test",
+        role: "user",
+        messageText,
+        recordedAt,
+        timestamp: Date.parse(recordedAt),
+        skillTag: "",
+    };
+}
+function makeRunner(raw) {
+    return {
+        run: async () => raw,
+    };
+}
+function memory(content) {
+    return `{
+    "type": "episodic",
+    "content": "${content}",
+    "priority": 50,
+    "sourceKind": "model_inference",
+    "verificationStatus": "unverified"
+  }`;
+}
+async function extractContents(raw) {
+    const result = await extractCognitiveMemories({
+        messages: [makeMessage("capture these paths")],
+        userId: "user_test",
+        sessionKey: "session_test",
+        sessionId: "session_test",
+        llmRunner: makeRunner(raw),
+    });
+    expect(result.success).toBe(true);
+    return result.records.map((record) => record.content);
+}
+describe("cognitive extractor JSON escape repair", () => {
+    it("round-trips ambiguous path backslashes without interpreting them as escapes", async () => {
+        const raw = String.raw `[
+      {
+        "scene_name": "Path repair",
+        "memories": [
+          ${memory(String.raw `C:\users\file`)},
+          ${memory(String.raw `C:\bin\node.exe`)},
+          ${memory(String.raw `/repos/\target/release`)},
+          ${memory(String.raw `\release\foo.txt`)},
+          ${memory(String.raw `line1\nline2`)}
+        ]
+      }
+    ]`;
+        await expect(extractContents(raw)).resolves.toEqual([
+            String.raw `C:\users\file`,
+            String.raw `C:\bin\node.exe`,
+            String.raw `/repos/\target/release`,
+            String.raw `\release\foo.txt`,
+            String.raw `line1\nline2`,
+        ]);
+    });
+    it("keeps legitimate JSON escapes on the happy path", async () => {
+        const raw = String.raw `[
+      {
+        "scene_name": "Happy path",
+        "memories": [
+          ${memory(String.raw `line1\nline2`)}
+        ]
+      }
+    ]`;
+        await expect(extractContents(raw)).resolves.toEqual(["line1\nline2"]);
+    });
+    it("decodes \\uXXXX unicode escapes on the happy path", async () => {
+        // The input JSON contains the literal 6-char sequence é (an
+        // escape sequence as text). When the JSON is well-formed, the first
+        // JSON.parse handles the escape and we get the actual é code point.
+        // Locks down the contract for content like "café" / "résumé" /
+        // non-ASCII names emitted by LLMs that escape non-ASCII output.
+        const raw = String.raw `[
+      {
+        "scene_name": "Unicode happy",
+        "memories": [
+          ${memory(String.raw `café done`)}
+        ]
+      }
+    ]`;
+        await expect(extractContents(raw)).resolves.toEqual(["café done"]);
+    });
+    it("preserves \\uXXXX literally when repair fires (paths win the tie-break)", async () => {
+        // If anything in the batch forces the repair branch (here: a Windows
+        // path with \u + non-hex), then ALL ambiguous backslashes — including
+        // otherwise-valid \uXXXX unicode escapes elsewhere in the payload —
+        // become literal. Deliberate tradeoff: silent path corruption is
+        // worse than a one-off escaped unicode that doesn't decode. The
+        // resulting content has a literal `é` (6 chars) instead of "é".
+        const raw = String.raw `[
+      {
+        "scene_name": "Unicode + path collision",
+        "memories": [
+          ${memory(String.raw `C:\users\file`)},
+          ${memory(String.raw `café collateral`)}
+        ]
+      }
+    ]`;
+        await expect(extractContents(raw)).resolves.toEqual([
+            String.raw `C:\users\file`,
+            String.raw `café collateral`,
+        ]);
+    });
+});

package/dist/__tests__/crypto.test.js

@@ -22,7 +22,14 @@ describe("crypto auth helpers", () => {
     });
     it("verifyJwt returns null for tampered signature", () => {
         const token = signJwt({ userId: "u1" }, "secret", 60);
-        const tampered = `${token.slice(0, -1)}x`;
+        // Pick a replacement char that is GUARANTEED to differ from the
+        // original last char. The previous version hard-coded "x"; whenever
+        // the JWT's base64url signature happened to end in "x" (~1/64 odds),
+        // the "tampered" token equalled the original and verification
+        // succeeded — flaky failure. See PR #22 CI run 26323691062.
+        const lastChar = token.slice(-1);
+        const replacement = lastChar === "A" ? "B" : "A";
+        const tampered = token.slice(0, -1) + replacement;
         expect(verifyJwt(tampered, "secret")).toBeNull();
     });
 });

package/dist/__tests__/working-memory.test.js

@@ -197,4 +197,71 @@ describe("short-term working memory tools", () => {
         expect(existsSync(join(resolve("abc123abc123"), ".brainrouter"))).toBe(false);
         rmSync(result.state.workDir, { recursive: true, force: true });
     });
+    it("round-trips kind:\"reasoning\" through offload → context", async () => {
+        // 0.3.6 item 2c: agents now offload a structured "Why: …" step after
+        // every non-trivial tool batch. The kind field is free-form on the
+        // schema, so a regression that silently dropped or overwrote the value
+        // (e.g. always-default to "tool_output") would erase the entire
+        // audit-trail surface. Pin the round-trip explicitly.
+        const workspacePath = mkdtempSync(join(tmpdir(), "brainrouter-working-reasoning-"));
+        const userId = "user-1";
+        const sessionKey = "reasoning-session";
+        const offload = parseToolJson(await handleMemoryWorkingTool("memory_working_offload", {
+            workspacePath,
+            userId,
+            sessionKey,
+            payload: "Decided to refactor canvas.ts because rendering by kind was missing.",
+            title: "Why: refactor canvas for kind-aware rendering",
+            summary: "Picked the dashed-border style for reasoning nodes.",
+            kind: "reasoning",
+        }));
+        expect(offload.state.injectedState.currentNode.kind).toBe("reasoning");
+        const context = parseToolJson(await handleMemoryWorkingTool("memory_working_context", {
+            workspacePath,
+            userId,
+            sessionKey,
+        }));
+        expect(context.steps).toHaveLength(1);
+        expect(context.steps[0].kind).toBe("reasoning");
+        expect(context.state.injectedState.recentSteps[0].kind).toBe("reasoning");
+    });
+    it("renders reasoning-kind nodes with a distinct Mermaid style in the canvas", async () => {
+        // The canvas needs to visually separate reasoning ("why") nodes from
+        // tool_output ("what came back") and compressed_summary ("the older
+        // history got rolled up") nodes, so a human inspecting `canvas.mmd`
+        // can see the decision trail at a glance. Pin the style emission so a
+        // future refactor of canvas.ts can't silently flatten all kinds back
+        // to a single shape.
+        const workspacePath = mkdtempSync(join(tmpdir(), "brainrouter-working-canvas-kind-"));
+        const userId = "user-1";
+        const sessionKey = "canvas-kind-session";
+        const tool = parseToolJson(await handleMemoryWorkingTool("memory_working_offload", {
+            workspacePath,
+            userId,
+            sessionKey,
+            payload: "tool output payload",
+            title: "Tool result",
+            summary: "Read repo files",
+            kind: "tool_output",
+        }));
+        const reason = parseToolJson(await handleMemoryWorkingTool("memory_working_offload", {
+            workspacePath,
+            userId,
+            sessionKey,
+            payload: "Chose dashed-border style because reasoning is conceptually different from tool output.",
+            title: "Why: dashed style for reasoning",
+            summary: "Visual separation of why vs. what.",
+            kind: "reasoning",
+        }));
+        const context = parseToolJson(await handleMemoryWorkingTool("memory_working_context", {
+            workspacePath,
+            userId,
+            sessionKey,
+        }));
+        // Reasoning node must carry a distinct stroke-dasharray style line.
+        // Tool-output node must NOT carry that same dashed style — otherwise
+        // the "distinct" claim is meaningless.
+        expect(context.canvas).toMatch(new RegExp(`style ${reason.nodeId} [^\\n]*stroke-dasharray`));
+        expect(context.canvas).not.toMatch(new RegExp(`style ${tool.nodeId} [^\\n]*stroke-dasharray`));
+    });
 });

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,
                 },
             });
         }