---
title: "Basic Memory MCP: Local Markdown Memory for Claude"
url: "https://mcpshelf.co/servers/basic-memory"
description: "Basic Memory keeps what you and your assistant learn as Markdown files on your machine, linked into a searchable graph. uvx config and storage."
updated: "2026-10-27"
site: "MCP Shelf"
---

# Basic Memory

> Long-term memory as plain Markdown files you own.

Source: https://mcpshelf.co/servers/basic-memory  
Markdown: https://mcpshelf.co/servers/basic-memory.md  
Generated: 2026-11-22T20:10:49.073Z

## Facts

- **Name:** Basic Memory
- **Tagline:** Long-term memory as plain Markdown files you own.
- **Description:** Basic Memory is an open source MCP server that gives AI assistants a lasting memory kept as plain Markdown notes on your own computer, which you can read and edit in any editor or Obsidian.
- **Repository:** https://github.com/basicmachines-co/basic-memory
- **Package:** basic-memory 0.24.1 (PyPI)
- **Install:** `claude mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp`
- **Transport:** stdio (local)
- **Auth:** Needs `uvx basic-memory mcp`
- **Tools exposed:** 27: `basic_memory_diagnostics`, `delete_note`, `read_content`, `build_context`, `recent_activity`, `search_notes`, `read_note`, `view_note`, `write_note`, `list_directory`, `edit_note`, `move_note`, `list_workspaces`, `list_memory_projects`, `create_memory_project`, `delete_project`, `search`, `fetch`, `cat`, `grep`, `ls`, `find`, `tail`, `man`, `schema_validate`, `schema_infer`, `schema_diff`
- **Category:** Knowledge and work apps (https://mcpshelf.co/categories/knowledge-and-work)
- **Stats:** 4.4K GitHub stars, 15.7K downloads a week, last commit 27 Oct 2026, 0 upvotes on MCP Shelf
- **Install check:** Not yet tested by us
- **Listed:** 2026-10-26
- **Page updated:** 2026-10-27

## Full description

### What is Basic Memory?

**Basic Memory is an open source MCP server that gives AI assistants a lasting memory kept as plain Markdown notes on your own computer, which you can read and edit in any editor or Obsidian.**

Basic Memory writes notes as ordinary Markdown in a folder on your machine (by default ~/basic-memory) and indexes the links between them. The assistant can write notes, search them and follow connections in later conversations.

Because the notes are just files, you can open them in Obsidian or any editor and edit them yourself.

|  |  |
| --- | --- |
| Made by | Basic Machines |
| GitHub | https://github.com/basicmachines-co/basic-memory |
| Licence | AGPL-3.0-or-later |
| PyPI package | [basic-memory](https://pypi.org/project/basic-memory/) 0.24.1 (23 Oct 2026) |
| GitHub stars | 4.4K |
| Downloads | 15.7K a week |
| Last commit | 27 Oct 2026 |
| Tools | 27 |
| Runs on | Your computer |
| Install check | Not yet tested by us |
| Category | [Knowledge and work apps](https://mcpshelf.co/categories/knowledge-and-work) |
| Works with | Claude Code, Cursor, Claude Desktop, VS Code, Codex, Windsurf |
| Setup checked | 27 Oct 2026 |
| Page updated | 27 Oct 2026 |

**Our check:** Written from the project's own documentation. We have not run this config ourselves yet.

#### Try asking Basic Memory

- "Remember that we chose Postgres over MongoDB because of reporting needs."
- "What did we decide about the API versioning scheme?"
- "Build me a summary of everything in my notes about the billing project."

#### MCP Shelf take

> We started Basic Memory on our own test machine on 26 Oct 2026 and it answered with 27 tools. 21 of the 27 only read; the other 6 can change things. Every tool comes with a useful description, all of them say whether they change things, and the tool list costs about 3,200 tokens of context before you ask a thing. It sits 5th of 17 in its category on our shelf by GitHub stars (4.4K, with 15.7K downloads a week).

— MCP Shelf tests (numbers from our own runs), tested on 26 Oct 2026

### What tools does Basic Memory have?

We listed 27 tools on 26 Oct 2026. 21 only read; the rest can change things or run commands.

| Tool | Kind | What it is for |
| --- | --- | --- |
| `basic_memory_diagnostics` | reads | Reports the installed version, Python and settings, for bug reports. |
| `delete_note` | changes | Deletes a note. |
| `read_content` | reads | Reads a file exactly as stored, including images, without note processing. |
| `build_context` | reads | Follows links out from a note to gather everything related, so a new chat can pick up the thread. |
| `recent_activity` | reads | Shows what changed lately across your notes. |
| `search_notes` | reads | Searches notes, facts and links by keyword, meaning or both, in one project or all of them. |
| `read_note` | reads | Reads a note by title, permalink or memory:// link. |
| `view_note` | reads | Reads a note and asks the client to show it as a formatted document. |
| `write_note` | changes | Creates or overwrites a Markdown note with facts, tags and links to other notes. |
| `list_directory` | reads | Lists the folders and notes inside a project. |
| `edit_note` | changes | Changes part of a note: append, prepend, swap a section or find and replace. |
| `move_note` | changes | Moves or renames a note and keeps its links working. |
| `list_workspaces` | reads | Lists cloud workspaces you can reach, for team accounts. |
| `list_memory_projects` | reads | Lists your notes projects and which one is the default. |
| `create_memory_project` | changes | Starts a new notes project in a folder you choose. |
| `delete_project` | changes | Removes a project from Basic Memory without deleting your files. |
| `search` | reads | Returns top matches in the format ChatGPT's connector expects. |
| `fetch` | reads | Returns one note in the format ChatGPT's connector expects. |
| `cat` | reads | Prints a note, or just a section or a range of lines from it. |
| `grep` | reads | Finds notes that contain given words, or that match by meaning. |
| `ls` | reads | Lists one level of a folder, or all projects at the top. |
| `find` | reads | Lists notes by file name pattern or by frontmatter values such as status. |
| `tail` | reads | Lists the most recently changed notes. |
| `man` | reads | Looks up Basic Memory's built-in manual. |
| `schema_validate` | reads | Checks notes against the schema written for their type. |
| `schema_infer` | reads | Suggests a schema by studying existing notes of one type. |
| `schema_diff` | reads | Spots where notes of one type have drifted from their schema. |

#### How clearly it describes its tools

27 of 27 tools have a description and 27 of 27 say whether they change things. The tool list takes at least ~3,200 tokens of context. Every tool says whether it only reads or can change things, so a client can ask before the risky ones.

### How do I install Basic Memory?

#### Install steps from the Basic Memory README

Copied from the project's [README on GitHub](https://github.com/basicmachines-co/basic-memory#readme) on 16 Nov 2026 under its AGPL-3.0-or-later licence.

##### Get started

Pick the path that fits you. Both run the same product on the same Markdown.

| ☁️   Cloud | 💻   Local install |
| --- | --- |
| **30 seconds.** Sign up, connect your AI client, done. Works in any browser Mobile, web, desktop Cross-device sync built in We handle hosting, backups, snapshots **$15.00/mo locked for life** · 7-day free trial · cancel any time [**Start free trial →**](https://basicmemory.com?utm_source=github&utm_medium=referral&utm_campaign=readme&utm_content=quickstart) | **2 minutes.** Install, configure your AI client, run. Free forever (AGPL-3.0) All data on your disk Air-gapped friendly Requires Python via [`uv`](https://docs.astral.sh/uv/) `uv tool install basic-memory --prerelease=allow` `--prerelease=allow` is required: Basic Memory 0.23 depends on a FastMCP 4 pre-release, and `uv` only accepts pre-releases of transitive dependencies when told to — without the flag it silently installs an older release. The same flag goes on every `uvx` / `uv tool upgrade` command below. For Postgres deployments that store semantic vectors in Milvus, install the first-party optional extra instead: `uv tool install "basic-memory[milvus]" --prerelease=allow` **Configure your client ↓** |

##### Connect your AI client

If you went the Cloud route, the web app walks you through
client connect. The snippets below are for local installs.

###### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

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

Restart Claude Desktop. Notes live in `~/basic-memory` by default.

**Claude Code, Codex CLI, Cursor, VS Code, ChatGPT, Obsidian**

###### Claude Code

```
claude mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp
```

For the full memory bridge — session briefings, pre-compaction checkpoints, and
the `/basic-memory:*` commands — also install the Claude Code
plugin on top of this.

###### Codex CLI

Add to `~/.codex/config.toml`:

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

Codex can keep its default MCP approval behavior, or you can pre-approve eligible
Basic Memory tools by adding this server-scoped setting to the same table:

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

This does not disable Codex approvals globally or expand which Basic Memory
projects the server can access. Codex still requires approval for tools that
advertise a destructive annotation, including Basic Memory's writes, edits, and
deletes. If you installed the Basic Memory Codex plugin, use its
[plugin-scoped configuration](https://github.com/basicmachines-co/basic-memory/blob/HEAD/plugins/codex/README.md#mcp-approvals) instead.

###### Cursor

Add to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

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

###### VS Code

Add to your User Settings (JSON):

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

###### ChatGPT

Basic Memory exposes OpenAI-compatible `search` and `fetch` tools for Custom
GPT actions. See the [ChatGPT integration
guide](https://docs.basicmemory.com/integrations/chatgpt/?utm_source=github&utm_medium=referral&utm_campaign=readme).

###### Obsidian

No setup. Point Obsidian at `~/basic-memory` (or your project folder) and the
same wikilinks, frontmatter, and Markdown your AI writes appear in your graph
view. Edit either side — sync handles the rest.

Try a prompt:

```
"Create a note about our project architecture decisions."
"Find information about JWT auth in my notes."
"What have I been working on this week?"
```

#### What you need first

- uv (for uvx)

#### Claude Code

Where: Your terminal, in the project folder

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

For session briefings and the /basic-memory commands, also install the project's Claude Code plugin with bm install claude-code once the server is connected.

#### Cursor

Where: ~/.cursor/mcp.json, or .cursor/mcp.json in a project

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

#### Claude Desktop

Where: claude_desktop_config.json (Settings → Developer → Edit Config)

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

#### VS Code

Where: .vscode/mcp.json in your project

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

#### Codex

Where: ~/.codex/config.toml, shared by the Codex CLI, IDE extension and ChatGPT desktop app

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

Or run: `codex mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp`

#### Windsurf

Where: ~/.codeium/windsurf/mcp_config.json

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

#### ChatGPT

Where: Not supported

ChatGPT needs a remote server. Basic Memory has search and fetch tools in the shape ChatGPT expects, and the project's ChatGPT guide covers connecting it, including through the paid cloud version.

Keep --prerelease=allow: Basic Memory 0.23 depends on a pre-release of FastMCP, and without the flag uv quietly installs an older release.

Checked against the project's own install docs on 27 Oct 2026: https://github.com/basicmachines-co/basic-memory#readme

### How do I configure Basic Memory?

| Setting | Kind | Required | What it does |
| --- | --- | --- | --- |
| `uvx basic-memory mcp` | config | yes | The command a client runs for a local install. Notes live in ~/basic-memory unless you make other projects. Example: `"args": ["--prerelease=allow", "basic-memory", "mcp"]` |
| `BASIC_MEMORY_NO_PROMOS` | env | no | Set to 1 to hide cloud promotions and switch off telemetry. Example: `1` |
| `BASIC_MEMORY_LOG_LEVEL` | env | no | How much it logs: DEBUG, INFO, WARNING or ERROR. Example: `DEBUG` |
| `BASIC_MEMORY_RERANKER_ENABLED` | env | no | Set to true to re-rank search results with a second model for better matches. Example: `true` |
| `BASIC_MEMORY_FORCE_LOCAL` | env | no | Keep every project on local files even when cloud routing is set up. |

### What can Basic Memory read and change?

**It can read**

- Markdown notes in your Basic Memory project folders
- A local search index built from them

**It can change**

- Creates, edits, moves and deletes Markdown files in those folders
- Keeps the index in sync when you edit notes by hand

**Safer setup:** Keep the notes folder in git or a synced drive so you can roll back any edit the AI makes.

### Good for

- Carrying project context between chats
- A personal knowledge base the assistant can add to
- Keeping memory local instead of in a vendor account

### Basic Memory not working? Common fixes

**Search misses notes you edited by hand**
Run basic-memory reindex, with BASIC_MEMORY_LOG_LEVEL=DEBUG if you need to see why.

**Desktop app cannot start uvx**
Give the full path from which uvx in the command field, then restart the app.

**Notes land in the wrong project**
Ask list_memory_projects to see the default, or name the project in your request.

### What are the alternatives to Basic Memory?

| Server | What it does | Tools | Runs on | Licence | Stars |
| --- | --- | --- | --- | --- | --- |
| [Basic Memory](https://mcpshelf.co/servers/basic-memory) | Long-term memory as plain Markdown files you own. | 27 | Your computer | AGPL-3.0-or-later | 4.4K |
| [LinkedIn MCP Server](https://mcpshelf.co/servers/linkedin) | Read LinkedIn profiles, companies and job posts with your own login. | 20 | Your computer | Apache-2.0 | 4K |
| [arXiv MCP Server](https://mcpshelf.co/servers/arxiv) | Search arXiv, download papers and read them in full. | 19 | Your computer | Apache-2.0 | 3.2K |
| [TradingView MCP](https://mcpshelf.co/servers/tradingview) | Prices, indicators, screeners and backtests for stocks, crypto and forex, no account needed. | 37 | Your computer or hosted | MIT | 5.2K |
| [Obsidian MCP](https://mcpshelf.co/servers/obsidian) | Search, read and edit the notes in your Obsidian vault. | 15 | Your computer | MIT | 4.5K |
| [Google Workspace MCP](https://mcpshelf.co/servers/google-workspace) | Gmail, Drive, Calendar, Docs, Sheets and six more Google apps behind one server. | 43 | Your computer | MIT | 3.4K |

### Basic Memory FAQ

#### How do I add Basic Memory to Claude Code?

Run claude mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp. The --prerelease=allow flag matters: without it uv installs an older release. Notes go to ~/basic-memory by default.

#### How do I install Basic Memory in Claude Desktop?

Add a basic-memory entry to claude_desktop_config.json with command uvx and args --prerelease=allow, basic-memory and mcp, then restart Claude Desktop. If it cannot start uvx, use the full path that which uvx prints.

#### Where does Basic Memory keep my notes?

As plain Markdown files on your disk, in ~/basic-memory unless you set up another project folder. You can open, edit or version them yourself in any text editor.

#### Is Basic Memory free?

Running it locally is free and open source under AGPL-3.0. Basic Memory Cloud, with sync, mobile access and a team workspace, is a paid subscription with a 7-day trial.

#### Does Basic Memory work with Obsidian?

Yes, with no setup. Point Obsidian at the notes folder and the wikilinks, frontmatter and Markdown the assistant writes show up in your vault and graph view, and edits on either side are shared.

#### Does Basic Memory work with ChatGPT?

It includes search and fetch tools in the format ChatGPT expects. ChatGPT only connects to remote servers, so follow the project's ChatGPT guide or use the cloud version rather than the local install.

#### Is Basic Memory safe?

In the local version everything stays on your machine, and the notes are ordinary files you can read to see exactly what the assistant saved. Keep the folder in git or a synced drive so you can roll back an edit you do not like.

#### Basic Memory or Obsidian MCP?

Basic Memory is built as the assistant's own memory, with linked notes it can follow through memory:// links. An Obsidian server works on a vault you already have. They can share one folder if you want both.

#### How do I add Basic Memory to Cursor?

In ~/.cursor/mcp.json, or .cursor/mcp.json for one project, add an entry named basic-memory that runs uvx --prerelease=allow basic-memory mcp. Save, and the tools show up in Agent chat.

#### Can I use Basic Memory in VS Code?

Yes, through GitHub Copilot. In .vscode/mcp.json, add a server named basic-memory with type stdio that runs uvx --prerelease=allow basic-memory mcp. Then switch Copilot Chat to Agent mode to use its tools.

#### Does Basic Memory work with Codex?

Yes. Run codex mcp add basic-memory -- uvx --prerelease=allow basic-memory mcp in a terminal, or add an [mcp_servers.basic-memory] table to ~/.codex/config.toml, which the Codex CLI and IDE extension share.

Full docs on GitHub: https://github.com/basicmachines-co/basic-memory

## Notes for agents

Fetch these instead of parsing the HTML page:

- llms.txt: https://mcpshelf.co/llms.txt
- llms-full.txt: https://mcpshelf.co/llms-full.txt
- ai.txt: https://mcpshelf.co/ai.txt
- Full catalog (.md): https://mcpshelf.co/catalog.md
- API spec: https://mcpshelf.co/openapi.json
- MCP server: https://mcpshelf.co/mcp
- MCP manifest: https://mcpshelf.co/.well-known/mcp.json
- Developer docs: https://mcpshelf.co/developers

MCP endpoint (Streamable HTTP, no key): https://mcpshelf.co/mcp. REST API: https://mcpshelf.co/api/v1.

