# basic-memory

A local MCP server that keeps your knowledge in Markdown files on disk and lets the AI read, write and search them. Useful when you are tired of re-explaining project context.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 4357
- Author: basicmachines-co
- License: AGPL-3.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/basicmachines-co/basic-memory
- Updated: 2026-10-24
- HTML: https://affpapa.org/en/nevibecode/mcp/basic-memory

## What it does

Basic Memory treats plain Markdown files on your disk as the source of truth. Both you and the agent write to the same notes, and sync keeps the two sides aligned. Observations and wikilinks build up into a knowledge graph, so context survives between sessions instead of evaporating.

Search works by meaning, not just keywords, and you can turn on cross-encoder reranking for better vector and hybrid results. Every tool carries behaviour hints — read-only, destructive, idempotent — so the agent picks the right one without burning context on trial and error. A hosted option exists for syncing across devices, though it is never required.

Local setup needs Python through `uv`. Install with `uv tool install basic-memory --prerelease=allow`. That flag is not optional: version 0.23 pulls in a FastMCP 4 pre-release, and without it `uv` quietly falls back to an older build. Postgres deployments that keep semantic vectors in Milvus use a separate extra: `uv tool install "basic-memory[milvus]" --prerelease=allow`.

## Requirements
- Needs: Python and uv (commands run via uvx)

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add basic-memory -- uvx basic-memory
```
uvx runs the command named after the package; if the README names another one, use uvx --from basic-memory <command>

### Codex

**Platform CLI**
```bash
codex mcp add basic-memory -- uvx basic-memory
```
uvx runs the command named after the package; if the README names another one, use uvx --from basic-memory <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "basic-memory": {
            "command": "uvx",
            "args": [
                "basic-memory"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from basic-memory <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "basic-memory": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "basic-memory"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from basic-memory <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add basic-memory uvx basic-memory
```
uvx runs the command named after the package; if the README names another one, use uvx --from basic-memory <command>

## When to use it
- build a knowledge graph from Markdown files on disk
- find a note by meaning rather than exact wording
- give the agent access to past sessions and decisions
- keep one shared log of human and AI edits
- sync notes across devices through the cloud

## Example prompts
- Search my notes for everything about this service's deploy
- Save the auth schema decision to basic-memory
- Show me the links between notes on the database migration

## Similar
- [GitHub](https://affpapa.org/en/nevibecode/mcp/github.md) — MCP server · ★ 33918
- [Netdata](https://affpapa.org/en/nevibecode/mcp/netdata.md) — MCP server · ★ 81115
- [browser-use](https://affpapa.org/en/nevibecode/mcp/browser-use.md) — MCP server · ★ 119160
- [Codebase Memory](https://affpapa.org/en/nevibecode/mcp/codebase-memory.md) — MCP server · ★ 47392
- [mcp-server](https://affpapa.org/en/nevibecode/mcp/mcp-server.md) — MCP server · ★ 43872
- [AIHawk](https://affpapa.org/en/nevibecode/mcp/aihawk.md) — MCP server · ★ 32221

From the same set: [basicmachines-co/basic-memory](https://affpapa.org/en/nevibecode/by/basicmachines-co/basic-memory.md) — 14 cards

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md