Hebbian Vault

io.github.onetrueclaude-creatorPublished by GitHub account onetrueclaude-creatorv0.2.0Updated Oct 25, 2026

Usage-adaptive Obsidian vault search: Hebbian + PageRank + BM25 hybrid ranking.

VerifiedSTDIODesktop onlyFiles & StorageKnowledge & MemoryData & Analytics

Overview

AI-generated overview

A local MCP server that gives an assistant hybrid, usage-adaptive search over an Obsidian vault, combining keyword, link-graph and usage signals.

What you can do
Search the vault with hybrid ranked results that blend keyword relevance, link-graph centrality and past usage, with recency decay. Read individual notes including frontmatter, links and usage metadata. Explore connected notes through wikilinks one or two hops out. List the most-used files and get vault analytics such as file and link counts, orphans and hubs. Run a structural health check for broken links and orphans. Point the server at a vault at runtime if no path was given at startup.
When to use it
Useful when you keep notes in an Obsidian vault and want an assistant to find and read them with better ranking than plain keyword search, especially in a large or densely linked vault. Also suited to checking vault structure for broken links and orphan notes.
Requirements
Runs locally as a Python package (Python 3.10 or later), typically started with uvx or pip. Needs the path to an Obsidian vault, given at startup or through the configure tool. No Obsidian app or cloud service is required. A Pro license JWT is optional and can be supplied via the HEBBIAN_VAULT_LICENSE environment variable, a CLI flag or a config file.
Before you install
Search and read calls increment per-file retrieval counts, and tracking data is written to a sidecar directory inside the vault by default; the Pro inline-tracking option instead writes retrieval counts into note frontmatter. The Pro license is a paid credential, and the purchase storefront is not yet available. The server reads vault files directly from disk.

Installation

In SourceWeft

  1. Open Hebbian Vault in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

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

bash
pip install hebbian-vault

Usage

Claude Code

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

Claude Desktop

Add to claude_desktop_config.json:

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

Direct

bash
hebbian-vault --vault ~/my-vault

MCP Tools

ToolDescription
configure_vaultPoint the server at a vault at runtime (if not set via --vault)
vault_searchHybrid ranked search (BM25 + PageRank + Hebbian)
vault_readRead a note with frontmatter, links, and Hebbian metadata
vault_neighborsFind connected notes by wikilinks (1-hop or 2-hop)
vault_hotTop-N most-used files by Hebbian score
vault_statsVault analytics (files, links, orphans, hubs)
vault_healthStructural 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:

bash
# 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

Source: README.md at commit 57a9569

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.2.0LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts