Skip to main content
Glama
mlorentedev

hive

by mlorentedev
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

hive-vault

CI codecov PyPI Python 3.12+ Docs License: MIT

Your AI coding assistant forgets everything between sessions. Hive fixes that.

Hive is an MCP server that connects your AI assistant to an Obsidian vault. Instead of loading everything upfront, it queries only what's needed — on demand.

Metric

Without Hive

With Hive

Context loaded per session

~800 lines (static)

~50 lines (on demand)

Token cost for context

100% every session

6% average per query

Knowledge retained between sessions

0%

100% (in vault)

Measured on a real vault with 19 projects, 200+ files. See benchmarks.

Quick Start

Hive runs without a vault — vault tools return a friendly error until VAULT_PATH is set, so you can install first and configure later.

# Minimal — uses default vault path ~/Projects/knowledge
claude mcp add -s user hive -- uvx --upgrade hive-vault

# With a custom vault path
claude mcp add -s user hive -e VAULT_PATH=$HOME/path/to/vault -- uvx --upgrade hive-vault

# Gemini CLI
gemini mcp add -s user -e VAULT_PATH=$HOME/path/to/vault hive-vault uvx -- --upgrade hive-vault

Default vault path: ~/Projects/knowledge. Override with VAULT_PATH (or HIVE_VAULT_PATH) as shown above.

For Codex CLI, GitHub Copilot, Cursor, Windsurf, and other clients, see Getting Started.

Then ask your assistant: "Use vault_list to see my vault"

Related MCP server: Obsidian MCP

Requirements

Hive degrades gracefully — every recommended or optional dependency reveals more capability without breaking the baseline.

  • Required

    • Python 3.12+ (works on 3.13).

    • A directory of markdown files. The vault structure used by 00_meta / 10_projects / 50_work / 80_agents is optional — without it, vault tools still operate but the scope routing is flat.

  • Recommended

    • git initialised inside the vault. Without it, vault_write / vault_patch still write to disk; they just skip the per-write commit (and vault_commit reports the working tree as untracked).

    • The Obsidian desktop app to author the vault by hand.

    • The obsidian-git plugin with auto-commit set to 5–10 minutes. Pair it with vault_write(commit=False) / vault_patch(commit=False) to push the git workload off the synchronous tool path; see Recommended configuration below.

  • Optional

    • Ollama running qwen2.5-coder:7b (or compatible) for local, free delegate_task / capture_lesson worker calls.

    • An OpenRouter API key (OPENROUTER_API_KEY) as a free-tier and paid fallback worker.

    • A backup git remote (e.g. private GitHub repo) so vault history survives a disk loss.

Recommended configuration

Per ADR-006 (commit policy), the recommended pairing for write-heavy flows is:

  1. Install and enable the obsidian-git plugin in your vault.

  2. Set its auto-commit interval to 5 or 10 minutes.

  3. Call vault_write(..., commit=False) and vault_patch(..., commit=False) for all bulk operations.

  4. Optionally call vault_commit(message="...") at the end of a session to force a checkpoint sooner than the obsidian-git tick.

vault_health reports a ## external_committer block when it detects obsidian-git in the vault. The commit=False durability contract is explicit: files are persisted to disk regardless; only the commit is deferred. A crash before the next flush loses the commit, not the content.

When a tool call is cancelled mid-flight (slow worker, client timeout), the server may have already mutated the disk before the cancel ack reaches the wire. vault_health surfaces a ## ghost_responses counter and emits a mcp.ghost_response.suppressed_after_cancel_ack WARNING for each event — verify state via vault_query rather than retrying, since the ErrorData ack does not imply rollback (ADR-007).

Daemon mode (optional)

The default uvx hive-vault runs a fresh server per session. Daemon mode instead runs one long-lived hive serve that owns the vault, with each session connecting through a thin hive client shim — useful for concurrent sessions, single-owner guarantees (ADR-011), and automatic version adoption. It always degrades to an in-process server if the daemon is down, so it never breaks a session.

uv tool install --upgrade hive-vault   # >= 1.32.0
hive service install                   # supervise hive serve (systemd --user / Task Scheduler)

To install a newer release, use the platform-specific command:

# Linux / macOS
uv tool upgrade hive-vault

# Windows (the version is optional; omitted selects the latest PyPI release)
hive self-upgrade [version]

On Windows, self-upgrade builds the release beside the running files and atomically switches the managed runtime, avoiding in-use-file conflicts. Open a new terminal after the first managed upgrade so its PATH change is available. Once supervised, the daemon detects the new installed version, exits 75, and the supervisor restarts it into the new code. See the daemon mode guide and the activation runbook.

Tools

Tool

What it does

vault_query

Load project context, tasks, roadmap, lessons — or any file by path

vault_search

Full-text search with metadata filters, regex, ranked results, recent changes, lesson-usage ranking (rank_by)

vault_list

Browse projects and files with glob filtering

vault_health

Server identity (version, vault path, backends), health metrics, drift detection, usage stats, opt-in runtime block

vault_write

Create, append, or replace vault files. commit=False defers the git commit for batching

vault_patch

Surgical find-and-replace. commit=False defers the git commit for batching

vault_commit

Flush pending commit=False writes into one git commit

capture_lesson

Capture lessons inline / batch-extract from text / look up existing lessons by keyword (find=)

session_briefing

Tasks + lessons + git log + health in one call

delegate_task

Route tasks to cheaper models or summarize vault files

worker_status

