@kinqs/brainrouter-mcp-server 0.3.4 → 0.3.6

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

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

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

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

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

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

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

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

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

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

package/dist/memory/pipeline/l2-direction-shift.js

@@ -1,27 +0,0 @@
-import { L2_DIRECTION_SHIFT_SYSTEM_PROMPT, formatL2DirectionShiftPrompt } from "../prompts/l2-direction-shift.js";
-export async function detectDirectionShift(params) {
-    const { activeScene, newL1Records, llmRunner } = params;
-    try {
-        const prompt = formatL2DirectionShiftPrompt(activeScene.sceneName, activeScene.summaryMd, newL1Records.map(r => ({ content: r.content, type: r.type })));
-        const response = await llmRunner.run({
-            prompt,
-            systemPrompt: L2_DIRECTION_SHIFT_SYSTEM_PROMPT,
-            taskId: "l2-direction-shift",
-            timeoutMs: 30_000,
-        });
-        const jsonMatch = response.match(/\{[\s\S]*\}/);
-        if (!jsonMatch) {
-            throw new Error("No JSON object found in LLM response");
-        }
-        const parsed = JSON.parse(jsonMatch[0]);
-        return {
-            shift: Boolean(parsed.shift),
-            confidence: Number(parsed.confidence) || 0,
-            reason: String(parsed.reason) || "",
-        };
-    }
-    catch (err) {
-        console.error(`[BrainRouter] L2 direction shift detection failed:`, err.message);
-        return { shift: false, confidence: 0, reason: "Error" };
-    }
-}

package/dist/memory/pipeline/l2-scene.d.ts

@@ -1,15 +0,0 @@
-import type { IMemoryStore } from "@brainrouter/types";
-import type { LLMRunner } from "@brainrouter/types";
-/**
- * L2 Scene Pipeline
- * Groups L1 memories by scene_name and asks the LLM to produce
- * a Markdown summary for each scene. Updates heat scores.
- */
-export declare function distillScenes(params: {
-    userId: string;
-    store: IMemoryStore;
-    llmRunner: LLMRunner;
-}): Promise<{
-    scenesDistilled: number;
-    sceneNames: string[];
-}>;

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

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

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

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

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

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

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

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