Reference

MCP Tools Reference

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

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.

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
`project`	string	No	Uses resolver fallback when omitted
`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

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://...`
`project`	string	No	Optional
`page`	integer	No	Pagination page number
`page_size`	integer	No	Results per page
`output_format`	string	No	`default` (structured), `ascii` (plain table), `ansi` (colorized terminal)

`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`
`content`	string	Yes	New content
`project`	string	No	Optional
`section`	string	Conditional	Required for `replace_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	Yes	Target path
`is_directory`	boolean	No	Default `false`. Set to `true` to move an entire directory
`project`	string	No	Optional

`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
`project`	string	No	Optional

`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
`identifier`	string	Yes	File path, permalink, or `memory://...` URL
`project`	string	No	Optional

`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
`project`	string	No	Optional
`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	Yes	Search query
`project`	string	No	Optional
`page`	integer	No	Default `1`
`page_size`	integer	No	Default `10`
`search_type`	string	No	`text`, `title`, `permalink`, `vector`, `semantic`, `hybrid`
`output_format`	string	No	`default` (structured), `ascii` (plain table), `ansi` (colorized terminal)
`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. text is the default keyword search. vector and semantic are equivalent — pure meaning-based similarity. hybrid combines both. See Semantic Search for details on each mode.

`search_by_metadata`

Metadata-first structured search. Finds notes based on their frontmatter fields rather than content.

Parameter	Type	Required	Notes
`filters`	object	Yes	Key-value pairs to match against note frontmatter
`project`	string	No	Optional
`limit`	integer	No	Maximum results to return
`offset`	integer	No	Pagination offset

`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
`project`	string	No	Optional
`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`)

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	No	Filter by entity type (e.g., `note`, `person`, `meeting`)
`depth`	integer	No	Relation traversal depth for context
`timeframe`	string	No	Time window (e.g., `7d`, `30d`, `1 week`)
`project`	string	No	Specific project, or omit for cross-project discovery

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.

`create_memory_project`

Create a project.

`delete_project`

Remove a project from Basic Memory config.

`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/`)
`project`	string	No	Optional

Parameter	Type	Required	Notes
`entity_type`	string	Conditional	Note type to validate (e.g., `person`). One of `entity_type` or `identifier` required
`identifier`	string	Conditional	Specific note path or permalink to validate
`project`	string	No	Optional

`schema_infer`

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

Parameter	Type	Required	Notes
`entity_type`	string	Yes	Note type to analyze (e.g., `person`)
`threshold`	float	No	Minimum field frequency for inclusion (default `0.25`)
`project`	string	No	Optional

`schema_diff`

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

Parameter	Type	Required	Notes
`entity_type`	string	Yes	Note type to compare (e.g., `person`)
`project`	string	No	Optional

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