home / mcp / basic memory mcp server

Basic Memory MCP Server

Provides a local MCP server enabling LLMs to read and write to a local Markdown-based knowledge graph.

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": "false",
        "BASIC_MEMORY_FORCE_LOCAL": "false"
      }
    }
  }
}

You set up and run a local MCP server that lets compatible AI tools read from and write to your knowledge base stored as Markdown files. This enables persistent, bidirectional conversations where your LLMs remember past discussions and can structure new notes directly into your local knowledge graph. The server runs locally and communicates with your MCP client through a defined command, making your data stay under your control while still enabling seamless AI-assisted workflows.

How to use

To use this MCP server, run it as a local process and connect your MCP client to it. You will configure your client to point at the local MCP server, then start interacting with your knowledge base through natural conversations. Common tasks include creating notes during chats, querying for related topics, and navigating your knowledge graph to discover connections.

How to install

Prerequisites: you need a compatible MCP client that can load an MCP server configuration, and you should have a working environment for running the local server command.

1. Ensure you have the required tooling installed, including the local MCP client and a runtime that supports the server execution method described below.

2. Prepare the MCP configuration for your client to connect to the local server as shown in the code example.

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

Additional sections

Configuration, security, and usage notes are important to smoothly run and secure your local MCP setup. You can view and manage shared context files in your local knowledge directory. The server supports cloud-related features that may be available through your client or subscription, but the core local workflow remains centered on your Markdown-based knowledge base.

Notes on usage patterns and examples are provided to help you structure conversations, create semantic notes, and traverse your knowledge graph using straightforward Markdown formats.

If you enable cloud features, follow the steps to authenticate, synchronize, and mount cloud storage as needed. Remember to keep your local files under your control and back up critical notes.

Tools and endpoints (summary)

The MCP server exposes a set of actions your MCP client can invoke to manage notes, traverse the knowledge graph, search content, and manage projects. These tools are designed to help you create, read, navigate, and visualize your knowledge base from within your AI conversations.

Troubleshooting and tips

If you encounter connection issues, verify the MCP client is configured to connect to the local server and that the server process is running. Check logs for any authentication or routing messages and ensure file permissions allow both reading and writing of your Markdown notes.

Example usage prompts

Create a note about our project architecture decisions. Find information about JWT authentication in my notes. Create a canvas visualization of my project components. Read my notes on the authentication system. What have I been working on in the past week?

Available tools

write_note

Create or update notes with a title, content, and optional folder and tags within the knowledge base.

read_note

Read notes by title or permalink, returning the note content for display.

read_content

Read raw content of a file, including text, images, or binaries.

view_note

View notes as formatted artifacts, suitable for presentation in clients.

edit_note

Edit notes incrementally, supporting various operations on note content.

move_note

Move notes between folders or paths while maintaining database consistency.

delete_note

Delete notes from the knowledge base.

build_context

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

recent_activity

Find recently updated information across the knowledge base.

list_directory

Browse directory contents with optional filtering.

search

Search across the knowledge base with a query and pagination.

search_notes

Search notes with filters for type, entities, dates, and tags.

search_by_metadata

Perform structured search on frontmatter metadata.

list_memory_projects

List all available memory projects.

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 local files and the knowledge graph.

canvas

Generate knowledge visualizations from nodes and edges.