MCP Tools Reference

This page lists core Basic Memory MCP tools and their current parameters.

Common parameters

Most tools accept these optional parameters. They are not repeated in every table below.

workspace is not a universal parameter. It appears on the note-writing tools (write_note, edit_note) and on the tools that create or delete cloud projects. For ordinary read, search, and schema calls, use project or project_id.

Knowledge tools

write_note

Create or update a markdown note.

The note_type parameter controls the type field in frontmatter, which is used for schema resolution and filtering. The metadata parameter accepts any key-value pairs that get written directly into the note's frontmatter — useful for custom fields like status, priority, or due_date.

Aliases accepted for directory: folder, dir, and path.

Folder casing resolution uses known indexed directories, so local and Cloud writes behave identically. Exact matches win; a unique case-insensitive match reuses the existing spelling; no match creates the folder as requested; and existing case-variant siblings keep exact-match behavior.

read_note

Read note content by title/permalink/memory URL.

On Cloud, structured JSON also returns revision_checksum and a review object containing summary counts and typed comment/suggestion items. Use that checksum for review decisions and for ordinary edits while review work is open. Raw mode is an inspection escape hatch; agents should not author or mutate CriticMarkup directly.

edit_note

Edit an existing note incrementally.

replace_section now follows Markdown heading levels. By default, a selected section extends through the next heading of the same or higher level, so replacing an ## section also replaces its nested ### subsections. Set replace_subsections=false to stop at the next heading of any level and keep nested subsections.

metadata preserves unrelated frontmatter and the note body. It ignores title, type, and permalink, which have dedicated handling, and does not support deleting keys.

On Cloud, edit_note preserves active review markers byte-for-byte. If an edit would change an anchored review range, it fails with the blocking review ID; use review_note to resolve or decide that item first. write_note(overwrite=true) is a full replacement and may remove review state.

review_note (Cloud)

Manage comments and suggestions on an existing Markdown note. Always begin with read_note(review_mode="structured", output_format="json"), and do not write CriticMarkup directly.

comment and suggest create attributed review records and return their IDs. reply works on comments or suggestions. resolve closes a comment without changing its anchored prose and can include a final reply. accept applies a pending suggestion; reject keeps the original prose. Every mutation is atomic and returns the new revision_checksum.

# Create a replacement suggestion
review_note(
  identifier="Launch plan",
  command="suggest",
  anchor={"exact": "Ship the beta on Friday."},
  suggestion_kind="replacement",
  replacement="Ship the beta after the security review."
)

# After a fresh structured read, accept it
review_note(
  identifier="Launch plan",
  command="accept",
  review_id="suggestion-id",
  expected_checksum="checksum-from-read-note"
)

See Comments and Suggestions for the complete human-and-agent workflow.

move_note

Move a note or directory.

Folder casing resolution applies to note destinations, not directory renames. The response reports the actual landing path after a case-corrected move. Case-only folder renames and merging already duplicated case variants remain separate operations.

delete_note

Delete a note or directory.

read_content

Read a file's content by path or permalink. Text files return as plain text; images are resized/optimized for display; other binary files return base64-encoded (subject to size limits). Useful for non-markdown files like images, PDFs, or attachments.

view_note

Render a note as a formatted artifact for display in MCP clients. Returns the note content in a presentation-friendly format.

open_basic_memory (Cloud)

Open the interactive Pocketbook in a compatible client. Use this when the user wants to see, browse, navigate, or interact with Basic Memory visually. Use read_note, search_notes, or list_directory instead when the assistant only needs data for its answer.

The default workspace and project resolve automatically. Do not call list_memory_projects first unless the user asks for project metadata or wants a non-default location.

Examples:

open_basic_memory()
open_basic_memory(view="search", query="authentication")
open_basic_memory(view="folders", directory="research")
open_basic_memory(view="note", identifier="memory://main/plans/api", note_mode="edit")
open_basic_memory(view="graph", identifier="Architecture", graph_mode="full")

See Pocketbook for the user workflow.

Search and context tools

search_notes

Main search tool with text, vector, and hybrid modes plus structured filters.

The search_type parameter controls the search strategy. hybrid is the default — it combines keyword and semantic search. text is keyword-only. vector and semantic are equivalent — pure meaning-based similarity. See Semantic Search for details on each mode.

