/graphmind

description: >
  graphmind gives Claude Code persistent memory and structural code intelligence
  across all registered projects. Auto-triggers in any registered project directory.
  MANDATORY: query graphmind before using grep, find, or reading source files.
allowed-tools: Bash, Read, Write

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 (or the absolute path of the checkout — in a git worktree, its path selects its own graph and the repo's shared memory)
• 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