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

# 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

# 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

{
  "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"
      }
    }
  }
}

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}")