Reference

MCP Tools Reference

Current MCP tool reference for Basic Memory local and cloud usage.

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.

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	Constrained project env → explicit parameter → `default_project` config
`workspace`	string	—	Cloud workspace name or tenant ID
`output_format`	`"text"` or `"json"`	`"text"`	Machine-readable JSON output. `build_context` defaults to `"json"`; all other tools default to `"text"`

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`	liststring 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	No	Extra frontmatter fields merged into the note's YAML header
`overwrite`	boolean	No	Default `false`. Must be `true` to replace an existing note. Without this, writing to an existing path returns an error. Set `write_note_overwrite_default: true` in config to change the default

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.

`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`

`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 raw file content by path or permalink. Returns the file's raw bytes — useful for non-markdown files like images, PDFs, or binary attachments.

Parameter	Type	Required	Notes
`path`	string	Yes	File path, permalink, or `memory://...` URL

`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
`page`	integer	No	Pagination page number
`page_size`	integer	No	Results per page

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`	liststring	No	Frontmatter type filter (e.g., `["person", "meeting"]`)
`entity_types`	liststring	No	Result type filter: `entity`, `observation`, `relation`
`after_date`	string	No	Date/time filter (ISO format)
`metadata_filters`	object	No	Structured metadata filters
`tags`	liststring	No	Tag filter shorthand
`status`	string	No	Status shorthand
`min_similarity`	float	No	Overrides global `semantic_min_similarity` threshold per query

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.

`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 called without a project parameter, returns activity across all projects.

Parameter	Type	Required	Notes
`type`	string or liststring	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, and last sync time for each project.

Parameter	Type	Required	Notes
`workspace`	string	No	Cloud workspace name or tenant ID

`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

`delete_project`

Remove a project from Basic Memory config.

Parameter	Type	Required	Notes
`project_name`	string	Yes	Name of the project to remove

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

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

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

`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`)

`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`)

Discovery tools

Cloud discovery tools

cloud_info() — Returns cloud connection information including authentication status, subscription details, and tenant info. No parameters.
release_notes() — Returns the latest Basic Memory release notes and changelog. 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.

Edit this pageorReport an issue

CLI Reference

Command-line reference for Basic Memory local and cloud workflows.

AI Assistant Guide

Guide for AI assistants using Basic Memory through the Model Context Protocol (MCP).