basic-memory

Write note

bm_write

Destructive

Create or replace a Markdown note by file path or title, with overwrite control and checksum-guarded updates to prevent conflicting edits.

Instructions

Create or replace a Basic Memory note. Give a file path as identifier ('notes/plan.md'), or title plus directory. With a path the file lands exactly there and the title comes from the content's frontmatter, then title, then the file name. An existing note is an error unless overwrite=true; pass expected_checksum (from bm_read) to replace only the revision you read. To change part of a note use bm_edit. Content may hold frontmatter, observations ('- [category] fact #tag') and relations ('- relation_type [[Other Note]]').

Tool call template

Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {
      "content": "<content>",
      "project": "<project>"
    },
    "name": "bm_write"
  }
}

Input Schema

Name	Required	Description	Default
`tags`	No	Tags, as a list or 'a,b,c'.
`title`	No	Note title. With `directory`, it also names the file. With `identifier`, it is used when the content has no frontmatter title.
`content`	Yes	The note's Markdown. Saved as given; it may start with frontmatter.
`project`	Yes	Required project name, 'workspace/project', or project external id. Discover projects with bm_project(command='list'). Paths are relative to this project; a qualified path must agree with it.
`metadata`	No	Extra frontmatter fields, merged into the note's frontmatter.
`directory`	No	Folder for a note addressed by title, e.g. 'meetings'; '/' is the root.
`note_type`	No	Frontmatter `type:`. A `type:` in the content wins.	note
`overwrite`	No	Replace a note that already exists. Default: the write_note_overwrite_default setting (false unless changed).
`identifier`	No	File path for the note, e.g. 'notes/plan.md'; '.md' is added when missing. '<project>/path' writes into another project. Use instead of title + directory.
`output_format`	No		text
`expected_checksum`	No	Replace the note only while it is still this revision (the checksum from bm_read). Implies overwrite=true.

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed7 schema fields changedOct 31, 2026

removedInput schema / properties / project / anyOf

Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]

removedInput schema / properties / project / default
```
Removed value: -null
```

changedInput schema / properties / project / description

Previous value: -"Project name, 'workspace/project', or project external id. Omit to use the default project."New value: +"Required project name, 'workspace/project', or project external id. Discover projects with bm_project(command='list'). Paths are relative to this project; a qualified path must agree with it."

addedInput schema / properties / project / minLength
```
Added value: +1
```
addedInput schema / properties / project / type
```
Added value: +"string"
```

changedInput schema / required

Previous value: -[
-  "content"
-]New value: +[
+  "content",
+  "project"
+]

changedOutput schema / properties / result / anyOf

Previous value: -[
-  {
-    "additionalProperties": true,
-    "type": "object"
-  },
-  {
-    "type": "string"
-  }
-]New value: +[
+  {
+    "type": "string"
+  },
+  {
+    "additionalProperties": true,
+    "type": "object"
+  }
+]

Addedv0.24.1Oct 23, 2026

TDQS

A4.5/5.0

Behavior4/5

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

Annotations already declare destructiveHint=true and idempotentHint=false, but the description adds the crucial nuance that writes are non-destructive by default and only overwrite when asked, plus optimistic-concurrency semantics via `expected_checksum`. It also discloses title-resolution precedence (frontmatter, then `title`, then file name). Missing only auth/permission context and whether the project must pre-exist, which keeps it off a 5.

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

Conciseness4/5

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

Four dense sentences ordered from what the tool does, to how to address the note, to conflict handling, to content shape. Zero filler, though the content-syntax sentence packs three concepts (frontmatter, observations, relations) into one trailing clause.

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?

An output schema exists, so return values need not be described, and the remaining parameters (tags, metadata, note_type, output_format) are documented in the schema at 91% coverage. What an agent needs for correct invocation — addressing, overwrite, checksum, content format — is all present; only cross-project path qualification is hinted at rather than explained.

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

Parameters4/5

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

Schema coverage is 91%, so the baseline is 3, but the description adds real precedence rules the schema does not: the title is taken from frontmatter first, then `title`, then the file name, and that a path pins the file exactly. That resolves the ambiguity between the `identifier` and `title`/`directory` parameters.

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

Purpose5/5

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

States a specific verb and resource ('Create or replace a Basic Memory note') and immediately names the sibling it is not ('To change part of a note use bm_edit'). An agent can separate bm_write from bm_edit and bm_delete without opening any schema.

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

Usage Guidelines5/5

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

Gives explicit addressing alternatives (file path as `identifier` vs `title` + `directory`), states that an existing note errors unless `overwrite=true`, and points to bm_read as the source of `expected_checksum` for revision-safe replacement. The redirect to bm_edit is an explicit when-not rule.

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

Deploy Server