# 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](/start-here/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`	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	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`	list string	No	Frontmatter type filter (e.g., `["person", "meeting"]` )
`entity_types`	list string	No	Result type filter: `entity` , `observation` , `relation`
`after_date`	string	No	Date/time filter (ISO format)
`metadata_filters`	object	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](/concepts/semantic-search) for details on each mode. **Parameter aliases.** `search_notes` accepts `q`, `search`, or `text` as aliases for `query`, so assistants can use the parameter name they reach for naturally. 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 called without a `project` parameter, returns activity across all projects.

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, and last sync time 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
`workspace`	string	No	Limit results to a specific 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
`workspace`	string	No	Cloud workspace name or slug to create the project in (cloud only)

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

### `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](/concepts/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

### `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](/integrations/chatgpt) for usage details and limitations. --- ## Related pages - [CLI Reference](/reference/cli-reference) - [AI Assistant Guide](/reference/ai-assistant-guide) - [Memory URLs](/concepts/memory-urls) - [Schema System](/concepts/schema-system) - [Semantic Search](/concepts/semantic-search)