Budget, connectivity, available models

Plus 5 resources and 4 prompts for guided workflows.

Lesson reinforcement

Every read of a lesson via vault_query, vault_search, or capture_lesson(find=…) increments a counter and grows that lesson's confidence asymptotically toward 1.0. Validated lessons rank higher than one-shot captures over time.

# Surface the top-ranked lessons matching a keyword
capture_lesson(project="hive", find="multi-process")

# Search lessons ranked by usage signal (not BM25)
vault_search(query="timeout", rank_by="reinforcements")    # most-reinforced first
vault_search(query="timeout", rank_by="confidence")        # highest decayed confidence
vault_search(query="timeout", rank_by="hybrid")            # α=0.7 BM25 + 0.3 confidence

Storage: SQLite side-table at HIVE_LESSON_DB_PATH (default ~/.local/share/hive/lesson_reinforcement.db). WAL mode + busy_timeout make it cross-process safe.

Architecture

MCP Host (Claude Code, Gemini CLI, Codex CLI, Cursor, ...)
    └── hive-vault (MCP server, stdio)
            ├── Vault Tools (7) ── Obsidian vault (Markdown + YAML frontmatter)
            ├── Session Tools (1) ── Adaptive context assembly
            └── Worker Tools (2) ── Ollama (free) → OpenRouter free → paid ($1/mo cap) → reject

Documentation

Full documentation at mlorentedev.github.io/hive:

Project-bound knowledge (docs-as-code) lives in docs/:

Contributing

See CONTRIBUTING.md for setup and PR workflow.

git clone https://github.com/mlorentedev/hive.git && cd hive
make install   # create venv + install deps
make check     # lint + typecheck + test (478 tests, 90% coverage)

License

MIT

Available Tools

13 tools
capture_lessonA

Capture lessons: inline / batch write, or lookup by keyword.

Inline mode (default): provide title, context, problem, solution. Batch mode: provide text to extract lessons automatically via worker. Lookup mode: provide find to surface top-ranked existing lessons whose heading matches the keyword.

ParametersJSON Schema
NameRequiredDescriptionDefault
findNoKeyword to look up in existing lesson headings (lookup mode).
tagsNoOptional tags (e.g. ["python", "testing"]).
textNoRaw text to extract lessons from (batch mode).
titleNoShort descriptive title (inline mode).
contextNoWhat you were doing (inline mode).
problemNoWhat went wrong or what decision was needed (inline mode).
projectYesProject slug (directory under 10_projects/).
rank_byNoLookup ranking — 'reinforcements' (default), 'confidence', or 'hybrid'. Ignored unless ``find`` is set.reinforcements
solutionNoWhat fixed it or what was decided (inline mode).
max_lessonsNoMaximum lessons to extract / surface. Default 5.
min_confidenceNoMinimum confidence for batch extraction. Default 0.7.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.8/5.0
Behavior5/5

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

Description goes beyond annotations by detailing the behavior of each mode, such as batch extraction via a worker and lookup ranking. Annotations already indicate not read-only, not destructive, not idempotent, and description aligns without contradiction.

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 structured into clear paragraphs for each mode, uses concise language, and avoids redundancy. Every sentence adds information without waste.

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 complexity of three modes and 11 parameters, the description is fully complete. It covers all necessary aspects for correct usage, including mode selection, parameter roles, and default values. The presence of an output schema does not detract from the description's completeness.

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

Parameters5/5

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

With 100% schema coverage, the description adds significant value by grouping parameters into modes, explaining conditional usage (e.g., rank_by ignored unless find is set), and providing context for each parameter. This exceeds the baseline of 3.

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 defines the tool's purpose as capturing lessons with three distinct modes (inline, batch, lookup). It differentiates from sibling tools which include vault operations and delegation tasks.

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 explains when to use each mode: inline for structured input, batch for extracting from raw text, lookup for searching existing lessons. It lacks explicit when-not-to-use guidance but is sufficient for most cases.

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

delegate_taskA

Offload work to a cheaper model or summarize vault files.

When project is provided, reads a vault file. Small files (≤50 lines) are returned directly. Large files are auto-delegated to a worker for summarization — falls back to raw content if workers are unavailable.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoRelative path to a .md file. Overrides section.
modelNoConcrete model id. Empty uses the configured worker model. The 4.0.0 removal retired 'auto', 'ollama', 'openrouter-free' and 'openrouter'; passing one is rejected rather than ignored.
promptNoThe task description or code to process.
contextNoOptional system context for the model.
projectNoProject slug for vault summarization mode.
sectionNoShortcut name for summarization. Ignored if path is set.context
timeout_sNoPer-dispatch deadline in seconds. 0 uses the ambient tool timeout. A value ABOVE the ambient one raises the ceiling rather than being clamped by it — a deadline a 60s default can silently cap is not a deadline (HIVE-384 AC3).
max_tokensNoMaximum tokens in the response.
structuredNoReturn a JSON record instead of prose. Prose is the default so every existing caller's contract is unchanged; the dispatcher asks for JSON because it needs the status as a VALUE. Exception types do not survive the JSON-RPC boundary between the daemon and its clients, so "the pool refused" and "the worker answered badly" cannot be told apart by type on the far side — and a dispatcher that cannot tell them apart turns a rate limit into a silent retry against a different model.
max_summary_linesNoTarget summary length for summarization.

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?

