# Engraph

> Local knowledge graph for AI agents. Hybrid search + MCP server for Obsidian vaults.

- **Type:** MCP server
- **Install:** `agentstack add mcp-devwhodevs-engraph`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [devwhodevs](https://agentstack.voostack.com/s/devwhodevs)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [devwhodevs](https://github.com/devwhodevs)
- **Source:** https://github.com/devwhodevs/engraph

## Install

```sh
agentstack add mcp-devwhodevs-engraph
```

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

## About

engraph — Vault Intelligence for AI Agents

Turn your Obsidian vault into a knowledge API. 5-lane hybrid search, MCP server, HTTP REST API, ChatGPT Actions — all local, all offline.

[](https://github.com/devwhodevs/engraph/actions/workflows/ci.yml)
[](LICENSE)
[](https://github.com/devwhodevs/engraph/releases)

engraph turns your markdown vault into a searchable knowledge graph that any AI agent can query — Claude Code via [MCP](https://modelcontextprotocol.io), ChatGPT via [Actions](https://platform.openai.com/docs/actions), or any tool via REST API. It combines semantic embeddings, full-text search, wikilink graph traversal, temporal awareness, and LLM-powered reranking into a single local binary. Same model stack as [qmd](https://github.com/tobi/qmd). No API keys, no cloud — everything runs on your machine.

  

## Why engraph?

Plain vector search treats your notes as isolated documents. But knowledge isn't flat — your notes link to each other, share tags, reference the same people and projects. engraph understands these connections.

- **5-lane hybrid search** — semantic embeddings + BM25 full-text + graph expansion + cross-encoder reranking + temporal scoring, fused via [Reciprocal Rank Fusion](https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf). An LLM orchestrator classifies queries and adapts lane weights per intent. Time-aware queries like "what happened last week" or "March 2026 notes" activate the temporal lane automatically.
- **MCP server for AI agents** — `engraph serve` exposes 25 tools (search, read, section-level editing, frontmatter mutations, vault health, context bundles, note creation, PARA migration, identity) that Claude, Cursor, or any MCP client can call directly.
- **HTTP REST API** — `engraph serve --http` adds an axum-based HTTP server alongside MCP with 26 REST endpoints, API key authentication, rate limiting, and CORS. Web-based agents and scripts can query your vault with simple `curl` calls.
- **Section-level editing** — AI agents can read, replace, prepend, or append to specific sections by heading. Full note rewriting with frontmatter preservation. Granular frontmatter mutations (set/remove fields, add/remove tags and aliases).
- **Vault health diagnostics** — detect orphan notes, broken wikilinks, stale content, and tag hygiene issues. Available as MCP tool and CLI command.
- **Obsidian CLI integration** — auto-detects running Obsidian and delegates compatible operations. Circuit breaker (Closed/Degraded/Open) ensures graceful fallback.
- **Real-time sync** — file watcher keeps the index fresh as you edit in Obsidian. No manual re-indexing needed.
- **Smart write pipeline** — AI agents can create, edit, rewrite, and delete notes with automatic tag resolution, wikilink discovery, and folder placement based on semantic similarity.
- **Fully local** — [llama.cpp](https://github.com/ggml-org/llama.cpp) inference with GGUF models (~300MB mandatory, ~1.3GB optional for intelligence). Metal GPU-accelerated on macOS (88 files indexed in 70s). No API keys, no cloud.

## What problem it solves

You have hundreds of markdown notes. You want your AI coding assistant to understand what you've written — not just search keywords, but follow the connections between notes, understand context, and write new notes that fit your vault's structure.

Existing options are either cloud-dependent (Notion AI, Mem), limited to keyword search (Obsidian's built-in), or require you to copy-paste context manually. engraph gives AI agents direct, structured access to your entire vault through a standard protocol.

## How it works

```
Your vault (markdown files)
        │
        ▼
┌─────────────────────────────────────────────┐
│              engraph index                   │
│                                             │
│  Walk → Chunk → Embed (llama.cpp) → Store   │
│                                             │
│  SQLite: files, chunks, FTS5, vectors,      │
│          edges, centroids, tags, LLM cache  │
└─────────────────────────────────────────────┘
        │
        ▼
┌─────────────────────────────────────────────┐
│              engraph serve                   │
│                                             │
│  MCP Server (stdio) + File Watcher          │
│  + HTTP REST API (--http, optional)         │
│                                             │
│  Search: Orchestrator → 4-lane retrieval    │
│          → Reranker → Two-pass RRF fusion   │
│                                             │
│  25 MCP tools + 26 REST endpoints           │
└─────────────────────────────────────────────┘
        │
        ▼
  Claude / Cursor / any MCP client / curl / web agents
```

1. **Index** — walks your vault, chunks markdown by headings, embeds with a local GGUF model via llama.cpp (Metal GPU on macOS), stores everything in SQLite with FTS5 + sqlite-vec + a wikilink graph
2. **Search** — an orchestrator classifies the query and sets lane weights, then runs up to five lanes (semantic KNN, BM25 keyword, graph expansion, cross-encoder reranking, temporal scoring), fused via RRF
3. **Serve** — starts an MCP server that AI agents connect to, with a file watcher that re-indexes changes in real time

## Quick start

**Install:**

```bash
# Homebrew (macOS)
brew install devwhodevs/tap/engraph

# Pre-built binaries (macOS arm64, Linux x86_64)
# → https://github.com/devwhodevs/engraph/releases

# From source (requires CMake for llama.cpp)
cargo install --git https://github.com/devwhodevs/engraph
```

**Index your vault:**

```bash
engraph index ~/path/to/vault
# Downloads embedding model on first run (~300MB)
# Incremental — only re-embeds changed files on subsequent runs
```

**Search:**

```bash
engraph search "how does the auth system work"
```

```
 1. [97%] 02-Areas/Development/Auth-Architecture.md > # Auth Architecture  #6e1b70
    OAuth 2.0 with PKCE for all client types. Session tokens stored in HTTP-only cookies...

 2. [95%] 01-Projects/API-Design.md > # API Design  #e3e350
    All endpoints require Bearer token authentication. Tokens are issued by the OAuth 2.0...

 3. [91%] 03-Resources/People/Sarah-Chen.md > # Sarah Chen  #4adb39
    Senior Backend Engineer. Tech lead for authentication and security systems...
```

Note how result #3 was found via **graph expansion** — Sarah's note doesn't mention "auth system" directly, but she's linked from the auth architecture doc via `[[Sarah Chen]]`.

**Claude Code** — Install the plugin (recommended):

```bash
claude plugin marketplace add devwhodevs/engraph
claude plugin install engraph@engraph
```

**Connect to Claude Code:**

Or configure MCP manually in `~/.claude/settings.json`:

```bash
{
  "mcpServers": {
    "engraph": {
      "command": "engraph",
      "args": ["serve"]
    }
  }
}
```

Now Claude can search your vault, read notes, build context bundles, and create new notes — all through structured tool calls.

**AI Agent Skills** — Install the Engraph skills using the skills CLI (recommended):

```bash
npx skills add devwhodevs/engraph
```

**Enable HTTP REST API:**

```bash
# Start MCP + HTTP server on port 3000
engraph serve --http

# Custom port and host
engraph serve --http --port 8080 --host 0.0.0.0

# Local development without API keys (127.0.0.1 only)
engraph serve --http --no-auth
```

**API key management:**

```bash
# Add a new API key (read or write permission)
engraph configure --add-api-key

# List existing keys
engraph configure --list-api-keys

# Revoke a key
engraph configure --revoke-api-key eg_abc123...
```

**Enable intelligence (optional, ~1.3GB download):**

```bash
engraph configure --enable-intelligence
# Downloads Qwen3-0.6B (orchestrator) + Qwen3-Reranker (cross-encoder)
# Adds LLM query expansion + 4th reranker lane to search
```

## Example usage

**4-lane search with intent classification:**

```bash
engraph search "how does authentication work" --explain
```
```
 1. [97%] 01-Projects/API-Design.md > # API Design  #e3e350
    All endpoints require Bearer token authentication...

Intent: Conceptual

--- Explain ---
01-Projects/API-Design.md
  RRF: 0.0387
    semantic: rank #2, raw 0.38, +0.0194
    rerank: rank #2, raw 0.01, +0.0194
02-Areas/Development/Auth-Architecture.md
  RRF: 0.0384
    semantic: rank #1, raw 0.51, +0.0197
    rerank: rank #4, raw 0.00, +0.0187
```

The orchestrator classified the query as **Conceptual** (boosting semantic lane weight). The reranker scored each result for relevance as the 4th RRF lane.

**Rich context for AI agents:**

```bash
engraph context topic "authentication" --budget 8000
```

Returns a token-budgeted context bundle: relevant notes, connected people, related projects — ready to paste into a prompt or serve via MCP.

**Person context:**

```bash
engraph context who "Sarah Chen"
```

Returns Sarah's note, all mentions across the vault, connected notes via wikilinks, and recent activity.

**Vault structure overview:**

```bash
engraph context vault-map
```

Returns folder counts, top tags, recent files — gives an AI agent orientation before it starts searching.

**Create a note via the write pipeline:**

```bash
engraph write create --content "# Meeting Notes\n\nDiscussed auth timeline with Sarah." --tags meeting,auth
```

engraph resolves tags against the registry (fuzzy matching), discovers potential wikilinks (`[[Sarah Chen]]`), suggests the best folder based on semantic similarity to existing notes, and writes atomically.

**Edit a specific section:**

```bash
engraph write edit --file "Meeting Notes" --heading "Action Items" --mode append --content "- [ ] Follow up with Sarah"
```

Targets the "Action Items" section by heading, appends content without touching the rest of the note.

**Rewrite a note (preserves frontmatter):**

```bash
engraph write rewrite --file "Meeting Notes" --content "# Meeting Notes\n\nRevised content here."
```

Replaces the entire body while keeping existing frontmatter (tags, dates, metadata) intact.

**Edit frontmatter:**

```bash
engraph write edit-frontmatter --file "Meeting Notes" --op add_tag --value "actionable"
```

Granular frontmatter mutations: `set`, `remove`, `add_tag`, `remove_tag`, `add_alias`, `remove_alias`.

**Delete a note:**

```bash
engraph write delete --file "Old Draft" --mode soft   # moves to archive
engraph write delete --file "Old Draft" --mode hard   # permanent removal
```

**Check vault health:**

```bash
engraph context health
```

Returns orphan notes (no links in or out), broken wikilinks, stale notes, and tag hygiene issues.

## HTTP REST API

`engraph serve --http` adds a full REST API alongside the MCP server, exposing the same capabilities over HTTP for web agents, scripts, and integrations.

**26 endpoints:**

| Method | Endpoint | Permission | Description |
|--------|----------|------------|-------------|
| GET | `/api/health-check` | read | Server health check |
| POST | `/api/search` | read | Hybrid search (semantic + FTS5 + graph + reranker + temporal) |
| GET | `/api/read/{file}` | read | Read full note content + metadata |
| GET | `/api/read-section` | read | Read a specific section by heading |
| GET | `/api/list` | read | List notes with optional tag/folder/created_by filters |
| GET | `/api/vault-map` | read | Vault structure overview (folders, tags, recent files) |
| GET | `/api/who/{name}` | read | Person context bundle |
| GET | `/api/project/{name}` | read | Project context bundle |
| POST | `/api/context` | read | Rich topic context with token budget |
| GET | `/api/health` | read | Vault health diagnostics |
| POST | `/api/create` | write | Create a new note |
| POST | `/api/append` | write | Append content to existing note |
| POST | `/api/edit` | write | Section-level editing (replace/prepend/append) |
| POST | `/api/rewrite` | write | Full note rewrite (preserves frontmatter) |
| POST | `/api/edit-frontmatter` | write | Granular frontmatter mutations |
| POST | `/api/move` | write | Move note to different folder |
| POST | `/api/archive` | write | Soft-delete (archive) a note |
| POST | `/api/unarchive` | write | Restore archived note |
| POST | `/api/update-metadata` | write | Update note metadata |
| POST | `/api/delete` | write | Delete note (soft or hard) |
| GET | `/api/identity` | read | User identity (L0) and current context (L1) |
| POST | `/api/setup` | write | First-time onboarding setup (detect/apply modes) |
| POST | `/api/reindex-file` | write | Re-index a single file after external edits |
| POST | `/api/migrate/preview` | write | Preview PARA migration (classify + suggest moves) |
| POST | `/api/migrate/apply` | write | Apply PARA migration (move files) |
| POST | `/api/migrate/undo` | write | Undo last PARA migration |

**Authentication:**

All requests require an API key via the `Authorization` header:

```bash
curl -H "Authorization: Bearer eg_abc123..." http://localhost:3000/api/vault-map
```

Keys have either `read` or `write` permission. Write keys can access all endpoints; read keys are restricted to read-only endpoints. Use `--no-auth` for local development without keys (127.0.0.1 only).

**curl examples:**

```bash
# Search
curl -X POST http://localhost:3000/api/search \
  -H "Authorization: Bearer eg_..." \
  -H "Content-Type: application/json" \
  -d '{"query": "authentication architecture", "top_n": 5}'

# Read a note
curl http://localhost:3000/api/read/01-Projects/API-Design.md \
  -H "Authorization: Bearer eg_..."

# Create a note
curl -X POST http://localhost:3000/api/create \
  -H "Authorization: Bearer eg_..." \
  -H "Content-Type: application/json" \
  -d '{"content": "# Meeting Notes\n\nDiscussed auth timeline.", "tags": ["meeting", "auth"]}'
```

**Rate limiting:** Configurable per-key token bucket (requests per minute). Defaults to 60 req/min. Returns `429 Too Many Requests` when exceeded.

**CORS:** Configurable allowed origins in `config.toml` under `[http]`. Defaults to allow all origins for local development.

```toml
[http]
port = 3000
host = "127.0.0.1"
cors_origins = ["http://localhost:3000", "https://myapp.example.com"]
rate_limit = 60

[[http.api_keys]]
key = "eg_..."
permission = "write"
```

## PARA Migration

`engraph migrate para` restructures your vault into the [PARA method](https://fortelabs.com/blog/para/) (Projects, Areas, Resources, Archive) using heuristic classification. The workflow is non-destructive: preview first, review the plan, then apply.

**Workflow:**

```bash
# 1. Preview — classify notes and generate a migration plan
engraph migrate para --preview
# Outputs: markdown summary + JSON plan saved to ~/.engraph/

# 2. Review the plan (edit if needed)
cat ~/.engraph/migration_preview.md

# 3. Apply — move files according to the plan
engraph migrate para --apply

# 4. Undo — reverse the last migration if something looks wrong
engraph migrate para --undo
```

**Classification signals:**

| Category | Detection signals |
|----------|-------------------|
| **Projects** | Open tasks (`- [ ]`), active/in-progress status in frontmatter, project tags |
| **Areas** | Recurring topic keywords (health, finance, career, learning), area-related tags |
| **Resources** | People notes (People folder, person-like content), reference material, articles, code snippets |
| **Archive** | Done/completed/inactive status, no incoming or outgoing wikilinks, stale content |

Notes that don't match any signal with sufficient confidence stay in place. Daily notes (`YYYY-MM-DD.md`) and templates are always skipped.

**MCP tools:** `migrate_preview`, `migrate_apply`, `migrate_undo` — available in `engraph serve` for AI-assisted migration.

**HTTP endpoints:** `POST /api/migrate/preview`, `/api/migrate/apply`, `/api/migrate/undo` — available via `engraph serve --http`.

## ChatGPT Actions

Connect your Obsidian vault to ChatGPT as a custom GPT Action. ChatGPT can search, read, create, and edit your notes through engraph's REST API.

### Prerequisites

- engraph installed and indexed (`engraph index ~/your-vault`)
- A tunnel tool: [Cloudflare

…

## Source & license

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

- **Author:** [devwhodevs](https://github.com/devwhodevs)
- **Source:** [devwhodevs/engraph](https://github.com/devwhodevs/engraph)
- **License:** MIT

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: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-devwhodevs-engraph
- Seller: https://agentstack.voostack.com/s/devwhodevs
- 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%.