@kinqs/brainrouter-mcp-server 0.3.4

package/dist/tools/memory_mark_cited.d.ts

@@ -0,0 +1,43 @@
+export declare const memoryMarkCitedToolSchema: {
+    readonly name: "memory_mark_cited";
+    readonly description: string;
+    readonly inputSchema: {
+        readonly type: "object";
+        readonly properties: {
+            readonly userId: {
+                readonly type: "string";
+                readonly description: "User identifier for isolation.";
+            };
+            readonly citedRecordIds: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: string;
+            };
+            readonly allRecalledRecordIds: {
+                readonly type: "array";
+                readonly items: {
+                    readonly type: "string";
+                };
+                readonly description: string;
+            };
+        };
+        readonly required: readonly ["citedRecordIds", "allRecalledRecordIds"];
+    };
+};
+export declare function handleMemoryMarkCited(args: unknown, options?: {
+    defaultUserId?: string;
+}): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/tools/memory_mark_cited.js

@@ -0,0 +1,63 @@
+import { z } from "zod";
+import { memoryEngine } from "../memory/engine.js";
+export const memoryMarkCitedToolSchema = {
+    name: "memory_mark_cited",
+    description: "Signal that specific recalled memories were used in the agent response. " +
+        "Pass all recalled record IDs (from the previous recall result) alongside the cited subset. " +
+        "Non-cited recalled memories accumulate a 'never_cited_count' signal that drives auto-archive. " +
+        "Call this once per turn, after your response is generated.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            userId: {
+                type: "string",
+                description: "User identifier for isolation.",
+            },
+            citedRecordIds: {
+                type: "array",
+                items: { type: "string" },
+                description: "IDs of memories you actually referenced in your response. " +
+                    "Pass an empty array if no memories were used (all recalled IDs will have never_cited_count incremented).",
+            },
+            allRecalledRecordIds: {
+                type: "array",
+                items: { type: "string" },
+                description: "All record IDs that were returned in the previous memory_recall result " +
+                    "(recalledCognitiveMemories[].recordId). This is the full set that was surfaced to you.",
+            },
+        },
+        required: ["citedRecordIds", "allRecalledRecordIds"],
+    },
+};
+const memoryMarkCitedSchema = z.object({
+    userId: z.string().optional(),
+    citedRecordIds: z.array(z.string()),
+    allRecalledRecordIds: z.array(z.string()),
+});
+export async function handleMemoryMarkCited(args, options) {
+    const params = memoryMarkCitedSchema.parse(args);
+    const effectiveUserId = params.userId ?? options?.defaultUserId ?? "default";
+    try {
+        const result = memoryEngine.markCited(effectiveUserId, params.citedRecordIds, params.allRecalledRecordIds);
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        success: true,
+                        ...result,
+                        message: `Marked ${result.cited} memories as cited. Incremented never_cited_count for ${result.nonCited} non-cited memories.${result.archiveThreshold > 0
+                            ? ` Auto-archive threshold: ${result.archiveThreshold}.`
+                            : " Auto-archive disabled (BRAINROUTER_ACE_ARCHIVE_THRESHOLD=0)."}`,
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `memory_mark_cited failed: ${err.message}` }],
+        };
+    }
+}

package/dist/tools/memory_recall.d.ts

