context-mcp-server 1.0.7 → 1.1.0

package/src/templates/GEMINI.md

@@ -1,87 +1,90 @@
 # Context-MCP — Gemini 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 (auto-linked if exactly one active)
-- `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` then `discussion.update`.
-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`** — 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 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/commands/context-resume.md

@@ -4,7 +4,7 @@ Both `project` and `rootPath` are required: `project` names the memory bucket, `
 
 This loads:
 - Recent decisions, bugs, and notes from past sessions
-- Active discussions
+- Active plans
 - 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/save-context.md

@@ -2,8 +2,11 @@ Call the `context` MCP tool with `action: "save"` to store a note for the curren
 
 Parse `$ARGUMENTS` to determine:
 - `project`: infer from current working directory name if not specified
-- `title`: first sentence or phrase from the argument
+- `title`: first sentence or phrase (up to 120 chars — be specific)
+- `why`: reason it mattered — what problem it solved or constraint it revealed
+- `outcome`: result — what changed, what was verified, what shipped, which files were affected
+- `files`: list of files changed (required for task/bug types)
 - `content`: full argument text
-- `type`: auto-detect — if mentions a bug/fix → `"bug"`, decision/chose/decided → `"decision"`, structure/architecture → `"architecture"`, otherwise `"note"`
+- `type`: auto-detect — bug/fix/error → `"bug"`, task/done/complete/shipped/implemented → `"task"`, decision/chose/decided/approach → `"decision"`, config/env/secret/deploy → `"config"`, otherwise `"note"`
 
-Confirm to the user what was saved (title, type, project).
+Confirm to the user: title, type, why, outcome, project.

package/src/templates/cursor-rules.mdc

@@ -13,7 +13,7 @@ Every conversation starts with `context.resume`. Every structural question uses
 
 Call `context` tool, `action: "resume"`, `project: "<project-name>"` before anything else.
 
-Returns: `recentEntries`, `activeDiscussions`, `codegraph { built, nodes, edges }`.
+Returns: `recentEntries`, `activePlans`, `codegraph { built, nodes, edges }`.
 
 - `codegraph.built: true` → use `codegraph_query` before reading files
 - `codegraph.built: false` → run `codegraph_build(path)` first
@@ -24,8 +24,8 @@ Returns: `recentEntries`, `activeDiscussions`, `codegraph { built, nodes, edges
 |-----------|--------|
 | Decision made | `context.save` type: `"decision"` |
 | Bug found/fixed | `context.save` type: `"bug"` |
-| Architecture understood | `context.save` type: `"architecture"` |
-| Multi-session feature | `discussion.create` |
+| Discovery / structure understood | `context.save` type: `"note"` |
+| Making any plan | `plan.save` + `planDir` |
 
 ## 3. CodeGraph
 

package/src/templates/skills/SKILL.md

@@ -12,7 +12,17 @@ description: >
 # 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.
+`context.resume` starts every session. `codegraph_arch` shows module structure. `codegraph_query` finds specific symbols. Files only for bugs/logic.
+
+---
+
+## Subcommands
+
+When invoked with an argument, act immediately:
+
+**`/context-mcp resume`** — call `context` tool with `action:"resume"`, infer `project` from cwd, pass `rootPath`. Report what was returned.
+
+**`/context-mcp save`** — call `context` tool with `action:"save"` to save the most recent thing worth keeping from this conversation. Use `type:"note"`, fill in `title`, `why`, `outcome`, `files` from context. Confirm what was saved.
 
 ---
 
@@ -23,92 +33,109 @@ Call `context` tool **before any tool or response** with:
 - `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)
+- `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, communities }`
+- `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
 
 ---
 
-## When to Auto-Save Context
+## When to Save Context (MANDATORY TRIGGERS)
 
-### Always save — no user prompt needed
+Call `context.save` with `type: "note"` after finishing anything worth keeping:
 
-**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>"
+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", ...]
 ```
 
-**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.
+**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.
 
 ---
 
-## ContextGraph Pipeline
+## Plans (MANDATORY for multi-file work)
 
-> Also called **CodeGraph**. MCP tools use the `codegraph_*` prefix — both names mean the same thing.
+**Create a plan when:** editing 2+ files, multi-step implementation, refactor, multi-file bug fix.
 
