io.github.KIOKO-LAB/freshvault

freshvault

한국어 · 日本語

Your Obsidian vault is Claude's memory. Always fresh, always local.

Every other vault-search MCP makes you re-run an index command, babysit a watch terminal, or click "Update Index" in a web UI. freshvault watches your vault from inside the MCP server: edit a note, and Claude sees it seconds later. Automatically. Forever.

• 🔄 Never reindex — the file watcher lives in the server process; boot catch-up absorbs offline edits
• 🔒 100% local — embeddings via Ollama (bge-m3), your notes never leave your machine
• 🌏 Multilingual by default — bge-m3 handles Korean, Japanese, and 100+ languages that English-only defaults fail on
• 🎯 Benchmark-driven retrieval — unconditional BM25 fusion wrecked Korean paraphrase queries (82.5% → 47.5% top-1), so it's off; pure dense missed identifier queries outright (57.1%), so it's not gone either. Lexical scoring is gated on code-like query tokens: paraphrase 82.5% → 82.5% (identical), identifiers 57.1% → 100% — receipts
• 🪶 No vector DB, no Docker, no Python — JSON metadata + a Float32 sidecar, plain Node, source you can read in one sitting
• 🧠 Chunking that respects sentences — YAML frontmatter stripped, splits on paragraph/sentence boundaries (CJK-aware)

Install

Prerequisites: Node 20+ and Ollama.

npx -y freshvault setup

That's it. The wizard detects your Obsidian vault, pulls the embedding model, builds the index, and registers with Claude Code. There is no step 2, and there is never a step 2: no index command to re-run, no watch terminal, no background service.

Manual install (Claude Desktop / Cursor / Windsurf)

{
  "mcpServers": {
    "freshvault": {
      "command": "npx",
      "args": ["-y", "freshvault", "serve"],
      "env": { "FRESHVAULT_VAULT": "/absolute/path/to/your/vault" }
    }
  }
}

Claude Code one-liner:

claude mcp add freshvault -s user -- npx -y freshvault serve

Use

Just ask Claude about your notes:

"Search my notes for what I wrote about cache eviction strategies"

Three tools, all read-only:

Scoped queries competitors gate behind settings or paywalls work per-query here:

"Search my notes tagged #project modified after June for the budget discussion"

How it works

Obsidian vault ──fs.watch──▶ freshvault MCP server ──search_notes──▶ Claude
   (.md files)               (chunks → bge-m3 embeddings              (generation)
                              → one JSON index, incremental)

• Incremental: only changed/deleted notes are re-embedded (mtime+size diff), debounced 4s
• Safety net: a 60s mtime sweep catches events the watcher misses (network drives, atomic-rename editors)
• Multi-client safe: first server process becomes the writer (heartbeated lock); others are readers that hot-reload and promote themselves if the writer dies
• Transactional: an embedding-server outage mid-index can never lose or corrupt notes
• Scale: vectors live in a packed Float32 sidecar (fast startup, compact); brute-force cosine over thousands of chunks is milliseconds. Honest note: search is still linear — sub-100ms into tens of thousands of chunks, but this is not a vector DB replacement for huge corpora

Multiple vaults

Register one server per vault — index files are kept per-vault automatically:

claude mcp add work-vault -s user -e FRESHVAULT_VAULT=/path/to/work -- npx -y freshvault serve
claude mcp add personal-vault -s user -e FRESHVAULT_VAULT=/path/to/personal -- npx -y freshvault serve

Other embedding servers (LM Studio, LiteLLM, OpenAI-compatible)

FRESHVAULT_EMBED_API=openai FRESHVAULT_EMBED_URL=http://localhost:1234 npx -y freshvault serve

Anything speaking /v1/embeddings works; FRESHVAULT_EMBED_KEY for authenticated endpoints (never written to the config file).

Configuration

Everything works with zero config after setup. Override when needed:

Commands: setup · serve (default) · index (manual escape hatch) · status

Ignore patterns

Patterns follow gitignore semantics, matched against vault-relative paths:

• A slash anywhere but the end anchors the pattern to the vault root. A trailing slash only means "directory" — it does not anchor.
• * and ? never cross a /. ** crosses directories only as a whole path segment (**/x, x/**, x/**/y); glued inside a segment it collapses to a single *, as in git.
• Matches end on a segment boundary — Templates never matches TemplatesOld.
• ! negation and character classes are not supported; such patterns match nothing.
• FRESHVAULT_IGNORE is comma-separated, so a pattern cannot contain a comma.

Behaviour change since v0.3.0. v0.3.0 treated a trailing slash as a root anchor, so Templates/ excluded only the vault-root Templates/ and silently indexed every nested one — no warning, just a quietly polluted index. Patterns shaped like Templates/, /Templates, **/x and a/**/b now exclude more than before (/Templates previously matched nothing at all). Conversely, ** glued inside a segment (Daily**md) no longer crosses /. Run freshvault status after upgrading and compare the excluded count if it matters to you.

Benchmark

Two retrieval micro-benchmarks ship in-repo (node scripts/bench.mjs): ko-bench (30 Korean notes, 40 paraphrase queries) and id-bench (38 technical notes, 14 identifier queries). Both run under three scoring modes — dense, hybrid-always, and the shipped gated mode — and the script checks the no-regression contract itself. Results and the bge-m3-ko (85.0% top-1, 634MB) import guide in docs/ko-bench.md.

Roadmap

• MCPB bundle for one-click Claude Desktop install
• Reranking pass for large vaults
• PDF text extraction at index time

License

MIT © Kioko Lab