@@ -0,0 +1,77 @@
+export declare const memoryRecallToolSchema: {
+    readonly name: "memory_recall";
+    readonly description: "Retrieve relevant memories, persona, and scene context before generating a response. Best used proactively when context is missing. Supports `filters` to scope results by type / scene / time range / minPriority / skillTag — apply them when the query is mid-conversation pivot or only one memory category is wanted.";
+    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 query: {
+                readonly type: "string";
+                readonly description: "The user's query or intent to recall memories for.";
+            };
+            readonly activeSkill: {
+                readonly type: "string";
+                readonly description: "The name of the BrainRouter skill currently being executed (if any).";
+            };
+            readonly filters: {
+                readonly type: "object";
+                readonly description: "Optional filters narrowing the candidate pool before ranking.";
+                readonly properties: {
+                    readonly types: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "Whitelist of memory types (e.g. ['instruction', 'feedback']).";
+                    };
+                    readonly scenes: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                        readonly description: "Whitelist of contextual focus scene names.";
+                    };
+                    readonly capturedAfter: {
+                        readonly type: "string";
+                        readonly description: "ISO 8601 lower bound on created_time.";
+                    };
+                    readonly capturedBefore: {
+                        readonly type: "string";
+                        readonly description: "ISO 8601 upper bound on created_time.";
+                    };
+                    readonly minPriority: {
+                        readonly type: "number";
+                        readonly description: "Drop records whose stored priority is below this threshold (0-100).";
+                    };
+                    readonly skillTag: {
+                        readonly type: "string";
+                        readonly description: "Restrict to records produced under this skill tag.";
+                    };
+                };
+            };
+        };
+        readonly required: readonly ["sessionKey", "query"];
+    };
+};
+export declare function handleMemoryRecall(args: any, options?: {
+    defaultUserId?: string;
+}): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/tools/memory_recall.js

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { memoryEngine } from "../memory/engine.js";
+export const memoryRecallToolSchema = {
+    name: "memory_recall",
+    description: "Retrieve relevant memories, persona, and scene context before generating a response. Best used proactively when context is missing. Supports `filters` to scope results by type / scene / time range / minPriority / skillTag — apply them when the query is mid-conversation pivot or only one memory category is wanted.",
+    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."
+            },
+            query: {
+                type: "string",
+                description: "The user's query or intent to recall memories for."
+            },
+            activeSkill: {
+                type: "string",
+                description: "The name of the BrainRouter skill currently being executed (if any)."
+            },
+            filters: {
+                type: "object",
+                description: "Optional filters narrowing the candidate pool before ranking.",
+                properties: {
+                    types: { type: "array", items: { type: "string" }, description: "Whitelist of memory types (e.g. ['instruction', 'feedback'])." },
+                    scenes: { type: "array", items: { type: "string" }, description: "Whitelist of contextual focus scene names." },
+                    capturedAfter: { type: "string", description: "ISO 8601 lower bound on created_time." },
+                    capturedBefore: { type: "string", description: "ISO 8601 upper bound on created_time." },
+                    minPriority: { type: "number", description: "Drop records whose stored priority is below this threshold (0-100)." },
+                    skillTag: { type: "string", description: "Restrict to records produced under this skill tag." }
+                }
+            }
+        },
+        required: ["sessionKey", "query"]
+    }
+};
+export async function handleMemoryRecall(args, options) {
+    const params = z.object({
+        userId: z.string().optional(),
+        sessionKey: z.string(),
+        query: z.string(),
+        activeSkill: z.string().optional(),
+        filters: z.object({
+            types: z.array(z.string()).optional(),
+            scenes: z.array(z.string()).optional(),
+            capturedAfter: z.string().optional(),
+            capturedBefore: z.string().optional(),
+            minPriority: z.number().optional(),
+            skillTag: z.string().optional(),
+        }).optional()
+    }).parse(args);
+    const effectiveUserId = params.userId ?? options?.defaultUserId ?? "default";
+    try {
+        if (params.activeSkill) {
+            memoryEngine.spikeSkill(effectiveUserId, params.activeSkill);
+        }
+        const result = await memoryEngine.recall({
+            userId: effectiveUserId,
+            sessionKey: params.sessionKey,
+            query: params.query,
+            activeSkill: params.activeSkill,
+            filters: params.filters,
+        });
+        return {
+            content: [{
+                    type: "text",
+                    text: JSON.stringify(result, null, 2)
+                }]
+        };
+    }
+    catch (err) {
+        return {
+            isError: true,
+            content: [{ type: "text", text: `Recall failed: ${err.message}` }]
+        };
+    }
+}

package/dist/tools/memory_register_skill_hints.d.ts

