context-mcp-server 1.0.3 → 1.0.5

package/src/templates/CLAUDE.md

@@ -28,22 +28,44 @@ 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 multiple conversations | `discussion.create` or `discussion.update` |
-| Need past info | `search` before asking user |
+### Always save — no user prompt needed
 
-Always pass `project`. Auto-compact fires at >50 entries — oldest summarized automatically.
+**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** — any phrase like "save this", "remember this", "note that" → save immediately.
+
+**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 >50 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,8 @@
+Call the `context` MCP tool with `action: "resume"` and `project: "$ARGUMENTS"` (if no argument given, infer the project name from the current working directory name).
+
+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,112 @@
+---
+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, `action: "resume"`, `project: "<project-name>"` **before any tool or response**.
+
+Infer `project` from the working directory name if not stated.
+
+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  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 >50 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