Clio
Reads and indexes markdown notes from an Obsidian vault as long-term memory, enabling semantic search, date-window recall, and filtered retrieval by note type, tag, and date.
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.
Clio, the librarian
A long-term memory for AI companions, served over MCP.
Clio reads a folder of markdown notes — an Obsidian vault, a journal, an archive — and holds it as meaning rather than text. A companion can ask "what happened the week everything went quiet?" and get back the four passages that answer it, each with its source path and date, so it can cite the note instead of guessing.
She runs on your own machine. The notes, the embeddings and the database stay there. No cloud service is involved.
What she does
Semantic search over a curated set of folders (
search_memory), with optional filters by note type, tag, and date range.Date-window recall (
recall_window): "what was going on between these two dates".An orientation call (
memory_start) for the start of a conversation: a few recent notes, a few nearly-forgotten ones that surface on their own (serendipity), the threads currently in use, and the types and tags that exist so the caller knows what it can filter on.Hybrid ranking. Results are oversampled from the vector store, then re-ranked on semantic similarity, literal keyword overlap, recency, how often a passage has been used (strengthening with use, fading when idle), note type, and tags. Notes you mark as protected never fade below a floor.
Session dedup. Pass the
session_idfrommemory_startand the same passage is never returned twice in one conversation.Careful ingest. Paragraph-aware chunking with overlap; content-addressed chunk IDs so re-running is cheap and only changed notes are re-embedded; renamed and deleted notes are pruned, with a safety valve that refuses to prune if the vault looks like it failed to mount; embedded base64 images and binary blobs are stripped before they can pollute the index.
Optional remote access over streamable HTTP with an OAuth 2.1 passphrase gate, for reaching her from claude.ai through a tunnel (e.g. Tailscale Funnel or Cloudflare Tunnel).
Related MCP server: open-zk-kb
Install
Python 3.10+.
git clone https://github.com/Seravielle-de-Lochan/clio-librarian.git
cd clio-librarian
python -m venv .venv
.venv/bin/pip install -r requirements.txt # Windows: .venv\Scripts\pipThe first real run downloads the all-MiniLM-L6-v2 embedding model (~90 MB)
from Hugging Face. After that, everything is offline.
Tell her what to read
Edit two lists before the first ingest:
CURATED_FOLDERSinlibrarian/ingest.py— which folders of your vault are memory. Leave out raw chat logs and bulk transcripts; authored notes make good memory and transcripts make noise.PROTECTED_PATH_PATTERNS,PROTECTED_TAGSandTYPE_WEIGHTSinclio_v02/config_v02.py— which notes should never fade, and how much each note type (thetype:field in frontmatter) should count.
Notes are plain markdown. Frontmatter is optional, but date, type and
tags are used when present:
---
date: 2026-03-15
type: journal
tags: [garden, milestone]
---Ingest
python -m librarian.ingest --vault "/path/to/your/vault" --db ./librarian_dbRun it again whenever you like (nightly is fine). Unchanged notes are skipped.
Connect
Claude Code:
claude mcp add clio -- /path/to/clio-librarian/.venv/bin/python -m librarian.server --db /path/to/clio-librarian/librarian_dbRun it from inside the repo folder, or set PYTHONPATH to it.
Claude Desktop (claude_desktop_config.json):
{
"mcpServers": {
"clio": {
"command": "/path/to/clio-librarian/.venv/bin/python",
"args": ["-m", "librarian.server", "--db", "/path/to/clio-librarian/librarian_db"],
"env": { "PYTHONPATH": "/path/to/clio-librarian" }
}
}
}Remote (claude.ai) — only if you need it, and only behind a tunnel you control:
python -m librarian.server --db ./librarian_db --set-passphrase "a long passphrase"
python -m librarian.server --db ./librarian_db --http 8765 --stateless \
--oauth --public-url https://my-machine.example.ts.net \
--http-host my-machine.example.ts.netAnyone can register a client, but nothing is issued until someone types the
passphrase on the /approve page. Access is read-only.
Tests
python tests/sanity_v02.py # ranker, dedup, strengthening, protection
python tests/test_prune.py # rename/delete pruning and the safety valve
python tests/test_oauth_flow.py # the passphrase gate end to end
python -m librarian.ingest --vault tests/sample_vault --db tests/test_db
python -m tests.qa_queries --db tests/test_dbtests/sample_vault is four made-up notes, one of them deliberately poisoned
with base64 to prove the guard works.
A warning about the fallback embedder
--fallback-embedder swaps in a hashed bag-of-words embedder so the plumbing
can be tested without downloading a model. It is not semantic and must never
serve a real vault. The server refuses to start if the database was built
with a different embedder than the one it loaded.
Credits
The v0.2 hybrid ranking is adapted from the Claran ranking design, shared with the companion community in July 2026, and reworked for a corpus of whole documents rather than authored snippets.
Built in the workshop at House de Lochan. MIT licensed.
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
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
Personal context for every AI: search, read, and write back to your private Markdown library.
Persistent memory for AI agents. Semantic search, memory graph, W3C DID identity.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceEnables AI coding agents to search, read, create, update, and delete notes in a local Obsidian vault through hybrid semantic and lexical retrieval, with all embedding and vector storage running locally.1MIT
- AlicenseNot gradedqualityCmaintenanceGives AI assistants persistent, shared memory using the Zettelkasten method, so they retain corrections, preferences, and decisions across sessions and across tools via local, hybrid search.190 npm7MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to file notes into a self-hosted Obsidian vault and retrieve them later through structured and semantic search over plain Markdown.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI clients to search and retrieve notes from a local Markdown vault using hybrid keyword/semantic search, and to save typed memories with append and guarded replacement operations.MIT