@@ -0,0 +1,49 @@
+import { z } from 'zod';
+export declare const memoryRegisterSkillHintsToolSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            skillName: {
+                type: string;
+                description: string;
+            };
+            hints: {
+                type: string;
+                description: string;
+            };
+            skillPath: {
+                type: string;
+                description: string;
+            };
+        };
+    };
+};
+export declare const memoryRegisterSkillHintsSchema: z.ZodEffects<z.ZodObject<{
+    skillName: z.ZodOptional<z.ZodString>;
+    hints: z.ZodOptional<z.ZodString>;
+    skillPath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    skillName?: string | undefined;
+    hints?: string | undefined;
+    skillPath?: string | undefined;
+}, {
+    skillName?: string | undefined;
+    hints?: string | undefined;
+    skillPath?: string | undefined;
+}>, {
+    skillName?: string | undefined;
+    hints?: string | undefined;
+    skillPath?: string | undefined;
+}, {
+    skillName?: string | undefined;
+    hints?: string | undefined;
+    skillPath?: string | undefined;
+}>;
+export declare function handleMemoryRegisterSkillHints(args: unknown): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/tools/memory_register_skill_hints.js

@@ -0,0 +1,55 @@
+import { z } from 'zod';
+import { memoryEngine } from '../memory/engine.js';
+import { loadSkillHints } from '../memory/skill-hints-loader.js';
+export const memoryRegisterSkillHintsToolSchema = {
+    name: 'memory_register_skill_hints',
+    description: 'Register extraction hints for a specific skill. Hints guide the memory engine to capture the most valuable context when this skill is active. Can load from a SKILL.md file path or accept hints directly.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            skillName: { type: 'string', description: 'Canonical skill name (must match the name field in SKILL.md frontmatter)' },
+            hints: { type: 'string', description: 'The extraction hints text. Use this for manual registration.' },
+            skillPath: { type: 'string', description: 'Absolute path to a SKILL.md file to auto-load hints from.' },
+        },
+    },
+};
+export const memoryRegisterSkillHintsSchema = z.object({
+    skillName: z.string().optional(),
+    hints: z.string().optional(),
+    skillPath: z.string().optional(),
+}).refine((data) => (data.skillPath) || (data.skillName && data.hints), { message: 'Either provide skillPath to auto-load, or both skillName and hints for manual registration.' });
+export async function handleMemoryRegisterSkillHints(args) {
+    const params = memoryRegisterSkillHintsSchema.parse(args);
+    let skillName;
+    let hints;
+    let sourceFile = '';
+    if (params.skillPath) {
+        // Auto-load from SKILL.md
+        const loaded = loadSkillHints(params.skillPath);
+        if (!loaded) {
+            return {
+                content: [{ type: 'text', text: `No memory_hints found in ${params.skillPath}. Add a memory_hints field to the YAML frontmatter.` }],
+            };
+        }
+        if (!loaded.name) {
+            return {
+                content: [{ type: 'text', text: `SKILL.md at ${params.skillPath} has no name field in its frontmatter. Cannot register.` }],
+            };
+        }
+        skillName = loaded.name;
+        hints = loaded.hints;
+        sourceFile = params.skillPath;
+    }
+    else {
+        // Manual registration
+        skillName = params.skillName;
+        hints = params.hints;
+    }
+    memoryEngine.registerSkillHints(skillName, hints, sourceFile);
+    return {
+        content: [{
+                type: 'text',
+                text: `✅ Skill hints registered for "${skillName}"\n\nHints:\n${hints}${sourceFile ? `\n\nLoaded from: ${sourceFile}` : ''}`,
+            }],
+    };
+}

package/dist/tools/memory_resolve_session.d.ts

@@ -0,0 +1,24 @@
+export declare const memoryResolveSessionToolSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            workspacePath: {
+                type: string;
+                description: string;
+            };
+            suggestedKey: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+};
+export declare function handleMemoryResolveSession(args: unknown): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;

