mdvault
 
您的Markdown笔记，可在Claude Code中搜索。
索引任何文件夹 .md 档案——黑曜石保险库， ~/.claude/ 历史、项目文档——并直接从Claude Code或终端以自然语言搜索它们。零基础设施。一 .db 文件。
它做什么
搜索结合了FTS5 BM25和256个弱矢量，与RRF融合，并在7个信号上重新排序（术语覆盖、航向匹配、路径匹配等）。
每个块都以其文档上下文作为前缀([path > title > heading])在索引之前，请遵循 人类学语境检索 方法。
其他值得了解的事情：
- 解析Markdown链接和
[[wikilinks]]，查找反向链接和类似文件 - 通过本地Ollama LLM进行可选查询扩展
- 记忆会随着时间的推移而衰退，被击中时会获得信心，并从重复的查询中自动提升
- 锂基-8M 嵌入式，仅限CPU，约30MB下载
- 增量索引（SHA256更改检测，仅重新处理更改的内容）
- MCP服务器，以便Claude Code可以直接搜索您的保险库
- 一切尽在一
.db文件（FTS5索引+向量+链接图+元数据）
快速开始
粘贴 install https://github.com/sderosiaux/mdvault 在Claude Code中，它将遵循以下步骤。1.安装
uv tool install mdvault2.将笔记编入索引
mdvault index ~/.claude/
# Keep rotated session logs in the index even after Claude Code deletes them
mdvault index ~/.claude/ --keep-deleted projects3.添加MCP服务器 到 ~/.claude/mcp.json:
{
"mcpServers": {
"mdvault": { "command": "uvx", "args": ["mdvault", "serve"] }
}
}4.重新启动克劳德代码，然后问： *“在我的笔记中搜索kubernetes设置”*
保持索引新鲜
索引是增量的（SHA256变化检测）。设置一个cron以保持更新：
# Every 30 minutes
(crontab -l; echo '*/30 * * * * uvx mdvault index ~/.claude/ 2>/dev/null') | crontab -其他安装方法
uvx mdvault --help # run without installing
pipx install mdvault # without uv示例
$ mdvault search "memory system LLM"
[1] 0.983 .claude/projects/.../ae863d59.jsonl:70
### Dedicated Memory Platforms
- **Mem0**: Universal memory layer. $24M raised (YC-backed).
41K GitHub stars, 13M+ PyPI downloads...
[2] 0.870 .claude/projects/.../agent-a581b10.jsonl:2
## The mapping: CPU, RAM, disk, I/O
Andrej Karpathy posted in October 2023 that LLMs should be
understood "not as a chatbot, but the kernel process of a new OS."CLI使用情况
# Index your notes (downloads ~30MB model on first run)
mdvault index ~/.claude/
# Incremental update (only changed/new/deleted files)
mdvault index ~/.claude/ --incremental
# Retain entries when matching files are removed from disk (repeatable).
# Pattern is a path prefix or fnmatch glob, relative to the vault root.
# --full also honors keep-deleted: it rebuilds from disk while preserving
# matching entries. Drop the flag to wipe everything.
mdvault index ~/.claude/ --keep-deleted projects --keep-deleted '*.jsonl'
# Search
mdvault search "nginx reverse proxy config"
mdvault search "ssh tunnel" --top-k 10
# Search with query expansion (requires Ollama running locally)
mdvault search "ssh tunnel" --expand
mdvault search "ssh tunnel" --expand --expand-model qwen3:0.6b # default model
# Related notes: links, backlinks, and semantically similar files
# (file path is relative to the vault root)
mdvault related path/to/note.md
# Stats (includes memory & query analytics)
mdvault stats
# Store a memory (searchable alongside your files)
mdvault remember "Kafka timeout is controlled by max.poll.interval.ms"
# List stored memories (with confidence, hits, decay)
mdvault memories
# Show knowledge gaps (recurring queries with poor results)
mdvault gaps
# Delete a memory
mdvault forget
# Custom DB location
mdvault index ~/.claude/ --db ~/vault.db
mdvault search "query" --db ~/vault.db克劳德代码集成（MCP）
添加 ~/.claude/mcp.json:
{
"mcpServers": {
"mdvault": {
"command": "uvx",
"args": ["mdvault", "serve"],
"env": {
"VAULT_DB": "/absolute/path/to/vault.db"
}
}
}
}如果 VAULT_DB 省略，默认为 ~/.local/share/mdvault/vault.db （Linux）或 ~/Library/Application Support/mdvault/vault.db （macOS）。
暴露的MCP工具：
| 工具 | 说明 |
|---|---|
search_vault | 混合BM25+语义搜索。筛选依据 vault, source, namespace |
related_notes | 给定注释的链接、反向链接和语义相似的文件 |
store_memory | 存储内存（自动分块，可与文件一起搜索） |
delete_memory | 按id或命名空间删除内存 |
然后问Claude一些事情，比如“搜索我的笔记，了解我是如何配置SSH隧道的”或“哪些笔记与我的kubernetes设置有关？”。
搜索管道
Query
├── FTS5 BM25 search → top-75 (NEAR bigrams + focused AND clause)
└── Vector search → top-75 nearest neighbors
│
▼
Reciprocal Rank Fusion (k=15, BM25 weight 4×)
│
▼
Re-ranking (7 signals)
├── Cosine similarity (continuous, from vec distance)
├── Query term coverage (squared, bonuses at ≥80% and 100%)
├── First-chunk coverage (intro paragraph = topic signal)
├── Heading match (H2/H3 vs query terms)
├── Title match (H1 vs query terms)
├── Path match (filename + parent dirs vs query terms)
└── Overview boost (about/intro pages with high coverage)
│
▼
Content-hash dedup → top-N results文件被拆分 ##/### 标题（最多400字，50字重叠，小部分合并）。每个块都有一个上下文前缀([path > title > heading])在嵌入和FTS索引之前。
查询扩展(--expand)呼叫本地 奥拉玛 模型（默认值： qwen3:0.6b)生成相关文档可能包含的段落，然后将其附加到原始查询中进行矢量搜索。BM25始终使用原始查询。拉动模型 ollama pull qwen3:0.6b.
回忆
记忆可以与文件一起搜索。幕后发生了三件事：
腐烂。 记忆会在180天内消失（0.1层）。每次搜索点击都会重置时钟。定期搜索一些东西，它就会保持相关性。停下来，它的排名就会下降。
信心。 基础分数取决于来源(user=0.7, agent=0.5, promoted=0.3）加上对数命中率提升（上限为+0.3）。不断匹配的记忆爬得更高。
汽车促销。 每个搜索都会被记录下来，并通过嵌入相似性（余弦>0.85）进行聚类。当一个集群出现5+次时：
- 好成绩（平均成绩>=0.3）：最好的成绩会成为永久记忆
- 不良结果（平均得分\<0.15）：记录了知识差距
Search query
├── query_log + query_vec (logged)
├── hit tracking on memory results
└── every 20 queries:
├── cluster_recent_queries (embedding similarity)
└── maybe_promote (crystallize or flag gap)跑 mdvault gaps 看看你一直在寻找什么，但找不到。
技术栈
局限性
- 英语优化：基于药水的8M主要接受英语培训。语义搜索在其他语言上降级（BM25关键字搜索仍然有效）
- 仅限Markdown（无PDF、DOCX）
- 精确向量搜索——在商品硬件上可扩展到约50万个块
发展
git clone https://github.com/sderosiaux/mdvault
cd mdvault
uv sync --dev
uv run pytest -q安装预提交挂钩（褶皱+格式）：
uv run pre-commit install许可证
麻省理工学院