@kinqs/brainrouter-mcp-server 0.3.4

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

@@ -0,0 +1,171 @@
+export declare const memoryGovernanceToolSchemas: readonly [{
+    readonly name: "memory_get";
+    readonly description: "Fetch a specific memory with attached evidence.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly recordId: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["recordId"];
+    };
+}, {
+    readonly name: "memory_update";
+    readonly description: "Correct memory content or update trust/status metadata.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly recordId: {
+                readonly type: "string";
+            };
+            readonly content: {
+                readonly type: "string";
+            };
+            readonly status: {
+                readonly type: "string";
+                readonly enum: readonly ["active", "superseded", "archived", "needs_verification"];
+            };
+            readonly confidence: {
+                readonly type: "number";
+            };
+            readonly verificationStatus: {
+                readonly type: "string";
+                readonly enum: readonly ["", "verified", "unverified", "stale"];
+            };
+            readonly note: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["recordId"];
+    };
+}, {
+    readonly name: "memory_evidence_add";
+    readonly description: "Attach evidence to a memory.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly recordId: {
+                readonly type: "string";
+            };
+            readonly kind: {
+                readonly type: "string";
+                readonly enum: readonly ["file", "command", "url", "test", "benchmark", "memory", "other"];
+            };
+            readonly ref: {
+                readonly type: "string";
+            };
+            readonly excerpt: {
+                readonly type: "string";
+            };
+            readonly metadata: {
+                readonly type: "object";
+            };
+        };
+        readonly required: readonly ["recordId", "kind", "ref"];
+    };
+}, {
+    readonly name: "memory_evidence_get";
+    readonly description: "Retrieve evidence attached to a memory.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly recordId: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["recordId"];
+    };
+}, {
+    readonly name: "memory_export";
+    readonly description: "Export all memories, evidence, and audit operations for a user.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+        };
+    };
+}, {
+    readonly name: "memory_import";
+    readonly description: "Import a BrainRouter memory export envelope.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly data: {
+                readonly type: "object";
+            };
+        };
+        readonly required: readonly ["data"];
+    };
+}, {
+    readonly name: "memory_governance_delete";
+    readonly description: "Hard delete a memory and write an audit record.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly recordId: {
+                readonly type: "string";
+            };
+            readonly reason: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["recordId", "reason"];
+    };
+}, {
+    readonly name: "memory_audit";
+    readonly description: "List memory audit log entries for a user.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly limit: {
+                readonly type: "number";
+            };
+            readonly cursor: {
+                readonly type: "object";
+            };
+        };
+    };
+}, {
+    readonly name: "memory_diagnostics";
+    readonly description: "Return a scrubbed diagnostics bundle with runtime versions, database stats, env key names, and recent error/degradation logs.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+            };
+        };
+    };
+}];
+export declare function handleMemoryGovernanceTool(name: string, args: unknown, options?: {
+    defaultUserId?: string;
+}): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/tools/memory-governance.js

