@exaudeus/memory-mcp 1.9.4 → 1.9.6

package/dist/config-manager.d.ts

@@ -35,6 +35,12 @@ export declare class ConfigManager {
     constructor(configPath: string, initial: LoadedConfig, initialStores: Map<string, MarkdownMemoryStore>, initialHealth: Map<string, LobeHealth>);
     /** Derive alwaysInclude lobe names from config — pure, no side effects. */
     private static computeAlwaysIncludeLobes;
+    /**
+     * Adopt a newly created config file that didn't exist at startup.
+     * Used by memory_bootstrap when it creates memory-config.json from scratch.
+     * Switches the manager from default/env mode to file-based mode and reloads.
+     */
+    adoptNewConfigFile(filePath: string): Promise<void>;
     /**
      * Ensure config is fresh. Call at the start of every tool handler.
      * Stats config file, reloads if mtime changed. Graceful on all errors.

package/dist/config-manager.js

@@ -36,6 +36,17 @@ export class ConfigManager {
             .filter(([, config]) => config.alwaysInclude === true)
             .map(([name]) => name);
     }
+    /**
+     * Adopt a newly created config file that didn't exist at startup.
+     * Used by memory_bootstrap when it creates memory-config.json from scratch.
+     * Switches the manager from default/env mode to file-based mode and reloads.
+     */
+    async adoptNewConfigFile(filePath) {
+        this.configPath = filePath;
+        this.configOrigin = { source: 'file', path: filePath };
+        this.configMtime = 0; // Force reload on next ensureFresh
+        await this.ensureFresh();
+    }
     /**
      * Ensure config is fresh. Call at the start of every tool handler.
      * Stats config file, reloads if mtime changed. Graceful on all errors.

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);
             }
         }
@@ -186,6 +201,13 @@ async function resolveLobesForRead(isFirstMemoryToolCall = true) {
 /** Build the shared lobe property for tool schemas — called on each ListTools request
  *  so the description and enum stay in sync after a hot-reload adds or removes lobes. */
 function buildLobeProperty(currentLobeNames) {
+    if (currentLobeNames.length === 0) {
+        return {
+            type: 'string',
+            description: 'Memory lobe name. No lobes configured yet — run memory_bootstrap(lobe: "your-project", root: "/absolute/path/to/repo") first.',
+            enum: undefined,
+        };
+    }
     const isSingle = currentLobeNames.length === 1;
     return {
         type: 'string',
@@ -384,7 +406,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: {
@@ -548,6 +570,14 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     sections.push(crashSection);
                 if (degradedSection)
                     sections.push(degradedSection);
+                // Zero lobes — guide agent to bootstrap before anything else
+                if (configManager.getLobeNames().length === 0) {
+                    sections.push('## No Lobes Configured\n\n' +
+                        'No memory lobes exist yet. Run **memory_bootstrap** to create one for this project:\n\n' +
+                        '```\nmemory_bootstrap(lobe: "your-project-name", root: "/absolute/path/to/repo")\n```\n\n' +
+                        'After bootstrapping, call **brief** again to load project context.');
+                    return { content: [{ type: 'text', text: sections.join('\n\n---\n\n') }] };
+                }
                 // Collect briefing across all lobes (or specified lobe + alwaysInclude)
                 const briefingLobeNames = allBriefingLobes;
                 const allStale = [];
@@ -1477,39 +1507,44 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                     root: z.string().optional(),
                     budgetMB: z.number().positive().optional(),
                 }).parse(args);
-                // Auto-create lobe: if the lobe is unknown AND root is provided AND config is
-                // file-based, write the new lobe entry into memory-config.json and hot-reload.
-                // This lets the agent bootstrap a brand-new repo in a single tool call.
+                // Auto-create lobe: if the lobe is unknown AND root is provided, write the new
+                // lobe entry into memory-config.json and hot-reload. If no config file exists yet,
+                // create one at cwd()/memory-config.json — this is the zero-config bootstrap path.
                 if (rawLobe && root && !configManager.getStore(rawLobe)) {
                     const origin = configManager.getConfigOrigin();
-                    if (origin.source !== 'file') {
-                        return {
-                            content: [{
-                                    type: 'text',
-                                    text: `Cannot auto-add lobe "${rawLobe}": config is not file-based (source: ${origin.source}).\n\n` +
-                                        `Create memory-config.json next to the memory MCP server with a "lobes" block, then retry.`,
-                                }],
-                            isError: true,
-                        };
-                    }
+                    // Determine the config file path to write to:
+                    // - If already file-based, use the existing file
+                    // - Otherwise, create memory-config.json in cwd() (the server's working directory)
+                    const targetConfigPath = origin.source === 'file'
+                        ? origin.path
+                        : path.join(process.cwd(), 'memory-config.json');
                     try {
-                        const raw = await readFile(origin.path, 'utf-8');
-                        const config = JSON.parse(raw);
+                        let config = {};
+                        if (origin.source === 'file') {
+                            const raw = await readFile(targetConfigPath, 'utf-8');
+                            config = JSON.parse(raw);
+                        }
                         if (!config.lobes || typeof config.lobes !== 'object')
                             config.lobes = {};
                         config.lobes[rawLobe] = { root, budgetMB: budgetMB ?? 2 };
-                        await writeFile(origin.path, JSON.stringify(config, null, 2) + '\n', 'utf-8');
-                        process.stderr.write(`[memory-mcp] Auto-added lobe "${rawLobe}" (root: ${root}) to memory-config.json\n`);
+                        await writeFile(targetConfigPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+                        process.stderr.write(`[memory-mcp] Auto-added lobe "${rawLobe}" (root: ${root}) to ${targetConfigPath}\n`);
                     }
                     catch (err) {
                         const message = err instanceof Error ? err.message : String(err);
                         return {
-                            content: [{ type: 'text', text: `Failed to auto-add lobe "${rawLobe}" to memory-config.json: ${message}` }],
+                            content: [{ type: 'text', text: `Failed to write lobe "${rawLobe}" to ${targetConfigPath}: ${message}` }],
                             isError: true,
                         };
                     }
-                    // Reload config to pick up the new lobe (hot-reload detects the updated mtime)
-                    await configManager.ensureFresh();
+                    // Reload config to pick up the new lobe.
+                    // If the file was just created from scratch, adopt it as the new config source.
+                    if (origin.source !== 'file') {
+                        await configManager.adoptNewConfigFile(targetConfigPath);
+                    }
+                    else {
+                        await configManager.ensureFresh();
+                    }
                 }
                 // Resolve store — after this point, rawLobe is never used again
                 const ctx = resolveToolContext(rawLobe);
@@ -1770,6 +1805,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.4",
+  "version": "1.9.6",
   "description": "Codebase memory MCP server - persistent, evolving knowledge for AI coding agents",
   "type": "module",
   "main": "dist/index.js",