context-mcp-server 1.0.8 → 1.1.0

package/codegraph/graph/query.py

@@ -237,6 +237,49 @@ def _general_search(matched: list, nodes: list, edges: list) -> dict:
     }
 
 
+def module_map(graph_dict: dict, limit: int = 100) -> dict:
+    """
+    Return a module map: for each file, its exported functions/classes and what it imports.
+    Output grouped by file, sorted by export count descending.
+    """
+    nodes = graph_dict.get("nodes", [])
+    edges = graph_dict.get("edges", [])
+
+    files: dict[str, dict] = {}
+    for n in nodes:
+        f = n.get("file") or "unknown"
+        if f not in files:
+            files[f] = {"exports": [], "imports": set()}
+        node_type = n.get("type", "?")
+        if node_type in ("function", "class", "struct"):
+            files[f]["exports"].append({"name": n["name"], "type": node_type})
+
+    node_map = {n["id"]: n for n in nodes}
+    for e in edges:
+        from_node = node_map.get(e.get("from", ""))
+        to_node   = node_map.get(e.get("to", ""))
+        if not from_node or not to_node:
+            continue
+        from_file = from_node.get("file") or "unknown"
+        to_file   = to_node.get("file") or "unknown"
+        if from_file != to_file and from_file in files:
+            files[from_file]["imports"].add(to_file)
+
+    result = []
+    for fpath, data in sorted(files.items(), key=lambda x: -len(x[1]["exports"])):
+        result.append({
+            "file":    fpath,
+            "exports": data["exports"][:30],
+            "imports": sorted(data["imports"])[:20],
+        })
+
+    return {
+        "files":       result[:limit],
+        "total_files": len(files),
+        "truncated":   len(files) > limit,
+    }
+
+
 def _render_subgraph(result_nodes: list, all_edges: list, token_budget: int) -> str:
     """
     Render a subgraph as structured plain text (graphify-style).

package/codegraph/server.py

@@ -4,10 +4,10 @@ codegraph/server.py — MCP server exposing codebase knowledge graph tools.
 
 Tools:
   codegraph_build   — scan project, extract AST nodes, build graph (local only, no API)
-  codegraph_query   — structural question OR single-node lookup (or both); replaces codegraph_explain
+  codegraph_query   — structural question OR single-node lookup (or both)
+  codegraph_arch    — module map: every file with its exports and imports
   codegraph_report  — return full CODEGRAPH_REPORT.md
   codegraph_nodes   — list nodes of a given type
-  codegraph_path    — shortest path between two concepts
 """
 
 import asyncio
@@ -25,7 +25,7 @@ from .config import classify_file
 from .cache import file_hash, set_cached_nodes, save_cache
 from .extractors.ast_extractor import extract as ast_extract
 from .graph.builder import build, to_json_dict, save_graph, load_graph
-from .graph.query import answer as graph_answer, find_path
+from .graph.query import answer as graph_answer, module_map
 from .graph.clustering import detect_communities
 from .report import generate as generate_report
 
@@ -95,16 +95,19 @@ TOOLS = [
         },
     ),
     Tool(
-        name="codegraph_path",
-        description="Find the shortest relationship path between two concepts in the graph.",
+        name="codegraph_arch",
+        description=(
+            "Return a module map: every file with its exported functions/classes and what it imports. "
+            "Use this to understand project structure without reading any files. "
+            "Call after codegraph_build. Much faster than reading each file."
+        ),
         inputSchema={
             "type": "object",
             "properties": {
-                "path": {"type": "string"},
-                "from": {"type": "string"},
-                "to":   {"type": "string"},
+                "path":  {"type": "string", "description": "Project root"},
+                "limit": {"type": "integer", "description": "Max files in output (default 100)"},
             },
-            "required": ["path", "from", "to"],
+            "required": ["path"],
         },
     ),
 ]
@@ -125,12 +128,11 @@ async def call_tool(name: str, arguments: dict):
 
 
 async def _dispatch(name: str, args: dict):