@@ -0,0 +1,224 @@
+import { z } from "zod";
+import { memoryEngine } from "../memory/engine.js";
+const baseUser = { userId: z.string().optional() };
+export const memoryGovernanceToolSchemas = [
+    {
+        name: "memory_get",
+        description: "Fetch a specific memory with attached evidence.",
+        inputSchema: {
+            type: "object",
+            properties: { userId: { type: "string" }, recordId: { type: "string" } },
+            required: ["recordId"],
+        },
+    },
+    {
+        name: "memory_update",
+        description: "Correct memory content or update trust/status metadata.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                userId: { type: "string" },
+                recordId: { type: "string" },
+                content: { type: "string" },
+                status: { type: "string", enum: ["active", "superseded", "archived", "needs_verification"] },
+                confidence: { type: "number" },
+                verificationStatus: { type: "string", enum: ["", "verified", "unverified", "stale"] },
+                note: { type: "string" },
+            },
+            required: ["recordId"],
+        },
+    },
+    {
+        name: "memory_evidence_add",
+        description: "Attach evidence to a memory.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                userId: { type: "string" },
+                recordId: { type: "string" },
+                kind: { type: "string", enum: ["file", "command", "url", "test", "benchmark", "memory", "other"] },
+                ref: { type: "string" },
+                excerpt: { type: "string" },
+                metadata: { type: "object" },
+            },
+            required: ["recordId", "kind", "ref"],
+        },
+    },
+    {
+        name: "memory_evidence_get",
+        description: "Retrieve evidence attached to a memory.",
+        inputSchema: {
+            type: "object",
+            properties: { userId: { type: "string" }, recordId: { type: "string" } },
+            required: ["recordId"],
+        },
+    },
+    {
+        name: "memory_export",
+        description: "Export all memories, evidence, and audit operations for a user.",
+        inputSchema: { type: "object", properties: { userId: { type: "string" } } },
+    },
+    {
+        name: "memory_import",
+        description: "Import a BrainRouter memory export envelope.",
+        inputSchema: {
+            type: "object",
+            properties: { userId: { type: "string" }, data: { type: "object" } },
+            required: ["data"],
+        },
+    },
+    {
+        name: "memory_governance_delete",
+        description: "Hard delete a memory and write an audit record.",
+        inputSchema: {
+            type: "object",
+            properties: { userId: { type: "string" }, recordId: { type: "string" }, reason: { type: "string" } },
+            required: ["recordId", "reason"],
+        },
+    },
+    {
+        name: "memory_audit",
+        description: "List memory audit log entries for a user.",
+        inputSchema: {
+            type: "object",
+            properties: { userId: { type: "string" }, limit: { type: "number" }, cursor: { type: "object" } },
+        },
+    },
+    {
+        name: "memory_diagnostics",
+        description: "Return a scrubbed diagnostics bundle with runtime versions, database stats, env key names, and recent error/degradation logs.",
+        inputSchema: { type: "object", properties: { userId: { type: "string" } } },
+    },
+];
+// Shared enum schemas — used both in the import envelope and the individual tool handlers.
+const statusSchema = z.enum(["active", "superseded", "archived", "needs_verification"]);
+const verificationSchema = z.enum(["", "verified", "unverified", "stale"]);
+const evidenceKindSchema = z.enum(["file", "command", "url", "test", "benchmark", "memory", "other"]);
+const evidenceSchema = z.object({
+    id: z.string(),
+    userId: z.string().optional(),
+    recordId: z.string(),
+    kind: evidenceKindSchema,
+    ref: z.string(),
+    excerpt: z.string().optional().default(""),
+    observedAt: z.string().optional().default(""),
+    metadata: z.record(z.unknown()).optional().default({}),
+});
+const memoryRecordSchema = z.object({
+    id: z.string(),
+    content: z.string(),
+    type: z.string(),
+    priority: z.number().optional().default(50),
+    sceneName: z.string().optional().default(""),
+    skillTag: z.string().optional().default(""),
+    sessionKey: z.string().optional().default(""),
+    sessionId: z.string().optional().default(""),
+    halfLifeDays: z.number().nullable().optional().default(null),
+    supersededBy: z.string().nullable().optional().default(null),
+    invalidAt: z.string().nullable().optional().default(null),
+    timestampStr: z.string().optional().default(""),
+    timestampStart: z.string().optional().default(""),
+    timestampEnd: z.string().optional().default(""),
+    createdTime: z.string().optional().default(""),
+    updatedTime: z.string().optional().default(""),
+    metadata: z.record(z.unknown()).optional().default({}),
+    confidence: z.number().min(0).max(1).optional().default(0.65),
+    status: z.enum(["active", "superseded", "archived", "needs_verification"]).optional().default("active"),
+    sourceKind: z.string().optional().default(""),
+    verificationStatus: z.string().optional().default(""),
+    repoPaths: z.array(z.string()).optional().default([]),
+    filePaths: z.array(z.string()).optional().default([]),
+    commands: z.array(z.string()).optional().default([]),
+    citationCount: z.number().optional().default(0),
+    lastCitedAt: z.string().nullable().optional().default(null),
+    neverCitedCount: z.number().optional().default(0),
+    archived: z.boolean().optional().default(false),
+});
+const importOperationSchema = z.object({
+    id: z.string(),
+    recordId: z.string().nullable().optional().default(null),
+    operation: z.string().min(1),
+    actor: z.string().optional().default("system"),
+    sessionKey: z.string().optional().default(""),
+    reason: z.string().optional().default(""),
+    createdAt: z.string(),
+    metadata: z.record(z.unknown()).optional().default({}),
+});
+const importEnvelopeSchema = z.object({
+    version: z.literal(1),
+    memories: z.array(memoryRecordSchema).optional().default([]),
+    evidence: z.array(evidenceSchema).optional().default([]),
+    /** Audit operations from a prior export — re-imported for historical continuity. */
+    operations: z.array(importOperationSchema).optional().default([]),
+});
+function effectiveUserId(userId, defaultUserId) {
+    return userId ?? defaultUserId ?? "default";
+}
+function toolResult(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }] };
+}
+export async function handleMemoryGovernanceTool(name, args, options) {
+    switch (name) {
+        case "memory_get": {
+            const params = z.object({ ...baseUser, recordId: z.string() }).parse(args);
+            return toolResult(memoryEngine.getMemoryById(effectiveUserId(params.userId, options?.defaultUserId), params.recordId));
+        }
+        case "memory_update": {
+            const params = z.object({
+                ...baseUser,
+                recordId: z.string(),
+                content: z.string().optional(),
+                status: statusSchema.optional(),
+                confidence: z.number().min(0).max(1).optional(),
+                verificationStatus: verificationSchema.optional(),
+                note: z.string().optional(),
+            }).parse(args);
+            return toolResult(memoryEngine.updateMemory(effectiveUserId(params.userId, options?.defaultUserId), params.recordId, params));
+        }
+        case "memory_evidence_add": {
+            const params = z.object({
+                ...baseUser,
+                recordId: z.string(),
+                kind: evidenceKindSchema,
+                ref: z.string(),
+                excerpt: z.string().optional().default(""),
+                metadata: z.record(z.unknown()).optional().default({}),
+            }).parse(args);
+            return toolResult(memoryEngine.addEvidence(effectiveUserId(params.userId, options?.defaultUserId), params.recordId, params));
+        }
+        case "memory_evidence_get": {
+            const params = z.object({ ...baseUser, recordId: z.string() }).parse(args);
+            return toolResult(memoryEngine.getEvidence(effectiveUserId(params.userId, options?.defaultUserId), params.recordId));
+        }
+        case "memory_export": {
+            const params = z.object(baseUser).parse(args ?? {});
+            return toolResult(memoryEngine.exportMemories(effectiveUserId(params.userId, options?.defaultUserId)));
+        }
+        case "memory_import": {
+            const params = z.object({ ...baseUser, data: importEnvelopeSchema }).parse(args);
+            return toolResult(memoryEngine.importMemories(effectiveUserId(params.userId, options?.defaultUserId), params.data));
+        }
+        case "memory_governance_delete": {
+            const params = z.object({ ...baseUser, recordId: z.string(), reason: z.string().min(1) }).parse(args);
+            memoryEngine.governanceDelete(effectiveUserId(params.userId, options?.defaultUserId), params.recordId, params.reason);
+            return toolResult({ success: true });
+        }
+        case "memory_audit": {
+            const params = z.object({
+                ...baseUser,
+                limit: z.number().int().min(1).max(200).optional().default(50),
+                cursor: z.object({ createdAt: z.string(), id: z.string() }).optional(),
+            }).parse(args ?? {});
+            return toolResult(memoryEngine.getOperationLog(effectiveUserId(params.userId, options?.defaultUserId), {
+                limit: params.limit,
+                cursor: params.cursor,
+            }));
+        }
+        case "memory_diagnostics": {
+            const params = z.object(baseUser).parse(args ?? {});
+            return toolResult(memoryEngine.getDiagnostics(effectiveUserId(params.userId, options?.defaultUserId)));
+        }
+        default:
+            throw new Error(`Unknown governance tool: ${name}`);
+    }
+}

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