-### 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`.
+**Skip plan for:** single-file edits, questions, simple config tweaks.
+
+1. `plan.save` with name, content, project, planDir — before starting work
+2. Work through plan
+3. `plan.update status:"done"` when complete — deletes the plan
+
+On `resume`, check `activePlans` — do not duplicate in-progress work.
+
+---
+
+## Auto-Summary Rule (MANDATORY)
+
+When `resume` returns `stats.totalEntries ≥ 20`, call `context.save` **before the user's task**:
 
-### Query (free, instant, forever)
 ```
-codegraph_query(path, question?, node?)  → structural question OR single-node lookup (or both in one call)
-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
+type: "compaction"  title: "Session summary — <date>"
+content: "<what was built, decided, broke, current state>"
+project: "<project>"
 ```
 
 ---
 
-## Graph vs File
+## Search Before Asking
+
+If user references past work → `search` first. Never ask user to re-explain saved information.
+
+---
+
+## ContextGraph Pipeline
 
-**Graph** — what exists: finding functions, classes, files, dependencies, callers, imports, paths between concepts.
+### Build (once per project)
+```
+codegraph_build(path)  →  AST graph: functions, classes, imports, edges
+```
+
+### Query tools
+```
+codegraph_arch(path)                     → module map: every file, 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)                   → god nodes, clusters, structural analysis
+```
 
-**File** — bugs, logic inside a specific function, tracing unexpected behavior.
+| Question | Tool |
+|---|---|
+| Architecture overview / what files exist | `codegraph_arch` |
+| Where is function/class X defined? | `codegraph_query node:"X"` |
+| What does module Y import? | `codegraph_query question:"..."` |
+| List all classes/functions | `codegraph_nodes type:"class"` |
+| Most connected / central files | `codegraph_report` |
 
 ---
 
 ## 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
+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 for multi-file work — `status:"done"` deletes it
+6. Search before asking about past work
+7. Graph tools before files

package/src/templates/windsurf-rules.md

@@ -1,35 +1,84 @@
 # Context-MCP — Windsurf Usage Guide
 
