Skip to content
Back to search

graphmind

SkillWorks with Claude CodeGitHub

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/aouicher--graphmind/badge.svg)](/listings/aouicher--graphmind)

HTML

<a href="/listings/aouicher--graphmind"><img src="/api/listings/aouicher--graphmind/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

Desktop app (macOS) — recommended

Download the `.dmg` from [Releases](https://github.com/aouicher/graphmind/releases). The app installs the CLI for you and runs a guided onboarding that configures MCP, hooks, skill, and embeddings — no terminal needed.

| Platform | Asset | |----------|-------| | macOS (Apple Silicon) | `GraphMind-macos-arm64.dmg` | | macOS (Intel) | `GraphMind-macos-x64.dmg` |

> **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/

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 90 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. ---
  2. description: >
  3. graphmind gives Claude Code persistent memory and structural code intelligence
  4. across all registered projects. Auto-triggers in any registered project directory.
  5. MANDATORY: query graphmind before using grep, find, or reading source files.
  6. allowed-tools: Bash, Read, Write
  7. ---
  8. # graphmind — Persistent Code Intelligence
  9. ## MANDATORY: Search through graphmind FIRST
  10. **Before using Grep, find, rg, ag, or reading files to understand code:**
  11. You MUST query graphmind first. Only fall back to grep/find if graphmind cannot answer (e.g., string literals, config values, non-code patterns).
  12. | Need | Command | MCP tool |
  13. |------|---------|----------|
  14. | Find a symbol | `graphmind fn <symbol>` | `gm_fn` |
  15. | Search by intent | `graphmind search "<query>"` | `gm_search` |
  16. | File dependencies | `graphmind deps <file>` | `gm_deps` |
  17. | Who calls X | `graphmind query <symbol>` | `gm_query` |
  18. | Blast radius | `graphmind fn-impact <symbol>` | `gm_fn_impact` |
  19. | Git change impact | `graphmind diff-impact` | `gm_diff_impact` |
  20. | Project overview | `graphmind map` | `gm_map` |
  21. | File outline | `graphmind outline <file>` | `gm_outline` |
  22. | Raw file content | `graphmind file <file>` | `gm_file` |
  23. | Who calls chain | — | `gm_who_calls_chain` |
  24. | Dead code | — | `gm_dead_code` |
  25. | Cross-project | `graphmind cross query <symbol>` | `gm_cross_query` |
  26. | Memory search | `graphmind memory search "<query>"` | `gm_memory_search` |
  27. ## Is this project registered?
  28. Check: `graphmind status`
  29. Register if not: `graphmind register .`
  30. ## The 3-Layer Rule — always follow this order
  31. ### Layer 1 — Structural graph (what the code IS)
  32. Query before touching any code:
  33. - Find a symbol: `graphmind fn <symbol>` or MCP `gm_fn`
  34. - File dependencies: `graphmind deps <file>` or MCP `gm_deps`
  35. - Blast radius before editing: `graphmind fn-impact <symbol> --no-tests`
  36. - Impact of current git changes: `graphmind diff-impact`
  37. - Entry points: `graphmind map`
  38. - File structure: `graphmind outline <file>` or MCP `gm_outline`
  39. - Transitive callers: MCP `gm_who_calls_chain`
  40. ### Layer 2 — Persistent memory (what was DECIDED, PREFERRED, KNOWN)
  41. Query for context, decisions, conventions:
  42. - `graphmind memory search "<query>"` or MCP `gm_memory_search`
  43. **AUTO-RECALL:** The hook automatically searches memory on each prompt. Use `gm_memory_search` for deeper/targeted recall.
  44. **AUTO-SAVE:** When the conversation reveals any of the following, immediately save via `gm_memory_add`:
  45. - **Decisions** (type: decision) — architecture choices, tech choices, trade-off resolutions
  46. - **Patterns** (type: pattern) — recurring approaches, solutions, code patterns
  47. - **Conventions** (type: convention) — naming, style, workflow rules
  48. - **Bugs** (type: bug) — known issues, workarounds, gotchas
  49. - **Context** (type: context) — business context, project goals, stakeholder info, user preferences
  50. Save rules:
  51. - Do NOT ask "should I save this?" — just save it
  52. - 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)
  53. - Use `global=true` for user preferences, team conventions, cross-project knowledge
  54. - Keep entries atomic: one fact per entry, clear and reusable
  55. - Do NOT save ephemeral task progress or things derivable from code/git
  56. ### Layer 3 — Raw files (only when layers 1-2 are insufficient)
  57. Read source files only when editing or when the graph doesn't have the answer.
  58. ## Cross-project queries
  59. When a symbol or pattern might exist in another project:
  60. `graphmind cross query <symbol>` or MCP `gm_cross_query`
  61. ## Session workflow
  62. **Start of session:** run `graphmind session start` → loads graph summary + recent memory
  63. **End of session:** run `graphmind session save` → saves decisions and progress to memory
  64. ## When to rebuild the graph
  65. - After adding/removing modules or major refactors
  66. - After `git merge` with structural changes
  67. - NOT every session — the graph persists between sessions
  68. - Command: `graphmind build` (fast, SHA256-cached)
  69. ## NEVER
  70. - Never use grep/find/rg to search for symbols — use graphmind
  71. - Never re-read the entire codebase if graphmind can answer it
  72. - Never manually edit files in `~/.graphmind/`
  73. - Never rebuild the graph every session
  74. - Never skip the 3-layer rule
