hebbian-vault 0.1.0

MCP server that adds intelligent, use-adaptive search to Obsidian vaults. Your vault remembers what matters.

hebbian-vault

MCP server for intelligent, use-adaptive Obsidian vault search.

Your vault remembers what matters. Files you use strengthen. Unused files fade. Hub pages surface first. Search gets better over time.

What it does

Unlike standard Obsidian search (keyword matching), hebbian-vault uses four signals merged via Reciprocal Rank Fusion:

• BM25 -- keyword relevance (like standard search, but ranked)
• Personalized PageRank -- graph centrality biased toward your query (hub pages surface first)
• Hebbian usage -- files you actually use rank higher, with recency decay
• RRF merge -- combines all signals without weight tuning

Works with any Obsidian vault. No cloud. No Obsidian running required. Direct filesystem access.

Install

pip install hebbian-vault

Usage

Claude Code

claude mcp add hebbian-vault -- hebbian-vault --vault ~/my-vault

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "hebbian-vault": {
      "command": "uvx",
      "args": ["hebbian-vault", "--vault", "/path/to/vault"]
    }
  }
}

Direct

hebbian-vault --vault ~/my-vault

MCP Tools

Tool	Description
vault_search	Hybrid ranked search (BM25 + PageRank + Hebbian)
vault_read	Read a note with frontmatter, links, and Hebbian metadata
vault_neighbors	Find connected notes by wikilinks (1-hop or 2-hop)
vault_hot	Top-N most-used files by Hebbian score
vault_stats	Vault analytics (files, links, orphans, hubs)
vault_health	Structural integrity check (broken links, orphans)

How Hebbian learning works

Every time vault_search or vault_read returns a file, that file's retrieval count increments. Files accessed recently get a recency boost. Files untouched for weeks decay. Over time, the vault develops a "heat signature" -- frequently useful files strengthen, rarely useful files fade.

This is Hebbian learning applied to information retrieval: "neurons that fire together wire together." Your vault adapts to how you actually use it.

Storage

By default, tracking data is stored in a .hebbian/ sidecar directory inside your vault. Your markdown files are not modified.

Use --inline-tracking to write retrieval_count directly into YAML frontmatter (visible in Obsidian).

Options

hebbian-vault --vault PATH          Path to Obsidian vault (required)
              --inline-tracking     Write tracking to file frontmatter
              --transport TYPE      stdio (default) or streamable-http
              --port PORT           Port for HTTP transport (default: 8000)

Requirements

• Python 3.10+
• An Obsidian vault (any size, wikilinks recommended for graph features)

License

MIT