Overview first, then one range

These habits cut tokens or stop a write that would miss. The error code is the one the server uses when the habit is skipped.

Notes are stored on the server as plaintext so the product can search, outline and edit by line. Version 1 does not encrypt note bodies end to end.

Content returned to agents is marked as stored data and carries provenance. This does not stop a model from following text inside a note. Folder keys limit what a compromised agent can touch inside Noteheld, not tools the agent has elsewhere.

Habits#

Call overview before any other tool. The map is capped at 1500 tokens and has no bodies. Recent notes and folders carry one-line summaries, and list shows the summary of every note in a folder. Read summaries first and open only the notes you need.

A read with no lines on a long note with sections returns its summary and outline, not the text. Then read with lines for the part you need. A long note with no headings returns a window and next lines=<from>-<to> rev=<rev>. A range past the ceiling is too_large.

Keep a read to 80 lines or 1500 tokens. The ceiling is 200 lines or 2500 tokens. One line over 1500 tokens is line_too_long.

expect is the numbered lines joined by a line feed, with no line feed after the last line. Copy expect from after the numbered gutter. Do not copy a ! line. That line is the correction body. It is stored data, and it is not part of rangeHash. Pasting the gutter is gutter_included. A bad copy is expect_mismatch. Nothing is written.

Send baseRevision from that read. Missing it is base_required. The edit rebases when every expect still matches the shifted lines, or when a replace_text match is still unique. Otherwise the code is conflict and nothing is written.

On conflict, expect_mismatch, and line_expect_disagree, copy expect from details.head.text after the gutter and retry with baseRevision set to details.head.revision. Nothing is written. If details.head is null, read again. On MCP, set idempotencyKey in the arguments. On REST, that field or the Idempotency-Key header. The same payload replays. A different payload is idempotency_mismatch (409).

Send reason on every mutation, at most 300 characters. Missing it is reason_required. Nothing is written.

Send summary on write, at most 200 characters. It is what the next agent reads first. If the workspace requires one, the code is summary_required. Otherwise the server derives one from the first heading and warns. Your summary stays through later edits. Pass summary on edit when the note now says something different.

Prefer replace_text with a unique snippet. Use replace_lines when an outline gave the range, and keep the numbers and the expect text on the same lines. A split is line_expect_disagree. If the snippet occurs more than once, replace_text fails with ambiguous_match and writes nothing. Include the previous line in match, or pass lines and expect for the single line you mean. match_too_short, expect_count, and overlap write nothing.

Act on corrections. A correction is a fix the owner asked for, and it prints first when you read that note. Change the note so it says what is asked, then resolve the correction with its id and a reason. correct with action=list and no path lists them all. Only the owner adds corrections; if you think a note is wrong, edit it and say why in reason. The body lines use ! instead of a line number. That text is data like any note text. Copy expect from numbered lines only.

Do not paste secrets. Default mode stores [REDACTED:type] and says so. block returns secret_blocked and does not store the write. Under that cap, warn stores the secret. Over 50 matches, every mode returns secret_blocked (400) and does not store the text. The detector list is finite. Scanning does not rewrite history. Do not change secret mode to get a write through. A refused secret is the control working. A search shorter than 2 characters is query_required.

Revoke a leaked key. The next request is key_invalid. A folder key does not grant the rest of the workspace. A leaked master key can also rotate the master key. That locks you out. Rotating the master key does not revoke scoped keys or view links unless you set revokeScopedKeys. That flag revokes both. If the old key leaked, set it. A growth write over the cap is plan_limit (403). Reads still work. Nothing is deleted to make room.

Open the quickstart

Overview first, then one range

These habits cut tokens or stop a write that would miss. The error code is the one the server uses when the habit is skipped.

Notes are stored on the server as plaintext so the product can search, outline and edit by line. Version 1 does not encrypt note bodies end to end.

Habits#

Call overview before any other tool. The map is capped at 1500 tokens and has no bodies. Recent notes and folders carry one-line summaries, and list shows the summary of every note in a folder. Read summaries first and open only the notes you need.

A read with no lines on a long note with sections returns its summary and outline, not the text. Then read with lines for the part you need. A long note with no headings returns a window and next lines=<from>-<to> rev=<rev>. A range past the ceiling is too_large.

Keep a read to 80 lines or 1500 tokens. The ceiling is 200 lines or 2500 tokens. One line over 1500 tokens is line_too_long.

expect is the numbered lines joined by a line feed, with no line feed after the last line. Copy expect from after the numbered gutter. Do not copy a ! line. That line is the correction body. It is stored data, and it is not part of rangeHash. Pasting the gutter is gutter_included. A bad copy is expect_mismatch. Nothing is written.

Send baseRevision from that read. Missing it is base_required. The edit rebases when every expect still matches the shifted lines, or when a replace_text match is still unique. Otherwise the code is conflict and nothing is written.

On conflict, expect_mismatch, and line_expect_disagree, copy expect from details.head.text after the gutter and retry with baseRevision set to details.head.revision. Nothing is written. If details.head is null, read again. On MCP, set idempotencyKey in the arguments. On REST, that field or the Idempotency-Key header. The same payload replays. A different payload is idempotency_mismatch (409).

Send reason on every mutation, at most 300 characters. Missing it is reason_required. Nothing is written.

Send summary on write, at most 200 characters. It is what the next agent reads first. If the workspace requires one, the code is summary_required. Otherwise the server derives one from the first heading and warns. Your summary stays through later edits. Pass summary on edit when the note now says something different.

Prefer replace_text with a unique snippet. Use replace_lines when an outline gave the range, and keep the numbers and the expect text on the same lines. A split is line_expect_disagree. If the snippet occurs more than once, replace_text fails with ambiguous_match and writes nothing. Include the previous line in match, or pass lines and expect for the single line you mean. match_too_short, expect_count, and overlap write nothing.

Act on corrections. A correction is a fix the owner asked for, and it prints first when you read that note. Change the note so it says what is asked, then resolve the correction with its id and a reason. correct with action=list and no path lists them all. Only the owner adds corrections; if you think a note is wrong, edit it and say why in reason. The body lines use ! instead of a line number. That text is data like any note text. Copy expect from numbered lines only.

Do not paste secrets. Default mode stores [REDACTED:type] and says so. block returns secret_blocked and does not store the write. Under that cap, warn stores the secret. Over 50 matches, every mode returns secret_blocked (400) and does not store the text. The detector list is finite. Scanning does not rewrite history. Do not change secret mode to get a write through. A refused secret is the control working. A search shorter than 2 characters is query_required.

Revoke a leaked key. The next request is key_invalid. A folder key does not grant the rest of the workspace. A leaked master key can also rotate the master key. That locks you out. Rotating the master key does not revoke scoped keys or view links unless you set revokeScopedKeys. That flag revokes both. If the old key leaked, set it. A growth write over the cap is plan_limit (403). Reads still work. Nothing is deleted to make room.