@@ -0,0 +1,67 @@
+export declare const memoryHookToolSchemas: readonly [{
+    readonly name: "memory_hook_register";
+    readonly description: "Register a passive host lifecycle hook source and optionally process one hook event into L0 memory.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly source: {
+                readonly type: "string";
+                readonly enum: readonly ["claude-code", "codex", "generic-mcp"];
+            };
+            readonly events: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+            };
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly sessionKey: {
+                readonly type: "string";
+            };
+            readonly sessionId: {
+                readonly type: "string";
+            };
+            readonly workspacePath: {
+                readonly type: "string";
+            };
+            readonly event: {
+                readonly type: "string";
+                readonly description: "Optional lifecycle event to process immediately.";
+            };
+            readonly payload: {
+                readonly type: "object";
+                readonly additionalProperties: true;
+            };
+            readonly metadata: {
+                readonly type: "object";
+                readonly additionalProperties: true;
+            };
+        };
+        readonly required: readonly ["source"];
+    };
+}, {
+    readonly name: "memory_hook_status";
+    readonly description: "List registered passive lifecycle hook sources and their last-seen timestamps.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly source: {
+                readonly type: "string";
+                readonly enum: readonly ["claude-code", "codex", "generic-mcp"];
+            };
+            readonly userId: {
+                readonly type: "string";
+            };
+        };
+    };
+}];
+export declare function handleMemoryHookTool(name: string, args: unknown, options?: {
+    defaultUserId?: string;
+}): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/tools/memory-hooks.js