-    if name == "codegraph_build":   return await _build(args)
-    if name == "codegraph_query":   return await _query(args)
-    if name == "codegraph_explain": return await _query(args)
-    if name == "codegraph_report":  return await _report(args)
-    if name == "codegraph_nodes":   return await _nodes(args)
-    if name == "codegraph_path":    return await _path(args)
+    if name == "codegraph_build":  return await _build(args)
+    if name == "codegraph_query":  return await _query(args)
+    if name == "codegraph_report": return await _report(args)
+    if name == "codegraph_nodes":  return await _nodes(args)
+    if name == "codegraph_arch":   return await _arch(args)
     raise ValueError(f"Unknown tool: {name}")
 
 
@@ -285,11 +287,12 @@ async def _nodes(args: dict) -> dict:
     return {"type": node_type, "count": len(matched), "nodes": matched[:limit]}
 
 
-async def _path(args: dict) -> dict:
+async def _arch(args: dict) -> dict:
     graph_dict = load_graph(args["path"])
     if not graph_dict:
         raise ValueError("No graph found. Run codegraph_build first.")
-    return find_path(args["from"], args["to"], graph_dict)
+    limit = args.get("limit", 100)
+    return module_map(graph_dict, limit=limit)
 
 
 # ── Entry point ───────────────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-mcp-server",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "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.8"
+version = "1.1.0"
 description = "Codebase knowledge graph MCP server — AST extraction, graph queries, community detection"
 readme = "README.md"
 requires-python = ">=3.11"

package/src/cli.js

@@ -107,45 +107,29 @@ function printSection(title, meta = '') {
 function printUsage() {
   printBanner();
 
-  // Terminal commands (ctx / context ...)
-  printSection('Terminal commands', 'run from your shell  (ctx … or context …)');
+  printSection('Commands');
   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 save --title "…" --content "…" --project <p> --type <t>', 'non-interactive save (scripts/hooks)');
   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)');
+  cmd('ctx stats',                     'storage report: entries, types, graph status');
   console.log('');
-  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 install --initial',         'install / update Node.js + Python (codegraph) deps only');
+  cmd('ctx install --<platform>',      'write MCP config + skill/rules file only (no uv/npm)');
+  cmd('ctx install --all',             'write config + skill files for all platforms');
   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)');
   cmd('ctx update',                    'check for and apply latest version');
   cmd('ctx help',                      'show this screen');
   console.log('');
