Search your Obsidian vault like a knowledge base. Keep it local.
obsidian-kb means Obsidian Knowledge Base. It turns an Obsidian vault into
a local knowledge base that you, a script, or a coding agent can search without
opening the whole vault.
It is built for the moment where keyword search is too narrow, semantic search is
too fuzzy, and sending an entire vault to an LLM is not acceptable. Your Markdown
notes stay the source of truth; obsidian-kb adds a local retrieval layer around
them.
- Find the right note section, not just the right file.
- Combine exact keyword search with semantic search.
- Follow useful Obsidian wikilinks and backlinks when context is connected.
- Get traceable results with file paths, headings, line ranges, scores, and snippets.
- Let LLM agents read only the few chunks they need.
- Keep indexing, embeddings, and metadata local.
obsidian-kb does not call OpenAI, Claude, ChatGPT, or any hosted LLM API. It
does not write summaries into your vault, and it does not replace Obsidian. It is
a fast local companion for retrieval.
With Homebrew:
brew install dgalichet/tap/obsidian-kbOr download the matching macOS archive from the
latest GitHub Release
and put obsidian-kb on your PATH.
Release archives for Linux are named by Rust target triple. Replace vX.Y.Z
with a release tag that contains the Linux archive, then extract the whole
directory and put a wrapper on your PATH:
version="vX.Y.Z"
tmpdir="$(mktemp -d)"
curl -L \
"https://github.com/dgalichet/obsidian-kb/releases/download/${version}/obsidian-kb-x86_64-unknown-linux-gnu.tar.gz" \
-o "${tmpdir}/obsidian-kb-linux-x86_64.tar.gz"
sudo mkdir -p /opt/obsidian-kb
sudo tar -xzf "${tmpdir}/obsidian-kb-linux-x86_64.tar.gz" \
-C /opt/obsidian-kb \
--strip-components=1
sudo tee /usr/local/bin/obsidian-kb >/dev/null <<'EOF'
#!/usr/bin/env sh
exec /opt/obsidian-kb/obsidian-kb "$@"
EOF
sudo chmod +x /usr/local/bin/obsidian-kb
obsidian-kb --helpKeep the extracted files together under /opt/obsidian-kb; the archive may
include runtime libraries that must stay next to the executable.
Release archives for Windows are named by Rust target triple. Replace vX.Y.Z
with a release tag that contains the Windows archive. In PowerShell:
$Version = "vX.Y.Z"
$InstallDir = "$env:LOCALAPPDATA\Programs\obsidian-kb"
$Archive = "$env:TEMP\obsidian-kb-windows-x86_64.tar.gz"
Invoke-WebRequest `
-Uri "https://github.com/dgalichet/obsidian-kb/releases/download/$Version/obsidian-kb-x86_64-pc-windows-msvc.tar.gz" `
-OutFile $Archive
New-Item -ItemType Directory -Force $InstallDir | Out-Null
tar -xzf $Archive -C $InstallDir --strip-components 1
$UserPath = [Environment]::GetEnvironmentVariable("Path", "User")
if ([string]::IsNullOrWhiteSpace($UserPath)) {
[Environment]::SetEnvironmentVariable("Path", $InstallDir, "User")
} elseif (($UserPath -split ";") -notcontains $InstallDir) {
[Environment]::SetEnvironmentVariable("Path", "$UserPath;$InstallDir", "User")
}
$env:Path = "$env:Path;$InstallDir"
obsidian-kb.exe --helpOpen a new terminal if obsidian-kb.exe is not found after updating the user
PATH. Keep the extracted files together in $InstallDir; the archive may
include runtime DLLs that must stay next to the executable.
For development from a Rust checkout:
cargo build --release
./target/release/obsidian-kb --helpCreate a local config for your vault:
obsidian-kb init --vault /path/to/ObsidianVaultBuild the local index:
obsidian-kb indexAsk a question:
obsidian-kb search "How do I avoid overloading an agent context?"Search for an exact name, command, API, or error:
obsidian-kb search "Service Connect TLS App Mesh" --mode bm25 --top 5Search for a vague idea:
obsidian-kb search "notes about context saturation" --mode vector --top 5Find notes similar to an indexed note:
obsidian-kb related "ai/contexte.md" --top 5Find notes similar to draft text that is not indexed yet:
pbpaste | obsidian-kb related --stdin --top 5
obsidian-kb related --text "draft paragraph..." --top 5Use hybrid search plus the Obsidian graph:
obsidian-kb search "local RAG with Obsidian" --mode hybrid --expand-graphFilter by indexed tags and frontmatter properties:
obsidian-kb search "hybrid retrieval" --tag retrieval/hybrid --property status=active
obsidian-kb search --tag business --json| Mode | Best for | Example |
|---|---|---|
bm25 |
Exact names, commands, errors, APIs, acronyms, file names | cargo clippy warning |
vector |
Vague concepts, synonyms, half-remembered ideas | how to reduce context noise |
hybrid |
Everyday search where exact and semantic signals both matter | Obsidian RAG second brain |
Add --expand-graph when linked notes and backlinks are likely to add useful
context:
obsidian-kb search "Obsidian RAG second brain" --mode hybrid --expand-graphFor automation, use JSON:
obsidian-kb search "query" --mode hybrid --expand-graph --json
obsidian-kb search "query" --mode hybrid --top 5 --include-text --max-chars 1200 --jsonThe JSON output is grouped by indexed document. Each result includes its best chunk, matched chunk count, matched chunks with headings, line ranges, optional PDF page ranges, snippets, chunk IDs, ranks, scores, document kind, and graph boosts.
related searches for notes that are semantically close to a source note or to
draft text. For indexed notes, it reuses the stored chunk embeddings for that
note, averages them into a source vector, scores indexed chunks, excludes the
source note, and aggregates the best matching chunks by note.
obsidian-kb related "note title or path" --top 10 --json
obsidian-kb related --stdin --top 10 --jsonUse --candidates N to change how many vector chunk candidates are scored
before note-level aggregation. With benchmarking enabled, related logs the
same vector load/scoring phases as search, plus related_aggregate_notes_ms.
In MCP and HTTP serve mode, repeated vector and related searches reuse cached
stored embeddings and report vector_embeddings_cached.
Use index.exclude_headings to keep noisy metadata sections out of BM25,
embeddings, and related-note scoring:
[index]
exclude_headings = ["Relations", "Sources"]Heading matches are case-insensitive and include descendants, so excluding
Relations also excludes ### Backlinks under ## Relations. Full heading
paths are supported for narrower exclusions, for example
"Project A > Relations". Wikilinks are still extracted from the whole note
for graph context.
PDF indexing is local and opt-in. Enable it in .obsidian-kb.toml:
[index.pdf]
enabled = true
max_file_size_mb = 50When enabled, index also scans non-excluded .pdf files, extracts embedded
text locally with lopdf, chunks each text-bearing page as Page N, and stores
the chunks alongside Markdown chunks for BM25, vector, and hybrid search. PDF
results use document_kind = "pdf" and include start_page/end_page fields
in JSON output. Scanned image-only PDFs need OCR first; this feature does not
call hosted APIs or write extracted text back to the vault.
obsidian-kb indexes tags and simple YAML frontmatter properties as structured
metadata. Use --tag to require a tag and --property KEY=VALUE to require a
frontmatter property value. Repeat either option to combine filters with AND
semantics:
obsidian-kb search "agents" --tag ai/context --property status=active
obsidian-kb search --property type=book --property status=reading --json
obsidian-kb search --property 'created>=2026-01-01' --jsonFilter-only searches are allowed when at least one --tag or --property
filter is present. Tag filters include tags found in frontmatter and Markdown
body text. Property filters use simple scalar values and scalar arrays from
frontmatter. Supported property operators are =, !=, >, >=, <, and
<=. Quote filters containing < or > in shells.
Discover available filters before guessing:
obsidian-kb tags
obsidian-kb tags --prefix ai --json
obsidian-kb properties
obsidian-kb properties --key status --jsonFrontmatter property indexing is configurable in .obsidian-kb.toml:
[index.properties]
enabled = true
filter_keys = ["*"]
ignored_keys = ["cssclasses", "template", "id", "uuid", "publish", "dg-*"]
max_value_chars = 200By default all simple properties are available for exact filters except noisy or technical keys. Property filters do not change BM25 or vector scoring yet; they narrow the result set after candidate retrieval.
Re-index after changing notes:
obsidian-kb indexRoutine indexing reloads the vault, refreshes SQLite metadata and Tantivy, and
reuses embeddings for chunks whose content hash has not changed. The legacy
--changed-only flag is still accepted, but it is not a true changed-only
SQLite/Tantivy indexer.
Rebuild everything if you want a clean index:
obsidian-kb index --rebuildInspect a result:
obsidian-kb show <chunk-id>
obsidian-kb show <chunk-id> --json
obsidian-kb show <chunk-id> <chunk-id> --jsonCheck that the vault and indexes are healthy:
obsidian-kb doctor
obsidian-kb statsExplore direct links around a note:
obsidian-kb graph "Obsidian" --depth 1Give the agent a simple rule: search first, read second.
Recommended defaults:
- Use
obsidian-kb search --mode hybrid --expand-graphfor conceptual questions. - Use
--mode bm25for exact names, commands, errors, APIs, classes, acronyms, and file names. - Use
--mode vectorfor vague conceptual questions. - Read only the top relevant chunks.
- Cite file paths and headings when summarizing.
This keeps answers grounded while avoiding bulk reads of the whole vault.
Ready-to-copy integration recipes are available in
docs/agent-recipes.md: Claude Desktop MCP,
Codex/CLI agents, Cursor, Continue, shell scripts, and a reusable
search first, read second system prompt.
For the complete agent and MCP usage guide, see docs/using-obsidian-kb-with-agents.md.
obsidian-kb init writes a .obsidian-kb.toml config file. Index data is stored
under .obsidian-kb/ by default:
- SQLite metadata and embeddings
- Tantivy full-text index
- chunk and link metadata
The tool does not modify your Markdown notes during indexing or search.
FastEmbed may download a local embedding model the first time embeddings are
built. Model files are cached in the user cache directory by default, such as
~/Library/Caches/obsidian-kb/models on macOS, and can be reused across vaults.
Optional benchmark logging can be enabled in .obsidian-kb.toml with
[benchmark] enabled = true. Timings are appended locally as JSONL under
.obsidian-kb/benchmarks.jsonl by default, and search query text is omitted
unless include_query = true.
Published vault-size benchmark results and the reproducible synthetic benchmark
runner are documented in docs/benchmarks.md.
For MCP clients, obsidian-kb mcp runs a local stdio server with search,
related, show, graph, tags, properties, stats, warmup, unload, status, and
get_current_note tools.
The MCP search tool accepts tags and properties arrays, plus tag and
property aliases for single filters. Hybrid and vector searches keep the local
embedding model and stored embeddings warm between requests, then unload them
automatically after the configured idle timeout.
For local HTTP clients, obsidian-kb serve binds to 127.0.0.1:27124 by
default and prints the chosen URL. Use --port to override the port. It exposes
GET /health, GET /status, POST /search, POST /show, POST /graph,
POST /index/refresh, POST /shutdown, POST /workspace/context,
DELETE /workspace/context, POST /workspace/current-note, and POST /mcp.
The /mcp endpoint
accepts MCP JSON-RPC over streamable HTTP and can return either JSON or
text/event-stream responses.
The Obsidian plugin publishes the active Markdown note identity when the UI context changes, and refreshes it with a heartbeat. This transient state is kept in service memory, separate from the search index; an existing note can be reported even before it has been indexed. No editor text, selection, or content revision is synchronized, and these endpoints never modify the vault.
Publish with POST /workspace/context:
{
"vault_path": "/absolute/path/to/vault",
"session_id": "unique-obsidian-workspace-session-id",
"context_version": 1,
"note": { "path": "Notes/Current.md", "title": "Current" }
}Use note: null when no Markdown note is active. A session's version must
increase when its note identity changes. Repeating the same version and payload
refreshes its heartbeat; older or conflicting updates are rejected. Sessions
expire after 90 seconds without a successful publication. At most 64 sessions
are retained; new sessions can replace expired sessions. Vault paths must match
the service's canonical vault, and note paths must identify existing Markdown
files inside that vault, including when symlinks are involved.
Read via the MCP get_current_note tool or POST /workspace/current-note with
{"vault_path":"/absolute/path/to/vault"} and optional session_id. The reply
has status, vault_path, and note. A usable identity is returned only for
status: "available", with session_id, context_version, and age_ms.
Other statuses are no_active_note, unavailable, stale, and ambiguous;
their note is null. With multiple live sessions the reply includes candidate
session IDs, and callers must choose an explicit session. Unloading a plugin
can remove its session via DELETE /workspace/context with vault_path and
session_id; an abrupt close is detected through expiry.
HTTP MCP reads the service's workspace state directly. Stdio MCP consults the
same loopback service and returns unavailable when it is absent or serves a
different vault. For a custom service port, configure both ends consistently:
obsidian-kb serve --port 27125
obsidian-kb mcp --workspace-port 27125Agents should pin the returned vault, note path, and session at the beginning of
a request about the current note. Changing tabs must not redirect work already
in progress. context_version identifies UI context changes, not a file
content revision: read the targeted file separately, and check for intervening
content changes before applying edits.
Browser CORS access is restricted to configured origins. The default is the Obsidian desktop origin:
[serve]
cors_allowed_origins = ["app://obsidian.md"]Requests without an Origin header, such as local CLI and native clients, are
not blocked. To allow a local browser app, add its exact origin including the
port, for example http://127.0.0.1:3000. Use * only when you intentionally
want any browser page to read from the local service.
obsidian-kb is intentionally small in scope:
- not a hosted AI product;
- not a hosted vector database;
- not a LangChain or LlamaIndex wrapper;
- not a full GraphRAG system;
- not an automatic note writer.
For implementation details, design tradeoffs, configuration reference, and release notes, see docs/architecture.md.
All indexes are local. Metadata and embeddings are stored in SQLite, and BM25 data is stored in Tantivy.
When an external agent reads selected chunks and includes them in its context,
those excerpts may be sent to the agent's model provider depending on your agent
configuration. obsidian-kb itself does not make hosted LLM calls.
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)