basic-memory

Read Note

read_note

Read-only

Retrieve a Markdown note by title or permalink, optionally a numbered line range. If no note matches directly, get related-note suggestions or metadata and checksum only.

Instructions

Read a markdown note by title or permalink, optionally a numbered line range. If the identifier doesn't resolve directly, a note whose title matches it exactly (case-insensitive) is returned with full content; otherwise it returns related-note suggestions from text search instead of content. Pass include_content=false to get only the note's metadata and checksum.

Input Schema

Name	Required	Description	Default
`page`	No	Page of fallback-search results to use when the identifier does not resolve to a note directly (default: 1). A direct or exact-title match returns the note content — page/page_size never chunk the note itself, and the title-match lookup pages through fixed-size pages of title results until an exact match is found or results are exhausted, regardless of page or page_size. Aliases: page_number.
`project`	No	Project name to read from. Optional - when omitted, a project prefix on a memory:// URL or permalink identifier routes the read; otherwise the server uses the configured default project. If unknown, use list_memory_projects() to discover available projects.
`end_line`	No	Last document line to read (inclusive); omitted means EOF. Out-of-file ranges return empty content; invalid/reversed ranges fail. With either bound, text output is numbered and JSON carries coordinates, has_more, and next_start_line/next_end_line. include_frontmatter does not strip an explicitly addressed range. Edits between calls may shift lines.
`page_size`	No	Number of fallback-search results per page (default: 10). When no match is found, this caps how many related-note suggestions are listed. Aliases: limit, per_page.
`identifier`	Yes	The title or permalink of the note to read. Can be a full memory:// URL, a permalink, a title, or search text. From the CLI this is a positional argument, not a flag.
`project_id`	No	Project external_id (UUID). Prefer this over `project` when known — it routes to the exact project regardless of name collisions across cloud workspaces. Takes precedence over `project`. Get from list_memory_projects().
`start_line`	No	First document line to read (1-based, inclusive). Defaults to 1 when only end_line is given. Line scans count the full Markdown, including frontmatter, matching cat's default line coordinates.
`output_format`	No	"text" returns markdown content or guidance text. "json" returns a structured object with title/permalink/file_path/content/frontmatter. Unresolved notes carry error="NOTE_NOT_FOUND" and a message, with related_results when suggestions are available.	text
`include_content`	No	Default true. Set to false to return only the note's metadata — title, permalink, file_path, the full accepted-revision checksum, and updated_at — without the body. Use it to refresh the checksum that edit_note/write_note take as expected_checksum without reading the whole note. Cannot be combined with start_line/end_line.
`include_frontmatter`	No	For unsliced JSON reads, include opening YAML in content; parsed frontmatter is returned either way. Explicit line ranges are never stripped. CLI: --frontmatter (--include-frontmatter is a deprecated alias).

Output Schema

Name	Required	Description	Default
`result`	Yes

Schema Changelog

Changes observed during successful MCP inspections.

Changed19 schema fields changedv0.24.1Oct 23, 2026

addedInput schema / additionalProperties
```
Added value: +false
```

addedInput schema / properties / end_line

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Last document line to read (inclusive); omitted means EOF.\nOut-of-file ranges return empty content; invalid/reversed ranges fail.\nWith either bound, text output is numbered and JSON carries coordinates,\nhas_more, and next_start_line/next_end_line. include_frontmatter does\nnot strip an explicitly addressed range. Edits between calls may shift lines."
+}

addedInput schema / properties / identifier / description

Added value: +"The title or permalink of the note to read.\n       Can be a full memory:// URL, a permalink, a title, or search text.\n       From the CLI this is a positional argument, not a flag."

removedInput schema / properties / identifier / title
```
Removed value: -"Identifier"
```

addedInput schema / properties / include_content

Added value: +{
+  "default": true,
+  "description": "Default true. Set to false to return only the note's metadata —\ntitle, permalink, file_path, the full accepted-revision checksum, and\nupdated_at — without the body. Use it to refresh the checksum that\nedit_note/write_note take as expected_checksum without reading the whole\nnote. Cannot be combined with start_line/end_line.",
+  "type": "boolean"
+}

