Basic Memory
Basic Memory is a local-first knowledge base that stores notes as Markdown files and exposes them to AI assistants via MCP, enabling two-way read/write and semantic search. It solves the problem of AI assistants lacking persistent memory across sessions. It is for developers and teams using AI coding tools like Claude, Codex, or Cursor who want a shared, searchable knowledge graph.
✨ Key features
- Local-first plain text Markdown files on your disk.
- Two-way sync between AI and human edits.
- Real knowledge graph with observations and wikilinks.
- Semantic search with optional cross-encoder reranking.
- MCP-native, works with major AI clients and IDEs.
- Progressive tool discovery with behavior hints.
🎯 Use cases
- Give Claude or Codex persistent memory across sessions.
- Maintain a project knowledge base that both humans and AI edit.
- Search notes by meaning, not just keywords.
- Sync knowledge across devices with the optional cloud service.
- Build a shared team knowledge base with Basic Memory Teams.
📦 Installation
🧰 Requirements: Local install requires Python via uv; cloud version requires an account and subscription.
uv tool install basic-memory --prerelease=allow
For Postgres deployments with Milvus:
uv tool install "basic-memory[milvus]" --prerelease=allow
🚀 Usage
Connect to Claude Desktop by editing ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"basic-memory": {
"command": "uvx",
"args": ["--prerelease=allow", "basic-memory", "mcp"]
}
}
}
Then restart Claude Desktop and try prompts like: "Create a note about our project architecture decisions."
⚠️ Good to know
Local install requires Python via uv and the --prerelease=allow flag due to a FastMCP 4 pre-release dependency; reranking is disabled by default due to latency and model download.
❓ FAQ
What is the difference between Cloud and local install?
Cloud is hosted, costs $15/mo, and includes cross-device sync and backups. Local is free, runs on your disk, and requires manual sync.
How do I install Basic Memory locally?
Use uv tool install basic-memory --prerelease=allow. The flag is required because it depends on a FastMCP 4 pre-release.
Which AI clients are supported?
Claude Desktop, Claude Code, Codex, Cursor, VS Code, ChatGPT, and any MCP-compatible client.
Can I use Basic Memory without the cloud?
Yes, the local install is free and stores all data on your disk, air-gapped friendly.
📊 Repository
🤖 Overview, features, install steps and FAQ were generated from the project's README on Sep 4, 2026. Always check the original source before running commands.