hebbian-vault
Provides intelligent, use-adaptive search and management for Obsidian vaults, using BM25, Personalized PageRank, and Hebbian learning signals, with tools for searching, reading, navigating, and analyzing vault content.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@hebbian-vaultfind notes about Hebbian learning"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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-vaultUsage
Claude Code
claude mcp add hebbian-vault -- hebbian-vault --vault ~/my-vaultClaude Desktop
Add to claude_desktop_config.json:
{
"mcpServers": {
"hebbian-vault": {
"command": "uvx",
"args": ["hebbian-vault", "--vault", "/path/to/vault"]
}
}
}Direct
hebbian-vault --vault ~/my-vaultMCP Tools
Tool | Description |
| Point the server at a vault at runtime (if not set via |
| Hybrid ranked search (BM25 + PageRank + Hebbian) |
| Read a note with frontmatter, links, and Hebbian metadata |
| Find connected notes by wikilinks (1-hop or 2-hop) |
| Top-N most-used files by Hebbian score |
| Vault analytics (files, links, orphans, hubs) |
| 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 filesPriority 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.jwtLicenses 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 toolsconfigure_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.
| Name | Required | Description | Default |
|---|---|---|---|
| vault_path | Yes | ||
| inline_tracking | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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_healthARead-only
Structural integrity check: broken links, orphaned leaves, missing frontmatter. Returns a list of issues found.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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_hotARead-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.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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_neighborsBRead-only
Find notes connected to a given note by wikilinks. Shows both outgoing and incoming links, with PageRank scores for prioritization.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| depth | No | ||
| limit | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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_searchA
Search the vault with hybrid ranking. Results are ranked by keyword relevance, graph centrality, and usage frequency merged via Reciprocal Rank Fusion. Each returned result strengthens that file's future ranking (Hebbian learning).
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes | ||
| include_content | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses hybrid ranking components (keyword, graph, usage), RRF merging, and Hebbian learning, adding value beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three succinct sentences with no fluff; each sentence adds meaningful information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers main behavior and side effects well; lacks parameter details but output schema exists. Minor gap.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No description of parameters despite 0% schema coverage; query, limit, include_content are unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it searches the vault with hybrid ranking, distinguishes from siblings like vault_hot or vault_neighbors.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Implies usage for hybrid search but provides no explicit guidance on when to use vs siblings or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
vault_statsARead-only
Vault-level analytics: file count, link count, orphans, broken links, average connectivity, and top hub pages by PageRank.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
7 tool updates
v0.2.0- First observed
configure_vault - First observed
vault_health - First observed
vault_hot - First observed
vault_neighbors - First observed
vault_read - First observed
vault_search - First observed
vault_stats
TDQS
Scored across 7 tools
Each tool has a clearly distinct purpose: setup, search, read, graph navigation, hot files, stats, health. No overlapping functionality.
Most tools follow a 'vault_' prefix pattern, but 'configure_vault' breaks the pattern by placing 'vault' at the end, introducing minor inconsistency.
With 7 tools, the server covers essential operations for analyzing an Obsidian vault without unnecessary bloat or gaps.
The tool set provides strong read/analysis capabilities but lacks write operations (create, update, delete notes), which limits full vault interaction.
Maintenance
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
Token-efficient MCP memory for Markdown vaults. Tiered search, GraphRAG, AI memories.
Personal knowledge base MCP server with semantic search, auto-categorization, metadata extraction
Capability registry for the agentic economy. Semantic search over verified MCP server listings.
Related MCP Servers
- AlicenseNot gradedqualityAmaintenanceMCP server that indexes Obsidian notes and enables hybrid search (full-text, fuzzy, semantic) for AI assistants to find and read notes.936102MIT
- FlicenseBqualityDmaintenanceA lightweight MCP server for intelligent, non-invasive analysis of Obsidian vaults.4-
- AlicenseNot gradedqualityBmaintenanceSelf-hosted MCP server that provides embedding-powered semantic search with graph context over Obsidian vaults, supporting multiple vaults, local embeddings, and a web dashboard.MIT
- AlicenseNot gradedqualityCmaintenanceAn MCP server that provides always-fresh semantic search over Obsidian vaults, automatically watching file changes and using local embeddings via Ollama.166MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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