@kinqs/brainrouter-mcp-server 0.3.4

package/dist/memory/engine.js

@@ -0,0 +1,626 @@
+import { SqliteMemoryStore } from "./store/sqlite.js";
+import { MemoryCapturePipeline } from "./capture.js";
+import { MemoryRecallPipeline } from "./recall.js";
+import { EmbeddingService } from "./store/embedding.js";
+import { RerankerService } from "./store/reranker.js";
+import { scanSkillsForHints } from "./skill-hints-loader.js";
+import { distillFocusScenes } from "./pipeline/contextual-focus-builder.js";
+import { distillCoreIdentity } from "./pipeline/identity-distiller.js";
+import { spikeSkill as spikeSkillActivation, decayPotential } from "./pipeline/skill-prewarm.js";
+import { NeuralSparkEngine } from "./pipeline/neural-spark.js";
+import { fetchWithExternalRetry } from "./retry.js";
+import { acquireLLMSlot } from "./llm-semaphore.js";
+import "dotenv/config";
+import path from "node:path";
+import os from "node:os";
+import fs from "node:fs";
+import { randomBytes } from "node:crypto";
+import { randomUUID } from "node:crypto";
+import { hashPassword } from "../api/auth/crypto.js";
+import { getMemoryTypeConfig } from "./memory-type-config.js";
+import { redactSensitiveMemoryText } from "./redaction.js";
+// Configure default path
+const defaultDbPath = process.env.BRAINROUTER_MEMORY_DB || path.join(os.homedir(), ".brainrouter", "memory.db");
+// Configurable LLM Runner — supports per-task model routing
+class ModelLLMRunner {
+    modelOverride;
+    constructor(modelOverride) {
+        this.modelOverride = modelOverride?.trim() || undefined;
+    }
+    async run({ prompt, systemPrompt, timeoutMs = 120_000, taskId }) {
+        const endpoint = process.env.BRAINROUTER_LLM_ENDPOINT ?? "https://api.openai.com/v1/chat/completions";
+        const apiKey = process.env.BRAINROUTER_LLM_API_KEY;
+        if (!apiKey) {
+            // Typed sentinel so upstream pipelines can short-circuit cleanly without dumping a stack trace.
+            // Callers should check `error.code === "LLM_NOT_CONFIGURED"` and skip extraction silently.
+            const err = new Error(`[BrainRouter:${taskId}] BRAINROUTER_LLM_API_KEY is not set. Skipping LLM step.`);
+            err.code = "LLM_NOT_CONFIGURED";
+            throw err;
+        }
+        const model = this.modelOverride
+            ?? (process.env.BRAINROUTER_LLM_MODEL?.trim() || undefined)
+            ?? "gpt-4o-mini";
+        const messages = [];
+        if (systemPrompt) {
+            messages.push({ role: "system", content: systemPrompt });
+        }
+        messages.push({ role: "user", content: prompt });
+        const doFetch = () => fetchWithExternalRetry(endpoint, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": `Bearer ${apiKey}`,
+            },
+            body: JSON.stringify({ model, messages }),
+            signal: AbortSignal.timeout(timeoutMs),
+        }, {
+            label: `[BrainRouter:${taskId}] LLM API`,
+        });
+        // Acquire a slot from the global LLM semaphore BEFORE issuing the
+        // request. On consumer hardware (LM Studio with a single GPU) firing
+        // more than ~2 concurrent generations against the same backend causes
+        // the model to thrash or auto-unload — see llm-semaphore.ts for the
+        // full rationale. Cloud backends (OpenAI / OpenRouter) can lift the cap
+        // with BRAINROUTER_LLM_MAX_CONCURRENT=10 (or higher).
+        const release = await acquireLLMSlot();
+        try {
+            let res = await doFetch();
+            // LM Studio quirk: if the model has been idle long enough to auto-unload,
+            // it returns 400 with `{"error":"Model is unloaded."}` on the first call
+            // and then loads the model in the background. The next call usually
+            // succeeds. Detect that exact error and retry ONCE after a brief pause
+            // so background workers (contradiction check, graph extraction, focus
+            // shift detection) don't all fail when the user has been quiet for a bit.
+            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();
+                        throw new Error(`[BrainRouter:${taskId}] LLM model "${model}" was unloaded by the server; ` +
+                            `retry also failed (${res.status} ${res.statusText}). ` +
+                            `If you're using LM Studio, enable JIT model loading or pin the model as always-loaded. ` +
+                            `Original error: ${errorBody}. Retry error: ${retryBody}`);
+                    }
+                }
+                else {
+                    throw new Error(`[BrainRouter:${taskId}] LLM Error (${model}): ${res.status} ${res.statusText} - ${errorBody}`);
+                }
+            }
+            else if (!res.ok) {
+                const errorBody = await res.text();
+                throw new Error(`[BrainRouter:${taskId}] LLM Error (${model}): ${res.status} ${res.statusText} - ${errorBody}`);
+            }
+            const data = await res.json();
+            // Defensive parsing — see brainrouter/src/agent/agent.ts callOpenAI for the
+            // full rationale. The short version: some endpoints return HTTP 200
+            // with an `error` envelope or a non-standard schema. Surface the
+            // actual response body in the error so a misconfigured model name
+            // doesn't crash with "Cannot read properties of undefined".
+            if (data && typeof data === "object" && data.error) {
+                const errMsg = typeof data.error === "string"
+                    ? data.error
+                    : (data.error.message ?? JSON.stringify(data.error).slice(0, 400));
+                throw new Error(`[BrainRouter:${taskId}] LLM endpoint returned an error envelope: ${errMsg}`);
+            }
+            if (!Array.isArray(data?.choices) || data.choices.length === 0) {
+                throw new Error(`[BrainRouter:${taskId}] LLM endpoint returned no choices for model "${model}". ` +
+                    `Response body: ${JSON.stringify(data).slice(0, 600)}`);
+            }
+            const choice = data.choices[0];
+            // Tolerate both message (standard) and delta (streaming-style) shapes.
+            const content = choice?.message?.content ?? choice?.delta?.content;
+            if (typeof content !== "string") {
+                throw new Error(`[BrainRouter:${taskId}] LLM choice had no usable content. Choice: ${JSON.stringify(choice).slice(0, 600)}`);
+            }
+            return content;
+        }
+        finally {
+            // Always release, success or failure, so the queue keeps moving even
+            // if an upstream throw bubbles. The semaphore's release is idempotent.
+            release();
+        }
+    }
+}
+export class MemoryEngine {
+    store;
+    capturePipeline;
+    recallPipeline;
+    extractionRunner;
+    synthesisRunner;
+    sweeperTimer;
+    /**
+     * Reentrancy guard: setInterval doesn't wait for the previous callback to
+     * finish before firing the next tick. If a sweep takes longer than the
+     * configured interval (very common when LLM calls queue behind the
+     * concurrency semaphore), ticks pile up and each one tries to extract
+     * the SAME backlog rows. The guard ensures at most one sweep is in flight
+     * at any time; later ticks become no-ops while a previous one runs.
+     */
+    sweepInProgress = false;
+    personaCache = new Map();
+    PERSONA_CACHE_TTL_MS = parseInt(process.env.BRAINROUTER_PERSONA_CACHE_TTL_MS ?? String(60 * 60 * 1000), 10);
+    constructor(storeOrDbPath = defaultDbPath) {
+        if (typeof storeOrDbPath === "string") {
+            const dir = path.dirname(storeOrDbPath);
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true });
+            }
+            this.store = new SqliteMemoryStore(storeOrDbPath);
+        }
+        else {
+            this.store = storeOrDbPath;
+        }
+        this.store.init();
+        this.ensureSeedAdminUser().catch((err) => {
+            console.error("[BrainRouter] Failed to seed admin user:", err instanceof Error ? err.message : err);
+        });
+        this.extractionRunner = new ModelLLMRunner(process.env.BRAINROUTER_EXTRACTION_MODEL);
+        this.synthesisRunner = new ModelLLMRunner(process.env.BRAINROUTER_SYNTHESIS_MODEL);
+        const embeddingService = new EmbeddingService({
+            endpoint: process.env.BRAINROUTER_EMBEDDING_ENDPOINT,
+            apiKey: process.env.BRAINROUTER_EMBEDDING_API_KEY ?? process.env.BRAINROUTER_LLM_API_KEY,
+            model: process.env.BRAINROUTER_EMBEDDING_MODEL,
+            dimensions: process.env.BRAINROUTER_EMBEDDING_DIMENSIONS ? parseInt(process.env.BRAINROUTER_EMBEDDING_DIMENSIONS, 10) : undefined,
+        });
+        const rerankerService = new RerankerService({
+            endpoint: process.env.BRAINROUTER_RERANKER_ENDPOINT,
+            apiKey: process.env.BRAINROUTER_RERANKER_API_KEY,
+            model: process.env.BRAINROUTER_RERANKER_MODEL,
+            topN: process.env.BRAINROUTER_RERANKER_TOP_N
+                ? parseInt(process.env.BRAINROUTER_RERANKER_TOP_N, 10)
+                : undefined,
+        });
+        this.store.initVec(embeddingService.getDimensions());
+        if (embeddingService.isReady()) {
+            void this.store.reembedStaleRecords((text) => embeddingService.embed(text)).then((count) => {
+                if (count > 0) {
+                    console.error(`[BrainRouter] Re-embedded ${count} stale cognitive vector records.`);
+                }
+            }).catch((err) => {
+                console.error("[BrainRouter] Failed to re-embed stale cognitive vector records:", err instanceof Error ? err.message : err);
+            });
+        }
+        this.capturePipeline = new MemoryCapturePipeline(this.store, this.extractionRunner, embeddingService, 1);
+        this.recallPipeline = new MemoryRecallPipeline(this.store, embeddingService, rerankerService);
+        this.startExtractionSweeper();
+    }
+    async ensureSeedAdminUser() {
+        const users = this.store.listUsers();
+        if (users.length > 0)
+            return;
+        const seededUserId = process.env.BRAINROUTER_DEFAULT_ADMIN_USER_ID ?? "admin";
+        const seededEmail = process.env.BRAINROUTER_ADMIN_EMAIL ?? "admin";
+        const seededPassword = process.env.BRAINROUTER_ADMIN_PASSWORD?.trim();
+        const apiKey = `br_${randomBytes(24).toString("hex")}`;
+        this.store.createUser(seededUserId, apiKey, "Default Admin", true);
+        this.store.updateUserEmail(seededUserId, seededEmail);
+        if (seededPassword) {
+            const passwordHash = await hashPassword(seededPassword);
+            this.store.updateUserPassword(seededUserId, passwordHash);
+        }
+        console.error(`[BrainRouter] Admin seeded. Email: ${seededEmail}  API key (shown once): ${apiKey}`);
+    }
+    get capture() {
+        return this.capturePipeline.captureTurn.bind(this.capturePipeline);
+    }
+    capturePassiveL0(params) {
+        const now = new Date().toISOString();
+        const timestamp = params.timestamp ?? Date.now();
+        const record = {
+            id: `sensory_hook_${params.sessionKey}_${timestamp}_${randomUUID()}`,
+            userId: params.userId,
+            sessionKey: params.sessionKey,
+            sessionId: params.sessionId ?? "",
+            role: params.role,
+            messageText: redactSensitiveMemoryText(params.content),
+            recordedAt: now,
+            timestamp,
+            skillTag: params.skillTag ?? "",
+        };
+        this.store.upsertSensory(record);
+        return record;
+    }
+    async explainRecall(params) {
+        return this.recallPipeline.recall({ ...params, explain: true });
+    }
+    get recall() {
+        return async (params) => {
+            const result = await this.recallPipeline.recall(params);
+            const persona = this.getPersona(params.userId);
+            if (persona) {
+                const existing = result.appendSystemContext ?? "";
+                result.appendSystemContext = `<user-persona>\n${persona.personaMd}\n</user-persona>\n\n` + existing;
+                result.coreIdentitySummary = persona.personaMd;
+            }
+            return result;
+        };
+    }
+    getPendingContradictions(userId, pagination) {
+        return this.store.getPendingContradictions(userId, pagination);
+    }
+    resolveContradiction(id, userId, status) {
+        return this.store.resolveContradiction(id, userId, status);
+    }
+    registerSkillHints(skillName, hints, sourceFile = "") {
+        this.store.upsertSkillHints(skillName, hints, sourceFile);
+    }
+    listSkillHints() {
+        return this.store.listSkillHints();
+    }
+    spikeSkill(userId, skillName) {
+        return spikeSkillActivation({ userId, skillName, store: this.store });
+    }
+    getSkillActivations(userId) {
+        const raw = this.store.getSkillActivations(userId);
+        const now = new Date();
+        return raw.map(r => ({
+            skillName: r.skillName,
+            potential: decayPotential({
+                potential: r.potential,
+                lastDecayTime: r.lastDecayTime,
+                now,
+            }),
+            lastDecayTime: r.lastDecayTime,
+        })).sort((a, b) => b.potential - a.potential);
+    }
+    autoScanSkillHints(skillsDirs) {
+        let loaded = 0;
+        for (const dir of skillsDirs) {
+            if (!fs.existsSync(dir))
+                continue;
+            const found = scanSkillsForHints(dir);
+            for (const item of found) {
+                const skillName = item.name || path.basename(path.dirname(item.filePath));
+                this.store.upsertSkillHints(skillName, item.hints, item.filePath);
+                loaded++;
+            }
+        }
+        if (loaded > 0) {
+            console.error(`[BrainRouter] Auto-loaded memory_hints for ${loaded} skill(s).`);
+        }
+    }
+    /** On-demand Focus Scene distillation — groups cognitives by scene and summarizes via LLM. */
+    async distillScenes(userId) {
+        return distillFocusScenes({ userId, store: this.store, llmRunner: this.synthesisRunner });
+    }
+    /** On-demand Core Identity distillation — cross-session synthesis of persona+instruction cognitives. */
+    async distillPersona(userId) {
+        const result = await distillCoreIdentity({ userId, store: this.store, llmRunner: this.synthesisRunner });
+        if (result.success && result.personaMd) {
+            this.personaCache.set(userId, { personaMd: result.personaMd, cachedAt: Date.now() });
+        }
+        return result;
+    }
+    /** Get the current Core Identity for a user, using prompt-level in-memory cache. */
+    getPersona(userId) {
+        const cached = this.personaCache.get(userId);
+        if (cached && (Date.now() - cached.cachedAt) < this.PERSONA_CACHE_TTL_MS) {
+            return { personaMd: cached.personaMd };
+        }
+        const persona = this.store.getCoreIdentity(userId);
+        if (persona) {
+            this.personaCache.set(userId, { personaMd: persona.personaMd, cachedAt: Date.now() });
+        }
+        return persona;
+    }
+    /** Get the top N active focus scenes for a user (ordered by heat score). */
+    getTopScenes(userId, limit = 3, cursor) {
+        return this.store.getTopContextualFocus(userId, limit, cursor);
+    }
+    /** Expose the ability to query the knowledge graph for a user/entity. */
+    queryGraph(userId, entity, skillTag, maxHops = 2) {
+        const node = this.store.getGraphNodeByEntity(userId, entity);
+        if (!node)
+            return { nodes: [], edges: [] };
+        return this.store.getGraphNeighbors(userId, node.id, skillTag, maxHops);
+    }
+    createUser(userId, apiKey, displayName = "", isAdmin = false) {
+        return this.store.createUser(userId, apiKey, displayName, isAdmin);
+    }
+    getUserByApiKey(apiKey) {
+        return this.store.getUserByApiKey(apiKey);
+    }
+    getUserByEmail(email) {
+        return this.store.getUserByEmail(email);
+    }
+    getUserById(userId) {
+        return this.store.getUserById(userId);
+    }
+    updatePassword(userId, hash) {
+        this.store.updateUserPassword(userId, hash);
+    }
+    updateUserEmail(userId, email) {
+        this.store.updateUserEmail(userId, email);
+    }
+    updateUserDisplayName(userId, displayName) {
+        this.store.updateUserDisplayName(userId, displayName);
+    }
+    updateUserStatus(userId, status) {
+        this.store.updateUserStatus(userId, status);
+    }
+    updateUserApiKey(userId, apiKey) {
+        this.store.updateUserApiKey(userId, apiKey);
+    }
+    listUsers(pagination) {
+        return this.store.listUsers(pagination);
+    }
+    deleteUser(userId) {
+        this.store.deleteUser(userId);
+    }
+    listMemories(userId, filters, pagination) {
+        return this.store.listMemories(userId, filters, pagination);
+    }
+    deleteMemory(userId, recordId) {
+        this.store.archiveCognitiveRecord(userId, recordId);
+    }
+    getMemoryById(userId, recordId) {
+        const memory = this.store.getMemoryById(userId, recordId);
+        if (!memory)
+            return null;
+        return { memory, evidence: this.store.getEvidenceByRecord(userId, recordId) };
+    }
+    upsertEngineeringMemory(params) {
+        const now = new Date().toISOString();
+        const config = getMemoryTypeConfig(params.type);
+        const record = {
+            id: `cognitive_manual_${randomUUID()}`,
+            userId: params.userId,
+            sessionKey: params.sessionKey ?? "",
+            sessionId: params.sessionId ?? "",
+            content: params.content,
+            type: params.type,
+            priority: params.priority ?? 75,
+            sceneName: params.activeSkill ? `${params.activeSkill} engineering` : "Software engineering memory",
+            skillTag: params.activeSkill ?? "",
+            halfLifeDays: config.halfLifeDays,
+            supersededBy: null,
+            invalidAt: null,
+            timestampStr: now,
+            timestampStart: now,
+            timestampEnd: now,
+            createdTime: now,
+            updatedTime: now,
+            metadata: params.metadata ?? {},
+            confidence: params.confidence ?? config.defaultConfidence,
+            status: "active",
+            sourceKind: params.sourceKind ?? "user_instruction",
+            verificationStatus: params.verificationStatus ?? "unverified",
+            repoPaths: params.repoPaths ?? [],
+            filePaths: params.filePaths ?? [],
+            commands: params.commands ?? [],
+            citationCount: 0,
+            lastCitedAt: null,
+            neverCitedCount: 0,
+            archived: false,
+        };
+        this.store.upsertCognitive(record);
+        return record;
+    }
+    getMemoriesByFilePath(userId, filePath, limit = 20) {
+        return this.store.getMemoriesByFilePath(userId, filePath, limit);
+    }
+    searchMemoryRecords(userId, query, limit = 20) {
+        return this.store.searchCognitiveFts(userId, query, limit);
+    }
+    updateMemory(userId, recordId, updates) {
+        const existing = this.store.getMemoryById(userId, recordId);
+        if (!existing)
+            return null;
+        const now = new Date().toISOString();
+        const updated = {
+            ...existing,
+            content: updates.content ?? existing.content,
+            status: updates.status ?? existing.status,
+            confidence: updates.confidence ?? existing.confidence,
+            verificationStatus: updates.verificationStatus ?? existing.verificationStatus,
+            updatedTime: now,
+            archived: updates.status === "archived" ? true : existing.archived,
+            metadata: updates.note
+                ? { ...existing.metadata, governanceNote: updates.note, governanceNoteAt: now }
+                : existing.metadata,
+        };
+        this.store.upsertCognitive(updated, { skipAudit: true });
+        this.store.insertOperation({
+            id: randomUUID(),
+            userId,
+            recordId,
+            operation: "memory_update",
+            actor: "user",
+            sessionKey: existing.sessionKey,
+            reason: updates.note ?? "",
+            createdAt: now,
+            metadata: {
+                contentChanged: typeof updates.content === "string",
+                status: updates.status,
+                confidence: updates.confidence,
+                verificationStatus: updates.verificationStatus,
+            },
+        });
+        return this.getMemoryById(userId, recordId);
+    }
+    updateMemoryStatus(userId, recordId, confidence, status) {
+        this.store.updateCognitiveConfidence(userId, recordId, confidence, status);
+        return this.getMemoryById(userId, recordId);
+    }
+    addEvidence(userId, recordId, evidence) {
+        const ev = {
+            id: evidence.id ?? randomUUID(),
+            userId,
+            recordId,
+            kind: evidence.kind,
+            ref: evidence.ref,
+            excerpt: evidence.excerpt ?? "",
+            observedAt: evidence.observedAt ?? new Date().toISOString(),
+            metadata: evidence.metadata ?? {},
+        };
+        this.store.insertEvidence(ev);
+        return ev;
+    }
+    getEvidence(userId, recordId) {
+        return this.store.getEvidenceByRecord(userId, recordId);
+    }
+    listEvidence(userId, filters, pagination) {
+        return this.store.listEvidence(userId, filters, pagination);
+    }
+    exportMemories(userId) {
+        return this.store.exportMemories(userId);
+    }
+    importMemories(userId, data) {
+        return this.store.importMemories(userId, data);
+    }
+    governanceDelete(userId, recordId, reason) {
+        this.store.hardDeleteMemory(userId, recordId, reason);
+    }
+    getOperationLog(userId, pagination, filters) {
+        return this.store.getOperationLog(userId, pagination, filters);
+    }
+    getStats(userId) {
+        return this.store.getMemoryStats(userId);
+    }
+    getDiagnostics(userId) {
+        const envKeys = Object.keys(process.env)
+            .filter((key) => key.startsWith("BRAINROUTER_") || key.includes("API") || key.includes("SECRET"))
+            .sort();
+        const recentOperations = this.store.getOperationLog(userId, { limit: 50 });
+        const recentErrors = recentOperations
+            .filter((op) => /error|degrad|fail/i.test(`${op.operation} ${op.reason} ${JSON.stringify(op.metadata ?? {})}`))
+            .slice(0, 10);
+        return {
+            timestamp: new Date().toISOString(),
+            sqliteVersion: this.store.getSqliteVersion(),
+            nodeVersion: process.version,
+            databaseStats: {
+                userStats: this.store.getMemoryStats(userId),
+            },
+            envKeys,
+            recentErrors,
+        };
+    }
+    startExtractionSweeper() {
+        if (process.env.BRAINROUTER_DISABLE_EXTRACTION_SWEEPER === "true") {
+            return;
+        }
+        const DEFAULT_INTERVAL_MS = 5 * 60 * 1000; // 5 minutes
+        // Floor at 30s — a user typo of `100` (intended seconds, actually ms)
+        // would otherwise fire the sweeper 10x/second, each tick hammering the
+        // LLM backend with extraction calls for the entire backlog. With a
+        // local LM Studio that's an instant model-unload + flood of 400s.
+        // 30s is a conservative floor that still feels responsive while keeping
+        // backend load sane on consumer hardware.
+        const MIN_INTERVAL_MS = 30 * 1000;
+        const raw = parseInt(process.env.BRAINROUTER_EXTRACTION_SWEEP_INTERVAL_MS ?? String(DEFAULT_INTERVAL_MS), 10);
+        if (!Number.isFinite(raw) || raw <= 0) {
+            return;
+        }
+        let intervalMs = raw;
+        if (intervalMs < MIN_INTERVAL_MS) {
+            console.error(`[BrainRouter] BRAINROUTER_EXTRACTION_SWEEP_INTERVAL_MS=${raw} is below the ${MIN_INTERVAL_MS}ms floor ` +
+                `(value is in MILLISECONDS, not seconds). Clamping to ${MIN_INTERVAL_MS}ms. ` +
+                `Use a value like 60000 (1 min) or 300000 (5 min) for local backends.`);
+            intervalMs = MIN_INTERVAL_MS;
+        }
+        this.sweeperTimer = setInterval(() => {
+            if (this.sweepInProgress) {
+                // Previous tick still running (likely waiting on the LLM semaphore).
+                // Skip this tick instead of stacking a second invocation.
+                return;
+            }
+            this.sweepInProgress = true;
+            this.sweepUnextractedBacklog()
+                .catch((err) => {
+                console.error("[BrainRouter] Extraction backlog sweeper failed:", err instanceof Error ? err.message : err);
+            })
+                .finally(() => {
+                this.sweepInProgress = false;
+            });
+        }, intervalMs);
+        this.sweeperTimer.unref?.();
+    }
+    async sweepUnextractedBacklog() {
+        const olderThanMs = parseInt(process.env.BRAINROUTER_EXTRACTION_SWEEP_MIN_AGE_MS ?? String(2 * 60 * 1000), 10);
+        const maxFailures = parseInt(process.env.BRAINROUTER_EXTRACTION_MAX_FAILURES ?? "5", 10);
+        const backlog = this.store.sweepUnextractedBacklog({
+            olderThanMs: Number.isFinite(olderThanMs) ? olderThanMs : 2 * 60 * 1000,
+            maxFailures: Number.isFinite(maxFailures) ? maxFailures : 5,
+            minUnextracted: 1,
+            limit: 20,
+        });
+        let processed = 0;
+        let extracted = 0;
+        for (const item of backlog) {
+            const result = await this.capturePipeline.processBacklog({
+                userId: item.userId,
+                sessionKey: item.sessionKey,
+                sessionId: item.sessionId,
+            });
+            if (result.triggered) {
+                processed += 1;
+                extracted += result.extractedCount;
+            }
+        }
+        return { candidates: backlog.length, processed, extracted };
+    }
+    // ============================
+    // ACE Feedback Loop
+    // ============================
+    ACE_ARCHIVE_THRESHOLD = (() => {
+        const v = parseInt(process.env.BRAINROUTER_ACE_ARCHIVE_THRESHOLD ?? "10", 10);
+        return isNaN(v) || v <= 0 ? 0 : v;
+    })();
+    markCited(userId, citedRecordIds, allRecalledRecordIds) {
+        if (citedRecordIds.length > 0) {
+            this.store.markCited(userId, citedRecordIds);
+        }
+        if (citedRecordIds.length >= 2) {
+            try {
+                const sparkEngine = new NeuralSparkEngine(this.store);
+                sparkEngine.strengthenSpines(userId, citedRecordIds);
+            }
+            catch (err) {
+                console.error("[BrainRouter] Failed to strengthen spines on citation:", err.message);
+            }
+        }
+        const citedSet = new Set(citedRecordIds);
+        const nonCited = allRecalledRecordIds.filter(id => !citedSet.has(id));
+        if (nonCited.length > 0) {
+            const updated = this.store.incrementNeverCited(userId, nonCited);
+            if (this.ACE_ARCHIVE_THRESHOLD > 0) {
+                for (const { recordId, neverCitedCount } of updated) {
+                    if (neverCitedCount >= this.ACE_ARCHIVE_THRESHOLD) {
+                        this.store.archiveCognitiveRecord(userId, recordId);
+                        console.error(`[BrainRouter] ACE: Auto-archived memory ${recordId} (never_cited_count=${neverCitedCount})`);
+                    }
+                }
+            }
+        }
+        return {
+            cited: citedRecordIds.length,
+            nonCited: nonCited.length,
+            archiveThreshold: this.ACE_ARCHIVE_THRESHOLD,
+        };
+    }
+    // ============================
+    // Point-in-Time Search (asOf)
+    // ============================
+    searchAsOf(userId, query, asOf, limit = 10) {
+        const ts = Date.parse(asOf);
+        if (isNaN(ts)) {
+            throw new Error(`Invalid asOf timestamp: "${asOf}". Must be a valid ISO 8601 date string.`);
+        }
+        const results = this.store.searchCognitiveFtsAsOf(userId, query, limit, asOf);
+        return {
+            memories: results.map(r => ({
+                recordId: r.record_id,
+                content: r.content,
+                type: r.type,
+                score: r.score,
+            })),
+            asOf,
+            count: results.length,
+        };
+    }
+}
+// Singleton export
+export const memoryEngine = new MemoryEngine();

package/dist/memory/llm-semaphore.d.ts

@@ -0,0 +1,41 @@
+/**
+ * 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)
+ */
+/**
+ * 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 declare function acquireLLMSlot(): Promise<() => void>;
+/** Exposed for tests / diagnostics. */
+export declare function getSemaphoreState(): {
+    cap: number;
+    inFlight: number;
+    queued: number;
+};
+/**
+ * Allow tests (or a future /config tool) to reset the cap and clear waiters
+ * without restarting the process.
+ */
+export declare function resetSemaphoreForTests(): void;