@kinqs/brainrouter-mcp-server 0.3.4

package/dist/tools/memory-working.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+import { getWorkingContext, offloadWorkingPayload, resetWorkingMemory, } from "../memory/working/offload.js";
+function toolResult(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+const baseWorkingInput = {
+    workspacePath: z.string().optional(),
+    userId: z.string().optional(),
+    sessionKey: z.string().min(1),
+};
+export const memoryWorkingToolSchemas = [
+    {
+        name: "memory_working_context",
+        description: "Return the current working-memory canvas and injected state block without raw payloads. Optionally fetch one raw ref by nodeId.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspacePath: { type: "string" },
+                userId: { type: "string" },
+                sessionKey: { type: "string" },
+                nodeId: { type: "string", description: "Optional ref node to fetch raw payload for." },
+                activeNodeId: { type: "string", description: "Optional node to highlight in the returned Mermaid canvas." },
+                contextWindowTokens: { type: "number" },
+                estimatedTokens: { type: "number" },
+            },
+            required: ["sessionKey"],
+        },
+    },
+    {
+        name: "memory_working_offload",
+        description: "Offload a large short-term working payload to .brainrouter/work refs and update step log, canvas, and injected state.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspacePath: { type: "string" },
+                userId: { type: "string" },
+                sessionKey: { type: "string" },
+                payload: { type: "string" },
+                title: { type: "string" },
+                summary: { type: "string" },
+                kind: { type: "string" },
+                contextWindowTokens: { type: "number" },
+                estimatedTokens: { type: "number" },
+                forceAggressive: { type: "boolean" },
+            },
+            required: ["sessionKey", "payload"],
+        },
+    },
+    {
+        name: "memory_working_reset",
+        description: "Clear working memory files for a session after session end or when starting a clean task context.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                workspacePath: { type: "string" },
+                userId: { type: "string" },
+                sessionKey: { type: "string" },
+            },
+            required: ["sessionKey"],
+        },
+    },
+];
+export async function handleMemoryWorkingTool(name, args, options) {
+    switch (name) {
+        case "memory_working_context": {
+            const params = z.object({
+                ...baseWorkingInput,
+                nodeId: z.string().optional(),
+                activeNodeId: z.string().optional(),
+                contextWindowTokens: z.number().int().positive().optional(),
+                estimatedTokens: z.number().int().nonnegative().optional(),
+            }).parse(args);
+            const result = getWorkingContext(params.workspacePath, params.userId ?? options?.defaultUserId ?? "default", params.sessionKey, {
+                nodeId: params.nodeId,
+                activeNodeId: params.activeNodeId,
+                contextWindowTokens: params.contextWindowTokens,
+                estimatedTokens: params.estimatedTokens,
+            });
+            return toolResult(result);
+        }
+        case "memory_working_offload": {
+            const params = z.object({
+                ...baseWorkingInput,
+                payload: z.string().min(1),
+                title: z.string().optional(),
+                summary: z.string().optional(),
+                kind: z.string().optional(),
+                contextWindowTokens: z.number().int().positive().optional(),
+                estimatedTokens: z.number().int().nonnegative().optional(),
+                forceAggressive: z.boolean().optional(),
+            }).parse(args);
+            return toolResult(offloadWorkingPayload({ ...params, userId: params.userId ?? options?.defaultUserId ?? "default" }));
+        }
+        case "memory_working_reset": {
+            const params = z.object(baseWorkingInput).parse(args);
+            return toolResult(resetWorkingMemory(params.workspacePath, params.userId ?? options?.defaultUserId ?? "default", params.sessionKey));
+        }
+        default:
+            throw new Error(`Unknown working memory tool: ${name}`);
+    }
+}

package/dist/tools/memory_capture_turn.d.ts