Search results expose each note's stable external_id in JSON and Markdown output. Use it for web-app deep links or exact follow-up operations instead of parsing a title or permalink.

Cloud search projects reviewed notes as clean prose rather than CriticMarkup. JSON note results include review_summary counts (open_comments, resolved_comments, pending_suggestions, and total_pending). If a stale search fragment splits or exposes review markup during asynchronous index reconciliation, Cloud omits that hit instead of returning ambiguous storage bytes.

Use categories for observation categories such as [decision], [rule], or [follow-up]. metadata_filters only checks note frontmatter, so metadata_filters={"category": "decision"} matches a frontmatter field named category, not observation categories. The singular category is accepted as an alias, and comma-separated strings work (categories="decision,rule"). Matching is exact, and categories only exist on observations — explicitly passing entity_types=["entity"] alongside categories returns nothing.

build_context

Build context graph from a memory URL. Traverses the knowledge graph from a starting entity, following relations to a configurable depth.

TimeFrame examples:

recent_activity

Recent activity in one project or cross-project discovery mode. When no project can be resolved at all (no parameter, no default project), it returns activity across all projects (discovery mode); otherwise it uses the resolved project.

Entity rows include external_id so clients can address the exact note returned.

Project and filesystem tools

list_memory_projects

List projects and project stats. Returns name, path, default status, note count, external project ID, and sync/workspace metadata for each project. In cloud mode, this discovers projects across every accessible workspace, not just the current one — so a team's projects show up without switching workspaces first.

create_memory_project

Create a project.

delete_project

Remove a project from Basic Memory. Note files are retained by default.

Cloud purge behavior applies when the MCP session is hosted or factory-routed to cloud, explicitly cloud-routed, or given a workspace selector. From a local stdio MCP session, delete_notes=true alone does not switch this tool to cloud routing; pass workspace to ensure the hosted project and objects are targeted. Hosted deletion is asynchronous. The tool response reports the project deletion status and background job ID when the cloud backend queues the work. With delete_notes=false, cloud objects are retained even though the project and its indexed database rows are removed. With delete_notes=true, the background job removes indexed and unindexed objects under the exact project prefix before completing the hard delete. Existing snapshots follow their separate retention lifecycle.

list_directory

List directory contents with optional depth, glob filter, and sorting.

Large listings are bounded. Continue with the next page instead of assuming one response contains every file. File nodes include external_id in both text and JSON output.

Glob filtering applies to returned nodes, not traversal. For example, depth=2 with file_name_glob="*.md" still finds Markdown files inside a folder whose own name does not match *.md.

Explicit sorts (v0.23) order folders before files, apply deterministically before pagination, and use note titles for title_* modes. Folders have no canonical update timestamp, so updated_* modes keep folders name-ascending while still listing them first.

list_workspaces

List available cloud workspaces. Returns workspace names and tenant IDs for the authenticated user.

Schema tools

Tools for defining, validating, and evolving note structure. See Schema System for concepts and workflow.

schema_validate

Validate notes against their schema. Pass note_type to validate all notes of a type, or identifier to validate a specific note.

schema_infer

Analyze existing notes of a type and suggest a schema based on common patterns.

schema_diff

Compare a schema definition against actual note usage to detect drift.

Diagnostics

basic_memory_diagnostics

Return a read-only Markdown report for support and installation troubleshooting. It takes no parameters and includes:

• Basic Memory package and API versions;
• Python, operating-system, and architecture details; and
• the config path and current config contents with secrets and URL credentials redacted.

ChatGPT compatibility tools

These are compatibility wrappers for ChatGPT's MCP implementation, which uses a simplified two-tool interface by default. v0.23 gates them by MCP client identity: only OpenAI clients can call them.

• search(query) — Search across the knowledge base. Equivalent to search_notes with default parameters.
• fetch(id) — Retrieve full document content by permalink. Equivalent to read_note.

Non-OpenAI MCP clients receive a clear rejection and must call search_notes and read_note directly.

See the ChatGPT integration guide for usage details and limitations.

Related pages

• CLI Reference
• AI Assistant Guide
• Memory URLs
• Schema System
• Semantic Search