README.md · README · 776 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # graphmind
  2. [![CI](https://github.com/aouicher/graphmind/actions/workflows/ci.yml/badge.svg)](https://github.com/aouicher/graphmind/actions/workflows/ci.yml)
  3. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
  4. > Your codebase has a shape. Now your AI can see it. And remember it.
  5. 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.
  6. 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.
  7. <table><tr>
  8. <td><img src="graphmind-demo-cli.gif" width="400" alt="GraphMind CLI demo" /></td>
  9. <td><img src="graphmind-demo-desktop.gif" width="400" alt="GraphMind Desktop app" /></td>
  10. </tr>
  11. <tr>
  12. <td align="center"><sub>CLI + Claude MCP integration</sub></td>
  13. <td align="center"><sub>Desktop app — Mac &amp; Windows</sub></td>
  14. </tr></table>
  15. ## Why GraphMind
  16. 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.
  17. **graphmind** fixes this with four layers:
  18. 1. **Structural graph** — function-level knowledge graph per repo (AST-based, tree-sitter, 30+ languages)
  19. 2. **Semantic embeddings** — vector search over symbols (local ONNX, OpenAI, or Voyage AI)
  20. 3. **Persistent memory** — declarative store for decisions, patterns, conventions — survives across sessions
  21. 4. **Cross-project links** — dependencies and relationships between registered repos
  22. Everything runs locally. No cloud. No open ports by default. No telemetry.
  23. ## Benchmark
  24. ![grep vs graphmind](assets/benchmark.png)
  25. 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.
  26. ## Install
  27. ### Desktop app (macOS) — recommended
  28. Download the `.dmg` from [Releases](https://github.com/aouicher/graphmind/releases). The app installs the CLI for you and runs a guided onboarding that configures MCP, hooks, skill, and embeddings — no terminal needed.
  29. ![GraphMind desktop app](assets/screenshot-desktop.png)
  30. | Platform | Asset |
  31. |----------|-------|
  32. | macOS (Apple Silicon) | `GraphMind-macos-arm64.dmg` |
  33. | macOS (Intel) | `GraphMind-macos-x64.dmg` |
  34. > **Linux / Windows**: CLI only — use the shell script or direct download below.
  35. ### CLI — shell script (macOS/Linux)
  36. ```bash
  37. curl -fsSL https://raw.githubusercontent.com/aouicher/graphmind/main/scripts/install.sh | bash
  38. ```
  39. Then run `graphmind setup` once to configure Claude Code, hooks, and skill.
  40. ### Homebrew (macOS/Linux)
  41. ```bash
  42. brew install aouicher/graphmind/graphmind # CLI
  43. brew install --cask aouicher/graphmind/graphmind # Desktop app (macOS only)
  44. ```
  45. ### CLI — Linux (direct download)
  46. ```bash
  47. curl -fsSL https://github.com/aouicher/graphmind/releases/latest/download/graphmind-cli-linux-x64 -o ~/.local/bin/graphmind
  48. chmod +x ~/.local/bin/graphmind
  49. ```
  50. ### From source
  51. ```bash
  52. git clone https://github.com/aouicher/graphmind
  53. cd graphmind
  54. cargo build --release -p graphmind-cli
  55. cp target/release/graphmind ~/.local/bin/
  56. ```
  57. ## Quick Start
  58. ```bash
  59. graphmind setup # once — configures Claude Code, Claude Desktop, hooks, skill
  60. cd ~/projects/myapp
  61. graphmind init # per project — registers, installs git hooks, builds graph
  62. ```
  63. That's it. Claude Code, Claude Desktop, Cursor, and VS Code will use graphmind automatically.
  64. ### `graphmind setup` (once, global)
  65. Configures your machine so all AI tools can use graphmind:
  66. 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
  67. 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
  68. 3. Claude Code skill (`/gm` + 19 sub-skills)
  69. 4. Claude Desktop MCP (`claude_desktop_config.json`; the location per OS is under [Manual setup](#manual-setup-if-you-prefer-granular-control))
  70. 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](#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
  71. 6. OpenCode MCP (`~/.config/opencode/opencode.jsonc`)
  72. 7. Cursor global MCP (`~/.cursor/mcp.json`) — available in all Cursor projects
  73. 8. VS Code MCP entries — updates the entry in `.vscode/mcp.json` of registered projects that already have one
  74. 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
  75. 10. CLAUDE.md instruction block (`~/.claude/CLAUDE.md`); a block you edited is left as you set it
  76. `setup` re-runs automatically after the binary is updated, when its configuration changed.
  77. ### `graphmind init` (per project)
  78. Registers and indexes a project:
  79. 1. Registers current directory in the graphmind registry
  80. 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
  81. 3. Git hooks (rebuild after commit, merge, rebase and branch switch — new worktrees included; impact check on push)
  82. 4. Builds the code graph
  83. ```bash
  84. cd ~/projects/api && graphmind init
  85. cd ~/projects/web && graphmind init
  86. cd ~/projects/lib && graphmind init
  87. ```
  88. Both commands are idempotent — safe to re-run.
  89. ### Using `/gm` outside a project
  90. Claude Code's MCP entries are per repository (see [MCP server for Claude Code](#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.
  91. ### Manual setup (if you prefer granular control)
  92. <details>
  93. <summary>Click to expand</summary>
  94. #### MCP server for Claude Code
  95. 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:
  96. - a repository's main checkout, for the checkout, its linked worktrees and their subfolders;
  97. - the bare repository (`repo.git`), for the worktrees of a bare repository;
  98. - the submodule's root, for a submodule and its subfolders, and `<superproject>/.git/modules/<name>` for a worktree of a submodule;
  99. - the work tree's root, for a repository created with `--separate-git-dir`;
  100. - the folder itself, outside git.
  101. - 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.
  102. - 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.
  103. - A `graphmind` entry you set up by hand (its command isn't a graphmind binary) is left alone.
  104. - A `.claude.json` that doesn't parse is left as is and the reason shown; the project is registered anyway.
  105. By hand, in that path (the main checkout, for most repositories):
  106. ```bash
  107. claude mcp remove -s local graphmind # only to replace an existing entry: `claude mcp add` refuses a name that exists
  108. claude mcp add -s local graphmind -- "$(command -v graphmind)" mcp
  109. ```
  110. which writes this to `~/.claude.json` (`$CLAUDE_CONFIG_DIR/.claude.json` when that is set), under that path:
  111. ```json
  112. {
  113. "projects": {
  114. "/home/user/projects/myapp": {
  115. "mcpServers": {
  116. "graphmind": {
  117. "type": "stdio",
  118. "command": "/home/user/.local/bin/graphmind",
  119. "args": ["mcp"],
  120. "env": {}
  121. }
  122. }
  123. }
  124. }
  125. }
  126. ```
  127. 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` for Homebrew). `graphmind setup` uses `~/.graphmind/bin/graphmind` instead whenever that file exists (older installs), even when another `graphmind` is first on PATH: pass that path to match it. The empty `env` is fine, but an `env.PATH` there replaces the environment the server inherits, so don't add one.
  128. #### MCP server for Claude Desktop
  129. Claude Desktop does not inherit your shell PATH, so use the full path:
  130. ```json
  131. {
  132. "mcpServers": {
  133. "graphmind": {
  134. "command": "/home/user/.local/bin/graphmind",
  135. "args": ["mcp"]
  136. }
  137. }
  138. }
  139. ```
  140. Config file location:
  141. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  142. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  143. - **Linux**: `~/.config/claude/claude_desktop_config.json`
  144. > **Tip**: Run `command -v graphmind` to find the correct path on your system.
  145. #### MCP server for Cursor (global)
  146. `graphmind setup` writes this automatically to `~/.cursor/mcp.json`:
  147. ```json
  148. {
  149. "mcpServers": {
  150. "graphmind": {
  151. "command": "/home/user/.local/bin/graphmind",
  152. "args": ["mcp"]
  153. }
  154. }
  155. }
  156. ```
  157. #### MCP server for VS Code (per project)
  158. `graphmind init` writes this automatically to `<project>/.vscode/mcp.json`, in projects that already have a `.vscode/` folder:
  159. ```json
  160. {
  161. "servers": {
  162. "graphmind": {
  163. "type": "stdio",
  164. "command": "/home/user/.local/bin/graphmind",
  165. "args": ["mcp"]
  166. }
  167. }
  168. }
  169. ```
  170. #### Claude Code search hook
  171. ```bash
  172. graphmind install hook-claude
  173. ```
  174. Registers hooks in `~/.claude/settings.json` for:
  175. - **PreToolUse** — once per session, reminds Claude to use graphmind when it reaches for grep/rg/find or an Explore agent
  176. - **SessionStart** — loads project context (stats, structure, priority memories) and runs memory upkeep once a day
  177. - **UserPromptSubmit** — pre-fetches relevant memories and code symbols for the user's prompt; priority memories already shown this session are not repeated
  178. Hook output stays under Claude Code's 10,000-character hook limit (longer output is replaced by a short preview), and hooks skip prompts that no person typed (task notifications, messages from other sessions). Re-running `graphmind install hook-claude` or `graphmind setup` removes hooks from older versions.
  179. Built-in intelligence:
  180. - **Exhaustive search bypass** — detects "find all occurrences", `grep -c`, pipes to `wc`/`sort` and lets them through
  181. - **Cache deduplication** — identical searches within 3 minutes are skipped (0 tokens cost)
  182. - **Pattern extraction** — extracts meaningful search terms from grep, find, fd, rg commands and Agent prompts
  183. #### Claude Code skill
  184. ```bash
  185. graphmind install skill
  186. ```
  187. #### CLAUDE.md sync
  188. ```bash
  189. graphmind sync # updates CLAUDE.md in current project
  190. graphmind sync --all # updates CLAUDE.md for all registered projects
  191. ```
  192. #### Git hooks
  193. ```bash
  194. graphmind install hook-git
  195. ```
  196. Installs, in the repo's own git dir (shared by all its worktrees):
  197. - **post-commit**, **post-merge**, **post-rewrite** — rebuild the graph in the background after a commit, a pull/merge, a rebase or an amend
  198. - **post-checkout** — reindex the files that changed on a branch switch; on `git worktree add`, register the new worktree and seed its graph
  199. - **pre-push** — print `graphmind diff-impact`
  200. Existing hook scripts are kept (graphmind appends its lines, after a backup). With husky or a `core.hooksPath` outside the repo's git dir, nothing is modified: graphmind prints the lines to add yourself.
  201. </details>
  202. ## Git Worktrees & Branches
  203. graphmind is worktree-aware. Each checkout of a repo gets its own code graph,
  204. so answers always describe the branch you are on, while memory (decisions,
  205. conventions, bugs) is shared by all of them: it is repo-wide knowledge.
  206. - **Zero setup for new worktrees**: `git worktree add` (or `claude --worktree`,
  207. or any graphmind command / MCP call made from a new checkout) registers the
  208. worktree on the spot. Identity is proven by git (`--git-common-dir`), never
  209. guessed from names.
  210. - **Nested worktrees**: checkouts inside the main one — Claude Code's
  211. `.claude/worktrees/<name>` — resolve to themselves, never to the main
  212. checkout's graph.
  213. - **Fast first build**: a new worktree's graph is copied from the main
  214. checkout's, then updated incrementally in the background. Only the files
  215. that differ between the two checkouts get parsed.
  216. - **Shared memory**: a worktree uses its main project's memory file
  217. (`graphmind list` shows `worktree of <slug>`).
  218. - **Reindex on git activity**: the git hooks (`graphmind install hook-git`,
  219. run by `graphmind init`) rebuild after commit, merge, rebase and branch
  220. switch. Hooks live in the repo's git dir, so every worktree gets them.
  221. Repos using husky or a shared `core.hooksPath` are not modified; graphmind
  222. prints the lines to add.
  223. - **No silent wrong answers**: from a git repo that is neither registered nor
  224. a worktree of a registered repo, commands fail with an explicit error
  225. instead of answering from another project. Outside any git repo, a single
  226. registered project is still used as before.
  227. - **Claude Code MCP entry**: one per repository, under the main checkout,
  228. which is where Claude Code reads it in every worktree. `graphmind init` in
  229. a worktree writes or confirms the main checkout's entry, and a worktree
  230. never gets an entry of its own.
  231. - **Cleanup**: a worktree registered automatically is forgotten, with its
  232. graph, once its directory is gone: by the next `graphmind list`,
  233. `graphmind build --all` or worktree registration. Projects registered by
  234. hand stay until `graphmind clean --stale`.
  235. ### Agents switching worktrees mid-session
  236. An MCP server answers for the checkout it was started in. When an agent moves
  237. into another worktree during a session, it should pass
  238. `project=<absolute path of that worktree>` (or its slug) to graphmind tools;
  239. the server instructions tell agents to do so.
  240. ### Upgrading
  241. Nothing to migrate. Existing projects, graphs and memory files are used as
  242. they are; projects registered before worktree support are recognized on
  243. first use. After the upgrade, `graphmind setup` (re-run automatically when
  244. the binary is updated) adds the new git hooks to repos that already have
  245. graphmind's hooks.
  246. ## Architecture
  247. ```
  248. ┌─────────────────────────────────────────────┐
  249. │ Claude Code / MCP Client │
  250. ├─────────────────────────────────────────────┤
  251. │ MCP Server (rmcp SDK, stdio) — 27 tools │
  252. │ gm_query · gm_fn · gm_file · gm_deps │
  253. │ gm_outline · gm_who_calls_chain · gm_dead │
  254. │ gm_export · gm_similar · gm_listeners │
  255. │ gm_memory_search · gm_cross_query │
  256. │ gm_status · gm_context · gm_diff_impact │
  257. ├─────────────────────────────────────────────┤
  258. │ Layer 1: Structural Graph (SQLite + FTS5) │
  259. │ Symbols · Edges · Call sites │
  260. ├─────────────────────────────────────────────┤
  261. │ Layer 2: Semantic Embeddings (SQLite) │
  262. │ Cosine search · Graph expansion · RRF │
  263. ├─────────────────────────────────────────────┤
  264. │ Layer 3: Semantic Memory (JSONL) │
  265. │ Decisions · Patterns · Conventions │
  266. ├─────────────────────────────────────────────┤
  267. │ Layer 4: Cross-Project Links (JSONL) │
  268. │ Shared symbols · Inferred relationships │
  269. ├─────────────────────────────────────────────┤
  270. │ Rust Core (tree-sitter + napi-rs) │
  271. │ Multi-language parsing · Symbol extraction │
  272. └─────────────────────────────────────────────┘
  273. ```
  274. ## Search & Embeddings
  275. graphmind search combines three retrieval strategies into a single ranked result:
  276. ```bash
  277. graphmind search "<query>" # hybrid search (FTS + semantic + graph)
  278. graphmind search "<q1>; <q2>" # multi-query with RRF ranking
  279. graphmind search "<query>" --kind function
  280. ```
  281. ### How search works
  282. 1. **FTS5** — exact text matching on symbol names, signatures, docs
  283. 2. **Semantic embeddings** — cosine similarity finds conceptually related symbols (e.g. "money transfer" → `payment_service`)
  284. 3. **Graph expansion** — top results are expanded with 1-hop callers/callees from the structural graph
  285. Results are fused via Reciprocal Rank Fusion (RRF, k=60). Each result shows its source: `[FTS]`, `[SEM]`, `[GRAPH]`, or combinations like `[FTS+SEM+G]`.
  286. ### Embedding providers
  287. Configured in `~/.graphmind/config.json`:
  288. ```json
  289. {
  290. "embedding": {
  291. "mode": "voyage",
  292. "model": "voyage-code-3",
  293. "api_keys": {
  294. "voyage": "pa-..."
  295. }
  296. }
  297. }
  298. ```
  299. | Mode | Model (default) | Notes |
  300. |------|----------------|-------|
  301. | `local` | `nomic-embed-text-v1.5` (768d) | ONNX, no API key needed |
  302. | `openai` | `text-embedding-3-small` (1536d) | Supports custom `openai_base_url` |
  303. | `voyage` | `voyage-code-3` (1024d) | Code-specialized, recommended |
  304. | `disabled` | — | No embeddings — **default for new installs** |
  305. Embeddings are computed automatically during `graphmind build` when a provider is configured. If the model changes, the embedding index is rebuilt automatically.
  306. OpenAI-compatible providers (Azure, proxies) can set a custom base URL:
  307. ```json
  308. {
  309. "embedding": {
  310. "mode": "openai",
  311. "model": "text-embedding-3-large",
  312. "openai_base_url": "https://your-proxy.example.com/v1",
  313. "api_keys": { "openai": "sk-..." }
  314. }
  315. }
  316. ```
  317. ## Persistent Memory
  318. graphmind gives Claude persistent memory across sessions — not just code, but decisions, patterns, conventions, and context.
  319. ### How it works
  320. Memory is **fully automatic**:
  321. - **Auto-recall** — at each prompt, the hook searches memory for relevant context and injects it into the conversation. No action needed.
  322. - **Auto-save** — Claude proactively saves important facts (decisions, patterns, conventions, bugs, context) without asking. You'll see a brief mention of what was saved.
  323. This works for both **Claude Code** (via hooks) and **Claude Desktop** (via MCP instructions).
  324. ### What gets saved
  325. | Type | Examples |
  326. |------|----------|
  327. | `decision` | Architecture choices, tech decisions, trade-off resolutions |
  328. | `pattern` | Recurring approaches, solutions, code patterns |
  329. | `convention` | Naming rules, workflow conventions, style guides |
  330. | `bug` | Known issues, workarounds, gotchas |
  331. | `context` | Business context, project goals, user preferences |
  332. ### Storage
  333. Memories are stored as JSONL files in `~/.graphmind/memory/`:
  334. - `global.jsonl` — cross-project knowledge (user preferences, team conventions)
  335. - `<project-slug>.jsonl` — project-specific facts
  336. ### Manual control
  337. ```bash
  338. graphmind memory add "<fact>" [--slug <slug>] [--global]
  339. graphmind memory search "<query>"
  340. graphmind memory list
  341. graphmind memory delete <id>
  342. ```
  343. Memories persist indefinitely until explicitly deleted. They are recalled automatically — you never need to ask "do you remember X?".
  344. ## Commands
  345. ### Setup & Init
  346. ```bash
  347. graphmind setup # global one-time (hooks, MCP, skill)
  348. graphmind init [path] # per-project (register, git hooks, build)
  349. graphmind init --skip-build # per-project without building
  350. ```
  351. ### Registry
  352. ```bash
  353. graphmind register [path] # register current dir (and its Claude Code MCP entry)
  354. graphmind unregister <slug> # remove project (and its Claude Code MCP entry)
  355. graphmind list # all projects
  356. graphmind status # health check
  357. ```
  358. ### Build
  359. ```bash
  360. graphmind build [slug] # incremental build
  361. graphmind build --all # all projects
  362. graphmind build --full # force full rebuild
  363. graphmind build --watch # watch mode (debounced 2s)
  364. graphmind clean [slug] # remove graph cache (forces full rebuild)
  365. graphmind clean --all # clean all projects
  366. graphmind clean --stale # unregister projects whose worktree was removed
  367. ```
  368. ### Query
  369. ```bash
  370. graphmind query <symbol> # find symbol + connections
  371. graphmind query <symbol> --file <path> # filter to a specific file
  372. graphmind query <symbol> --kind function # filter by kind
  373. graphmind query <symbol> --limit 20 --offset 0 # paginate callers/callees
  374. graphmind fn <symbol> # full detail with source + callers/callees
  375. graphmind fn <symbol> --file <path> # disambiguate by file
  376. graphmind fn <symbol> --kind function # filter by kind
  377. graphmind fn <symbol> --limit 20 --offset 0 # paginate callers/callees
  378. graphmind fn <symbol> --include-content # include source code in output
  379. graphmind fn <symbol> --no-tests # skip test files
  380. graphmind deps <file> # file dependency map
  381. graphmind impact <file> # transitive reverse deps
  382. graphmind fn-impact <symbol> # blast radius
  383. graphmind diff-impact # impact of current git changes
  384. graphmind diff-impact --staged
  385. graphmind map [slug] # most-connected files
  386. graphmind cycles [slug] # circular dependencies
  387. graphmind outline <file> # hierarchical symbol tree for a file
  388. graphmind file <file> # raw content of an indexed file, path from project root
  389. graphmind who-calls <symbol> # transitive caller chain (BFS)
  390. graphmind who-calls <symbol> --depth 5 # limit traversal depth
  391. graphmind dead-code # symbols with no incoming edges
  392. graphmind dead-code --kind function # filter by kind
  393. graphmind dead-code --limit 50 # cap results
  394. graphmind similar <symbol> # structurally similar symbols
  395. graphmind similar <symbol> --limit 10 # cap results
  396. graphmind listeners <event> # find listeners for an event name
  397. ```
  398. ### Search
  399. ```bash
  400. graphmind search "<query>" # hybrid FTS + semantic + graph
  401. graphmind search "<q1>; <q2>" # multi-query
  402. graphmind search "<query>" --kind class
  403. graphmind search "<query>" --offset 10 # paginate results
  404. graphmind search "<query>" --include-content # include source code in output
  405. ```
  406. ### Embeddings
  407. ```bash
  408. graphmind embed # show embedding index status
  409. graphmind embed --run # generate embeddings for current project
  410. graphmind embed --run --all # generate embeddings for all projects
  411. ```
  412. ### Memory
  413. ```bash
  414. graphmind memory add "<fact>" [--slug <slug>] [--global]
  415. graphmind memory search "<query>"
  416. graphmind memory list
  417. graphmind memory delete <id>
  418. ```
  419. ### Cross-Project
  420. ```bash
  421. graphmind cross query <symbol> # search across ALL projects
  422. graphmind cross deps <slug> # who depends on this project
  423. graphmind cross links # all cross-project relationships
  424. graphmind cross link add <a> <b> # manual link
  425. graphmind cross link infer # auto-detect shared symbols
  426. ```
  427. ### Export
  428. ```bash
  429. graphmind export [slug] -f dot # Graphviz dot format
  430. graphmind export [slug] -f mermaid # Mermaid diagram
  431. graphmind export [slug] -f json # JSON graph
  432. graphmind export --cross -f mermaid # cross-project diagram
  433. graphmind export --obsidian ~/vault/ # Obsidian vault with [[wikilinks]]
  434. ```
  435. ### Exclude
  436. ```bash
  437. graphmind exclude list # show all patterns
  438. graphmind exclude add grafana-data # exclude from current project
  439. graphmind exclude add grafana-data --global
  440. graphmind exclude remove grafana-data
  441. ```
  442. ### Team Sync *(Pro/Team tiers)*
  443. Share your code graph and architectural memories across your team. Every member gets the same structural understanding without re-indexing.
  444. ```bash
  445. graphmind team init [--team-id <id>] # connect to a team
  446. graphmind team push [slug] # push graph + shared memories
  447. graphmind team push --memories-only # push memories only
  448. graphmind team push --graph-only # push graph only
  449. graphmind team push --all # push all projects
  450. graphmind team pull [slug] # pull latest from team
  451. graphmind team status # sync status per project
  452. ```
  453. - **Auto-sync** (Team tier): graph is pushed automatically after each `graphmind build`
  454. - **Memory privacy**: memories marked private (`is_shared: false`) never leave the machine
  455. - **MCP tools**: `gm_team_memories` (shared context) · `gm_team_who_knows` (who documented a symbol)
  456. ### Sessions
  457. ```bash
  458. graphmind session start [slug] # log session start
  459. graphmind session save ["message"] # save session summary
  460. graphmind session history [slug] # recent sessions
  461. ```
  462. ### Install / Uninstall
  463. ```bash
  464. graphmind install hook-claude # Claude Code search hook
  465. graphmind install hook-git # git hooks (rebuild on commit/merge/rebase/checkout, diff-impact on push)
  466. graphmind install skill # Claude Code skill
  467. graphmind uninstall hook-claude # remove Claude Code hook
  468. graphmind uninstall hook-git # remove git hooks
  469. graphmind uninstall all [--purge] [--yes] # remove ALL integrations (reverse of setup+init); --purge also deletes ~/.graphmind data
  470. graphmind sync [slug] # inject graph context into CLAUDE.md
  471. graphmind sync --all # update CLAUDE.md for all projects
  472. ```
  473. ### Update
  474. ```bash
  475. graphmind update # download and install latest version
  476. graphmind update --check # check for updates without installing
  477. ```
  478. If installed via Homebrew, use `brew upgrade graphmind` instead. The desktop app also checks for CLI updates at startup and offers one-click update.
  479. ## Token Optimization
  480. MCP responses are optimized for LLM consumption — minimal tokens, maximum signal.
  481. **Compact format (default):** One-line-per-symbol text output instead of verbose JSON. Example:
  482. ```
  483. >> 5 result(s) for "auth" [FTS+semantic+graph]:
  484. AuthService [Class] src/services/auth.ts:3 (0.95) [FTS+SEM]
  485. implements Service
  486. validate_token [Function] src/services/auth.ts:15 (0.82) [FTS+G]
  487. (token: string, scope?: string) -> TokenResult
  488. ```
  489. **Field pruning:** No `id`, no null signature/doc/content, no redundant `total_found`/`projects_searched` fields. Only useful information is returned.
  490. **Smart limits:** Default 15 results (not 50). Truncation indicators (`+N more...`) shown only when results are capped.
  491. **Content opt-in:** Symbol source code is omitted by default. Pass `include_content: true` to any tool to get it.
  492. **JSON mode:** Pass `format: "json"` to any tool to get structured JSON output instead of compact text.
  493. **Hook cache deduplication:** The Claude Code hook skips duplicate searches within a 5-minute window. Same query → instant skip (0 tokens). Cache is per-session at `/tmp/graphmind-hook-cache.txt`.
  494. ## MCP Tools Reference
  495. graphmind exposes 27 tools via MCP (Model Context Protocol):
  496. | Tool | Description |
  497. |------|-------------|
  498. | `gm_query` | Find symbol and its connections |
  499. | `gm_fn` | Function detail with source + callers/callees |
  500. | `gm_deps` | File-level dependency map |
  501. | `gm_impact` | Transitive reverse dependencies |
  502. | `gm_fn_impact` | Blast radius for a symbol |
  503. | `gm_diff_impact` | Impact of current git changes |
  504. | `gm_map` | Most-connected files |
  505. | `gm_cycles` | Circular dependency detection |
  506. | `gm_search` | Hybrid search (FTS + semantic + graph) |
  507. | `gm_listeners` | Find event listeners by event name |
  508. | `gm_outline` | Hierarchical file structure with qualified names |
  509. | `gm_file` | Raw source content of a file |
  510. | `gm_who_calls_chain` | Transitive caller chain (BFS) |
  511. | `gm_dead_code` | Find symbols with no incoming edges |
  512. | `gm_export` | Export subgraph as Mermaid/DOT |
  513. | `gm_similar` | Find structurally similar symbols |
  514. | `gm_memory_search` | Search stored decisions/patterns |
  515. | `gm_memory_add` | Store a fact (requires confirmation) |
  516. | `gm_memory_list` | List memory entries |
  517. | `gm_memory_update` | Edit a fact in place (keeps its id; a type change can reset the expiry, a demotion the recall count) |
  518. | `gm_session_analyze` | Save several facts at once, skipping near-duplicates |
  519. | `gm_cross_query` | Symbol search across all projects |
  520. | `gm_cross_deps` | Cross-project dependency graph |
  521. | `gm_cross_links` | List all cross-project links |
  522. | `gm_status` | Project health and stats |
  523. | `gm_context` | Full project context for session start |
  524. | `gm_list_projects` | All registered projects |
  525. | `gm_team_memories` | Shared team memories and context *(Pro/Team)* |
  526. | `gm_team_who_knows` | Who documented a given symbol *(Pro/Team)* |
  527. ## Security
  528. - **No open ports by default** — MCP uses stdio.
  529. - **Path traversal protection** — all file ops restricted to registered paths + `~/.graphmind/`.
  530. - **No network calls by default** — everything runs locally. Embedding API calls only when explicitly configured. Team sync (Pro/Team tiers) is opt-in and never runs automatically on Free.
  531. - **API keys stored locally** — in `~/.graphmind/config.json`, never sent anywhere except the configured provider.
  532. - **Atomic writes** — memory JSONL writes use tmp+rename to prevent corruption.
  533. - **MCP write confirmation** — `gm_memory_add` requires explicit confirmation.
  534. ## Language Support
  535. | Language | Extensions | Status |
  536. |----------|-----------|--------|
  537. | TypeScript | `.ts`, `.tsx` | Stable |
  538. | JavaScript | `.js`, `.jsx`, `.mjs` | Stable |
  539. | Python | `.py` | Stable |
  540. | Go | `.go` | Stable |
  541. | Rust | `.rs` | Stable |
  542. | Ruby | `.rb` | Stable |
  543. | Terraform (HCL) | `.tf`, `.tfvars` | Stable |
  544. | YAML | `.yml`, `.yaml` | Stable |
  545. | Markdown | `.md` | Stable |
  546. | C | `.c`, `.h` | Stable |
  547. | Objective-C | `.m`, `.mm` | Stable |
  548. | Java | `.java` | Stable |
  549. | PHP | `.php` | Stable |
  550. | Swift | `.swift` | Stable |
  551. | Bash | `.sh`, `.bash`, `.zsh` | Stable |
  552. | Perl | `.pl`, `.pm` | Stable |
  553. | CSS | `.css` | Stable |
  554. | SCSS | `.scss`, `.sass` | Stable |
  555. | HTML | `.html`, `.htm` | Stable |
  556. | TOML | `.toml` | Stable |
  557. | Dockerfile | `Dockerfile` | Stable |
  558. | SQL | `.sql` | Stable |
  559. | C++ | `.cpp`, `.cc`, `.cxx`, `.hpp` | Stable |
  560. | C# | `.cs` | Stable |
  561. | Kotlin | `.kt`, `.kts` | Stable |
  562. | Dart | `.dart` | Stable |
  563. | Scala | `.scala`, `.sc` | Stable |
  564. | R | `.r`, `.R` | Stable |
  565. | GraphQL | `.graphql`, `.gql` | Stable |
  566. | PowerShell | `.ps1`, `.psm1` | Stable |
  567. ## Data Storage
  568. All data lives in `~/.graphmind/`:
  569. ```
  570. ~/.graphmind/
  571. ├── config.json # registered projects + embedding settings
  572. ├── memory/ # JSONL memory files
  573. ├── graphs/<slug>/
  574. │ ├── graph.db # structural graph (SQLite + FTS5)
  575. │ ├── embeddings.db # vector embeddings (SQLite)
  576. │ ├── meta.json # build stats
  577. │ └── cache/ # incremental build cache
  578. ├── cross-links/ # cross-project relationships
  579. └── sessions/ # daily session logs
  580. ```
  581. Everything is plaintext or SQLite — fully inspectable with standard tools.
  582. ## Contributing
  583. Contributions are welcome. graphmind is MIT licensed.
  584. ### Setup
  585. ```bash
  586. git clone https://github.com/aouicher/graphmind
  587. cd graphmind
  588. cargo build --release -p graphmind-cli
  589. cargo clippy --workspace -- -D warnings
  590. cargo test --workspace
  591. ```
  592. ### Branch model
  593. | Branch | Purpose |
  594. |--------|---------|
  595. | `main` | Stable, protected. Only maintainers merge here. |
  596. | `feat/<name>` | New features |
  597. | `fix/<name>` | Bug fixes |
  598. | `chore/<name>` | Tooling, deps, CI |
  599. All changes go through a pull request targeting `main`. Direct pushes to `main` are blocked.
  600. ### Opening a PR
  601. 1. Fork the repo and create a branch from `main`
  602. 2. Make your changes — keep commits atomic and descriptive
  603. 3. Run `cargo clippy --workspace -- -D warnings` and `cargo test --workspace` — both must pass
  604. 4. Open a PR against `main` with a clear description of what and why
  605. 5. One maintainer review required before merge
  606. ### Tagging and releases
  607. Releases are triggered by pushing a semver tag:
  608. ```bash
  609. git tag v0.3.0
  610. git push origin v0.3.0
  611. ```
  612. The CI will build binaries for macOS (arm64, x64) and Linux (x64), create a GitHub release, update the Homebrew formula, and publish the Tauri auto-updater manifest — all automatically.
  613. Use `-rc` suffix for pre-releases: `v0.3.0-rc1` (published as pre-release, skipped by Homebrew).
  614. ### Reporting issues
  615. Open a [GitHub issue](https://github.com/aouicher/graphmind/issues) with steps to reproduce, your OS, and the output of `graphmind status`.
  616. For security vulnerabilities, see [SECURITY.md](SECURITY.md).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.