context-mcp-server 1.0.7 → 1.1.0

package/src/guard.js

@@ -1,7 +1,13 @@
 import { resolve, sep } from 'node:path';
+import { realpathSync } from 'node:fs';
+
+// Follow symlinks to get the true path; fall back to resolve() if path doesn't exist yet.
+function safeStat(p) {
+  try { return realpathSync(p); } catch { return resolve(p); }
+}
 
 /**
- * Resolves `inputPath` and asserts it falls within `allowedRoot`.
+ * Resolves `inputPath` (following symlinks) and asserts it falls within `allowedRoot`.
  * Throws if no root is configured or if the path escapes the root.
  * Returns the resolved absolute path on success.
  */
@@ -11,8 +17,8 @@ export function guardPath(inputPath, allowedRoot) {
       'Project root not configured. Call context with action:"resume" and include rootPath to enable file/git access.'
     );
   }
-  const resolved = resolve(inputPath);
-  const root = resolve(allowedRoot);
+  const resolved = safeStat(inputPath);
+  const root = safeStat(allowedRoot);
   if (resolved !== root && !resolved.startsWith(root + sep)) {
     throw new Error(`Access denied: "${resolved}" is outside the project root "${root}"`);
   }

package/src/search.js

@@ -1,13 +1,71 @@
-/**
- * search.js — unified search entry point
- *
- * Single function replaces direct calls to searchContext / vectorSearch / findRelated
- * across index.js, cli.js, and error_check. db.js + vector.js stay as low-level impls.
- */
-
 import { getContext, searchContext } from './db.js';
 import { vectorSearch, findRelated } from './vector.js';
 
