home / mcp / basic memory mcp server

Basic Memory MCP Server

Provides a local MCP server to read and write Markdown-based knowledge graphs with LLMs.

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": "INFO",
        "BASIC_MEMORY_NO_PROMOS": "true",
        "BASIC_MEMORY_CLOUD_MODE": "true",
        "BASIC_MEMORY_FORCE_CLOUD": "false",
        "BASIC_MEMORY_FORCE_LOCAL": "false",
        "BASIC_MEMORY_EXPLICIT_ROUTING": "false"
      }
    }
  }
}

You will run this MCP server locally to let compatible LLMs read from and write to your personal knowledge base using the Model Context Protocol. This server exposes a standardized interface so AI assistants can traverse and modify your structured Markdown notes, enabling persistent memory and seamless collaboration between human notes and AI reasoning.

How to use

Install and run the MCP server, then connect your MCP-compatible client. You will configure a local MCP server that exposes an interface for your editor or AI assistant to read and write notes stored as Markdown files. Use the provided configuration to route conversations to your local knowledge graph, load context from your files, and keep everything synchronized as you interact with supported LLMs.

How to install

Prerequisites: you need a modern Node-like runtime or an environment that can execute the MCP client you will pair with this server. For the concrete setup shown here, you will use the recommended runtime to start an MCP-enabled client that talks to the local server.

# Step 1: Install the MCP client runtime (example placeholder for your environment)
# Replace with the actual client you are using, e.g. uv/uvx or a similar MCP client
install-mcp-client

# Step 2: Start the local MCP server using the documented runtime command
uvx basic-memory mcp

Additional sections

Configuration basics: you define the local MCP server so your LLM can access and modify your knowledge graph. You will also see cloud-related features that require an account to sync or route data to the cloud. The server keeps all data in local Markdown files and indexes them for search using a local database.

Security and privacy: everything remains under your control locally unless you opt into cloud features. You can disable cloud features or opt out of telemetry by setting environment controls as described in the environment variables section.

Usage tips: create notes through natural conversations, structure them with semantic patterns in Markdown, and link related topics to form a traversable knowledge graph. You can enable real-time or scheduled synchronization with cloud storage if you choose to enable cloud routing for supported projects.

Notes on tools and endpoints

The MCP-enabled client can perform common knowledge base operations, including creating, reading, editing, moving, and deleting notes; navigating and querying the knowledge graph; and managing projects and cloud-related settings.

Troubleshooting

If you encounter connection issues, verify that the local MCP server is reachable at the configured runtime and that your client is pointing to the correct command and arguments. Check logs at the default path or as configured for your environment to diagnose routing or synchronization problems.

Available tools

write_note

Create or update notes in the knowledge base from LLM prompts or user actions.

read_note

Read notes by title or permalink for review in your client.

read_content

Read raw file content including text and binary assets.

view_note

View notes as formatted artifacts for display in the client.

edit_note

Edit notes incrementally using various operations like append or replace.

move_note

Move notes to a different path while maintaining database consistency.

delete_note

Delete notes from the knowledge base.

build_context

Navigate the knowledge graph through memory:// URLs with depth control.

recent_activity

Retrieve recently updated information within the knowledge base.

list_directory

Browse directory contents with optional filtering.

search

Search across your knowledge base with optional pagination and filters.

search_notes

Advanced search with multiple filters for notes and metadata.

list_memory_projects

List all available projects in the local environment.

create_memory_project

Create a new knowledge project at a specified path.

get_current_project

Show statistics for the current project.

sync_status

Check the synchronization status between files and the knowledge graph.

cloud_info

Show optional Cloud overview and setup guidance for cloud features.

release_notes

Show latest release notes for MCP server features.

canvas

Generate visualizations of knowledge graph components.