@@ -0,0 +1,66 @@
+export declare const memoryCaptureTurnToolSchema: {
+    readonly name: "memory_capture_turn";
+    readonly description: "Record a completed conversation turn for memory processing. Call this passively after every agent response to ensure accurate tracking.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+                readonly description: "The ID of the user (enforces multi-tenant isolation).";
+            };
+            readonly sessionKey: {
+                readonly type: "string";
+                readonly description: "A stable identifier for this conversation channel/session.";
+            };
+            readonly sessionId: {
+                readonly type: "string";
+                readonly description: "An optional sub-session identifier.";
+            };
+            readonly messages: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "object";
+                    readonly properties: {
+                        readonly role: {
+                            readonly type: "string";
+                            readonly enum: readonly ["user", "assistant", "tool"];
+                        };
+                        readonly content: {
+                            readonly type: "string";
+                        };
+                        readonly timestamp: {
+                            readonly type: "number";
+                            readonly description: "Epoch timestamp in milliseconds";
+                        };
+                    };
+                    readonly required: readonly ["role", "content", "timestamp"];
+                };
+                readonly description: "The new messages that occurred in this turn.";
+            };
+            readonly activeSkill: {
+                readonly type: "string";
+                readonly description: "The name of the BrainRouter skill currently being executed (if any).";
+            };
+            readonly skillHints: {
+                readonly type: "string";
+                readonly description: "Skill-specific extraction hints provided by the active skill.";
+            };
+        };
+        readonly required: readonly ["sessionKey", "messages"];
+    };
+};
+export declare function handleMemoryCaptureTurn(args: any, options?: {
+    defaultUserId?: string;
+}): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/tools/memory_capture_turn.js

