Full-text keyword search via PostgreSQL tsvector. Use this for exact identifiers, code symbols, proper nouns, or known phrases — anywhere semantic noise hurts.

For conceptual or paraphrased queries, use semantic_search instead.

Args: query: Keywords or phrase to match (websearch tsquery syntax: "foo bar", "foo OR bar", "-bar"). folder: Optional folder prefix (e.g. "Cards/", "Projects/"). limit: Maximum number of results (default 20). tags: Optional list of tag names; only notes carrying ALL listed tags match (e.g. ["project", "active"]). frontmatter: Optional dict of frontmatter key/value pairs; only notes whose JSONB frontmatter contains every pair match. Strict type matching — string "0" does not match integer 0 (e.g. {"status": "draft"}).

Read a note from the Obsidian vault by its relative path.

Returns a structured result, not a rendered document. Metadata and note content sit in separate fields, so there is no envelope to parse and no textual procedure to get wrong — read the fields:

• content — the selected note text. Whole-note reads: the body with a valid YAML frontmatter block stripped, which is exactly what edit_note(path, content) full replacement accepts. Section reads: the section's body only, which is exactly what edit_note(path, content, section=...) accepts. Pass it straight back; do not add, strip or split anything.

• heading — section reads only: the matched heading line, with no line terminator. It is not part of content, and a section write must not be sent it — the heading line is never rewritten.

• path, title, tags — metadata as data.

• frontmatter_yaml — the frontmatter block's YAML source, fence lines excluded, LF-normalized (a CRLF or lone-CR block comes back with LF terminators — the same declared residual content carries, because this tool normalises and the write tools work on raw bytes; edit_note still reattaches the original block byte-identically). This is the authoritative copy. frontmatter is a best-effort JSON view of the same block for convenience and may be absent — dates, non-string keys, recursive aliases and unpaired-surrogate escapes have no faithful JSON form, and metadata_omissions then says which and why. To change frontmatter use set_frontmatter, or edit the raw block with edit_note(find=...); never write back a round trip of the JSON view.

• truncated, offset, next_offset, total_chars — truncation as data. outline (whole-note reads that were truncated) lists every section with its #N ordinal so you can fetch the one you want directly, and notice carries the guidance in prose.

• metadata_omissions — any metadata field this response had to drop, and why. Nothing is ever signalled by a marker inside a field.

• content_hash — this note's file digest, sha256:<64 lowercase hex>, and the token the write tools accept as expected_hash to bind a write to the bytes you actually read. Three things about it: it is the whole file's hash in every mode — a section read and a truncated read return the same value a whole-note read of the unchanged file returns, so a section write guarded with it is refused when anything in the file changed (that is the trade, and it is why the argument is optional: bind when you reasoned about what you read, omit when you are appending to a log); it comes from the same read that built this response, never a second one; and it is not a hash of content — a note with frontmatter, or with CRLF terminators, has a digest the returned text cannot reproduce, so never compute it yourself, hand this value back verbatim. read_file on the same path is the byte-exact route to the file itself, frontmatter_yaml here being authoritative but LF-normalized.

• error — set when the read failed (missing note, bad offset/limit, unknown section). It is a normal result, not a transport error, and the content-bearing fields are absent beside it.

Budgets are per field, not per response: content is bounded by the server's response cap, the outline by its own equal budget, and the metadata fields by a third — so a truncated whole-note read can carry several capped components. Read the one section you need with section= rather than paging a large note.

Round trips. A whole-note content is byte-exact input for edit_note(path, content) only when the read is complete and unwindowed (offset=0 and truncated false); a truncated read must be paged to the end first, or full replacement replaces the whole body with the fragment. A section content is byte-exact input for edit_note(section=...) under the same completeness condition. Byte-identity holds for notes whose body newlines are LF: terminators inside the selected content come back as LF, because this tool normalises and the write tools rewrite raw bytes.

Args: path: Vault-relative path to the note (e.g. "Cards/My Note.md") section: Optional ATX heading to read instead of the whole note. Plain text ("Balance Sheet"), a path-style chain ("Parent/Child") when the heading appears under different parents, or a "#N" ordinal ("#7", 1-based document order) — the ordinal is the only form that can address duplicate headings sharing the same parent. The outline returned with a truncated note carries the ordinal for every section. A bare "#N" always selects by position and is never shadowed by a heading whose text happens to be "#N"; use "Parent/#N" to reach such a heading by title. offset: Character offset to start reading from (default 0). Use the next_offset the response reports to continue. limit: Maximum characters of content to return. Only lowers the server cap; it cannot raise it.

List notes in a vault folder, sorted by most recently modified.

Results come from the index, so a note that exists on disk but has not yet been picked up by the indexer will not appear (lag is bounded by the index interval, typically up to 5 minutes).

Args: folder: Vault-relative folder path (e.g. "Cards/", "Projects/"). Empty for vault root. limit: Maximum number of results (default 50). tags: Optional list of tag names; only notes carrying ALL listed tags match (e.g. ["idea"]). frontmatter: Optional dict of frontmatter key/value pairs; strict type match (e.g. {"status": "active"}).