+// ── Vocabulary cache (lazy singleton per process) ─────────────────────────────
+
+let _vocabCache = null;
+
+function buildVocab(entries) {
+  const vocab = new Set();
+  for (const e of entries) {
+    const text = `${e.title || ''} ${e.content || ''}`.toLowerCase();
+    for (const w of text.split(/\W+/)) {
+      if (w.length > 2) vocab.add(w);
+    }
+  }
+  return vocab;
+}
+
+// ── Levenshtein fuzzy correction ──────────────────────────────────────────────
+
+function levenshtein(a, b) {
+  const prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 0; i < a.length; i++) {
+    const curr = [i + 1];
+    for (let j = 0; j < b.length; j++) {
+      curr.push(Math.min(prev[j + 1] + 1, curr[j] + 1, prev[j] + (a[i] === b[j] ? 0 : 1)));
+    }
+    prev.splice(0, prev.length, ...curr);
+  }
+  return prev[b.length];
+}
+
+function maxEditDist(len) {
+  if (len <= 4) return 1;
+  if (len <= 12) return 2;
+  return 3;
+}
+
+function fuzzyCorrect(word, vocab) {
+  const max = maxEditDist(word.length);
+  let bestWord = word;
+  let bestDist = max + 1;
+  for (const candidate of vocab) {
+    if (Math.abs(candidate.length - word.length) > max) continue;
+    const dist = levenshtein(word, candidate);
+    if (dist < bestDist) { bestDist = dist; bestWord = candidate; }
+  }
+  return bestDist <= max ? bestWord : word;
+}
+
+// ── Smart snippet (window centered on first match position) ───────────────────
+
+function snippet(text, terms, windowSize = 200) {
+  if (!text) return text;
+  const lower = text.toLowerCase();
+  let bestPos = -1;
+  for (const term of terms) {
+    const idx = lower.indexOf(term.toLowerCase());
+    if (idx !== -1 && (bestPos === -1 || idx < bestPos)) bestPos = idx;
+  }
+  if (bestPos === -1) return text.slice(0, windowSize);
+  const start = Math.max(0, bestPos - Math.floor(windowSize / 3));
+  const end = Math.min(text.length, start + windowSize);
+  return (start > 0 ? '…' : '') + text.slice(start, end) + (end < text.length ? '…' : '');
+}
+
+// ── Unified search ────────────────────────────────────────────────────────────
+
 /**
  * @param {Object} opts
  * @param {string} opts.query      - search query (keyword/semantic)
@@ -21,7 +79,14 @@ export function search({ query, mode = 'semantic', project, limit = 10, id, comp
   switch (mode) {
     case 'keyword': {
       if (!query) throw new Error('query required for keyword search');
-      return searchContext({ query, project, limit, compact });
+      if (!_vocabCache) {
+        _vocabCache = buildVocab(getContext({ project, limit: 500 }));
+      }
+      const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+      const corrected = terms.map(t => fuzzyCorrect(t, _vocabCache));
+      const correctedQuery = corrected.join(' ');
+      const results = searchContext({ query: correctedQuery, project, limit, compact: false });
+      return results.map(e => ({ ...e, content: snippet(e.content, corrected) }));
     }
     case 'semantic': {
       if (!query) throw new Error('query required for semantic search');
@@ -33,7 +98,6 @@ export function search({ query, mode = 'semantic', project, limit = 10, id, comp
       const all = getContext({ limit: 1000 });
       const target = all.find(e => e.id === id || e.id.startsWith(id));
       if (!target) throw new Error(`No entry found with id starting "${id}"`);
-      // explicit relations first, semantic enrichment for remainder
       const explicitIds = new Set([
         ...(target.relations  || []).map(r => r.id),
         ...(target.relatedBy  || []).map(r => r.id),

package/src/server.js

@@ -5,7 +5,7 @@ import { getConfig } from './config.js';
 
 import * as contextTool    from './tools/context.js';
 import * as searchTool     from './tools/search.js';
-import * as discussionTool from './tools/discussion.js';
+import * as planTool        from './tools/plan.js';
 import * as errorCheckTool from './tools/errorCheck.js';
 import * as fileTool       from './tools/fileTools.js';
 import * as gitTool        from './tools/gitTools.js';
@@ -17,8 +17,9 @@ const CODEGRAPH_TOOL_NAMES = codegraphTool.TOOL_NAMES;
 
 export function createServer({ enableFileTools = false, enableGitTools = getConfig().access_git === true } = {}) {
   const state = {
-    sessionProject: null,
-    discussionId:   null,
+    sessionProject:  null,
+    discussionId:    null,
+    projectRootPath: null,
   };
 
   const server = new Server(
@@ -30,7 +31,7 @@ export function createServer({ enableFileTools = false, enableGitTools = getConf
     const tools = [
       contextTool.definition,
       searchTool.definition,
-      discussionTool.definition,
+      planTool.definition,
       errorCheckTool.definition,
     ];
     if (enableFileTools) tools.push(...fileTool.definitions);
@@ -56,8 +57,8 @@ export function createServer({ enableFileTools = false, enableGitTools = getConf
         result = await contextTool.handle(args, state);
       } else if (name === searchTool.definition.name) {
         result = await searchTool.handle(args, state);
-      } else if (name === discussionTool.definition.name) {
-        result = await discussionTool.handle(args, state);
+      } else if (name === planTool.definition.name) {
+        result = await planTool.handle(args, state);
       } else if (name === errorCheckTool.definition.name) {
         result = await errorCheckTool.handle(args, state);
       } else if (FILE_TOOL_NAMES.has(name)) {

package/src/templates/AGENTS.md

@@ -1,87 +1,90 @@
 # Context-MCP — Codex CLI Usage Guide
 
 Persistent memory + codebase knowledge graph.
-Every conversation starts with `context.resume`. Every codebase question uses `codegraph_query`. Files only read for bugs/logic.
+`context.resume` starts every session. `codegraph_arch` shows module structure. `codegraph_query` finds specific symbols. Files only for bugs/logic.
 
 ---
 
 ## 1. Start of Every Conversation (MANDATORY)
 
-Call the `context` MCP tool with `action: "resume"`, `project: "<project-name>"` **before anything else**.
+Call `context` MCP tool: `action:"resume"`, `project:"<project>"` before anything else.
 
-Returns:
-- `recentEntries` — decisions, bugs, notes from previous conversations
-- `activeDiscussions` — ongoing topics
-- `codegraph` — `{ built: true/false, nodes, edges, communities }`
+Returns: `recentEntries`, `activePlans`, `codegraph`, `stats.totalEntries`.
 
-Then:
-- `codegraph.built: true` → use `codegraph_query` before reading any files
-- `codegraph.built: false` → call `codegraph_build(path)` first, then proceed
+- `codegraph.built: true` → use graph tools before reading files
+- `codegraph.built: false` → call `codegraph_build(path)` first
+- `stats.totalEntries ≥ 20` → write compaction summary FIRST (see Rule 4)
+- `activePlans` non-empty → read them before starting new work
 
 ---
 
-## 2. When to Auto-Save Context
+## 2. Save Triggers (MANDATORY)
 
-**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"
-```
+Call `context.save` with `type: "note"` after finishing anything worth keeping:
 
-**User explicitly asks** — "save this", "remember this", "note that" → save immediately.
+| Trigger | Required fields |
+|---|---|
+| Task / fix / feature complete | title, why, outcome, files[] |
+| Decision made | title, why, outcome |
+| Discovery / constraint / gotcha | title, content |
+| Config / env / deploy info | title, content |
+| Graph build complete | title, content (nodes/edges count) |
+| User says "save this" | title, content |
+| "compact now" / "compress memory" | `type:"compaction"`, full session summary |
 
-**During plan / implementation / discussion / research** — save only when genuinely valuable:
+**Do NOT save:** routine reads, search results, explanations of existing code.
+
+---
 
-| 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` |
+## 3. Plans (MANDATORY for multi-file work)
 
-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`.
+**Create a plan when:** editing 2+ files, multi-step implementation, refactor, multi-file bug fix.
+
+1. Call `plan.save` with name, content, project before starting
+2. Call `plan.update status:"done"` when complete — deletes the plan
+
+Check `activePlans` on resume — don't create duplicates.
 
 ---
 
-## 3. ContextGraph Pipeline
+## 4. Auto-Summary at ≥ 20 Entries (MANDATORY)
 
-> The knowledge graph is also called **ContextGraph**. The MCP tools use the `codegraph_*` prefix — both names refer to the same thing.
+When `totalEntries ≥ 20`, call `context.save` BEFORE the user's task:
 
-### Step 1 — Build (once, fast, local)
 ```
-codegraph_build(path)  →  AST graph: functions, classes, imports, edges
+type: "compaction"  title: "Session summary — <YYYY-MM-DD>"
+content: "<what was built, decided, broke, current state>"
+project: "<project>"
 ```
 
-### Step 2 — Query (free, instant)
-```
-codegraph_query(path, question)   →  fetch any details about the codebase
-codegraph_explain(path, node)     →  single node: type, file, connections
-codegraph_path(path, from, to)    →  shortest path
-codegraph_nodes(path, type)       →  list nodes by type
-codegraph_report(path)            →  full graph analysis
-```
+---
+
+## 5. Search Before Asking
+
+Call `search` before asking user to re-explain past work.
 
 ---
 
-## 4. Graph vs File
+## 6. ContextGraph Tools
+
+```
+codegraph_build(path)                    → build AST graph (run once)
+codegraph_arch(path, limit?)             → module map: files, exports, imports
+codegraph_query(path, question?, node?)  → find symbol or answer structural question
+codegraph_nodes(path, type)              → list all nodes of a type
+codegraph_report(path)                   → structural analysis
+```
 
-**Graph** — use for any question about what exists: finding functions, classes, files, dependencies, callers, imports, paths between concepts.
-**File** — bugs, logic, tracing unexpected behavior.
+Use `codegraph_arch` first. Never read files for structure questions.
 
 ---
 
-## 5. Rules
+## 7. Rules
 
-1. **`context.resume` first** — before any tool or response
-2. **Always pass `project`**
-3. **`search` before asking** — if user references past work
-4. **`codegraph_query` before reading files** — graph is faster and cheaper
-5. **Read files for bugs/logic only**
+1. `context.resume` first — before any tool or response
+2. Always pass `project`
+3. Save on task complete — `why` + `outcome` + `files`
+4. Compaction at ≥ 20 entries — before starting task
+5. Plan before multi-file work — `status:"done"` deletes it
+6. Search before asking about past work
+7. Graph tools before files

package/src/templates/CLAUDE.md

@@ -1,109 +1,137 @@
 ---
 name: context-mcp
 description: >
-  Guides Claude on using the context-mcp memory + knowledge graph system.
-  Trigger at the start of every conversation, when the user mentions a project,
-  asks to remember/save something, or says "pick up where we left off".
+  Persistent memory + ContextGraph 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 — query ContextGraph before reading any files.
 ---
 
 # Context-MCP — Claude Usage Guide
 
-Persistent memory + codebase knowledge graph for Claude.
-Every conversation starts with `context.resume`. Every codebase question uses `codegraph_query`. Files only read for bugs/logic.
+Persistent memory + codebase knowledge graph across every conversation.
+`context.resume` starts every session. `codegraph_arch` shows module structure. `codegraph_query` finds specific symbols. Files only for bugs/logic.
 
 ---
 
 ## 1. Start of Every Conversation (MANDATORY)
 
-Call `context` tool **before anything else** with:
+Call `context` tool **before any tool or response**:
 - `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.
+- `project: "<basename of git repo root>"` — infer from cwd
+- `rootPath: "<absolute path to git repo root>"` — required
 
 Returns:
-- `recentEntries` — decisions, bugs, notes from previous conversations
-- `activeDiscussions` — ongoing topics (auto-linked if exactly one active)
-- `codegraph` — `{ built: true/false, nodes, edges, communities }`
+- `recentEntries` — last 15 entries; newest 5 have full content, rest have 200-char preview
+- `activePlans` — in-progress plans; read them before starting any new work
+- `codegraph` — `{ built: true/false, nodes, edges }`
+- `stats.totalEntries` — if ≥ 20, write a compaction summary before proceeding (see Rule 4)
 
 Then:
-- `codegraph.built: true` → use `codegraph_query` before reading any files
-- `codegraph.built: false` → call `codegraph_build(path)` first, then proceed
+- `codegraph.built: true` → use `codegraph_arch` for structure overview, `codegraph_query` for specific lookups
+- `codegraph.built: false` → call `codegraph_build(path)` first
 
 ---
 
-## 2. When to Auto-Save Context
+## 2. When to Save Context (MANDATORY TRIGGERS)
 
-### Always save — no user prompt needed
+Call `context.save` with `type: "note"` whenever you finish something or discover something worth keeping:
 
-**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"
+context.save
+  project: "<project>"
+  title:   "<what was done — up to 120 chars>"
+  why:     "<why it mattered>"
+  outcome: "<what the result was>"
+  files:   ["src/file.js", ...]
 ```
 
-**User explicitly asks** — any phrase like "save this", "remember this", "note that" → save immediately.
+**Save immediately after:**
+- Task / fix / feature complete
+- Decision made (architecture, library, approach)
+- Discovery — non-obvious behavior, constraint, gotcha
+- Config / env / deploy info
+- Graph build complete — include nodes/edges count in content
+- User says "save this" / "remember this"
+
+**Manual compaction** — "compact now", "compress memory", "clean up context":
+Save a full session summary as `type: "compaction"`. Server removes old entries using it.
+
+**Do NOT save:** routine reads, search results, explanations of existing code, dead-end debugging.
+
+---
 
-**During plan / implementation / discussion / research** — save only when genuinely valuable:
+## 3. Plans (MANDATORY for multi-file work)
 
-| 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` |
+**Create a plan when:** editing 2+ files, multi-step implementation, refactor, multi-file bug fix.
 
-Do NOT save: routine reads, search results, temporary debugging dead-ends.
+**Skip plan for:** single-file edits, questions, simple config tweaks.
 
-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.
+1. Call `plan.save` with `name`, `content` (full plan in markdown), `project`, `planDir` before starting
+2. Work through the plan
+3. Call `plan.update status:"done"` when complete — this deletes the plan
+
+On `resume`, if `activePlans` is non-empty — read them before starting new work. Do not create a duplicate.
 
 ---
 
-## 3. ContextGraph Pipeline
+## 4. Auto-Summary Rule (MANDATORY)
 
-> The knowledge graph is also called **ContextGraph**. The MCP tools use the `codegraph_*` prefix — both names refer to the same thing.
+When `resume` returns `stats.totalEntries ≥ 20`, call `context.save` **before doing anything else**:
 
-### Step 1 — Build (once per project, fast, local)
 ```
-codegraph_build(path)
+context.save
+  type:    "compaction"
+  title:   "Session summary — <YYYY-MM-DD>"
+  content: "<what was built, decided, broke, current state>"
+  project: "<project>"
 ```
-- Parses codebase into AST graph using tree-sitter (regex fallback for unsupported languages)
-- Extracts functions, classes, imports, call edges for all code files
-- Build files (package.json, pyproject.toml, go.mod, Dockerfile, etc.) get a single metadata node
-- Saves graph to `~/.context-mcp/graphs.json`. Visible on `context.resume`.
 
-### Step 2 — Query (free, instant, forever)
+---
+
+## 5. Search Before Asking
+
+If the user references past work → call `search` first:
 ```
-codegraph_query(path, question)     → fetch any details about the codebase
-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
+search  query: "<what they're referencing>"  project: "<project>"
 ```
 
 ---
 
-## 4. Graph vs File
+## 6. ContextGraph Pipeline
+
+### Build (once per project)
+```
+codegraph_build(path)
+```
+
+### Query tools
+```
+codegraph_arch(path, limit?)             → module map: every file, its exports, its imports
+codegraph_query(path, question?, node?)  → find function/class/file or answer structural question
+codegraph_nodes(path, type)              → list all nodes of a type
+codegraph_report(path)                   → god nodes, clusters, structural analysis
+```
 
-**Graph** — use for any question about what exists in the codebase: finding functions, classes, files, understanding what a module contains, dependencies, callers, imports, paths between concepts.
+| Question | Tool |
+|---|---|
+| What files exist and what do they export? | `codegraph_arch` |
+| Where is function X defined? | `codegraph_query node:"X"` |
+| What does module Y depend on? | `codegraph_query question:"what does Y import?"` |
+| What are all the classes? | `codegraph_nodes type:"class"` |
+| Most connected files? | `codegraph_report` |
 
-**File** — use for bugs, logic inside a specific function, tracing unexpected behavior.
+**Never read files for structure questions — use graph tools first.**
 
 ---
 
-## 5. Rules
+## 7. 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** — graph is structure only, not behavior
+1. `context.resume` first — before any tool or response
+2. Always pass `project`
+3. Save on task complete — `why` + `outcome` + `files`
+4. Compaction at ≥ 20 entries — before starting the task
+5. Plan for multi-file work — save before starting, `status:"done"` deletes it
+6. Search before asking about past work
+7. Graph tools before files