@exaudeus/memory-mcp 1.9.2 → 1.9.4

package/dist/index.js

@@ -215,7 +215,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             // --- Retrieval ---
             {
                 name: 'brief',
-                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'}"}`,
+                description: `Start of conversation — call once to load context for a project. Returns stored preferences, gotchas overview, stale entries needing review, and entry counts. Example: {"lobe": "${currentLobeNames[0] ?? 'my-project'}"} Surfaces everything previously saved via learn/gotcha/convention/prefer. Call once at session start. Results stay valid for the entire conversation — no need to re-call.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -226,7 +226,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'recall',
-                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'}"}`,
+                description: `Before starting a task, surface prior knowledge you haven't loaded yet. Searches stored memory using semantic + keyword matching. Example: {"context": "auth token refresh", "lobe": "${currentLobeNames[0] ?? 'my-project'}"} Searches YOUR memory entries (from learn/gotcha/convention/prefer). Does NOT search the codebase or the internet. Call once per area. Skip if you already recalled this topic or received it from brief(). Knowledge stays in your context. Required param: "context" — the area you need knowledge about.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -246,7 +246,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'gotchas',
-                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.`,
+                description: `Before making changes to an area, check for known pitfalls. Retrieves stored gotchas, optionally filtered. Example: {"lobe": "${currentLobeNames[0] ?? 'my-project'}", "area": "auth"} or {"lobe": "${currentLobeNames[0] ?? 'my-project'}"} for all. brief() already includes a gotchas overview. Use this when you need gotchas for a specific area not covered in the briefing.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -261,7 +261,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'conventions',
-                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.`,
+                description: `Before writing new code, check how this codebase does things. Retrieves stored conventions, optionally filtered. Example: {"lobe": "${currentLobeNames[0] ?? 'my-project'}", "area": "testing"} or {"lobe": "${currentLobeNames[0] ?? 'my-project'}"} for all. recall() also surfaces conventions. Use this for focused convention lookup, recall() for broader cross-topic search.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -277,7 +277,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             // --- Storage ---
             {
                 name: 'gotcha',
-                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"}`,
+                description: `When something surprises you or doesn't work as expected, flag it here. Example: {"lobe": "${currentLobeNames[0] ?? 'my-project'}", "observation": "Gradle cache must be cleaned after Tuist changes or builds silently use stale artifacts"} Store facts that help future sessions, not notes about this one. Wrong: "Build failed because of stale cache." Right: "Gradle cache must be cleaned after Tuist changes." One insight per call. Persists across sessions, gets priority in brief() and recall(). Returns related knowledge. Required params: "lobe", "observation".`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -298,7 +298,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'convention',
-                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."}`,
+                description: `When you notice a pattern the codebase follows, record it here. For personal style rules, use prefer() instead. Example: {"lobe": "${currentLobeNames[0] ?? 'my-project'}", "observation": "All ViewModels use StateFlow for UI state. LiveData is banned."} Store facts that help future sessions, not notes about this one. Wrong: "Migrated to StateFlow." Right: "All ViewModels use StateFlow." One insight per call. Persists across sessions, surfaces in brief() and recall(). Returns related knowledge. Required params: "lobe", "observation".`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -319,7 +319,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'learn',
-                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"}`,
+                description: `When you understand how something works — architecture, dependencies, module boundaries — store it here. Catch-all for knowledge not covered by gotcha/convention. Example: {"lobe": "${currentLobeNames[0] ?? 'my-project'}", "observation": "Payments module depends on auth for tokens only, no other cross-module dependency"} Store facts that help future sessions, not actions you took or bugs you fixed. Wrong: "Fixed the null pointer in UserService." Right: "UserService.getUser() returns null when session expires — callers must handle this." One insight per call. Persists across sessions. Returns related knowledge. Required params: "lobe", "observation".`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -340,7 +340,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'prefer',
-                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'}"}`,
+                description: `When the user corrects you or states how they want things done, record it here. Example: {"rule": "Never use !! operator"} or {"rule": "Use Anvil for DI", "lobe": "${currentLobeNames[0] ?? 'my-project'}"} Highest trust level. Persists across sessions, surfaced in every brief(). Omit lobe for global preferences; add lobe to scope to one project. Required param: "rule".`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -359,7 +359,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             // --- Maintenance ---
             {
                 name: 'fix',
-                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.`,
+                description: `When a stored entry is wrong or outdated, correct or delete it. IDs appear in brief/recall/gotchas/conventions results. Example: {"id": "gotcha-3f7a", "correction": "Updated text"} to replace, or {"id": "gotcha-3f7a"} to delete. Required param: "id". Pass "correction" to update; omit to delete.`,
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -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: scans repo structure, README, and build system to seed initial memory. Run once per project. Provide "root" to auto-create a new lobe.',
+                description: 'First time with a new codebase — scans repo structure, README, and build system to seed initial memory. Run once per project. Example: {"lobe": "my-project"} or {"lobe": "new-project", "root": "/path/to/repo"} to auto-create lobe.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1566,16 +1566,18 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         }
         // Tool-specific hints based on which field failed
         let hint = '';
+        const exampleLobe = lobeNames[0] ?? '<your-lobe>';
+        const lobeHint = lobeNames.length > 0 ? `Available lobes: ${lobeList}` : 'No lobes configured — run memory_bootstrap with a "root" path to create one.';
         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"}`,
+            brief: `brief takes an optional lobe. Example: {"lobe": "${exampleLobe}"}. ${lobeHint}`,
+            recall: `recall requires "context" (the area you need knowledge about). Example: {"context": "auth token refresh", "lobe": "${exampleLobe}"}. ${lobeHint}`,
+            gotcha: `gotcha requires "lobe" and "observation". Example: {"lobe": "${exampleLobe}", "observation": "Gradle cache breaks after Tuist changes"}. ${lobeHint}`,
+            convention: `convention requires "lobe" and "observation". Example: {"lobe": "${exampleLobe}", "observation": "All ViewModels use StateFlow"}. ${lobeHint}`,
+            learn: `learn requires "lobe" and "observation". Example: {"lobe": "${exampleLobe}", "observation": "Messaging uses MVVM with FlowCoordinator"}. ${lobeHint}`,
+            prefer: `prefer requires "rule". Example: {"rule": "Always suggest the simplest solution first"}. Omit lobe for global; add "lobe" to scope to a project.`,
             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}`,
+            gotchas: `gotchas takes optional "lobe" and "area". Example: {"lobe": "${exampleLobe}", "area": "auth"}. ${lobeHint}`,
+            conventions: `conventions takes optional "lobe" and "area". Example: {"lobe": "${exampleLobe}", "area": "testing"}. ${lobeHint}`,
         };
         if (name in v2ToolHints) {
             hint = `\n\nUsage: ${v2ToolHints[name]}`;

package/dist/normalize.js

@@ -23,16 +23,18 @@ const TOOL_ALIASES = {
     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 tools: tool-name-as-param + common guesses map to "context"
+    recall: { recall: 'context', query: 'context', search: 'context', description: 'context', task: 'context', topic: 'context', area: 'context' },
+    // v2 brief: common guesses map to "lobe"
+    brief: { project: 'lobe' },
+    // v2 storage tools: tool-name-as-param + common guesses all map to "observation"
+    gotcha: { gotcha: 'observation', content: 'observation', note: 'observation', fact: 'observation', message: 'observation', pitfall: 'observation', trap: 'observation' },
+    convention: { convention: 'observation', content: 'observation', note: 'observation', fact: 'observation', message: 'observation', pattern: 'observation', rule: 'observation' },
+    learn: { learn: 'observation', knowledge: 'observation', insight: 'observation', content: 'observation', note: 'observation', fact: 'observation', message: 'observation' },
+    // v2 prefer: tool-name-as-param + common guesses map to "rule"
+    prefer: { prefer: 'rule', preference: 'rule', pref: 'rule', observation: 'rule', content: 'rule' },
+    // v2 fix: tool-name-as-param + common guesses map to "correction"
+    fix: { fix: 'correction', text: 'correction', content: 'correction', replacement: 'correction', update: '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' },

package/package.json

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