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.

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.

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.

Build context from a memory:// URI to continue conversations naturally.

Use this to follow up on previous discussions or explore related topics.

Memory URL Format:
- Use paths like "folder/note" or "memory://folder/note"
- Pattern matching: "folder/*" matches all notes in folder
- Valid characters: letters, numbers, hyphens, underscores, forward slashes
- Avoid: double slashes (//), angle brackets (<>), quotes, pipes (|)
- Examples: "specs/search", "projects/basic-memory", "notes/*"

Timeframes support natural language like:
- "2 days ago", "last week", "today", "3 months ago"
- Or standard formats like "7d", "24h"

Format options:
- "json" (default): Structured JSON with internal fields excluded
- "text": Compact markdown text for LLM consumption

Queries the Basic Memory knowledge base API — see
https://docs.basicmemory.com/concepts/memory-urls

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"

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

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.

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.

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.

List directory contents with filtering and depth control.

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.

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.

List available cloud workspaces (tenant_id, type, role, and name).

List all available projects with their status.

Shows projects from both local and cloud sources when cloud credentials are available, merging by permalink to give a unified view.

Each project entry includes an external_id (UUID). Pass that value as the project_id parameter on other tools to address a specific project unambiguously across cloud workspaces — useful when the same project name exists in more than one workspace.

Create a new Basic Memory project.

Creates a new project with the specified name and path. The project directory will be created if it doesn't exist. Optionally sets the new project as default.

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.

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.

Print a note's content. Accepts '/path' identifiers.

Search note content in one project and return matching notes. Not a regex: pattern is matched as full-text keywords by default, and a pattern found in no note returns no results. semantic=True ranks by meaning instead (hybrid semantic plus full-text, when semantic search is enabled). Add context_lines to get case-insensitive matching lines with surrounding context and line numbers. Requires 'project' when several projects are addressable.

List one directory level. '/' lists projects; paths accept '/path'.

Recursively list files by name glob or metadata predicates (e.g. "status=active"). Paths accept '/path'.

Show recently changed notes. Requires 'project' when several are addressable.

Look up a manual page or search the manual.

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.

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.

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.

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

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

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

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

List one folder of a Basic Memory project: its subfolders, then its files with title, date and id. bm_list('/') with no project lists the projects you can address; '/path' lists inside another project. Filter files with glob and order them with sort. For a recursive search by name or frontmatter, use bm_find.

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

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

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

Basic Memory projects. command: list (projects, grouped by workspace); create (name, path, optional set_default, workspace); recent (what changed lately: since, items, paging; project picks the project, else the default project, and with no default every project).

Search 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. Read full notes with bm_read.

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

Create 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]]').