@kinqs/brainrouter-mcp-server 0.3.4

package/dist/tools/memory-engineering.d.ts

@@ -0,0 +1,225 @@
+export declare const memoryEngineeringToolSchemas: readonly [{
+    readonly name: "memory_debug_trace_save";
+    readonly description: "Save an engineering debug trace, including repro, cause, fix, verification, files, and commands.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly sessionKey: {
+                readonly type: "string";
+            };
+            readonly activeSkill: {
+                readonly type: "string";
+            };
+            readonly symptom: {
+                readonly type: "string";
+            };
+            readonly reproSteps: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly suspectedCause: {
+                readonly type: "string";
+            };
+            readonly confirmedCause: {
+                readonly type: "string";
+            };
+            readonly fixSummary: {
+                readonly type: "string";
+            };
+            readonly verificationResult: {
+                readonly type: "string";
+            };
+            readonly failedAttempt: {
+                readonly type: "string";
+            };
+            readonly filePaths: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly commands: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly required: readonly ["symptom"];
+    };
+}, {
+    readonly name: "memory_debug_trace_search";
+    readonly description: "Search prior engineering debug traces by error, file, command, or symptom.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly query: {
+                readonly type: "string";
+            };
+            readonly limit: {
+                readonly type: "number";
+            };
+        };
+        readonly required: readonly ["query"];
+    };
+}, {
+    readonly name: "memory_failed_attempts";
+    readonly description: "Return previously recorded failed attempts for a problem area.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly query: {
+                readonly type: "string";
+            };
+            readonly limit: {
+                readonly type: "number";
+            };
+        };
+        readonly required: readonly ["query"];
+    };
+}, {
+    readonly name: "memory_file_history";
+    readonly description: "Return memories and evidence associated with a file path or symbol.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly filePath: {
+                readonly type: "string";
+            };
+            readonly limit: {
+                readonly type: "number";
+            };
+        };
+        readonly required: readonly ["filePath"];
+    };
+}, {
+    readonly name: "memory_task_state";
+    readonly description: "Read current task or handover state for a repo/session.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly query: {
+                readonly type: "string";
+            };
+            readonly limit: {
+                readonly type: "number";
+            };
+        };
+    };
+}, {
+    readonly name: "memory_task_update";
+    readonly description: "Write structured task progress, blockers, and next actions.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly sessionKey: {
+                readonly type: "string";
+            };
+            readonly activeSkill: {
+                readonly type: "string";
+            };
+            readonly status: {
+                readonly type: "string";
+            };
+            readonly completed: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly blockers: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly nextActions: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly filePaths: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+        };
+        readonly required: readonly ["status"];
+    };
+}, {
+    readonly name: "memory_handover";
+    readonly description: "Generate a compact continuation note from current task memories.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly query: {
+                readonly type: "string";
+            };
+            readonly limit: {
+                readonly type: "number";
+            };
+        };
+    };
+}, {
+    readonly name: "memory_verify";
+    readonly description: "Update verification status and confidence for a memory after re-checking it.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly recordId: {
+                readonly type: "string";
+            };
+            readonly confidence: {
+                readonly type: "number";
+            };
+            readonly status: {
+                readonly type: "string";
+                readonly enum: readonly ["active", "superseded", "archived", "needs_verification"];
+            };
+            readonly verificationStatus: {
+                readonly type: "string";
+                readonly enum: readonly ["", "verified", "unverified", "stale"];
+            };
+            readonly note: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["recordId", "verificationStatus"];
+    };
+}];
+export declare function handleMemoryEngineeringTool(name: string, args: unknown, options?: {
+    defaultUserId?: string;
+}): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/tools/memory-engineering.js

