# Graphmind

> Local-first code intelligence for AI assistants. Turns your codebase into a knowledge graph your AI can query, navigate, and remember. 25 MCP tools.

- **Type:** MCP server
- **Install:** `agentstack add mcp-aouicher-graphmind`
- **Verified:** Pending review
- **Seller:** [aouicher](https://agentstack.voostack.com/s/aouicher)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [aouicher](https://github.com/aouicher)
- **Source:** https://github.com/aouicher/graphmind
- **Website:** https://getgraphmind.com

## Install

```sh
agentstack add mcp-aouicher-graphmind
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# graphmind

[](https://github.com/aouicher/graphmind/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)

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

CLI + Claude MCP integration
Desktop app — Mac & Windows

## 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](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)

```bash
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)

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

### CLI — Linux (direct download)

```bash
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

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

## Quick Start

```bash
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 (`~/.zshenv`, `~/.zshrc`, `~/.bashrc`)
2. Claude Code hooks (rewrites grep/find, injects session context, pre-fetches on prompts)
3. Claude Code skill (`/gm` + 19 sub-skills)
4. Claude Desktop MCP (`~/Library/Application Support/Claude/claude_desktop_config.json`)
5. Claude Code MCP (`~/.claude/settings.json`)
6. OpenCode MCP (`~/.config/opencode/opencode.jsonc`)
7. Cursor global MCP (`~/.cursor/mcp.json`) — available in all Cursor projects
8. CLAUDE.md instruction block (`~/.claude/CLAUDE.md`)

### `graphmind init` (per project)

Registers and indexes a project, then writes MCP config for editors that support project-level config:
1. Registers current directory in the graphmind registry
2. MCP project configs — written automatically:
   - Claude Code: `~/.claude.json` under `projects..mcpServers` (local scope)
   - VS Code: `/.vscode/mcp.json`
3. Git hooks (auto-rebuild on commit, impact check on push)
4. Builds the code graph

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

Both commands are idempotent — safe to re-run.

### Manual setup (if you prefer granular control)

Click to expand

#### MCP server for Claude Code (global)

```bash
claude mcp add graphmind -- graphmind mcp
```

Or manually in `~/.claude/settings.json`:
```json
{
  "mcpServers": {
    "graphmind": {
      "command": "/home/user/.graphmind/bin/graphmind",
      "args": ["mcp"],
      "env": { "PATH": "/home/user/.graphmind/bin:/usr/local/bin:/usr/bin:/bin" }
    }
  }
}
```

#### MCP server for Claude Code (per project)

`graphmind init` writes this automatically to `~/.claude.json`:
```json
{
  "projects": {
    "/absolute/path/to/project": {
      "mcpServers": {
        "graphmind": {
          "type": "stdio",
          "command": "/home/user/.graphmind/bin/graphmind",
          "args": ["mcp"],
          "env": { "PATH": "/home/user/.graphmind/bin:/usr/local/bin:/usr/bin:/bin" }
        }
      }
    }
  }
}
```

#### MCP server for Claude Desktop

Claude Desktop does not inherit your shell PATH. Use the full path:

```json
{
  "mcpServers": {
    "graphmind": {
      "command": "/opt/homebrew/bin/graphmind",
      "args": ["mcp"],
      "env": { "PATH": "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin" }
    }
  }
}
```

Config file location:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

> **Tip**: Run `which graphmind` to find the correct path on your system.

#### MCP server for Cursor (global)

`graphmind setup` writes this automatically to `~/.cursor/mcp.json`:
```json
{
  "mcpServers": {
    "graphmind": {
      "command": "/home/user/.graphmind/bin/graphmind",
      "args": ["mcp"],
      "env": { "PATH": "/home/user/.graphmind/bin:/usr/local/bin:/usr/bin:/bin" }
    }
  }
}
```

#### MCP server for VS Code (per project)

`graphmind init` writes this automatically to `/.vscode/mcp.json`:
```json
{
  "servers": {
    "graphmind": {
      "type": "stdio",
      "command": "/home/user/.graphmind/bin/graphmind",
      "args": ["mcp"],
      "env": { "PATH": "/home/user/.graphmind/bin:/usr/local/bin:/usr/bin:/bin" }
    }
  }
}
```

#### Claude Code search hook

```bash
graphmind install hook-claude
```

