@exaudeus/memory-mcp 1.9.3 → 1.9.5

package/dist/config.js

@@ -251,18 +251,32 @@ export function getLobeConfigs() {
             process.stderr.write(`[memory-mcp] Failed to parse MEMORY_MCP_WORKSPACES: ${e}\n`);
         }
     }
-    // 3. Fall back to single-repo default
-    const repoRoot = process.env.MEMORY_MCP_REPO_ROOT ?? process.cwd();
-    const explicitDir = process.env.MEMORY_MCP_DIR;
-    const storageBudget = parseInt(process.env.MEMORY_MCP_BUDGET ?? '', 10) || DEFAULT_STORAGE_BUDGET_BYTES;
-    configs.set('default', {
-        repoRoot,
-        memoryPath: resolveMemoryPath(repoRoot, 'default', explicitDir),
-        storageBudgetBytes: storageBudget,
-        alwaysInclude: false,
-        embedder: autoEmbedder,
-    });
-    // No ensureAlwaysIncludeLobe here — single-repo default users have everything in one lobe
-    process.stderr.write(`[memory-mcp] Using single-lobe default mode (cwd: ${repoRoot})\n`);
+    // 3. Single-repo fallback: only when MEMORY_MCP_REPO_ROOT is explicitly set
+    //    (Using cwd() as a fallback caused cross-project contamination in shared MCP instances)
+    const explicitRepoRoot = process.env.MEMORY_MCP_REPO_ROOT;
+    if (explicitRepoRoot) {
+        const lobeName = path.basename(explicitRepoRoot);
+        const explicitDir = process.env.MEMORY_MCP_DIR;
+        const storageBudget = parseInt(process.env.MEMORY_MCP_BUDGET ?? '', 10) || DEFAULT_STORAGE_BUDGET_BYTES;
+        if (!lobeName || lobeName === path.sep || lobeName === '/') {
+            process.stderr.write(`[memory-mcp] MEMORY_MCP_REPO_ROOT="${explicitRepoRoot}" has an invalid basename — cannot derive a lobe name. ` +
+                `Use a path like "/path/to/my-project". Starting with zero lobes.\n`);
+        }
+        else {
+            configs.set(lobeName, {
+                repoRoot: explicitRepoRoot,
+                memoryPath: resolveMemoryPath(explicitRepoRoot, lobeName, explicitDir),
+                storageBudgetBytes: storageBudget,
+                alwaysInclude: false,
+                embedder: autoEmbedder,
+            });
+            process.stderr.write(`[memory-mcp] Single-lobe mode via MEMORY_MCP_REPO_ROOT: lobe="${lobeName}" root="${explicitRepoRoot}"\n`);
+            return { configs, origin: { source: 'default' }, embedder: autoEmbedder };
+        }
+    }
+    // No configuration found — start with zero lobes
+    // Agents will be guided to run memory_bootstrap() to create lobes
+    process.stderr.write(`[memory-mcp] No lobes configured. Agents will be prompted to run memory_bootstrap() when they first call a tool.\n` +
+        `[memory-mcp] To configure lobes: create memory-config.json, set MEMORY_MCP_WORKSPACES, or set MEMORY_MCP_REPO_ROOT.\n`);
     return { configs, origin: { source: 'default' }, embedder: autoEmbedder };
 }

package/dist/index.js

