Basic Memory MCP
Long-term agent memory in local Markdown files with a link graph, semantic search and MCP access
- 4,389 ★ on the repository
- Last commit
- AGPL-3.0
Extended access
Why this level
- Creates, edits and deletes note files on disk
- The CLI auto-updates in the background when installed via uv tool or Homebrew
Install
- Works in
Manual install
claude mcp add basic-memory -- uvx --prerelease=allow basic-memory mcpAccess and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Creates, edits and deletes note files on disk
- The CLI auto-updates in the background when installed via uv tool or Homebrew
This is third-party code. Review the repository files before installing.
What it does
Basic Memory keeps knowledge in plain Markdown files that both people and agents read and write. Each note holds categorized observations and wikilink relations, forming a graph the agent follows to restore context in a new session. The server provides tools to write, read, edit and search notes, walk the graph, manage projects and validate the knowledge base structure. Search can be full-text, vector or hybrid, with a local SQLite index. A Claude Code plugin adds session-start briefings and checkpoints before context compaction.
Who it is for. For people running long projects with an agent who are tired of re-explaining context every time.
Good fit when
- You want the agent to remember decisions and findings across sessions
- You want a knowledge base you can open in Obsidian or an editor
- You want the same notes from Claude, Codex and Cursor
Not a fit when
- Built-in agent memory files like CLAUDE.md are enough
- The AGPL license does not fit how you distribute software
Example request
Write a note on our architecture decisions and link it to the auth noteMCP
- Transport
- stdio, http
- Authentication
- not required
Environment variables
BASIC_MEMORY_NO_PROMOS- Disables cloud promos and telemetry
BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED- Enables semantic search
BASIC_MEMORY_LOG_LEVEL- Log level
Limitations
The local version is free and needs Python via uv with --prerelease=allow in install commands. The cloud version is paid and may be unavailable from Russia. The CLI sends minimal anonymous telemetry, disabled via BASIC_MEMORY_NO_PROMOS. AGPL-3.0 licensed.
How to disable. Run claude mcp remove basic-memory or delete the block from the MCP config. Notes stay in ~/basic-memory.
FAQ
Is the cloud required?
No, the local version runs entirely on disk; the cloud is only for cross-device sync.
Why --prerelease=allow?
The current version depends on a FastMCP pre-release; without the flag uv installs an older release.
Discussion
No questions or reviews yet.
Related
MCP serversPersistent agent memory in a folder of linked markdown notes, so Claude Code remembers a project across sessions
Long-term memory for AI agents: Markdown files as the source of truth, a SQLite index as a cache, shared by Claude Code, Codex and others
A long-term memory plugin that keeps decisions, preferences and task state across sessions and injects only what a query needs
Self-hosted long-term memory for agents: semantic search, a knowledge graph and autonomous consolidation over MCP and a REST API
A long-term memory MCP server for agents: one Rust binary that runs offline and never calls a language model
Local memory for agents: stores conversations and project files verbatim and retrieves them with semantic search over MCP
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Basic Memory (this entry) | no | not required | 4,389 | |
| Engram by Gentleman Programming | no | not required | 7,679 | persistent memory for AI coding agents in a single Go binary |
| IWE | no | not required | 1,803 | iWE keeps project memory in linked Markdown notes |
| Token Savior | no | not required | 1,197 | token Savior indexes code by symbol |
README in short
The README compares the cloud and local options and gives configs for Claude Desktop, Claude Code, Codex, Cursor and VS Code. It covers the Claude Code plugin, shared skills and Hermes and OpenClaw integrations. It explains the note format in detail: frontmatter, observations and relations. It lists MCP tools, CLI commands, search reranking, auto-updates, telemetry and logging. AGPL-3.0 licensed.