List configured vaults with their status (note count, last indexed run). DEPRECATED since v2.0.0 — prefer MCP Resource vault-memory://vaults for agent discovery. The tool remains callable through v2.x; removal scheduled for v3.0.0.

Read the full content + frontmatter of a note by its vault-relative path.

Semantic search via embedding cosine similarity. Searches all vaults by default.

Full-text BM25 search via SQLite FTS5. Best for exact-word and phrase matches.

Hybrid search: combines semantic (embedding) and BM25 (full-text) results via Reciprocal Rank Fusion. Best general-purpose query. Pass expand: {hops: 1} to auto-attach 1–2 hop typed-edge neighbors as expansions[] per hit (preserves ranking; runs after recency/authority rescore).

Find all notes that link TO a given note. DEPRECATED since v2.0.0 — prefer MCP Resource vault-memory://backlinks/{vault}/{+docId} for agent discovery. The tool remains callable through v2.x; removal scheduled for v3.0.0.

List all wikilinks FROM a given note. Optionally include broken links.

List all wikilinks in a vault that point to non-existent notes.

Filter notes by their YAML frontmatter. Supports equality, $in, $exists, $contains predicates. Multiple keys are AND-combined.

Atomically create or overwrite a note. Requires write_enabled=true. Use expected_hash for safe overwrites (read the note first, pass its hash). Omit expected_hash only when creating a new note.

Modify a note's frontmatter only. The body is preserved bytegenau. Merge DSL: scalar=set, {$unset:true}=delete, {$push:x}=array append, {$pull:x}=array remove.

Delete a note. Requires write_enabled=true AND expected_hash (no blind deletes).

Query the write audit trail for a vault. Filterable by note path, operation type, or time. Default limit 50.

List all embedding models registered for a vault, with dim, active flag, and how many chunks have been embedded under each. Use before start_shadow_index / switch_active_model. DEPRECATED since v2.0.0 — prefer MCP Resource vault-memory://models/{vault} for agent discovery. The tool remains callable through v2.x; removal scheduled for v3.0.0.

Backfill embeddings for a secondary (shadow) model over every chunk in the vault. The active model is untouched — search keeps working during the run. Idempotent (resumable). Run switch_active_model once complete to promote the shadow.

Atomically promote a registered model to active. Fails with ok:false / reason:'incomplete' if any chunk is missing a shadow embedding for the target model.

Drop orphaned embedding rows whose chunk_id no longer exists in the chunks table. Safe and idempotent; does not touch live data. Useful after migrations from pre-v0.7.0 schemas where chunk deletion did not always cascade to the derived layer.

List recent index runs for a vault — what was scanned, when, how long, errors.

OB1-compatible search adapter. Returns a flat list of {id, title, url, snippet} for connector ecosystems (ChatGPT Custom Connectors, Claude.ai, Deep-Research). Backed by hybrid (semantic+BM25+RRF) search. For richer output use search_hybrid.

OB1-compatible fetch adapter. Resolves an opaque id (from search) to {id, title, text, url, metadata}. Backed by read_note.

Vault overview for agent self-orientation: note/word counts, top tags, top frontmatter keys, embedding model, last index run. Omit vault to get all configured vaults. DEPRECATED since v2.0.0 — prefer MCP Resource vault-memory://stats/{vault} for agent discovery. The tool remains callable through v2.x; removal scheduled for v3.0.0.

List recently modified notes (mtime DESC). Use for agent self-orientation: 'what has the user been working on lately?'. No vector search, just SQL. DEPRECATED since v2.0.0 — prefer MCP Resource vault-memory://recent/{vault} for agent discovery. The tool remains callable through v2.x; removal scheduled for v3.0.0.

Suggest frontmatter fields for a note based on folder-conventions, wikilink-neighborhood, and title/body content-heuristics. Returns {existing, suggestions, conflicts}. Two input modes: (1) existing note via {path}; (2) draft via {content, folder_hint, title}. At least one of path/content required. Suggestions sorted by confidence DESC; conflicts list disagreements between sources.

Record a new memory observation under the labeled MemorySink for a vault. Required provenance properties (source, confidence, evidence, status, observed_at, type, superseded_by) are auto-filled from arguments; properties is an escape hatch for contract-allowed extras and overrides any sugar default (D-02 — caller-last merge). Writes route through DeliveryAdapter.write() and pass through the centralized provenance validator.

Mark an existing memory document as superseded by a replacement document. Forward-only — the replacement doc is NOT touched; back-links are derived by the Phase 4 graph layer at query time. Atomic single OCC update on the OLD doc; sets status="superseded", superseded_by, and superseded_reason.

