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
configure_vault	Point the server at a vault at runtime (if not set via --vault)
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.

Pro users can enable --inline-tracking to write retrieval_count directly into YAML frontmatter (visible natively in Obsidian, queryable via Dataview).

Pro tier

The free tier is fully featured for most use. Pro unlocks convenience features for power users:

• --inline-tracking — write retrieval counts into note frontmatter instead of sidecar files
• Priority email support from the developer
• Future premium features ship Pro-unlocked by default

License activation — any one of these works:

# 1. Environment variable (good for shell profiles)
export HEBBIAN_VAULT_LICENSE="eyJhbGc..."

# 2. CLI flag (good for one-off testing)
hebbian-vault --license-key "eyJhbGc..." --vault ~/my-vault

# 3. Config file (good for permanent install)
echo "eyJhbGc..." > ~/.hebbian-vault/license.jwt

Licenses are verified fully offline — no phone-home, no activation server. Get a license: [coming soon — Dodo Payments storefront in verification].

Options

hebbian-vault --vault PATH          Path to Obsidian vault
              --inline-tracking     [Pro] Write tracking to file frontmatter
              --license-key KEY     Pro license JWT (also reads HEBBIAN_VAULT_LICENSE env)
              --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