@@ -8,6 +8,7 @@ import { CallToolRequestSchema, ListToolsRequestSchema, ListResourcesRequestSche
 import { z } from 'zod';
 import path from 'path';
 import { readFile, writeFile } from 'fs/promises';
+import { existsSync } from 'fs';
 import { MarkdownMemoryStore } from './store.js';
 import { parseTopicScope, parseTrustLevel } from './types.js';
 import { getLobeConfigs } from './config.js';
@@ -17,7 +18,7 @@ import { buildCrashReport, writeCrashReport, writeCrashReportSync, readLatestCra
 import { formatStaleSection, formatConflictWarning, formatStats, formatBehaviorConfigSection, mergeTagFrequencies, buildQueryFooter, buildBriefingTagPrimerSections, formatSearchMode, formatLootDrop } from './formatters.js';
 import { parseFilter, extractTitle } from './text-analyzer.js';
 import { VOCABULARY_ECHO_LIMIT, WARN_SEPARATOR } from './thresholds.js';
-import { matchRootsToLobeNames, buildLobeResolution } from './lobe-resolution.js';
+import { matchRootsToLobeNames, buildLobeResolution, isPathPrefixOf } from './lobe-resolution.js';
 let serverMode = { kind: 'running' };
 const lobeHealth = new Map();
 const serverStartTime = Date.now();
@@ -77,10 +78,22 @@ const ALWAYS_INCLUDE_WRITE_TOPICS = new Set(['user', 'preferences']);
  *  After this call, consumers use ctx.label — the raw lobe is not in scope. */
 function resolveToolContext(rawLobe) {
     const lobeNames = configManager.getLobeNames();
+    // Zero lobes configured — guide agent to bootstrap
+    if (lobeNames.length === 0) {
+        return {
+            ok: false,
+            error: `No lobes configured. Run memory_bootstrap(lobe: 'your-project-name', root: '/absolute/path/to/repo') to create one. ` +
+                `After bootstrapping, retry your call with the lobe name you chose.`,
+        };
+    }
     // Default to single lobe when omitted
     const lobe = rawLobe || (lobeNames.length === 1 ? lobeNames[0] : undefined);
     if (!lobe) {
-        return { ok: false, error: `Lobe is required. Available: ${lobeNames.join(', ')}` };
+        return {
+            ok: false,
+            error: `Lobe is required. Available: ${lobeNames.join(', ')}. ` +
+                `If this is a new project, run memory_bootstrap(lobe: 'your-project-name', root: '/absolute/path/to/repo') to create a lobe for it.`,
+        };
     }
     // Check if lobe is degraded
     const health = configManager.getLobeHealth(lobe);
@@ -134,8 +147,10 @@ function inferLobeFromPaths(paths) {
             const config = configManager.getLobeConfig(lobeName);
             if (!config)
                 continue;
-            // Check if the file path starts with or is inside the repo root
-            if (resolved.startsWith(config.repoRoot) || resolved.startsWith(path.basename(config.repoRoot))) {
+            // Check if the file path starts with or is inside the repo root (path-boundary aware)
+            const normalizedResolved = path.resolve(resolved);
+            const normalizedRoot = path.resolve(config.repoRoot);
+            if (isPathPrefixOf(normalizedRoot, normalizedResolved)) {
                 matchedLobes.add(lobeName);
             }
         }
@@ -384,7 +399,7 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
             // but are hidden from tool discovery. Agents use the new v2 tools above.
             {
                 name: 'memory_bootstrap',
-                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.',
+                description: 'When no lobe exists for a project — run this before any other tool. Scans repo structure, README, and build system to create a named lobe and seed initial memory. Required param: "root" (absolute path to repo) when the lobe does not yet exist. Example: {"lobe": "my-project", "root": "/absolute/path/to/repo"}. After bootstrapping, all other tools become available for that lobe.',
                 inputSchema: {
                     type: 'object',
                     properties: {
@@ -1566,16 +1581,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]}`;
@@ -1768,6 +1785,26 @@ async function main() {
     }
     // Initialize ConfigManager with current config state
     configManager = new ConfigManager(configPath, { configs: lobeConfigs, origin: configOrigin }, stores, lobeHealth);
+    // Warn if a 'default' lobe data directory exists but no 'default' lobe is configured.
+    // This indicates a user who was relying on the old zero-config default mode.
+    if (!lobeConfigs.has('default')) {
+        const orphanCandidates = [
+            path.join(process.cwd(), '.memory', 'default'),
+            ...(process.env.MEMORY_MCP_DIR ? [path.join(process.env.MEMORY_MCP_DIR, 'default')] : []),
+        ];
+        for (const candidate of orphanCandidates) {
+            try {
+                if (existsSync(candidate)) {
+                    process.stderr.write(`[memory-mcp] WARNING: Found orphaned 'default' lobe data at ${candidate} but no 'default' lobe is configured.\n` +
+                        `[memory-mcp] This data was created by the old zero-config default mode.\n` +
+                        `[memory-mcp] To recover: run memory_bootstrap(lobe: 'your-project-name', root: '/path/to/repo') to create a named lobe,\n` +
+                        `[memory-mcp] then manually move files from ${candidate}/ to the new lobe's memory directory.\n`);
+                    break;
+                }
+            }
+            catch { /* ignore fs errors during startup check */ }
+        }
+    }
     const transport = new StdioServerTransport();
     // Handle transport errors — journal and exit
     transport.onerror = (error) => {

package/dist/lobe-resolution.d.ts

@@ -16,6 +16,9 @@ export interface LobeRootConfig {
     readonly name: string;
     readonly repoRoot: string;
 }
+/** Check if `child` is equal to or nested under `parent` with path-boundary awareness.
+ *  Prevents false matches like "/projects/zillow-tools" matching "/projects/zillow". */
+export declare function isPathPrefixOf(parent: string, child: string): boolean;
 /** Match MCP client workspace root URIs against known lobe repo roots.
  *  Returns matched lobe names, or empty array if none match.
  *

package/dist/lobe-resolution.js

@@ -10,7 +10,7 @@
 import path from 'path';
 /** Check if `child` is equal to or nested under `parent` with path-boundary awareness.
  *  Prevents false matches like "/projects/zillow-tools" matching "/projects/zillow". */
-function isPathPrefixOf(parent, child) {
+export function isPathPrefixOf(parent, child) {
     if (child === parent)
         return true;
     // Ensure the prefix ends at a path separator boundary
@@ -81,9 +81,16 @@ export function buildLobeResolution(allLobeNames, matchedLobes, alwaysIncludeLob
         };
     }
     // Fallback — no lobes could be determined
+    if (allLobeNames.length === 0) {
+        return {
+            kind: 'global-only',
+            hint: `No lobes configured. Run memory_bootstrap(lobe: 'your-project-name', root: '/absolute/path/to/repo') to create one.`,
+        };
+    }
     return {
         kind: 'global-only',
         hint: `Multiple lobes available (${allLobeNames.join(', ')}) but none could be inferred from client workspace roots. ` +
-            `Specify lobe parameter for lobe-specific results.`,
+            `Specify lobe parameter for lobe-specific results. ` +
+            `If this is a new project not in the list, run memory_bootstrap(lobe: 'your-project-name', root: '/absolute/path/to/repo') to add it.`,
     };
 }

package/package.json

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