addedInput schema / properties / include_frontmatter

Added value: +{
+  "default": false,
+  "description": "For unsliced JSON reads, include opening YAML in content;\nparsed frontmatter is returned either way. Explicit line ranges are never\nstripped. CLI: --frontmatter (--include-frontmatter is a deprecated alias).",
+  "type": "boolean"
+}

addedInput schema / properties / output_format

Added value: +{
+  "default": "text",
+  "description": "\"text\" returns markdown content or guidance text.\n\"json\" returns a structured object with title/permalink/file_path/content/frontmatter.\nUnresolved notes carry error=\"NOTE_NOT_FOUND\" and a message, with\nrelated_results when suggestions are available.",
+  "enum": [
+    "text",
+    "json"
+  ],
+  "type": "string"
+}

addedInput schema / properties / page / description

Added value: +"Page of fallback-search results to use when the identifier does not\nresolve to a note directly (default: 1). A direct or exact-title match\nreturns the note content — page/page_size never chunk the\nnote itself, and the title-match lookup pages through fixed-size pages\nof title results until an exact match is found or results are\nexhausted, regardless of page or page_size. Aliases: page_number."

removedInput schema / properties / page / title
```
Removed value: -"Page"
```

addedInput schema / properties / page_size / description

Added value: +"Number of fallback-search results per page (default: 10). When no\nmatch is found, this caps how many related-note suggestions are listed.\nAliases: limit, per_page."

removedInput schema / properties / page_size / title
```
Removed value: -"Page Size"
```

addedInput schema / properties / project / description

Added value: +"Project name to read from. Optional - when omitted, a project prefix\n    on a memory:// URL or permalink identifier routes the read; otherwise the\n    server uses the configured default project. If unknown, use\n    list_memory_projects() to discover available projects."

removedInput schema / properties / project / title
```
Removed value: -"Project"
```

addedInput schema / properties / project_id

Added value: +{
+  "anyOf": [
+    {
+      "type": "string"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "Project external_id (UUID). Prefer this over `project` when known —\n    it routes to the exact project regardless of name collisions across cloud\n    workspaces. Takes precedence over `project`. Get from list_memory_projects()."
+}

addedInput schema / properties / start_line

Added value: +{
+  "anyOf": [
+    {
+      "type": "integer"
+    },
+    {
+      "type": "null"
+    }
+  ],
+  "default": null,
+  "description": "First document line to read (1-based, inclusive). Defaults to 1\nwhen only end_line is given. Line scans count the full Markdown,\nincluding frontmatter, matching cat's default line coordinates."
+}

addedOutput schema / properties / result / anyOf

Added value: +[
+  {
+    "additionalProperties": true,
+    "type": "object"
+  },
+  {
+    "type": "string"
+  }
+]

removedOutput schema / properties / result / title
```
Removed value: -"Result"
```
removedOutput schema / properties / result / type
```
Removed value: -"string"
```
removedOutput schema / title
```
Removed value: -"_WrappedResult"
```

First observedAug 18, 2025

TDQS

A4.4/5.0

Behavior4/5

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

Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavior beyond that: the exact-title fallback, the fact that unresolved notes return suggestions instead of content, and the checksum-refresh use of include_content=false.

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?

Three dense sentences that front-load the core read action and then layer the fallback and metadata-only mode. No wasted language, though it packs a lot into a single sentence block.

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 10 params at 100% schema coverage, an output schema present, and annotations covering safety, the description supplies the remaining behavioral essentials (fallback path, checksum use case, error suggestion behavior). An agent has everything needed to invoke it correctly.

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 100%, so the baseline is 3. The description still adds value by explaining the purpose behind include_content=false (refreshing the checksum for edit_note/write_note) and the page/page_size fallback semantics, going beyond restating parameter names.

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 markdown note by title or permalink, optionally a numbered line range') and describes the fallback path when the identifier doesn't resolve. An agent can distinguish this read operation from search-based siblings without opening the schema.

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?

The fallback behavior ('if the identifier doesn't resolve directly... returns related-note suggestions') and the include_content=false guidance give clear context for when to use this tool. However, it does not explicitly name a competing sibling like search_notes or view_note to route between them.

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