2.mcp-tools-reference.md

title	MCP Tools Reference
description	Current MCP tool reference for Basic Memory local and cloud usage.

::note This is a technical reference for developers and AI integrations. For a conceptual overview of what Basic Memory can do, see What is Basic Memory. ::

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

::tip Project resolution order is: constrained project env -> explicit project parameter -> default_project fallback. ::

Common parameters

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

Parameter	Type	Default	Notes
project	string	resolved via fallback	Project name. Constrained project env → explicit parameter → default_project config
project_id	string	—	Project external UUID from list_memory_projects. Prefer this when the same project name exists in more than one workspace
output_format	"text" or "json"	"text"	Machine-readable JSON output. build_context defaults to "json"; most other tools default to "text"

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.

Parameter	Type	Required	Notes
title	string	Yes	Note title
content	string	Yes	Markdown body
directory	string	Yes	Relative folder path
tags	list[string] or string	No	Comma-separated string accepted
note_type	string	No	Default note. Sets the type frontmatter field (e.g., person, meeting, decision)
metadata	object or JSON string	No	Extra frontmatter fields merged into the note's YAML header
overwrite	boolean	No	Default follows write_note_overwrite_default config (false unless changed). Pass true to replace an existing note; without it, writing to an existing path returns an error
workspace	string	No	Cloud workspace to write into (name or tenant ID)

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.

read_note

Read note content by title/permalink/memory URL.

Parameter	Type	Required	Notes
identifier	string	Yes	Title, permalink, or memory://...
page	integer	No	Pagination page number
page_size	integer	No	Results per page
include_frontmatter	boolean	No	Default false. When true, includes YAML frontmatter in output

edit_note

Edit an existing note incrementally.

Parameter	Type	Required	Notes
identifier	string	Yes	Exact note identifier
operation	string	Yes	append, prepend, find_replace, replace_section, insert_before_section, insert_after_section
content	string	Yes	New content
section	string	Conditional	Required for replace_section, insert_before_section, insert_after_section
find_text	string	Conditional	Required for find_replace
expected_replacements	integer	No	Default 1
workspace	string	No	Cloud workspace containing the note (name or tenant ID)

move_note

Move a note or directory.

Parameter	Type	Required	Notes
identifier	string	Yes	Note or directory identifier
destination_path	string	Conditional	Target path. Mutually exclusive with destination_folder
destination_folder	string	Conditional	Target folder — moves note into folder preserving filename. Mutually exclusive with destination_path
is_directory	boolean	No	Default false. Set to true to move an entire directory

delete_note

Delete a note or directory.

Parameter	Type	Required	Notes
identifier	string	Yes	Note or directory
is_directory	boolean	No	Set to true to delete an entire directory and its contents

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.

Parameter	Type	Required	Notes
path	string	Yes	File path, permalink, or memory://... URL. Aliases: file_path, filepath, file

view_note

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

Parameter	Type	Required	Notes
identifier	string	Yes	Note title, permalink, or memory://... URL

---

Search and context tools

search_notes

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

Parameter	Type	Required	Notes
query	string	No	Search query. Optional for metadata-only searches. Supports tag: shorthand (e.g., "tag:security")
page	integer	No	Default 1
page_size	integer	No	Default 10
search_type	string	No	Default None — resolves to hybrid when semantic search is enabled, text otherwise. Options: text, title, permalink, vector, semantic, hybrid
note_types	list[string] or string	No	Case-insensitive frontmatter type filter (e.g., ["person", "meeting"]). Aliases: note_type, types
entity_types	list[string] or string	No	Knowledge graph result filter: entity, observation, relation. Alias: entity_type
categories	list[string] or string	No	Exact observation category filter (e.g., ["decision", "rule"]). When provided without entity_types, results default to observations.
after_date	string	No	Date/time filter (ISO format)
metadata_filters	object or JSON string	No	Structured metadata filters
tags	list[string]	No	Tag filter shorthand
status	string	No	Status shorthand
min_similarity	float	No	Overrides global semantic_min_similarity threshold per query
search_all_projects	boolean	No	Default false. Search stays scoped to the resolved project; set true to search across every accessible project and workspace

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.

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.