Registers hooks in `~/.claude/settings.json` for:
- **PreToolUse** — rewrites grep/find/rg to `graphmind search`, provides graph results for Grep/Glob/LS tools
- **SessionStart** — loads project context (stats, structure) at session start
- **UserPromptSubmit** — pre-fetches relevant graph context based on the user's prompt
- **PostToolUse** — enriches results with graph-aware suggestions

Built-in intelligence:
- **Exhaustive search bypass** — detects "find all occurrences", `grep -c`, pipes to `wc`/`sort` and lets them through
- **Cache deduplication** — identical searches within 5 minutes are skipped (0 tokens cost)
- **Pattern extraction** — extracts meaningful search terms from grep, find, fd, rg commands and Agent prompts

#### Claude Code skill

```bash
graphmind install skill
```

#### CLAUDE.md sync

```bash
graphmind sync                # updates CLAUDE.md in current project
graphmind sync --all          # updates CLAUDE.md for all registered projects
```

#### Git hooks

```bash
graphmind install hook-git
```

## Architecture

```
┌─────────────────────────────────────────────┐
│  Claude Code / MCP Client                    │
├─────────────────────────────────────────────┤
│  MCP Server (rmcp SDK, stdio) — 27 tools     │
│  gm_query · gm_fn · gm_file · gm_deps      │
│  gm_outline · gm_who_calls_chain · gm_dead  │
│  gm_export · gm_similar · gm_listeners      │
│  gm_memory_search · gm_cross_query          │
│  gm_status · gm_context · gm_diff_impact    │
├─────────────────────────────────────────────┤
│  Layer 1: Structural Graph (SQLite + FTS5)   │
│  Symbols · Edges · Call sites                │
├─────────────────────────────────────────────┤
│  Layer 2: Semantic Embeddings (SQLite)       │
│  Cosine search · Graph expansion · RRF      │
├─────────────────────────────────────────────┤
│  Layer 3: Semantic Memory (JSONL)            │
│  Decisions · Patterns · Conventions          │
├─────────────────────────────────────────────┤
│  Layer 4: Cross-Project Links (JSONL)        │
│  Shared symbols · Inferred relationships     │
├─────────────────────────────────────────────┤
│  Rust Core (tree-sitter + napi-rs)           │
│  Multi-language parsing · Symbol extraction  │
└─────────────────────────────────────────────┘
```

## Search & Embeddings

graphmind search combines three retrieval strategies into a single ranked result:

```bash
graphmind search ""          # hybrid search (FTS + semantic + graph)
graphmind search "; "       # multi-query with RRF ranking
graphmind search "" --kind function
```

### How search works

1. **FTS5** — exact text matching on symbol names, signatures, docs
2. **Semantic embeddings** — cosine similarity finds conceptually related symbols (e.g. "money transfer" → `payment_service`)
3. **Graph expansion** — top results are expanded with 1-hop callers/callees from the structural graph

Results are fused via Reciprocal Rank Fusion (RRF, k=60). Each result shows its source: `[FTS]`, `[SEM]`, `[GRAPH]`, or combinations like `[FTS+SEM+G]`.

### Embedding providers

Configured in `~/.graphmind/config.json`:

```json
{
  "embedding": {
    "mode": "voyage",
    "model": "voyage-code-3",
    "api_keys": {
      "voyage": "pa-..."
    }
  }
}
```

| Mode | Model (default) | Notes |
|------|----------------|-------|
| `local` | `nomic-embed-text-v1.5` (768d) | ONNX, no API key needed |
| `openai` | `text-embedding-3-small` (1536d) | Supports custom `openai_base_url` |
| `voyage` | `voyage-code-3` (1024d) | Code-specialized, recommended |
| `disabled` | — | No embeddings — **default for new installs** |

Embeddings are computed automatically during `graphmind build` when a provider is configured. If the model changes, the embedding index is rebuilt automatically.

OpenAI-compatible providers (Azure, proxies) can set a custom base URL:
```json
{
  "embedding": {
    "mode": "openai",
    "model": "text-embedding-3-large",
    "openai_base_url": "https://your-proxy.example.com/v1",
    "api_keys": { "openai": "sk-..." }
  }
}
```

## Persistent Memory

graphmind gives Claude persistent memory across sessions — not just code, but decisions, patterns, conventions, and context.

### How it works

