Basic Memory Cloud

Replace the body under a section heading. section uses bm_read selectors (Decisions, Auth/Decisions, Decisions[1]). replace_subsections includes child sections when true. Read with bm_read first and pass its checksum as expected_checksum. Existing Markdown notes only; preserves open review threads and refuses edits that change them.

bm_edit_replace_section

Merge metadata into the note frontmatter while preserving other fields and the body. Read with bm_read first and pass its checksum as expected_checksum. Existing Markdown notes only; preserves open review threads and refuses edits that change them.

bm_edit_set_metadata

Create a Basic Memory project with name and its notes folder path in the selected workspace. Optionally make it the default.

bm_project_create

List accessible Basic Memory projects, grouped by workspace. Call only when project metadata is needed or the user requests their projects; bm_open resolves its default project itself.

bm_project_list

Show recent changes in a Basic Memory project. since accepts a date or lookback such as 7d (default); items selects notes, observations or relations. Supports pagination.

bm_project_recent

Read workspace credit usage for owners and admins. since accepts a UTC date or lookback; until is a UTC date. Defaults to the current billing period. group_by selects actor, day or job_type. Partner staff may select a managed customer or all.

bm_project_usage

Accept a pending review suggestion and apply it to the note. Requires the current revision_checksum from bm_read as expected_checksum. First call bm_read for the note prose, review threads and checksum. Review changes are attributed to the detected MCP client and saved atomically with checksum conflict protection.

bm_review_accept

Add a review comment anchored to exact prose copied from bm_read. First call bm_read for the note prose, review threads and checksum. Review changes are attributed to the detected MCP client and saved atomically with checksum conflict protection.

bm_review_comment

Reject a pending review suggestion. Requires the current revision_checksum from bm_read as expected_checksum. First call bm_read for the note prose, review threads and checksum. Review changes are attributed to the detected MCP client and saved atomically with checksum conflict protection.

bm_review_reject

Reply to an existing review thread using its review_id from bm_read. First call bm_read for the note prose, review threads and checksum. Review changes are attributed to the detected MCP client and saved atomically with checksum conflict protection.

bm_review_reply

Resolve a review comment, optionally with a final reply. review_id comes from bm_read. First call bm_read for the note prose, review threads and checksum. Review changes are attributed to the detected MCP client and saved atomically with checksum conflict protection.

bm_review_resolve

Suggest an addition, deletion or replacement anchored to exact prose from bm_read. Supply replacement text for additions and replacements; deletions omit it. Creates a pending suggestion without accepting it. First call bm_read for the note prose, review threads and checksum. Review changes are attributed to the detected MCP client and saved atomically with checksum conflict protection.

bm_review_suggest

Find drift between notes of one frontmatter type and its Picoschema. Reads notes and returns differences without changing them.

bm_schema_diff

Infer a Picoschema from notes of one frontmatter type. threshold is the share of notes a field must appear in. Returns a proposed schema without writing it.

bm_schema_infer

Validate notes against their Picoschema. Give a note identifier, a note_type, or neither to validate all schema-covered types.

bm_schema_validate

Follow the Basic Memory knowledge graph from a note: the note, its observations, and the notes its relations reach, up to `depth` hops (1-5). `identifier` is a path, permalink, memory:// URL, or a pattern such as 'specs/*'. `since` limits related results to recent changes. `compact` returns the graph without note bodies; read chosen notes with bm_read.

bm_context

Check whether one exact mounted note changed since a known checksum.

check_note_revision_for_widget

Read the current Basic Memory Cloud account and workspace setup status, app link, and next-step guidance when registration or provisioning is incomplete.

bm_cloud_setup_status

Delete a Basic Memory note (`identifier`) or a directory (`path`). A directory delete removes every file under it and needs `recursive=true`. Pass `expected_checksum` (from bm_read) to delete a note only if it is still the revision you read. A note that does not exist is an error. This cannot be undone.

bm_delete