The annotations provide no safety disclosure, but the description adds useful behavioral detail beyond them: the 50-line threshold, automatic worker delegation, and fallback behavior. It also clarifies the tool mutates nothing structurally while it performs offloading, though it doesn't fully explain side effects or costs.

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 entire description is two sentences that front-load the key action and immediately provide the most important behavioral caveat. No word is wasted, and the format is easy to grasp.

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?

The description covers the main usage modes, file-size behavior, and fallback. With an output schema and full parameter descriptions present, this is sufficient for basic invocation, but it does not explain the generic no-project delegation mode clearly, so it is not a 5.

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 description coverage is 100%, so the tool description does not need to document parameters. The main description only associates project with vault reading, but availing of the expected baseline: since the schema already covers 10 parameters, the description adds little beyond that.

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

Purpose4/5

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

The opening line 'Offload work to a cheaper model or summarize vault files' names a clear verb and resource, so an agent can understand the tool's purpose immediately. It does not explicitly name or distinguish itself from siblings like vault_ask or worker_status, so it's not quite a 5.

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 gives concrete execution context: it states that when project is provided a vault file is read, files ≤50 lines are returned directly, larger files are delegated to a worker, and there is a fallback if workers are unavailable. It does not provide explicit when-not-to-use guidance or alternatives, so it stops short of 5.

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

session_briefingA
Read-onlyIdempotent

Call at the start of every new session to load project context.

Without a project, returns the available project list with a usage hint — discoverability parity with vault_health() and worker_status(). With a project, assembles active tasks, recent lessons, git activity, and project health into a single response (replaces 3-4 manual calls).

ParametersJSON Schema
NameRequiredDescriptionDefault
projectNoProject slug (directory under 10_projects/). Empty = list available projects so the caller can pick one. This is the only parameter — there is no `days` argument (the briefing window is fixed).

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.9/5.0
Behavior5/5

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

Beyond annotations (readOnly, idempotent), the description details what the tool assembles (active tasks, recent lessons, git activity, project health) and how it provides discoverability parity with other tools. No contradictions with annotations; adds valuable 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 concise paragraphs: first sentence states primary use, second paragraph explains dual behavior (with/without project). Every sentence adds value, no fluff, and the critical info is front-loaded.

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 low complexity (1 param, no required, output schema exists), the description fully covers what the tool does, what it returns in both cases, and how it fits with sibling tools. It is complete for an agent to decide when and how to invoke it.

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?

Schema coverage is 100% with a clear description for the 'project' parameter. The description adds extra meaning by clarifying the slug is a directory under 10_projects/, that empty lists projects, and explicitly stating there is no 'days' argument – fixed briefing window. This reduces ambiguity beyond 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?

Description clearly states the tool loads project context at session start. It distinguishes from siblings by being a consolidated briefing that replaces multiple manual calls, and notes behavior without a project (returns project list) for discoverability parity with vault_health and worker_status.

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

Usage Guidelines5/5

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

Explicitly says 'Call at the start of every new session' and explains what happens with and without a project. It also contrasts with alternatives by stating it replaces 3-4 manual calls, giving clear usage context.

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

vault_askA
Read-onlyIdempotent

Ask a natural-language question; get a source-cited synthesized answer (semantic retrieval / RAG) or relevant vault sections when no synthesis model is configured.

OPTIONAL — disabled by default. Requires the [semantic] extra plus an embeddings backend (HIVE_EMBED_BASE_URL); until then it returns a short how-to-enable message and never errors. Set HIVE_SYNTH_MODEL to enable LLM synthesis on top of retrieval. For keyword / regex lookups use vault_search instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
questionNoThe natural-language question to answer. Use `question`, not `query` or `prompt`.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already declare readOnlyHint and idempotentHint. The description adds that without proper setup, it returns a helpful how-to-enable message and never errors, which is consistent and transparent.

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

Conciseness4/5

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

The description is informative but slightly wordy. It is well-structured with optional setup details, but could be more succinct.

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 presence of an output schema and annotations, the description provides sufficient context about behavior when not configured. It covers key aspects for a RAG tool.

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?

Only one parameter 'question' with full schema coverage. The description adds no extra semantic detail beyond what the schema provides, so baseline 3 is appropriate.

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's purpose: answering natural-language questions via semantic retrieval or returning relevant sections. It distinguishes itself from sibling tool vault_search, which handles keyword/regex lookups.

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

Usage Guidelines5/5

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

Explicitly tells when to use (natural-language questions) and when not (use vault_search for keyword/regex). Also notes it is optional and requires specific configuration to work, preventing misuse.

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

vault_commitA

Stage everything in the vault and create one commit.

Companion to vault_write(commit=False) and vault_patch(commit=False): callers that opt out of per-write commits batch many writes and then flush with a single vault_commit call.

Returns the new commit SHA on success, a clean-tree notice when there is nothing to commit, or a human-readable error.

ParametersJSON Schema
NameRequiredDescriptionDefault
messageNoCommit message. Empty defaults to "vault: batch update". This is the only parameter — there is no `project` argument; the commit spans the whole vault working tree.

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?

Description adds behavioral details beyond annotations: it stages everything, creates one commit, returns commit SHA, clean-tree notice, or error, and mentions default commit message. Annotations confirm it's not read-only, not destructive, and not idempotent, which aligns with the described behavior.

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?

Three sentences, front-loaded with the core purpose, followed by usage context and return values. Every sentence adds value with no redundancy.

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?

For a simple tool with one optional parameter and an output schema, the description covers return values (commit SHA, clean-tree notice, error), batch usage context, and default message, providing complete guidance.

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?

