Grove

What is Grove about?

Grove offers a personal, self‑hosted MCP layer over a Git‑backed Obsidian vault. It exposes six core tools (query, get, multi_get, write_note, list_notes, vault_status) via a streamable HTTP endpoint, enabling AI clients such as Claude, ChatGPT, or Cursor to read, search, and write markdown notes while preserving full version history.

How to use Grove?

1. Prerequisites – Install Node ≥ 22 and have a Git‑tracked Obsidian vault on disk.
2. Clone and install

   git clone https://github.com/jmilinovich/grove.git
   cd grove
   npm install
   

3. Set environment variables

   export GROVE_VAULT=/path/to/your/vault
   export GROVE_API_KEY=$(openssl rand -hex 32)   # bearer token for clients
   export VOYAGE_API_KEY=YOUR_VOYAGE_KEY          # embeddings on write
   

4. Start the server

   npx tsx src/server.ts
   

   The server listens on http://127.0.0.1:8420/mcp. Point any MCP‑compatible client at that URL and include Authorization: Bearer <GROVE_API_KEY>.
5. Optional – Run the discovery worker for automatic wikilink generation:

   GROVE_VAULT=/path/to/vault ANTHROPIC_API_KEY=YOUR_KEY npx tsx src/discovery-worker.ts
   

Key Features of Grove

• Hybrid search: BM25 + vector retrieval with Reciprocal Rank Fusion, powered by a QMD index.
• Git‑backed writes: Every create, update, move, or delete results in a Git commit, preserving full provenance.
• Provenance & blame: Commits can carry durable/perishable trailers; the get tool surfaces segment‑level authorship.
• Write queue: Serializes all Git operations to avoid race conditions.
• Discovery worker: Extracts entities from new notes and auto‑creates wikilinks.
• Vault diagnostics: vault_status returns health metrics, graph clusters, lifecycle digest, and performance counters.
• Minimal dependencies: Pure Node http server, TypeScript strict mode, no heavyweight frameworks.

Use Cases of Grove

• Personal knowledge base augmentation – Enable LLMs to retrieve and update your Obsidian notes in real time.
• AI‑assisted writing – Ask an AI to draft a note; the server writes it as a Git commit with attribution.
• Contextual search for agents – Hybrid BM25‑vector search gives agents precise, relevant snippets.
• Provenance‑aware collaboration – Distinguish human edits from AI‑generated content via commit trailers.
• Automatic linking – Discovery worker enriches notes with wikilinks without manual effort.

FAQ

Q: Do I need a remote Git host? A: No. The vault is a local Git repository; all commits stay on your machine.

Q: Can I run Grove without authentication? A: Yes, set GROVE_AUTH=none and bind the server to localhost only.

Q: What embeddings does Grove use? A: Voyage AI (voyage-4-large) is used for on‑write embeddings; an API key is required.

Q: How is the discovery worker started? A: It’s a separate process invoked with the same GROVE_VAULT and an Anthropic API key for the extract‑to‑link engine.

Q: Which clients are compatible? A: Any client that implements the Model Context Protocol (MCP), such as Claude, ChatGPT, Cursor, or custom MCP SDKs.

Q: Where are state files stored? A: Discovery queue, provenance cache, and blame data reside in ~/.grove/state.db by default.

Grove

Open-source MCP server that makes your Obsidian vault searchable and writable from any AI client.

Six tools, one git-backed vault, single-user. Claude, ChatGPT, Cursor, or any MCP-compatible client connects and gets structured access — search, read, write-back, graph diagnostics. Your vault stays yours: markdown files in a git repo, versioned forever.

┌─────────────────────────────────────────────────────────┐
│              MCP client (Claude / Cursor / …)            │
└──────────────────────┬──────────────────────────────────┘
                       │ MCP — Streamable HTTP + Bearer
                       ▼
┌─────────────────────────────────────────────────────────┐
│                       grove-server                       │
│   6 tools · write queue · provenance · discovery        │
└──────────────────────┬──────────────────────────────────┘
                       │
            ┌──────────┼──────────┐
            ▼          ▼          ▼
        Hybrid      Vault       Discovery
        Search      (git)        worker
      BM25+Vec               (extract → link)

About this repo. Grove was a hosted product 2026-04 → 2026-05. The repo you're looking at is the open-source cathedral that came out of it: a personal MCP layer over an Obsidian vault, single-user, self-host. The multi-tenant SaaS layer, autonomous-agent layer, encryption, trails, waitlist, and admin portal have all been stripped. See RETROSPECTIVE.md for the full history.

---

The six tools