OpenAI/ChatGPT connector fetch adapter. Takes an id from search results (permalink, title, or memory:// URL) and returns one text item holding JSON {id, title, text, url, metadata}. Other MCP clients receive an unsupported-client error; use bm_read instead.

fetch

Find files in a Basic Memory project, recursively. With `name`, match file names against a glob ('*meeting*'). With `filters`, match notes by frontmatter, e.g. {"status": "active"} or {"priority": {"$in": ["high"]}}, and with `fields` return just those frontmatter values per note. `path` limits the search to a folder. For ranked text or meaning search, use bm_search.

bm_find

List one project or folder page for the interactive notes gallery.

list_notes_for_widget

List one folder of a Basic Memory project: its subfolders, then its files with title, date and id. `project` is required; '/' lists its root. Discover projects with bm_project_list(). Filter files with `glob` and order them with `sort`. For a recursive search by name or frontmatter, use bm_find. Use this when the assistant needs a directory listing as data. To let the user browse folders visually, call `bm_open` with `view="folders"`.

bm_list

Load one project topology and its graph insights for the interactive app.

load_knowledge_graph_for_widget

Load one exact workspace/project/note identity for an MCP App.

load_note_for_widget

Load one project-local note image for the sandboxed MCP App.

load_note_image_for_widget

Load project roots for the interactive location picker.

load_projects_for_widget

Read the Basic Memory workspace log: who changed which notes (created, updated, moved, deleted), folder and project changes, indexing, imports and agent runs, with who did each when known. Newest first, metadata only, with an opaque nextCursor to resume from. Each event has only the fields that say what happened; pass full=true for every field, including ids, checksums and app links. To read what a note says, use bm_read. For recently changed notes' content, use bm_project_recent(project='<project>'). Discover projects with bm_project_list().

bm_log

Read the Basic Memory manual. With no arguments, the index of every page. `page` reads one page: 'bm-search(3)' for an MCP tool, 'grep(1)' for a shell command; a tool name such as 'bm_search' works too. `query` lists the pages that mention every word given, like `man -k`.

bm_man

Move or rename a Basic Memory note (`identifier`) or a directory (`path`) within its project. `destination` is the new project-relative path; ending it with '/' moves into that folder under the current name ('archive/'). A note keeps its file extension ('.markdown' may become '.md'). Pass `expected_checksum` (from bm_read) to move a note only if it is still the revision you read. Moving into another project is refused: bm_read, bm_write there, then bm_delete.

bm_move

Open the Basic Memory app when the user wants to open, browse, navigate, or interact with their notes visually: the notes gallery, a specific note or folder, search, or graph. Do not use only to retrieve information for the assistant's answer; use the data tools instead. The default workspace and project resolve automatically, so do not list projects first.

bm_open

Run a bounded, project-scoped Comark query for the interactive app.

query_comark_for_widget

Read a Basic Memory note or file by path, permalink, memory:// URL or exact title. Open review comments and suggestions come back as threads beside the prose (review_mode='raw' returns the stored bytes). Slice a long note with `section`, `start_line`/`end_line` or `max_tokens`. `versions=true` lists the note's stored versions and `version` reads one. `view='text'` shows what a reader sees, with ::bm-* components rendered. `include_content=false` returns only the metadata and the checksum that bm_write and the bm_edit_* tools take as expected_checksum. A missing note is an error: find notes with bm_search. Use `bm_read` when the assistant needs note content to answer, summarize, compare, quote, or reason about it. `bm_read` does not open the Basic Memory interface; use `bm_open` when the user wants to see or navigate it.

bm_read

Resolve a textual Basic Memory note identifier for an MCP App.

resolve_note_for_widget

Save one user-confirmed Markdown draft from the Basic Memory note widget.

save_note_for_widget

OpenAI/ChatGPT connector search adapter. Returns one text item holding JSON {results, total_count, query} for the top 10 bm_search matches. Other MCP clients receive an unsupported-client error; use bm_search instead. Use this when the assistant needs search results as data. To show interactive search results to the user, call `bm_open` with `view="search"`.

search

Find authorized Cloud notes for the composer mention picker.

search_note_mentions

Search Basic Memory for the interactive search-results widget.

search_notes_for_widget

Search a Basic Memory project, ranked by relevance. `query` supports quoted phrases, AND/OR/NOT and tag:name. `mode` picks hybrid (the default when semantic search is available), text, semantic, title or permalink (globs with *). Narrow with `filters` (frontmatter), `note_types`, `items` (notes, observations, relations) and `since`. `lines` returns the matching lines of each hit with that many lines of context, like grep. `path` limits the search to a folder; `identifier` searches one note. Scope every search with `project` (one project), `projects` (a list), or `all_projects=true`. Read full notes with bm_read. Use this when the assistant needs search results as data. To show interactive search results to the user, call `bm_open` with `view="search"`.

bm_search

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 the individual bm_edit_* tools. Content may hold frontmatter, observations ('- [category] fact #tag') and relations ('- relation_type [[Other Note]]').

bm_write