# Basic Memory

> Local-first agent memory as plain Markdown — a semantic knowledge graph you and the agent can both read.

[Canonical HTML page](https://top-mcps.com/mcp/basic-memory) · [server.json](https://top-mcps.com/mcp/basic-memory.json) · [methodology](https://top-mcps.com/about/methodology)

## Install

### Claude Desktop — `claude_desktop_config.json`

Paste under mcpServers. Fully quit and reopen Claude after editing.

```json
{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ],
      "env": {
        "BASIC_MEMORY_PROJECT": "${BASIC_MEMORY_PROJECT}"
      }
    }
  }
}
```

### Claude Code — `CLI or .mcp.json`

Run from your repo. Commit .mcp.json to share with your team.

```shell
# export BASIC_MEMORY_PROJECT=optional-project-name
claude mcp add basic-memory -- uvx basic-memory mcp
```

### Cursor — `.cursor/mcp.json`

Global path: ~/.cursor/mcp.json. Reload window after editing.

```json
{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ],
      "env": {
        "BASIC_MEMORY_PROJECT": "${BASIC_MEMORY_PROJECT}"
      }
    }
  }
}
```

### VS Code — `.vscode/mcp.json`

VS Code uses the "servers" key (not "mcpServers").

```jsonc
{
  "servers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ],
      "env": {
        "BASIC_MEMORY_PROJECT": "${BASIC_MEMORY_PROJECT}"
      }
    }
  }
}
```

### Windsurf — `~/.codeium/windsurf/mcp_config.json`

Open via Cascade → hammer icon → Configure.

```json
{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ],
      "env": {
        "BASIC_MEMORY_PROJECT": "${BASIC_MEMORY_PROJECT}"
      }
    }
  }
}
```

### Cline — `cline_mcp_settings.json`

Open via the Cline sidebar → MCP Servers → Edit.

```json
{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ],
      "env": {
        "BASIC_MEMORY_PROJECT": "${BASIC_MEMORY_PROJECT}"
      }
    }
  }
}
```

### Continue — `~/.continue/config.json`

Continue uses modelContextProtocolServers with a transport block.

```json
{
  "experimental": {
    "modelContextProtocolServers": [
      {
        "transport": {
          "type": "stdio",
          "command": "uvx",
          "args": [
            "basic-memory",
            "mcp"
          ],
          "env": {
            "BASIC_MEMORY_PROJECT": "${BASIC_MEMORY_PROJECT}"
          }
        }
      }
    ]
  }
}
```

### Codex CLI — `~/.codex/config.toml`

Codex uses TOML. Each server is a [mcp_servers.<name>] subtable.

```shell
# ~/.codex/config.toml
[mcp_servers.basic-memory]
command = "uvx"
args = [
  "basic-memory",
  "mcp",
]
env = { BASIC_MEMORY_PROJECT = "${BASIC_MEMORY_PROJECT}" }
```

### Zed — `~/.config/zed/settings.json`

Zed calls them "context_servers". Settings live-reload on save.

```jsonc
{
  "context_servers": {
    "basic-memory": {
      "command": {
        "path": "uvx",
        "args": [
          "basic-memory",
          "mcp"
        ]
      },
      "env": {
        "BASIC_MEMORY_PROJECT": "${BASIC_MEMORY_PROJECT}"
      }
    }
  }
}
```

### ChatGPT — `ChatGPT → Apps directory`

Basic Memory doesn't ship a hosted HTTPS endpoint today. ChatGPT supports remote MCP servers only — to use this server in ChatGPT you'll need to deploy it to a public HTTPS URL first (e.g. via Cloudflare Workers or Vercel) or wait for an official remote build.

```none

```

## At a glance

- **Maintainer:** Basic Machines
- **Transport:** stdio
- **Auth model:** None
- **Required secrets:** BASIC_MEMORY_PROJECT
- **Supported clients:** Claude, Claude Desktop, Cursor, VS Code, Obsidian, Any MCP-compatible client
- **License:** AGPL-3.0
- **Language:** Python
- **Latest version:** 0.22.1
- **Last verified:** 2026-06-22
- **GitHub stars:** 3,273 (fetched 2026-06-22T09:44:47.864Z)
- **Score:** 81/100 (rubric 2026-04 — see https://top-mcps.com/about/methodology)
- **Source:** https://github.com/basicmachines-co/basic-memory

## Tools & permissions

| Tool | Description | Args | Side effects |
|------|-------------|------|--------------|
| `write_note` | Create or update a Markdown note in the knowledge base. | `title: string, content: string` | write |
| `read_note` | Read a note by title or path. | `identifier: string` | read |
| `search` | Full-text and semantic search across notes. | `query: string` | read |
| `build_context` | Traverse the note graph to assemble relevant context for a topic. | `url: string` | read |
| `recent_activity` | List recently created or edited notes. | `—` | read |

## Security & scope

- **Access scope:** read-write
- **Sandbox:** Reads and writes Markdown files inside the configured project directory. No outbound network calls unless cloud sync is explicitly enabled.
- **Gotchas:**
  - Tools can delete and overwrite notes — point it at a dedicated folder, not your whole home directory.
  - AGPL-3.0 is copyleft; review it before bundling Basic Memory into a distributed product.
  - A misconfigured project path can let the agent write outside the intended vault — set BASIC_MEMORY_PROJECT explicitly.

## Quick answer

**What it does.** Reads and writes Markdown notes in a local project folder, builds a link-based semantic graph over them, and serves relevant context back to the agent via search and graph-traversal tools.

**Best for:**
- Local-first agent memory
- Obsidian vault read/write from an agent
- Inspectable, git-versionable memory
- Cross-session project recall
- Privacy-conscious personal assistants

**Not for:**
- Multi-tenant SaaS memory at scale
- Billion-scale vector retrieval
- Teams blocked by AGPL-3.0 licensing

## Description

Basic Memory gives an AI agent persistent, cross-session recall by writing notes to plain Markdown files on disk and building a semantic graph over them. Unlike a managed cloud memory or an opaque vector index, every memory is a human-readable Markdown file in a folder you control — editable in any text editor, viewable in Obsidian, and versionable in git. The agent writes a note, links it to related notes, and on the next session reads the relevant slice back. It is the memory layer for people who want their agent's memory to be inspectable, portable, and theirs.

## Why it matters

The two dominant memory approaches — managed cloud (Mem0) and JSONL knowledge graphs (the official Memory server) — are both opaque to the human. Basic Memory makes the memory store the same Markdown the human already reads, so there is no second system of record and nothing leaves the machine unless you opt into cloud sync.

## Key features

- Memory stored as plain Markdown on disk
- Semantic graph built from note links
- Obsidian-compatible vaults
- Read-only / destructive / idempotent MCP tool annotations
- Optional cloud sync, local by default

## FAQ

### Where does the memory actually live?

In plain Markdown files in a local folder (default ~/basic-memory). You can open, edit, and git-version them directly, or point Basic Memory at an existing Obsidian vault.

### How is it different from the official Memory MCP?

The official Memory server stores a knowledge graph in a JSONL file the human rarely opens. Basic Memory stores human-readable Markdown notes and derives the graph from their links — the store and your notes are the same files.

### Does anything leave my machine?

No, by default. Basic Memory is local-first; cloud sync is an explicit opt-in. With no cloud configured, all reads and writes stay on disk.

## Changelog

- **2026-06-22** — Refreshed install snippets and fact sheet; verified for 2026.
- **2025-03-01** — Initial directory listing.