Vault Coach
wanjin550825 downloadsLocal knowledge Q&A and interview practice from your vault using Ollama.
- Overview
- Scorecard
- Updates2
🌐 Language: English | 中文
An Obsidian plugin for intelligent local knowledge base Q&A, powered by Advanced RAG (Retrieval-Augmented Generation) and a locally-running Ollama service. Your data never leaves your machine.
Table of Contents
Features
✅ Phase 1 (Current — v0.0.2)
| Feature | Description |
|---|---|
| 🔍 Hybrid Retrieval | TF-IDF keyword search + semantic vector search + RRF fusion |
| ✏️ Query Rewrite | Local LLM auto-rewrites queries to improve retrieval quality |
| 📊 Rerank | Optional external rerank service, falls back to heuristic rerank |
| 🧠 Long-term Memory | Cross-session extraction and injection of user preferences |
| 🔄 Incremental Index Sync | Watches vault file changes and updates the index automatically |
| 🌊 Streaming Output | Pseudo-streaming response rendering with low perceived latency |
| 💾 Conversation Persistence | Chat history saved locally and restored after restart |
| 🔒 100% Local | Powered by Ollama REST API — no data leaves your device |
Quick Start
Prerequisites
- Obsidian v1.5.0+
- Ollama running locally
- At least one chat model (e.g.
gemma3:4b) and one embedding model pulled
Installation (Development Build)
# 1. Clone into your vault's plugin directory
cd <your-vault>/.obsidian/plugins
git clone https://github.com/Wanjin5508/vault-coach vault-coach
# 2. Install dependencies and build
cd vault-coach
npm install
npm run build
# 3. Enable Vault Coach in Obsidian Settings > Community Plugins
Basic Setup
- Open Settings → Vault Coach
- Set your Ollama base URL (default:
http://127.0.0.1:11434) - Enter your chat model name (e.g.
gemma3:4b) and embedding model name - Click Rebuild Index or wait for auto-sync to complete
- Click the 💬 ribbon icon to start chatting
Configuration
General
| Setting | Description |
|---|---|
| Assistant Name | Name shown in the sidebar header |
| Default Greeting | First message shown after conversation reset (Markdown supported) |
| Open on Startup | Auto-open Vault Coach when Obsidian loads |
| Default Retrieval Mode | keyword / vector / hybrid (hybrid recommended) |
| Collapse Sources | Whether to collapse the sources section by default |
Knowledge Base
| Setting | Default | Description |
|---|---|---|
| Scope | Whole Vault | Or limit to a specific folder |
| Chunk Size | 600 chars | Maximum characters per chunk |
| Chunk Overlap | 120 chars | Overlap between adjacent chunks |
| Auto Sync | ✅ | Watch file changes and update index automatically |
| Debounce Delay | 15,000 ms | Wait time after last file change before syncing |
| Max Wait Time | 120,000 ms | Force sync after this duration regardless |
| File Threshold | 8 files | Trigger immediate sync when this many files change |
Advanced RAG
| Setting | Default | Description |
|---|---|---|
| Query Rewrite | ✅ | LLM rewrites the query before retrieval |
| Vector Retrieval | ✅ | Generate embeddings during index build |
| Rerank | ✅ | Rerank retrieved candidates |
| Keyword top-k | 10 | Keyword retrieval candidate count |
| Vector top-k | 10 | Vector retrieval candidate count |
| Hybrid limit | 12 | Max candidates after fusion |
| Rerank top-k | 8 | Candidates entering rerank stage |
| Context chunks | 8 | Final chunks injected into the prompt |
| Source limit | 5 | Max sources shown per answer |
| Temperature | 0.2 | Generation temperature (keep low for RAG) |
Local Model
| Setting | Description |
|---|---|
| LLM Base URL | Ollama address, default http://127.0.0.1:11434 |
| Chat Model | Used for query rewrite and answer generation |
| Embedding Model | Used for vector retrieval; rebuild index after changing |
| Rerank Service URL | Optional; leave empty to use heuristic rerank |
| Rerank Model | Used when a rerank service URL is configured |
Long-term Memory
| Setting | Default | Description |
|---|---|---|
| Enable Memory | ✅ | Extract and store useful facts after each turn |
| Memory Top-k | 4 | Max memories injected per answer |
| Max Memory Items | 150 | Oldest/least-accessed items are evicted when exceeded |
| Max Persisted Messages | 60 | Max conversation messages kept in local storage |
Roadmap
See PROJECT_PLAN.md for the full three-phase development plan.
Phase Overview
| Phase | Name | Status | Key Goal |
|---|---|---|---|
| Phase 1 | Advanced RAG Q&A | ✅ Complete | Hybrid retrieval + Rerank + Long-term memory + Incremental index |
| Phase 2 | Knowledge Graph Enhancement | 🔜 Planned | Entity extraction + Graph construction + Smart query routing |
| Phase 3 | Agentic Interview Assistant | 🔜 Planned | Multi-role agents + Interview simulation + Skill diagnosis |
| Phase 4 | Standalone Application | 🔜 Vision | Independent frontend/backend + Voice + Avatar |
Architecture
┌─────────────────────────────────────────────────┐
│ view.ts (UI) │
│ Obsidian ItemView · Right Sidebar │
└────────────────────┬────────────────────────────┘
│
┌────────────────────▼────────────────────────────┐
│ main.ts │
│ Plugin Entry · State Management · Vault Events │
└──────┬─────────────┬──────────────┬─────────────┘
│ │ │
┌──────▼──────┐ ┌────▼─────┐ ┌────▼──────────────┐
│ rag-engine │ │knowledge │ │ persistent-store │
│ Advanced │ │ -base │ │ runtime-state.json │
│ RAG Flow │ │Index/Ret.│ │ index-snapshot.json│
└──────┬──────┘ └──────────┘ └───────────────────┘
│
┌──────▼──────────────────────────────────────────┐
│ model-client.ts │
│ Ollama REST API · /api/chat · /api/embed │
└─────────────────────────────────────────────────┘
For detailed technical documentation, see TECHNICAL_DOC.docx.
Known Issues
- Non-true streaming:
requestUrlreturns the full response at once; true token-level streaming will require afetch+ReadableStreammigration - Memory search lacks semantic similarity: Currently uses keyword matching only; embedding-based memory search is planned for Phase 2
- VIEW_TYPE typo: The constant value in
constants.tssaysvalue-coach-viewinstead ofvault-coach-view(non-breaking, will be fixed in next release)
Contributing
Issues and PRs are welcome! Please check PROJECT_PLAN.md for the current development direction before opening a PR.
License
92%
HealthExcellent
ReviewPassed
About
Ask your vault questions locally with an RAG-powered assistant combining TF-IDF, semantic vectors and RRF, backed by a local Ollama model so data never leaves your device. Rewrite queries, rerank results, persist conversations and long-term memory, and sync indexes incrementally with streaming responses.Details
Current version
1.0.1
Last updated
Last week
Created
2 months ago
Updates
2 releases
Downloads
25
Compatible with
Obsidian 1.5.0+
Platforms
Desktop, Mobile
License
MIT