playbooks

home / mcp / basic memory mcp server

Basic Memory MCP Server

Provides a local, bidirectional knowledge graph with notes and semantic relationships accessible via MCP-enabled clients.

Installation
Add the following to your MCP client configuration file.

Configuration

View docs
{
  "mcpServers": {
    "basicmachines-co-basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ],
      "env": {
        "BASIC_MEMORY_ENV": "dev",
        "BASIC_MEMORY_LOG_LEVEL": "DEBUG",
        "BASIC_MEMORY_NO_PROMOS": "true",
        "BASIC_MEMORY_CLOUD_MODE": "true",
        "BASIC_MEMORY_FORCE_CLOUD": "true",
        "BASIC_MEMORY_FORCE_LOCAL": "true",
        "BASIC_MEMORY_EXPLICIT_ROUTING": "true"
      }
    }
  }
}

Basic Memory MCP Server enables seamless interaction between your local knowledge base and compatible AI models through the Model Context Protocol. You run a local MCP server that lets AI assistants read and write to your Markdown-based knowledge graph, while you retain full control over your data. This setup supports collaborative workflows, offline use, and future cloud options without mandatory reliance on remote services.

How to use

You interact with the MCP server by connecting an MCP-enabled client (such as Claude Desktop or a compatible editor) to the server. The client sends read and write requests to your local Markdown-based knowledge graph, and the server exposes a set of tools to navigate, create, edit, and query notes and the knowledge graph.

How to install

Prerequisites: ensure you have a compatible runtime and tooling installed on your machine.

# Install the MCP-capable client tool (example)
uv tool install basic-memory

Configure the MCP server connection in your client. Use the following standard local server configuration, which runs the MCP server via the uvx command and forwards the basic-memory MCP endpoint.

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

Additional configuration and usage notes

You can also configure client integrations to enable per-project routing and cloud features when you choose to opt in. The MV configuration blocks shown above are designed to be pasted into your client’s MCP settings.

Tools and endpoints

The server exposes a rich set of capabilities to manage and query your knowledge graph. Core tools include the following.

Knowledge of tools and endpoints

  • write_note - Create or update notes with optional folder and tags; returns the resulting note reference
  • read_note - Read notes by title or permalink; supports page navigation and formats
  • read_content - Read raw file content (text, images, binaries) from the knowledge base
  • view_note - View notes as formatted artifacts for display
  • edit_note - Incrementally edit notes with various operations (append, find_replace, replace_section)
  • move_note - Move notes between folders/destinations with consistency guarantees
  • delete_note - Remove notes from the knowledge base with optional format output
  • build_context - Navigate the knowledge graph via memory:// URLs, depth, and timeframe controls
  • recent_activity - Retrieve recently updated information with filtering
  • list_directory - Browse directory contents with filtering
  • search - Global search across the knowledge base
  • search_notes - Filtered searches with multiple parameters (query optional)
  • list_memory_projects - List all projects available to the MCP server
  • create_memory_project - Create a new memory project with a path
  • get_current_project - Show current project statistics
  • sync_status - Check synchronization status between files and the graph
  • cloud_info - Show an optional Cloud overview and setup guidance
  • release_notes - Show latest release notes
  • canvas - Generate knowledge visualizations of nodes and edges

Using with Claude Desktop and other MCP clients

You can configure Claude Desktop to connect to the local MCP server by editing its MCP configuration to point to the local uvx-based server. You can also enable per-project routing, cloud features, and synchronization using the provided commands and flows.

Available tools

write_note

Create or update notes with specified title, content, and optional folder or tags; supports output in text or JSON formats.

read_note

Read notes by title or permalink with support for pagination and formatting options.

read_content

Read raw file content from the knowledge base, including text, images, and binaries.

view_note

View notes as formatted artifacts suitable for display in clients.

edit_note

Edit notes incrementally using operations like append, find_replace, or replace_section with optional JSON output.

move_note

Move notes between directories or destinations while preserving database consistency.

delete_note

Delete notes from the knowledge base with optional output format.

build_context

Navigate the knowledge graph using memory:// URLs to fetch related context.

recent_activity

Retrieve recently updated information from the knowledge base.

list_directory

Browse directory contents with filtering options.

search

Search across the knowledge base with optional pagination and filters.

search_notes

Search notes with multiple filters, including query, tags, types, and project context.

list_memory_projects

List all available memory projects and their status.

create_memory_project

Create a new memory project with a specified path.

get_current_project

Show statistics for the currently active project.

sync_status

Check synchronization status between local files and the knowledge graph.

cloud_info

Provide an overview and setup guidance for optional cloud features.

release_notes

Show the latest release notes for the MCP server.

canvas

Generate visualizations of knowledge graph nodes and edges.