freshvault

freshvault

한국어 · 日本語

你的 Obsidian 知识库就是 Claude 的记忆。始终保持最新，始终留在本地。

其他所有知识库搜索 MCP 都需要你重新运行索引命令、守着监控终端，或在 Web 界面中点击“更新索引”。freshvault 在 MCP 服务内部监控你的知识库：编辑一条笔记，几秒后 Claude 就能看到。自动完成，永远如此。

• 🔄 无需重新索引——文件监控器运行在服务进程中；启动时会补齐离线期间的更改
• 🔒 100% 本地运行——通过 Ollama（bge-m3）生成嵌入，你的笔记绝不会离开你的设备
• 🌏 默认支持多语言——bge-m3 支持韩语、日语及 100 多种语言，而仅支持英语的默认方案无法做到这一点
• 🎯 由基准测试驱动的检索——无条件融合 BM25 会严重损害韩语释义查询（top-1 从 82.5% 降至 47.5%），因此已关闭；纯稠密检索则完全无法命中标识符查询（57.1%），所以也没有弃用。词法评分仅在查询词元类似代码时启用：释义查询 82.5% → 82.5%（不变），标识符查询 57.1% → 100% — 测试结果
• 🪶 无需向量数据库、Docker 或 Python——JSON 元数据 + Float32 sidecar，纯 Node，源代码一眼就能看完
• 🧠 遵循句子边界的分块——剥离 YAML frontmatter，按段落／句子边界拆分（支持 CJK）

安装

前置条件：Node 20+ 和 Ollama。

npx -y freshvault setup

就这么简单。向导会检测你的 Obsidian 知识库、拉取嵌入模型、构建索引，并注册到 Claude Code。没有第二步，以后也永远不需要第二步：无需重新运行 index 命令，无需监控终端，也无需后台服务。

{
  "mcpServers": {
    "freshvault": {
      "command": "npx",
      "args": ["-y", "freshvault", "serve"],
      "env": { "FRESHVAULT_VAULT": "/absolute/path/to/your/vault" }
    }
  }
}

claude mcp add freshvault -s user -- npx -y freshvault serve

使用

直接向 Claude 询问你的笔记：

“搜索我的笔记，查找我写过的缓存淘汰策略”

三个工具，全部只读：

竞品需要通过设置或付费墙才能使用的范围限定查询，在这里可以按查询逐次使用：

“搜索我标记为 #project 且在 6 月之后修改过的笔记，查找预算讨论”

工作原理

Obsidian vault ──fs.watch──▶ freshvault MCP server ──search_notes──▶ Claude
   (.md files)               (chunks → bge-m3 embeddings              (generation)
                              → one JSON index, incremental)

• 增量式：只对已更改或已删除的笔记重新生成嵌入向量（比较修改时间和大小），防抖时间为 4 秒
• 安全保障：每 60 秒进行一次修改时间扫描，捕获监视器遗漏的事件（网络驱动器、使用原子重命名的编辑器）
• 支持多客户端安全使用：第一个启动的服务进程成为写入者（通过心跳维持锁）；其他进程作为读取者热重载，并在写入者退出时提升为写入者
• 事务性：即使索引期间嵌入服务中断，也绝不会丢失或损坏笔记
• 可扩展性：向量存储在紧凑的 Float32 旁路文件中（启动快、体积小）；对数千个文本块进行暴力余弦相似度计算只需几毫秒。坦诚地说：搜索仍是线性搜索——数万个文本块也能在 100 毫秒内完成，但它不能替代用于超大型语料库的向量数据库

多个知识库

每个知识库注册一个服务——索引文件会自动按知识库分别保存：

claude mcp add work-vault -s user -e FRESHVAULT_VAULT=/path/to/work -- npx -y freshvault serve
claude mcp add personal-vault -s user -e FRESHVAULT_VAULT=/path/to/personal -- npx -y freshvault serve

其他嵌入服务（LM Studio、LiteLLM、兼容 OpenAI 的服务）

FRESHVAULT_EMBED_API=openai FRESHVAULT_EMBED_URL=http://localhost:1234 npx -y freshvault serve

任何支持 /v1/embeddings 的服务都能使用；对于需要身份验证的端点，可使用 FRESHVAULT_EMBED_KEY（绝不会写入配置文件）。

配置

运行 setup 后，无需配置即可使用。需要时可覆盖默认值：

命令：setup · serve（默认）· index（手动备用选项）· status

忽略模式

模式遵循 gitignore 语义，并根据知识库相对路径进行匹配：

• 除末尾之外，模式中任意位置的斜杠都会将模式锚定到知识库根目录。末尾的斜杠只表示“目录”——不会将模式锚定到根目录。
• * 和 ? 不会跨越 /。** 只有作为完整路径段时才会跨越目录（**/x、x/**、x/**/y）；如果与路径段相连，则会像 git 一样折叠为单个 *。
• 匹配以路径段边界为止——Templates 永远不会匹配 TemplatesOld。
• 不支持 ! 取反和字符类；此类模式不会匹配任何内容。
• FRESHVAULT_IGNORE 使用逗号分隔，因此模式中不能包含逗号。

自 v0.3.0 起的行为变更。 v0.3.0 将末尾的斜杠视为根目录锚点，因此 Templates/ 只会排除知识库根目录下的 Templates/，并悄无声息地索引所有嵌套目录——没有警告，只会悄悄污染索引。现在，形如 Templates/、/Templates、**/x 和 a/**/b 的模式会比以前排除更多内容（/Templates 以前完全不匹配）。反过来，嵌在路径段中的 **（Daily**md）现在不会再跨越 /。升级后运行 freshvault status，如果你在意排除数量，请对比查看。

基准测试

项目仓库中附带两个检索微基准（node scripts/bench.mjs）：ko-bench（30 条韩语笔记，40 个释义查询）和 id-bench（38 条技术笔记，14 个标识符查询）。两者均采用三种评分模式运行——密集、始终混合，以及随附的门控模式——脚本本身会检查是否符合无回退约定。结果和 bge-m3-ko（top-1 准确率 85.0%，634MB）的导入指南见 docs/ko-bench.md。

路线图

• 用于一键安装 Claude Desktop 的 MCPB 包
• 面向大型知识库的重排序环节
• 在建立索引时提取 PDF 文本

许可证

MIT © Kioko Lab