-Persistent memory + codebase knowledge graph for Windsurf.
-Every conversation starts with `context.resume`. Every structural question uses `codegraph_query`. Files only read for bugs/logic.
+Persistent memory + codebase knowledge graph.
+`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, `action: "resume"`, `project: "<project-name>"` before anything else.
+Call `context` tool: `action:"resume"`, `project:"<name>"` before anything else.
 
-Returns: `recentEntries`, `activeDiscussions`, `codegraph { built, nodes, edges }`.
+Returns: `recentEntries`, `activePlans`, `codegraph`, `stats.totalEntries`.
 
-- `codegraph.built: true` → use `codegraph_query` before reading files
 - `codegraph.built: false` → run `codegraph_build(path)` first
+- `stats.totalEntries ≥ 20` → write compaction summary first (see Rule 4)
+- `activePlans` non-empty → read before starting new work
+
+---
+
+## 2. Save Triggers (MANDATORY)
+
+Call `context.save` with `type: "note"` after finishing anything worth keeping:
+
+| 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 |
+
+**Do NOT save:** routine reads, search results, explanations of existing code.
+
+---
+
+## 3. Plans
+
+Call `plan.save` before any work touching 2+ files or multiple steps.
+Call `plan.update status:"done"` when complete — deletes the plan.
+Check `activePlans` on resume — don't duplicate.
+
+---
+
+## 4. Auto-Summary at ≥ 20 Entries (MANDATORY)
+
+When `totalEntries ≥ 20`, call `context.save` BEFORE the user's task:
+
+```
+type: "compaction"  title: "Session summary — <date>"
+content: "<what was built, decided, broke, current state>"
+project: "<project>"
+```
+
+---
+
+## 5. Search Before Asking
+
+Call `search` before asking user to re-explain past work.
+
+---
 
-## 2. Save Context
+## 6. ContextGraph Tools
 
-| Situation | Action |
-|-----------|--------|
-| Decision made | `context.save` type: `"decision"` |
-| Bug found/fixed | `context.save` type: `"bug"` |
-| Architecture understood | `context.save` type: `"architecture"` |
-| Multi-session feature | `discussion.create` |
+```
+codegraph_arch(path)          → module map (files, exports, imports)
+codegraph_query(path, ...)    → find specific function/class/file
+codegraph_nodes(path, type)   → list all nodes of a type
+codegraph_report(path)        → structural analysis
+```
 
-## 3. CodeGraph
+Use `codegraph_arch` first. Never read files for structure questions.
 
-Build once: `codegraph_build(path)` — then query forever.
-Use `codegraph_query` for structural questions. Read files for bugs/logic.
+---
 
-## Rules
+## 7. Rules
 
 1. `context.resume` first — every conversation
-2. Always pass `project`
-3. `search` before asking the user about past work
-4. `codegraph_query` before reading files
-5. Files only for bugs and logic
+2. Save on task complete — `why` + `outcome` + `files`
+3. Compaction at ≥ 20 entries — before starting task
+4. Plan for 2+ file changes — `status:"done"` deletes it
+5. Search before asking about past work
+6. Graph tools before files

package/src/tools/codegraph.js

@@ -6,6 +6,7 @@
 import { spawnSync } from 'node:child_process';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { saveGraph, saveContext, updateContext, getContext, flushToDisk } from '../db.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const REPO_ROOT  = join(__dirname, '..', '..');
@@ -82,16 +83,18 @@ export const definitions = [
     },
   },
   {
-    name: 'codegraph_path',
-    description: 'Find the shortest relationship path between two concepts in the graph.',
+    name: 'codegraph_arch',
+    description:
+      'Return a module map of the project — every file with its exported functions/classes and its imports. ' +
+      'Use this to understand project structure without reading any files. ' +
+      'Call after codegraph_build. Much faster than reading each file individually.',
     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'],
     },
   },
 ];
@@ -103,46 +106,46 @@ export function handle(name, args, state) {
 
   // Persist graph metadata + save/update a context entry as a visible build record
   if (name === 'codegraph_build' && result.success) {
-    import('../db.js').then(({ saveGraph, saveContext, updateContext, getContext }) => {
-      saveGraph({
-        path:        args.path,
-        nodes:       result.nodes,
-        edges:       result.edges,
-        communities: result.communities,
-        cached:      result.cached,
-        changed:     result.changed,
-        time_ms:     result.time_ms,
-        summary:     result.summary || '',
-      });
+    saveGraph({
+      path:        args.path,
+      nodes:       result.nodes,
+      edges:       result.edges,
+      communities: result.communities,
+      cached:      result.cached,
+      changed:     result.changed,
+      time_ms:     result.time_ms,
+      summary:     result.summary || '',
+    });
+    flushToDisk(); // write graph.json to disk immediately so ctx list sees it
 
-      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}`,
-        `cached: ${result.cached} | changed: ${result.changed} | time: ${result.time_ms}ms`,
-        result.summary || '',
-      ].filter(Boolean).join('\n');
+    const inferredProject = args.path
+      ? args.path.replace(/\\/g, '/').replace(/\/$/, '').split('/').pop()
+      : null;
+    const project = state?.sessionProject || inferredProject || null;
+    const title   = `ContextGraph built — ${args.path}`;
+    const content = [
+      `nodes: ${result.nodes} | edges: ${result.edges} | communities: ${result.communities}`,
+      `cached: ${result.cached} | changed: ${result.changed} | time: ${result.time_ms}ms`,
+      result.summary || '',
+    ].filter(Boolean).join('\n');
 
-      const existing = getContext({ project, tags: ['codegraph'], limit: 100 })
-        .find(e => e.title === title);
+    // Search all projects — same path always produces same title regardless of session
+    const existing = getContext({ tags: ['codegraph'], limit: 100 })
+      .find(e => e.title === title);
 
-      if (existing) {
-        updateContext({ id: existing.id, content, status: 'active' });
-      } else {
-        saveContext({
-          project,
-          sessionId: state?.sessionId || null,
-          title,
-          content,
-          type:   'architecture',
-          source: 'auto',
-          tags:   ['codegraph', 'graph-build'],
-        });
-      }
-    }).catch(() => {});
+    if (existing) {
+      updateContext({ id: existing.id, content, status: 'active' });
+    } else {
+      saveContext({
+        project,
+        sessionId: state?.sessionId || null,
+        title,
+        content,
+        type:   'note',
+        source: 'auto',
+        tags:   ['codegraph', 'graph-build'],
+      });
+    }
   }
 
   return result;