package/dist/tools/memory_resolve_session.js

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { getSafeWorkspacePath } from '../resolver.js';
+/**
+ * Per-workspace MCP cache directory under the user home, NOT inside the
+ * project tree. Mirrors the brainrouter CLI's convention so the workspace
+ * tree stays clean of MCP-side state.
+ *
+ *   ~/.brainrouter/mcp-cache/<workspace-hash>/
+ *
+ * The hash is sha256(absoluteWorkspacePath).slice(0, 12) so two different
+ * workspaces never collide. We don't reuse the CLI's `<basename>-<hash8>`
+ * encoding because the MCP and CLI are separate processes — keeping them
+ * encoded independently avoids cross-package coupling.
+ */
+function getMcpCacheDir(workspacePath) {
+    const hash = createHash('sha256').update(workspacePath).digest('hex').slice(0, 12);
+    const dir = path.join(os.homedir(), '.brainrouter', 'mcp-cache', hash);
+    fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
+export const memoryResolveSessionToolSchema = {
+    name: 'memory_resolve_session',
+    description: 'Resolve and standardize the active session key (Conversation ID). If missing or descriptive, caches and retrieves a stable session UUID in the workspace.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            workspacePath: { type: 'string', description: 'The absolute path to the active project workspace.' },
+            suggestedKey: { type: 'string', description: 'Optional suggested conversation/session ID from prompt metadata.' },
+        },
+        required: ['workspacePath'],
+    },
+};
+const resolveSessionSchema = z.object({
+    workspacePath: z.string(),
+    suggestedKey: z.string().optional(),
+});
+// Helper to check if a key is a valid non-descriptive unique identifier (like UUID or hex hash)
+function isUniqueId(key) {
+    // UUID pattern
+    const uuidPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+    // Simple generic alphanumeric hash (e.g. 16-64 chars, standard for thread IDs, no spaces/hyphens with common words)
+    const cleanHashPattern = /^[a-z0-9_-]{16,64}$/i;
+    // Reject keys that are purely descriptive natural language words like "datedrop-collab-playlists"
+    const containsCommonWords = /playlist|collab|task|feature|debug|collection|datedrop|implement/i;
+    if (uuidPattern.test(key))
+        return true;
+    if (cleanHashPattern.test(key) && !containsCommonWords.test(key))
+        return true;
+    return false;
+}
+export async function handleMemoryResolveSession(args) {
+    const { workspacePath, suggestedKey } = resolveSessionSchema.parse(args);
+    const safeWorkspacePath = getSafeWorkspacePath(workspacePath);
+    // 1. If suggestedKey is a valid clean unique ID, use it directly
+    if (suggestedKey && isUniqueId(suggestedKey)) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ sessionKey: suggestedKey, source: 'provider_metadata' }, null, 2),
+                },
+            ],
+        };
+    }
+    // 2. Cache lives in the user-global MCP cache dir, NOT inside the
+    // workspace. Writing `<workspace>/.brainrouter/` polluted every project
+    // tree, then bounced back through the CLI's legacy-state migration on
+    // each restart — a loop the user could see as recurring
+    // `.brainrouter/` + `.brainrouter.migrated/` folders.
+    let cacheFilePath;
+    try {
+        const cacheDir = getMcpCacheDir(safeWorkspacePath);
+        cacheFilePath = path.join(cacheDir, 'active_session.json');
+    }
+    catch (err) {
+        // If the user home itself is unwritable (rare), fall back to a transient
+        // UUID rather than touching the workspace tree.
+        const fallbackUuid = randomUUID();
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({ sessionKey: fallbackUuid, source: 'fallback_transient', error: err.message }, null, 2),
+                },
+            ],
+        };
+    }
+    // 3. Read cached session if it exists and is not too old (e.g. within 2 hours, or just stable for the workspace)
+    if (fs.existsSync(cacheFilePath)) {
+        try {
+            const data = JSON.parse(fs.readFileSync(cacheFilePath, 'utf8'));
+            if (data && data.sessionKey) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ sessionKey: data.sessionKey, source: 'workspace_cache' }, null, 2),
+                        },
+                    ],
+                };
+            }
+        }
+        catch {
+            // Ignore parse errors and generate fresh
+        }
+    }
+    // 4. Generate fresh standard UUID session key
+    const newSessionKey = randomUUID();
+    const sessionData = {
+        sessionKey: newSessionKey,
+        createdAt: new Date().toISOString(),
+        workspace: workspacePath,
+        cacheWorkspace: safeWorkspacePath,
+    };
+    try {
+        fs.writeFileSync(cacheFilePath, JSON.stringify(sessionData, null, 2), 'utf8');
+    }
+    catch (err) {
+        console.error(`[BrainRouter] Failed to write session cache: ${err.message}`);
+    }
+    return {
+        content: [
+            {
+                type: 'text',
+                text: JSON.stringify({ sessionKey: newSessionKey, source: 'new_workspace_generation' }, null, 2),
+            },
+        ],
+    };
+}

