context-mcp-server 1.0.4 → 1.0.6

package/README.md

@@ -371,7 +371,10 @@ Available to web clients (Claude.ai, ChatGPT) only — local AI clients use thei
 
 All file and git operations are sandboxed to the registered project root. Enable git tools with `--access-git` or `access_git: true` in config.
 
-### CodeGraph
+### ContextGraph (CodeGraph)
+
+> Also referred to as **ContextGraph** — the MCP tools use the `codegraph_*` prefix but both names mean the same thing.
+
 - `codegraph_build` — AST scan using tree-sitter: functions, classes, imports, edges. Runs locally, no API cost.
 - `codegraph_query` — fetch any details about the codebase using natural language: find functions, classes, files, dependencies, callers
 - `codegraph_explain` — single node: type, file location, all direct connections (depends_on, used_by)
@@ -381,15 +384,25 @@ All file and git operations are sandboxed to the registered project root. Enable
 
 ### Multi-AI Support
 
-| AI | Config File | Instruction File |
-|----|------------|-----------------|
-| Claude Code | `.claude/mcp.json` | `CLAUDE.md` |
-| VS Code Copilot | `.vscode/mcp.json` | `CLAUDE.md` |
-| Cursor | `.cursor/mcp.json` | `.cursor/rules/context-mcp.mdc` |
-| Gemini CLI | `.gemini/settings.json` | `GEMINI.md` |
-| Codex CLI | `.codex/config.toml` | `AGENTS.md` |
-| Windsurf | `~/.codeium/windsurf/mcp_config.json` | `.windsurf/rules/context-mcp.md` |
-| Claude.ai / ChatGPT | HTTP (`ctx online`) | — |
+| AI | Config File | Instructions | Slash Commands |
+|----|------------|--------------|----------------|
+| Claude Code | `.claude/mcp.json` | Skill → `~/.claude/skills/context-mcp/` (global) | ✓ (3 commands) |
+| Cursor | `.cursor/mcp.json` | Rule → `.cursor/rules/context-mcp.mdc` | — |
+| Windsurf | `~/.codeium/windsurf/mcp_config.json` | Rule → `.windsurf/rules/context-mcp.md` | — |
+| Gemini CLI | `.gemini/settings.json` | `GEMINI.md` | — |
+| Codex CLI | `.codex/config.toml` | `AGENTS.md` | — |
+| VS Code Copilot | `.vscode/mcp.json` | — | — |
+| Claude.ai / ChatGPT | HTTP (`ctx online`) | — | — |
+
+> Claude Code installs context-mcp as a **skill** (`~/.claude/skills/context-mcp/SKILL.md`) — available globally across all projects, not just the current one. Cursor and Windsurf use their native rules system. Gemini and Codex use plain instruction files since they have no skill/rules system.
+
+`ctx install --claude` also writes slash commands into `.claude/commands/`:
+
+| Command | What it does |
+|---------|-------------|
+| `/context-resume` | Resume context for the current project |
+| `/graph-build` | Build or rebuild the ContextGraph |
+| `/save-context` | Save a note, decision, or bug to context |
 
 > The context store lives at `~/.context-mcp/` — not inside any tool, IDE, or session. A decision saved in Claude Code is visible in Cursor. A bug logged from Gemini CLI shows up when you resume in Codex.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mcp-server",
-  "version": "1.0.4",
+  "version": "1.0.6",
   "description": "Persistent AI memory + codebase knowledge graph MCP server. Works across Claude Code, Cursor, Gemini CLI, Codex, Windsurf, VS Code Copilot, Claude.ai, and ChatGPT.",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codegraph-mcp"
-version = "1.0.4"
+version = "1.0.6"
 description = "Codebase knowledge graph MCP server — AST extraction, graph queries, community detection"
 readme = "README.md"
 requires-python = ">=3.11"

package/src/cli.js