@@ -0,0 +1,284 @@
+import { z } from "zod";
+import { memoryEngine } from "../memory/engine.js";
+const baseUser = { userId: z.string().optional() };
+function effectiveUserId(userId, defaultUserId) {
+    return userId ?? defaultUserId ?? "default";
+}
+function toolResult(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+const stringList = z.array(z.string()).optional().default([]);
+export const memoryEngineeringToolSchemas = [
+    {
+        name: "memory_debug_trace_save",
+        description: "Save an engineering debug trace, including repro, cause, fix, verification, files, and commands.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                userId: { type: "string" },
+                sessionKey: { type: "string" },
+                activeSkill: { type: "string" },
+                symptom: { type: "string" },
+                reproSteps: { type: "array", items: { type: "string" } },
+                suspectedCause: { type: "string" },
+                confirmedCause: { type: "string" },
+                fixSummary: { type: "string" },
+                verificationResult: { type: "string" },
+                failedAttempt: { type: "string" },
+                filePaths: { type: "array", items: { type: "string" } },
+                commands: { type: "array", items: { type: "string" } },
+            },
+            required: ["symptom"],
+        },
+    },
+    {
+        name: "memory_debug_trace_search",
+        description: "Search prior engineering debug traces by error, file, command, or symptom.",
+        inputSchema: {
+            type: "object",
+            properties: { userId: { type: "string" }, query: { type: "string" }, limit: { type: "number" } },
+            required: ["query"],
+        },
+    },
+    {
+        name: "memory_failed_attempts",
+        description: "Return previously recorded failed attempts for a problem area.",
+        inputSchema: {
+            type: "object",
+            properties: { userId: { type: "string" }, query: { type: "string" }, limit: { type: "number" } },
+            required: ["query"],
+        },
+    },
+    {
+        name: "memory_file_history",
+        description: "Return memories and evidence associated with a file path or symbol.",
+        inputSchema: {
+            type: "object",
+            properties: { userId: { type: "string" }, filePath: { type: "string" }, limit: { type: "number" } },
+            required: ["filePath"],
+        },
+    },
+    {
+        name: "memory_task_state",
+        description: "Read current task or handover state for a repo/session.",
+        inputSchema: {
+            type: "object",
+            properties: { userId: { type: "string" }, query: { type: "string" }, limit: { type: "number" } },
+        },
+    },
+    {
+        name: "memory_task_update",
+        description: "Write structured task progress, blockers, and next actions.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                userId: { type: "string" },
+                sessionKey: { type: "string" },
+                activeSkill: { type: "string" },
+                status: { type: "string" },
+                completed: { type: "array", items: { type: "string" } },
+                blockers: { type: "array", items: { type: "string" } },
+                nextActions: { type: "array", items: { type: "string" } },
+                filePaths: { type: "array", items: { type: "string" } },
+            },
+            required: ["status"],
+        },
+    },
+    {
+        name: "memory_handover",
+        description: "Generate a compact continuation note from current task memories.",
+        inputSchema: {
+            type: "object",
+            properties: { userId: { type: "string" }, query: { type: "string" }, limit: { type: "number" } },
+        },
+    },
+    {
+        name: "memory_verify",
+        description: "Update verification status and confidence for a memory after re-checking it.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                userId: { type: "string" },
+                recordId: { type: "string" },
+                confidence: { type: "number" },
+                status: { type: "string", enum: ["active", "superseded", "archived", "needs_verification"] },
+                verificationStatus: { type: "string", enum: ["", "verified", "unverified", "stale"] },
+                note: { type: "string" },
+            },
+            required: ["recordId", "verificationStatus"],
+        },
+    },
+];
+export async function handleMemoryEngineeringTool(name, args, options) {
+    switch (name) {
+        case "memory_debug_trace_save": {
+            const params = z.object({
+                ...baseUser,
+                sessionKey: z.string().optional(),
+                activeSkill: z.string().optional(),
+                symptom: z.string().min(1),
+                reproSteps: stringList,
+                suspectedCause: z.string().optional(),
+                confirmedCause: z.string().optional(),
+                fixSummary: z.string().optional(),
+                verificationResult: z.string().optional(),
+                failedAttempt: z.string().optional(),
+                filePaths: stringList,
+                commands: stringList,
+            }).parse(args);
+            const userId = effectiveUserId(params.userId, options?.defaultUserId);
+            const records = [
+                memoryEngine.upsertEngineeringMemory({
+                    userId,
+                    sessionKey: params.sessionKey,
+                    activeSkill: params.activeSkill,
+                    type: "bug_finding",
+                    content: `Bug finding: ${params.symptom}${params.confirmedCause ? `. Confirmed cause: ${params.confirmedCause}` : ""}`,
+                    priority: 85,
+                    sourceKind: "user_instruction",
+                    filePaths: params.filePaths,
+                    commands: params.commands,
+                }),
+                memoryEngine.upsertEngineeringMemory({
+                    userId,
+                    sessionKey: params.sessionKey,
+                    activeSkill: params.activeSkill,
+                    type: "debug_trace",
+                    content: [
+                        `Debug symptom: ${params.symptom}`,
+                        params.reproSteps.length ? `Repro steps: ${params.reproSteps.join("; ")}` : "",
+                        params.suspectedCause ? `Suspected cause: ${params.suspectedCause}` : "",
+                        params.confirmedCause ? `Confirmed cause: ${params.confirmedCause}` : "",
+                    ].filter(Boolean).join(". "),
+                    priority: 80,
+                    sourceKind: "user_instruction",
+                    filePaths: params.filePaths,
+                    commands: params.commands,
+                    metadata: { reproSteps: params.reproSteps },
+                }),
+            ];
+            if (params.failedAttempt) {
+                records.push(memoryEngine.upsertEngineeringMemory({
+                    userId,
+                    sessionKey: params.sessionKey,
+                    activeSkill: params.activeSkill,
+                    type: "failed_attempt",
+                    content: `Failed attempt: ${params.failedAttempt}`,
+                    priority: 70,
+                    filePaths: params.filePaths,
+                    commands: params.commands,
+                }));
+            }
+            if (params.fixSummary) {
+                records.push(memoryEngine.upsertEngineeringMemory({
+                    userId,
+                    sessionKey: params.sessionKey,
+                    activeSkill: params.activeSkill,
+                    type: "fix_summary",
+                    content: `Fix summary: ${params.fixSummary}`,
+                    priority: 80,
+                    filePaths: params.filePaths,
+                    commands: params.commands,
+                }));
+            }
+            if (params.verificationResult) {
+                records.push(memoryEngine.upsertEngineeringMemory({
+                    userId,
+                    sessionKey: params.sessionKey,
+                    activeSkill: params.activeSkill,
+                    type: "verification_result",
+                    content: `Verification result: ${params.verificationResult}`,
+                    priority: 75,
+                    sourceKind: "test_result",
+                    verificationStatus: "verified",
+                    filePaths: params.filePaths,
+                    commands: params.commands,
+                }));
+            }
+            return toolResult({ records });
+        }
+        case "memory_debug_trace_search": {
+            const params = z.object({ ...baseUser, query: z.string(), limit: z.number().int().min(1).max(100).optional().default(20) }).parse(args);
+            const hits = memoryEngine.searchMemoryRecords(effectiveUserId(params.userId, options?.defaultUserId), params.query, params.limit)
+                .filter((hit) => ["bug_finding", "debug_trace", "fix_summary", "verification_result", "failed_attempt"].includes(hit.type));
+            return toolResult(hits);
+        }
+        case "memory_failed_attempts": {
+            const params = z.object({ ...baseUser, query: z.string(), limit: z.number().int().min(1).max(100).optional().default(20) }).parse(args);
+            const hits = memoryEngine.searchMemoryRecords(effectiveUserId(params.userId, options?.defaultUserId), params.query, params.limit)
+                .filter((hit) => hit.type === "failed_attempt");
+            return toolResult(hits);
+        }
+        case "memory_file_history": {
+            const params = z.object({ ...baseUser, filePath: z.string(), limit: z.number().int().min(1).max(100).optional().default(20) }).parse(args);
+            return toolResult(memoryEngine.getMemoriesByFilePath(effectiveUserId(params.userId, options?.defaultUserId), params.filePath, params.limit));
+        }
+        case "memory_task_state": {
+            const params = z.object({ ...baseUser, query: z.string().optional().default("task state handover blocked next actions"), limit: z.number().int().min(1).max(100).optional().default(20) }).parse(args ?? {});
+            const hits = memoryEngine.searchMemoryRecords(effectiveUserId(params.userId, options?.defaultUserId), params.query, params.limit)
+                .filter((hit) => ["task_state", "handover_note", "blocked_reason"].includes(hit.type));
+            return toolResult(hits);
+        }
+        case "memory_task_update": {
+            const params = z.object({
+                ...baseUser,
+                sessionKey: z.string().optional(),
+                activeSkill: z.string().optional(),
+                status: z.string().min(1),
+                completed: stringList,
+                blockers: stringList,
+                nextActions: stringList,
+                filePaths: stringList,
+            }).parse(args);
+            const userId = effectiveUserId(params.userId, options?.defaultUserId);
+            const record = memoryEngine.upsertEngineeringMemory({
+                userId,
+                sessionKey: params.sessionKey,
+                activeSkill: params.activeSkill,
+                type: params.blockers.length > 0 ? "blocked_reason" : "task_state",
+                content: [
+                    `Task status: ${params.status}`,
+                    params.completed.length ? `Completed: ${params.completed.join("; ")}` : "",
+                    params.blockers.length ? `Blockers: ${params.blockers.join("; ")}` : "",
+                    params.nextActions.length ? `Next actions: ${params.nextActions.join("; ")}` : "",
+                ].filter(Boolean).join(". "),
+                priority: params.blockers.length > 0 ? 85 : 80,
+                filePaths: params.filePaths,
+                metadata: {
+                    completed: params.completed,
+                    blockers: params.blockers,
+                    nextActions: params.nextActions,
+                },
+            });
+            return toolResult(record);
+        }
+        case "memory_handover": {
+            const params = z.object({ ...baseUser, query: z.string().optional().default("handover task state next actions"), limit: z.number().int().min(1).max(50).optional().default(10) }).parse(args ?? {});
+            const hits = memoryEngine.searchMemoryRecords(effectiveUserId(params.userId, options?.defaultUserId), params.query, params.limit)
+                .filter((hit) => ["task_state", "handover_note", "blocked_reason", "fix_summary", "verification_result"].includes(hit.type));
+            return toolResult({
+                handover: hits.map((hit) => `- [${hit.type}] ${hit.content}`).join("\n"),
+                records: hits,
+            });
+        }
+        case "memory_verify": {
+            const params = z.object({
+                ...baseUser,
+                recordId: z.string(),
+                confidence: z.number().min(0).max(1).optional(),
+                status: z.enum(["active", "superseded", "archived", "needs_verification"]).optional(),
+                verificationStatus: z.enum(["", "verified", "unverified", "stale"]),
+                note: z.string().optional(),
+            }).parse(args);
+            const result = memoryEngine.updateMemory(effectiveUserId(params.userId, options?.defaultUserId), params.recordId, {
+                confidence: params.confidence,
+                status: params.status,
+                verificationStatus: params.verificationStatus,
+                note: params.note,
+            });
+            return toolResult(result);
+        }
+        default:
+            throw new Error(`Unknown engineering memory tool: ${name}`);
+    }
+}

