basic-memory — Claude Code MCP server: Markdown notes
A local MCP server that keeps your knowledge in Markdown files on disk and lets the AI read, write and search them. Useful when you are tired of re-explaining project context.
claude mcp add basic-memory -- uvx basic-memoryWhat basic-memory does
Basic Memory treats plain Markdown files on your disk as the source of truth. Both you and the agent write to the same notes, and sync keeps the two sides aligned. Observations and wikilinks build up into a knowledge graph, so context survives between sessions instead of evaporating.
Search works by meaning, not just keywords, and you can turn on cross-encoder reranking for better vector and hybrid results. Every tool carries behaviour hints — read-only, destructive, idempotent — so the agent picks the right one without burning context on trial and error. A hosted option exists for syncing across devices, though it is never required.
Local setup needs Python through uv. Install with uv tool install basic-memory --prerelease=allow. That flag is not optional: version 0.23 pulls in a FastMCP 4 pre-release, and without it uv quietly falls back to an older build. Postgres deployments that keep semantic vectors in Milvus use a separate extra: uv tool install "basic-memory[milvus]" --prerelease=allow.
What it helps with
- build a knowledge graph from Markdown files on disk
- find a note by meaning rather than exact wording
- give the agent access to past sessions and decisions
- keep one shared log of human and AI edits
- sync notes across devices through the cloud
Example prompts for the agent
- Search my notes for everything about this service's deploy
- Save the auth schema decision to basic-memory
- Show me the links between notes on the database migration
How to install basic-memory
Platform CLI
claude mcp add basic-memory -- uvx basic-memoryuvx runs the command named after the package; if the README names another one, use uvx --from basic-memory <command>
Platform CLI
codex mcp add basic-memory -- uvx basic-memoryuvx runs the command named after the package; if the README names another one, use uvx --from basic-memory <command>
Config file
{
"mcpServers": {
"basic-memory": {
"command": "uvx",
"args": [
"basic-memory"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from basic-memory <command>
Config file
{
"servers": {
"basic-memory": {
"type": "stdio",
"command": "uvx",
"args": [
"basic-memory"
]
}
}
}uvx runs the command named after the package; if the README names another one, use uvx --from basic-memory <command>
Platform CLI
gemini mcp add basic-memory uvx basic-memoryuvx runs the command named after the package; if the README names another one, use uvx --from basic-memory <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about basic-memory
How do I install basic-memory in Claude Code?
Install the package first: uv tool install basic-memory --prerelease=allow. Then register the server with claude mcp add basic-memory -- uvx basic-memory.
What does basic-memory do?
It stores your knowledge as Markdown files and exposes them to an MCP client for reading, writing and searching. You and the agent work on the same files.
Why is the --prerelease=allow flag needed?
Version 0.23 depends on a FastMCP 4 pre-release. Without the flag uv installs an older release, and the server will not behave as expected.
