Skip to content
Back to search

engraph

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

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/devwhodevs--engraph/badge.svg)](/listings/devwhodevs--engraph)

HTML

<a href="/listings/devwhodevs--engraph"><img src="/api/listings/devwhodevs--engraph/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.

**Install:**

# 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:**

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

**Search:**

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

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

**Connect to Claude Code:**

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

{
  "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):

npx skills add devwhodevs/engraph

**Enable HTTP REST API:**

# 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:**

# 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):**

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

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.

.claude-plugin/marketplace.json · Manifest · 35 lines

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

  1. {
  2. "name": "engraph",
  3. "owner": {
  4. "name": "devwhodevs",
  5. "email": "devwhodevs@gmail.com"
  6. },
  7. "plugins": [
  8. {
  9. "name": "engraph",
  10. "source": "./",
  11. "description": "Turn your Markdown vault into a searchable knowledge graph that any AI agent can query.",
  12. "version": "1.0.0",
  13. "author": {
  14. "name": "devwhodevs",
  15. "email": "devwhodevs@gmail.com"
  16. },
  17. "repository": "https://github.com/devwhodevs/engraph",
  18. "license": "MIT",
  19. "keywords": [
  20. "markdown",
  21. "search",
  22. "engraph",
  23. "graph search",
  24. "knowledge graph"
  25. ],
  26. "skills": ["./skills/"],
  27. "mcpServers": {
  28. "engraph": {
  29. "command": "engraph",
  30. "args": ["serve"]
  31. }
  32. }
  33. }
  34. ]
  35. }
README.md · README · 642 lines

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

  1. <p align="center">
  2. <img src="assets/logo.png" alt="engraph logo" width="180">
  3. </p>
  4. <h1 align="center">engraph — Vault Intelligence for AI Agents</h1>
  5. <p align="center"><strong>Turn your Obsidian vault into a knowledge API.</strong> 5-lane hybrid search, MCP server, HTTP REST API, ChatGPT Actions — all local, all offline.</p>
  6. [![CI](https://github.com/devwhodevs/engraph/actions/workflows/ci.yml/badge.svg)](https://github.com/devwhodevs/engraph/actions/workflows/ci.yml)
  7. [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
  8. [![GitHub release](https://img.shields.io/github/v/release/devwhodevs/engraph)](https://github.com/devwhodevs/engraph/releases)
  9. 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.
  10. <p align="center">
  11. <img src="assets/demo.gif" alt="engraph demo: 4-lane hybrid search with LLM intelligence, person context bundles, Metal GPU" width="800">
  12. </p>
  13. ## Why engraph?
  14. 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.
  15. - **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.
  16. - **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.
  17. - **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.
  18. - **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).
  19. - **Vault health diagnostics** — detect orphan notes, broken wikilinks, stale content, and tag hygiene issues. Available as MCP tool and CLI command.
  20. - **Obsidian CLI integration** — auto-detects running Obsidian and delegates compatible operations. Circuit breaker (Closed/Degraded/Open) ensures graceful fallback.
  21. - **Real-time sync** — file watcher keeps the index fresh as you edit in Obsidian. No manual re-indexing needed.
  22. - **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.
  23. - **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.
  24. ## What problem it solves
  25. 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.
  26. 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.
  27. ## How it works
  28. ```
  29. Your vault (markdown files)
  30. │
  31. ▼
  32. ┌─────────────────────────────────────────────┐
  33. │ engraph index │
  34. │ │
  35. │ Walk → Chunk → Embed (llama.cpp) → Store │
  36. │ │
  37. │ SQLite: files, chunks, FTS5, vectors, │
  38. │ edges, centroids, tags, LLM cache │
  39. └─────────────────────────────────────────────┘
  40. │
  41. ▼
  42. ┌─────────────────────────────────────────────┐
  43. │ engraph serve │
  44. │ │
  45. │ MCP Server (stdio) + File Watcher │
  46. │ + HTTP REST API (--http, optional) │
  47. │ │
  48. │ Search: Orchestrator → 4-lane retrieval │
  49. │ → Reranker → Two-pass RRF fusion │
  50. │ │
  51. │ 25 MCP tools + 26 REST endpoints │
  52. └─────────────────────────────────────────────┘
  53. │
  54. ▼
  55. Claude / Cursor / any MCP client / curl / web agents
  56. ```
  57. 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
  58. 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
  59. 3. **Serve** — starts an MCP server that AI agents connect to, with a file watcher that re-indexes changes in real time
  60. ## Quick start
  61. **Install:**
  62. ```bash
  63. # Homebrew (macOS)
  64. brew install devwhodevs/tap/engraph
  65. # Pre-built binaries (macOS arm64, Linux x86_64)
  66. # → https://github.com/devwhodevs/engraph/releases
  67. # From source (requires CMake for llama.cpp)
  68. cargo install --git https://github.com/devwhodevs/engraph
  69. ```
  70. **Index your vault:**
  71. ```bash
  72. engraph index ~/path/to/vault
  73. # Downloads embedding model on first run (~300MB)
  74. # Incremental — only re-embeds changed files on subsequent runs
  75. ```
  76. **Search:**
  77. ```bash
  78. engraph search "how does the auth system work"
  79. ```
  80. ```
  81. 1. [97%] 02-Areas/Development/Auth-Architecture.md > # Auth Architecture #6e1b70
  82. OAuth 2.0 with PKCE for all client types. Session tokens stored in HTTP-only cookies...
  83. 2. [95%] 01-Projects/API-Design.md > # API Design #e3e350
  84. All endpoints require Bearer token authentication. Tokens are issued by the OAuth 2.0...
  85. 3. [91%] 03-Resources/People/Sarah-Chen.md > # Sarah Chen #4adb39
  86. Senior Backend Engineer. Tech lead for authentication and security systems...
  87. ```
  88. 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]]`.
  89. **Claude Code** — Install the plugin (recommended):
  90. ```bash
  91. claude plugin marketplace add devwhodevs/engraph
  92. claude plugin install engraph@engraph
  93. ```
  94. **Connect to Claude Code:**
  95. Or configure MCP manually in `~/.claude/settings.json`:
  96. ```bash
  97. {
  98. "mcpServers": {
  99. "engraph": {
  100. "command": "engraph",
  101. "args": ["serve"]
  102. }
  103. }
  104. }
  105. ```
  106. Now Claude can search your vault, read notes, build context bundles, and create new notes — all through structured tool calls.
  107. **AI Agent Skills** — Install the Engraph skills using the skills CLI (recommended):
  108. ```bash
  109. npx skills add devwhodevs/engraph
  110. ```
  111. **Enable HTTP REST API:**
  112. ```bash
  113. # Start MCP + HTTP server on port 3000
  114. engraph serve --http
  115. # Custom port and host
  116. engraph serve --http --port 8080 --host 0.0.0.0
  117. # Local development without API keys (127.0.0.1 only)
  118. engraph serve --http --no-auth
  119. ```
  120. **API key management:**
  121. ```bash
  122. # Add a new API key (read or write permission)
  123. engraph configure --add-api-key
  124. # List existing keys
  125. engraph configure --list-api-keys
  126. # Revoke a key
  127. engraph configure --revoke-api-key eg_abc123...
  128. ```
  129. **Enable intelligence (optional, ~1.3GB download):**
  130. ```bash
  131. engraph configure --enable-intelligence
  132. # Downloads Qwen3-0.6B (orchestrator) + Qwen3-Reranker (cross-encoder)
  133. # Adds LLM query expansion + 4th reranker lane to search
  134. ```
  135. ## Example usage
  136. **4-lane search with intent classification:**
  137. ```bash
  138. engraph search "how does authentication work" --explain
  139. ```
  140. ```
  141. 1. [97%] 01-Projects/API-Design.md > # API Design #e3e350
  142. All endpoints require Bearer token authentication...
  143. Intent: Conceptual
  144. --- Explain ---
  145. 01-Projects/API-Design.md
  146. RRF: 0.0387
  147. semantic: rank #2, raw 0.38, +0.0194
  148. rerank: rank #2, raw 0.01, +0.0194
  149. 02-Areas/Development/Auth-Architecture.md
  150. RRF: 0.0384
  151. semantic: rank #1, raw 0.51, +0.0197
  152. rerank: rank #4, raw 0.00, +0.0187
  153. ```
  154. The orchestrator classified the query as **Conceptual** (boosting semantic lane weight). The reranker scored each result for relevance as the 4th RRF lane.
  155. **Rich context for AI agents:**
  156. ```bash
  157. engraph context topic "authentication" --budget 8000
  158. ```
  159. Returns a token-budgeted context bundle: relevant notes, connected people, related projects — ready to paste into a prompt or serve via MCP.
  160. **Person context:**
  161. ```bash
  162. engraph context who "Sarah Chen"
  163. ```
  164. Returns Sarah's note, all mentions across the vault, connected notes via wikilinks, and recent activity.
  165. **Vault structure overview:**
  166. ```bash
  167. engraph context vault-map
  168. ```
  169. Returns folder counts, top tags, recent files — gives an AI agent orientation before it starts searching.
  170. **Create a note via the write pipeline:**
  171. ```bash
  172. engraph write create --content "# Meeting Notes\n\nDiscussed auth timeline with Sarah." --tags meeting,auth
  173. ```
  174. 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.
  175. **Edit a specific section:**
  176. ```bash
  177. engraph write edit --file "Meeting Notes" --heading "Action Items" --mode append --content "- [ ] Follow up with Sarah"
  178. ```
  179. Targets the "Action Items" section by heading, appends content without touching the rest of the note.
  180. **Rewrite a note (preserves frontmatter):**
  181. ```bash
  182. engraph write rewrite --file "Meeting Notes" --content "# Meeting Notes\n\nRevised content here."
  183. ```
  184. Replaces the entire body while keeping existing frontmatter (tags, dates, metadata) intact.
  185. **Edit frontmatter:**
  186. ```bash
  187. engraph write edit-frontmatter --file "Meeting Notes" --op add_tag --value "actionable"
  188. ```
  189. Granular frontmatter mutations: `set`, `remove`, `add_tag`, `remove_tag`, `add_alias`, `remove_alias`.
  190. **Delete a note:**
  191. ```bash
  192. engraph write delete --file "Old Draft" --mode soft # moves to archive
  193. engraph write delete --file "Old Draft" --mode hard # permanent removal
  194. ```
  195. **Check vault health:**
  196. ```bash
  197. engraph context health
  198. ```
  199. Returns orphan notes (no links in or out), broken wikilinks, stale notes, and tag hygiene issues.
  200. ## HTTP REST API
  201. `engraph serve --http` adds a full REST API alongside the MCP server, exposing the same capabilities over HTTP for web agents, scripts, and integrations.
  202. **26 endpoints:**
  203. | Method | Endpoint | Permission | Description |
  204. |--------|----------|------------|-------------|
  205. | GET | `/api/health-check` | read | Server health check |
  206. | POST | `/api/search` | read | Hybrid search (semantic + FTS5 + graph + reranker + temporal) |
  207. | GET | `/api/read/{file}` | read | Read full note content + metadata |
  208. | GET | `/api/read-section` | read | Read a specific section by heading |
  209. | GET | `/api/list` | read | List notes with optional tag/folder/created_by filters |
  210. | GET | `/api/vault-map` | read | Vault structure overview (folders, tags, recent files) |
  211. | GET | `/api/who/{name}` | read | Person context bundle |
  212. | GET | `/api/project/{name}` | read | Project context bundle |
  213. | POST | `/api/context` | read | Rich topic context with token budget |
  214. | GET | `/api/health` | read | Vault health diagnostics |
  215. | POST | `/api/create` | write | Create a new note |
  216. | POST | `/api/append` | write | Append content to existing note |
  217. | POST | `/api/edit` | write | Section-level editing (replace/prepend/append) |
  218. | POST | `/api/rewrite` | write | Full note rewrite (preserves frontmatter) |
  219. | POST | `/api/edit-frontmatter` | write | Granular frontmatter mutations |
  220. | POST | `/api/move` | write | Move note to different folder |
  221. | POST | `/api/archive` | write | Soft-delete (archive) a note |
  222. | POST | `/api/unarchive` | write | Restore archived note |
  223. | POST | `/api/update-metadata` | write | Update note metadata |
  224. | POST | `/api/delete` | write | Delete note (soft or hard) |
  225. | GET | `/api/identity` | read | User identity (L0) and current context (L1) |
  226. | POST | `/api/setup` | write | First-time onboarding setup (detect/apply modes) |
  227. | POST | `/api/reindex-file` | write | Re-index a single file after external edits |
  228. | POST | `/api/migrate/preview` | write | Preview PARA migration (classify + suggest moves) |
  229. | POST | `/api/migrate/apply` | write | Apply PARA migration (move files) |
  230. | POST | `/api/migrate/undo` | write | Undo last PARA migration |
  231. **Authentication:**
  232. All requests require an API key via the `Authorization` header:
  233. ```bash
  234. curl -H "Authorization: Bearer eg_abc123..." http://localhost:3000/api/vault-map
  235. ```
  236. 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).
  237. **curl examples:**
  238. ```bash
  239. # Search
  240. curl -X POST http://localhost:3000/api/search \
  241. -H "Authorization: Bearer eg_..." \
  242. -H "Content-Type: application/json" \
  243. -d '{"query": "authentication architecture", "top_n": 5}'
  244. # Read a note
  245. curl http://localhost:3000/api/read/01-Projects/API-Design.md \
  246. -H "Authorization: Bearer eg_..."
  247. # Create a note
  248. curl -X POST http://localhost:3000/api/create \
  249. -H "Authorization: Bearer eg_..." \
  250. -H "Content-Type: application/json" \
  251. -d '{"content": "# Meeting Notes\n\nDiscussed auth timeline.", "tags": ["meeting", "auth"]}'
  252. ```
  253. **Rate limiting:** Configurable per-key token bucket (requests per minute). Defaults to 60 req/min. Returns `429 Too Many Requests` when exceeded.
  254. **CORS:** Configurable allowed origins in `config.toml` under `[http]`. Defaults to allow all origins for local development.
  255. ```toml
  256. [http]
  257. port = 3000
  258. host = "127.0.0.1"
  259. cors_origins = ["http://localhost:3000", "https://myapp.example.com"]
  260. rate_limit = 60
  261. [[http.api_keys]]
  262. key = "eg_..."
  263. permission = "write"
  264. ```
  265. ## PARA Migration
  266. `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.
  267. **Workflow:**
  268. ```bash
  269. # 1. Preview — classify notes and generate a migration plan
  270. engraph migrate para --preview
  271. # Outputs: markdown summary + JSON plan saved to ~/.engraph/
  272. # 2. Review the plan (edit if needed)
  273. cat ~/.engraph/migration_preview.md
  274. # 3. Apply — move files according to the plan
  275. engraph migrate para --apply
  276. # 4. Undo — reverse the last migration if something looks wrong
  277. engraph migrate para --undo
  278. ```
  279. **Classification signals:**
  280. | Category | Detection signals |
  281. |----------|-------------------|
  282. | **Projects** | Open tasks (`- [ ]`), active/in-progress status in frontmatter, project tags |
  283. | **Areas** | Recurring topic keywords (health, finance, career, learning), area-related tags |
  284. | **Resources** | People notes (People folder, person-like content), reference material, articles, code snippets |
  285. | **Archive** | Done/completed/inactive status, no incoming or outgoing wikilinks, stale content |
  286. Notes that don't match any signal with sufficient confidence stay in place. Daily notes (`YYYY-MM-DD.md`) and templates are always skipped.
  287. **MCP tools:** `migrate_preview`, `migrate_apply`, `migrate_undo` — available in `engraph serve` for AI-assisted migration.
  288. **HTTP endpoints:** `POST /api/migrate/preview`, `/api/migrate/apply`, `/api/migrate/undo` — available via `engraph serve --http`.
  289. ## ChatGPT Actions
  290. 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.
  291. ### Prerequisites
  292. - engraph installed and indexed (`engraph index ~/your-vault`)
  293. - A tunnel tool: [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-local-tunnel/) (recommended) or [ngrok](https://ngrok.com)
  294. ### Step 1: Configure engraph
  295. ```bash
  296. # Interactive setup — enables HTTP, creates API key, sets CORS
  297. engraph configure --setup-chatgpt
  298. ```
  299. Or configure manually in `~/.engraph/config.toml`:
  300. ```toml
  301. [http]
  302. enabled = true
  303. port = 3000
  304. host = "127.0.0.1"
  305. rate_limit = 60
  306. cors_origins = ["https://chat.openai.com", "https://chatgpt.com"]
  307. [[http.api_keys]]
  308. key = "eg_your_key_here" # generate with: engraph configure --add-api-key --key-name chatgpt --key-permissions write
  309. name = "chatgpt"
  310. permissions = "write" # "read" for search-only, "write" to also create/edit notes
  311. [http.plugin]
  312. name = "My Vault"
  313. description = "Search and manage my Obsidian vault"
  314. public_url = "https://your-tunnel-url.trycloudflare.com" # set after starting tunnel
  315. ```
  316. ### Step 2: Start engraph + tunnel
  317. **Terminal 1 — engraph HTTP server:**
  318. ```bash
  319. engraph serve --http
  320. ```
  321. **Terminal 2 — Cloudflare tunnel:**
  322. ```bash
  323. cloudflared tunnel --url http://localhost:3000
  324. # Prints a URL like: https://abc-xyz.trycloudflare.com
  325. ```
  326. Or with ngrok:
  327. ```bash
  328. ngrok http 3000
  329. # Prints a URL like: https://abc123.ngrok-free.app
  330. ```
  331. ### Step 3: Update config with tunnel URL
  332. Edit `~/.engraph/config.toml` and set `public_url` to your tunnel URL:
  333. ```toml
  334. [http.plugin]
  335. public_url = "https://abc-xyz.trycloudflare.com"
  336. ```
  337. Then restart engraph (`Ctrl+C` and re-run `engraph serve --http`). This ensures the OpenAPI spec points to the correct public URL.
  338. ### Step 4: Verify endpoints
  339. ```bash
  340. # Both should return JSON (no auth required)
  341. curl https://your-tunnel-url/openapi.json
  342. curl https://your-tunnel-url/.well-known/ai-plugin.json
  343. # Search with auth
  344. curl -X POST -H "Authorization: Bearer eg_your_key" \
  345. -H "Content-Type: application/json" \
  346. -d '{"query": "test search"}' \
  347. https://your-tunnel-url/api/search
  348. ```
  349. ### Step 5: Register in ChatGPT
  350. 1. Go to [ChatGPT](https://chat.openai.com) → **Explore GPTs** → **Create**
  351. 2. Give your GPT a name (e.g., "Vault Assistant")
  352. 3. Add these **Instructions**:
  353. ```
  354. You are a knowledge assistant connected to the user's Obsidian vault via engraph.
  355. WORKFLOW:
  356. 1. Use searchVault to find relevant notes before answering questions
  357. 2. Use readNote for full content, readSection for specific headings
  358. 3. Use getWho for people context, getProject for project context
  359. 4. Use getVaultMap to orient yourself in the vault structure
  360. 5. Only create or edit notes when explicitly asked
  361. SEARCH TIPS:
  362. - Temporal queries ("last week", "yesterday") activate time-aware search automatically
  363. - Results include confidence % — prefer higher confidence matches
  364. - Fuzzy matching works: typos in names are handled
  365. STYLE:
  366. - Reference vault notes by name when answering
  367. - Quote relevant snippets
  368. - If information isn't in the vault, say so clearly
  369. - Be concise
  370. ```
  371. 4. Click **Add Action** → **Import from URL**
  372. 5. Enter: `https://your-tunnel-url/openapi.json`
  373. 6. Click the **gear icon** next to Authentication
  374. 7. Select **API Key**, Auth Type: **Bearer**
  375. 8. Paste your API key (the `eg_...` key from Step 1)
  376. 9. **Save** and test
  377. ### Conversation starters
  378. - "What happened in my vault last week?"
  379. - "Summarize my current work projects"
  380. - "Find notes related to [topic]"
  381. - "Create a note about today's meeting with [person]"
  382. ### Notes
  383. - **Tunnel URLs are temporary** (Cloudflare quick tunnels change on restart). For persistent URLs, set up a [named Cloudflare tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/get-started/create-local-tunnel/) or use ngrok with a reserved domain.
  384. - **Read-only mode**: set `permissions = "read"` on the API key if you don't want ChatGPT to create or modify notes.
  385. - **Rate limiting**: default is 60 requests/minute per key. Adjust `rate_limit` in config if needed.
  386. - **engraph must be running** on your machine for ChatGPT to access it. If you close the terminal, the connection drops.
  387. ## Use cases
  388. **AI-assisted knowledge work** — Give Claude or Cursor deep access to your personal knowledge base. Instead of copy-pasting context, the agent searches, reads, and cross-references your notes directly.
  389. **Developer second brain** — Index architecture docs, decision records, meeting notes, and code snippets. Search by concept across all of them.
  390. **Research and writing** — Find connections between notes that you didn't explicitly link. The graph lane surfaces related content through shared wikilinks and mentions.
  391. **Team knowledge graphs** — Index a shared docs vault. AI agents can answer "who knows about X?" and "what decisions were made about Y?" by traversing the note graph.
  392. ## How it compares
  393. | | engraph | Basic RAG (vector-only) | Obsidian search |
  394. |---|---|---|---|
  395. | Search method | 5-lane RRF (semantic + BM25 + graph + reranker + temporal) | Vector similarity only | Keyword only |
  396. | Query understanding | LLM orchestrator classifies intent, adapts weights | None | None |
  397. | Understands note links | Yes (wikilink graph traversal) | No | Limited (backlinks panel) |
  398. | AI agent access | MCP server (25 tools) + HTTP REST API (26 endpoints) | Custom API needed | No |
  399. | Write capability | Create/edit/rewrite/delete with smart filing | No | Manual |
  400. | Vault health | Orphans, broken links, stale notes, tag hygiene | No | Limited |
  401. | Real-time sync | File watcher, 2s debounce | Manual re-index | N/A |
  402. | Runs locally | Yes, llama.cpp + Metal GPU | Depends | Yes |
  403. | Setup | One binary, one command | Framework + code | Built-in |
  404. engraph is not a replacement for Obsidian — it's the intelligence layer that sits between your vault and your AI tools.
  405. ## Current capabilities
  406. - 5-lane hybrid search (semantic + FTS5 + graph + cross-encoder reranker + temporal) with two-pass RRF fusion
  407. - Temporal search: natural language date queries ("last week", "March 2026", "recent"), date extraction from frontmatter and filenames, smooth decay scoring
  408. - Confidence % display: search results show normalized 0-100% confidence instead of raw RRF scores
  409. - LLM research orchestrator: query intent classification + query expansion + adaptive lane weights
  410. - llama.cpp inference via Rust bindings (GGUF models, Metal GPU on macOS, CUDA on Linux)
  411. - Intelligence opt-in: heuristic fallback when disabled, LLM-powered when enabled
  412. - MCP server with 25 tools (8 read, 10 write, 2 identity, 1 index, 1 diagnostic, 3 migrate) via stdio
  413. - HTTP REST API with 26 endpoints, API key auth (`eg_` prefix), rate limiting, CORS — enabled via `engraph serve --http`
  414. - User identity with L0/L1 tiered context for AI agent session starts
  415. - Section-level reading and editing: target specific headings with replace/prepend/append modes
  416. - Full note rewriting with automatic frontmatter preservation
  417. - Granular frontmatter mutations: set/remove fields, add/remove tags and aliases
  418. - Soft delete (archive) and hard delete (permanent) with audit logging
  419. - Vault health diagnostics: orphan notes, broken wikilinks, stale content, tag hygiene
  420. - Obsidian CLI integration with circuit breaker (Closed/Degraded/Open) for resilient delegation
  421. - Real-time file watching with 2s debounce, startup reconciliation, and watcher coordination to prevent double re-indexing
  422. - Write pipeline: tag resolution, fuzzy link discovery, semantic folder placement
  423. - Context engine: topic bundles, person bundles, project bundles with token budgets
  424. - Vault graph: bidirectional wikilink + mention edges with multi-hop expansion
  425. - Placement correction learning from user file moves
  426. - Enhanced file resolution with fuzzy Levenshtein matching fallback
  427. - Content-based folder role detection (people, daily, archive) by content patterns
  428. - PARA migration: AI-assisted vault restructuring into Projects/Areas/Resources/Archive with preview, apply, and undo workflow
  429. - Configurable model overrides for multilingual support
  430. - 426 unit tests, CI on macOS + Ubuntu
  431. ## Roadmap
  432. - [x] ~~Research orchestrator — query classification and adaptive lane weighting~~ (v1.0)
  433. - [x] ~~LLM reranker — optional local model for result quality~~ (v1.0)
  434. - [x] ~~MCP edit/rewrite tools — full note editing for AI agents~~ (v1.1)
  435. - [x] ~~Vault health monitor — orphan notes, broken links, stale content, tag hygiene~~ (v1.1)
  436. - [x] ~~Obsidian CLI integration — auto-detect and delegate with circuit breaker~~ (v1.1)
  437. - [x] ~~Temporal search — find notes by time period, date-aware queries~~ (v1.2)
  438. - [x] ~~HTTP/REST API — complement MCP with a standard web API~~ (v1.3)
  439. - [x] ~~PARA migration — AI-assisted vault restructuring with preview/apply/undo~~ (v1.4)
  440. - [x] ~~ChatGPT Actions — OpenAPI 3.1.0 spec + plugin manifest + `--setup-chatgpt` helper~~ (v1.5)
  441. - [x] ~~Identity — user context at session start, enhanced onboarding~~ (v1.6)
  442. - [ ] Timeline — temporal knowledge graph with point-in-time queries (v1.7)
  443. - [ ] Mining — automatic fact extraction from vault notes (v1.8)
  444. ## Configuration
  445. Optional config at `~/.engraph/config.toml`:
  446. ```toml
  447. vault_path = "~/Documents/MyVault"
  448. top_n = 10
  449. exclude = [".obsidian/", "node_modules/", ".git/"]
  450. # Enable LLM-powered intelligence (query expansion + reranking)
  451. intelligence = true
  452. # Override models for multilingual or custom use
  453. [models]
  454. # embed = "hf:Qwen/Qwen3-Embedding-0.6B-GGUF/qwen3-embedding-0.6b-q8_0.gguf"
  455. # rerank = "hf:ggml-org/Qwen3-Reranker-0.6B-Q8_0-GGUF/qwen3-reranker-0.6b-q8_0.gguf"
  456. # Obsidian CLI integration (auto-detected during init)
  457. [obsidian]
  458. # enabled = true
  459. # cli_path = "/usr/local/bin/obsidian"
  460. # Registered AI agents
  461. [agents]
  462. # names = ["claude-code", "cursor"]
  463. ```
  464. All data stored in `~/.engraph/` — single SQLite database (~10MB typical), GGUF models, and vault profile.
  465. ## Development
  466. ```bash
  467. cargo test --lib # 426 unit tests, no network (requires CMake for llama.cpp)
  468. cargo clippy -- -D warnings
  469. cargo fmt --check
  470. # Integration tests (downloads GGUF model)
  471. cargo test --test integration -- --ignored
  472. ```
  473. ## Contributing
  474. Contributions welcome. Please open an issue first to discuss what you'd like to change.
  475. The codebase is 26 Rust modules behind a lib crate. `CLAUDE.md` in the repo root has detailed architecture documentation for AI-assisted development.
  476. ## License
  477. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

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