Schema coverage is 100% for the single parameter 'message', and the description adds extra meaning: empty defaults to 'vault: batch update' and notes it's the only parameter with no project argument, enhancing understanding beyond 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?

Description clearly states 'Stage everything in the vault and create one commit' and explains its relationship to vault_write and vault_patch, distinguishing it from sibling tools by specifying it's a batch commit operation.

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?

Explicitly says this is a companion to vault_write and vault_patch with commit=False, providing when-to-use context. It also notes there is no project argument, clarifying scope. Missing explicit 'when not to use', but the context is sufficient.

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

vault_deleteB

Delete a single file from the vault (destructive; recoverable via git).

Removes one file and, by default, commits the deletion so it stays recoverable from git history (git revert / git show). Files only — directories are rejected. A non-existent path is an error, unless idempotency_key is set (then a retry against an already-gone file is a no-op success).

ParametersJSON Schema
NameRequiredDescriptionDefault
pathYesRelative path to the file within the project.
commitNoMust be True (the default). Unlike ``vault_write``, this tool has no deferred mode: it neither uses the commit queue (a delete and a recreate inside one tick would collapse to a single state) nor leaves the removal uncommitted, which is the indefinite deferral ADR-018 §4 removed. ``commit=False`` is rejected with an explanation rather than silently upgraded — see the ADR's 2026-08-09 amendment.
projectYesProject slug or '_meta' for cross-project content.
idempotency_keyNoOptional at-most-once token. If set, a retry with the same key is a no-op after the first delete (ADR-013), which also makes deleting an already-removed file succeed. Empty (default) disables idempotency.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.4/5.0
Behavior1/5

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

The description states 'destructive; recoverable via git', but the annotations include destructiveHint: false. This is a direct contradiction. The description does provide rich behavioral context (commit default, idempotency, error conditions), but the contradiction triggers the score 1 rule.

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 three sentences, front-loaded with the primary purpose, and includes essential caveats (files only, recoverable via git, idempotency behavior) without wasting words. Every sentence contributes value.

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?

The description covers edge cases (error on non-existent path, idempotency, commit behavior) and references git recovery. With the output schema and rich parameter descriptions, it is nearly complete. It loses a point for not providing usage alternatives or addressing the destructive annotation inconsistency.

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 description coverage is 100%, so the schema documents all parameters. The description adds general context (e.g., error behavior for non-existent paths) but does not add meaning beyond the schema's parameter descriptions. Baseline 3 is appropriate.

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 opens with a specific verb and resource: 'Delete a single file from the vault'. It clearly states that it removes one file, commits the deletion, and explicitly excludes directories. This distinguishes it from sibling tools like vault_write and vault_patch.

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 (delete files, not directories; use commit=True) and contrasts with vault_write for commit behavior. However, it does not explicitly state when to use this tool over alternatives, nor does it mention any alternative for directory deletion.

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

vault_healthA
Read-onlyIdempotent

Return vault health metrics, validation, and optional usage analytics.

Always emits the ## server identity block (version, python, vault path, backend presence, started_at) at the top.

Without parameters, returns a health summary for all projects. When checks are specified, runs drift detection (frontmatter, stale, links). When include_usage is True, appends tool usage analytics. When include_runtime is True, appends runtime metadata (uptime, tools, budget).

ParametersJSON Schema
NameRequiredDescriptionDefault
checksNoValidation checks to run. Empty = health summary only. Options: frontmatter, stale, links.
projectNoProject slug to validate. Empty = all projects.
max_issuesNoMaximum validation issues to report. Default 50.
usage_daysNoUsage look-back window in days. Default 30.
include_usageNoAppend vault tool usage analytics. Default False.
include_runtimeNoAppend runtime metadata block. Default False.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior5/5

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

Annotations already declare readOnlyHint and idempotentHint. The description adds behavioral details: always emits server identity block, conditional outputs based on parameters. 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.

Conciseness4/5

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

The description is well-structured with clear bullet points. It is informative without being overly verbose, though could be slightly more concise.

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 has 6 optional parameters and conditional behavior, the description covers main use cases. Output format is partially described (blocks), but output schema exists to fill gaps. Adequate for the complexity.

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?

Schema coverage is 100%, so baseline is 3. The description adds meaning beyond schema by explaining what checks trigger drift detection and what include_usage/runtime append, enhancing semantic understanding.

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 it returns vault health metrics, validation, and optional usage analytics. It distinguishes itself from sibling tools like vault_list or vault_search by focusing on health checks and diagnostics.

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 explains conditional usage: without parameters returns summary, with checks runs drift detection, and with flags appends analytics or runtime metadata. It provides clear context but does not explicitly state when not to use or mention alternatives.

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

vault_listA
Read-onlyIdempotent

List vault projects, or files within a project.