Memory is **fully automatic**:
- **Auto-recall** — at each prompt, the hook searches memory for relevant context and injects it into the conversation. No action needed.
- **Auto-save** — Claude proactively saves important facts (decisions, patterns, conventions, bugs, context) without asking. You'll see a brief mention of what was saved.

This works for both **Claude Code** (via hooks) and **Claude Desktop** (via MCP instructions).

### What gets saved

| Type | Examples |
|------|----------|
| `decision` | Architecture choices, tech decisions, trade-off resolutions |
| `pattern` | Recurring approaches, solutions, code patterns |
| `convention` | Naming rules, workflow conventions, style guides |
| `bug` | Known issues, workarounds, gotchas |
| `context` | Business context, project goals, user preferences |

### Storage

Memories are stored as JSONL files in `~/.graphmind/memory/`:
- `global.jsonl` — cross-project knowledge (user preferences, team conventions)
- `.jsonl` — project-specific facts

### Manual control

```bash
graphmind memory add "" [--project ] [--global]
graphmind memory search ""
graphmind memory list
graphmind memory delete 
```

Memories persist indefinitely until explicitly deleted. They are recalled automatically — you never need to ask "do you remember X?".

## Commands

### Setup & Init
```bash
graphmind setup                   # global one-time (hooks, MCP, skill)
graphmind init [path]             # per-project (register, git hooks, build)
graphmind init --skip-build       # per-project without building
```

### Registry
```bash
graphmind register [path]     # register current dir
graphmind unregister    # remove project
graphmind list                # all projects
graphmind status              # health check
```

### Build
```bash
graphmind build [slug]        # incremental build
graphmind build --all         # all projects
graphmind build --full        # force full rebuild
graphmind build --watch       # watch mode (debounced 2s)
graphmind clean [slug]        # remove graph cache (forces full rebuild)
graphmind clean --all         # clean all projects
```

### Query
```bash
graphmind query                           # find symbol + connections
graphmind query  --file             # filter to a specific file
graphmind query  --kind function          # filter by kind
graphmind query  --limit 20 --offset 0   # paginate callers/callees
graphmind fn                              # full detail with source + callers/callees
graphmind fn  --file                # disambiguate by file
graphmind fn  --kind function             # filter by kind
graphmind fn  --limit 20 --offset 0      # paginate callers/callees
graphmind fn  --include-content           # include source code in output
graphmind fn  --no-tests                  # skip test files
graphmind deps                              # file dependency map
graphmind impact                            # transitive reverse deps
graphmind fn-impact                       # blast radius
graphmind diff-impact                             # impact of current git changes
graphmind diff-impact --staged
graphmind map [slug]                              # most-connected files
graphmind cycles [slug]                           # circular dependencies
graphmind outline                           # hierarchical symbol tree for a file
graphmind file                              # raw file content from project root
graphmind who-calls                       # transitive caller chain (BFS)
graphmind who-calls  --depth 5            # limit traversal depth
graphmind dead-code                               # symbols with no incoming edges
graphmind dead-code --kind function               # filter by kind
graphmind dead-code --limit 50                    # cap results
graphmind similar                         # structurally similar symbols
graphmind similar  --limit 10             # cap results
graphmind listeners                        # find listeners for an event name
```

### Search
```bash
graphmind search ""                        # hybrid FTS + semantic + graph
graphmind search "; "                     # multi-query
graphmind search "" --kind class
graphmind search "" --offset 10            # paginate results
graphmind search "" --include-content      # include source code in output
```

### Embeddings
```bash
graphmind embed                     # show embedding index status
graphmind embed --run               # generate embeddings for current project
graphmind embed --run --all         # generate embeddings for all projects
```

### Memory
```bash
graphmind memory add "" [--project ] [--global]
graphmind memory search ""
graphmind memory list
graphmind memory delete 
```

### Cross-Project
```bash
graphmind cross query       # search across ALL projects
graphmind cross deps          # who depends on this project
graphmind cross links               # all cross-project relationships
graphmind cross link add      # manual link
graphmind cross link infer          # auto-detect shared symbols
```

### Export
```bash
graphmind export [slug] -f dot            # Graphviz dot format
graphmind export [slug] -f

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [aouicher](https://github.com/aouicher)
- **Source:** [aouicher/graphmind](https://github.com/aouicher/graphmind)
- **License:** MIT
- **Homepage:** https://getgraphmind.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: flagged — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-aouicher-graphmind
- Seller: https://agentstack.voostack.com/s/aouicher
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.