@@ -106,28 +106,46 @@ function printSection(title, meta = '') {
 
 function printUsage() {
   printBanner();
-  printSection('Commands');
+
+  // Terminal commands (ctx ...)
+  printSection('Terminal commands', 'run from your shell');
   const cmd = (c, desc) => console.log(`  ${accent(c.padEnd(40))} ${faint(desc)}`);
-  cmd('ctx',                        'open interactive mode');
-  cmd('ctx list [project]',         'list entries + discussions + graphs');
-  cmd('ctx search <query>',         'keyword → semantic fallback search');
-  cmd('ctx add',                    'add entry interactively');
-  cmd('ctx delete <id-prefix>',     'delete one entry');
-  cmd('ctx delete project <name|id>', 'delete all entries for a project (by name or id)');
-  cmd('ctx summary [project]',      'summarize recent entries');
-  cmd('ctx projects',               'show all projects + graphs');
-  cmd('ctx discuss [project]',      'show discussions');
-  cmd('ctx benchmark',              'token savings report (memory + graph)');
+  cmd('ctx',                           'open interactive mode');
+  cmd('ctx list [project]',            'list entries + discussions + graphs');
+  cmd('ctx search <query>',            'keyword → semantic fallback search');
+  cmd('ctx add',                       'add entry interactively');
+  cmd('ctx delete <id-prefix>',        'delete one entry');
+  cmd('ctx delete project <name|id>',  'delete all entries for a project');
+  cmd('ctx summary [project]',         'summarize recent entries');
+  cmd('ctx projects',                  'show all projects + graphs');
+  cmd('ctx discuss [project]',         'show discussions');
+  cmd('ctx benchmark',                 'token savings report (memory + graph)');
   console.log('');
-  cmd('ctx install --initial',          'install / update Node.js + Python (codegraph) deps');
-  cmd('ctx install --<platform>',      'write MCP config + instruction file for an AI platform');
+  cmd('ctx install --initial',         'install / update Node.js + Python (codegraph) deps');
+  cmd('ctx install --<platform>',      'write MCP config + skill/rules for an AI platform');
   cmd('ctx install --all',             'install for all platforms at once');
-  cmd('ctx online [--port N]',         'start HTTP server + show credentials for Claude.ai / ChatGPT');
+  cmd('ctx online [--port N]',         'start HTTP server for Claude.ai / ChatGPT');
   cmd('ctx online --close',            'stop the running HTTP server');
   cmd('ctx settings',                  'view and edit config (port, host, client id/secret)');
-  console.log('');
+  cmd('ctx update',                    'check for and apply latest version');
   cmd('ctx help',                      'show this screen');
   console.log('');
+
+  // Interactive mode commands (no ctx prefix)
+  printSection('Interactive mode', 'type these inside  ctx  (no "ctx" prefix)');
+  const icmd = (c, desc) => console.log(`  ${accent(c.padEnd(40))} ${faint(desc)}`);
+  icmd('list [project]',               'list entries');
+  icmd('search <query>',               'search context');
+  icmd('add',                          'add entry');
+  icmd('projects',                     'show all projects');
+  icmd('discuss [project]',            'show discussions');
+  icmd('summary [project]',            'summarize recent entries');
+  icmd('benchmark',                    'token savings report');
+  icmd('install --<platform>',         'install for a platform');
+  icmd('settings',                     'edit config');
+  icmd('clear',                        'clear screen');
+  icmd('exit / quit / q',              'exit interactive mode');
+  console.log('');
 }
 function clearScreen() {
   // \x1b[2J = clear screen, \x1b[3J = clear scrollback, \x1b[H = cursor home
@@ -168,7 +186,7 @@ function cmdList(args) {
 
   for (const projectName of projectNames) {
     const pData     = projects[projectName];
-    const graph     = allGraphs.find(g => g.path?.toLowerCase().includes(projectName.toLowerCase()));
+    const graph     = _graphForProject(allGraphs, projectName);
     const activeD   = pData.discussions.filter(d => d.status === 'active').length;
     const totalSecs = (pData.contexts.length > 0 ? 1 : 0) + (pData.discussions.length > 0 ? 1 : 0) + (graph ? 1 : 0);
     let   secIdx    = 0;
@@ -222,7 +240,7 @@ function cmdList(args) {
   }
 
   // Orphan graphs (no matching project)
-  const orphanGraphs = allGraphs.filter(g => !projectNames.some(p => g.path?.toLowerCase().includes(p.toLowerCase())));
+  const orphanGraphs = allGraphs.filter(g => !projectNames.some(p => _graphForProject([g], p)));
   if (orphanGraphs.length) {
     console.log(`\n  ${color(C.dblue, '◇')} ${muted('other graphs')}`);
     for (const g of orphanGraphs) {
@@ -274,7 +292,7 @@ function cmdProjects() {
     const entries   = getContext({ project: project.name, limit: 3, compact: true }).filter(e => e.status !== 'archived');
     const discs     = allDiscs.filter(d => (d.project || 'global') === project.name);
     const activeD   = discs.filter(d => d.status === 'active');
-    const graph     = graphs.find(g => g.path?.toLowerCase().includes(project.name.toLowerCase()));
+    const graph     = _graphForProject(graphs, project.name);
 
     const barLen = Math.min(Math.ceil(project.count / 2), 24);
     const bar    = color(C.dblue, '█'.repeat(barLen)) + color(C.darkgray, '░'.repeat(24 - barLen));
@@ -531,65 +549,187 @@ function _writeFile(filePath, content, label) {
   console.log(`  ${ok('✓')} ${label.padEnd(28)} ${faint(filePath.replace(/\\/g, '/'))}`);
 }
 
+// Entries ctx install writes into project roots — add to user's global gitignore if one exists
+const _GLOBAL_GITIGNORE_ENTRIES = [
+  // Installed instruction files
+  'CLAUDE.md',
+  'GEMINI.md',
+  'AGENTS.md',
+  // AI/IDE platform config folders (context-mcp specific — safe to ignore globally)
+  '.claude/',
+  '.cursor/',
+  '.vscode/',
+  '.gemini/',
+  '.codex/',
+  '.windsurf/',
+  // Build outputs and session artifacts
+  'codegraph-cache/',
+  '.mcp.json',
+];
+
+// Match a graph to a project by exact last-path-component comparison (not substring)
+function _graphForProject(graphs, projectName) {
+  const norm = p => (p || '').toLowerCase().replace(/\\/g, '/').replace(/\/$/, '');
+  const name = projectName.toLowerCase();
+  return graphs.find(g => norm(g.path).split('/').pop() === name) || null;
+}
+
+const _PROJECT_GITIGNORE_ENTRIES = [
+  '.claude/', '.cursor/', '.vscode/', '.gemini/', '.codex/',
+  'codegraph-cache/', '.mcp.json', 'CLAUDE.md', 'GEMINI.md', 'AGENTS.md',
+];
+
+function _updateProjectGitignore(projectDir) {
+  const giPath = join(projectDir, '.gitignore');
+  const existing = existsSync(giPath) ? readFileSync(giPath, 'utf8') : '';
+  const lines = existing.split(/\r?\n/);
+  const missing = _PROJECT_GITIGNORE_ENTRIES.filter(e => !lines.includes(e));
+  if (!missing.length) return;
+  const block = '\n# context-mcp — written by ctx install\n' + missing.join('\n') + '\n';
+  writeFileSync(giPath, (existing ? existing.trimEnd() : '') + block, 'utf8');
+  console.log(`  ${ok('✓')} ${'project .gitignore'.padEnd(28)} ${faint(giPath.replace(/\\/g, '/'))}`);
+  for (const e of missing) console.log(`      ${faint('+ ' + e)}`);
+}
+
+function _updateGlobalGitignore() {
+  // Resolve global gitignore path: git config > ~/.gitignore_global > ~/.gitignore
+  let giPath = null;
+  const gitCfg = spawnSync('git', ['config', '--global', 'core.excludesFile'], { encoding: 'utf8' });
+  if (gitCfg.status === 0 && gitCfg.stdout.trim()) {
+    const resolved = gitCfg.stdout.trim().replace(/^~/, homedir());
+    if (existsSync(resolved)) giPath = resolved;
+  }
+  if (!giPath) {
+    for (const candidate of [join(homedir(), '.gitignore_global'), join(homedir(), '.gitignore')]) {
+      if (existsSync(candidate)) { giPath = candidate; break; }
+    }
+  }
+  if (!giPath) return; // no global gitignore — skip silently
+
+  const existing = readFileSync(giPath, 'utf8');
+  const lines = existing.split(/\r?\n/);
+  const missing = _GLOBAL_GITIGNORE_ENTRIES.filter(e => !lines.includes(e));
+  if (!missing.length) return;
+
+  const block = '\n# context-mcp — written by ctx install\n' + missing.join('\n') + '\n';
+  writeFileSync(giPath, existing.trimEnd() + block, 'utf8');
+  console.log(`  ${ok('✓')} ${'global gitignore'.padEnd(28)} ${faint(giPath.replace(/\\/g, '/'))}`);
+  for (const e of missing) console.log(`      ${faint('+ ' + e)}`);
+}
+
+function _writeCommands(baseDir) {
+  const cmdsDir = join(TPLS, 'commands');
+  const destDir = join(baseDir, '.claude', 'commands');
+  for (const [name, label] of [
+    ['context-resume.md', '/context-resume'],
+    ['graph-build.md',    '/graph-build'],
+    ['save-context.md',   '/save-context'],
+  ]) {
+    const src = join(cmdsDir, name);
+    if (existsSync(src)) {
+      _writeFile(join(destDir, name), readFileSync(src, 'utf8'), label);
+    }
+  }
+}
+
+const MCP_SERVER_CMD = { command: 'npx', args: ['-y', 'context-mcp-server@latest'] };
+
 const PLATFORMS = {
   claude: {
     label: 'Claude Code',
-    install(cwd) {
-      const mcpJson = JSON.stringify({
-        mcpServers: { 'context-mcp': { command: 'npx', args: ['-y', 'context-mcp-server@latest'] } },
-      }, null, 2);
-      _writeFile(join(cwd, '.claude', 'mcp.json'), mcpJson, '.claude/mcp.json');
-      const md = _tpl('CLAUDE.md');
-      if (md) _writeFile(join(cwd, 'CLAUDE.md'), md, 'CLAUDE.md');
+    restartNote: 'Type /context-resume in Claude Code to start using context-mcp.',
+    install(dir, scope) {
+      // Install as a skill (global, works across all projects) instead of a flat CLAUDE.md
+      const skillSrc = join(TPLS, 'skills', 'SKILL.md');
+      const skillDest = join(homedir(), '.claude', 'skills', 'context-mcp', 'SKILL.md');
+      if (existsSync(skillSrc)) {
+        _writeFile(skillDest, readFileSync(skillSrc, 'utf8'), '~/.claude/skills/context-mcp/');
+      }
+      // Slash commands are always user-global (not project-scoped)
+      _writeCommands(homedir());
+      // Register via claude CLI so the server is trusted immediately (no manual trust prompt)
+      const scopeFlag = scope === 'global' ? 'user' : 'project';
+      const reg = spawnSync(
+        'claude', ['mcp', 'add', '--scope', scopeFlag, 'context-mcp', '--', 'npx', '-y', 'context-mcp-server@latest'],
+        { encoding: 'utf8', shell: true },
+      );
+      if (reg.status === 0) {
+        console.log(`  ${ok('✓')} ${'registered via claude mcp add'.padEnd(28)} ${faint('scope: ' + scopeFlag)}`);
+      } else {
+        console.log(`  ${faint('ℹ')} claude CLI not found — open Claude Code and trust context-mcp when prompted`);
+      }
     },
   },
   cursor: {
     label: 'Cursor',
-    install(cwd) {
-      const mcpJson = JSON.stringify({
-        mcpServers: { 'context-mcp': { command: 'npx', args: ['-y', 'context-mcp-server@latest'] } },
-      }, null, 2);
-      _writeFile(join(cwd, '.cursor', 'mcp.json'), mcpJson, '.cursor/mcp.json');
-      const mdc = _tpl('cursor-rules.mdc');
-      if (mdc) _writeFile(join(cwd, '.cursor', 'rules', 'context-mcp.mdc'), mdc, '.cursor/rules/context-mcp.mdc');
+    restartNote: 'Restart Cursor to load the new MCP server.',
+    install(dir, scope) {
+      const mcpJson = JSON.stringify({ mcpServers: { 'context-mcp': MCP_SERVER_CMD } }, null, 2);
+      _writeFile(join(dir, '.cursor', 'mcp.json'), mcpJson, '.cursor/mcp.json');
+      if (scope === 'project') {
+        const mdc = _tpl('cursor-rules.mdc');
+        if (mdc) _writeFile(join(dir, '.cursor', 'rules', 'context-mcp.mdc'), mdc, '.cursor/rules/context-mcp.mdc');
+      }
+      // Try to enable via cursor CLI (enable/disable only — no add command)
+      const reg = spawnSync(
+        'cursor', ['agent', 'mcp', 'enable', 'context-mcp'],
+        { encoding: 'utf8', shell: true },
+      );
+      if (reg.status === 0) {
+        console.log(`  ${ok('✓')} ${'enabled via cursor agent mcp'.padEnd(28)}`);
+      }
     },
   },
   vscode: {
     label: 'VS Code Copilot',
-    install(cwd) {
+    restartNote: 'Reload VS Code window (Ctrl+Shift+P → "Reload Window").',
+    install(dir) {
       const mcpJson = JSON.stringify({
-        servers: { 'context-mcp': { type: 'stdio', command: 'npx', args: ['-y', 'context-mcp-server@latest'] } },
+        servers: { 'context-mcp': { type: 'stdio', ...MCP_SERVER_CMD } },
       }, null, 2);
-      _writeFile(join(cwd, '.vscode', 'mcp.json'), mcpJson, '.vscode/mcp.json');
-      const md = _tpl('CLAUDE.md');
-      if (md) _writeFile(join(cwd, 'CLAUDE.md'), md, 'CLAUDE.md');
+      _writeFile(join(dir, '.vscode', 'mcp.json'), mcpJson, '.vscode/mcp.json');
     },
   },
   gemini: {
     label: 'Gemini CLI',
-    install(cwd) {
-      const cfg = JSON.stringify({
-        mcpServers: { 'context-mcp': { command: 'npx', args: ['-y', 'context-mcp-server@latest'] } },
-      }, null, 2);
-      _writeFile(join(cwd, '.gemini', 'settings.json'), cfg, '.gemini/settings.json');
-      const md = _tpl('GEMINI.md');
-      if (md) _writeFile(join(cwd, 'GEMINI.md'), md, 'GEMINI.md');
+    restartNote: 'Restart your Gemini CLI session.',
+    install(dir, scope) {
+      const cfg = JSON.stringify({ mcpServers: { 'context-mcp': MCP_SERVER_CMD } }, null, 2);
+      _writeFile(join(dir, '.gemini', 'settings.json'), cfg, '.gemini/settings.json');
+      if (scope === 'project') {
+        const md = _tpl('GEMINI.md');
+        if (md) _writeFile(join(dir, 'GEMINI.md'), md, 'GEMINI.md');
+      }
     },
   },
   codex: {
     label: 'Codex CLI',
-    install(cwd) {
+    restartNote: 'Restart your Codex CLI session.',
+    install(dir, scope) {
       const toml = `[[mcp_servers]]\nname    = "context-mcp"\ncommand = "npx"\nargs    = ["-y", "context-mcp-server@latest"]\n`;
-      _writeFile(join(cwd, '.codex', 'config.toml'), toml, '.codex/config.toml');
-      const md = _tpl('AGENTS.md');
-      if (md) _writeFile(join(cwd, 'AGENTS.md'), md, 'AGENTS.md');
+      _writeFile(join(dir, '.codex', 'config.toml'), toml, '.codex/config.toml');
+      if (scope === 'project') {
+        const md = _tpl('AGENTS.md');
+        if (md) _writeFile(join(dir, 'AGENTS.md'), md, 'AGENTS.md');
+      }
+      // Register via codex CLI so server is active immediately
+      const reg = spawnSync(
+        'codex', ['mcp', 'add', 'context-mcp', '--', 'npx', '-y', 'context-mcp-server@latest'],
+        { encoding: 'utf8', shell: true },
+      );
+      if (reg.status === 0) {
+        console.log(`  ${ok('✓')} ${'registered via codex mcp add'.padEnd(28)}`);
+      } else {
+        console.log(`  ${faint('ℹ')} codex CLI not found — server will load on next Codex session`);
+      }
     },
   },
   windsurf: {
     label: 'Windsurf',
-    install(cwd) {
+    restartNote: 'Restart Windsurf to load the updated MCP config.',
+    install(dir) {
       const rules = _tpl('windsurf-rules.md');
-      if (rules) _writeFile(join(cwd, '.windsurf', 'rules', 'context-mcp.md'), rules, '.windsurf/rules/context-mcp.md');
+      if (rules) _writeFile(join(dir, '.windsurf', 'rules', 'context-mcp.md'), rules, '.windsurf/rules/context-mcp.md');
       const globalCfgPath = join(homedir(), '.codeium', 'windsurf', 'mcp_config.json');
       let existing = {};
       try { existing = JSON.parse(readFileSync(globalCfgPath, 'utf8')); } catch {}
@@ -600,7 +740,7 @@ const PLATFORMS = {
   },
 };
 
-function cmdInstall(args) {
+async function cmdInstall(args) {
   const flags = new Set(args.map(a => a.replace(/^--/, '')));
   const all     = flags.has('all');
   const initial = flags.has('initial');
@@ -665,22 +805,59 @@ function cmdInstall(args) {
     return;
   }
 
-  const cwd = process.cwd();
-  printSection('Install', keys.map(k => PLATFORMS[k].label).join(', '));
-  console.log('');
+  // ── Scope prompt (skip for windsurf-only installs — it's always global) ──────
+  const nonWindsurf = keys.filter(k => k !== 'windsurf');
+  let scope = 'project';
+  let baseDir = process.cwd();
+
+  if (nonWindsurf.length > 0) {
+    const rl  = readline.createInterface({ input: process.stdin, output: process.stdout });
+    const ask = q => new Promise(resolve => rl.question(`  ${accent('›')} ${muted(q)} `, resolve));
+
+    printSection('Install', keys.map(k => PLATFORMS[k].label).join(', '));
+    console.log('');
+    console.log(`  ${muted('Install scope:')}`);
+    console.log(`  ${accent('1.')} For this project  ${faint('(writes config into current directory)')}`);
+    console.log(`  ${accent('2.')} Globally          ${faint('(writes config to your home directory)')}`);
+    console.log('');
+    const answer = (await ask('Choose (1/2) [1]:')).trim();
+    rl.close();
+    console.log('');
+
+    if (answer === '2') {
+      scope = 'global';
+      baseDir = homedir();
+    }
+  } else {
+    printSection('Install', keys.map(k => PLATFORMS[k].label).join(', '));
+    console.log('');
+  }
 
   for (const key of keys) {
-    console.log(`  ${bold(lblue(PLATFORMS[key].label))}`);
+    const platform = PLATFORMS[key];
+    console.log(`  ${bold(lblue(platform.label))}`);
+    const dir = key === 'windsurf' ? process.cwd() : baseDir;
     try {
-      PLATFORMS[key].install(cwd);
+      platform.install(dir, scope);
     } catch (err) {
       console.log(`  ${bad('✗')} failed: ${err.message}`);
     }
+    if (platform.restartNote) {
+      console.log(`  ${faint('→ ' + platform.restartNote)}`);
+    }
     console.log('');
   }
 
+  const destLabel = scope === 'global' ? homedir().replace(/\\/g, '/') : process.cwd().replace(/\\/g, '/');
   console.log(line());
-  console.log(faint(`  ${keys.length} platform(s) installed into ${cwd.replace(/\\/g, '/')}`));
+  console.log(faint(`  ${keys.length} platform(s) installed  ·  scope: ${scope}  ·  ${destLabel}`));
+  console.log('');
+
+  // ── Project .gitignore — add context-mcp entries for this project ──────────
+  _updateProjectGitignore(process.cwd());
+
+  // ── Global gitignore — add context-mcp runtime files if global gitignore exists ──
+  _updateGlobalGitignore();
   console.log('');
 
   // ── Python / uv setup (codegraph) ─────────────────────────────────────────
@@ -853,10 +1030,10 @@ async function cmdSettings(existingRl) {
   console.log('');
 
   const choice = (await ask('Edit field (1-' + FIELDS.length + '):')).trim();
-  if (!existingRl) rl.close();
 
   const idx = parseInt(choice) - 1;
   if (isNaN(idx) || idx < 0 || idx >= FIELDS.length) {
+    if (!existingRl) rl.close();
     console.log(`  ${faint('no changes made')}`);
     return;
   }
@@ -1007,7 +1184,7 @@ async function interactive() {
         case 'benchmark': case 'bench':
           clearScreen(); printCompactHeader('benchmark'); cmdBenchmark(); break;
         case 'install':
-          clearScreen(); printCompactHeader('install'); cmdInstall(rest); break;
+          clearScreen(); printCompactHeader('install'); await cmdInstall(rest); break;
         case 'online':
           clearScreen(); printCompactHeader('online'); cmdOnline(rest); break;
         case 'settings': case 'config':
@@ -1033,6 +1210,25 @@ function printBye() {
   console.log(`\n  ${ok('✓')} ${bold(lblue('goodbye'))}  ${faint('keep building')}\n`);
 }
 
+// ── Update check ──────────────────────────────────────────────────────────────
+
+async function checkForUpdate() {
+  try {
+    const result = spawnSync(
+      'npm', ['view', 'context-mcp-server', 'version', '--json'],
+      { encoding: 'utf8', timeout: 3000, shell: true },
+    );
+    if (result.status !== 0 || !result.stdout) return;
+    const parsed = JSON.parse(result.stdout.trim());
+    const latest = typeof parsed === 'string' ? parsed : String(parsed);
+    const current = pkg.version;
+    if (latest && latest !== current) {
+      console.log(`  ${warn('↑')} ${bold('Update available')}  ${faint(current)} ${accent('→')} ${ok(latest)}  ${faint('run:')} ${accent('npm i -g context-mcp-server@latest')}`);
+      console.log('');
+    }
+  } catch {}
+}
+
 // ── CLI entry point ───────────────────────────────────────────────────────────
 
 (async () => {
@@ -1052,7 +1248,24 @@ function printBye() {
     case 'benchmark': case 'bench':
       cmdBenchmark(); break;
     case 'install':
-      cmdInstall(rest); break;
+      await cmdInstall(rest);
+      process.exit(0);
+      break;
+    case 'update': {
+      printSection('Update');
+      console.log('');
+      const upd = spawnSync(
+        'npm', ['install', '-g', 'context-mcp-server@latest'],
+        { encoding: 'utf8', shell: true, stdio: 'inherit' },
+      );
+      if (upd.status === 0) {
+        console.log(`\n  ${ok('✓')} ${bold('context-mcp updated to latest')}`);
+      } else {
+        console.log(`\n  ${bad('✗')} update failed — try: ${accent('npm i -g context-mcp-server@latest')}`);
+      }
+      console.log('');
+      break;
+    }
     case 'online':
       cmdOnline(rest); break;
     case 'settings': case 'config':
@@ -1062,10 +1275,13 @@ function printBye() {
     case 'delete': case 'del': case 'rm':
       cmdDelete(rest); break;
     case 'help': case '--help': case '-h':
-      printUsage(); break;
+      await checkForUpdate();
+      printUsage();
+      break;
     case '--version': case '-v':
       console.log(pkg.version); break;
     default:
+      await checkForUpdate();
       await interactive();
   }
 })();

package/src/db.js

@@ -23,6 +23,11 @@ const PROJECTS_PATH     = join(DATA_DIR, 'projects.json');
 
 const MAX_CONTENT_LENGTH = 5000;
 const PREVIEW_LENGTH = 200;
+
+// Normalize file paths for cross-platform comparison (Windows case + slash variants)
+function normPath(p) {
+  return p ? p.toLowerCase().replace(/\\/g, '/').replace(/\/$/, '') : '';
+}
 const WRITE_DEBOUNCE_MS = 500;
 const LOCK_WAIT_TIMEOUT_MS = 2000;
 
@@ -126,9 +131,9 @@ function mergeStore(latest, local) {
     if (_changedDiscussionNames.has(disc.name)) discussionsByName.set(disc.name, disc);
   }
 
-  const graphsByPath = new Map((latest.graphs || []).map(g => [g.path, g]));
+  const graphsByPath = new Map((latest.graphs || []).map(g => [normPath(g.path), g]));
   for (const graph of (local.graphs || [])) {
-    if (_changedGraphPaths.has(graph.path)) graphsByPath.set(graph.path, graph);
+    if (_changedGraphPaths.has(graph.path)) graphsByPath.set(normPath(graph.path), graph);
   }
 
   const projectsById = new Map((latest.projects || []).map(p => [p.id, p]));
@@ -713,7 +718,7 @@ export function flushStore() { flushToDisk(); }
 
 // ── Auto-compaction ───────────────────────────────────────────────────────────
 
-const COMPACTION_THRESHOLD = 50;
+const COMPACTION_THRESHOLD = 20;
 const COMPACTION_TARGET = 30;
 
 export function shouldCompact(project) {
@@ -753,7 +758,14 @@ export function compactProject(project, summaryContent) {
 export function saveGraph({ path, nodes, edges, communities, cached, changed, time_ms, summary }) {
   refreshFromDisk();
   const store = load();
-  const existing = store.graphs.find(g => g.path === path);
+  // Deduplicate: collapse any case/slash variants of same path, keep newest
+  const dupes = store.graphs.filter(g => normPath(g.path) === normPath(path));
+  if (dupes.length > 1) {
+    const keep = dupes.reduce((a, b) => (a.builtAt >= b.builtAt ? a : b));
+    store.graphs = store.graphs.filter(g => normPath(g.path) !== normPath(path));
+    store.graphs.push(keep);
+  }
+  const existing = store.graphs.find(g => normPath(g.path) === normPath(path));
   const record = {
     path,
     nodes:       nodes       ?? existing?.nodes       ?? 0,
@@ -777,7 +789,7 @@ export function saveGraph({ path, nodes, edges, communities, cached, changed, ti
 
 export function getGraph(path) {
   const store = load();
-  if (path) return store.graphs.find(g => g.path === path) || null;
+  if (path) return store.graphs.find(g => normPath(g.path) === normPath(path)) || null;
   return store.graphs;
 }
 

package/src/hooks/autoContext.js

@@ -3,7 +3,7 @@ import { fireAutoLink } from './autoLink.js';
 
 export function saveAutoContext({ title, content, type, files, state, tags = [] }) {
   const entry = saveContext({
-    project:   state.sessionProject || 'global',
+    project:   state.sessionProject || null,
     sessionId: state.sessionId || null,
     title,
     content,

package/src/templates/AGENTS.md

@@ -20,22 +20,40 @@ Then:
 
 ---
 
-## 2. During the Conversation
+## 2. When to Auto-Save Context
 
-| Situation | Action |
-|-----------|--------|
-| Decision made | `context.save` type: `"decision"` |
-| Bug found/fixed | `context.save` type: `"bug"` |
-| Architecture understood | `context.save` type: `"architecture"` |
-| User says "save/remember this" | `context.save` immediately |
-| Feature spans sessions | `discussion.save` status: `"active"` |
-| Need past info | `search` before asking user |
+**After graph build or rebuild** — every time `codegraph_build` completes:
+```
+context.save  type: "architecture"  title: "ContextGraph built — <project>"
+content: "nodes: X | edges: Y | communities: Z"
+```
+
+**User explicitly asks** — "save this", "remember this", "note that" → save immediately.
 
-Always pass `project`. Auto-compact fires at >50 entries.
+**During plan / implementation / discussion / research** — save only when genuinely valuable:
+
+| What happened | Type |
+|--------------|------|
+| Approach / library / pattern decided | `decision` |
+| Bug found (root cause known) or fixed | `bug` |
+| System structure understood | `architecture` |
+| Gotcha, constraint, non-obvious behavior | `note` |
+| Config / env var / secret key discovered | `config` |
+| External API or service integration learned | `note` |
+| Performance insight (why something is slow/fast) | `note` |
+| How to run tests / test pattern discovered | `note` |
+| Deploy / release step discovered | `note` |
+| Milestone / feature / task completed | `note` |
+
+Do NOT save: routine reads, search results, temporary debugging dead-ends.
+Feature spans sessions → `discussion.save` status: `"active"`.
+Need past info → `search` before asking. Always pass `project`.
 
 ---
 
-## 3. CodeGraph Pipeline
+## 3. ContextGraph Pipeline
+
+> The knowledge graph is also called **ContextGraph**. The MCP tools use the `codegraph_*` prefix — both names refer to the same thing.
 
 ### Step 1 — Build (once, fast, local)
 ```

package/src/templates/CLAUDE.md

@@ -15,7 +15,12 @@ Every conversation starts with `context.resume`. Every codebase question uses `c
 
 ## 1. Start of Every Conversation (MANDATORY)
 
-Call `context` tool, `action: "resume"`, `project: "<project-name>"` **before anything else**.
+Call `context` tool **before anything else** with:
+- `action: "resume"`
+- `project: "<basename of git repo root dir>"` — infer from cwd if not stated
+- `rootPath: "<absolute path to git repo root>"` — required for sandbox + graph lookup
+
+Both fields are required: `project` names the memory bucket, `rootPath` enables exact graph matching and file sandboxing.
 
 Returns:
 - `recentEntries` — decisions, bugs, notes from previous conversations
@@ -28,22 +33,44 @@ Then:
 
 ---
 
-## 2. During the Conversation
+## 2. When to Auto-Save Context
+
+### Always save — no user prompt needed
+
+**After graph build or rebuild** — every time `codegraph_build` completes:
+```
+context.save  project: "<project>"  type: "architecture"  title: "ContextGraph built — <project>"
+content: "nodes: X | edges: Y | communities: Z"
+```
 
-| Situation | Action |
-|-----------|--------|
-| Decision made | `context.save` type: `"decision"` |
-| Bug found/fixed | `context.save` type: `"bug"` |
-| Architecture understood | `context.save` type: `"architecture"` |
-| User says "save/remember this" | `context.save` immediately |
-| Feature spans multiple conversations | `discussion.create` or `discussion.update` |
-| Need past info | `search` before asking user |
+**User explicitly asks** — any phrase like "save this", "remember this", "note that" → save immediately.
 
-Always pass `project`. Auto-compact fires at >50 entries — oldest summarized automatically.
+**During plan / implementation / discussion / research** — save only when genuinely valuable:
+
+| What happened | Type |
+|--------------|------|
+| Approach / library / pattern decided | `decision` |
+| Bug found (root cause known) or fixed | `bug` |
+| System structure understood | `architecture` |
+| Gotcha, constraint, non-obvious behavior | `note` |
+| Config / env var / secret key discovered | `config` |
+| External API or service integration learned | `note` |
+| Performance insight (why something is slow/fast) | `note` |
+| How to run tests / test pattern discovered | `note` |
+| Deploy / release step discovered | `note` |
+| Milestone / feature / task completed | `note` |
+
+Do NOT save: routine reads, search results, temporary debugging dead-ends.
+
+Feature spans multiple sessions → `discussion.create` or `discussion.update`.
+Need past info → `search` before asking user.
+Always pass `project`. Auto-compact fires at >20 entries.
 
 ---
 
-## 3. CodeGraph Pipeline
+## 3. ContextGraph Pipeline
+
+> The knowledge graph is also called **ContextGraph**. The MCP tools use the `codegraph_*` prefix — both names refer to the same thing.
 
 ### Step 1 — Build (once per project, fast, local)
 ```

package/src/templates/GEMINI.md

@@ -20,22 +20,40 @@ Then:
 
 ---
 
-## 2. During the Conversation
+## 2. When to Auto-Save Context
 
-| Situation | Action |
-|-----------|--------|
-| Decision made | `context.save` type: `"decision"` |
-| Bug found/fixed | `context.save` type: `"bug"` |
-| Architecture understood | `context.save` type: `"architecture"` |
-| User says "save/remember this" | `context.save` immediately |
-| Feature spans sessions | `discussion.save` then `discussion.update` |
-| Need past info | `search` before asking user |
+**After graph build or rebuild** — every time `codegraph_build` completes:
+```
+context.save  type: "architecture"  title: "ContextGraph built — <project>"
+content: "nodes: X | edges: Y | communities: Z"
+```
+
+**User explicitly asks** — "save this", "remember this", "note that" → save immediately.
 
-Always pass `project`. Auto-compact fires at >50 entries.
+**During plan / implementation / discussion / research** — save only when genuinely valuable:
+
+| What happened | Type |
+|--------------|------|
+| Approach / library / pattern decided | `decision` |
+| Bug found (root cause known) or fixed | `bug` |
+| System structure understood | `architecture` |
+| Gotcha, constraint, non-obvious behavior | `note` |
+| Config / env var / secret key discovered | `config` |
+| External API or service integration learned | `note` |
+| Performance insight (why something is slow/fast) | `note` |
+| How to run tests / test pattern discovered | `note` |
+| Deploy / release step discovered | `note` |
+| Milestone / feature / task completed | `note` |
+
+Do NOT save: routine reads, search results, temporary debugging dead-ends.
+Feature spans sessions → `discussion.save` then `discussion.update`.
+Need past info → `search` before asking. Always pass `project`.
 
 ---
 
-## 3. CodeGraph Pipeline
+## 3. ContextGraph Pipeline
+
+> The knowledge graph is also called **ContextGraph**. The MCP tools use the `codegraph_*` prefix — both names refer to the same thing.
 
 ### Step 1 — Build (once, fast, local)
 ```

package/src/templates/commands/context-resume.md

@@ -0,0 +1,10 @@
+Call the `context` MCP tool with `action: "resume"`, `project: "$ARGUMENTS"` (if no argument given, infer the project name from the current working directory name), and `rootPath: "<absolute path to the project root / git repo root>"`.
+
+Both `project` and `rootPath` are required: `project` names the memory bucket, `rootPath` enables exact graph lookup and file sandboxing.
+
+This loads:
+- Recent decisions, bugs, and notes from past sessions
+- Active discussions
+- ContextGraph status (built or not)
+
+If `codegraph.built` is false in the response, immediately call `codegraph_build` on the project path before proceeding.

package/src/templates/commands/graph-build.md

@@ -0,0 +1,5 @@
+Call `codegraph_build` with the path `$ARGUMENTS` (if no argument given, use the current working directory).
+
+This builds the ContextGraph for the project — parses all source files into an AST knowledge graph using tree-sitter. Takes a few seconds. Once built, use `codegraph_query` to answer any structural question about the codebase instead of reading files directly.
+
+After build completes, report: total nodes, edges, and communities found.

package/src/templates/commands/save-context.md

@@ -0,0 +1,9 @@
+Call the `context` MCP tool with `action: "save"` to store a note for the current project.
+
+Parse `$ARGUMENTS` to determine:
+- `project`: infer from current working directory name if not specified
+- `title`: first sentence or phrase from the argument
+- `content`: full argument text
+- `type`: auto-detect — if mentions a bug/fix → `"bug"`, decision/chose/decided → `"decision"`, structure/architecture → `"architecture"`, otherwise `"note"`
+
+Confirm to the user what was saved (title, type, project).

package/src/templates/skills/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: context-mcp
+description: >
+  Persistent memory + ContextGraph (codebase knowledge graph) for Claude.
+  Use at the START of every conversation to resume project context. Use
+  whenever the user mentions a project, asks to remember/save something,
+  references past work, or says "pick up where we left off". Also use
+  when the user asks about code structure, dependencies, or what exists
+  in a codebase — query the ContextGraph before reading any files.
+---
+
+# Context-MCP
+
+Persistent memory + codebase knowledge graph across every conversation.
+`context.resume` starts every session. `codegraph_query` answers every structure question. Files only for bugs/logic.
+
+---
+
+## MANDATORY: Start of Every Conversation
+
+Call `context` tool **before any tool or response** with:
+- `action: "resume"`
+- `project: "<basename of git repo root dir>"` — infer from `cwd` if not stated
+- `rootPath: "<absolute path to git repo root>"` — required for sandbox + graph lookup
+
+Both fields are required: `project` names the memory bucket, `rootPath` enables exact graph matching and file sandboxing.
+
+Returns:
+- `recentEntries` — decisions, bugs, notes from past sessions
+- `activeDiscussions` — ongoing topics (auto-linked if exactly one active)
+- `codegraph` — `{ built: true/false, nodes, edges, communities }`
+
+Then:
+- `codegraph.built: true` → use `codegraph_query` before reading any files
+- `codegraph.built: false` → call `codegraph_build(path)` first, then proceed
+
+---
+
+## When to Auto-Save Context
+
+### Always save — no user prompt needed
+
+**1. After graph build or rebuild**
+Every time `codegraph_build` completes successfully, immediately call:
+```
+context.save  project: "<project>"  type: "architecture"  title: "ContextGraph built — <project>"
+content: "nodes: X | edges: Y | communities: Z | built: <timestamp>"
+```
+
+**2. When user explicitly asks**
+Any phrase like "save this", "remember this", "note that", "log this" → `context.save` immediately with whatever was just discussed.
+
+**3. During plan / implementation / discussion / research — save when something valuable happens**
+Only save if the moment is genuinely worth keeping across sessions:
+- A decision was made and agreed on (approach, library, pattern, architecture)
+- A bug was found with its root cause identified, or fixed
+- An important discovery (gotcha, constraint, non-obvious behavior, env requirement)
+- A significant milestone reached (feature complete, refactor done, plan finalized)
+- Something that would save future-you from re-learning it
+
+Do NOT save for: routine file reads, search results, explanations of existing code, temporary debugging steps that led nowhere.
+
+| What happened | Type |
+|--------------|------|
+| Approach / library / pattern decided | `decision` |
+| Bug found (root cause known) or fixed | `bug` |
+| System structure understood | `architecture` |
+| Gotcha, constraint, non-obvious behavior | `note` |
+| Config / env var / secret key discovered | `config` |
+| External API or service integration learned | `note` |
+| Performance insight (why something is slow/fast) | `note` |
+| How to run tests / test pattern discovered | `note` |
+| Deploy / release step discovered | `note` |
+| Milestone / feature / task completed | `note` |
+
+Always pass `project`. Feature spans multiple sessions → `discussion.create` or `discussion.update`. Need past info → `search` before asking user. Auto-compact fires at >20 entries.
+
+---
+
+## ContextGraph Pipeline
+
+> Also called **CodeGraph**. MCP tools use the `codegraph_*` prefix — both names mean the same thing.
+
+### Build (once per project, ~seconds, local)
+```
+codegraph_build(path)
+```
+Parses codebase into AST graph via tree-sitter. Extracts functions, classes, imports, call edges for 16+ languages. Build files get a single metadata node. Saved to `~/.context-mcp/graphs.json`.
+
+### Query (free, instant, forever)
+```
+codegraph_query(path, question)   → find functions, classes, files, dependencies, callers
+codegraph_explain(path, node)     → one node: type, file, depends_on, used_by
+codegraph_path(path, from, to)    → shortest path between two concepts
+codegraph_nodes(path, type)       → list all nodes of a type
+codegraph_report(path)            → god nodes, clusters, surprises
+```
+
+---
+
+## Graph vs File
+
+**Graph** — what exists: finding functions, classes, files, dependencies, callers, imports, paths between concepts.
+
+**File** — bugs, logic inside a specific function, tracing unexpected behavior.
+
+---
+
+## Rules
+
+1. **`context.resume` first** — before any tool or response
+2. **Always pass `project`** — never save to global unless truly cross-project
+3. **`search` before asking** — if user references past work, find it first
+4. **`codegraph_query` before reading files** — graph is faster and cheaper
+5. **Read files for bugs/logic only** — graph is structure, not behavior

package/src/tools/codegraph.js

@@ -184,7 +184,10 @@ export function handle(name, args, state) {
         summary:     result.summary || '',
       });
 
-      const project = state?.sessionProject || 'global';
+      const inferredProject = args.path
+        ? args.path.replace(/\\/g, '/').replace(/\/$/, '').split('/').pop()
+        : null;
+      const project = state?.sessionProject || inferredProject || null;
       const title   = `CodeGraph — ${args.path}`;
       const content = [
         `nodes: ${result.nodes} | edges: ${result.edges} | communities: ${result.communities}`,

package/src/tools/context.js

@@ -92,9 +92,15 @@ export async function handle(args, state) {
         .filter(e => e.status !== 'archived');
       const discussions   = listDiscussions({ project: proj, status: 'active' });
       const allGraphs     = listGraphs();
-      const graph         = proj
-        ? allGraphs.find(g => g.path?.toLowerCase().includes(proj.toLowerCase())) || allGraphs[0] || null
-        : allGraphs[0] || null;
+      const np = p => (p || '').toLowerCase().replace(/\\/g, '/');
+      const graph         = resolvedRoot
+        ? allGraphs.find(g => np(g.path) === np(resolvedRoot)) || null
+        : proj
+          ? allGraphs.find(g => {
+              const parts = np(g.path).split('/');
+              return parts[parts.length - 1] === proj.toLowerCase();
+            }) || null
+          : null;
       const totalEntries  = countContext(proj);
 
       // Auto-restore single active discussion

package/src/tools/gitTools.js

@@ -29,11 +29,10 @@ function resolveCwd(args, state) {
   // Auto-detect project root on first use if not already configured.
   if (!state.projectRootPath) {
     const detected = autoDetectRoot(args.cwd ? pathResolve(args.cwd) : process.cwd());
-    if (detected) state.projectRootPath = detected;
+    state.projectRootPath = detected || process.cwd();
   }
-  const raw = args.cwd ? pathResolve(args.cwd) : (state.projectRootPath || process.cwd());
-  if (state.projectRootPath) return guardPath(raw, state.projectRootPath);
-  return raw;
+  const raw = args.cwd ? pathResolve(args.cwd) : state.projectRootPath;
+  return guardPath(raw, state.projectRootPath);
 }
 
 const ROOT_NOTE = ' All paths must be within the project root (sandboxed — access outside root is denied).';

package/uv.lock

@@ -168,7 +168,7 @@ wheels = [
 
 [[package]]
 name = "codegraph-mcp"
-version = "1.0.3"
+version = "1.0.5"
 source = { editable = "." }
 dependencies = [
     { name = "mcp" },