@@ -0,0 +1,102 @@
+import { z } from "zod";
+import { processClaudeCodeHook } from "../integrations/claude-code.js";
+import { processCodexHook } from "../integrations/codex.js";
+import { buildHookResult, listHostHooks, processGenericMcpHook, registerHostHook, } from "../integrations/generic-mcp.js";
+import { memoryEngine } from "../memory/engine.js";
+const hookSourceSchema = z.enum(["claude-code", "codex", "generic-mcp"]);
+export const memoryHookToolSchemas = [
+    {
+        name: "memory_hook_register",
+        description: "Register a passive host lifecycle hook source and optionally process one hook event into L0 memory.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                source: { type: "string", enum: ["claude-code", "codex", "generic-mcp"] },
+                events: { type: "array", items: { type: "string" } },
+                userId: { type: "string" },
+                sessionKey: { type: "string" },
+                sessionId: { type: "string" },
+                workspacePath: { type: "string" },
+                event: { type: "string", description: "Optional lifecycle event to process immediately." },
+                payload: { type: "object", additionalProperties: true },
+                metadata: { type: "object", additionalProperties: true },
+            },
+            required: ["source"],
+        },
+    },
+    {
+        name: "memory_hook_status",
+        description: "List registered passive lifecycle hook sources and their last-seen timestamps.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                source: { type: "string", enum: ["claude-code", "codex", "generic-mcp"] },
+                userId: { type: "string" },
+            },
+        },
+    },
+];
+export async function handleMemoryHookTool(name, args, options) {
+    switch (name) {
+        case "memory_hook_register": {
+            const params = z.object({
+                source: hookSourceSchema,
+                events: z.array(z.string()).optional(),
+                userId: z.string().optional(),
+                sessionKey: z.string().optional(),
+                sessionId: z.string().optional(),
+                workspacePath: z.string().optional(),
+                event: z.string().optional(),
+                payload: z.record(z.unknown()).optional(),
+                metadata: z.record(z.unknown()).optional(),
+            }).parse(args);
+            const defaultUserId = options?.defaultUserId ?? "default";
+            const userId = params.userId ?? defaultUserId;
+            const hook = registerHostHook({
+                userId,
+                source: params.source,
+                events: params.events,
+                sessionKey: params.sessionKey,
+                workspacePath: params.workspacePath,
+                metadata: params.metadata,
+            });
+            if (!params.event) {
+                return buildHookResult({ registered: hook });
+            }
+            const payload = {
+                ...(params.payload ?? {}),
+                event: params.event,
+                userId,
+                sessionKey: params.sessionKey,
+                sessionId: params.sessionId,
+                workspacePath: params.workspacePath,
+            };
+            const captureResult = params.source === "claude-code"
+                ? await processClaudeCodeHook(memoryEngine, payload, defaultUserId)
+                : params.source === "codex"
+                    ? await processCodexHook(memoryEngine, payload, defaultUserId)
+                    : await processGenericMcpHook(memoryEngine, {
+                        source: "generic-mcp",
+                        event: params.event,
+                        userId,
+                        sessionKey: params.sessionKey ?? hook.sessionKey ?? "generic-mcp",
+                        sessionId: params.sessionId,
+                        workspacePath: params.workspacePath,
+                        args: params.payload,
+                        metadata: params.metadata,
+                    });
+            return buildHookResult({ registered: hook, captureResult });
+        }
+        case "memory_hook_status": {
+            const params = z.object({
+                source: hookSourceSchema.optional(),
+                userId: z.string().optional(),
+            }).parse(args ?? {});
+            const userId = params.userId ?? options?.defaultUserId ?? "default";
+            const hooks = listHostHooks(userId).filter((hook) => !params.source || hook.source === params.source);
+            return buildHookResult({ hooks });
+        }
+        default:
+            throw new Error(`Unknown hook tool: ${name}`);
+    }
+}

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

