graphmind

name	graphmind
description	> Use when this capability is needed.

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

---

Source: aouicher/graphmind — distributed by TomeVault.