::note Parameter aliases. search_notes accepts q, search, or text as aliases for query; all_projects for search_all_projects; page_number for page; and limit / per_page for page_size. Search responses also include a result total for pagination. ::

build_context

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

Parameter	Type	Required	Notes
url	string	Yes	memory:// URL or path
depth	string or integer	No	Traversal depth (default 1). Use 2 or 3 for broader context
timeframe	string	No	Time window filter (default 7d). Accepts formats like 7d, 1 week, 30d, 3 months
page	integer	No	Default 1
page_size	integer	No	Default 10
max_related	integer	No	Maximum related entities per level (default 10)
output_format	string	No	Default "json". Also accepts "text" for human-readable output

TimeFrame examples:

Value	Meaning
7d	Last 7 days
30d	Last 30 days
1 week	Last week
3 months	Last 3 months
1 year	Last year

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.

Parameter	Type	Required	Notes
type	string or list[string]	No	Filter by result type: "entity", "relation", "observation"
depth	integer	No	Relation traversal depth for context
timeframe	string	No	Time window (e.g., 7d, 30d, 1 week)
page	integer	No	Default 1
page_size	integer	No	Default 10

---

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.

Parameter	Type	Required	Notes
output_format	"text" or "json"	No	Use "json" when an agent needs exact project_id values for later tool calls

create_memory_project

Create a project.

Parameter	Type	Required	Notes
project_name	string	Yes	Name for the new project
project_path	string	Yes	Filesystem path for the project
set_default	boolean	No	Default false. Set to true to make this the default project
workspace	string	No	Cloud workspace name or slug to create the project in (cloud only)

delete_project

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

Parameter	Type	Required	Notes
project_name	string	Yes	Name of the project to remove
delete_notes	boolean	No	Default false. Set to true to delete local files or purge every active cloud object under the project's storage prefix
workspace	string	No	Cloud workspace selector when deleting from a specific workspace

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 and glob filter.

Parameter	Type	Required	Notes
dir_name	string	No	Directory path to list (root if omitted)
depth	integer	No	How many levels deep to list
file_name_glob	string	No	Glob pattern to filter files (e.g., *.md, schemas/*)

canvas

Create Obsidian canvas files for visual knowledge graph exploration. Local-only — see Canvas Visualizations.

Parameter	Type	Required	Notes
nodes	list	Yes	List of node definitions for the canvas
edges	list	Yes	List of edge definitions connecting nodes
title	string	Yes	Canvas file title
directory	string	Yes	Relative folder path for the canvas file

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.

Parameter	Type	Required	Notes
note_type	string	Conditional	Note type to validate (e.g., person). One of note_type or identifier required
identifier	string	Conditional	Specific note path or permalink to validate
output_format	"text" or "json"	No	Machine-readable validation report

schema_infer

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

Parameter	Type	Required	Notes
note_type	string	Yes	Note type to analyze (e.g., person)
threshold	float	No	Minimum field frequency for inclusion (default 0.25)
output_format	"text" or "json"	No	Machine-readable inference report

schema_diff

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

Parameter	Type	Required	Notes
note_type	string	Yes	Note type to compare (e.g., person)
output_format	"text" or "json"	No	Machine-readable drift report

---

Discovery tools

• cloud_info() — Returns an overview of Basic Memory Cloud: features and how to get set up (bm cloud login). No parameters.
• release_notes() — Returns bundled release-notes highlights for the installed version. No parameters.

---

ChatGPT compatibility tools

These are compatibility wrappers for ChatGPT's MCP implementation, which uses a simplified two-tool interface by default.

• 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.

See the ChatGPT integration guide for usage details and limitations.

---

Related pages

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