read_note
Retrieve note content and metadata from an Obsidian vault by path, with optional section or offset for partial reads. Returns structured fields for direct editing or analysis.
Instructions
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 whatedit_note(path, content)full replacement accepts. Section reads: the section's body only, which is exactly whatedit_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 ofcontent, 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 residualcontentcarries, because this tool normalises and the write tools work on raw bytes;edit_notestill reattaches the original block byte-identically). This is the authoritative copy.frontmatteris 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, andmetadata_omissionsthen says which and why. To change frontmatter useset_frontmatter, or edit the raw block withedit_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#Nordinal so you can fetch the one you want directly, andnoticecarries 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 asexpected_hashto 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 ofcontent— 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_fileon the same path is the byte-exact route to the file itself,frontmatter_yamlhere being authoritative but LF-normalized.error— set when the read failed (missing note, badoffset/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.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | ||
| limit | No | ||
| offset | No | ||
| section | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| tags | No | ||
| error | No | ||
| title | No | ||
| notice | No | ||
| offset | No | ||
| content | No | ||
| heading | No | ||
| outline | No | ||
| truncated | No | ||
| frontmatter | No | ||
| next_offset | No | ||
| total_chars | No | ||
| content_hash | No | ||
| frontmatter_yaml | No | ||
| metadata_coercions | No | ||
| metadata_omissions | No |