Claude Desktop

Claude Desktop is the flagship way to use Basic Memory. Connect once, and Claude gains full access to your knowledge base — reading, writing, searching, and building on past conversations automatically.

Basic Memory describes its tools to Claude through the Model Context Protocol, so Claude already knows how to use them. You just ask in plain language.

Cloud Setup

Basic Memory is published in Claude's Connectors Directory. This is the recommended way to connect Basic Memory Cloud.

List my Basic Memory projects.

Manual Cloud Setup

Use the custom-connector flow only if the directory listing is unavailable or you specifically need to add the MCP endpoint yourself.

Local Setup

Install Basic Memory first — see Quickstart: Local for the Homebrew and uv install commands.

Edit the Claude Desktop config

Add this configuration:

{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": ["basic-memory", "mcp"]
    }
  }
}

Restart and verify

Restart Claude Desktop, then open the search and tools menu in the chat input area — Basic Memory tools should be listed.

Try It

Once connected, try these prompts to see Basic Memory in action:

Save something from a conversation:

Create a note summarizing what we just discussed about API rate limiting.

Claude will write a structured note with observations, tags, and relations to other topics in your knowledge base.

Search with meaning, not just keywords:

Find my notes about login security.

Even if your notes use terms like "authentication hardening" or "credential rotation," semantic search surfaces them based on meaning. See Semantic Search for details.

Pick up where you left off:

What have we been working on this week?

Claude checks recent activity and offers to continue any thread. Changes sync in real time — edits you make in any text editor appear instantly in your next conversation.

You can also reference specific notes with memory:// URLs. Learn more in Memory URLs.

Troubleshooting

Tools not appearing

• Directory connector: Open Settings → Customize → Connectors and confirm Basic Memory is connected. In a managed workspace, an owner may need to enable the connector first.
• Custom cloud connector: Re-open Claude Desktop after adding it. Check that the connector URL is exactly https://cloud.basicmemory.com/mcp.
• Local: Verify uv is installed (which uvx), check config JSON syntax, and restart Claude Desktop.

Tools appear but return errors

• Cloud: check the Activity view for failed operations, or disconnect and reconnect the connector.
• Local: check Basic Memory is installed (basic-memory --version), verify sync status (basic-memory status), and check file permissions in your ~/basic-memory directory.

Changes not showing up (local)

• Real-time sync is on by default. Run basic-memory status to confirm.
• Make sure the file is in the correct project directory.
• If the index is stale, rebuild it with bm reindex (file watching runs automatically inside the MCP server).

Project selection

Projects are selected at the start of each conversation. For single-project setups, set a default in ~/.basic-memory/config.json:

{
  "default_project": "main"
}

For Claude's current platform instructions, see Use connectors to extend Claude's capabilities.

Next Steps