basic-memory

Read note

bm_read

Read-onlyIdempotent

Read a Basic Memory note or file by path, permalink, memory:// URL, or exact title, and slice long content by section, line range, or token budget.

Instructions

Read a Basic Memory note or file by path, permalink, memory:// URL or exact title. Slice a long note with section (a heading), start_line/end_line or max_tokens; line numbers count the whole file, frontmatter included. A text file such as .txt takes start_line/end_line too. include_content=false returns only the metadata and the checksum that bm_write and bm_edit take as expected_checksum. Images come back as images and other binary files as documents. A missing note is an error: find notes with bm_search.

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": {
      "identifier": "<identifier>",
      "project": "<project>"
    },
    "name": "bm_read"
  }
}

Input Schema

Name	Required	Description	Default
`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.
`section`	No	A heading to read: "Decisions", "Auth/Decisions" for a heading under "Auth", or "Decisions[1]" for the second "Decisions" heading.
`end_line`	No
`identifier`	Yes	The note or file: a file path ('notes/plan.md'), permalink, memory:// URL, exact title, external id, or '<project>/path'.
`max_tokens`	No	Approximate token budget. Longer content is cut at a section or paragraph boundary, and the result says which line to continue from.
`start_line`	No
`output_format`	No		text
`include_content`	No	False returns only title, paths, checksum and updated_at.
`include_frontmatter`	No	Include the YAML frontmatter in a whole-note read.

Schema Changelog

Changes observed during successful MCP inspections.

Changed6 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: -[
-  "identifier"
-]New value: +[
+  "identifier",
+  "project"
+]

Addedv0.24.1Oct 23, 2026

TDQS

A4.6/5.0

Behavior5/5

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

Beyond the readOnly/idempotent annotations, it discloses non-obvious behavior: missing notes raise an error rather than returning empty, images come back as images and other binaries as documents, truncation via max_tokens reports a continuation line, and the checksum is the expected_checksum value consumed by bm_write/bm_edit. That cross-tool linkage is exactly the kind of context annotations cannot carry.

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?

Front-loaded with the core action, then slicing options, then the metadata/checksum mode, then edge cases — a sensible order with no filler. It is dense and long for a read tool, but every clause carries distinct information.

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

Completeness5/5

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

With 9 parameters and no output schema, the description carries the return-value burden well: it says what comes back for notes, text files, images and binaries, what the truncated response includes, and what metadata-only mode yields. Nothing essential for a correct call is missing.

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?

At 67% schema coverage it adds real meaning: line numbers count the whole file including frontmatter, section accepts a heading path or an indexed repeat ('Decisions[1]'), max_tokens cuts at section/paragraph boundaries, and include_content=false returns title, paths, checksum and updated_at. It leaves output_format, start_line and end_line's own semantics (e.g., default end) unstated.

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+resource ('Read a Basic Memory note or file') and enumerates the accepted identifier forms (path, permalink, memory:// URL, exact title), which lets an agent map its input to this tool immediately. It also distinguishes itself from the discovery sibling by naming bm_search.

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?

Gives clear routing: 'A missing note is an error: find notes with bm_search,' and explains the metadata-only mode via include_content=false for checksum lookups. It stops short of naming other plausible alternatives (bm_find, bm_list, bm_context) or stating when not to read a whole file.

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

Deploy Server