Compile a brief from caller-supplied source documents and write it to the briefs sink. Resolves the LLM via the D-10 capability-first ladder (MCP Sampling → local Ollama → caller prepared_text → structured error). Enforces D-11 wikilink emission per source (appends a ## Sources footer when the LLM omits them) and writes through DeliveryAdapter. On target collision, auto-supersedes the prior brief via the Phase 2 supersede chain (D-12).

Look up a brief by target slug. D-13 decision tree: staleness dominates; age is independent; follow the supersede chain to the terminal brief. Returns null when the caller MUST recompile (stale + !allow_stale OR too_old + !allow_stale).

Return the navigable section tree for a document. Each OutlineNode carries an anchor (the section's citation token), heading_path (root → leaf), heading_text, level, and chunk_ids (v1 chunk-table IDs in that section). Consume anchor + heading_path as the section-level half of the citation packet. Unknown doc_id returns an error response with {error:'doc_not_found', doc_id}.

Section-level retrieval. Composes the v1 hybrid (semantic + BM25 + RRF) pipeline with a chunk-to-section promotion step: runs hybrid with an inflated top_k = limit × 5, promotes each chunk hit to its enclosing section, dedupes by (note, section anchor), scores each section as the MAX of its constituent chunks, tie-breaks by chunk_id_first ASC, and returns the top limit sections. Each hit carries an 8-field citation packet (D-01) with a non-empty section heading_path PLUS the section anchor, score, contributing chunk_ids, and an optional snippet from the best-scoring chunk. Use when you want WHOLE-SECTION context, not a chunk window.

Retrieve memory documents from one or more labeled MemorySinks, filtered by provenance (min_confidence, types, max_age_days) and ranked by recency (observed_at DESC). Returns citation packets (doc_id, source_handle, title, heading_path, mtime, hash, display_url, properties) — the same 8-field shape Phase 3 assembly tools use. Superseded documents are hidden by default.

Document-tree retrieval. Returns a structured bundle for a single document: { anchor (citation packet + optional status/superseded_by), outline (section tree via buildOutlineTree — same shape as get_outline.root), backlinks (citation packets + property_snippet + relation:"wikilink"), forward_links (same shape; broken links omitted), recent_edits (≤10 most recent audit_log rows mapped to {at, op, client_id, is_memory_sink_write?}) }. Every citation packet is the full 8-field D-01 shape from src/memory/citation-packet.ts. v2.0.0 accepts only depth:1 (one-hop links); the field is zod-pinned to z.literal(1) for forward compatibility. recent_edits is keyed by the anchor's CURRENT note path — pre-rename history is preserved in audit_log but not surfaced here (Phase 4 widens). Unknown doc_id returns { isError: true, error: "doc_not_found", doc_id }.

Typed-edge BFS retrieval. Returns the typed-edge neighborhood of one or more seed documents as a flat array of citation packets, each carrying via: {seed_doc_id, hop, edge_type, direction} provenance. Hops hard-capped at 2 (v2.0.0). Default direction = 'both'. Filterable by edge_type and by document properties (strict equality, no operators). Memory-sink documents (_memory/...) surface only when they are already linked from a user note in the result set (per ADR-004 memory-namespace opacity rule). Frontmatter-ref edges are extracted heuristically: [[...]] syntax in any property value OR allowlisted property names (assignee, owner, project, related, parent, child, attendees, superseded_by) matched against note_aliases. include_superseded defaults to false (Phase 2 D-03 forward-only supersede). Unknown seed_doc_ids do not throw — they are returned in a warnings: [{seed_doc_id, reason: 'unknown_doc'}] array. Shortest path wins on dedup; ties broken by (seed_doc_id, edge_type, direction).

Community detection over the typed-edge graph via Louvain modularity (Blondel et al. 2008) using graphology + graphology-communities-louvain. Deterministic: same input produces byte-identical cluster_id assignment via DocId-sorted node insertion + seeded RNG (vault-memory-cluster-v1). cluster_id = smallest member DocId per community. Hard-capped at 5000 nodes; pass force: true to override. Either query (composes search_hybrid + expand 1-hop) OR seed_doc_ids (uses provided seeds + induced 1-hop neighborhood); not both — passing both returns {ok:false, reason:'both_seeds_and_query'}. On the query path with multiple vaults configured, the vault field is required so search scope is deterministic; single-vault setups may omit it (returns {ok:false, reason:'vault_required'} otherwise). Returns per-cluster {cluster_id, size, members[], summary: {top_types, top_titles, edge_density}}. No LLM enrichment — summary fields are pure-deterministic computations (LLM enrichment is Phase 5 brief layer's job). _memory opacity inherited from expand() (Plan 04-03).

Resolve a {type, key} pair to an anchor document and walk its backlinks into a structured dossier: { anchor (citation packet), linked_documents (citation packets + relation), property_rollups (linked_count, linked_types, status_distribution) }. Strict properties.type match (D-03). The key matches the candidate's title OR any entry in properties.aliases (D-04). v2.0.0 returns relation:"wikilink" on every linked_documents entry (the v1 wikilinks table is the only edge source); Phase 4 (GRA-04) widens to typed edges. Superseded backlinks are NOT filtered — dossiers show the whole picture (CONTEXT D-04).

Explicit-control escape valve (D-A1) — scans the per-vault contract registry and updates the dynamic MCP tool list (registers new contracts as vm_ tools, unregisters removed ones) regardless of the [contracts.auto_register_tools] config gate. Always callable. Returns a per-vault diff of {registered, unregistered}. Omit vault to apply to every configured vault.

Return the input JSON Schema + an auto-generated markdown summary for a contract (Q-DESCRIBE). Pure function — does not execute the contract. Summary lists Inputs / Sources / Sinks / Assembly (numbered) / write_back / Output Shape. Omit vault on single-vault setups; on multi-vault setups, pass vault to disambiguate (returns {ok:false, reason:'ambiguous_vault'} otherwise).

Execute a registered contract end-to-end. Zod-validates inputs against the contract's inputZodSchema (additionalProperties:false rejects typos). Resolves source/sink overrides per D-A4b default chain (explicit → config → contract literal → error if required); sinks are MemorySink-only per D-A4c (MEM-05 invariant un-bypassable). Runs each assembly step through verbDispatcher with template resolution + named-binding accumulation. write_back routes through DeliveryAdapter.write() (MEM-05 chokepoint). Returns the Q-OUTPUT bundle {steps, write_back} on success OR a structured InstantiateError envelope (12 sealed reasons per ADR-006 §Decision 7). Omit vault on single-vault setups; multi-vault setups require it (returns ambiguous_vault otherwise).