@crowley/rag-mcp 1.0.4 → 1.0.6

package/dist/tools/memory.js

@@ -5,7 +5,9 @@
  *        batch_remember, validate_memory, review_memories,
  *        promote_memory, run_quality_gates, memory_maintenance
  */
-import { formatMemoryResults, truncate, PREVIEW } from "../formatters.js";
+import { formatMemoryResults, truncate, paginationFooter, PREVIEW } from "../formatters.js";
+import { z } from "zod";
+import { TOOL_ANNOTATIONS } from "../annotations.js";
 const typeEmojis = {
     decision: "\u{1F3AF}",
     insight: "\u{1F4A1}",
@@ -21,545 +23,357 @@ const statusEmojis = {
     cancelled: "\u274C",
 };
 export function createMemoryTools(projectName) {
-    const tools = [
+    return [
         {
             name: "remember",
             description: "Store important information in agent memory. Use this to save decisions, insights, context, todos, or important conversations for future reference.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    content: {
-                        type: "string",
-                        description: "Information to remember",
-                    },
-                    type: {
-                        type: "string",
-                        enum: [
-                            "decision",
-                            "insight",
-                            "context",
-                            "todo",
-                            "conversation",
-                            "note",
-                        ],
-                        description: "Type of memory (default: note)",
-                        default: "note",
-                    },
-                    tags: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Tags for categorization (e.g., ['feature-x', 'important'])",
-                    },
-                    relatedTo: {
-                        type: "string",
-                        description: "Related feature or topic",
-                    },
-                },
-                required: ["content"],
+            schema: z.object({
+                content: z.string().describe("Information to remember"),
+                type: z.enum(["decision", "insight", "context", "todo", "conversation", "note"]).optional().describe("Type of memory (default: note)"),
+                tags: z.array(z.string()).optional().describe("Tags for categorization (e.g., ['feature-x', 'important'])"),
+                relatedTo: z.string().optional().describe("Related feature or topic"),
+            }),
+            annotations: TOOL_ANNOTATIONS["remember"],
+            handler: async (args, ctx) => {
+                const content = args.content;
+                const type = args.type || "note";
+                const tags = args.tags || [];
+                const relatedTo = args.relatedTo;
+                const response = await ctx.api.post("/api/memory", {
+                    projectName: ctx.projectName,
+                    content,
+                    type,
+                    tags,
+                    relatedTo,
+                });
+                const memory = response.data.memory;
+                return (`\u2705 **Memory stored**\n\n` +
+                    `- **ID:** ${memory.id}\n` +
+                    `- **Type:** ${memory.type}\n` +
+                    `- **Content:** ${truncate(content, 200)}\n` +
+                    (tags.length > 0 ? `- **Tags:** ${tags.join(", ")}\n` : "") +
+                    (relatedTo ? `- **Related to:** ${relatedTo}\n` : "") +
+                    `- **Created:** ${new Date(memory.createdAt).toLocaleString()}`);
             },
         },
         {
             name: "recall",
             description: "Retrieve relevant memories based on context. Searches agent memory for past decisions, insights, and notes related to the query.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    query: {
-                        type: "string",
-                        description: "What to recall (semantic search)",
-                    },
-                    type: {
-                        type: "string",
-                        enum: [
-                            "decision",
-                            "insight",
-                            "context",
-                            "todo",
-                            "conversation",
-                            "note",
-                            "all",
-                        ],
-                        description: "Filter by memory type (default: all)",
-                        default: "all",
-                    },
-                    limit: {
-                        type: "number",
-                        description: "Max memories to retrieve (default: 5)",
-                        default: 5,
-                    },
-                },
-                required: ["query"],
+            schema: z.object({
+                query: z.string().describe("What to recall (semantic search)"),
+                type: z.enum(["decision", "insight", "context", "todo", "conversation", "note", "all"]).optional().describe("Filter by memory type (default: all)"),
+                limit: z.number().optional().describe("Max memories to retrieve (default: 5)"),
+            }),
+            annotations: TOOL_ANNOTATIONS["recall"],
+            handler: async (args, ctx) => {
+                const query = args.query;
+                const type = args.type || "all";
+                const limit = args.limit || 5;
+                const response = await ctx.api.post("/api/memory/recall", {
+                    projectName: ctx.projectName,
+                    query,
+                    type,
+                    limit,
+                });
+                const results = response.data.results || [];
+                if (results.length === 0) {
+                    return `\u{1F50D} No memories found for: "${query}"`;
+                }
+                const header = `\u{1F9E0} **Recalled Memories** (${results.length} found)\n\n`;
+                return header + formatMemoryResults(results);
             },
         },
         {
             name: "list_memories",
             description: "List recent memories or filter by type/tags. Shows what the agent has remembered.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    type: {
-                        type: "string",
-                        enum: [
-                            "decision",
-                            "insight",
-                            "context",
-                            "todo",
-                            "conversation",
-                            "note",
-                            "all",
-                        ],
-                        description: "Filter by type",
-                        default: "all",
-                    },
-                    tag: {
-                        type: "string",
-                        description: "Filter by tag",
-                    },
-                    limit: {
-                        type: "number",
-                        description: "Max results (default: 10)",
-                        default: 10,
-                    },
-                },
+            schema: z.object({
+                type: z.enum(["decision", "insight", "context", "todo", "conversation", "note", "all"]).optional().describe("Filter by type"),
+                tag: z.string().optional().describe("Filter by tag"),
+                limit: z.number().optional().describe("Max results (default: 10)"),
+                offset: z.number().optional().describe("Pagination offset (default: 0)"),
+            }),
+            annotations: TOOL_ANNOTATIONS["list_memories"],
+            handler: async (args, ctx) => {
+                const type = args.type || "all";
+                const tag = args.tag;
+                const limit = args.limit || 10;
+                const offset = args.offset || 0;
+                const params = new URLSearchParams({
+                    projectName: ctx.projectName,
+                    limit: limit.toString(),
+                    offset: offset.toString(),
+                });
+                if (type && type !== "all")
+                    params.append("type", type);
+                if (tag)
+                    params.append("tag", tag);
+                const response = await ctx.api.get(`/api/memory/list?${params}`);
+                const memories = response.data.memories || [];
+                if (memories.length === 0) {
+                    return `\u{1F4ED} No memories found${type !== "all" ? ` of type "${type}"` : ""}`;
+                }
+                let result = `\u{1F4DA} **Agent Memories** (${memories.length})\n\n`;
+                memories.forEach((m, i) => {
+                    const emoji = typeEmojis[m.type] || "\u{1F4DD}";
+                    const statusStr = m.status ? ` [${m.status}]` : "";
+                    result += `${offset + i + 1}. ${emoji} **${m.type}**${statusStr}: ${truncate(m.content, PREVIEW.SHORT)}\n`;
+                    result += `   ID: \`${m.id}\` | ${new Date(m.createdAt).toLocaleDateString()}\n\n`;
+                });
+                result += paginationFooter(memories.length, limit, offset);
+                return result;
             },
         },
         {
             name: "forget",
             description: "Delete a specific memory by ID or clear memories by type.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    memoryId: {
-                        type: "string",
-                        description: "Specific memory ID to delete",
-                    },
-                    type: {
-                        type: "string",
-                        enum: [
-                            "decision",
-                            "insight",
-                            "context",
-                            "todo",
-                            "conversation",
-                            "note",
-                        ],
-                        description: "Delete all memories of this type",
-                    },
-                    olderThanDays: {
-                        type: "number",
-                        description: "Delete memories older than N days",
-                    },
-                },
+            schema: z.object({
+                memoryId: z.string().optional().describe("Specific memory ID to delete"),
+                type: z.enum(["decision", "insight", "context", "todo", "conversation", "note"]).optional().describe("Delete all memories of this type"),
+                olderThanDays: z.number().optional().describe("Delete memories older than N days"),
+            }),
+            annotations: TOOL_ANNOTATIONS["forget"],
+            handler: async (args, ctx) => {
+                const memoryId = args.memoryId;
+                const type = args.type;
+                if (memoryId) {
+                    const response = await ctx.api.delete(`/api/memory/${memoryId}?projectName=${ctx.projectName}`);
+                    return response.data.success
+                        ? `\u{1F5D1}\uFE0F Memory deleted: ${memoryId}`
+                        : `\u274C Failed to delete memory: ${memoryId}`;
+                }
+                if (type) {
+                    await ctx.api.delete(`/api/memory/type/${type}?projectName=${ctx.projectName}`);
+                    return `\u{1F5D1}\uFE0F Deleted all memories of type: ${type}`;
+                }
+                return "Please specify memoryId or type to delete.";
             },
         },
         {
             name: "update_todo",
             description: "Update status of a todo/task in memory.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    todoId: {
-                        type: "string",
-                        description: "Todo memory ID",
-                    },
-                    status: {
-                        type: "string",
-                        enum: ["pending", "in_progress", "done", "cancelled"],
-                        description: "New status",
-                    },
-                    note: {
-                        type: "string",
-                        description: "Optional note about the update",
-                    },
-                },
-                required: ["todoId", "status"],
+            schema: z.object({
+                todoId: z.string().describe("Todo memory ID"),
+                status: z.enum(["pending", "in_progress", "done", "cancelled"]).describe("New status"),
+                note: z.string().optional().describe("Optional note about the update"),
+            }),
+            annotations: TOOL_ANNOTATIONS["update_todo"],
+            handler: async (args, ctx) => {
+                const todoId = args.todoId;
+                const status = args.status;
+                const note = args.note;
+                const response = await ctx.api.patch(`/api/memory/todo/${todoId}`, {
+                    projectName: ctx.projectName,
+                    status,
+                    note,
+                });
+                if (!response.data.memory) {
+                    return `\u274C Todo not found: ${todoId}`;
+                }
+                return (`${statusEmojis[status] || "\u{1F4CB}"} **Todo updated**\n\n` +
+                    `- **ID:** ${todoId}\n` +
+                    `- **Status:** ${status}\n` +
+                    (note ? `- **Note:** ${note}\n` : "") +
+                    `- **Content:** ${response.data.memory.content}`);
             },
         },
         {
             name: "batch_remember",
             description: `Efficiently store multiple memories at once in ${projectName}. Faster than individual remember calls.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    items: {
-                        type: "array",
-                        items: {
-                            type: "object",
-                            properties: {
-                                content: {
-                                    type: "string",
-                                    description: "Content to remember",
-                                },
-                                type: {
-                                    type: "string",
-                                    enum: [
-                                        "decision",
-                                        "insight",
-                                        "context",
-                                        "todo",
-                                        "conversation",
-                                        "note",
-                                    ],
-                                    description: "Memory type (default: note)",
-                                },
-                                tags: {
-                                    type: "array",
-                                    items: { type: "string" },
-                                    description: "Tags for categorization",
-                                },
-                                relatedTo: {
-                                    type: "string",
-                                    description: "Related feature or topic",
-                                },
-                            },
-                            required: ["content"],
-                        },
-                        description: "Array of memories to store",
-                    },
-                },
-                required: ["items"],
+            schema: z.object({
+                items: z.array(z.object({
+                    content: z.string().describe("Content to remember"),
+                    type: z.enum(["decision", "insight", "context", "todo", "conversation", "note"]).optional().describe("Memory type (default: note)"),
+                    tags: z.array(z.string()).optional().describe("Tags for categorization"),
+                    relatedTo: z.string().optional().describe("Related feature or topic"),
+                })).describe("Array of memories to store"),
+            }),
+            annotations: TOOL_ANNOTATIONS["batch_remember"],
+            handler: async (args, ctx) => {
+                const items = args.items;
+                const response = await ctx.api.post("/api/memory/batch", {
+                    items,
+                });
+                const { savedCount, errors, memories } = response.data;
+                let result = `# \u{1F4E6} Batch Memory Result\n\n`;
+                result += `**Saved**: ${savedCount} memories\n\n`;
+                if (memories && memories.length > 0) {
+                    result += `## Stored Memories\n`;
+                    memories.forEach((m) => {
+                        result += `- [${m.type}] ${truncate(m.content, 80)}\n`;
+                        result += `  ID: \`${m.id}\`\n`;
+                    });
+                }
+                if (errors && errors.length > 0) {
+                    result += `\n## \u26A0\uFE0F Errors\n`;
+                    errors.forEach((e) => {
+                        result += `- ${e}\n`;
+                    });
+                }
+                return result;
             },
         },
         {
             name: "validate_memory",
             description: `Validate or reject an auto-extracted memory in ${projectName}. Helps improve future extraction accuracy.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    memoryId: {
-                        type: "string",
-                        description: "ID of the memory to validate",
-                    },
-                    validated: {
-                        type: "boolean",
-                        description: "true to confirm the memory is valuable, false to reject it",
-                    },
-                },
-                required: ["memoryId", "validated"],
+            schema: z.object({
+                memoryId: z.string().describe("ID of the memory to validate"),
+                validated: z.boolean().describe("true to confirm the memory is valuable, false to reject it"),
+            }),
+            annotations: TOOL_ANNOTATIONS["validate_memory"],
+            handler: async (args, ctx) => {
+                const memoryId = args.memoryId;
+                const validated = args.validated;
+                const response = await ctx.api.patch(`/api/memory/${memoryId}/validate`, {
+                    validated,
+                });
+                const { memory } = response.data;
+                return (`\u2705 Memory ${validated ? "validated" : "rejected"}\n\n` +
+                    `- **ID**: ${memory.id}\n` +
+                    `- **Type**: ${memory.type}\n` +
+                    `- **Content**: ${truncate(memory.content, PREVIEW.SHORT)}\n` +
+                    `- **Validated**: ${memory.validated}`);
             },
         },
         {
             name: "review_memories",
             description: `Get auto-extracted memories pending review in ${projectName}. Shows unvalidated learnings that need human confirmation.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    limit: {
-                        type: "number",
-                        description: "Max memories to return (default: 20)",
-                        default: 20,
-                    },
-                },
+            schema: z.object({
+                limit: z.number().optional().describe("Max memories to return (default: 20)"),
+                offset: z.number().optional().describe("Pagination offset (default: 0)"),
+            }),
+            annotations: TOOL_ANNOTATIONS["review_memories"],
+            handler: async (args, ctx) => {
+                const limit = args.limit || 20;
+                const offset = args.offset || 0;
+                const response = await ctx.api.get(`/api/memory/quarantine?limit=${limit}&offset=${offset}`);
+                const { memories, count } = response.data;
+                if (count === 0) {
+                    return "No unvalidated memories to review. All auto-extracted learnings have been reviewed.";
+                }
+                let result = `# \u{1F4CB} Memories Pending Review (${count} total)\n\n`;
+                result += `These are auto-extracted learnings that need validation.\n\n`;
+                memories.forEach((m, i) => {
+                    result += `## ${offset + i + 1}. ${m.type.toUpperCase()}\n`;
+                    result += `**ID**: \`${m.id}\`\n`;
+                    result += `**Confidence**: ${((m.confidence || 0) * 100).toFixed(0)}%\n`;
+                    result += `**Source**: ${m.source || "unknown"}\n`;
+                    result += `**Content**: ${m.content}\n`;
+                    if (m.tags && m.tags.length > 0) {
+                        result += `**Tags**: ${m.tags.join(", ")}\n`;
+                    }
+                    result += `\nTo validate: \`validate_memory(memoryId="${m.id}", validated=true)\`\n`;
+                    result += `To reject: \`validate_memory(memoryId="${m.id}", validated=false)\`\n\n`;
+                });
+                result += paginationFooter(memories.length, limit, offset);
+                return result;
             },
         },
         {
             name: "promote_memory",
             description: `Promote a quarantine memory to durable storage in ${projectName}. Requires a reason for promotion. Optionally runs quality gates before promotion.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    memoryId: {
-                        type: "string",
-                        description: "ID of the memory to promote",
-                    },
-                    reason: {
-                        type: "string",
-                        enum: ["human_validated", "pr_merged", "tests_passed"],
-                        description: "Reason for promotion",
-                    },
-                    evidence: {
-                        type: "string",
-                        description: "Optional evidence supporting the promotion",
-                    },
-                    runGates: {
-                        type: "boolean",
-                        description: "Run quality gates before promotion (default: false)",
-                    },
-                    affectedFiles: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Files affected by this memory (for quality gate checking)",
-                    },
-                },
-                required: ["memoryId", "reason"],
+            schema: z.object({
+                memoryId: z.string().describe("ID of the memory to promote"),
+                reason: z.enum(["human_validated", "pr_merged", "tests_passed"]).describe("Reason for promotion"),
+                evidence: z.string().optional().describe("Optional evidence supporting the promotion"),
+                runGates: z.boolean().optional().describe("Run quality gates before promotion (default: false)"),
+                affectedFiles: z.array(z.string()).optional().describe("Files affected by this memory (for quality gate checking)"),
+            }),
+            annotations: TOOL_ANNOTATIONS["promote_memory"],
+            handler: async (args, ctx) => {
+                const memoryId = args.memoryId;
+                const reason = args.reason;
+                const evidence = args.evidence;
+                const runGates = args.runGates;
+                const affectedFiles = args.affectedFiles;
+                const response = await ctx.api.post("/api/memory/promote", {
+                    projectName: ctx.projectName,
+                    memoryId,
+                    reason,
+                    evidence,
+                    runGates: runGates || false,
+                    projectPath: runGates ? ctx.projectPath : undefined,
+                    affectedFiles: runGates ? affectedFiles : undefined,
+                });
+                const { memory } = response.data;
+                return (`\u2705 **Memory promoted to durable storage**\n\n` +
+                    `- **ID:** ${memory.id}\n` +
+                    `- **Type:** ${memory.type}\n` +
+                    `- **Reason:** ${reason}\n` +
+                    (evidence ? `- **Evidence:** ${evidence}\n` : "") +
+                    (runGates ? `- **Quality Gates:** passed\n` : "") +
+                    `- **Content:** ${truncate(memory.content, 200)}`);
             },
         },
         {
             name: "run_quality_gates",
             description: `Run quality gates (typecheck, tests, blast radius) for ${projectName}.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    affectedFiles: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Files to check (for related tests and blast radius)",
-                    },
-                    skipGates: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Gates to skip (typecheck, test, blast_radius)",
-                    },
-                },
+            schema: z.object({
+                affectedFiles: z.array(z.string()).optional().describe("Files to check (for related tests and blast radius)"),
+                skipGates: z.array(z.string()).optional().describe("Gates to skip (typecheck, test, blast_radius)"),
+            }),
+            annotations: TOOL_ANNOTATIONS["run_quality_gates"],
+            handler: async (args, ctx) => {
+                const affectedFiles = args.affectedFiles;
+                const skipGates = args.skipGates;
+                const response = await ctx.api.post("/api/quality/run", {
+                    projectName: ctx.projectName,
+                    projectPath: ctx.projectPath,
+                    affectedFiles,
+                    skipGates,
+                });
+                const report = response.data;
+                let result = `**Quality Report**: ${report.passed ? "\u2705 All gates passed" : "\u274C Some gates failed"}\n\n`;
+                for (const gate of report.gates) {
+                    const icon = gate.passed ? "\u2705" : "\u274C";
+                    result += `${icon} **${gate.gate}** (${(gate.duration / 1000).toFixed(1)}s)\n`;
+                    result += `   ${gate.details.slice(0, 500)}\n\n`;
+                }
+                if (report.blastRadius) {
+                    result += `\n**Blast Radius**: ${report.blastRadius.affectedFiles.length} files, depth ${report.blastRadius.depth}\n`;
+                    if (report.blastRadius.affectedFiles.length > 0) {
+                        result += report.blastRadius.affectedFiles
+                            .slice(0, 10)
+                            .map((f) => `  - ${f}`)
+                            .join("\n");
+                        if (report.blastRadius.affectedFiles.length > 10) {
+                            result += `\n  ... and ${report.blastRadius.affectedFiles.length - 10} more`;
+                        }
+                    }
+                }
+                return result;
             },
         },
         {
             name: "memory_maintenance",
             description: `Run feedback-driven memory maintenance for ${projectName}: auto-promote memories with 3+ positive feedback, auto-prune memories with 2+ incorrect feedback.`,
-            inputSchema: {
-                type: "object",
-                properties: {},
-            },
-        },
-    ];
-    const handlers = {
-        // ----- remember -----
-        async remember(args, ctx) {
-            const content = args.content;
-            const type = args.type || "note";
-            const tags = args.tags || [];
-            const relatedTo = args.relatedTo;
-            const response = await ctx.api.post("/api/memory", {
-                projectName: ctx.projectName,
-                content,
-                type,
-                tags,
-                relatedTo,
-            });
-            const memory = response.data.memory;
-            return (`\u2705 **Memory stored**\n\n` +
-                `- **ID:** ${memory.id}\n` +
-                `- **Type:** ${memory.type}\n` +
-                `- **Content:** ${truncate(content, 200)}\n` +
-                (tags.length > 0 ? `- **Tags:** ${tags.join(", ")}\n` : "") +
-                (relatedTo ? `- **Related to:** ${relatedTo}\n` : "") +
-                `- **Created:** ${new Date(memory.createdAt).toLocaleString()}`);
-        },
-        // ----- recall -----
-        async recall(args, ctx) {
-            const query = args.query;
-            const type = args.type || "all";
-            const limit = args.limit || 5;
-            const response = await ctx.api.post("/api/memory/recall", {
-                projectName: ctx.projectName,
-                query,
-                type,
-                limit,
-            });
-            const results = response.data.results || [];
-            if (results.length === 0) {
-                return `\u{1F50D} No memories found for: "${query}"`;
-            }
-            const header = `\u{1F9E0} **Recalled Memories** (${results.length} found)\n\n`;
-            return header + formatMemoryResults(results);
-        },
-        // ----- list_memories -----
-        async list_memories(args, ctx) {
-            const type = args.type || "all";
-            const tag = args.tag;
-            const limit = args.limit || 10;
-            const params = new URLSearchParams({
-                projectName: ctx.projectName,
-                limit: limit.toString(),
-            });
-            if (type && type !== "all")
-                params.append("type", type);
-            if (tag)
-                params.append("tag", tag);
-            const response = await ctx.api.get(`/api/memory/list?${params}`);
-            const memories = response.data.memories || [];
-            if (memories.length === 0) {
-                return `\u{1F4ED} No memories found${type !== "all" ? ` of type "${type}"` : ""}`;
-            }
-            let result = `\u{1F4DA} **Agent Memories** (${memories.length})\n\n`;
-            memories.forEach((m, i) => {
-                const emoji = typeEmojis[m.type] || "\u{1F4DD}";
-                const statusStr = m.status ? ` [${m.status}]` : "";
-                result += `${i + 1}. ${emoji} **${m.type}**${statusStr}: ${truncate(m.content, PREVIEW.SHORT)}\n`;
-                result += `   ID: \`${m.id}\` | ${new Date(m.createdAt).toLocaleDateString()}\n\n`;
-            });
-            return result;
-        },
-        // ----- forget -----
-        async forget(args, ctx) {
-            const memoryId = args.memoryId;
-            const type = args.type;
-            if (memoryId) {
-                const response = await ctx.api.delete(`/api/memory/${memoryId}?projectName=${ctx.projectName}`);
-                return response.data.success
-                    ? `\u{1F5D1}\uFE0F Memory deleted: ${memoryId}`
-                    : `\u274C Failed to delete memory: ${memoryId}`;
-            }
-            if (type) {
-                await ctx.api.delete(`/api/memory/type/${type}?projectName=${ctx.projectName}`);
-                return `\u{1F5D1}\uFE0F Deleted all memories of type: ${type}`;
-            }
-            return "Please specify memoryId or type to delete.";
-        },
-        // ----- update_todo -----
-        async update_todo(args, ctx) {
-            const todoId = args.todoId;
-            const status = args.status;
-            const note = args.note;
-            const response = await ctx.api.patch(`/api/memory/todo/${todoId}`, {
-                projectName: ctx.projectName,
-                status,
-                note,
-            });
-            if (!response.data.memory) {
-                return `\u274C Todo not found: ${todoId}`;
-            }
-            return (`${statusEmojis[status] || "\u{1F4CB}"} **Todo updated**\n\n` +
-                `- **ID:** ${todoId}\n` +
-                `- **Status:** ${status}\n` +
-                (note ? `- **Note:** ${note}\n` : "") +
-                `- **Content:** ${response.data.memory.content}`);
-        },
-        // ----- batch_remember -----
-        async batch_remember(args, ctx) {
-            const items = args.items;
-            const response = await ctx.api.post("/api/memory/batch", {
-                items,
-            });
-            const { savedCount, errors, memories } = response.data;
-            let result = `# \u{1F4E6} Batch Memory Result\n\n`;
-            result += `**Saved**: ${savedCount} memories\n\n`;
-            if (memories && memories.length > 0) {
-                result += `## Stored Memories\n`;
-                memories.forEach((m) => {
-                    result += `- [${m.type}] ${truncate(m.content, 80)}\n`;
-                    result += `  ID: \`${m.id}\`\n`;
-                });
-            }
-            if (errors && errors.length > 0) {
-                result += `\n## \u26A0\uFE0F Errors\n`;
-                errors.forEach((e) => {
-                    result += `- ${e}\n`;
+            schema: z.object({}),
+            annotations: TOOL_ANNOTATIONS["memory_maintenance"],
+            handler: async (_args, ctx) => {
+                const response = await ctx.api.post("/api/memory/maintenance", {
+                    projectName: ctx.projectName,
                 });
-            }
-            return result;
-        },
-        // ----- validate_memory -----
-        async validate_memory(args, ctx) {
-            const memoryId = args.memoryId;
-            const validated = args.validated;
-            const response = await ctx.api.patch(`/api/memory/${memoryId}/validate`, {
-                validated,
-            });
-            const { memory } = response.data;
-            return (`\u2705 Memory ${validated ? "validated" : "rejected"}\n\n` +
-                `- **ID**: ${memory.id}\n` +
-                `- **Type**: ${memory.type}\n` +
-                `- **Content**: ${truncate(memory.content, PREVIEW.SHORT)}\n` +
-                `- **Validated**: ${memory.validated}`);
-        },
-        // ----- promote_memory -----
-        async promote_memory(args, ctx) {
-            const memoryId = args.memoryId;
-            const reason = args.reason;
-            const evidence = args.evidence;
-            const runGates = args.runGates;
-            const affectedFiles = args.affectedFiles;
-            const response = await ctx.api.post("/api/memory/promote", {
-                projectName: ctx.projectName,
-                memoryId,
-                reason,
-                evidence,
-                runGates: runGates || false,
-                projectPath: runGates ? ctx.projectPath : undefined,
-                affectedFiles: runGates ? affectedFiles : undefined,
-            });
-            const { memory } = response.data;
-            return (`\u2705 **Memory promoted to durable storage**\n\n` +
-                `- **ID:** ${memory.id}\n` +
-                `- **Type:** ${memory.type}\n` +
-                `- **Reason:** ${reason}\n` +
-                (evidence ? `- **Evidence:** ${evidence}\n` : "") +
-                (runGates ? `- **Quality Gates:** passed\n` : "") +
-                `- **Content:** ${truncate(memory.content, 200)}`);
-        },
-        // ----- run_quality_gates -----
-        async run_quality_gates(args, ctx) {
-            const affectedFiles = args.affectedFiles;
-            const skipGates = args.skipGates;
-            const response = await ctx.api.post("/api/quality/run", {
-                projectName: ctx.projectName,
-                projectPath: ctx.projectPath,
-                affectedFiles,
-                skipGates,
-            });
-            const report = response.data;
-            let result = `**Quality Report**: ${report.passed ? "\u2705 All gates passed" : "\u274C Some gates failed"}\n\n`;
-            for (const gate of report.gates) {
-                const icon = gate.passed ? "\u2705" : "\u274C";
-                result += `${icon} **${gate.gate}** (${(gate.duration / 1000).toFixed(1)}s)\n`;
-                result += `   ${gate.details.slice(0, 500)}\n\n`;
-            }
-            if (report.blastRadius) {
-                result += `\n**Blast Radius**: ${report.blastRadius.affectedFiles.length} files, depth ${report.blastRadius.depth}\n`;
-                if (report.blastRadius.affectedFiles.length > 0) {
-                    result += report.blastRadius.affectedFiles
-                        .slice(0, 10)
-                        .map((f) => `  - ${f}`)
-                        .join("\n");
-                    if (report.blastRadius.affectedFiles.length > 10) {
-                        result += `\n  ... and ${report.blastRadius.affectedFiles.length - 10} more`;
-                    }
+                const { promoted, pruned, errors } = response.data;
+                let result = `# \u{1F9F9} Memory Maintenance Results\n\n`;
+                if (promoted.length > 0) {
+                    result += `**Promoted** (${promoted.length}): memories with 3+ positive feedback moved to durable\n`;
+                    promoted.forEach((id) => { result += `  \u2705 ${id}\n`; });
+                    result += `\n`;
                 }
-            }
-            return result;
-        },
-        // ----- memory_maintenance -----
-        async memory_maintenance(args, ctx) {
-            const response = await ctx.api.post("/api/memory/maintenance", {
-                projectName: ctx.projectName,
-            });
-            const { promoted, pruned, errors } = response.data;
-            let result = `# \u{1F9F9} Memory Maintenance Results\n\n`;
-            if (promoted.length > 0) {
-                result += `**Promoted** (${promoted.length}): memories with 3+ positive feedback moved to durable\n`;
-                promoted.forEach((id) => { result += `  \u2705 ${id}\n`; });
-                result += `\n`;
-            }
-            if (pruned.length > 0) {
-                result += `**Pruned** (${pruned.length}): memories with 2+ incorrect feedback removed\n`;
-                pruned.forEach((id) => { result += `  \u{1F5D1}\u{FE0F} ${id}\n`; });
-                result += `\n`;
-            }
-            if (errors.length > 0) {
-                result += `**Errors** (${errors.length}):\n`;
-                errors.forEach((e) => { result += `  \u26A0\u{FE0F} ${e}\n`; });
-                result += `\n`;
-            }
-            if (promoted.length === 0 && pruned.length === 0) {
-                result += `No memories needed maintenance. All feedback thresholds are below auto-action levels.\n`;
-            }
-            return result;
-        },
-        // ----- review_memories -----
-        async review_memories(args, ctx) {
-            const limit = args.limit || 20;
-            const response = await ctx.api.get(`/api/memory/quarantine?limit=${limit}`);
-            const { memories, count } = response.data;
-            if (count === 0) {
-                return "No unvalidated memories to review. All auto-extracted learnings have been reviewed.";
-            }
-            let result = `# \u{1F4CB} Memories Pending Review (${count})\n\n`;
-            result += `These are auto-extracted learnings that need validation.\n\n`;
-            memories.forEach((m, i) => {
-                result += `## ${i + 1}. ${m.type.toUpperCase()}\n`;
-                result += `**ID**: \`${m.id}\`\n`;
-                result += `**Confidence**: ${((m.confidence || 0) * 100).toFixed(0)}%\n`;
-                result += `**Source**: ${m.source || "unknown"}\n`;
-                result += `**Content**: ${m.content}\n`;
-                if (m.tags && m.tags.length > 0) {
-                    result += `**Tags**: ${m.tags.join(", ")}\n`;
+                if (pruned.length > 0) {
+                    result += `**Pruned** (${pruned.length}): memories with 2+ incorrect feedback removed\n`;
+                    pruned.forEach((id) => { result += `  \u{1F5D1}\u{FE0F} ${id}\n`; });
+                    result += `\n`;
+                }
+                if (errors.length > 0) {
+                    result += `**Errors** (${errors.length}):\n`;
+                    errors.forEach((e) => { result += `  \u26A0\u{FE0F} ${e}\n`; });
+                    result += `\n`;
+                }
+                if (promoted.length === 0 && pruned.length === 0) {
+                    result += `No memories needed maintenance. All feedback thresholds are below auto-action levels.\n`;
                 }
-                result += `\nTo validate: \`validate_memory(memoryId="${m.id}", validated=true)\`\n`;
-                result += `To reject: \`validate_memory(memoryId="${m.id}", validated=false)\`\n\n`;
-            });
-            return result;
+                return result;
+            },
         },
-    };
-    return { tools, handlers };
+    ];
 }