Verfy

MCP servers / basic-memory

MCP tool changes

basic-memory

2 of its last 4 updates changed what the agent reads: 18 tool descriptions rewritten, up to 1.0.0.

PyPI package · last recorded on 13 November 2026 on a clean machine with placeholder settings; only tools/list was sent. A changed description is not a vulnerability. PyPI page · Method and limits · this data as JSON.

Release by release

0.24.1 → 1.0.0

major release, 29 October 2026

Added: bm_context, bm_delete, bm_edit, bm_find, bm_list, bm_man, bm_move, bm_project, bm_read, bm_schema, bm_search, bm_write

Removed: basic_memory_diagnostics, build_context, cat, create_memory_project, delete_note, delete_project, edit_note, fetch, find, grep, list_directory, list_memory_projects, list_workspaces, ls, man, move_note, read_content, read_note, recent_activity, schema_diff, schema_infer, schema_validate, search, search_notes, tail, view_note, write_note

prompt:continue_conversation: input schema changed; new arguments: project

prompt:recent_activity: description and input schema changed
Before (0.24.1)
Get recent activity from one project: the given one, else the default project. Lists every project only when no default is set
After (1.0.0)
Get recent activity from the given or configured default project. Discover projects first when neither resolves.

prompt:search_knowledge_base: input schema changed; new arguments: project

0.23.2 → 0.24.1

minor release, 23 October 2026

Added: cat, find, grep, ls, man, tail

basic_memory_diagnostics: description changed
Before (0.23.2)
Return version, system, and configuration diagnostics for Basic Memory. Provides: - Basic Memory package version - Python version and platform details - Config file path and its contents (secrets redacted) Useful for troubleshooting installations and gathering information for support requests. Read-only; never emits secrets or API keys.
After (0.24.1)
Return version, system, and configuration diagnostics for Basic Memory. Provides: - Basic Memory package version - Python version and platform details - Config file path and its contents (secrets redacted) - BASIC_MEMORY_* environment variables that override the file at runtime Useful for troubleshooting installations and gathering information for support requests. Read-only; never emits secrets or API keys.

build_context: input schema changed; new arguments: compact

create_memory_project: input schema changed

