Basic Memory
Long-term agent memory in local Markdown files with a link graph, semantic search and MCP access
Install
claude mcp add basic-memory -- uvx --prerelease=allow basic-memory mcpThis 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 noteLimitations
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.
MCP
- 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 |
Security check
- Creates, edits and deletes note files on disk
- The CLI auto-updates in the background when installed via uv tool or Homebrew
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.
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.
Related
Open-source personal AI assistant on your own machine: answers in Telegram, Slack, Discord and WhatsApp, extended with skills and plugins
A self-improving agent from Nous Research with a TUI, messaging gateway, cron jobs and skills it writes itself
Anthropic's coding agent for the terminal, IDE and GitHub: understands your codebase, runs tasks and handles git
OpenAI's coding agent that runs locally in your terminal, with IDE and desktop versions