List all tags used across the vault with note counts.

Args: limit: Maximum number of tags to return (default 50)

Get recently modified notes.

Args: limit: Number of recent notes to return (default 20). folder: Optional folder prefix to filter (e.g. "Projects/"). tags: Optional list of tag names; only notes carrying ALL listed tags match (e.g. ["meeting"]). frontmatter: Optional dict of frontmatter key/value pairs; strict type match (e.g. {"status": "active"}).

Vector similarity search over the vault's chunk embeddings. Use this for conceptual or paraphrased queries — anywhere exact word matching would miss the point.

For exact identifiers, code symbols, proper nouns, or known phrases, use keyword_search instead.

Each result is one note (deduped) with its best-matching chunk as a ~200-character preview. Call read_note on a result's path to get the full note content.

The header line carries a stale count and a truncated count, always — including when both are zero, so "nothing here is degraded" is distinguishable from a build that does not report it.

stale: true on a row means the note changed after it was embedded: it was matched and ranked against its previous content, and its preview is withheld rather than shown, because that excerpt is text the note no longer has. Its path, title and tags are current — the indexer refreshed them, which is how the staleness is known at all — so read_note on that path returns the true content and is the remedy. Stale notes are never filtered out: during an embedding outage that would empty the result set rather than degrade it.

embedding_truncated: true means the note is longer than the indexer's per-note chunk cap and only its head was embedded. A match against such a note is a match against its head; its tail is not reachable by semantic search at all, though keyword_search still covers the whole note.

The bound on the staleness signal, stated so it is not over-read: it reports what the index has committed. An edit that the indexer has not yet scanned is not marked, so a note edited in the last few minutes may come back unmarked with a superseded preview. The guarantee is "no result presents text the index knows to be superseded", not "no result is ever out of date".

Args: query: Natural language description of what you're looking for. limit: Maximum number of distinct notes to return (default 15). folder: Optional folder prefix (e.g. "Projects/"). tags: Optional list of tag names; only notes carrying ALL listed tags match (e.g. ["product"]). frontmatter: Optional dict of frontmatter key/value pairs; strict type matching — string "0" does not match integer 0 (e.g. {"status": "active"}).

Create a new markdown note in the Obsidian vault. Requires write permission — a readwrite API key, or an OAuth token carrying the readwrite scope.

See get_vault_guide for Obsidian syntax and any vault-specific conventions (naming, folder placement, frontmatter, tags).

Refuses a path whose final component is a symlink, naming its target, so a write never lands on a note other than the one named; symlinked folders inside the vault work normally.

The note is published no-clobber: the content is staged out of sight and linked into place in one kernel-atomic step, so an existing file at path can never be replaced by this tool. A vault filesystem that cannot stage an unnamed file refuses the write with an error naming VAULT_ALLOW_NAMED_STAGING_FALLBACK rather than staging under a visible name.

