@exaudeus/memory-mcp 1.9.0 → 1.9.2

package/dist/index.js

@@ -215,7 +215,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             // --- Retrieval ---
             {
                 name: 'brief',
-                description: 'Session start. Returns user identity, preferences, gotchas overview, stale entries. Call once at the beginning of a conversation. Example: brief(lobe: "android")',
+                description: `Session-start briefing for a project. Returns everything stored via learn/gotcha/convention/prefer — preferences, gotchas, stale entries, counts. Call once at conversation start. Usage: {"lobe": "${currentLobeNames[0] ?? 'my-project'}"}`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -226,18 +226,18 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'recall',
-                description: 'Pre-task lookup. Describe what you are about to do and get relevant knowledge (semantic + keyword search). Example: recall(lobe: "android", context: "writing a Kotlin reducer for the messaging feature")',
+                description: `Search your stored memory entries (from learn/gotcha/convention/prefer) — architecture notes, conventions, gotchas, decisions — by relevance using semantic + keyword matching. Does NOT search the codebase itself. Use BEFORE starting a task to surface prior knowledge. Usage: {"context": "auth token refresh", "lobe": "${currentLobeNames[0] ?? 'my-project'}"}`,
                 inputSchema: {
                     type: 'object',
                     properties: {
                         lobe: lobeProperty,
                         context: {
                             type: 'string',
-                            description: 'What you are about to do, in natural language.',
+                            description: 'The topic or area you need knowledge about. Describe in natural language — e.g. "auth token refresh", "how modules communicate", "payment webhook handler".',
                         },
                         maxResults: {
                             type: 'number',
-                            description: 'Max results (default: 10)',
+                            description: 'Max results (default: 10).',
                             default: 10,
                         },
                     },
@@ -246,14 +246,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'gotchas',
-                description: 'Get stored gotchas for a codebase area. Example: gotchas(lobe: "android", area: "auth")',
+                description: `Retrieve stored gotchas (pitfalls, traps, surprising behaviors) for a project. Check BEFORE making changes. Optionally filter by area. Usage: {"lobe": "${currentLobeNames[0] ?? 'my-project'}", "area": "auth"} or {"lobe": "${currentLobeNames[0] ?? 'my-project'}"} for all.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
                         lobe: lobeProperty,
                         area: {
                             type: 'string',
-                            description: 'Optional keyword filter for a specific area (e.g. "auth", "build", "navigation").',
+                            description: 'Optional keyword filter (e.g. "auth", "build", "navigation").',
                         },
                     },
                     required: [],
@@ -261,14 +261,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'conventions',
-                description: 'Get stored conventions for a codebase area. Example: conventions(lobe: "android", area: "testing")',
+                description: `Retrieve stored conventions (coding patterns, naming rules, architectural standards) for a project. Check BEFORE writing code. Optionally filter by area. Usage: {"lobe": "${currentLobeNames[0] ?? 'my-project'}", "area": "testing"} or {"lobe": "${currentLobeNames[0] ?? 'my-project'}"} for all.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
                         lobe: lobeProperty,
                         area: {
                             type: 'string',
-                            description: 'Optional keyword filter for a specific area (e.g. "testing", "naming", "architecture").',
+                            description: 'Optional keyword filter (e.g. "testing", "naming", "architecture").',
                         },
                     },
                     required: [],
@@ -277,14 +277,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             // --- Storage ---
             {
                 name: 'gotcha',
-                description: 'Store a gotcha — a pitfall, surprising behavior, or trap. Write naturally; title is auto-extracted. Example: gotcha(lobe: "android", observation: "Gradle cache must be cleaned after Tuist changes or builds silently use stale artifacts")',
+                description: `Store a pitfall, surprising behavior, or trap you discovered in the codebase. Persists across sessions, surfaces in brief() and recall(). Write naturally; first sentence becomes the title. Usage: {"lobe": "${currentLobeNames[0] ?? 'my-project'}", "observation": "Gradle cache must be cleaned after Tuist changes or builds silently use stale artifacts"}`,
                 inputSchema: {
                     type: 'object',
                     properties: {
                         lobe: lobeProperty,
                         observation: {
                             type: 'string',
-                            description: 'The gotcha — write naturally. First sentence becomes the title.',
+                            description: 'The gotcha. Write naturally — first sentence becomes the title.',
                         },
                         durabilityDecision: {
                             type: 'string',
@@ -298,14 +298,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'convention',
-                description: 'Store a convention — a pattern, rule, or standard the codebase follows. Example: convention(lobe: "android", observation: "All ViewModels use StateFlow for UI state. LiveData is banned.")',
+                description: `Store a coding pattern or standard the codebase follows. Persists across sessions, surfaces in brief() and recall(). Write naturally; first sentence becomes the title. Usage: {"lobe": "${currentLobeNames[0] ?? 'my-project'}", "observation": "All ViewModels use StateFlow for UI state. LiveData is banned."}`,
                 inputSchema: {
                     type: 'object',
                     properties: {
                         lobe: lobeProperty,
                         observation: {
                             type: 'string',
-                            description: 'The convention — write naturally. First sentence becomes the title.',
+                            description: 'The convention. Write naturally — first sentence becomes the title.',
                         },
                         durabilityDecision: {
                             type: 'string',
@@ -319,14 +319,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'learn',
-                description: 'Store a general observation — architecture decisions, dependency info, or any insight. Example: learn(lobe: "android", observation: "The messaging feature uses MVVM with a FlowCoordinator for navigation state")',
+                description: `Store codebase knowledge — architecture, module boundaries, dependencies, or any insight not covered by gotcha/convention. Catch-all for durable project knowledge. Persists across sessions, surfaces in brief() and recall(). Write naturally; first sentence becomes the title. Usage: {"lobe": "${currentLobeNames[0] ?? 'my-project'}", "observation": "Payments module depends on auth for tokens only — no other cross-module dependency"}`,
                 inputSchema: {
                     type: 'object',
                     properties: {
                         lobe: lobeProperty,
                         observation: {
                             type: 'string',
-                            description: 'The observation — write naturally. First sentence becomes the title.',
+                            description: 'The observation. Write naturally — first sentence becomes the title.',
                         },
                         durabilityDecision: {
                             type: 'string',
@@ -340,17 +340,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'prefer',
-                description: 'Store a user preference or working style rule. Stored with high trust. Example: prefer(rule: "Always suggest the simplest solution first")',
+                description: `Store a user preference or working-style rule — when the user corrects you or states how they want things done. Highest trust, surfaced in every brief(). Omit lobe for global. Usage: {"rule": "Never use !! operator"} or {"rule": "Use Anvil for DI", "lobe": "${currentLobeNames[0] ?? 'my-project'}"}`,
                 inputSchema: {
                     type: 'object',
                     properties: {
                         rule: {
                             type: 'string',
-                            description: 'The preference or rule — write naturally.',
+                            description: 'The preference or rule. Write naturally.',
                         },
                         lobe: {
                             ...lobeProperty,
-                            description: `Optional. Lobe to scope this preference to. Omit for global preferences. Available: ${currentLobeNames.join(', ')}`,
+                            description: `Optional. Scope this preference to a specific lobe. Omit for global. Available: ${currentLobeNames.join(', ')}`,
                         },
                     },
                     required: ['rule'],
@@ -359,17 +359,17 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             // --- Maintenance ---
             {
                 name: 'fix',
-                description: 'Fix or delete an entry. With correction: replaces content. Without: deletes. Example: fix(id: "gotcha-3f7a", correction: "updated text") or fix(id: "gotcha-3f7a")',
+                description: `Correct or delete a stored memory entry. IDs appear in brief/recall/gotchas/conventions results. Pass correction to update; omit correction to delete. Usage: {"id": "gotcha-3f7a", "correction": "Updated: cache must be cleaned after ANY dependency change"} or {"id": "gotcha-3f7a"} to delete.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
                         id: {
                             type: 'string',
-                            description: 'Entry ID (e.g. gotcha-3f7a, arch-5c9b).',
+                            description: 'Entry ID (e.g. gotcha-3f7a, conv-5c9b, gen-a2d1, pref-8e4f).',
                         },
                         correction: {
                             type: 'string',
-                            description: 'New text. Omit to delete the entry.',
+                            description: 'New text to replace the entry content. Omit entirely to delete the entry.',
                         },
                         lobe: {
                             ...lobeProperty,
@@ -384,7 +384,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             // but are hidden from tool discovery. Agents use the new v2 tools above.
             {
                 name: 'memory_bootstrap',
-                description: 'First-time setup: scan repo structure, README, and build system to seed initial knowledge. Run once per new codebase. If the lobe does not exist yet, provide "root" to auto-add it to memory-config.json and proceed without a manual restart.',
+                description: 'First-time setup: scans repo structure, README, and build system to seed initial memory. Run once per project. Provide "root" to auto-create a new lobe.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1547,20 +1547,50 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
     }
     catch (error) {
         const message = error instanceof Error ? error.message : String(error);
-        // Provide helpful hints for common Zod validation errors
+        // Provide helpful, human-readable hints for Zod validation errors.
+        // Raw Zod JSON is cryptic for agents — translate to actionable guidance.
+        const lobeNames = configManager.getLobeNames();
+        const lobeList = lobeNames.join(', ');
+        let friendlyMessage = message;
+        // Detect Zod validation errors (they contain path arrays in JSON)
+        if (message.includes('"path"') && message.includes('"message"')) {
+            // Build a friendlyMessage from the Zod issues
+            try {
+                const issues = JSON.parse(message);
+                const fields = issues.map(i => `${i.path.join('.')}: ${i.message}`).join(', ');
+                friendlyMessage = `Invalid arguments — ${fields}`;
+            }
+            catch {
+                // If parsing fails, keep original message
+            }
+        }
+        // Tool-specific hints based on which field failed
         let hint = '';
-        if (message.includes('"lobe"') && message.includes('Required')) {
-            const lobeNames = configManager.getLobeNames();
-            hint = `\n\nHint: lobe is required. Use memory_list_lobes to see available lobes. Available: ${lobeNames.join(', ')}`;
+        const v2ToolHints = {
+            brief: `brief takes an optional lobe. Example: {"lobe": "${lobeNames[0] ?? 'default'}"}. Available lobes: ${lobeList}`,
+            recall: `recall requires "context" (describe what you are working on). Example: {"context": "implementing auth flow", "lobe": "${lobeNames[0] ?? 'default'}"}. Available lobes: ${lobeList}`,
+            gotcha: `gotcha requires "lobe" and "observation". Example: {"lobe": "${lobeNames[0] ?? 'default'}", "observation": "Gradle cache breaks after Tuist changes"}`,
+            convention: `convention requires "lobe" and "observation". Example: {"lobe": "${lobeNames[0] ?? 'default'}", "observation": "All ViewModels use StateFlow"}`,
+            learn: `learn requires "lobe" and "observation". Example: {"lobe": "${lobeNames[0] ?? 'default'}", "observation": "Messaging uses MVVM with FlowCoordinator"}`,
+            prefer: `prefer requires "rule". Example: {"rule": "Always suggest the simplest solution first"}`,
+            fix: `fix requires "id". Optional: "correction" (new text; omit to delete). Example: {"id": "gotcha-3f7a", "correction": "updated text"}`,
+            gotchas: `gotchas takes optional "lobe" and "area". Example: {"lobe": "${lobeNames[0] ?? 'default'}", "area": "auth"}. Available lobes: ${lobeList}`,
+            conventions: `conventions takes optional "lobe" and "area". Example: {"lobe": "${lobeNames[0] ?? 'default'}", "area": "testing"}. Available lobes: ${lobeList}`,
+        };
+        if (name in v2ToolHints) {
+            hint = `\n\nUsage: ${v2ToolHints[name]}`;
+        }
+        else if (friendlyMessage.includes('"lobe"') || friendlyMessage.includes('lobe:')) {
+            hint = `\n\nHint: lobe is required. Available: ${lobeList}`;
         }
         else if (message.includes('"topic"') || message.includes('"entries"')) {
-            hint = '\n\nHint: memory_store requires: topic (architecture|conventions|gotchas|recent-work|modules/<name>) and entries (Array<{title, fact}>). Example: entries: [{title: "Build cache", fact: "Must clean build after Tuist changes"}]. Use modules/<name> for custom namespaces.';
+            hint = '\n\nHint: memory_store requires: topic (architecture|conventions|gotchas|general|recent-work|modules/<name>) and entries (Array<{title, fact}>).';
         }
         else if (message.includes('"scope"')) {
-            hint = '\n\nHint: memory_query requires: lobe, scope (architecture|conventions|gotchas|recent-work|modules/<name>|* for all)';
+            hint = '\n\nHint: memory_query requires: scope (architecture|conventions|gotchas|*). Example: memory_query(scope: "*")';
         }
         return {
-            content: [{ type: 'text', text: `Error: ${message}${hint}` }],
+            content: [{ type: 'text', text: `${friendlyMessage}${hint}` }],
             isError: true,
         };
     }

package/dist/normalize.js

@@ -3,17 +3,10 @@
 // Agents frequently guess wrong param names. This module resolves common aliases
 // and applies defaults to avoid wasted round-trips from validation errors.
 // Pure functions — no side effects, no state.
-/** Canonical param name aliases — maps guessed names to their correct form */
-const PARAM_ALIASES = {
+/** Global param aliases — apply to all tools regardless of name */
+const GLOBAL_ALIASES = {
     // memory_store aliases
     refs: 'references',
-    // memory_query aliases
-    query: 'filter',
-    search: 'filter',
-    keyword: 'filter',
-    // memory_context aliases
-    description: 'context',
-    task: 'context',
     // tag aliases
     tag: 'tags',
     labels: 'tags',
@@ -22,6 +15,28 @@ const PARAM_ALIASES = {
     workspace: 'lobe',
     repo: 'lobe',
 };
+/** Tool-specific param aliases — only apply when the tool name matches.
+ *  Prevents `query` → `filter` rewriting from breaking `recall(query: "...")`. */
+const TOOL_ALIASES = {
+    // Legacy tools: "query" means "filter"
+    memory_query: { query: 'filter', search: 'filter', keyword: 'filter' },
+    memory_store: { scope: 'topic' },
+    // Legacy tools: "description"/"task" mean "context"
+    memory_context: { description: 'context', task: 'context' },
+    // v2 retrieval tools: "query"/"search"/"description"/"task" mean "context"
+    recall: { query: 'context', search: 'context', description: 'context', task: 'context' },
+    // v2 storage tools: "content"/"note"/"fact" mean "observation"
+    gotcha: { content: 'observation', note: 'observation', fact: 'observation', message: 'observation' },
+    convention: { content: 'observation', note: 'observation', fact: 'observation', message: 'observation' },
+    learn: { content: 'observation', note: 'observation', fact: 'observation', message: 'observation' },
+    // v2 prefer: "preference"/"pref" mean "rule"
+    prefer: { preference: 'rule', pref: 'rule' },
+    // v2 fix: "text"/"content"/"replacement" mean "correction"
+    fix: { text: 'correction', content: 'correction', replacement: 'correction' },
+    // v2 retrieval: "filter"/"keyword" mean "area"
+    gotchas: { filter: 'area', keyword: 'area', query: 'area', search: 'area' },
+    conventions: { filter: 'area', keyword: 'area', query: 'area', search: 'area' },
+};
 /** Wildcard scope aliases — agents guess many variations instead of "*" */
 const SCOPE_WILDCARDS = new Set([
     'all', 'everything', 'any', '*', 'global', 'project', 'repo',
@@ -30,17 +45,22 @@ const SCOPE_WILDCARDS = new Set([
 /** Normalize args before Zod validation: resolve aliases, default workspace, fix wildcards */
 export function normalizeArgs(toolName, raw, lobeNames) {
     const args = { ...(raw ?? {}) };
-    // 1. Resolve param aliases (move aliased keys to canonical names)
-    for (const [alias, canonical] of Object.entries(PARAM_ALIASES)) {
+    // 1. Resolve global param aliases
+    for (const [alias, canonical] of Object.entries(GLOBAL_ALIASES)) {
         if (alias in args && !(canonical in args)) {
             args[canonical] = args[alias];
             delete args[alias];
         }
     }
-    // 2. For memory_store: accept "scope" as alias for "topic"
-    if (toolName === 'memory_store' && 'scope' in args && !('topic' in args)) {
-        args['topic'] = args['scope'];
-        delete args['scope'];
+    // 2. Resolve tool-specific param aliases
+    const toolSpecific = TOOL_ALIASES[toolName];
+    if (toolSpecific) {
+        for (const [alias, canonical] of Object.entries(toolSpecific)) {
+            if (alias in args && !(canonical in args)) {
+                args[canonical] = args[alias];
+                delete args[alias];
+            }
+        }
     }
     // 3. Default lobe to the only available one when omitted
     if (!('lobe' in args) || args['lobe'] === undefined || args['lobe'] === '') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exaudeus/memory-mcp",
-  "version": "1.9.0",
+  "version": "1.9.2",
   "description": "Codebase memory MCP server - persistent, evolving knowledge for AI coding agents",
   "type": "module",
   "main": "dist/index.js",