Vault Recommender

保险库推荐器

 

黑曜石金库的语义推荐引擎。使用句子变换器嵌入+维基链接图增强来显示相关笔记、遗忘的知识和缺失的连接。

作为LLM的工具而设计——返回上下文丰富的结果和解释，而不仅仅是排名路径。

运作原理

Your vault (markdown files)
       │
   Parser ─── extracts frontmatter, body, wiki-links
       │
   Indexer ─── embeds each note as a 384-dim vector (all-MiniLM-L6-v2)
       │
   Link Graph ─── builds bidirectional wiki-link adjacency
       │
   Recommender ─── cosine similarity + graph boost + staleness boost
       │
   Ranked results with reasons

三个得分信号：

• 语义相似性 --音符嵌入之间的余弦距离。抓住意义，而不仅仅是关键词。
• 链接图增强 --通过wiki链接连接的笔记会出现碰撞。2跳邻居（通过共享链路连接）表面“桥接”连接。
• 增强稳定性 --30多天未被触碰的笔记会得到小幅提升。表面被遗忘，但相关知识。

安装

# From PyPI
uv tool install vault-recommender

# Or from source
git clone https://github.com/JoshuaOliphant/vault-recommender.git
cd vault-recommender
uv sync

用法

命令行界面

# Build the index (run once, re-run when vault changes significantly)
vault-recommender --vault /path/to/vault index

# Recommend by topic
vault-recommender --vault /path/to/vault recommend --topic "career transition strategies"

# Recommend notes similar to a specific note
vault-recommender --vault /path/to/vault recommend --note "areas/career/plan.md"

# Find missing connections (similar but not linked)
vault-recommender --vault /path/to/vault recommend --note "areas/career/plan.md" --exclude-linked

# Auto-rebuild stale index before querying
vault-recommender --vault /path/to/vault recommend --topic "python testing" --rebuild

# JSON output (for LLM consumption)
vault-recommender --vault /path/to/vault recommend --topic "python testing" --json

这 --rebuild 标志检查是否有任何vault文件比索引新。如果是这样，它会在查询之前自动重建。如果索引是新的，它会悄无声息地跳过。

HTTP服务器（用于钩子和快速查询）

CLI冷启动主题查询上的嵌入模型（~13秒）。对于像Claude Code钩子这样对延迟敏感的用例，请运行HTTP服务器：

# Start the server (loads index once, then serves fast queries)
vault-recommender --vault /path/to/vault serve

# Custom host/port
vault-recommender --vault /path/to/vault serve --host 0.0.0.0 --port 8000

终点：

# Health check
curl localhost:7532/health

# Recommend by topic
curl "localhost:7532/recommend?topic=career+transition&top_k=5"

# Recommend by note
curl "localhost:7532/recommend?note=areas/career/plan.md&top_k=3"

# Find missing connections
curl "localhost:7532/recommend?note=areas/career/plan.md&exclude_linked=true"

# Hot-reload index after re-indexing via CLI
curl -X POST localhost:7532/reload

MCP服务器（克劳德代码集成）

添加到您的 .mcp.json:

{
  "mcpServers": {
    "vault-recommender": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/vault-recommender",
        "python",
        "-m",
        "vault_recommender.mcp_server"
      ],
      "env": {
        "VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

这暴露了四个工具：

• recommend_by_topic --开放式语义搜索
• recommend_by_note --“像这样的笔记”
• find_missing_connections --类似但未链接的笔记
• reload_index --通过CLI重新索引后强制重新加载索引

Python API

from pathlib import Path
from vault_recommender.recommender import create_recommender

vault = Path("/path/to/vault")
index_dir = Path(".vault-recommender-index")

rec = create_recommender(vault, index_dir)

# By topic
results = rec.similar_to_topic("career transition")

# By note
results = rec.similar_to_note("areas/career/plan.md")

# Each result has: path, title, score, snippet, tags, reason
for r in results:
    print(f"{r.score:.3f} {r.title} — {r.reason}")

演出

• 约5秒内索引约1500个音符（M系列Mac）
• 查询在\<1秒内返回（模型预热后）
• 索引以numpy+JSON格式保存（1500个音符约2MB）
• 型号： all-MiniLM-L6-v2 （约80MB，在CPU上运行）
• --help 立即响应（大量进口推迟到需要时）

需求

• Python 3.12+
• 黑曜石保险库（或任何带有标记文件的目录） [[wiki-links]])

许可证

麻省理工学院