context-mcp-server 1.0.8 → 1.1.0

package/src/templates/CLAUDE.md

@@ -1,103 +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
-- `activePlans` — active AI-created plans for this project
-- `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: "note"  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` |
-| Gotcha, constraint, discovery, structure understood | `note` |
-| Config / env var / secret / deploy step | `config` |
+**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.
 
-**Making any kind of plan** → call `plan.save` immediately with the plan summary and `planDir` pointing to your platform's plans folder.
-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

package/src/templates/GEMINI.md

@@ -1,80 +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
-- `activePlans` — active AI-created plans for this project
-- `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: "note"  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` |
-| Gotcha, constraint, discovery, structure understood | `note` |
-| Config / env var / secret / deploy step | `config` |
+## 3. Plans (MANDATORY for multi-file work)
 
-Do NOT save: routine reads, search results, temporary debugging dead-ends.
-**Making any kind of plan** → call `plan.save` immediately with the plan summary and `planDir` pointing to your platform's plans folder.
-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_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/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"`, config/env/secret/deploy → `"config"`, 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/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,86 +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
-- `activePlans` — active AI-created plans for this project
+- `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: "note"  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.
+**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.
+
+---
+
+## Plans (MANDATORY for multi-file work)
 
-**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
+**Create a plan when:** editing 2+ files, multi-step implementation, refactor, multi-file bug fix.
 
-Do NOT save for: routine file reads, search results, explanations of existing code, temporary debugging steps that led nowhere.
+**Skip plan for:** single-file edits, questions, simple config tweaks.
 
-| What happened | Type |
-|--------------|------|
-| Approach / library / pattern decided | `decision` |
-| Bug found, root cause known, or fixed | `bug` |
-| Gotcha, constraint, discovery, structure understood | `note` |
-| Config / env var / secret / deploy step | `config` |
+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
 
-Always pass `project`. **Making any plan** → `plan.save` immediately (planDir = your platform's plans folder). Need past info → `search` before asking user. Auto-compact fires at >20 entries.
+On `resume`, check `activePlans` — do not duplicate in-progress work.
 
 ---
 
-## ContextGraph Pipeline
+## Auto-Summary Rule (MANDATORY)
 
-> Also called **CodeGraph**. MCP tools use the `codegraph_*` prefix — both names mean the same thing.
+When `resume` returns `stats.totalEntries ≥ 20`, call `context.save` **before the user's task**:
 
-### Build (once per project, ~seconds, local)
 ```
-codegraph_build(path)
+type: "compaction"  title: "Session summary — <date>"
+content: "<what was built, decided, broke, current state>"
+project: "<project>"
 ```
-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?, 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
-```
+---
+
+## Search Before Asking
+
+If user references past work → `search` first. Never ask user to re-explain saved information.
 
 ---
 
-## Graph vs File
+## ContextGraph Pipeline
+
+### Build (once per project)
+```
+codegraph_build(path)  →  AST graph: functions, classes, imports, edges
+```
 
-**Graph** — what exists: finding functions, classes, files, dependencies, callers, imports, paths between concepts.
+### 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`, `activePlans`, `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"` |
-| Discovery / structure understood | `context.save` type: `"note"` |
-| Making any plan | `plan.save` + `planDir` |
+```
+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