@@ -0,0 +1,85 @@
+import { z } from "zod";
+import { memoryEngine } from "../memory/engine.js";
+export const memoryCaptureTurnToolSchema = {
+    name: "memory_capture_turn",
+    description: "Record a completed conversation turn for memory processing. Call this passively after every agent response to ensure accurate tracking.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            userId: {
+                type: "string",
+                description: "The ID of the user (enforces multi-tenant isolation)."
+            },
+            sessionKey: {
+                type: "string",
+                description: "A stable identifier for this conversation channel/session."
+            },
+            sessionId: {
+                type: "string",
+                description: "An optional sub-session identifier."
+            },
+            messages: {
+                type: "array",
+                items: {
+                    type: "object",
+                    properties: {
+                        role: { type: "string", enum: ["user", "assistant", "tool"] },
+                        content: { type: "string" },
+                        timestamp: { type: "number", description: "Epoch timestamp in milliseconds" }
+                    },
+                    required: ["role", "content", "timestamp"]
+                },
+                description: "The new messages that occurred in this turn."
+            },
+            activeSkill: {
+                type: "string",
+                description: "The name of the BrainRouter skill currently being executed (if any)."
+            },
+            skillHints: {
+                type: "string",
+                description: "Skill-specific extraction hints provided by the active skill."
+            }
+        },
+        required: ["sessionKey", "messages"]
+    }
+};
+export async function handleMemoryCaptureTurn(args, options) {
+    const params = z.object({
+        userId: z.string().optional(),
+        sessionKey: z.string(),
+        sessionId: z.string().optional(),
+        messages: z.array(z.object({
+            role: z.enum(["user", "assistant", "tool"]),
+            content: z.string(),
+            timestamp: z.number()
+        })),
+        activeSkill: z.string().optional(),
+        skillHints: z.string().optional()
+    }).parse(args);
+    const effectiveUserId = params.userId ?? options?.defaultUserId ?? "default";
+    try {
+        if (params.activeSkill) {
+            memoryEngine.spikeSkill(effectiveUserId, params.activeSkill);
+        }
+        const result = await memoryEngine.capture({
+            userId: effectiveUserId,
+            sessionKey: params.sessionKey,
+            sessionId: params.sessionId,
+            messages: params.messages,
+            activeSkill: params.activeSkill,
+            skillHints: params.skillHints
+        });
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Capture failed: ${err.message}` }]
+        };
+    }
+}

package/dist/tools/memory_consolidate.d.ts

@@ -0,0 +1,55 @@
+/**
+ * MCP-side memory consolidation. Collapses recall records into per-type
+ * markdown files under `<workspace>/.brainrouter/memories/` so the user
+ * has a human-readable view of what the cognitive memory engine has
+ * learned across sessions.
+ *
+ * The MCP server already exposes recall + capture. This tool exposes the
+ * filesystem consolidation step so any MCP-speaking client can write the
+ * same artifacts without re-implementing the bucketing logic.
+ */
+export declare const memoryConsolidateToolSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            userId: {
+                type: string;
+                description: string;
+            };
+            sessionKey: {
+                type: string;
+                description: string;
+            };
+            workspacePath: {
+                type: string;
+                description: string;
+            };
+            query: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleMemoryConsolidate(args: unknown, options?: {
+    defaultUserId?: string;
+}): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/tools/memory_consolidate.js

@@ -0,0 +1,176 @@
+import { z } from 'zod';
+import fs from 'node:fs';
+import path from 'node:path';
+import { memoryEngine } from '../memory/engine.js';
+/**
+ * MCP-side memory consolidation. Collapses recall records into per-type
+ * markdown files under `<workspace>/.brainrouter/memories/` so the user
+ * has a human-readable view of what the cognitive memory engine has
+ * learned across sessions.
+ *
+ * The MCP server already exposes recall + capture. This tool exposes the
+ * filesystem consolidation step so any MCP-speaking client can write the
+ * same artifacts without re-implementing the bucketing logic.
+ */
+export const memoryConsolidateToolSchema = {
+    name: 'memory_consolidate',
+    description: 'Read recent memory records and write them to per-type markdown files ' +
+        '(user.md, feedback.md, project.md, reference.md, raw_memories.md, MEMORY.md) ' +
+        'under <workspacePath>/.brainrouter/memories/. Use this at session end or on demand ' +
+        'to produce a human-readable consolidation of what the agent learned.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            userId: { type: 'string', description: 'User identifier for isolation' },
+            sessionKey: { type: 'string', description: 'Session identifier' },
+            workspacePath: { type: 'string', description: 'Absolute path to the workspace where files will be written.' },
+            query: { type: 'string', description: 'Optional query to filter records before consolidation. Defaults to "*".' },
+            limit: { type: 'number', description: 'Max records to consider (default 200).' },
+        },
+        required: ['sessionKey', 'workspacePath'],
+    },
+};
+const inputSchema = z.object({
+    userId: z.string().optional(),
+    sessionKey: z.string(),
+    workspacePath: z.string(),
+    query: z.string().optional(),
+    limit: z.number().int().positive().optional(),
+});
+export async function handleMemoryConsolidate(args, options) {
+    const params = inputSchema.parse(args);
+    const effectiveUserId = params.userId ?? options?.defaultUserId ?? 'default';
+    const limit = params.limit ?? 200;
+    const query = params.query ?? '*';
+    try {
+        const result = await memoryEngine.recall({
+            userId: effectiveUserId,
+            sessionKey: params.sessionKey,
+            query,
+        });
+        const records = extractRecords(result ?? {});
+        if (records.length > limit)
+            records.length = limit;
+        const dir = path.join(params.workspacePath, '.brainrouter', 'memories');
+        fs.mkdirSync(path.join(dir, 'rollout_summaries'), { recursive: true });
+        const buckets = { user: [], feedback: [], project: [], reference: [], raw: [] };
+        for (const rec of records) {
+            const t = String(rec.type ?? '').toLowerCase();
+            if (t === 'user' || t === 'feedback' || t === 'project' || t === 'reference') {
+                buckets[t].push(rec);
+            }
+            else {
+                buckets.raw.push(rec);
+            }
+        }
+        const filesWritten = [];
+        for (const t of ['user', 'feedback', 'project', 'reference', 'raw']) {
+            const file = path.join(dir, t === 'raw' ? 'raw_memories.md' : `${t}.md`);
+            fs.writeFileSync(file, renderTypeFile(t, buckets[t]), 'utf8');
+            filesWritten.push(path.relative(params.workspacePath, file));
+        }
+        const indexFile = path.join(dir, 'MEMORY.md');
+        fs.writeFileSync(indexFile, renderIndex(records, buckets), 'utf8');
+        filesWritten.push(path.relative(params.workspacePath, indexFile));
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        totalRecords: records.length,
+                        perType: Object.fromEntries(Object.entries(buckets).map(([k, v]) => [k, v.length])),
+                        files: filesWritten,
+                        dir: path.relative(params.workspacePath, dir),
+                    }, null, 2),
+                }],
+        };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [{ type: 'text', text: `memory_consolidate failed: ${err.message}` }],
+        };
+    }
+}
+function extractRecords(parsed) {
+    if (!parsed)
+        return [];
+    const sources = [
+        parsed.records, parsed.results, parsed.items,
+        Array.isArray(parsed) ? parsed : undefined,
+    ].filter((x) => Array.isArray(x));
+    for (const list of sources) {
+        const out = [];
+        for (const r of list) {
+            if (!r)
+                continue;
+            const recordId = String(r.recordId ?? r.id ?? r.record_id ?? '');
+            if (!recordId)
+                continue;
+            out.push({
+                recordId,
+                type: String(r.type ?? r.memoryType ?? 'raw'),
+                content: String(r.content ?? r.text ?? r.body ?? r.summary ?? ''),
+                scene: r.scene ?? r.focusScene,
+                capturedAt: r.capturedAt ?? r.createdAt ?? r.timestamp,
+            });
+        }
+        if (out.length > 0)
+            return out;
+    }
+    return [];
+}
+function renderTypeFile(type, records) {
+    const heading = type === 'raw' ? 'Raw memories' : `${cap(type)} memory`;
+    const intro = type === 'raw'
+        ? 'Memories that were not classified into user/feedback/project/reference.'
+        : descriptionFor(type);
+    if (records.length === 0) {
+        return `# ${heading}\n\n${intro}\n\n_(empty — no records of this type yet)_\n`;
+    }
+    const body = records.sort((a, b) => a.recordId.localeCompare(b.recordId)).map(renderRecord).join('\n\n');
+    return `# ${heading}\n\n${intro}\n\n${body}\n`;
+}
+function renderRecord(rec) {
+    const lines = [`## ${rec.recordId}`];
+    if (rec.scene)
+        lines.push(`*Scene: ${rec.scene}*`);
+    if (rec.capturedAt)
+        lines.push(`*Captured: ${rec.capturedAt}*`);
+    lines.push('', rec.content.trim());
+    return lines.join('\n');
+}
+function renderIndex(records, buckets) {
+    const lines = [];
+    lines.push('# Memory index');
+    lines.push('');
+    lines.push(`_${records.length} consolidated memory records across ${Object.keys(buckets).length} files._`);
+    lines.push('');
+    for (const t of ['user', 'feedback', 'project', 'reference', 'raw']) {
+        const list = buckets[t];
+        if (list.length === 0)
+            continue;
+        const file = t === 'raw' ? 'raw_memories.md' : `${t}.md`;
+        lines.push(`## ${cap(t)} (${list.length})`);
+        lines.push(`File: [${file}](${file})`);
+        lines.push('');
+        for (const r of list.slice(0, 12)) {
+            lines.push(`- \`${r.recordId}\` — ${r.content.split('\n')[0].slice(0, 140)}`);
+        }
+        if (list.length > 12)
+            lines.push(`- _…and ${list.length - 12} more in ${file}_`);
+        lines.push('');
+    }
+    return lines.join('\n');
+}
+function descriptionFor(type) {
+    switch (type) {
+        case 'user': return 'Profile facts about the user — role, expertise, goals.';
+        case 'feedback': return 'Validated guidance from the user about how to approach work (do/avoid).';
+        case 'project': return 'In-flight project context: deadlines, stakeholders, motivation.';
+        case 'reference': return 'Pointers to external systems (Linear, Grafana, GitHub) where authoritative info lives.';
+        default: return '';
+    }
+}
+function cap(s) {
+    return s ? s[0].toUpperCase() + s.slice(1) : s;
+}

