basic-memory

Basic Memory exposes an MCP server that lets AI agents interact with your local knowledge base stored as Markdown files. It integrates with Claude Desktop (and other MCP-enabled clients) to enable bi-directional reading and writing to your notes, building a persistent knowledge graph locally. With the MCP server running, you can instruct your connected AI to create, read, and link notes, navigate relationships, and store structured observations directly in your local files. In Claude Desktop, you typically configure the server as a small task runner that the AI can invoke to fetch or update information within your knowledge graph. Typical actions include creating notes from a conversation, querying existing notes for context, and following semantic relations between topics. You can view or edit the underlying files in your local project directory (e.g., ~/basic-memory) to see the real Markdown documents and their semantic structure. The setup and configuration are designed to keep your data local-first while still enabling rich, bidirectional interaction with LLMs.

Prerequisites:

• Python 3.12 or newer
• A tool to run MCP servers (recommended: uv via the uvx workflow)

Installation steps:

1. Install uv (or ensure you have it available on your system). If you don’t have uv, install it following the official guidance for your OS.

2. Install Basic Memory MCP server via uv:

uv tool install basic-memory

3. Run or configure your MCP client (example below uses Claude Desktop configuration). If you’re using Claude Desktop or another MCP client, add the server configuration as shown in the Quick Start:

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

4. Optionally configure your environment for local storage and access:

• The default local project directory is ~/basic-memory
• Ensure you have read/write permissions to this directory
• You can adjust the directory as needed by moving or symlinking your project

5. Verify installation by starting the MCP server through your client and sending a simple read/write request according to your client’s MCP usage documentation.

Tips and notes:

• The server is designed for local-first workflows; your data remains in Markdown files tracked locally.
• The Quick Start uses uvx to run the Basic Memory MCP server. If you prefer npx or other runtimes, adapt the command accordingly (here uvx is recommended).
• In Claude Desktop, you typically edit the MCP configuration to point to the basic-memory server and then use natural language prompts to create and read notes, or to traverse the knowledge graph via semantic relations.
• The knowledge graph is built on top of your Markdown files and is indexed for fast search via SQLite under the hood.
• If you relocate your notes, ensure the MCP index is aware of the new location or reconfigure the server accordingly.
• Common issues include permission errors accessing ~/basic-memory, misconfigured MCP endpoints in your client, or Python/uvx tooling not installed correctly. Check your client’s console logs for endpoint errors and verify that the uvx command is available in your PATH.