expected_hash — binding a write to the bytes you read. Optional; omit it and nothing changes. Pass the content_hash a read returned, verbatim and canonical (sha256:<64 lowercase hex>), and the call is refused with nothing written if the file changed in between. It is always the whole file's hash, never a hash of the text you received. Two windows, both live: expected_hash covers your read → this call's read, the server's own pre-publication compare covers this call's read → its publication, and a match on the first does not exempt the second. Every refusal ends with one machine-readable MCP-REFUSAL {"code":…} line — stale_precondition (with the file's current hash, ready to resend), concurrent_write, no_incumbent, malformed_precondition, precondition_unavailable, precondition_required — and each states what resolves it.

Here there are no incumbent bytes to bind: a supplied hash is answered no_incumbent before any filesystem work, nothing is created, and the remedy is to call again without it. A malformed hash is still reported as malformed first. Success reports the content_hash of the note this call published.

Args: path: Vault-relative path for the new note (e.g. "Cards/New Topic.md"). The .md extension is added if missing. content: Full markdown content for the note, including any frontmatter. expected_hash: Accepted and always refused as no_incumbent, so the refusal is a normal result rather than a protocol error.

Edit an existing note in the Obsidian vault. Requires write permission — a readwrite API key, or an OAuth token carrying the readwrite scope.

See get_vault_guide for Obsidian syntax and any vault-specific conventions (naming, folder placement, frontmatter, tags).

Four mutually exclusive modes (set at most one of append/find/section):

1. Full replace (default): provide only content. content becomes the note's body; an existing valid line-1 YAML frontmatter block is preserved byte-identically ahead of it. Pass replace_frontmatter=True to overwrite the entire file, frontmatter included.

2. Append: append=True; content is added at the end (preceded by a single newline).

3. Find & replace: find=<exact text>; replaced with content. Must match exactly once unless replace_all=True. This mode operates on the raw file, so it is the one mode that can edit frontmatter text in place.

4. Section: section=<heading>; replaces the whole body under the named ATX heading — see "Section mode: what content replaces" below. Use the path-style form Parent/Child to disambiguate when the same heading appears more than once, or the #N ordinal form ("#7", 1-based document order) — the ordinal is the only form that can address duplicate headings sharing one parent, and it is the selector the outline of a truncated read_note advertises. A bare "#N" always selects by position and is never shadowed by a heading whose text happens to be "#N"; reach such a heading by title with "Parent/#N". A selector resolves to the same section in read_note as in this tool on any write this tool admits — that parity is about resolution, not about admission: see the two section-mode refusals below, where a section that reads fine is deliberately not writable. Setext (====/----) headings are not matched.

Frontmatter and the round trip. Read a note, edit the content field of the response, pass it straight back to full replacement: the frontmatter survives. No property of content's shape changes that — a body whose first line is a thematic break ---, or which itself begins with a complete mapping-shaped fenced block, is body. A note with no valid block (no line-1 fence, or a malformed one) is replaced wholesale by default, which is the repair path and needs no flag. To change the frontmatter itself use set_frontmatter, or edit the raw block through find=; a read_note response's frontmatter JSON view is a lossy convenience and must never be written back.

The round-trip guarantee covers a complete, unwindowed whole-note read only — read_note(path) with no section, offset=0 and truncated false in the response. A truncated read must be paged to the end before it is written back, or full replacement will replace the whole body with the fragment.

Section mode: what content replaces.

• In section mode content is the section's body: the text beginning on the line immediately after the matched heading line, running to the next heading of equal-or-shallower depth or to end of note. The heading line itself is never removed or rewritten.

• A section write replaces that body whole. Anything content does not resend is deleted — a blank line, a list, and a fenced code block sitting directly under the heading included. There is no third region between the heading line and the body that survives a write.

• So a blank line you want between the heading and its content belongs in content (send "\ntext", not "text").

• read_note(path, section=...) is the matching read: its response carries the heading line in the heading field and the body in the content field, and this tool takes exactly that content. Pass the field through unchanged — there is nothing to split off and nothing to strip.

• Byte-identity holds for notes whose body newlines are LF. Every non-LF terminator inside the selected body (CRLF, or a lone CR) comes back as LF — the read path normalises and this tool writes raw bytes — whether the note uses one dialect throughout or mixes them. Terminators outside the selected body are untouched, so a round trip can leave a note with more mixed endings than it started with.

Section mode resolves headings over the frontmatter-stripped body, exactly as read_note does, so #N ordinals agree between the two and a YAML # comment inside the block is never selectable. A heading inside a fenced code block is not a heading: fences count with up to three spaces of indentation and a closer at least as long as the opener, and an unclosed column-zero fence hides everything below it.

Two shapes refuse a section write outright, naming the problem and writing nothing:

• a malformed frontmatter block (unclosed fence, YAML error, non-mapping) — the refusal names the defect and the replace_frontmatter=True repair;

• a fence opener indented by one to three spaces that nothing below it closes — such an opener may sit inside a list item, whose code block ends where the item does, and this server does not parse container blocks, so it will not guess whether the text below is code or content. Close the fence or unindent it to column zero, then reissue.

Both refusals are asymmetric with reads on purpose: read_note(section=…) and the truncation outline keep working on such notes, because a read destroys nothing.

Flags:

• operation="append": legacy alias for append=True. This is accepted to prevent older clients from silently falling through to full replacement. operation="replace" explicitly selects full replacement.

• replace_all=True: with find, replace every occurrence rather than failing on multiple matches. Ignored when find is unset.

• replace_frontmatter=True: full replacement overwrites the entire file including the frontmatter block. Combined with append/find/section it is an error and nothing is written.

• dry_run=True: compute the would-be result and return a unified diff without writing. Works for all four modes, and diffs the composed result.

Writes are atomic: the composed result is staged in the note's own directory, flushed to disk, and published with a single same-directory rename, so a crash mid-write cannot truncate the destination. The publish is guarded, but only against a change landing inside this call: the file is read here and re-compared immediately before the rename, so a writer racing this tool's own read-modify-write fails with File changed while editing: <name> and nothing is written. That is not a guard on your read — it is the second of the two windows below, and expected_hash is the first. Structured frontmatter mutation is better done via set_frontmatter — PyYAML serialization there discards YAML comments. A path whose final component is a symlink is refused in every mode (dry_run included), naming the link's target; symlinked folders inside the vault work normally.

expected_hash — binding a write to the bytes you read. Optional; omit it and nothing changes, including today's silent overwrite of whatever landed since your read_note. Pass the content_hash a read returned, verbatim and canonical (sha256:<64 lowercase hex>), and the call is refused with nothing written if the file changed in between. It is always the whole file's hash, never a hash of the text you received. Two windows, both live: expected_hash covers your read → this call's read, the server's own pre-publication compare covers this call's read → its publication, and a match on the first does not exempt the second. Every refusal ends with one machine-readable MCP-REFUSAL {"code":…} line — stale_precondition (with the file's current hash, ready to resend), concurrent_write, no_incumbent, malformed_precondition, precondition_unavailable, precondition_required — and each states what resolves it.