package/dist/tools/memory-explain.d.ts

@@ -0,0 +1,34 @@
+export declare const memoryExplainToolSchema: {
+    readonly name: "memory_explain_recall";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly query: {
+                readonly type: "string";
+                readonly description: "The query to explain recall for.";
+            };
+            readonly userId: {
+                readonly type: "string";
+                readonly description: "User ID to run explain against. Defaults to the authenticated user.";
+            };
+            readonly sessionKey: {
+                readonly type: "string";
+                readonly description: "Session key for the recall context.";
+            };
+            readonly activeSkill: {
+                readonly type: "string";
+                readonly description: "Active skill to simulate skill-boost scoring.";
+            };
+        };
+        readonly required: readonly ["query"];
+    };
+};
+export declare function handleMemoryExplainRecall(args: unknown, context: {
+    defaultUserId: string;
+}): Promise<{
+    content: [{
+        type: "text";
+        text: string;
+    }];
+}>;

package/dist/tools/memory-explain.js

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { memoryEngine } from "../memory/engine.js";
+// ── Schema ────────────────────────────────────────────────────────────────────
+export const memoryExplainToolSchema = {
+    name: "memory_explain_recall",
+    description: "Re-run a recall query in explain mode. Returns the full pipeline breakdown: FTS hits, vector hits, " +
+        "RRF scores, intent detected, type boosts, skill boost, reranker status, graph expansion, and per-record scores. " +
+        "Use this to debug why specific memories did or didn't surface for a query.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            query: {
+                type: "string",
+                description: "The query to explain recall for.",
+            },
+            userId: {
+                type: "string",
+                description: "User ID to run explain against. Defaults to the authenticated user.",
+            },
+            sessionKey: {
+                type: "string",
+                description: "Session key for the recall context.",
+            },
+            activeSkill: {
+                type: "string",
+                description: "Active skill to simulate skill-boost scoring.",
+            },
+        },
+        required: ["query"],
+    },
+};
+const memoryExplainInputSchema = z.object({
+    query: z.string().min(1, "Query must not be empty"),
+    userId: z.string().optional(),
+    sessionKey: z.string().optional(),
+    activeSkill: z.string().optional(),
+});
+// ── Handler ───────────────────────────────────────────────────────────────────
+export async function handleMemoryExplainRecall(args, context) {
+    const input = memoryExplainInputSchema.parse(args);
+    const userId = input.userId ?? context.defaultUserId;
+    const sessionKey = input.sessionKey ?? `explain_${Date.now()}`;
+    const result = await memoryEngine.explainRecall({
+        userId,
+        sessionKey,
+        query: input.query,
+        activeSkill: input.activeSkill,
+    });
+    const explanation = result.recallExplanation;
+    const lines = [
+        `## Recall Explain: "${input.query}"`,
+        "",
+        `**Strategy**: ${result.recallStrategy}`,
+        `**Duration**: ${explanation?.durationMs ?? 0}ms`,
+        `**Intent Detected**: ${explanation?.intentDetected ?? "none"}`,
+        "",
+        "### Search Hits",
+        `- FTS5 hits: ${explanation?.ftsHits ?? 0}`,
+        `- Vector hits: ${explanation?.vecHits ?? 0}`,
+        `- File-path expansion hits: ${explanation?.filePathHits ?? 0}`,
+        `- Top RRF score: ${explanation?.rrfTopScore?.toFixed(4) ?? "n/a"}`,
+        "",
+        "### Boosting",
+        `- Reranker used: ${explanation?.rerankerUsed ? "yes" : "no"} (candidates: ${explanation?.rerankerCandidates ?? 0})`,
+        `- Skill boost applied: ${explanation?.skillBoostApplied ? "yes" : "no"}`,
+        `- Graph expansion: ${explanation?.graphExpansion ? "yes" : "no"}`,
+    ];
+    if (explanation?.typeBoosts && Object.keys(explanation.typeBoosts).length > 0) {
+        lines.push("", "### Intent Type Boosts");
+        for (const [type, boost] of Object.entries(explanation.typeBoosts)) {
+            lines.push(`- ${type}: ${boost.toFixed(2)}×`);
+        }
+    }
+    if (explanation?.citationBoosts && Object.keys(explanation.citationBoosts).length > 0) {
+        lines.push("", "### Citation Boosts (recordId → boost)");
+        for (const [id, boost] of Object.entries(explanation.citationBoosts)) {
+            lines.push(`- ${id}: +${(boost * 100).toFixed(0)}%`);
+        }
+    }
+    const previewByRecordId = new Map();
+    for (const m of (result.recalledCognitiveMemories ?? [])) {
+        if (m?.recordId)
+            previewByRecordId.set(m.recordId, { type: m.type, content: m.content });
+    }
+    const shortenId = (id) => {
+        const tail = id.split(/[:_]/).pop() ?? id;
+        return tail.length > 12 ? tail.slice(0, 8) : tail;
+    };
+    const oneLine = (s, max = 100) => {
+        const flat = s.replace(/\s+/g, " ").trim();
+        return flat.length > max ? flat.slice(0, max - 1) + "…" : flat;
+    };
+    if (explanation?.scoredRecords && explanation.scoredRecords.length > 0) {
+        lines.push("", "### Ranked Results");
+        explanation.scoredRecords.forEach((r, i) => {
+            const preview = previewByRecordId.get(r.recordId);
+            const snippet = preview?.content ? oneLine(preview.content) : "";
+            lines.push(`${i + 1}. **[${r.type}]** ${r.finalScore.toFixed(4)} · \`${shortenId(r.recordId)}\``);
+            if (snippet)
+                lines.push(`   ${snippet}`);
+        });
+    }
+    else {
+        lines.push("", "_(No memories matched this query)_");
+    }
+    return {
+        content: [{ type: "text", text: lines.join("\n") }],
+    };
+}