@@ -0,0 +1,98 @@
+export declare const memoryWorkingToolSchemas: readonly [{
+    readonly name: "memory_working_context";
+    readonly description: "Return the current working-memory canvas and injected state block without raw payloads. Optionally fetch one raw ref by nodeId.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly workspacePath: {
+                readonly type: "string";
+            };
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly sessionKey: {
+                readonly type: "string";
+            };
+            readonly nodeId: {
+                readonly type: "string";
+                readonly description: "Optional ref node to fetch raw payload for.";
+            };
+            readonly activeNodeId: {
+                readonly type: "string";
+                readonly description: "Optional node to highlight in the returned Mermaid canvas.";
+            };
+            readonly contextWindowTokens: {
+                readonly type: "number";
+            };
+            readonly estimatedTokens: {
+                readonly type: "number";
+            };
+        };
+        readonly required: readonly ["sessionKey"];
+    };
+}, {
+    readonly name: "memory_working_offload";
+    readonly description: "Offload a large short-term working payload to .brainrouter/work refs and update step log, canvas, and injected state.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly workspacePath: {
+                readonly type: "string";
+            };
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly sessionKey: {
+                readonly type: "string";
+            };
+            readonly payload: {
+                readonly type: "string";
+            };
+            readonly title: {
+                readonly type: "string";
+            };
+            readonly summary: {
+                readonly type: "string";
+            };
+            readonly kind: {
+                readonly type: "string";
+            };
+            readonly contextWindowTokens: {
+                readonly type: "number";
+            };
+            readonly estimatedTokens: {
+                readonly type: "number";
+            };
+            readonly forceAggressive: {
+                readonly type: "boolean";
+            };
+        };
+        readonly required: readonly ["sessionKey", "payload"];
+    };
+}, {
+    readonly name: "memory_working_reset";
+    readonly description: "Clear working memory files for a session after session end or when starting a clean task context.";
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly workspacePath: {
+                readonly type: "string";
+            };
+            readonly userId: {
+                readonly type: "string";
+            };
+            readonly sessionKey: {
+                readonly type: "string";
+            };
+        };
+        readonly required: readonly ["sessionKey"];
+    };
+}];
+export declare function handleMemoryWorkingTool(name: string, args: unknown, options?: {
+    defaultUserId?: string;
+}): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;