Claude Code
Claude Code is powerful, but every session starts from zero. Basic Memory gives it a persistent knowledge base -- so your AI remembers project decisions, code patterns, and context across every session.
New to this setup? Basic Memory for Claude Code has a two-minute overview of what persistent memory changes.
Cloud Setup
Sign Up
Create your account at basicmemory.com.
Add Remote MCP Server
In your terminal, add the remote MCP server:
claude mcp add -s user -t http basic-memory-cloud https://cloud.basicmemory.com/mcp
Authenticate
In Claude Code, run /mcp, select basic-memory-cloud, and choose Authenticate to complete the OAuth flow in your browser.
Verify
Re-run /mcp and confirm the Basic Memory tools are listed.
Local Setup
Install Basic Memory locally (Quickstart: Local), then add it to Claude Code:
claude mcp add basic-memory basic-memory mcp
Run /mcp in Claude Code to confirm the tools are available.
bm_read for full or sliced reads, bm_search for ranked results and matching lines, bm_list and bm_find for navigation, and bm_man for the manual. Upgrading from earlier tools? See Migrating to 1.0. The legacy enable_posix_tools setting does not hide the new bm_* tools.Basic Memory Plugin
The Basic Memory plugin for Claude Code adds a session-start briefing, a checkpoint before context compaction, and skills such as /basic-memory:bm-setup, /basic-memory:bm-orient, /basic-memory:bm-checkpoint, /basic-memory:bm-decide, and /basic-memory:bm-remember. Install it with the Basic Memory CLI (v0.24+):
# Preview the plan without running anything
bm install claude-code --dry-run
# Install at user level (default)
bm install claude-code
# Install for this repository only, or for your local copy of it
bm install claude-code --scope project
bm install claude-code --scope local
bm install claude-code delegates to Claude Code's own plugin CLI: it adds the Basic Memory marketplace and installs the basic-memory plugin at the scope you choose. It shows the plan and asks before applying it (--yes skips the prompt). It doesn't touch your Basic Memory database or config.
After installing:
- Restart Claude Code and run
/basic-memory:bm-setupto map the repository to a Basic Memory project. - Make sure the Basic Memory MCP server is connected (see Local Setup or Cloud Setup) — the plugin's skills call its tools.
- Install uv if it isn't on your PATH; the plugin's hooks run through it.
The plugin's hooks honor CLAUDE_CONFIG_DIR, so they work with a non-default Claude Code profile. See Harness Capture for how the lifecycle hooks behave.
Try It
Once connected, try these prompts in Claude Code:
"Create a note about our authentication strategy -- we're using JWT with
refresh tokens, and here's why..."
"Search my notes for anything related to database migration patterns"
"What do my notes say about the API rate limiting decision we made last week?"
Basic Memory supports semantic search, so your queries don't need to match exact keywords -- it finds notes by meaning.
For the full list of tools Claude Code can use, see the MCP Tools Reference.
CLAUDE.md and Basic Memory
Claude Code uses CLAUDE.md files for project-level instructions. Basic Memory complements this nicely: CLAUDE.md tells Claude Code how to work in a project, while Basic Memory stores the knowledge -- decisions, architecture notes, research, context -- that doesn't belong in a static instruction file.
Agent Skills
Install agent skills to teach Claude Code best practices for writing well-structured notes. Skills give your AI reusable patterns so notes are consistent and useful from the start.
Troubleshooting
Tools not showing up in /mcp?
- For local: verify Basic Memory is installed (
basic-memory --version) and re-add the server:claude mcp remove basic-memory && claude mcp add basic-memory basic-memory mcp - For cloud: re-run the
claude mcp addcommand and complete the OAuth flow again
Notes not syncing?
- Check project index status:
basic-memory status - Look for errors in
~/.basic-memory/basic-memory.log
FAQ
Claude Code already has CLAUDE.md and auto memory. Why add Basic Memory?
Claude Code's built-in memory is great for project instructions and short learnings. Basic Memory adds a full knowledge base on top — searchable notes with semantic connections, observations, and relations that span across projects and AI tools. Think of CLAUDE.md as "how to work here" and Basic Memory as "everything we know." See Using Basic Memory with Built-in AI Memory for a deeper comparison.