graphmind — Persistent Code Intelligence
MANDATORY: Search through graphmind FIRST
Before using Grep, find, rg, ag, or reading files to understand code: You MUST query graphmind first. Only fall back to grep/find if graphmind cannot answer (e.g., string literals, config values, non-code patterns).
| Need | Command | MCP tool |
|---|---|---|
| Find a symbol | graphmind fn <symbol> | gm_fn |
| Search by intent | graphmind search "<query>" | gm_search |
| File dependencies | graphmind deps <file> | gm_deps |
| Who calls X | graphmind query <symbol> | gm_query |
| Blast radius | graphmind fn-impact <symbol> | gm_fn_impact |
| Git change impact | graphmind diff-impact | gm_diff_impact |
| Project overview | graphmind map | gm_map |
| File outline | graphmind outline <file> | gm_outline |
| Raw file content | graphmind file <file> | gm_file |
| Who calls chain | — | gm_who_calls_chain |
| Dead code | — | gm_dead_code |
| Cross-project | graphmind cross query <symbol> | gm_cross_query |
| Memory search | graphmind memory search "<query>" | gm_memory_search |
Is this project registered?
Check: graphmind status
Register if not: graphmind register .
The 3-Layer Rule — always follow this order
Layer 1 — Structural graph (what the code IS)
Query before touching any code:
- Find a symbol:
graphmind fn <symbol>or MCPgm_fn - File dependencies:
graphmind deps <file>or MCPgm_deps - Blast radius before editing:
graphmind fn-impact <symbol> --no-tests - Impact of current git changes:
graphmind diff-impact - Entry points:
graphmind map - File structure:
graphmind outline <file>or MCPgm_outline - Transitive callers: MCP
gm_who_calls_chain
Layer 2 — Persistent memory (what was DECIDED, PREFERRED, KNOWN)
Query for context, decisions, conventions:
graphmind memory search "<query>"or MCPgm_memory_search
AUTO-RECALL: The hook automatically searches memory on each prompt. Use gm_memory_search for deeper/targeted recall.
AUTO-SAVE: When the conversation reveals any of the following, immediately save via gm_memory_add:
- Decisions (type: decision) — architecture choices, tech choices, trade-off resolutions
- Patterns (type: pattern) — recurring approaches, solutions, code patterns
- Conventions (type: convention) — naming, style, workflow rules
- Bugs (type: bug) — known issues, workarounds, gotchas
- Context (type: context) — business context, project goals, stakeholder info, user preferences
Save rules:
- Do NOT ask "should I save this?" — just save it
- Use
project=<slug>for project-specific facts - Use
global=truefor user preferences, team conventions, cross-project knowledge - Keep entries atomic: one fact per entry, clear and reusable
- Do NOT save ephemeral task progress or things derivable from code/git
Layer 3 — Raw files (only when layers 1-2 are insufficient)
Read source files only when editing or when the graph doesn't have the answer.
Cross-project queries
When a symbol or pattern might exist in another project:
graphmind cross query <symbol> or MCP gm_cross_query
Session workflow
Start of session: run graphmind session start → loads graph summary + recent memory
End of session: run graphmind session save → saves decisions and progress to memory
When to rebuild the graph
- After adding/removing modules or major refactors
- After
git mergewith structural changes - NOT every session — the graph persists between sessions
- Command:
graphmind build(fast, SHA256-cached)
NEVER
- Never use grep/find/rg to search for symbols — use graphmind
- Never re-read the entire codebase if graphmind can answer it
- Never manually edit files in
~/.graphmind/ - Never rebuild the graph every session
- Never skip the 3-layer rule