It applies in all four modes, dry_run included, and is checked before mode dispatch, the size cap, the diff and every no-op branch, so a stale base never yields a diff or a "no changes" answer. A section= write binds the whole file as well: #N ordinals are positional, so a body-only digest could certify an unchanged body while an insertion above it changed which section the selector names. That makes the narrowest mode the most conflict-prone — an unrelated edit elsewhere refuses it — which is exactly why the argument is optional: bind when you reasoned about what you read, omit when you are appending to a log. Every mode that publishes reports the content_hash of the bytes this call wrote (not of whatever is on disk when you read the message), so an edit→edit chain needs no intervening read; dry_run publishes nothing and reports none.

Args: path: Vault-relative path to the note. content: New body (full replace), replacement text, text to append, or section body. append: If True, append content to the end of the note. operation: Legacy mode selector; accepts "append" or "replace". find: Exact text to find and replace. section: ATX heading text identifying the section whose body to replace. Use Parent/Child to disambiguate repeated headings, or a "#N" ordinal ("#7", 1-based document order) for duplicate siblings. replace_all: With find, replace every match instead of requiring uniqueness. dry_run: Return a unified diff and do not write. replace_frontmatter: Full-replace only. If True, content replaces the entire file including any frontmatter block. Default False preserves an existing valid block. expected_hash: The note's content_hash as you last read it. Refuses the write, changing nothing, if the file has changed since.

Returns a two-part guide for working with this Obsidian vault:

1. Obsidian primer — generic syntax (wikilinks, embeds, block refs, heading refs, tags, frontmatter, callouts, comments, highlights, math, mermaid, footnotes, tasks, plugin literals).

2. Vault-specific conventions — folder structure, naming rules, frontmatter requirements, and tag taxonomy as configured by the vault owner in CLAUDE.md. If CLAUDE.md is absent, the response includes instructions for creating one.

Notes that link TO path. Use this to discover what references a given note — projects citing a card, daily notes mentioning a person, etc.

Resolved links only (dangling references are not counted as backlinks).

Args: path: Vault-relative path to the target note (e.g. "Cards/Foo.md"). limit: Maximum results (default 50, hard cap 500).

Outgoing links from path — both resolved and dangling.

Useful for "what does this note depend on?" or finding broken references that need follow-up notes.

The result carries a truncated field. truncated: true means this note holds more links than the indexer's per-note cap and the list is the first N in document order only — treat it as incomplete rather than as the note's full outgoing-link set.

Links come back in document order and are capped by limit; when more rows exist the result says how many of them were persisted, so a partial page is never read as the whole set. limit raises the page up to a hard cap of 500 — this tool has no paging beyond that, so a note with more than 500 link rows can only be read in full from the note itself.

Each row's link text is clipped to 120 characters.

Args: path: Vault-relative path to the source note. limit: Maximum links returned (default 100, hard cap 500).

The connected subgraph reachable from path via links or backlinks, up to depth hops (treated as undirected).

Use this when an agent needs the local cluster around a topic — e.g. "summarize everything connected to this project". Prefer this over find_related when explicit links are the signal you want; prefer find_related when the connection is conceptual rather than linked.

Args: path: Vault-relative path to the seed note. depth: Maximum BFS depth (default 1, capped at 5). limit: Maximum distinct neighbor notes (default 50, hard cap 200).

Semantically similar notes based on the source note's chunk embeddings, averaged then queried via pgvector.

Independent of the link graph — useful when the source is sparsely linked or when looking for thematic neighbors. For link-based exploration use get_neighborhood. For arbitrary topic queries use semantic_search.

Carries semantic_search's per-row markers and its header counts: stale: true means that neighbour changed after it was embedded, so it was ranked against its previous content and its preview is withheld — read_note returns the current text. embedding_truncated: true means only that note's head was embedded, so a match against it says nothing about its tail.

One marker is about the source rather than a neighbour. If the note you asked about has itself changed since it was embedded, the result says so once, at the top — and it says so on the empty result too. The query vector is the average of the source's stored chunk vectors, so a stale source means every neighbour answers a question about content that note no longer has, and "no related notes" from a stale source means "nothing is near what this note used to say", not "this note has no neighbours". The next embed pass repairs it. A source with no vectors at all is a different message ("has not been embedded yet") with a different fix.

The bound on the staleness signal: it reports what the index has committed, so an edit the indexer has not yet scanned is not marked.

Args: path: Vault-relative path to the source note. limit: Maximum results (default 10, hard cap 50).

Notes with zero incoming AND zero outgoing resolved links — useful for vault hygiene ("what's disconnected?") and cleanup decisions.

Args: folder: Optional vault-relative folder prefix to scope the search (e.g. "Cards/"). limit: Maximum results (default 50, hard cap 500).

Move or rename a note inside the vault. Requires write permission — a readwrite API key, or an OAuth token carrying the readwrite scope.