package/dist/tools/memory_search.d.ts

@@ -0,0 +1,146 @@
+import { z } from 'zod';
+export declare const memorySearchToolSchema: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: string;
+        properties: {
+            userId: {
+                type: string;
+                description: string;
+            };
+            query: {
+                type: string;
+                description: string;
+            };
+            sessionKey: {
+                type: string;
+                description: string;
+            };
+            activeSkill: {
+                type: string;
+                description: string;
+            };
+            limit: {
+                type: string;
+                description: string;
+            };
+            asOf: {
+                type: string;
+                description: string;
+            };
+            filters: {
+                type: string;
+                description: string;
+                properties: {
+                    types: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                        description: string;
+                    };
+                    scenes: {
+                        type: string;
+                        items: {
+                            type: string;
+                        };
+                        description: string;
+                    };
+                    capturedAfter: {
+                        type: string;
+                        description: string;
+                    };
+                    capturedBefore: {
+                        type: string;
+                        description: string;
+                    };
+                    minPriority: {
+                        type: string;
+                        description: string;
+                    };
+                    skillTag: {
+                        type: string;
+                        description: string;
+                    };
+                };
+            };
+        };
+        required: string[];
+    };
+};
+export declare const memorySearchSchema: z.ZodObject<{
+    userId: z.ZodOptional<z.ZodString>;
+    query: z.ZodString;
+    sessionKey: z.ZodString;
+    activeSkill: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    asOf: z.ZodOptional<z.ZodString>;
+    filters: z.ZodOptional<z.ZodObject<{
+        types: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        scenes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        capturedAfter: z.ZodOptional<z.ZodString>;
+        capturedBefore: z.ZodOptional<z.ZodString>;
+        minPriority: z.ZodOptional<z.ZodNumber>;
+        skillTag: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        skillTag?: string | undefined;
+        capturedAfter?: string | undefined;
+        capturedBefore?: string | undefined;
+        types?: string[] | undefined;
+        scenes?: string[] | undefined;
+        minPriority?: number | undefined;
+    }, {
+        skillTag?: string | undefined;
+        capturedAfter?: string | undefined;
+        capturedBefore?: string | undefined;
+        types?: string[] | undefined;
+        scenes?: string[] | undefined;
+        minPriority?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    sessionKey: string;
+    userId?: string | undefined;
+    activeSkill?: string | undefined;
+    filters?: {
+        skillTag?: string | undefined;
+        capturedAfter?: string | undefined;
+        capturedBefore?: string | undefined;
+        types?: string[] | undefined;
+        scenes?: string[] | undefined;
+        minPriority?: number | undefined;
+    } | undefined;
+    limit?: number | undefined;
+    asOf?: string | undefined;
+}, {
+    query: string;
+    sessionKey: string;
+    userId?: string | undefined;
+    activeSkill?: string | undefined;
+    filters?: {
+        skillTag?: string | undefined;
+        capturedAfter?: string | undefined;
+        capturedBefore?: string | undefined;
+        types?: string[] | undefined;
+        scenes?: string[] | undefined;
+        minPriority?: number | undefined;
+    } | undefined;
+    limit?: number | undefined;
+    asOf?: string | undefined;
+}>;
+export declare function handleMemorySearch(args: unknown, options?: {
+    defaultUserId?: string;
+}): Promise<{
+    content: {
+        type: string;
+        text: string;
+    }[];
+    isError?: undefined;
+} | {
+    isError: boolean;
+    content: {
+        type: string;
+        text: string;
+    }[];
+}>;