VaultRAG

A private, local-first retrieval stack that turns your Obsidian vault into searchable semantic memory using .NET, Qdrant, and local embedding models.

Reference document in your Obsidian vault: Open in Obsidian

Run with Docker Compose

Prerequisites:

• Docker Desktop installed and running.
• .NET SDK 10 installed (dotnet --version should report 10.x).

Environment configuration:

• Initialize .env from template if needed:
  • PowerShell: Copy-Item .env.example .env
  • Bash: cp .env.example .env
• Edit .env to customize ports, container names, and default model.
• Current defaults:
  • OLLAMA_PORT=11435
  • EMBEDDINGS_BASE_URL=http://localhost:11435/v1
  • EMBEDDING_MODEL=nomic-embed-text
  • QDRANT_HTTP_PORT=6333
  • QDRANT_GRPC_PORT=6334
  • QDRANT_GRPC_URL=http://localhost:6334
  • QDRANT_COLLECTION=vaultrag_notes
  • OLLAMA_MODEL=glm-5:cloud

Start services:

docker compose up -d

Check containers:

docker compose ps

Ollama

Base URL (host): http://localhost:11435 by default (from OLLAMA_PORT in .env)

For cloud models (example: glm-5:cloud), sign in once:

docker compose exec ollama ollama signin

Run a model:

docker compose exec ollama ollama run glm-5:cloud

Quick API test:

curl.exe http://localhost:11435/api/chat -H "Content-Type: application/json" -d "{\"model\":\"glm-5:cloud\",\"messages\":[{\"role\":\"user\",\"content\":\"Hello\"}],\"stream\":false}"

Qdrant

HTTP endpoint (host): http://localhost:6333 by default (from QDRANT_HTTP_PORT in .env) gRPC endpoint (host): localhost:6334 by default (from QDRANT_GRPC_PORT in .env)

Quick health check:

curl http://localhost:6333/healthz

Stop services:

docker compose down

Ingest Obsidian Markdown into Qdrant

Build the ingestion app:

dotnet build src/VaultRAG.Ingest

Ensure the embedding model is available in Ollama:

docker compose exec ollama ollama pull nomic-embed-text

Run ingestion for a vault folder:

dotnet run --project src/VaultRAG.Ingest -- --vault "E:\Brain"

Useful options:

dotnet run --project src/VaultRAG.Ingest -- --help

dotnet run --project src/VaultRAG.Ingest -- --vault "E:\Brain" --force-reindex

Incremental indexing state is stored in .vaultrag/ingest-state.json.

Implementation details:

• Excluded folders during indexing: .obsidian, .trash.
• Point IDs are deterministic per chunk (source_path + chunk_index) for stable upserts.
• Deleted files are removed from Qdrant only when they exist in ingest state; if state is reset, run with --force-reindex.

MCP server for LLM clients

Build the MCP server:

dotnet build src/VaultRAG.McpServer

Run MCP server over stdio:

dotnet run --project src/VaultRAG.McpServer

Implemented MCP tools:

• search_notes: semantic retrieval from Qdrant (query, topK, optional sourcePathPrefix).
• get_note_chunks: fetch chunks for one indexed note (sourcePath, maxChunks).
• list_sources: list indexed source files (query, limit).
• health: checks Qdrant collection and embeddings endpoint.

Tool argument limits:

• search_notes.topK: clamped to 1..50 (default 5).
• get_note_chunks.maxChunks: clamped to 1..500 (default 50).
• list_sources.limit: clamped to 1..1000 (default 100).

Response shape:

• Tools return structuredContent (JSON object) and content[0].text (the same JSON serialized as text).
• search_notes.sourcePathPrefix filtering is applied after vector retrieval (client-side in the server process).

Environment variables used by MCP server:

• QDRANT_GRPC_URL
• QDRANT_COLLECTION
• QDRANT_API_KEY (optional)
• EMBEDDINGS_BASE_URL
• EMBEDDING_MODEL
• OPENAI_COMPAT_API_KEY (optional)
• MCP_SERVER_NAME (optional, default VaultRAG.McpServer)
• MCP_SERVER_VERSION (optional, default 0.1.0)
• MCP_SERVER_LOG_PATH (optional, default mcp-server.log next to the executable)

Scope and Security Notes

Current project scope:

• Ingestion/indexing CLI (VaultRAG.Ingest).
• Retrieval MCP server (VaultRAG.McpServer) exposing search/list/chunk/health tools.
• No built-in answer-generation API is implemented in this repository yet.

Security:

• Indexed chunk text is retrievable through MCP tools. Do not keep plaintext credentials/secrets in notes you index.