Basic Memory

Local-first knowledge management with bi-directional LLM sync via Markdown files.

Connector by basicmachines-co · GitHub account verified by the MCP Registry

IndexedAGPL-3.0Local (stdio)★ 4,336

Install

Works with Claude Code, Codex, VS Code, Cursor, Windsurf, Claude Desktop. Read the repository before you give any tool access to your data.

npx agentmarket install connector/basicmachines-co-basic-memory

Asks which of your tools to add it to (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude Desktop) and shows the change first. See https://agentmart.dev/cli.

Get the weekly diff

The weekly diff: one email a week with new agent tools, notable updates and grade changes, plus security alerts for tools you follow. Double opt-in, one-click unsubscribe.

About

Local-first knowledge management with bi-directional LLM sync via Markdown files.

Use cases: note-taking, agent-memory

Reviews

Write a review

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this server can do and what it asks for, from its tool list and install config. Checked Oct 25, 2026.

Runs code on install

Its package runs an install script (such as npm postinstall or setup.py code) as soon as you install it, before any tool is called. Read the script first.

Tools: 30 read · 2 write · 5 delete
Secrets: None asked for
Install scripts: Runs code on install
Runs as: Python package

Tools by what they do 37

Read from the source code; the running server may list different tools.

Read 30 · Look things up without changing anything.

basic_memory_diagnostics
bm_capture
bm_context
bm_find
bm_list
bm_man
bm_read
bm_recall
build_context
cat
fetch
find

Show 18 more tools

grep
list_directory
list_memory_projects
list_workspaces
ls
man
memory_get
memory_search
read_content
read_note
recent_activity
schema_diff
schema_infer
schema_validate
search
search_notes
tail
view_note

Write 2 · Create, change, send or run things.

bm_move
move_note

Delete 5 · Delete, drop, revoke or wipe things.

bm_delete
bm_write
delete_note
edit_note
write_note

Files it touches

Any path the agent passes to its tools

Tools (37)

Read from the source code; the running server may differ. Descriptions are the server’s own words; hidden characters are shown as [U+…].

basic_memory_diagnosticsBasic Memory Diagnosticsread-only
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.
bm_capture
Capture the current Pi working thread to Basic Memory as a durable checkpoint.
bm_contextBuild contextread-only
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.
bm_deleteDelete notecan change or delete data
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.
bm_findFind filesread-only
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.
bm_listList folderread-only
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; '<project>/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.
bm_manManualread-only
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`.
bm_moveMove note
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.
bm_readRead noteread-only
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.
bm_recall
Recall recent Pi session checkpoints from Basic Memory for a topic.
bm_writeWrite notecan change or delete data
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]]').
build_contextBuild Contextread-only
Navigate the Basic Memory knowledge graph via memory:// URLs. Returns the target note plus related notes connected through the graph. Use this to follow relations and discover connected concepts.
catCatread-only
Print a note's content. Accepts '<project>/path' identifiers.
delete_noteDelete Notecan change or delete data
Delete a note from the Basic Memory knowledge graph. The note is permanently removed from the filesystem and the search index.
edit_noteEdit Notecan change or delete data
Incrementally edit an existing note in the Basic Memory knowledge graph. Supports append, prepend, find/replace, and section replacement without rewriting the entire note. The result returns the note's permalink and file_path: cite those exact values when confirming the edit — never report a save that no tool call performed.

Show 22 more tools

fetchFetch Documentread-only
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 bm_read instead.
findFindread-only
Recursively list files by name glob or metadata predicates (e.g. "status=active"). Paths accept '<project>/path'.
grepGrepread-only
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_directoryList Directoryread-only
List directory contents with filtering and depth control.
list_memory_projects
List Basic Memory projects accessible to this agent, optionally filtered by workspace. Returns each project's name, external_id, source (local, cloud, or local+cloud), path, default flag, workspace, and qualified name. Call this before passing `project` to another tool when the user names a project that isn't the default. Pass a project's external_id as `project_id` to route to that exact project.
list_workspacesList Workspacesread-only
List workspaces represented by accessible Basic Memory projects. Use it to find the workspace to pass to list_memory_projects when the same project name may exist in more than one workspace.
lsLsread-only
List one directory level. '/' lists projects; paths accept '<project>/path'.
manManread-only
Look up a manual page or search the manual.
memory_get
Read a specific note from the knowledge graph by title, permalink, or path. Returns the full note content. Use after memory_search to read a specific result in full.
memory_search
Search across all memory sources: MEMORY.md (working memory), Basic Memory knowledge graph (long-term archive), and active tasks. Returns composited results from all sources. Use it for broad recall; use search_notes when you need metadata, tag, or status filters or a specific project.
move_noteMove Note
Move a note to a different folder in the Basic Memory knowledge graph. The note content is preserved; only the location changes.
read_contentRead Contentread-only
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_noteRead Noteread-only
Read a specific note from the Basic Memory knowledge graph by title or permalink. Returns the full note content including observations and relations, followed by the note's checksum: pass it to write_note as expected_checksum (with overwrite=true) to replace only this revision.
recent_activityRecent Activityread-only
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_diffSchema Diffread-only
Detect drift between a Picoschema definition and actual note usage. Identifies new fields in notes not declared in the schema, declared fields no longer used, and cardinality changes.
schema_inferInfer Schemaread-only
Analyze existing notes of a given type and suggest a Picoschema definition. Examines observation categories and relation types to infer required and optional fields.
schema_validateValidate Schemaread-only
Validate notes against their Picoschema definitions. Validates a specific note by identifier, or all notes of a given type.
searchSearch Knowledge Baseread-only
OpenAI/ChatGPT connector search adapter. Returns one text item holding JSON {results, total_count, query} for the top 10 bm_search matches. Other MCP clients receive an unsupported-client error; use bm_search instead.
search_notes
Search the Basic Memory knowledge graph for relevant notes, concepts, and connections. Returns matching notes with titles, content previews, and relevance scores. Optionally filter by frontmatter metadata fields, tags, or status, or target another project. For a quick cross-source recall that also covers MEMORY.md and active tasks, use memory_search.
tailTailread-only
Show recently changed notes. Requires 'project' when several are addressable.
view_noteView Noteread-only
Read a note (same resolution as bm_read) 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 bm_read when you need the content yourself. Missing notes raise tool errors.
write_noteWrite Notecan change or delete data
Create a note in the Basic Memory knowledge graph. Call this whenever the user asks to remember, record, save, or note something — saying 'saved' without this call saves nothing. The result returns the note's permalink and file_path: cite those exact values when confirming, never a recalled filename. If the note already exists, returns an error by default. Pass overwrite=true to replace, or use edit_note for incremental updates. To replace only the revision you read, also pass expected_checksum (the checksum read_note reports); a newer revision is then left untouched.

Compare and alternatives

Featured in

Signals

Stars: 4,336
Forks: 335
Open issues: 87
Weekly downloads: 14,373
Last commit: Oct 24, 2026 (5 days ago)
Last release: Oct 23, 2026 (7 days ago)
Last package publish: Oct 23, 2026 (7 days ago)

From GitHub (fetched Oct 24, 2026) and the package registry.

Details

Registry name: io.github.basicmachines-co/basic-memory
Version: 0.24.1
Auth: No auth
Packages: pypi basic-memory
License: AGPL-3.0
Repository: github.com/basicmachines-co/basic-memory
First seen: Oct 24, 2026
Last checked: Oct 25, 2026
Source: Official MCP Registry github-graphql