-
-  // Interactive mode commands (no prefix needed)
-  printSection('Interactive mode', 'type these inside the UI — no "ctx" prefix needed');
-  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
@@ -155,7 +139,8 @@ function clearScreen() {
 // ── List (grouped by project) ─────────────────────────────────────────────────
 
 function cmdList(args) {
-  const filterProject  = args[0];
+  const projectFlagIdx = args.indexOf('--project');
+  const filterProject  = projectFlagIdx !== -1 ? args[projectFlagIdx + 1] : args[0];
   const entries        = getContext({ project: filterProject, limit: 100 });
   const allDiscussions = listDiscussions({ project: filterProject });
   const allGraphs      = listGraphs();
@@ -163,7 +148,6 @@ function cmdList(args) {
 
   printSection('Context', filterProject ? `project: ${filterProject}` : 'all projects');
 
-  // Build per-project map, split entries into their three trees
   const projects = {};
   const ensureProj = p => {
     if (!projects[p]) projects[p] = { context: [], summary: [], plans: [] };
@@ -213,13 +197,12 @@ function cmdList(args) {
         const id   = item.id.slice(0, 8);
         const tags = safeTags(item.tags);
         const pipe = secIsLast ? ' ' : '│';
-        console.log(`  ${color(C.darkgray, pipe)}  ${color(C.darkgray, br)} ${pill(item.type || 'note')}  ${bold(item.title || '(no title)')}  ${faint('id:' + id)}  ${faint(date)}`);
+        console.log(`  ${color(C.darkgray, pipe)}  ${color(C.darkgray, br)} ${bold(item.title || '(no title)')}  ${faint('id:' + id)}  ${faint(date)}`);
         if (tags.length) console.log(`  ${color(C.darkgray, pipe)}     ${faint(tags.map(t => '#' + t).join(' '))}`);
       });
       if (!secIsLast) console.log(`  ${color(C.darkgray, '│')}`);
     };
 
-    // ── Graph (build stats only) ──────────────────────────────────────────────
     if (graphBuild) {
       secIdx++;
       const isLast  = secIdx === sections.length;
@@ -228,13 +211,11 @@ function cmdList(args) {
       if (!isLast) console.log(`  ${color(C.darkgray, '│')}`);
     }
 
-    // ── Context ───────────────────────────────────────────────────────────────
     if (pData.context.length) {
       secIdx++;
       renderEntries(pData.context, 'context', secIdx === sections.length);
     }
 
-    // ── Summary (compaction digests only — no type labels) ───────────────────
     if (pData.summary.length) {
       secIdx++;
       const isLast = secIdx === sections.length;
@@ -248,7 +229,6 @@ function cmdList(args) {
       if (!isLast) console.log(`  ${color(C.darkgray, '│')}`);
     }
 
-    // ── Plans ─────────────────────────────────────────────────────────────────
     if (pData.plans.length) {
       secIdx++;
       const isLast = secIdx === sections.length;
@@ -285,7 +265,7 @@ function cmdSearch(args) {
     const id     = entry.id.slice(0, 8);
     const type   = entry.type || 'note';
     const isLast = index === results.length - 1;
-    console.log(`  ${color(C.darkgray, isLast ? '└─' : '├─')} ${bold(entry.title || '(no title)')}${score}  ${pill(type)}  ${faint('id:' + id)}  ${faint(date)}`);
+    console.log(`  ${color(C.darkgray, isLast ? '└─' : '├─')} ${bold(entry.title || '(no title)')}${score}  ${faint('id:' + id)}  ${faint(date)}`);
   });
   console.log('');
   console.log(line());
@@ -313,7 +293,6 @@ function cmdProjects() {
     console.log(`\n  ${color(C.dblue, '◆')} ${bold(lblue(project.name))}${idTag}  ${bar}  ${faint(project.count + ' entries')}`);
     console.log(`  ${color(C.darkgray, '│')}`);
 
-    // Graph status
     if (graph) {
       const builtAt = (graph.builtAt || '').slice(0, 10);
       console.log(`  ${color(C.darkgray, '├─')} ${accent('⬡')} ${muted('graph')}  ${faint(`${graph.nodes}n · ${graph.edges}e · ${graph.communities} clusters · ${builtAt}`)}`);
@@ -321,18 +300,15 @@ function cmdProjects() {
       console.log(`  ${color(C.darkgray, '├─')} ${faint('⬡ no graph')}`);
     }
 
-    // Recent context
     if (entries.length) {
       console.log(`  ${color(C.darkgray, '├─')} ${muted('recent')}`);
       entries.forEach((e, i) => {
         const br   = i === entries.length - 1 && !activeD.length ? '└─' : '├─';
-        const type = e.type || 'note';
         const date = (e.createdAt || '').slice(0, 10);
-        console.log(`  ${color(C.darkgray, '│')}  ${color(C.darkgray, br)} ${pill(type)}  ${bold(e.title || '(no title)')}  ${faint(date)}`);
+        console.log(`  ${color(C.darkgray, '│')}  ${color(C.darkgray, br)} ${bold(e.title || '(no title)')}  ${faint(date)}`);
       });
     }
 
-    // Active discussions
     if (activeD.length) {
       console.log(`  ${color(C.darkgray, '├─')} ${muted('discussions')}`);
       activeD.forEach((d, i) => {
@@ -354,7 +330,8 @@ function cmdProjects() {
 // ── Discussions ───────────────────────────────────────────────────────────────
 
 function cmdDiscussions(args) {
-  const filterProject = args[0];
+  const projectFlagIdx = args.indexOf('--project');
+  const filterProject  = projectFlagIdx !== -1 ? args[projectFlagIdx + 1] : args[0];
   const discussions   = listDiscussions({ project: filterProject });
   printSection('Discussions', filterProject || 'all projects');
 
@@ -392,7 +369,8 @@ function cmdDiscussions(args) {
 // ── Summary ───────────────────────────────────────────────────────────────────
 
 function cmdSummary(args) {
-  const project = args[0];
+  const projectFlagIdx = args.indexOf('--project');
+  const project        = projectFlagIdx !== -1 ? args[projectFlagIdx + 1] : args[0];
   const entries = getContext({ project, limit: 50 });
   printSection('Summary', project || 'global');
   if (!entries.length) { console.log(`  ${faint('no entries to summarize')}`); return; }
@@ -411,137 +389,54 @@ function cmdSummary(args) {
 // ── Benchmark ────────────────────────────────────────────────────────────────
 
 
-function _walkBytes(dirPath) {
-  const walkScript =
-    `const fs=require('fs'),path=require('path');` +
-    `function walk(d,t=0){try{for(const f of fs.readdirSync(d)){` +
-    `const p=path.join(d,f);try{const s=fs.statSync(p);` +
-    `if(s.isDirectory()&&!['node_modules','.git','codegraph-cache','.venv','venv','__pycache__','dist','build','.next'].includes(f))t+=walk(p);` +
-    `else if(s.isFile()&&/\\.(js|jsx|ts|tsx|py|json|md|yaml|yml|toml|sh|bash|env|txt|css|html|sql|go|rs|java|rb|php|c|cpp|h)$/.test(f)&&!/^(package-lock|uv\.lock|yarn\.lock|Pipfile\.lock|poetry\.lock)$/.test(path.basename(f,path.extname(f))+path.extname(f)))t+=s.size;}catch{}}}catch{}return t;}` +
-    `console.log(walk(${JSON.stringify(dirPath)}));`;
-  const res = spawnSync('node', ['-e', walkScript], { encoding: 'utf8', timeout: 8000 });
-  return res.stdout ? parseInt(res.stdout.trim()) : null;
-}
-
-function _sampleQueryTokens(graphPath) {
-  const questions = ['what does the server do', 'how is the graph built', 'what calls save'];
-  const sizes = [];
-  for (const q of questions) {
-    const req = JSON.stringify({ tool: 'codegraph_query', args: { path: graphPath, question: q, token_budget: 2000 } });
-    const res = spawnSync('uv', ['run', 'python', '-m', 'codegraph'],
-      { input: req, encoding: 'utf8', cwd: process.cwd(), timeout: 12000 });
-    if (res.stdout) { try { const r = JSON.parse(res.stdout); if (!r.error) sizes.push(res.stdout.length); } catch {} }
-  }
-  return { avgTok: sizes.length ? Math.round(sizes.reduce((a, b) => a + b, 0) / sizes.length / 4) : 472, measured: sizes.length > 0 };
-}
-
-function cmdBenchmark() {
-  const graphs   = listGraphs();
-  const projects = listProjects();
-  printSection('Benchmark', 'real token savings');
-
-  const RESUME_LIMIT = 15;
-  const COMPACT_AT   = 20;
-
-  // ── Measure entry sizes from actual stored data ──────────────────────────────
-  const allEntries   = getContext({ limit: 500, compact: false });
-  const totalEntries = allEntries.length;
-  let avgFullTok = 155, avgCompactTok = 50;
-  if (allEntries.length) {
-    const fullSizes    = allEntries.map(e => JSON.stringify(e).length);
-    const compactSizes = allEntries.map(e =>
-      ([e.title || '', (e.content || '').slice(0, 200), (e.tags || []).join(' ')].join(' ')).length);
-    avgFullTok    = Math.round(fullSizes.reduce((a, b) => a + b, 0) / fullSizes.length / 4);
-    avgCompactTok = Math.round(compactSizes.reduce((a, b) => a + b, 0) / compactSizes.length / 4);
-  }
+function cmdStats() {
+  const projects   = listProjects();
+  const graphs     = listGraphs();
+  const allEntries = getContext({ limit: 2000, compact: false });
 
-  // ── Run graph queries once, reuse in both sections ────────────────────────────
-  let avgQueryTok = 472, queryMeasured = false;
-  if (graphs.length) {
-    const r = _sampleQueryTokens(graphs[0].path);
-    avgQueryTok   = r.avgTok;
-    queryMeasured = r.measured;
-  }
+  printSection('Stats', 'context-mcp storage report');
 
-  // ── Corpus size (run once) ────────────────────────────────────────────────────
-  let corpusToks = null;
-  if (graphs.length) {
-    const bytes = _walkBytes(graphs[0].path);
-    if (bytes) corpusToks = Math.round(bytes / 4);
-  }
-
-  // ── Memory ───────────────────────────────────────────────────────────────────
-  // Without context-mcp: AI reads all entries at full size every conversation
-  // With context-mcp:    AI loads min(15, N) entries as compact previews via resume
-  console.log(`\n  ${bold(lblue('Memory'))}  ${faint('measured from actual stored entries')}`);
-  if (totalEntries) {
-    const resumeCount   = Math.min(RESUME_LIMIT, totalEntries);
-    const withoutMemTok = totalEntries * avgFullTok;         // load all entries full
-    const withMemTok    = resumeCount  * avgCompactTok;      // resume: compact previews only
-    const memSaved      = withoutMemTok - withMemTok;
-    const memReduction  = (withoutMemTok / withMemTok).toFixed(1);
-    const memPct        = ((1 - withMemTok / withoutMemTok) * 100).toFixed(1);
-
-    console.log(`    ${faint('avg entry size (full):   ')} ${muted(avgFullTok)} tok  ${faint('(measured)')}`);
-    console.log(`    ${faint('avg entry size (compact):')} ${muted(avgCompactTok)} tok  ${faint('(measured)')}`);
-    console.log(`    ${faint('stored:                  ')} ${muted(totalEntries)} entries  ${faint('across')} ${muted(projects.length)} project(s)`);
-    console.log(`    ${faint('without — load all full: ')} ${warn('~' + withoutMemTok.toLocaleString('en-US'))} tokens`);
-    console.log(`    ${faint('with    — resume compact:')} ${ok('~' + withMemTok.toLocaleString('en-US'))} tokens  ${faint(`(${resumeCount} of ${totalEntries} entries)`)}`);
-    console.log(`    ${faint('saved per chat:          ')} ${ok('~' + memSaved.toLocaleString('en-US'))} tokens  ${highlight(memReduction + '×')}  ${ok(memPct + '%')} reduction`);
-    console.log(`    ${faint('auto-compact at:         ')} ${faint(COMPACT_AT + ' entries → oldest summarized to 1')}`);
-    console.log('');
+  // ── Projects ──────────────────────────────────────────────────────────────────
+  console.log(`\n  ${bold(lblue('Projects'))}`);
+  if (!projects.length) {
+    console.log(`    ${faint('no projects yet')}`);
+  } else {
     for (const p of projects) {
-      const pToks  = p.count * avgFullTok;
-      const barLen = Math.min(Math.ceil(p.count / 2), 24);
-      const bar    = color(C.dblue, '█'.repeat(barLen)) + color(C.darkgray, '░'.repeat(24 - barLen));
-      console.log(`    ${color(C.darkgray, '·')} ${muted(p.name.padEnd(22))} ${bar}  ${faint(p.count + ' entries · ~' + pToks.toLocaleString('en-US') + ' tok full')}`);
+      const g = graphs.find(gr => {
+        const gp = (gr.path || '').replace(/\\/g, '/').replace(/\/$/, '').split('/').pop();
+        return gp === p.name;
+      });
+      const graphStatus = g ? ok(`graph: ${g.nodes} nodes, ${g.edges} edges`) : faint('no graph');
+      const builtAt = g?.builtAt ? faint('  built ' + g.builtAt.slice(0, 10)) : '';
+      console.log(`    ${bold(p.name.padEnd(24))} ${muted(String(p.count).padStart(3) + ' entries')}  ${graphStatus}${builtAt}`);
     }
-  } else {
-    console.log(`    ${faint('no entries yet')}`);
   }
 
-  // ── CodeGraph ─────────────────────────────────────────────────────────────────
-  // Without context-mcp: AI reads all source files to answer structural questions
-  // With context-mcp:    AI calls codegraph_query → focused NODE/EDGE subgraph
-  console.log(`\n  ${bold(lblue('CodeGraph'))}  ${faint('measured from live graph queries')}`);
-  if (!graphs.length) {
-    console.log(`    ${faint('no graphs — run codegraph_build first')}`);
+  // ── Entry type breakdown ──────────────────────────────────────────────────────
+  console.log(`\n  ${bold(lblue('Entries by type'))}`);
+  if (!allEntries.length) {
+    console.log(`    ${faint('no entries yet')}`);
   } else {
-    for (const g of graphs) {
-      const pathShort  = g.path.replace(/\\/g, '/').split('/').slice(-2).join('/');
-      const builtAt    = (g.builtAt || '').slice(0, 10);
-      const graphReduce = corpusToks ? (corpusToks / avgQueryTok).toFixed(0) + '×' : null;
-      const graphPct    = corpusToks ? ((1 - avgQueryTok / corpusToks) * 100).toFixed(2) : null;
-
-      console.log(`\n    ${accent('⬡')} ${bold(pathShort)}  ${faint(builtAt)}`);
-      console.log(`      ${faint('nodes:')} ${muted(g.nodes)}  ${faint('edges:')} ${muted(g.edges)}  ${faint('clusters:')} ${muted(g.communities)}`);
-      if (corpusToks) console.log(`      ${faint('without — read all files:')} ${warn('~' + corpusToks.toLocaleString('en-US'))} tokens  ${faint('(all source + config + doc files)')}`);
-      console.log(`      ${faint('with    — graph query:   ')} ${ok('~' + avgQueryTok.toLocaleString('en-US'))} tokens  ${faint(queryMeasured ? '(avg of 3 live queries)' : '(calibrated fallback)')}`);
-      if (graphReduce) console.log(`      ${faint('saved per query:         ')} ${highlight(graphReduce)}  ${ok(graphPct + '%')} fewer tokens`);
+    const byType = {};
+    for (const e of allEntries) { byType[e.type] = (byType[e.type] || 0) + 1; }
+    for (const [type, count] of Object.entries(byType).sort((a, b) => b[1] - a[1])) {
+      const bar = color(C.dblue, '█'.repeat(Math.min(count, 20))) + color(C.darkgray, '░'.repeat(Math.max(0, 20 - count)));
+      console.log(`    ${type.padEnd(14)} ${bar}  ${muted(count)}`);
     }
   }
 
-  // ── Combined ──────────────────────────────────────────────────────────────────
-  // Without: read all files (no graph) + load all entries full (no memory system)
-  // With:    compact resume (memory) + one graph query (codegraph)
-  if (graphs.length) {
-    const resumeCount   = Math.min(RESUME_LIMIT, totalEntries);
-    const withMemTok    = resumeCount * avgCompactTok;
-    const withMcp       = withMemTok + avgQueryTok;
-    const withoutMemTok = totalEntries * avgFullTok;
-    const withoutMcp    = withoutMemTok + (corpusToks || graphs[0].nodes * 80);
-    const totalRed      = withoutMcp > 0 ? (withoutMcp / withMcp).toFixed(0) : '—';
-    const totalPct      = withoutMcp > 0 ? ((1 - withMcp / withoutMcp) * 100).toFixed(2) : '—';
-
-    console.log(`\n  ${bold(lblue('Combined'))}  ${faint('per conversation')}`);
-    console.log(`    ${faint('without context-mcp:  ')} ${warn('~' + withoutMcp.toLocaleString('en-US'))} tokens  ${faint('(all entries full + all files read directly)')}`);
-    console.log(`    ${faint('with context-mcp:     ')} ${ok('~' + withMcp.toLocaleString('en-US'))} tokens  ${faint('(compact resume + 1 graph query)')}`);
-    console.log(`    ${faint('total reduction:      ')} ${highlight(totalRed + '×')}  ${ok(totalPct + '%')} fewer tokens`);
-  }
-
+  // ── Storage summary ───────────────────────────────────────────────────────────
+  const compactions = allEntries.filter(e => e.type === 'compaction').length;
+  const avgSize = allEntries.length
+    ? Math.round(allEntries.reduce((s, e) => s + (e.content || '').length, 0) / allEntries.length)
+    : 0;
+
+  console.log(`\n  ${bold(lblue('Storage'))}`);
+  console.log(`    ${faint('total entries:  ')} ${muted(allEntries.length)}`);
+  console.log(`    ${faint('compactions:    ')} ${muted(compactions)}`);
+  console.log(`    ${faint('avg entry size: ')} ${muted(avgSize + ' chars')}`);
+  console.log(`    ${faint('graphs built:   ')} ${muted(graphs.length)}`);
   console.log('');
-  console.log(line());
-  console.log(faint('  token estimate: chars ÷ 4  ·  corpus = all source/config/doc files (excl. lock files, .venv, node_modules)'));
 }
 
 
@@ -796,6 +691,15 @@ async function cmdInstall(args) {
         console.log(`  ${ok('✓')} Python environment ready — codegraph enabled`);
       }
     }
+    // Bootstrap store structure — creates ~/.context-mcp/, projects/, contextconfig.json
+    console.log(`  ${bold(lblue('Store'))}`);
+    try {
+      getConfig(); // triggers DATA_DIR creation + contextconfig.json generation
+      console.log(`  ${ok('✓')} store ready          ${faint(getStorePath())}`);
+      console.log(`  ${ok('✓')} config ready         ${faint(getConfigPath())}`);
+    } catch (e) {
+      console.log(`  ${bad('✗')} store init failed: ${faint(e.message)}`);
+    }
     console.log('');
     return;
   }
@@ -871,27 +775,6 @@ async function cmdInstall(args) {
   // ── Global gitignore — add context-mcp runtime files if global gitignore exists ──
   _updateGlobalGitignore();
   console.log('');
-
-  // ── Python / uv setup (codegraph) ─────────────────────────────────────────
-  console.log(`  ${bold(lblue('Python Codegraph'))}`);
-  const uvCheck = spawnSync('uv', ['--version'], { encoding: 'utf8' });
-  if (uvCheck.error || uvCheck.status !== 0) {
-    console.log(`  ${bad('✗')} uv not found — install it from ${accent('https://docs.astral.sh/uv/')} to enable codegraph`);
-    console.log('');
-    return;
-  }
-  console.log(`  ${ok('✓')} uv found: ${faint(uvCheck.stdout.trim())}`);
-
-  // Package root is one level up from src/
-  const __dirname_cli = dirname(fileURLToPath(import.meta.url));
-  const pkgRoot = join(__dirname_cli, '..');
-  const sync = spawnSync('uv', ['--directory', pkgRoot, 'sync', '--no-dev'], { encoding: 'utf8' });
-  if (sync.status !== 0) {
-    console.log(`  ${bad('✗')} uv sync failed:\n${faint((sync.stderr || sync.stdout || '').trim())}`);
-  } else {
-    console.log(`  ${ok('✓')} Python environment ready — codegraph enabled`);
-  }
-  console.log('');
 }
 
 // ── Online ────────────────────────────────────────────────────────────────────
@@ -1077,7 +960,7 @@ async function cmdAdd(existingRl) {
   const content = await ask('Content:');
   const project = await ask('Project (blank = global):');
   const tagsRaw = await ask('Tags (comma-separated):');
-  const type    = await ask('Type (note/decision/code/bug/architecture/config/error):');
+  const type    = await ask('Type (note/compaction):');
 
   if (!existingRl) rl.close();
   if (!content.trim()) { console.log(`  ${bad('✗')} content required`); return; }
@@ -1094,6 +977,30 @@ async function cmdAdd(existingRl) {
   console.log(`  ${ok('✓')} ${bold(entry.title || '(no title)')}  ${faint('id:' + entry.id.slice(0, 8))}`);
 }
 
+// ── Save (non-interactive, flag-based — used by hooks and scripts) ───────────
+
+function cmdSave(args) {
+  // Usage: ctx save --title "..." --content "..." --project <p> --type <t> --tags <t1,t2>
+  const flags = {};
+  for (let i = 0; i < args.length; i++) {
+    if (args[i].startsWith('--')) {
+      flags[args[i].slice(2)] = args[i + 1] || '';
+      i++;
+    }
+  }
+  const content = flags.content || flags.c;
+  if (!content) { console.log(`  ${bad('✗')} --content required`); process.exit(1); }
+  const entry = saveContext({
+    title:   (flags.title || flags.t || '').trim(),
+    content: content.trim(),
+    project: (flags.project || flags.p || '').trim() || 'global',
+    tags:    (flags.tags || '').split(',').map(s => s.trim()).filter(Boolean),
+    type:    (flags.type || 'note').trim(),
+    source:  'cli',
+  });
+  console.log(`  ${ok('✓')} saved "${entry.title || entry.id.slice(0, 8)}" → ${entry.project}`);
+}
+
 // ── Delete ────────────────────────────────────────────────────────────────────
 
 function cmdDelete(args) {
@@ -1193,8 +1100,8 @@ async function interactive() {
           clearScreen(); printCompactHeader('discussions'); cmdDiscussions(rest); break;
         case 'summary':
           clearScreen(); printCompactHeader('summary'); cmdSummary(rest); break;
-        case 'benchmark': case 'bench':
-          clearScreen(); printCompactHeader('benchmark'); cmdBenchmark(); break;
+        case 'stats':
+          clearScreen(); printCompactHeader('stats'); cmdStats(); break;
         case 'install':
           clearScreen(); printCompactHeader('install'); await cmdInstall(rest); break;
         case 'online':
@@ -1203,6 +1110,8 @@ async function interactive() {
           clearScreen(); printCompactHeader('settings'); await cmdSettings(rl); break;
         case 'add':
           clearScreen(); printCompactHeader('add'); await cmdAdd(rl); break;
+        case 'save':
+          cmdSave(rest); break;
         case 'delete': case 'del': case 'rm':
           clearScreen(); printCompactHeader('delete'); cmdDelete(rest); break;
         case 'help': case '?':
@@ -1257,8 +1166,8 @@ async function checkForUpdate() {
       cmdDiscussions(rest); break;
     case 'summary':
       cmdSummary(rest); break;
-    case 'benchmark': case 'bench':
-      cmdBenchmark(); break;
+    case 'stats':
+      cmdStats(); break;
     case 'install':
       await cmdInstall(rest);
       process.exit(0);
@@ -1284,6 +1193,8 @@ async function checkForUpdate() {
       await cmdSettings(); break;
     case 'add':
       await cmdAdd(); break;
+    case 'save':
+      cmdSave(rest); break;
     case 'delete': case 'del': case 'rm':
       cmdDelete(rest); break;
     case 'help': case '--help': case '-h':