delete_note: description and input schema changed
Before (0.23.2)
Delete a note or directory by title, permalink, or path
After (0.24.1)
Delete a note or directory by title, permalink, or path. Deletion is permanent and removes the file. With is_directory=True every file under the path is deleted. A missing note returns false rather than an error.
delete_project: description and input schema changed
Before (0.23.2)
Delete a Basic Memory project. Removes a project from Basic Memory's configuration and database records. By default the project's note files are retained: local projects keep their files on disk, cloud projects keep their files in cloud storage. Pass delete_notes=True to also delete the note files themselves.
After (0.24.1)
Delete a Basic Memory project. Removes a project from Basic Memory's configuration and database records. Local projects keep their note files on disk unless delete_notes=True. Cloud projects always have their note files deleted from cloud storage; those files can be recovered only from a cloud snapshot.
edit_note: description and input schema changed; new arguments: expected_checksum
Before (0.23.2)
Edit an existing markdown note using various operations like append, prepend, find_replace, replace_section, insert_before_section, or insert_after_section. Pass metadata to merge YAML frontmatter fields independent of the operation.
After (0.24.1)
Edit a note in place. `operation` picks the edit: append or prepend `content` (prepend lands after frontmatter; both create the note if it does not exist); find_replace (replaces every exact, case-sensitive occurrence of `find_text`, and writes nothing unless the count equals `expected_replacements`, default 1); replace_section (replaces the content under the `section` heading, including its subsections unless replace_subsections=false); insert_before_section / insert_after_section (adds content beside the `section` heading). The heading must match exactly and appear once; a heading without leading `#` is treated as `##`. A missing or duplicate heading, or missing find_text, fails without writing. `identifier` must resolve exactly; there is no fuzzy matching. Pass `metadata` to merge frontmatter fields in the same call. Pass `expected_checksum` to edit only if the note is still the revision you read.
fetch: description changed
Before (0.23.2)
Fetch the full contents of a search result document
After (0.24.1)
OpenAI/ChatGPT connector fetch adapter. Takes an id from search results (permalink, title, or memory:// URL) and returns one text item holding JSON {id, title, text, url, metadata}. Other MCP clients receive an unsupported-client error; use read_note instead.

list_memory_projects: input schema changed

move_note: description and input schema changed
Before (0.23.2)
Move a note or directory to a new location, updating database and maintaining links.
After (0.24.1)
Move a note, or a whole directory with is_directory=true, to a new path within the same project; cross-project moves are refused. For a file, give either `destination_path` (project-relative, with the same file extension as the source, e.g. "archive/note.md"; `.markdown` may become `.md`) or `destination_folder` (keeps the filename). The file moves on disk and its index entry, observations, and relations move with it. The permalink stays the same unless the server's update_permalinks_on_move setting is on, so links that use it keep resolving; other notes' text is not rewritten.

prompt:continue_conversation: input schema changed

prompt:getting_started: input schema changed

prompt:recent_activity: description and input schema changed
Before (0.23.2)
Get recent activity from a specific project or across all projects
After (0.24.1)
Get recent activity from one project: the given one, else the default project. Lists every project only when no default is set

prompt:search_knowledge_base: input schema changed

read_content: description changed
Before (0.23.2)
Read a file's raw content by path or permalink. Paths resolve against the Basic Memory knowledge base API — see https://docs.basicmemory.com/local/mcp-tools-local
After (0.24.1)
Read a file's raw bytes by path, permalink, or memory:// URL, without knowledge-graph processing. Text and JSON come back as {"type": "text"}; images are re-encoded as JPEG and downscaled to about 350 KB; other binaries come back base64 as {"type": "document"} and are refused above 350 KB. Use read_note for markdown notes when you want note resolution and fallback search.
read_note: description and input schema changed; new arguments: end_line, include_content, start_line
Before (0.23.2)
Read a markdown note by title or permalink.
After (0.24.1)
Read a markdown note by title or permalink, optionally a numbered line range. If the identifier doesn't resolve directly, a note whose title matches it exactly (case-insensitive) is returned with full content; otherwise it returns related-note suggestions from text search instead of content. Pass include_content=false to get only the note's metadata and checksum.
recent_activity: description and input schema changed
Before (0.23.2)
Get recent activity for a project or across all projects. Timeframe supports natural language formats like: - "2 days ago" - "last week" - "yesterday" - "today" - "3 weeks ago" Or standard formats like "7d"
After (0.24.1)
Get recent activity for one project. With no project, this uses the configured default project. It lists activity across all projects only when there is no default. Timeframe supports natural language formats like: - "2 days ago" - "last week" - "yesterday" - "today" - "3 weeks ago" Or standard formats like "7d"
schema_diff: description changed
Before (0.23.2)
Detect drift between a schema definition and actual note usage.
After (0.24.1)
Detect drift between a schema definition and actual note usage. A schema is a note with type: schema whose entity field names the note type it describes.
schema_infer: description changed
Before (0.23.2)
Analyze existing notes and suggest a Picoschema definition.
After (0.24.1)
Analyze existing notes of one type and suggest a Picoschema definition. A schema is a note with type: schema whose entity field names the note type it describes.
schema_validate: description changed
Before (0.23.2)
Validate notes against their Picoschema definitions.
After (0.24.1)
Validate notes against their Picoschema definitions. With neither note_type nor identifier it validates every note type that has a schema. A schema is a note with type: schema whose entity field names the note type it describes.
search: description changed
Before (0.23.2)
Search for content across the knowledge base
After (0.24.1)
OpenAI/ChatGPT connector search adapter. Returns one text item holding JSON {results, total_count, query} for the top 10 search_notes matches. Other MCP clients receive an unsupported-client error; use search_notes instead.
search_notes: description and input schema changed; new arguments: compact, projects, time_kind, valid_at, valid_overlaps
Before (0.23.2)
Search across all content in the knowledge base with advanced syntax support.
After (0.24.1)
Search notes, observations, and relations in one project, or in several with `projects` / `search_all_projects`. The query supports quoted phrases, AND/OR/NOT with parentheses, and `tag:name` (converted to a tags filter). A plain multi-term query first requires every term and may fall back to any-term matching when that returns nothing. `search_type` selects text, title, permalink (a `*` glob matched against the full permalink path), vector/semantic, or hybrid; the default is hybrid when semantic search is enabled, otherwise text. Omit `query` to search by filters alone (metadata_filters, tags, status, note_types). Results are whole notes by default; a `categories` or valid-time filter switches the default to observations. `after_date` filters by when content was last updated. `valid_at` / `valid_overlaps` / `time_kind` filter by dates written inside notes (e.g. `@effective[2026-06-10,2026-07-27)`) and exclude undated content. Returns ranked, paginated results; read full content with read_note or cat. Syntax reference: memory://man/search-notes(3).
view_note: description changed
Before (0.23.2)
View a note as a formatted artifact for better readability.
After (0.24.1)
Read a note (same resolution as read_note) and return it wrapped in an instruction to display it to the user as a markdown artifact. Use when the user wants to see the note rendered; use read_note when you need the content yourself. Not-found results are returned unwrapped.
write_note: description and input schema changed; new arguments: expected_checksum
Before (0.23.2)
Create a markdown note. If the note already exists, returns an error by default — pass overwrite=True to replace.
After (0.24.1)
Create a markdown note. If the note already exists, returns an error by default — pass overwrite=True to replace. directory is required. For incremental changes to an existing note use edit_note. A new note's result may list similar existing notes; that is advisory and does not block the write. Pass expected_checksum with overwrite=True to replace the note only if it is still the revision you read.

0.23.1 → 0.23.2

patch release, 25 August 2026

No tool definition changed.

0.23.0 → 0.23.1

patch release, 25 August 2026

No tool definition changed.

Releases tried: 0.23.0 (2026-08-24); 0.23.1 (2026-08-25); 0.23.2 (2026-08-25); 0.24.0 (2026-10-23), did not start; 0.24.1 (2026-10-23); 1.0.0 (2026-10-29).

Tools in 1.0.0

The pin is the SHA-256 of the tool's name, description and input schema, as verfy.lock records it. The same pin in your lock means your agent reads this exact definition. Verfy 0.16.0 and later also pin a tool's title, annotations and output schema when the server sends them, so such a tool shows a different pin in your lock.

Tools in 1.0.0
ToolDescriptionPin
bm_contextFollow the Basic Memory knowledge graph from a note: the note, its observations, and the notes its relations reach, up to `depth` hops (1-5). `identifier` is a path, permalink, memory:// URL, or a pattern such as 'specs/*'. `since` limits related results to recent changes. `compact` returns the graph without note bodies; read chosen notes with bm_read.4f8bdffa1af3
bm_deleteDelete a Basic Memory note (`identifier`) or a directory (`path`). A directory delete removes every file under it and needs `recursive=true`. Pass `expected_checksum` (from bm_read) to delete a note only if it is still the revision you read. A note that does not exist is an error. This cannot be undone.0659be417771
bm_editChange part of an existing Basic Memory note. `command`: append or prepend `content`; find_replace `find_text` with `content` (exact text, which must occur `expected_replacements` times, default 1); replace_section, insert_before_section or insert_after_section for a `section` heading ('Decisions', 'Auth/Decisions', 'Decisions[1]', as bm_read takes it); set_metadata to merge `metadata` into the frontmatter without touching the body. `metadata` also merges with any other command. Pass `expected_checksum` (from bm_read) to edit only the revision you read. A missing note is an error; create notes with bm_write.3d56f1c880f6
bm_findFind files in a Basic Memory project, recursively. With `name`, match file names against a glob ('*meeting*'). With `filters`, match notes by frontmatter, e.g. {"status": "active"} or {"priority": {"$in": ["high"]}}, and with `fields` return just those frontmatter values per note. `path` limits the search to a folder. For ranked text or meaning search, use bm_search.ebd360ab7567
bm_listList one folder of a Basic Memory project: its subfolders, then its files with title, date and id. `project` is required; '/' lists its root. Discover projects with bm_project(command='list'). Filter files with `glob` and order them with `sort`. For a recursive search by name or frontmatter, use bm_find.db5d85cfab8f
bm_manRead the Basic Memory manual. With no arguments, the index of every page. `page` reads one page: 'bm-search(3)' for an MCP tool, 'grep(1)' for a shell command; a tool name such as 'bm_search' works too. `query` lists the pages that mention every word given, like `man -k`.34aa3f3c0076
bm_moveMove or rename a Basic Memory note (`identifier`) or a directory (`path`) within its project. `destination` is the new project-relative path; ending it with '/' moves into that folder under the current name ('archive/'). A note keeps its file extension ('.markdown' may become '.md'). Pass `expected_checksum` (from bm_read) to move a note only if it is still the revision you read. Moving into another project is refused: bm_read, bm_write there, then bm_delete.9b3d0dae8ee8
bm_schemaBasic Memory note schemas (Picoschema). `command`: validate notes against their schema (one `note_type`, one note by `identifier`, or every type that has a schema); infer a schema from the notes of a `note_type`; diff a `note_type`'s notes against its schema to find drift. A schema is a note with type: schema whose `entity` field names the note type it describes.bba7bddda3c7
bm_projectBasic Memory projects. `command`: list (projects, grouped by workspace); create (`name`, `path`, optional `set_default`, `workspace`); recent (what changed lately in the required `project`: `since`, `items`, paging).c4509e9fdf7e
bm_searchSearch a Basic Memory project, ranked by relevance. `query` supports quoted phrases, AND/OR/NOT and tag:name. `mode` picks hybrid (the default when semantic search is available), text, semantic, title or permalink (globs with *). Narrow with `filters` (frontmatter), `note_types`, `items` (notes, observations, relations) and `since`. `lines` returns the matching lines of each hit with that many lines of context, like grep. `path` limits the search to a folder; `identifier` searches one note. Scope every search with `project` (one project), `projects` (a list), or `all_projects=true`. Read full notes with bm_read.8e24d4aec7cb
bm_readRead a Basic Memory note or file by path, permalink, memory:// URL or exact title. Slice a long note with `section` (a heading), `start_line`/`end_line` or `max_tokens`; line numbers count the whole file, frontmatter included. A text file such as .txt takes start_line/end_line too. `include_content=false` returns only the metadata and the checksum that bm_write and bm_edit take as expected_checksum. Images come back as images and other binary files as documents. A missing note is an error: find notes with bm_search.c03a4928ba05
bm_writeCreate or replace a Basic Memory note. Give a file path as `identifier` ('notes/plan.md'), or `title` plus `directory`. With a path the file lands exactly there and the title comes from the content's frontmatter, then `title`, then the file name. An existing note is an error unless `overwrite=true`; pass `expected_checksum` (from bm_read) to replace only the revision you read. To change part of a note use bm_edit. Content may hold frontmatter, observations ('- [category] fact #tag') and relations ('- relation_type [[Other Note]]').235ce304b399
prompt:continue_conversationContinue a previous conversation52eacdc83e58
prompt:getting_startedIntroduce Basic Memory and help the user create their first notea2e170f20c78
prompt:recent_activityGet recent activity from the given or configured default project. Discover projects first when neither resolves.f52610da4696
prompt:search_knowledge_baseSearch across all content in basic-memoryca7c1960888c

Lock these tools

Pin what basic-memory serves you today, commit the lock, and a pull request fails when a tool changes, with the text before and after. Pin the package version in your MCP config as well.

$ pip install verfy
$ verfy lock check --update   # shows each tool, then writes verfy.lock
$ git add verfy.lock
# .github/workflows/verfy.yml, after actions/checkout
- uses: verfy-dev/verfy-action@v1

Maintain this server? Run the same check on your releases and add the Locked by Verfy badge to your README.