Skip to main content
Glama

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.

Related MCP server: background-vault-analysis

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

Available Tools

7 tools
configure_vaultA

Configure the vault path for this server. Call this first if the server started without a --vault argument. The vault_path must be an absolute path to an Obsidian vault directory containing .md files.

ParametersJSON Schema
NameRequiredDescriptionDefault
vault_pathYes
inline_trackingNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations indicate write operation (readOnlyHint: false). The description adds calling condition and path constraints but does not disclose side effects like overwriting existing configuration or reversibility.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with purpose, no wasted words. Efficient and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity and the presence of an output schema, the description covers essential usage: purpose, when to call, and parameter constraint. Missing explanation of inline_tracking is acceptable due to default value.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%; description adds meaning for vault_path (absolute path, .md files) but ignores inline_tracking. The added value for vault_path compensates partially for the lack of schema description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool configures the vault path for the server, with specific conditions and constraints. It distinguishes from sibling tools like vault_search and vault_read by emphasizing setup.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description explicitly says to call this first if the server started without a --vault argument, providing clear when-to-use context. It lacks explicit when-not-to-use, but the condition is well-defined.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vault_healthA
Read-only

Structural integrity check: broken links, orphaned leaves, missing frontmatter. Returns a list of issues found.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, so the description adds value by specifying the types of issues checked and that it returns a list. No contradictions. With annotations, the bar is lower, and the description adds meaningful behavioral context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences: the first describes the purpose, the second the return type. No extraneous information. Front-loaded with main purpose.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters, readOnlyHint annotations, and an output schema (present), the description adequately covers what the tool does and returns. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist (0 params, 100% schema coverage). Per guidelines, baseline is 4. The description does not need to add param info, and it doesn't repeat what's in the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool performs 'Structural integrity check' and lists specific types of issues (broken links, orphaned leaves, missing frontmatter). This clearly differentiates it from sibling tools like vault_search or vault_read.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies the tool should be used to check vault health, but it does not explicitly state when to use it vs. alternatives or provide any exclusions. The context from sibling hints are not utilized.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vault_hotA
Read-only

Top-N most-used files by Hebbian score (usage frequency weighted by recency). Shows what the vault considers most important based on actual usage patterns.

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations declare readOnlyHint=true; the description adds detail on the scoring method (Hebbian, recency-weighted), which provides behavioral context beyond the annotation. No contradictions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loaded with the key action and metric, and every word adds value. No unnecessary phrasing.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (one optional parameter, output schema present), the description is complete: it conveys purpose and behavioral logic. The output schema covers return format, so no further explanation is needed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0% and the single parameter `limit` is not described in the description. The description should clarify that `limit` controls the number of returned top files, which is its sole effect. With low coverage, the description must compensate but does not.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns top-N files by Hebbian score weighted by recency. It distinguishes from sibling tools like vault_search (general search) and vault_neighbors (graph neighbors), making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for finding important files but does not explicitly state when to use this tool over alternatives or provide exclusions. No guidance on context like when the vault is empty or when recency matters.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vault_neighborsB
Read-only

Find notes connected to a given note by wikilinks. Shows both outgoing and incoming links, with PageRank scores for prioritization.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes
depthNo
limitNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already indicate readOnlyHint=true. Description adds that it shows bidirectional links and PageRank scores, but does not disclose performance implications of depth/limit parameters or any other behavioral traits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences with no wasted words. Front-loaded with action and resource, followed by details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description fails to explain the two optional parameters (depth, limit) which are critical for usage. It also does not mention any prerequisites or context about the vault. For a tool with three parameters, this is insufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With 0% schema description coverage, the description only implicitly explains the 'path' parameter (the note's path). The 'depth' and 'limit' parameters are not explained at all, leaving the agent to guess their semantics.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the tool finds notes connected via wikilinks, listing both outgoing and incoming links with PageRank scores. This uniquely identifies its purpose among siblings like vault_search and vault_read.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description does not provide explicit guidance on when to use this tool versus alternatives. It only states what it does, leaving the agent to infer context. No exclusions or alternative tool references.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vault_readA

Read a single vault note by relative path. Returns full content with parsed frontmatter, outgoing links, and incoming links. Strengthens the file's Hebbian score.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.2/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations set readOnlyHint to false, and the description adds a side effect ('Strengthens the file's Hebbian score'). Contradiction is false. The description also discloses that it parses frontmatter and links, providing useful behavioral context beyond the schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences with no extraneous information. First sentence covers action and returns; second sentence adds a key side effect. Every word earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description adequately covers return elements (frontmatter, links) and the side effect (Hebbian score). It could mention that it reads a single note (not bulk), but that is implied. Overall, it is complete for a read tool with side effects.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The only parameter 'path' has no schema description (0% coverage). The description clarifies it is a 'relative path,' adding meaningful semantic guidance. However, it does not explain the base directory or format.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('Read a single vault note by relative path') and the resource ('vault note'). It also specifies return content (frontmatter, links) and distinguishes from sibling tools like vault_search.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for reading a specific note by path but does not explicitly state when to use this tool versus alternatives (e.g., vault_search for searching, vault_neighbors for links). No exclusions or prerequisites are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

vault_statsA
Read-only

Vault-level analytics: file count, link count, orphans, broken links, average connectivity, and top hub pages by PageRank.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already provide readOnlyHint=true. Description adds value by listing the specific analytics returned (file count, link count, orphans, etc.), offering behavioral context beyond safety.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with key terms, no fluff. Efficient and to the point.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, existing annotations, and an output schema, the description fully covers the tool's purpose and data. No missing elements.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, so schema coverage is 100%. Baseline 4 for 0 params. Description adds no parameter info, which is acceptable.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states tool provides vault-level analytics listing specific metrics like file count, link count, orphans, etc. It distinguishes from sibling tools such as vault_search or vault_read, which focus on different operations.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Description implies use for getting high-level vault stats, but does not explicitly state when not to use or provide alternatives. Context from sibling names helps, but lacks explicit guidance.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 7 tool updatesv0.2.0
    • First observedconfigure_vault
    • First observedvault_health
    • First observedvault_hot
    • First observedvault_neighbors
    • First observedvault_read
    • First observedvault_search
    • First observedvault_stats

TDQS

A3.9/5.0

Scored across 7 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: setup, search, read, graph navigation, hot files, stats, health. No overlapping functionality.

Naming Consistency4/5

Most tools follow a 'vault_' prefix pattern, but 'configure_vault' breaks the pattern by placing 'vault' at the end, introducing minor inconsistency.

Tool Count5/5

With 7 tools, the server covers essential operations for analyzing an Obsidian vault without unnecessary bloat or gaps.

Completeness3/5

The tool set provides strong read/analysis capabilities but lacks write operations (create, update, delete notes), which limits full vault interaction.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/onetrueclaude-creator/hebbian-vault'

If you have feedback or need assistance with the MCP directory API, please join our Discord server