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).

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

graphmind

Your codebase has a shape. Now your AI can see it. And remember it.

GraphMind turns your codebase into a knowledge graph your AI can query, navigate, and remember. Ask about dead code, dependencies, or blast radius — and get answers grounded in your actual architecture.

Up to 5,700× fewer tokens than raw search (~10M tokens saved per session). Works with Claude Code, Cursor, Windsurf, Cline, Zed, Continue, and any MCP-compatible AI assistant.

Why GraphMind

Every new AI session starts from zero. Your assistant re-reads the entire codebase, re-discovers architecture, and forgets every decision you explained last time. Across multiple projects, there's zero visibility into shared dependencies.

graphmind fixes this with four layers:

1. Structural graph — function-level knowledge graph per repo (AST-based, tree-sitter, 30+ languages)
2. Semantic embeddings — vector search over symbols (local ONNX, OpenAI, or Voyage AI)
3. Persistent memory — declarative store for decisions, patterns, conventions — survives across sessions
4. Cross-project links — dependencies and relationships between registered repos

Everything runs locally. No cloud. No open ports by default. No telemetry.

Benchmark

Comparison of token usage: grep -r (raw file search) vs graphmind search for the same query on a ~100k LOC codebase. graphmind returns ranked, structured results in under 300 tokens vs 1.5M+ for raw grep output.

Install

Desktop app (macOS) — recommended

Download the .dmg from Releases. The app installs the CLI for you and runs a guided onboarding that configures MCP, hooks, skill, and embeddings — no terminal needed.

Linux / Windows: CLI only — use the shell script or direct download below.

CLI — shell script (macOS/Linux)

curl -fsSL https://raw.githubusercontent.com/aouicher/graphmind/main/scripts/install.sh | bash

Then run graphmind setup once to configure Claude Code, hooks, and skill.

Homebrew (macOS/Linux)

brew install aouicher/graphmind/graphmind                # CLI
brew install --cask aouicher/graphmind/graphmind         # Desktop app (macOS only)

CLI — Linux (direct download)

curl -fsSL https://github.com/aouicher/graphmind/releases/latest/download/graphmind-cli-linux-x64 -o ~/.local/bin/graphmind
chmod +x ~/.local/bin/graphmind

From source

git clone https://github.com/aouicher/graphmind
cd graphmind
cargo build --release -p graphmind-cli
cp target/release/graphmind ~/.local/bin/

Quick Start

graphmind setup          # once — configures Claude Code, Claude Desktop, hooks, skill
cd ~/projects/myapp
graphmind init           # per project — registers, installs git hooks, builds graph

That's it. Claude Code, Claude Desktop, Cursor, and VS Code will use graphmind automatically.

graphmind setup (once, global)

Configures your machine so all AI tools can use graphmind:

