osi
Provides read-only semantic and keyword search, similar-note discovery, note/section retrieval with links and backlinks, and index status over an Obsidian vault. Includes a Dataview view for showing similar notes inside Obsidian.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
OSI — Obsidian Semantic Index
Read-only semantic search and similar notes over an Obsidian vault, mainly for LLMs over MCP. Assumed setup. The vault reaches the server through a sync tool and is mounted read-only. Embeddings come from a llama.cpp server in router mode, with one GPU entry and one CPU entry for the same GGUF file. The GPU is shared with other models, such as chat models.
search: keyword (SQLite FTS5) and vector search, merged with reciprocal rank fusion, grouped by note, with the best 1–3 matching sections per note.
similar: precomputed similar notes with the section pairs that explain each match and their link status.
get_note: a note or one section, with frontmatter, outgoing links and backlinks.
status: index health.
The same four functions are served as REST routes and as MCP tools at /mcp. Everything needs a bearer key
except /health.
Layout
Path | Contents |
| The service: config, markdown parsing, chunking, links, SQLite store, embedder client, search, similar notes, indexer thread, REST, MCP, CLI |
| pytest suite with a synthetic fixture vault and a fake embedder (no llama.cpp needed) |
| Dataview view that shows similar notes inside a note |
| Instructions for LLM harnesses on when to use which tool |
| Embedder entries for the llama.cpp router |
| curl checks against a running service |
Related MCP server: EzRAG MCP Server
Build and test (on the server)
Nothing runs on the development machine; the server builds and tests.
docker build --target test -t osi:test . # runs the test suite; fails the build on any failure
docker build --target runtime -t osi:0.1.0 . # the service image; the tag must match IMAGE_TAG in .envLock file. The test stage records exact dependency versions. Copy them back into the repo once:
docker run --rm osi:test cat /app/requirements.lock > requirements.lockConfigure and run
The service needs only
compose.yamland.env, so it can run from any folder on the machine that built the image.cp .env.example .envand fill it in;IMAGE_TAGnames the image you built. Generate keys withopenssl rand -hex 32. To update, build a new tag, changeIMAGE_TAGand rundocker compose up -d.Add the two entries from
llama/router-preset.inito the router.EMBED_MODEL_IDis the GGUF file name without.gguf(Qwen3-Embedding-8B-Q8_0); OSI checks it against both entries. The model, the router entries, the nightly time and the update mode are all set in.env.docker compose up -d, then checkdocker compose logs -f osi. A missing or malformed setting stops the service at startup with a list of every problem.The keyword index builds on its own within a minute. Build the vectors once:
docker compose exec osi osi reindex # refuses while another model is loaded on the router docker compose exec osi osi reindex --force # runs anyway docker compose exec osi osi status # watch build.state, pending_vectors, vector_searchRun
scripts/smoke.shwith a client key.
Admin commands
All run inside the container and use ADMIN_KEY.
Command | Does |
| Full status: counts, freshness, fingerprint, build progress, recent errors |
| Scan the vault now |
| Run the nightly update now: pending chunks on the GPU entry, or the CPU entry while the GPU is in use |
| Full vector build on the GPU entry (or CPU if |
| Embed sample chunks on CPU and GPU and compare: cosine and top-10 overlap |
| recall@k and MRR for keyword, vector and hybrid search, plus similar notes |
| One-off model benchmark against the router; needs no |
Benchmark: choosing the model
osi bench reads the vault exactly as the indexer does and, for each model, measures:
a full GPU pass over every chunk, plus the similar-notes recompute (the cost of a nightly rebuild);
CPU query latency, CPU throughput on a sample, and how closely CPU vectors match GPU vectors;
recall@10 for vector search and similar notes, if you pass the test set.
It prints a Markdown report with numbers only (no note paths, titles, prompts or text) and sends progress
to stderr. It refuses to start while another model is loaded on the router (--force overrides), stops if
one gets loaded during a GPU pass, and unloads every entry it used.
Make sure the router has the entries to compare. The defaults are the 4B and 8B Q8_0 pairs in
llama/router-preset.ini.On the server:
docker build --target runtime -t osi:bench . docker run --rm --user "$(id -u):$(id -g)" \ -v /path/to/vault:/vault:ro \ -v /path/to/data/eval:/eval:ro \ osi:bench osi bench --url http://<router>:<port> \ --exclude-folders "Templates,Private" --exclude-tags private \ --testset /eval/testset.yaml > bench.mdWithout a test set, leave out the
/evalmount and--testset.With a
.env,--env-file .envsupplies the exclusions and chunk settings instead of the flags.Add
--limit-chunks 300for a quick trial run first.
Entries the router lacks are skipped.
--pair LABEL=GPU_ENTRY,CPU_ENTRY[,CPU_ENTRY...](repeatable) picks other entries.
The default model, Qwen3-Embedding-8B Q8_0, was chosen this way. On a vault of about 2,400 notes a full GPU
pass took about 4 minutes, CPU queries took about 0.2 s with 16 threads, and at Q8_0 CPU and GPU vectors were
interchangeable (cosine 0.999 or higher). Your numbers will differ; run osi bench on your own hardware.
Test set
osi eval reads /data/eval/testset.yaml (inside the data folder, never in the repo, since it names notes):
search:
- prompt: "a question you would ask"
expect: ["Folder/Expected note.md", "Other/Note.md"]
similar:
- note: "Folder/Some note.md"
expect: ["Folder/Related note.md"]Clients
opencode (opencode.json, current config format: servers under mcp.servers, oauth off for key auth):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"servers": {
"osi": {
"type": "remote",
"url": "http://<server>:<API_PORT>/mcp",
"oauth": false,
"headers": { "Authorization": "Bearer {env:OSI_KEY}" }
}
}
}
}Claude Code: claude mcp add --transport http osi http://<server>:<API_PORT>/mcp --header "Authorization: Bearer $OSI_KEY"
Other MCP clients: Streamable HTTP at http://<server>:<port>/mcp with the header
Authorization: Bearer <key>. Give each client its own key so it can be revoked on its own and shows up
separately in the query log.
Obsidian: see the header of obsidian/similar.js.
Skill: copy skill/SKILL.md to ~/.claude/skills/vault-notes/SKILL.md, which both Claude Code and
opencode read. Then replace the server placeholder and fill in what your folders mean. The skill names the
tools for each harness and falls back to the REST API when no MCP tool is registered. For harnesses
without skills, paste it into the system prompt.
How it behaves
Who does what: the GPU is assumed to be shared with other work, such as chat models, and busy during the day. So the CPU entry only embeds search queries (a fraction of a second each), and all bulk embedding goes to the GPU entry at night, which is unloaded afterwards.
Updates: the vault is scanned every
SCAN_SECONDS, so keyword search, links, tags, filters andget_notefollow edits within a minute. Edited sections are found by meaning after the nightly run, which starts atNIGHTLY_TIME, embeds only chunks without a vector, then recomputes the similar lists. If another model is loaded on the router, the run waits; in the window's lastNIGHTLY_CPU_FALLBACK_MINUTESthe CPU entry takes over.UPDATE_MODE=debounceadds daytime embedding on the CPU,DEBOUNCE_MINUTESafter a note's last change./statusshowslast_embedandupdate_waiting.Guards: vector search switches off, with the reason in
/statusand in each search response, when the embedding settings changed since the last build, when the CPU embedder serves a different GGUF thanEMBED_MODEL_ID, or when its probe vectors drift. Search then falls back to keywords untilosi reindex.Sharing the GPU: a full build refuses to start while another model is loaded on the router (unless forced), steps aside if one gets loaded during the build, and unloads the GPU embedder at the end.
Privacy: excluded folders, hidden folders and notes with an excluded tag are never stored; get_note answers 404 for them exactly as for missing notes.
%%comments%%, HTML comments and Templater tags are stripped from the index and from get_note output. The query log stays in/dataand is purged afterQUERY_LOG_RETENTION_DAYS.
License
MIT; see LICENSE.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Search and read your own notes: insights, drafts, book and podcast notes. Read-only, OAuth.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables read-only access to Obsidian vaults with semantic search, tag filtering, and metadata queries. Provides secure, intelligent note retrieval and summarization for LLMs without modifying your vault.13 npm13ISC
- AlicenseNot gradedqualityDmaintenanceProvides semantic search and keyword search over Obsidian notes, along with direct note retrieval, allowing external AI agents to query and access the vault.19BSD Zero Clause
- FlicenseNot gradedqualityDmaintenanceEnables semantic search over an Obsidian vault using ChromaDB, allowing users to search, read, and list notes via natural language.-
- AlicenseNot gradedqualityDmaintenanceEnables read-only, filesystem-based access to Obsidian vault Markdown notes, including full-text search, title/path search, and frontmatter or tag metadata lookup, all without running Obsidian or using a plugin/REST API.8 npmMIT