home / mcp / basic memory mcp server

Basic Memory MCP Server

Provides a local-first knowledge graph and MCP-enabled access to create, read, and navigate Markdown notes.

Installation

Add the following to your MCP client configuration file.

Configuration

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

Basic Memory MCP Server enables your local Markdown-based knowledge graph to be read and written by compatible AI assistants through the MCP protocol. It focuses on local-first knowledge management with seamless integration into your preferred MCP clients, so you can structure, navigate, and grow your notes while retaining full control over your data.

How to use

You connect an MCP client to the Basic Memory server using the standard MCP setup provided by your client. In practice, you configure the client to point to the Basic Memory MCP server, then you can create, read, and navigate your knowledge graph through natural conversations and commands.

In Claude Desktop or similar MCP-enabled environments, you can route the Basic Memory server as a local MCP backend. Use the local routing to keep all data on your machine. You will be able to create notes during conversations, load context from existing Markdown files, and query your knowledge graph with semantic relations.

If you prefer to edit and view notes with editors like Obsidian or VS Code, you can access and manipulate your notes in real time while your AI assistant reads from and writes to the same files through MCP.

How to install

Prerequisites you need before installing: a shell environment, and a client that can launch MCP servers. The recommended client in this setup is uv, which is used to install and run MCP-powered tools.

Step 1: Install the Basic Memory MCP client support with the recommended installer command.

Step 2: Configure your MCP client to connect to Basic Memory. Use the provided configuration snippet to register Basic Memory as an MCP server. This example shows how to wire Basic Memory into Claude Desktop’s MCP configuration, which enables you to create, read, and search notes through natural language prompts.

Step 3: Start using Basic Memory with your MCP client. The client will communicate with the local MCP server to load context, persist notes, and traverse the knowledge graph as you work.

Configuration and usage notes

Local-first and cloud options exist. You can keep all notes as Markdown files on your machine and optionally sync to the cloud.

The Basic Memory server exposes a simple local command flow that you use from your MCP client. For local operation, the recommended approach is to run the local MCP server through the standard CLI flow shown in the examples.

Cloud-related features require a valid subscription and OAuth flow for cloud access. You can route certain projects through the cloud while keeping others local, controlled by explicit routing commands.

Tools and endpoints

The MCP integration provides a set of endpoints to manage knowledge and graph navigation. You can create notes, read notes, edit content, search across your notes, and build contextual views of your knowledge graph.

Available tools

write_note

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

read_note

Read notes by identifier, page, or permalink with configurable output format.

read_content

Read raw file content from a given path, returning text, images, or binaries.

view_note

View notes as formatted artifacts for quick review.

edit_note

Edit notes incrementally with operations like append, find_replace, or replace_section.

move_note

Move notes to a new destination path while maintaining database consistency.

delete_note

Delete notes from the knowledge base with optional JSON output.

build_context

Navigate the knowledge graph using memory:// URLs and return contextual results in the preferred format.

recent_activity

Query recently updated information within a specified depth and timeframe.

list_directory

Browse directory contents with optional depth filtering.

search

Search across your knowledge base with a query and pagination.

search_notes

Search notes with multiple filters including types, entity types, and tags.

search_by_metadata

Perform structured frontmatter searches across the repository.

list_memory_projects

List all available projects for memory management.

create_memory_project

Create a new memory project with a given name and path.

get_current_project

Show current project statistics and status.

sync_status

Check synchronization status between files and the knowledge graph.

cloud_info

Show optional Cloud overview and setup guidance.

release_notes

Show latest release notes for the MCP server.

canvas

Generate knowledge visualizations from graph data.