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.

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

Search the vault: full-text, ranked, or recent changes.

Default mode: flat full-text search across all vault files. Ranked mode (ranked=True): results scored by relevance. Recent mode (since_days>0): files changed in the last N days. rank_by mode (rank_by != 'bm25'): lessons-only, ranked by usage.

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).

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. Requires path, relative to the project directory. Frontmatter is generated (doc_type defaults to "note") unless content opens with its own block, which is kept as is. Inferred automatically when you pass a path with no section, so operation may be omitted.

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.

Commit every unstaged and untracked change in the vault, in 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.

It also sweeps edits made outside hive. A path that already has a staged change is left out and named in the result: it belongs to whoever staged it, often another session sharing the vault. Commit one deliberately with git commit -- <path>.

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

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).

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).

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.

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.

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.

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.