graphmind

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 MCP gm_fn
• File dependencies: graphmind deps <file> or MCP gm_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 MCP gm_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 MCP gm_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=true for 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 merge with 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