@exaudeus/memory-mcp 1.9.1 → 1.9.3

package/dist/index.js

@@ -215,7 +215,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             // --- Retrieval ---
             {
                 name: 'brief',
-                description: `Session start for a project. Returns your preferences (global), gotchas, and recent work for this project and branch. Also surfaces stale entries that need review. Call once at the beginning of a conversation. Lobe names: ${currentLobeNames.join(', ') || 'none configured'}. Example: brief(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,14 +226,14 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'recall',
-                description: `Search stored knowledge by relevance within a project. BEFORE starting a task, describe what you are about to do in natural language and get relevant knowledge back (semantic + keyword search). Example: recall(lobe: "${currentLobeNames[0] ?? 'my-project'}", context: "how does auth token refresh work") or recall(lobe: "${currentLobeNames[0] ?? 'my-project'}", context: "refactoring the payment webhook handler")`,
+                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: {
                         lobe: lobeProperty,
                         context: {
                             type: 'string',
-                            description: 'Describe 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',
@@ -246,7 +246,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             },
             {
                 name: 'gotchas',
-                description: `Pitfalls in a project, optionally scoped to an area. Check BEFORE making changes to avoid known traps. Example: gotchas(lobe: "${currentLobeNames[0] ?? 'my-project'}", area: "auth") or gotchas(lobe: "${currentLobeNames[0] ?? 'my-project'}") for all gotchas.`,
+                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: `Coding patterns and standards in a project, optionally scoped to an area. Check BEFORE writing new code to follow established patterns. Example: conventions(lobe: "${currentLobeNames[0] ?? 'my-project'}", area: "testing") or conventions(lobe: "${currentLobeNames[0] ?? 'my-project'}") for all conventions.`,
+                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: `Flag a pitfall you hit — what you expected vs what actually happened. Gets priority in brief and recall results. Returns related knowledge you might want to review. Example: gotcha(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: `Record a codebase pattern you observed — how the code is structured, naming rules, architectural decisions. For personal rules or preferences, use prefer() instead. Returns related knowledge. Example: convention(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 architecture, dependencies, decisions, progress, or any knowledge not covered by gotcha() or convention(). Use this as the catch-all for insights worth remembering. Returns related knowledge. Example: learn(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: `When your user corrects you or states a working-style rule, record it here. Persists globally by default and is surfaced in every brief(). Optionally scope to a specific project. Example: prefer(rule: "Never use !! operator") or prefer(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 memory entry. IDs appear in brief(), recall(), gotchas(), and conventions() results. Pass correction to update content; omit correction to delete the entry entirely. Example: fix(id: "gotcha-a1b2c3d4", correction: "Fixed in v2.3 — cache is auto-cleaned now") or fix(id: "gotcha-a1b2c3d4") 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: 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 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: {

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.1",
+  "version": "1.9.3",
   "description": "Codebase memory MCP server - persistent, evolving knowledge for AI coding agents",
   "type": "module",
   "main": "dist/index.js",