When called without arguments, lists all available projects. When called with a project, lists files in that project directory.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoSubdirectory within the project. Empty = project root. (Use `path`, not `subpath` — `subpath` is accepted as an alias.)
patternNoGlob pattern to filter files (e.g. 'adr-*', '*.md').
projectNoProject slug. Empty = list all projects.
subpathNoAlias of `path` (#151). Prefer `path`. Note: there is no `scope` parameter here — `scope` lives on `vault_search`.

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 indicate readOnlyHint and idempotentHint. The description adds details on how arguments affect behavior (listing projects vs files, using subdirectories and patterns). It does not contradict annotations and provides good behavioral context beyond the structured fields.

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 very concise at 4 lines, front-loads the main purpose, and includes only essential details with no redundant content. Every sentence provides useful information.

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 complexity (4 optional params, nested structure), the description covers the main usage patterns. It explains the two modes and parameter roles. The output schema exists to document return values, so the description is sufficiently complete for a list tool.

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

Parameters5/5

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

Schema coverage is 100%, but the description adds significant value: explains the alias 'subpath' for 'path', notes that 'scope' is not a parameter here, and clarifies default behaviors for empty strings. This is excellent parameter-level guidance.

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 lists vault projects or files within a project. It distinguishes two modes based on arguments, and the verb 'list' combined with resource 'vault projects/files' is specific. It differentiates from sibling tools like vault_search and vault_write.

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 explains when to use with or without the 'project' argument. It does not directly compare with sibling tools, but the usage context is clear and provides actionable guidance.

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

vault_patchA

Surgical find-and-replace in a vault file with auto git commit.

Supports single or multi-replacement. For a single replacement, provide find and replace. For multiple replacements, provide patches — a list of {"find": "...", "replace": "..."} dicts applied in sequence. Do not mix both modes.

Each find value must appear exactly once in the file (after prior patches in the list have been applied). If any patch fails validation, no changes are written.

Uses 3-pass cascading match: exact → body-only → whitespace-normalized.

ParametersJSON Schema
NameRequiredDescriptionDefault
findNoExact text to find (single mode). Empty = not set. (Use `find`/`replace`, NOT `old_string`/`new_string` — those are accepted as aliases.)
pathYesRelative path to the file within the project.
commitNoIf True, commit synchronously before returning. Defaults to False, which queues the path for the reconciler. See ``vault_write`` docstring for the durability contract.
patchesNoList of {"find", "replace"} dicts (multi mode).
projectYesProject slug or '_meta' for cross-project content.
replaceNoReplacement text (single mode). Empty = not set.
new_stringNoAlias of `replace` (#151). Prefer `replace`.
old_stringNoAlias of `find` (#151). Prefer `find`.
idempotency_keyNoOptional at-most-once token. If set, a retry with the same key is a no-op after the first apply (ADR-013). Empty (default) disables idempotency.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior5/5

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

Beyond the annotations (readOnly=false, idempotentHint=false, destructiveHint=false), the description discloses critical behavior: auto git commit, 3-pass cascading match, uniqueness requirement, and atomic failure semantics ('If any patch fails validation, no changes are written'). It also references the durability contract in vault_write, providing valuable 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?

The description is compact and front-loaded with a one-sentence summary, followed by a short bulleted list of usage rules and matching behavior. Every sentence earns its place, and technical details are grouped logically.

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?

With 9 parameters, rich schema descriptions, an output schema, and annotations, the description still contributes the essential behavioral contract: validation atomicity, matching cascades, and commit durability. The reference to the vault_write docstring for the durability contract avoids duplication while pointing to the needed detail.

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 input schema already has 100% descriptive coverage, so the baseline is 3; the description adds value by clarifying the two mutually exclusive modes (find/replace vs patches), the 'applied in sequence' semantics, and the uniqueness rule that governs patch validation. It does not need to repeat every schema field, but it explains the relationships between parameters.

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 opens with a specific verb+resource: 'Surgical find-and-replace in a vault file with auto git commit,' clearly distinguishing it from siblings like vault_write, vault_delete, and vault_commit. It further specifies single/multi modes and matching algorithm, leaving no ambiguity about what the tool does.

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 gives concrete conditions for use: single vs multi replacement, 'Do not mix both modes,' the requirement that each find appear exactly once, and all-or-nothing validation. It does not explicitly name sibling alternatives with 'use X instead,' but the context makes it obvious this is the targeted-edit tool.

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

vault_queryA
Read-onlyIdempotent

Read content from a vault project — use instead of direct filesystem access.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoRelative path to a specific .md file within the project. Overrides section. (Use `path` for a file, not `identifier` — `identifier` is accepted as an alias.)
projectYesProject slug (directory under 10_projects/), or '_meta' for 00_meta/.
sectionNoShortcut name (context, tasks, roadmap, lessons). Ignored if path is set.context
max_linesNoMaximum lines to return. 0 = unlimited.
identifierNoAlias of `path` (#151). Prefer `path`; for a section shortcut use `section` instead.
include_metadataNoPrepend a structured metadata line from YAML frontmatter.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.8/5.0
Behavior3/5

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

Annotations already declare readOnlyHint and idempotentHint, so the description's 'Read content' aligns. No additional behavioral details beyond what annotations provide, which is acceptable for a safe read operation.

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

Conciseness4/5

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

A single concise sentence that front-loads the purpose. Could be slightly expanded for completeness but is efficient and clear.

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

Completeness3/5

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

Given the tool has 6 parameters, annotations, and an output schema, the description is minimal. It doesn't mention return format or error handling, but for a straightforward read tool this is adequate but not comprehensive.

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 description coverage is 100%, so the schema already documents each parameter's meaning. The description text does not add extra parameter context, but the baseline score of 3 is appropriate.

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 'Read content from a vault project', specifying a verb (read) and resource (vault project). It also distinguishes from file system access and implicitly from siblings like vault_write and 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 Guidelines4/5

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

Explicitly says 'use instead of direct filesystem access', providing context for when to use. Does not explicitly list when not to use or compare to vault_list/search, but the sibling names and purpose make alternatives clear.

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

vault_writeA

Write to the vault: append, replace a section, or create a new file.

Modes:

  • append/replace: Update a project section. Requires section.

  • create: Create a new file with auto-generated frontmatter. Requires path; doc_type defaults to "note". Inferred automatically when you pass a path with no section, so operation may be omitted.

ParametersJSON Schema
NameRequiredDescriptionDefault
pathNoRelative path for the file. Setting this with no section creates the file (create mode).
commitNoIf True, commit synchronously before returning — the escape hatch for a caller that needs the commit to exist by the time the call ends. Defaults to False, which queues the path for the reconciler to commit on its next tick (a few seconds). Durability contract: the file is persisted to disk regardless; only the *commit* is deferred, so a crash before the next flush loses the commit, not the content.
contentYesMarkdown content to write (body only for create mode).
projectYesProject slug or '_meta' for cross-project content.
sectionNoSection shortcut (context, tasks, roadmap, lessons). For append/replace.
doc_typeNoDocument type for frontmatter (create mode). Optional; defaults to "note".
operationNo'append', 'replace', or 'create'. Default 'append'. 'create' is inferred when path is set and section is empty.append
idempotency_keyNoOptional at-most-once token. If set, a retry with the same key is a no-op (safe for transparent retries after a daemon restart cuts an in-flight write — ADR-013). Empty (default) disables idempotency.

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?

With annotations indicating a non-read-only, non-idempotent, non-destructive write, the description adds behavior: auto-generated frontmatter, doc_type defaulting to 'note', and automatic mode inference. It does not mention deferred commit, but that is disclosed in the schema, and the description's extra mode semantics exceed what annotations alone provide.

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?

Four short lines, bulleted modes, no filler. Every sentence earns its place.

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?

For an 8-param tool with rich schema and output schema, the description provides the necessary high-level behavioral map: modes, requirements, and default inference. It is complete enough for selection and correct invocation.

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?

Schema coverage is 100%, so the baseline is 3. Description adds cross-parameter semantics: which modes require which params, that operation can be omitted when path has no section, and doc_type defaulting. This goes beyond individual schema entries.

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 opens with 'Write to the vault' and lists three concrete modes: append, replace, and create a new file. This clearly identifies the resource and operation and distinguishes it from vault_list/vault_query/vault_search siblings.

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?

Modes explicitly state requirements: append/replace requires a section, create requires a path, and operation is inferred when path is passed without section. It gives clear within-tool mode-selection context, though it does not name sibling alternatives or exclusions.

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

worker_statusA
Read-onlyIdempotent

Show worker health: configuration, reachability, model, and usage.

HIVE-384 reshaped this tool, and the reshape is the point rather than a side effect. The old output led with a dollar budget and reported two providers by configuration: it said "Ollama: offline / OpenRouter: no API key" for an unknown length of time while every caller treated the worker as a working capability. A status surface that cannot distinguish "configured" from "answers" is how a dead backend stays invisible.

So reachability is probed, not inferred, and reported separately from configuration. The dollar figures are gone: on a flat subscription they would read zero forever, and a gauge that always says the same thing looks like a working gauge.

ParametersJSON Schema
NameRequiredDescriptionDefault
include_modelsNoProbe the provider for its model list. Default True. Set False to report configuration without a network call.

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4/5.0
Behavior5/5

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

Beyond the readOnly and idempotent annotations, the description explains that reachability is actively probed rather than inferred, and that configuration is reported separately from availability. It also notes removed dollar figures and the reasoning behind them, giving the agent crucial 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.

Conciseness2/5

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

The opening sentence is succinct and front-loaded, but the rest is a long narrative about HIVE-384, the old output, and design rationale. Most of that detail is not necessary for an AI agent to invoke the tool correctly, so the description is wordier than needed.

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?

The description is behaviorally rich and, together with the output schema and annotations, gives the agent a complete picture. It explains what the tool measures, what is intentionally excluded, and how reachability is resolved, leaving no critical gap for invocation.

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 description coverage is 100%, so the include_models parameter is already fully documented in the schema. The tool description adds no parameter-specific detail beyond mentioning 'model' as one health dimension, so the baseline of 3 applies.

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 opens with 'Show worker health: configuration, reachability, model, and usage,' which is a specific verb plus resource and outcome. It clearly distinguishes the tool's focus from the vault_* siblings by naming its unique scope of worker health.

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 conveys when to use the tool—when worker health/status is needed—but does not explicitly state when not to use it or point to alternatives. The context is clear enough for a watchful agent, but the guidance is implied rather than explicit.

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. 1 tool updatev4.1.0
    • Changeddelegate_task2 fields changed
      • addedInput schema / properties / structured
        Added value: +{
+  "default": false,
+  "description": "Return a JSON record instead of prose. Prose is the\ndefault so every existing caller's contract is unchanged; the\ndispatcher asks for JSON because it needs the status as a\nVALUE. Exception types do not survive the JSON-RPC boundary\nbetween the daemon and its clients, so \"the pool refused\" and\n\"the worker answered badly\" cannot be told apart by type on the\nfar side — and a dispatcher that cannot tell them apart turns a\nrate limit into a silent retry against a different model.",
+  "type": "boolean"
+}
      • addedInput schema / properties / timeout_s
        Added value: +{
+  "default": 0,
+  "description": "Per-dispatch deadline in seconds. 0 uses the ambient\ntool timeout. A value ABOVE the ambient one raises the ceiling\nrather than being clamped by it — a deadline a 60s default can\nsilently cap is not a deadline (HIVE-384 AC3).",
+  "type": "number"
+}
  2. 2 tool updatesv4.0.0
    • Changeddelegate_task3 fields changed
      • removedInput schema / properties / max_cost_per_request
        Removed value: -{
-  "default": 0,
-  "description": "Max USD. 0 = free models only.",
-  "type": "number"
-}
      • changedInput schema / properties / model / default
        Previous value: -"auto"New value: +""
      • changedInput schema / properties / model / description
        Previous value: -"'auto', 'ollama', 'openrouter-free', 'openrouter' (paid), or model ID."New value: +"Concrete model id. Empty uses the configured worker model.\nThe 4.0.0 removal retired 'auto', 'ollama', 'openrouter-free'\nand 'openrouter'; passing one is rejected rather than ignored."
    • Changedworker_status1 field changed
      • changedInput schema / properties / include_models / description
        Previous value: -"Include available model list from all providers. Default True."New value: +"Probe the provider for its model list. Default True.\nSet False to report configuration without a network call."
  3. 3 tool updatesv3.0.0
    • Changedvault_delete1 field changed
      • changedInput schema / properties / commit / description
        Previous value: -"If True (default), stage + commit the deletion. If False,\nunlink on disk but leave the removal staged for a later\n``vault_commit`` (or obsidian-git). Same durability contract as\n``vault_write``."New value: +"Must be True (the default). Unlike ``vault_write``, this\ntool has no deferred mode: it neither uses the commit queue\n(a delete and a recreate inside one tick would collapse to a\nsingle state) nor leaves the removal uncommitted, which is\nthe indefinite deferral ADR-018 §4 removed. ``commit=False``\nis rejected with an explanation rather than silently\nupgraded — see the ADR's 2026-08-09 amendment."
    • Changedvault_patch2 fields changed
      • changedInput schema / properties / commit / default
        Previous value: -trueNew value: +false
      • changedInput schema / properties / commit / description
        Previous value: -"If True (default), auto-commit. If False, write to disk\nwithout committing — useful for batching many patches into\none ``vault_commit`` flush. See ``vault_write`` docstring for\nthe durability contract."New value: +"If True, commit synchronously before returning.\nDefaults to False, which queues the path for the reconciler.\nSee ``vault_write`` docstring for the durability contract."
    • Changedvault_write2 fields changed
      • changedInput schema / properties / commit / default
        Previous value: -trueNew value: +false
      • changedInput schema / properties / commit / description
        Previous value: -"If True (default), auto-commit to git. If False, write to\ndisk but leave the file dirty so the caller can batch many\nwrites into one commit via the ``vault_commit`` tool, or let\nobsidian-git's auto-commit pick it up. Durability contract:\nfiles are persisted to disk regardless; only the *commit* is\ndeferred. A crash before the next flush loses the commit, not\nthe file content."New value: +"If True, commit synchronously before returning — the\nescape hatch for a caller that needs the commit to exist by\nthe time the call ends. Defaults to False, which queues the\npath for the reconciler to commit on its next tick (a few\nseconds). Durability contract: the file is persisted to disk\nregardless; only the *commit* is deferred, so a crash before\nthe next flush loses the commit, not the content."
  4. 4 tool updatesv1.41.1
    • Addedvault_ask
    • Addedvault_delete
    • Changedvault_search2 fields changed
      • addedInput schema / properties / limit
        Added value: +{
+  "default": 0,
+  "description": "Alias of `max_results` (#202). Prefer `max_results`. When\nboth are given the tighter (smaller) cap wins; 0 = unset.",
+  "type": "integer"
+}
      • changedInput schema / properties / max_results / description
        Previous value: -"Max files when ranked. Default 10."New value: +"Max result files. Default 10. Caps the file count in\nall modes (flat, ranked, recent); in flat/recent the cap is by\npath order (alphabetical) — use ranked=True for relevance order."
    • Changedvault_write3 fields changed
      • changedInput schema / properties / doc_type / description
        Previous value: -"Document type for frontmatter. For create mode."New value: +"Document type for frontmatter (create mode). Optional;\ndefaults to \"note\"."
      • changedInput schema / properties / operation / description
        Previous value: -"'append', 'replace', or 'create'. Default 'append'."New value: +"'append', 'replace', or 'create'. Default 'append'.\n'create' is inferred when path is set and section is empty."
      • changedInput schema / properties / path / description
        Previous value: -"Relative path for new file. For create mode."New value: +"Relative path for the file. Setting this with no section\ncreates the file (create mode)."
  5. 2 tool updatesv1.32.2
    • Changedvault_patch1 field changed
      • addedInput schema / properties / idempotency_key
        Added value: +{
+  "default": "",
+  "description": "Optional at-most-once token. If set, a retry with\nthe same key is a no-op after the first apply (ADR-013). Empty\n(default) disables idempotency.",
+  "type": "string"
+}
    • Changedvault_write1 field changed
      • addedInput schema / properties / idempotency_key
        Added value: +{
+  "default": "",
+  "description": "Optional at-most-once token. If set, a retry with\nthe same key is a no-op (safe for transparent retries after a\ndaemon restart cuts an in-flight write — ADR-013). Empty\n(default) disables idempotency.",
+  "type": "string"
+}
  6. 6 tool updatesv1.23.0
    • Changedsession_briefing1 field changed
      • changedInput schema / properties / project / description
        Previous value: -"Project slug (directory under 10_projects/). Empty =\nlist available projects so the caller can pick one."New value: +"Project slug (directory under 10_projects/). Empty =\nlist available projects so the caller can pick one. This is the\nonly parameter — there is no `days` argument (the briefing\nwindow is fixed)."
    • Changedvault_commit1 field changed
      • changedInput schema / properties / message / description
        Previous value: -"Commit message. Empty defaults to \"vault: batch update\"."New value: +"Commit message. Empty defaults to \"vault: batch update\".\nThis is the only parameter — there is no `project` argument;\nthe commit spans the whole vault working tree."
    • Changedvault_list2 fields changed
      • changedInput schema / properties / path / description
        Previous value: -"Subdirectory within the project. Empty = project root."New value: +"Subdirectory within the project. Empty = project root.\n(Use `path`, not `subpath` — `subpath` is accepted as an alias.)"
      • addedInput schema / properties / subpath
        Added value: +{
+  "default": "",
+  "description": "Alias of `path` (#151). Prefer `path`. Note: there is no\n`scope` parameter here — `scope` lives on `vault_search`.",
+  "type": "string"
+}
    • Changedvault_patch3 fields changed
      • changedInput schema / properties / find / description
        Previous value: -"Exact text to find (single mode). Empty = not set."New value: +"Exact text to find (single mode). Empty = not set.\n(Use `find`/`replace`, NOT `old_string`/`new_string` — those\nare accepted as aliases.)"
      • addedInput schema / properties / new_string
        Added value: +{
+  "default": "",
+  "description": "Alias of `replace` (#151). Prefer `replace`.",
+  "type": "string"
+}
      • addedInput schema / properties / old_string
        Added value: +{
+  "default": "",
+  "description": "Alias of `find` (#151). Prefer `find`.",
+  "type": "string"
+}
    • Changedvault_query2 fields changed
      • addedInput schema / properties / identifier
        Added value: +{
+  "default": "",
+  "description": "Alias of `path` (#151). Prefer `path`; for a section\nshortcut use `section` instead.",
+  "type": "string"
+}
      • changedInput schema / properties / path / description
        Previous value: -"Relative path to a specific .md file within the project. Overrides section."New value: +"Relative path to a specific .md file within the project. Overrides section.\n(Use `path` for a file, not `identifier` — `identifier` is accepted as an alias.)"
    • Changedvault_search2 fields changed
      • addedInput schema / properties / regex
        Added value: +{
+  "default": false,
+  "description": "Alias of `use_regex` (#151). Prefer `use_regex`. To narrow\nby location use `scope` / `project`, not `path_filter` /\n`path_prefix`.",
+  "type": "boolean"
+}
      • changedInput schema / properties / use_regex / description
        Previous value: -"Treat query as regex. Default False."New value: +"Treat query as regex. Default False. (Use `use_regex`,\nnot `regex` — `regex` is accepted as an alias.)"
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4/5.0
Disambiguation3/5

Most tools have a distinct role, but several retrieval paths overlap: vault_query, vault_search, vault_ask, and delegate_task can all be used to read or summarize vault content, and vault_search's lessons-only mode overlaps capture_lesson's lookup mode. vault_write/replace and vault_patch also offer close update paths, so the boundaries are clear only with careful reading.

Naming Consistency4/5

The vault_* tools form a clear, consistent namespace and all names are readable snake_case. The set is not perfectly uniform, though: session_briefing and worker_status use domain-plus-noun, while capture_lesson and delegate_task use verb-first names, so the naming convention is cohesive but mixed.

Tool Count5/5

Thirteen tools is a well-scoped size for this domain: content CRUD, search, git commits, health, session context, lesson capture, and worker visibility are all represented without obvious bloat. Each tool appears to earn its place.

Completeness4/5

The vault surface covers create, read, update, patch, delete, commit, search, health, session startup, lessons, and worker status, which is strong for the stated domain. Minor gaps remain for direct lesson edit/delete operations and file renames/moves, but those can be worked around with the existing vault write/delete tools.

Maintenance

ActivityActive
ResponsivenessResponsive

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

  • Obsidian

    clavia-labs
    A
    license
    Not graded
    quality
    Not graded
    maintenance
    This is a connector to allow Claude Desktop (or any MCP client) to read and search any directory containing Markdown notes (such as an Obsidian vault).
    1,444
    1,352
    AGPL 3.0

  • Obsidian MCP

    newtype-01
    A
    license
    A
    quality
    F
    maintenance
    This project implements a Model Context Protocol (MCP) server for connecting AI models with Obsidian knowledge bases. Through this server, AI models can directly access and manipulate Obsidian notes, including reading, creating, updating, and deleting notes, as well as managing folder structures.
    11
    104
    312
    MIT

  • context-portal

    GreatScottyMac
    A
    license
    Not graded
    quality
    D
    maintenance
    Context Portal (ConPort): A memory bank MCP server building a project-specific knowledge graph to supercharge AI assistants. Enables powerful Retrieval Augmented Generation (RAG) for context-aware development in your IDE.
    765
    Apache 2.0

  • Another bloated Obsidian MCP

    diegorv
    A
    license
    A
    quality
    F
    maintenance
    A Model Context Protocol (MCP) server that provides AI assistants with secure access to Obsidian vaults. Enables reading, writing, searching, and managing notes without requiring Obsidian to be running.
    50
    5,784
    Apache 2.0

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/mlorentedev/hive'

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