Updates notes_metadata.file_path for the moved note and note_links.target_path rows whose stored target matched the old path. Backlinks via target_note_id keep working without rewriting source notes (the moved note's id is unchanged).

With rewrite_links=True, also opens every source note that linked to this note and rewrites the link in place: [[Old]] → [[New]], [[Old|alias]] → [[New|alias]], [[Old#anchor]] → [[New#anchor]], ![[Old]] → ![[New]], path-style [[folder/Old]] → [[new/folder/New]], and markdown links [text](Old.md) → [text](<new path>), whose href is written relative to the linking note's own folder (anchors preserved). Aliases and anchors survive; only the target portion is rewritten. The moved note's own body is rewritten as well, so a self-reference does not end up pointing at the old path.

The rewrites are planned before anything changes: if one would push a source note past the 10 MiB note limit the whole move is refused, naming that source, before any file is touched. That preflight is also bounded in aggregate: if the originals plus rewrites for all backlink sources would exceed 256 MiB in memory the move is refused before anything changes, naming the note count and the limit.

The same preflight refuses the whole move, before the rename, when any source it would rewrite — the moved note's own body included — contains a fence opener indented by one to three spaces that nothing below it closes. The refusal names each such source and where its opener sits. A link under such an opener may be inside a list item's code block, which this server does not parse, and a rewrite would mutate text whose code-or-content status had to be guessed. Move with rewrite_links=False (unaffected by this refusal) and fix the links yourself, or close the fences first.

A rewrite can still fail after the move has committed. The move is one rename and the rewrites follow it, so an I/O failure, a vault reassignment, or a database that cannot be reached to confirm the assignment stops the remaining rewrites — and the result then reads partial success: …, naming the sources that still link to the old path. The move is not rolled back and the index rows describe where the note now is. Treat the link graph as agreeing with the vault bytes only when the result reports plain success; on a partial outcome, fix the named sources with edit_note.

Writes are atomic. Either path is refused, naming the link's target, when its final component is a symlink; symlinked folders inside the vault work normally and the recorded paths are the real ones behind them. See get_vault_guide for vault folder conventions.

expected_hash — binding a write to the bytes you read. Optional; omit it and nothing changes. Pass the content_hash a read returned, verbatim and canonical (sha256:<64 lowercase hex>), and the call is refused with nothing written if the file changed in between. It is always the whole file's hash, never a hash of the text you received. expected_hash covers your read through this call's preflight read. The rename pins inode identity but does not compare the bytes again: an in-place edit after that comparison can still be moved. Each optional link rewrite retains its own pre-publication byte comparison. Precondition refusals end with one machine-readable MCP-REFUSAL {"code":…} line — stale_precondition (with the file's current hash, ready to resend), concurrent_write, no_incumbent, malformed_precondition, precondition_unavailable, precondition_required — and each states what resolves it.

Here it binds from_path's own bytes and nothing else, compared before the rename and before any rewrite; the backlink sources a rewrite_links=True move would rewrite are not bound, because you never read them. Success reports the content_hash of the bytes actually published at to_path — the moved bytes for a plain move, the post-rewrite bytes when the moved note's own body was rewritten — and that value binds a following edit_note(to_path, …, expected_hash=…). A rewrite that fails after the rename stays a partial success and never claims nothing was written; if it failed because another writer changed to_path in between, no hash is reported at all and the result says to re-read to_path before writing to it.

Args: from_path: Vault-relative path of the existing note. to_path: Vault-relative path of the destination. Must not exist. Parent directories are created automatically. rewrite_links: If True, also rewrite incoming wikilinks and embeds in source notes. Off by default — opting in is destructive (it modifies other notes' bodies). expected_hash: from_path's content_hash as you last read it. Refuses the move, changing nothing, if that note has changed since.

Delete a note from the vault. Requires write permission — a readwrite API key, or an OAuth token carrying the readwrite scope.

By default this is a soft-delete: the file is moved to .trash/<YYYYMMDD-HHMMSS>-<basename>-<8 hex> inside the vault root, by a single non-replacing rename, so an existing trash entry is never overwritten and two deletes in the same second land on distinct names. The indexer skips dot-prefixed directories, so search and embeddings drop the note automatically on the next reindex pass (≤ 5 minutes). Soft-deleted files accumulate in .trash/ — emptying that directory is the user's responsibility.

A vault filesystem that cannot perform that non-replacing rename into .trash/ makes the soft delete refuse with an error naming the limitation rather than fall back to a rename that could overwrite; pass permanent=True to unlink instead.

With permanent=True, the file is unlinked directly with no recovery path inside this server. Existing backups are the rollback story.

A path whose final component is a symlink is refused, naming its target, so a delete never removes a note other than the one named; symlinked folders inside the vault work normally.

Dangling backlinks left behind by a delete are surfaced via get_backlinks and find_orphans. See get_vault_guide for context.

expected_hash — binding a write to the bytes you read. Optional; omit it and nothing changes. Pass the content_hash a read returned, verbatim and canonical (sha256:<64 lowercase hex>), and the call is refused with nothing written if the file changed in between. It is always the whole file's hash, never a hash of the text you received. expected_hash covers your read through this call's preflight read. The delete acts through the pinned parent directory but does not compare the bytes again: an in-place edit after that comparison can still be deleted. Precondition refusals end with one machine-readable MCP-REFUSAL {"code":…} line — stale_precondition (with the file's current hash, ready to resend), concurrent_write, no_incumbent, malformed_precondition, precondition_unavailable, precondition_required — and each states what resolves it.

It applies in both modes, and the comparison runs before the .trash rename and before the unlink, so a refused delete leaves the note where it was and creates no trash entry. A successful delete reports no content_hash: nothing remains to hash.

Args: path: Vault-relative path to the note. permanent: If True, unlink instead of soft-deleting. expected_hash: The note's content_hash as you last read it. Refuses the delete, changing nothing, if the note has changed since.

Mutate a note's YAML frontmatter without touching its body. Requires write permission — a readwrite API key, or an OAuth token carrying the readwrite scope.

Parses the existing frontmatter, merges in updates (overwriting matching keys, adding any new ones), then drops keys listed in remove. The note body is preserved byte-for-byte. If the note has no frontmatter (no --- fence on line 1), a fresh block is prepended ahead of the unchanged body.

A malformed block is refused, never worked around. An unclosed line-1 fence, YAML that fails to parse, and YAML that is not a mapping (null, ~, comments only, a list, a scalar) each return an error naming the defect and pointing at edit_note(path, content, replace_frontmatter=True) as the repair. Nothing is written — in particular no second block is prepended above the broken one — and remove= refuses identically rather than silently doing nothing. This is reported even for a call with no updates and no remove. An empty fenced block (--- immediately followed by ---) is valid: it is a valid empty mapping and is updated in place.

Only an effective change writes. updates that set every named key to the value it already holds (compared type-sensitively, so true is not 1) together with remove naming only absent keys report no changes and leave the file byte-identical. Removing the last key removes the block entirely — no fences, no separator, exactly the prior body.

Re-serialization uses yaml.safe_dump(default_flow_style=False, sort_keys=False, allow_unicode=True). Caveat: PyYAML does NOT preserve YAML comments — any # comment in the original frontmatter will be lost on the first set_frontmatter call.

A path whose final component is a symlink is refused, naming its target, so the frontmatter of an unnamed note is never rewritten; symlinked folders inside the vault work normally.

See get_vault_guide for vault frontmatter conventions.

expected_hash — binding a write to the bytes you read. Optional; omit it and nothing changes. Pass the content_hash a read returned, verbatim and canonical (sha256:<64 lowercase hex>), and the call is refused with nothing written if the file changed in between. It is always the whole file's hash, never a hash of the text you received. Two windows, both live: expected_hash covers your read → this call's read, the server's own pre-publication compare covers this call's read → its publication, and a match on the first does not exempt the second. Every refusal ends with one machine-readable MCP-REFUSAL {"code":…} line — stale_precondition (with the file's current hash, ready to resend), concurrent_write, no_incumbent, malformed_precondition, precondition_unavailable, precondition_required — and each states what resolves it.

The comparison runs ahead of the malformed-block diagnosis and ahead of the no-op check, so a stale base never yields "no changes" or a defect report about bytes you have not seen. A write reports the content_hash of the bytes this call published; a no-op publishes nothing and reports none.

Args: path: Vault-relative path to the note. updates: Mapping of keys to set. Use the empty dict (or omit) to skip. remove: List of keys to delete from the frontmatter. Missing keys are ignored (and, on their own, make the call a no-op rather than a write). expected_hash: The note's content_hash as you last read it. Refuses the write, changing nothing, if the note has changed since.

Read any file in the vault — including non-markdown (PDFs, images, skill HTML/JS, data files). Peer to read_note, which stays markdown-only.

This is pure byte transport: the server does NOT extract or parse PDFs and cannot interpret binary bytes. Non-text/non-image files come back as an opaque base64 string intended for a client-side skill to decode — not as something the model can read directly.

Encoding:

• "auto" (default): text-like files (HTML, JSON, CSV, source, …) return as readable text; images (PNG/JPEG/GIF/WebP) return as an inline image block that renders in-client; everything else returns as a labeled base64 string.

• "text": force a UTF-8 text decode; errors if the file is not valid UTF-8.

• "base64": force a raw-bytes base64 string regardless of type.

Files larger than MAX_FILE_READ_BYTES (default 10 MB) are refused with a size report. Base64 reads pass through the model context and inflate ~33%, so they are token-heavy — check a file's size with list_files before reading large binaries. Any path with a component starting with . is rejected — dot-directories (.obsidian, .git, .trash, …) and dot-files alike — as is path traversal.

Text results are additionally capped to a context-safe size: the cap bounds the returned window, and a truncated read appends a short notice carrying the offset to continue from. Base64 and image results are not windowed.

The base64 header and hash_only=True return the whole raw file's content_hash (sha256:<64 lowercase hex>), which write/delete tools accept as expected_hash. Their path is a quoted JSON string. Text stays deliberately unenveloped. Use base64 for byte-exact frontmatter bytes; read_note.frontmatter_yaml has normalized line endings.

Encoding is validated first, then hash_only/window compatibility, then ranges. hash_only refuses offset != 0 or any non-None limit; explicitly passing offset=0 is fine. A valid encoding has no effect in this mode.

Args: path: Vault-relative path to the file (e.g. "Reference Docs/spec.pdf"). hash_only: Return only path, byte count, MIME and hash, with no content. encoding: One of "auto" (default), "text", or "base64". offset: Character offset to start a text read from (default 0). Use the value the truncation notice reports to continue. limit: Maximum characters to return for a text read. Only lowers the server cap; it cannot raise it.

Write a file into the vault — including non-markdown (e.g. save a generated PDF or image). Requires write permission — a readwrite API key, or an OAuth token carrying the readwrite scope. Peer to create_note/edit_note, which stay markdown-only.

content carries the bytes: with encoding="base64" (default) it is base64-decoded to raw bytes; with encoding="text" it is written verbatim as UTF-8. The write is atomic — the bytes are staged and flushed before anything is published — missing parent folders are created, and content over MAX_FILE_WRITE_BYTES (default 25 MB, decoded length) is refused.

No-clobber by default: writing over an existing file requires overwrite=True. The default publishes by linking a staged, never-named inode into place in one kernel-atomic step, so an existing file cannot be replaced; overwrite=True publishes with a single same-directory rename instead. A vault filesystem that cannot stage an unnamed file refuses the no-clobber write with an error naming VAULT_ALLOW_NAMED_STAGING_FALLBACK, rather than staging under a visible name. Any path with a component starting with . (dot-directories and dot-files alike) and path traversal are rejected; invalid base64 errors without writing anything. A path whose final component is a symlink is refused, naming its target, so overwrite=True cannot clobber a file through an alias; symlinked folders inside the vault work normally.

The MCP transport also bounds the whole request body (sized so a base64 write at the cap always gets through). Base64 is therefore the always-safe encoding: encoding="text" content whose JSON escaping inflates past that bound is rejected by the transport with a bare HTTP 413 before this tool runs — send such content as base64 instead.

Optional expected_hash binds an existing whole file on overwrite=True. Obtain its canonical sha256:<64 lowercase hex> value from read_file's base64 header, read_file(hash_only=True), or a prior write's success. Syntax is checked before path work; a hash with no-clobber or a missing destination is no_incumbent. An over-cap incumbent cannot be guarded. A stale hash refuses before publication; matching also enables the in-call comparison, which refuses an edit arriving during this call as concurrent_write. Without a hash, overwrite remains unconditional unless the deployment requires preconditions. Creation is exempt.

Success reports the hash of the bytes this call published, not necessarily what remains when the response arrives. Over-cap incumbents or results omit the hash without failing an otherwise permitted unguarded write.

Args: path: Vault-relative destination path (e.g. "Outputs/report.pdf"). content: File contents — base64 string (default) or UTF-8 text. encoding: "base64" (default) or "text". overwrite: If True, replace an existing file. Off by default. expected_hash: Optional whole-file raw-byte digest of the incumbent.

Browse the vault filesystem (ls-style), including non-markdown files. Peer to list_notes, which lists indexed markdown only; list_files reads the filesystem directly and reports sizes so you can gauge a binary before read_file.

By default lists the immediate children of folder — subdirectories and files, each file with size and modification time. pattern is a glob that filters file entries (e.g. "*.pdf"); recursive=True descends into subfolders and returns matching files. Anything with a path component starting with . is hidden — dot-directories (.obsidian, .git, .trash, …) and dot-files — and a folder with such a component is rejected.

At most limit entries are returned (default 200, hard cap 1000); the response indicates when the listing was truncated.

Args: folder: Vault-relative folder (default "." = vault root). pattern: Glob applied to file names (default "*"). recursive: If True, descend into subfolders. Off by default. limit: Maximum entries to return (default 200, hard cap 1000).

Get a short-lived link a person can use to put a file into the vault. Requires write permission — a readwrite API key, or an OAuth token carrying the readwrite scope. Peer to write_file, which takes the bytes directly — use this one when you do not have them.

No MCP client can hand a tool the bytes of a file the user is looking at, and your shell cannot reach their machine. This mints a link bound to exactly one destination path: hand it to the person you are helping, they open it and pick a file, and it lands at path. Nothing else can be written with it.

The token lives in the URL's # fragment, which browsers never send to a server, so it stays out of access logs. Treat the whole URL as a secret — whoever holds it can write that one path, once, until it expires. Never put it in a query string: that would log it.

Single use, and no-clobber unless you ask otherwise. With overwrite=True the link also remembers what the file looked like now and refuses to publish if it changed in the meantime, so a stale link cannot silently undo an edit someone made while it was waiting.

From a shell you can upload without the page: curl -H "Authorization: Bearer <token>" -T <file> <base>/transfer/upload.

Then call check_upload(upload_id) to confirm the bytes landed and get their sha256. See get_vault_guide for how files fit into the vault.

Args: path: Vault-relative destination (e.g. "Attachments/photo.png"). overwrite: If True, allow replacing an existing file at path. expires_in: Seconds until the link dies. Clamped to 60–3600; defaults to TRANSFER_TOKEN_TTL_SECONDS (600). A link can never outlive the credential you are calling with, so the deadline in the result may be earlier than you asked for — it says so when that happens.

Ask what happened to an upload link you minted with request_upload.

Returns one of pending (nothing sent yet), uploading (bytes are in flight), completed (with the path, size, sha256 and MIME type of what landed), unknown (a stream started and the server never recorded how it ended), revoked (the link is dead because the credential or vault root changed under it), or expired. Use it to confirm a transfer really finished before you tell the user it did, and to get the sha256 if they want to verify it.

Visibility is scoped to the principal that minted the link, not to one credential row. For an API key that is the key itself. For OAuth it is the whole grant family behind the access token you are calling with, so a handle stays readable across the hourly token refresh that mints a new row. A different API key, a different client, or a separate approval of the same client reads as not found.

uploading names the deadline the stream has. Check again after it: past that point the answer becomes either completed or unknown. unknown does not mean nothing arrived — a publish can succeed and still fail to record its completion — so read or list the path before minting another link or telling anyone the file did not arrive.

Pass the upload_id itself — the short handle from request_upload, not the upload URL and not the token after the #. Anything else is refused without a lookup.

Args: upload_id: The upload_id that request_upload returned.

Get a short-lived link a person can use to save a vault file. Peer to read_file, which returns the bytes to you — use this one when the file is for the human, not for you.

Handy for anything read_file would waste context on or cannot render: a PDF, a large image, an archive. Reading works with a read-only key.

The token lives in the URL's # fragment, so it never reaches an access log. Treat the whole URL as a secret — whoever holds it can read that one file until it expires. Never put it in a query string.

The link is bound to the file as it is now: if it is edited or replaced, the link stops working rather than serving different content than you described. Unlike an upload link it can be used more than once, so the person can preview and then save.

From a shell: `curl -H "Authorization: Bearer " -o

Args: path: Vault-relative path of the file to share. expires_in: Seconds until the link dies. Clamped to 60–3600; defaults to TRANSFER_TOKEN_TTL_SECONDS (600). A link can never outlive the credential you are calling with, so the deadline in the result may be earlier than you asked for — it says so when that happens.

Fetch a file from a public https URL straight into the vault. Requires write permission — a readwrite API key, or an OAuth token carrying the readwrite scope. Peer to write_file and request_upload — use this one when the bytes are already somewhere public.

The server does the fetching, so nothing passes through your context: a 20 MB PDF costs one tool call. Returns the path, size, sha256, MIME type and the final URL after any redirects.

Only genuinely public addresses. This server sits on a private network next to a database and other services, so the fetch is restricted: https only — plain http is refused unless the operator has set IMPORT_ALLOW_HTTP=true — no credentials in the URL, no private/loopback/link-local/metadata addresses in any spelling, and the same rules re-checked at every redirect. A refusal names the rule that was violated — that is information about the URL, not a hint to work around it. Rewriting the URL to evade the check is never the right next step; ask the user for a public link instead.

Size-capped at MAX_FILE_WRITE_BYTES, with one 30-second deadline for the whole fetch. No-clobber unless overwrite=True. Nothing is written unless the whole body arrives intact.

This tool shares the transfer tools' preflight, so it also refuses when the server has no public origin configured (MCP_HOSTNAME or BASE_URL), even though it mints no link — that is an operator setting, not something to work around.

Args: url: Public https URL of the file. path: Vault-relative destination (e.g. "Attachments/paper.pdf"). overwrite: If True, allow replacing an existing file at path.

Delete a non-markdown file from the vault. Requires write permission — a readwrite API key, or an OAuth token carrying the readwrite scope. Peer to delete_note, which stays markdown-only.

By default this is a soft delete: the file moves to .trash/<YYYYMMDD-HHMMSS>-<basename>-<8 hex> inside the vault, keeping a copy the user can recover. Two files with the same name deleted in the same second both survive — the trash never clobbers.

With permanent=True the file is unlinked outright and this server has no recovery path; the user's backups are the only rollback.

Refuses markdown files (use delete_note, which understands the index and backlinks), directories, and symlinks. Non-markdown files are not indexed, so search and embeddings are unaffected either way.

Optional expected_hash binds the whole raw file in either mode. Use the canonical sha256:<64 lowercase hex> from read_file's base64 header, read_file(hash_only=True), or a write success. Malformed hashes refuse before path checks; unavailable, required and stale preconditions refuse before any trash entry or unlink. The deployment may require a hash. This checks the caller-read-to-call window; a later concurrent replacement remains possible, so it is not an atomic filesystem compare-and-delete. A successful delete reports no content hash.

Args: path: Vault-relative path to the file. permanent: If True, unlink instead of moving to .trash/. expected_hash: Optional whole-file raw-byte digest of the incumbent.