package/dist/tools/memory_contradictions.d.ts

@@ -0,0 +1,53 @@
+import { z } from 'zod';
+export declare const memoryContradictionsToolSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            userId: {
+                type: string;
+                description: string;
+            };
+            action: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            contradictionId: {
+                type: string;
+                description: string;
+            };
+            resolutionStatus: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+        };
+        required: never[];
+    };
+};
+export declare const memoryContradictionsSchema: z.ZodObject<{
+    userId: z.ZodOptional<z.ZodString>;
+    action: z.ZodDefault<z.ZodEnum<["list", "resolve"]>>;
+    contradictionId: z.ZodOptional<z.ZodString>;
+    resolutionStatus: z.ZodOptional<z.ZodEnum<["resolved", "dismissed"]>>;
+}, "strip", z.ZodTypeAny, {
+    action: "list" | "resolve";
+    contradictionId?: string | undefined;
+    userId?: string | undefined;
+    resolutionStatus?: "resolved" | "dismissed" | undefined;
+}, {
+    contradictionId?: string | undefined;
+    userId?: string | undefined;
+    action?: "list" | "resolve" | undefined;
+    resolutionStatus?: "resolved" | "dismissed" | undefined;
+}>;
+export declare function handleMemoryContradictions(args: unknown, options?: {
+    defaultUserId?: string;
+}): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/tools/memory_contradictions.js