Tool	What it does
query	Hybrid BM25 + vector + title search with RRF fusion. Returns ranked snippets with URLs.
get	Read a note by path or title. Surfaces per-segment provenance (durable vs perishable voice).
multi_get	Batch read via glob or comma-separated paths.
write_note	Create / update / soft-delete / hard-delete / move a note. Single op or batch (atomic optional).
list_notes	List notes matching a pattern. Optional alias resolution.
vault_status	Health, history, diagnostics, graph, lifecycle digest, discovery state, perf counters.

Every write is a git commit. Every commit can carry provenance trailers that the read path surfaces via blame so future readers know what's the user's standing thinking vs an AI's moment-in-time synthesis.

---

Quick start

You need:

• Node ≥ 22
• A git-backed Obsidian-style markdown vault on disk
• A QMD index for the vault (Grove reads BM25 + vector hits from it)
• A Voyage AI API key for per-write embeddings (voyage-4-large)

git clone https://github.com/jmilinovich/grove.git
cd grove
npm install

Set the env vars:

export GROVE_VAULT=/path/to/your/vault       # absolute path to the git repo
export GROVE_API_KEY=$(openssl rand -hex 32) # your bearer token — keep secret
export VOYAGE_API_KEY=...                    # Voyage AI key for embeddings

Then start the server:

npx tsx src/server.ts

It listens on http://127.0.0.1:8420/mcp. Point any MCP client at that URL with Authorization: Bearer <GROVE_API_KEY>.

Local-only without a token

For purely local development you can disable auth:

GROVE_AUTH=none GROVE_VAULT=/path/to/vault npx tsx src/server.ts

Only do this when the listener is bound to localhost.

---

Discovery worker (optional)

The discovery worker runs in the background and auto-wikilinks new notes by extracting entities from each write. It's a separate process:

GROVE_VAULT=/path/to/vault \
ANTHROPIC_API_KEY=... \
npx tsx src/discovery-worker.ts

If you don't run it, writes still work — they just don't get auto-linked. The discovery queue + cache live in ~/.grove/state.db and will resume when the worker comes back.

---

Env reference

Var	Required?	Default	Purpose
GROVE_VAULT	yes	$HOME/life	Absolute path to the vault git repo
GROVE_API_KEY	yes (unless GROVE_AUTH=none)	empty	Bearer token clients must send
GROVE_AUTH	no	bearer	Set to none to disable auth (localhost only)
GROVE_PORT	no	8420	HTTP listen port
GROVE_STATE_DB	no	~/.grove/state.db	SQLite state file (discovery queue, provenance, blame cache)
GROVE_PUBLIC_BASE_URL	no	grove://vault	Prefix used when minting URLs returned by tool calls
VOYAGE_API_KEY	for embed-on-write	—	Voyage AI key
ANTHROPIC_API_KEY	for the discovery worker	—	Anthropic key for the extract→link engine
GROVE_INTERNAL_TOKEN	optional	—	Bearer for the /internal/post-sync-warmup cron hook

---

What's in the box

src/
├── server.ts          # MCP HTTP server, the 6 tools, bearer-auth gate
├── rest.ts            # write / delete / move / batch handlers (git write-queue)
├── write-queue.ts     # single-writer mutex per vault
├── hybrid-search.ts   # BM25 + vector + RRF fusion over the QMD index
├── embed-single.ts    # per-write embed → Voyage AI → QMD index
├── notes-validate.ts  # frontmatter validation, hash, serialize/parse
├── provenance.ts      # durable/perishable voice, commit trailers
├── blame.ts           # per-segment authorship from git blame + trailers
├── discovery*.ts      # extract → link engine (auto-wikilinking on write)
├── graph-health.ts    # vault health metrics + flags
├── vault-graph.ts     # wikilink graph + clusters
├── vault-stats.ts     # cached stats for vault_status
├── vault-config.ts    # detection + loading of the vault structure
└── db.ts              # single SQLite state-db for discovery + provenance + blame

---

Code conventions

• TypeScript strict mode. No any except at untyped externals.
• Raw node:http. No Express / Fastify.
• Node ≥ 22, ESM only, built-in fetch + crypto.
• Dependencies are intentionally minimal (@modelcontextprotocol/sdk, better-sqlite3, zod, yaml).
• The vault is sacred — Grove is plumbing. Never restructure or make policy decisions about vault content.

Architecture rules

1. The vault is the source of truth. All other state (state.db, QMD index) is derived. If they diverge, the derived state is wrong — rebuild it.
2. All writes are serialized via the write queue. No concurrent git operations.
3. Every write creates a git commit with attribution.
4. Search index updates synchronously on write so the agent's next call sees the change.
5. Keep the tool count small. Six tools today. If you're adding a tenth, stop and reconsider.

---

License

MIT. See LICENSE.