1. Shell PATH: when graphmind isn't on PATH yet, one marked line in the profile your shell reads (~/.zshenv for zsh, ~/.bashrc for bash, ~/.profile otherwise), after a backup of that profile. On Windows, ~/.graphmind/bin goes on the user PATH and into your PowerShell profile instead. A profile that can't be read as text is left unchanged, and setup prints the folder to add to PATH yourself
2. Claude Code hooks (session context, prompt pre-fetch, and a once-per-session nudge from grep/find searches and Explore agents to graphmind), registered in ~/.claude/settings.json; a settings.json that can't be read or parsed is left unchanged
3. Claude Code skill (/gm + 19 sub-skills)
4. Claude Desktop MCP (claude_desktop_config.json; the location per OS is under Manual setup)
5. Claude Code MCP entries, one per repository (projects.<path>.mcpServers.graphmind in ~/.claude.json, or $CLAUDE_CONFIG_DIR/.claude.json when that is set, under the path Claude Code reads for the repository, usually its main checkout; see MCP server for Claude Code): rewrites an entry that points at a moved binary or carries an env block, moves an entry earlier versions wrote under a worktree's or a subfolder's own path (which Claude Code never reads) to the repository's, and replaces a user-scope graphmind entry that runs graphmind with entries for the registered projects, in one write. Entries are added when a project is registered (graphmind init, graphmind register, the desktop app); a .claude.json that doesn't parse is left as is, and setup runs again later
6. OpenCode MCP (~/.config/opencode/opencode.jsonc)
7. Cursor global MCP (~/.cursor/mcp.json) — available in all Cursor projects
8. VS Code MCP entries — updates the entry in .vscode/mcp.json of registered projects that already have one
9. Git hooks of registered projects — after an upgrade, adds hooks introduced since they were installed (only where graphmind's hooks already are); an existing hook is backed up first, and one that can't be read as text or backed up is left unchanged
10. CLAUDE.md instruction block (~/.claude/CLAUDE.md); a block you edited is left as you set it

setup re-runs automatically after the binary is updated, when its configuration changed.

graphmind init (per project)

Registers and indexes a project:

1. Registers current directory in the graphmind registry
2. MCP project configs: the Claude Code entry of the project's repository (projects.<path>.mcpServers.graphmind in ~/.claude.json, through claude mcp add -s local when the claude CLI is on PATH), and VS Code's (<project>/.vscode/mcp.json), only in projects that already have a .vscode/ folder
3. Git hooks (rebuild after commit, merge, rebase and branch switch — new worktrees included; impact check on push)
4. Builds the code graph

cd ~/projects/api && graphmind init
cd ~/projects/web && graphmind init
cd ~/projects/lib && graphmind init

Both commands are idempotent — safe to re-run.

Using /gm outside a project

Claude Code's MCP entries are per repository (see MCP server for Claude Code), so a session opened outside every registered project has no graphmind MCP tools. /gm runs the graphmind CLI and works there too: in a session opened outside any indexed project (graphmind which prints nothing and exits 1), it still answers questions about a registered project. It runs graphmind list, picks the project the question is about (asking you only when several could match), and passes it to every command with --slug <project>, for example graphmind fn dispatch_tool --slug myapp. Every query command takes --slug, except list and cross query, which span all projects. A slug that isn't registered is an error. Questions about an unregistered folder go to the agent's normal tools.

Manual setup (if you prefer granular control)

MCP server for Claude Code

Claude Code gets graphmind per project, with one entry per repository, under the path Claude Code reads for it when started anywhere in the repository:

• a repository's main checkout, for the checkout, its linked worktrees and their subfolders;

• the bare repository (repo.git), for the worktrees of a bare repository;

• the submodule's root, for a submodule and its subfolders, and <superproject>/.git/modules/<name> for a worktree of a submodule;

• the work tree's root, for a repository created with --separate-git-dir;

• the folder itself, outside git.

• Registering a project (graphmind init, graphmind register, or adding it in the desktop app) writes or confirms that entry. From a worktree or a subfolder, it says which path it used.

• Unregistering a project removes the entry, unless another registered project uses it. For a project whose folder was deleted, the entry is the graphmind entry under its path or a parent that no registered project uses; when more than one could be, all are left and graphmind says so.

• A graphmind entry you set up by hand (its command isn't a graphmind binary) is left alone.

• A .claude.json that doesn't parse is left as is and the reason shown; the project is registered anyway.

By hand, in that path (the main checkout, for most repositories):

claude mcp remove -s local graphmind   # only to replace an existing entry: `claude mcp add` refuses a name that exists
claude mcp add -s local graphmind -- "$(command -v graphmind)" mcp

which writes this to ~/.claude.json ($CLAUDE_CONFIG_DIR/.claude.json when that is set), under that path:

{
  "projects": {
    "/home/user/projects/myapp": {
      "mcpServers": {
        "graphmind": {
          "type": "stdio",
          "command": "/home/user/.local/bin/graphmind",
          "args": ["mcp"],
          "env": {}
        }
      }
    }
  }
}

The command is the absolute path of your binary. command -v graphmind finds it on PATH (~/.local/bin/graphmind for the install script, $(brew --prefix)/bin/graphmind