@@ -0,0 +1,52 @@
+import { z } from 'zod';
+import { memoryEngine } from '../memory/engine.js';
+export const memoryContradictionsToolSchema = {
+    name: 'memory_contradictions',
+    description: 'List unresolved semantic contradictions in memory or resolve them. Default action is "list". If action is "resolve", provide contradictionId and resolutionStatus.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            userId: { type: 'string', description: 'User identifier' },
+            action: { type: 'string', enum: ['list', 'resolve'], description: 'Action to perform. Default is list.' },
+            contradictionId: { type: 'string', description: 'ID of the contradiction to resolve (required if action is resolve)' },
+            resolutionStatus: { type: 'string', enum: ['resolved', 'dismissed'], description: 'Status to set (required if action is resolve)' },
+        },
+        required: [],
+    },
+};
+export const memoryContradictionsSchema = z.object({
+    userId: z.string().optional(),
+    action: z.enum(['list', 'resolve']).default('list'),
+    contradictionId: z.string().optional(),
+    resolutionStatus: z.enum(['resolved', 'dismissed']).optional(),
+});
+export async function handleMemoryContradictions(args, options) {
+    const { userId, action, contradictionId, resolutionStatus } = memoryContradictionsSchema.parse(args);
+    const effectiveUserId = userId ?? options?.defaultUserId ?? "default";
+    if (action === 'resolve') {
+        if (!contradictionId || !resolutionStatus) {
+            throw new Error('contradictionId and resolutionStatus are required when action is "resolve"');
+        }
+        memoryEngine.resolveContradiction(contradictionId, effectiveUserId, resolutionStatus);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Successfully marked contradiction ${contradictionId} as ${resolutionStatus}.`,
+                },
+            ],
+        };
+    }
+    // Handle 'list' action
+    const results = memoryEngine.getPendingContradictions(effectiveUserId);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: results.length > 0
+                    ? JSON.stringify(results, null, 2)
+                    : "No pending contradictions found.",
+            },
+        ],
+    };
+}

package/dist/tools/memory_graph_query.d.ts

@@ -0,0 +1,51 @@
+import { z } from 'zod';
+export declare const memoryGraphQueryToolSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            userId: {
+                type: string;
+                description: string;
+            };
+            entity: {
+                type: string;
+                description: string;
+            };
+            skillTag: {
+                type: string;
+                description: string;
+            };
+            maxHops: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare const memoryGraphQuerySchema: z.ZodObject<{
+    userId: z.ZodOptional<z.ZodString>;
+    entity: z.ZodString;
+    skillTag: z.ZodOptional<z.ZodString>;
+    maxHops: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    entity: string;
+    userId?: string | undefined;
+    skillTag?: string | undefined;
+    maxHops?: number | undefined;
+}, {
+    entity: string;
+    userId?: string | undefined;
+    skillTag?: string | undefined;
+    maxHops?: number | undefined;
+}>;
+export declare function handleMemoryGraphQuery(args: unknown, options?: {
+    defaultUserId?: string;
+}): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/tools/memory_graph_query.js

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import { memoryEngine } from '../memory/engine.js';
+export const memoryGraphQueryToolSchema = {
+    name: 'memory_graph_query',
+    description: 'Query the GraphRAG knowledge graph to retrieve entities and relationships within 2 hops of a starting entity, optionally filtered by active skill.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            userId: { type: 'string', description: 'User identifier for isolation' },
+            entity: { type: 'string', description: 'The starting entity to search for' },
+            skillTag: { type: 'string', description: 'Filter relationships matching this skill' },
+            maxHops: { type: 'number', description: 'Max hops to traverse (default 2)' },
+        },
+        required: ['entity'],
+    },
+};
+export const memoryGraphQuerySchema = z.object({
+    userId: z.string().optional(),
+    entity: z.string(),
+    skillTag: z.string().optional(),
+    maxHops: z.number().optional(),
+});
+export async function handleMemoryGraphQuery(args, options) {
+    const params = memoryGraphQuerySchema.parse(args);
+    const effectiveUserId = params.userId ?? options?.defaultUserId ?? "default";
+    const result = memoryEngine.queryGraph(effectiveUserId, params.entity, params.skillTag, params.maxHops);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+}