basic-memory

Edit note

bm_edit

Destructive

Edit existing Basic Memory notes by appending, prepending, replacing text or headings, or merging frontmatter metadata, with checksum protection to avoid overwriting newer changes.

Instructions

Change part of an existing Basic Memory note. command: append or prepend content; find_replace find_text with content (exact text, which must occur expected_replacements times, default 1); replace_section, insert_before_section or insert_after_section for a section heading ('Decisions', 'Auth/Decisions', 'Decisions[1]', as bm_read takes it); set_metadata to merge metadata into the frontmatter without touching the body. metadata also merges with any other command. Pass expected_checksum (from bm_read) to edit only the revision you read. A missing note is an error; create notes with bm_write.

Input Schema

Name	Required	Description	Default
`command`	Yes	The edit.
`content`	No	The text to add or the replacement. Not used by set_metadata.
`project`	No	Project name, 'workspace/project', or project external id. Omit to use the default project.
`section`	No	The heading for section commands: "Decisions", "Auth/Decisions" for one under "Auth", or "Decisions[1]" for the second of two.
`metadata`	No	Frontmatter fields to set; other fields are kept.
`find_text`	No	For find_replace: the exact, case-sensitive text to replace.
`identifier`	Yes	The note or file: a file path ('notes/plan.md'), permalink, memory:// URL, exact title, external id, or '<project>/path'.
`output_format`	No		text
`expected_checksum`	No	Edit only while the note is still this revision (from bm_read).
`replace_subsections`	No	For replace_section: true replaces the section's subsections too; false stops at the first subsection heading.
`expected_replacements`	No	For find_replace: how many times find_text must occur.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Addedv0.24.1Oct 23, 2026

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already mark this as destructive, non-read-only, and non-idempotent. The description adds useful behavior beyond those hints: optimistic concurrency via expected_checksum, exact replacement-count enforcement, missing-note errors, and metadata merging without touching the body. It does not call out that replace_section may remove subsections by default, though the schema documents that.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is dense but front-loaded and appropriate for a seven-command editing tool. Every sentence adds operational detail, and the command mapping is organized efficiently despite the compact paragraph form.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the rich schema, output schema, and annotations, the description covers the critical editing semantics and error behavior. Minor gaps remain around explicitly warning about replace_subsections' destructive default and fully differentiating from the edit_note sibling.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is high, but the description adds cross-parameter meaning that is not obvious from individual field descriptions: how command selects content, find_text, section, metadata, and expected_checksum behavior, including that metadata merges with any command and expected_checksum comes from bm_read.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description gives a specific verb, resource, and scope: changing part of an existing Basic Memory note. It also distinguishes creation by directing missing notes to bm_write, but it does not explicitly differentiate itself from the sibling edit_note tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It clearly states that missing notes are errors and should be created with bm_write, and it references bm_read for checksums and section syntax. It does not give an explicit when-not rule against using sibling tools such as edit_note.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.