obsidian-vault-rag

Terminal app that indexes an Obsidian vault and uses it as the retrieval source for RAG-powered chat with local LLM models (via Ollama).

Note: Tested using the gpt-oss:20b model on an M1 Pro MacBook.

Installation

Prerequisites

• Python 3.13+
• Ollama installed and running
• Optional: Docker (for running ChromaDB as a server + admin UI)

Install Ollama models

ollama pull llama3.2
ollama pull nomic-embed-text

Install project dependencies (uv)

git clone <repo-url>
cd obsidian-vault-rag

uv sync

Configuration

Configuration is loaded from environment variables (a .env file is supported via python-dotenv).

Start from:

cp .env.example .env

Environment variables

Variable	Purpose	Default
MODEL_NAME	Ollama chat model	llama3.2
EMBEDDING_MODEL	Ollama embeddings model	nomic-embed-text
CHUNK_SIZE	Chunk size for indexing	1000
CHUNK_OVERLAP	Chunk overlap for indexing	200
RETRIEVAL_K	Retrieved chunks per query	3
PERSIST_DIRECTORY	Local ChromaDB directory	./chroma_db
COLLECTION_NAME	ChromaDB collection name	obsidian_documents
LOGS_FILE	Log file path	logs/app.log
SUMMARIZATION_ENABLED	Summarize long documents during indexing (true/false)	false
SUMMARIZATION_MIN_WORDS	Min words to summarize	500
SUMMARIZATION_MAX_LENGTH	Max summary length (words)	150
MARKDOWN_MODE	Markdown parsing mode (single or elements)	single
MARKDOWN_STRATEGY	Markdown parsing strategy (auto, hi_res, fast)	auto
OLLAMA_BASE_URL	Base URL for Ollama OpenAI-compatible API (used by tool-calling agent)	unset

Notes:

• CLI flags override defaults (including .env defaults).
• MARKDOWN_MODE=elements splits documents by structure (headings/paragraphs/lists).

Usage

Basic run (local ChromaDB)

Indexes your vault and starts an interactive Q&A session:

uv run obsidian-vault-rag --vault-path "/path/to/your/obsidian/vault"

Copy vault before indexing (optional)

If you prefer indexing a copy:

uv run obsidian-vault-rag \
  --vault-path "/path/to/your/obsidian/vault" \
  --copy-vault \
  --destination "./vault" \
  --overwrite-destination

Run with Docker ChromaDB (optional)

Start ChromaDB server and the admin UI:

docker compose up -d

Then point the CLI at the server:

uv run obsidian-vault-rag \
  --vault-path "/path/to/your/obsidian/vault" \
  --chroma-host localhost \
  --chroma-port 8000

Admin UI:

• ChromaDB: http://localhost:8000
• Admin UI: http://localhost:3001

CLI options

Run uv run obsidian-vault-rag --help to see the full help output.

Option	Description	Default
-v, --vault-path	Path to your Obsidian vault (required)	none
-d, --destination	Destination for copied vault (only with --copy-vault)	./vault
--copy-vault / --no-copy-vault	Copy vault before indexing (otherwise index in-place)	--no-copy-vault
--overwrite-destination	Allow deleting destination when copying	disabled
--persist-directory	Local ChromaDB storage directory	from config (./chroma_db)
--prune-missing / --no-prune-missing	Remove embeddings for files missing from vault	disabled
-m, --model	Ollama model for answering	from config (llama3.2)
-e, --embedding-model	Embedding model	from config (nomic-embed-text)
-r, --rebuild	Force rebuild of vector store	disabled
--chroma-host	ChromaDB host (remote mode)	unset
--chroma-port	ChromaDB port	8000
--collection-name	ChromaDB collection name	from config
--verbose	Verbose terminal logging	disabled
--quiet	Minimal terminal output	disabled
--log-level	Minimum terminal log level	warning
--summarization / --no-summarization	Enable summarization during indexing	from config
--summarization-min-words	Minimum words for summarization	from config
--markdown-mode	single or elements	from config
--markdown-strategy	auto, hi_res, or fast	from config

Notes:

• --verbose and --quiet cannot be used together.

Interactive session commands

When the interactive prompt starts, you can type:

Command	Description
/help or /?	Show available commands
/list	List markdown documents in the vault
/search <term>	Search file names/paths
/info <relative-path-to-md>	Show metadata for a specific document
/exit, /quit, /q	Exit the session
quit, exit, q	Exit the session (non-slash)

If summarization is enabled:

Command	Description
summaries	Show stored document summaries
stats	Show summarization statistics