Basic Memory MCP server
An MCP server over a folder of Markdown notes that you and the agent both edit, indexed in SQLite for hybrid full-text and vector search.
Basic Memory keeps an agent's memory as plain Markdown files in a folder you choose (~/basic-memory by default), readable in Obsidian or any editor. A note can carry YAML frontmatter, observations written as lines like "- [decision] use Postgres #db", and relations written as wiki links like "- depends_on [[Auth Service]]". The server parses those into a knowledge graph and indexes notes, observations and relations in SQLite (or Postgres), with hybrid full-text and FastEmbed vector ranking and an optional cross-encoder reranker. Notes are grouped into projects, and a search can be scoped to one project or several.
The 1.0 server exposes 17 tools, all prefixed bm_: writing, editing, moving and deleting notes, ranked search, frontmatter and file-name lookup, graph traversal from a note with bm_context, project management, Picoschema validation of note types, and a built-in manual. bm_project_delete stays hidden unless the server opts in. It runs locally over stdio with uvx, and Basic Memory Cloud serves the same tools at https://cloud.basicmemory.com/mcp behind OAuth, with workspaces that members share. The code is AGPL-3.0; Cloud lists at $19 a month per workspace. Through MCP alone, a note exists only when the agent calls bm_write or bm_edit, so what gets stored is what the agent or you chose to keep.
Quick install
Copy-paste configs are provided for all 8 supported clients. Pick your client below.
Add to ~/.claude.json
{
"mcpServers": {
"basic-memory": {
"type": "http",
"url": "https://cloud.basicmemory.com/mcp"
}
}
}claude mcp add --transport http basic-memory https://cloud.basicmemory.com/mcpHeads up
- First tool call opens a browser to authorize.
Available tools
| Tool | Description |
|---|---|
| bm_write | Create or replace a note by path, or by title plus directory; content may hold frontmatter, observations and relations. Refuses to overwrite unless overwrite=true or a matching expected_checksum is passed. |
| bm_read | Read a note or file by path, permalink, memory:// URL or exact title, optionally sliced by section heading, line range or token budget. Returns the checksum other write tools take. |
| bm_edit | Change part of an existing note: append, prepend, find and replace, replace or insert around a section heading, or merge frontmatter metadata. |
| bm_move | Move or rename a note or directory within its project, or into another project as a new note. |
| bm_delete | Delete a note, or a directory with recursive=true. Cannot be undone. |
| bm_search | Relevance-ranked search across notes, observations and relations, in hybrid, text, semantic, title or permalink mode, with boolean operators, tag filters, frontmatter filters and date limits. |
| bm_list | List one folder of a project: its subfolders, then its files with title, date and id. |
| bm_find | Recursively find files by name glob, or notes by frontmatter filters, optionally returning only selected frontmatter fields. |
| bm_context | Follow the knowledge graph from a note: the note, its observations, and the notes its relations reach, up to five hops. |
| bm_recent | List notes, observations or relations changed in a project within a time window, newest first. |
| bm_project_list | List the projects the caller can reach, grouped by workspace. |
| bm_project_create | Create a project backed by a folder; in Cloud, pick the workspace that holds it. |
| bm_project_delete | Remove a project, optionally deleting its files. Hidden unless the server enables project deletion. |
| bm_schema_validate | Check notes against the Picoschema schema for their note type. |
| bm_schema_infer | Suggest a Picoschema schema for a note type from the fields its notes share. |
| bm_schema_diff | Report drift between a note type's notes and its schema: added fields, dropped fields and cardinality changes. |
| bm_man | Read the Basic Memory manual: the page index, one page per tool or command, or pages matching keywords. |
What you can do with it
A notebook the agent and you both maintain
The agent records decisions and conventions as Markdown notes with observations and relations, and you correct or extend the same files in Obsidian. Both sides read the latest version on the next session.
Graph-shaped recall across a project's notes
bm_search finds the relevant note, then bm_context walks its relations a few hops out, so the agent loads the design note together with the services and decisions it links to.
One notebook across machines and clients
With Basic Memory Cloud, Claude, ChatGPT, Cursor and Codex connect to the same workspace over OAuth, and the files sync back to a local folder.
FAQ
- Is it free?
- The server is open source under AGPL-3.0 and free to run locally. Basic Memory Cloud, which hosts the notes and the MCP endpoint, lists at $19 a month per workspace.
- Does it support remote or OAuth?
- Yes. Basic Memory Cloud serves the same bm_ tools at https://cloud.basicmemory.com/mcp with an OAuth sign-in. The local install runs over stdio with uvx and needs no login.
- How does it compare to a team memory service like Glen?
- Basic Memory stores what the agent or a person writes into notes, and a Cloud workspace can be shared by its members. Glen records every teammate's agent sessions and connected tools without anyone writing notes, and filters recall by what each user may see.