# Basic Memory MCP server

> Keep persistent AI memory as a local Markdown knowledge graph that you and your assistant both read and edit.

- Listing: https://mcp.tc/i/basic-memory
- Connect: this is a local (stdio) server; install it on your machine (see Install). The listing link is a page, not an MCP endpoint.
- Type: local (stdio)
- Auth: no API key needed
- Category: [Productivity & Projects](https://mcp.tc/c/productivity)
- Vendor: Basic Machines
- Homepage: <https://basicmemory.com>
- Docs: <https://github.com/basicmachines-co/basic-memory>
- Repository: <https://github.com/basicmachines-co/basic-memory>
- Package: pypi `basic-memory`

## About

Basic Memory stores what you and your AI talk about as plain Markdown files on your disk. Notes use observations and wikilinks to form a knowledge graph. Both you and the assistant can write to the same files, and sync keeps them aligned. It also offers semantic search and works with Obsidian, since it reads and writes the same Markdown.

It runs locally over stdio as a Python package started with uvx, and needs no sign-in or API key. The --prerelease=allow flag is required because of a pre-release FastMCP dependency. A hosted Basic Memory Cloud option exists at https://cloud.basicmemory.com/mcp with OAuth sign-in and a paid plan.

## What it can do

- Store AI conversation context as local Markdown notes
- Build a knowledge graph from observations and wikilinks
- Search notes by keyword or by meaning with semantic search
- Edit the same files by hand or through the assistant
- Work with Obsidian and other MCP clients
- Optionally use the hosted cloud version for cross-device sync

## Example prompts

- "Save a note summarizing our decisions about the API design."
- "What did we decide last week about the database schema?"
- "Search my notes for anything related to authentication."
- "Continue from where we left off on the migration project."

## Install

### Claude Code

1. Run this in a terminal, in your project folder:

```bash
claude mcp add --transport stdio basic-memory -- uvx --prerelease=allow basic-memory mcp
```

2. Start Claude Code and type `/mcp`. **basic-memory** should show as connected.

Add `--scope user` to make it available in every project.

### Claude Desktop

1. Open **Settings → Developer → Edit Config**. It opens `claude_desktop_config.json`. Add:

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "--prerelease=allow",
        "basic-memory",
        "mcp"
      ]
    }
  }
}
```

2. Save the file and restart Claude Desktop.

Needs uv (Python) on your computer. The file lives in `~/Library/Application Support/Claude/` on macOS and `%APPDATA%\Claude\` on Windows.

### Cursor

[Add to Cursor](<https://cursor.com/install-mcp?name=basic-memory&config=eyJjb21tYW5kIjoidXZ4IiwiYXJncyI6WyItLXByZXJlbGVhc2U9YWxsb3ciLCJiYXNpYy1tZW1vcnkiLCJtY3AiXX0%3D>) (opens Cursor)

Or add it by hand to `~/.cursor/mcp.json` (all projects) or `.cursor/mcp.json` (this project):

`mcp.json`:

```json
{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "--prerelease=allow",
        "basic-memory",
        "mcp"
      ]
    }
  }
}
```

Needs uv (Python) on your computer.

### VS Code

[Install in VS Code](<https://vscode.dev/redirect/mcp/install?name=basic-memory&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22--prerelease%3Dallow%22%2C%22basic-memory%22%2C%22mcp%22%5D%7D>) (opens VS Code)

Or from a terminal:

```bash
code --add-mcp '{"name":"basic-memory","type":"stdio","command":"uvx","args":["--prerelease=allow","basic-memory","mcp"]}'
```

Or commit it to the repo in `.vscode/mcp.json`:

`.vscode/mcp.json`:

```json
{
  "servers": {
    "basic-memory": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "--prerelease=allow",
        "basic-memory",
        "mcp"
      ]
    }
  }
}
```

Needs uv (Python) on your computer.

### Devin Desktop

1. Add it to `~/.config/devin/mcp_config.json` (macOS and Linux) or `%APPDATA%\devin\mcp_config.json` (Windows):

`mcp_config.json`:

```json
{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "--prerelease=allow",
        "basic-memory",
        "mcp"
      ]
    }
  }
}
```

2. Refresh the MCP server list in Cascade.

Devin Desktop is the new name for Windsurf.

### Codex

```bash
codex mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp
```

Or edit `~/.codex/config.toml` directly:

`config.toml`:

```toml
[mcp_servers.basic-memory]
command = "uvx"
args = ["--prerelease=allow", "basic-memory", "mcp"]
```

Needs uv (Python) on your computer.

### Gemini CLI

```bash
gemini mcp add basic-memory uvx -- --prerelease=allow basic-memory mcp
```

This adds it to the current project. Add `-s user` to use it everywhere.

### Any client

Most clients that start local servers accept this shape:

```json
{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "--prerelease=allow",
        "basic-memory",
        "mcp"
      ]
    }
  }
}
```

Zed puts servers under `context_servers` in its settings, with the same `command`, `args` and `env` fields.

Needs uv (Python) on your computer.

## Details

- Server version: 0.23.2
- Last checked: 2026-10-03
- Listed: 2026-10-03
- Updated: 2026-10-03

---
Source: https://mcp.tc/i/basic-memory (mcp.tc is an independent directory, not affiliated with this server's publisher). Corrections: https://mcp.tc/report