# basicmachines-co/basic-memory [Health: Active]

**Category:** 🧠 Knowledge & Memory  
**Repository:** https://github.com/basicmachines-co/basic-memory  
**GitHub Stars:** 4369  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/basicmachines-co-basic-memory

## Description
Persistent, local-first AI memory: a semantic knowledge graph of plain Markdown files that humans and LLMs both read and write. Works with any MCP client, with optional cloud sync and team workspaces.

## Tools
Capabilities this server exposes over MCP:

- **bm_write**
- **bm_read**
- **bm_edit**
- **bm_move**
- **bm_delete**
- **bm_search**
- **bm_list**
- **bm_find**
- **bm_context**
- **bm_man**
- **search**
- **fetch**
- **basic_memory_diagnostics**

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

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

## Documentation

## What basicmachines-co/basic-memory does

basicmachines-co/basic-memory exposes a Markdown-backed knowledge system through the Model Context Protocol. Notes remain ordinary text files that humans can inspect and edit, while observations and wikilinks form a connected knowledge graph for agent use. The same underlying Markdown model supports both the local application and the hosted cloud service.

The server is designed for persistent context across conversations and projects. Agents can create knowledge, retrieve relevant material, update existing notes, reorganize files, and remove obsolete content. Because the data is stored as Markdown, it can also be used outside the MCP client and exported without converting it to a proprietary format.

## How it works

A local deployment runs as a Python package and reads and writes knowledge on the local disk. Python 3.12 or newer is required, and the recommended installation path uses `uv`. The project describes this mode as free, local-first, and suitable for air-gapped environments. Synchronization is optional rather than required; users can handle local synchronization with tools such as Git or Syncthing.

Basic Memory Cloud runs the same open-source engine while hosting the database and synchronization layer. It provides web, mobile, and desktop access, with bidirectional sync between local Markdown and hosted storage. Cloud accounts also provide snapshots, backups, conflict resolution, and shared team workspaces. The hosted service uses HTTPS connections for MCP clients, while local connections can use stdio.

Semantic search finds notes by meaning rather than only matching words. Optional cross-encoder reranking can improve vector and hybrid search results. Tool behavior hints identify properties such as read-only, destructive, and idempotent operations, allowing clients to discover tools progressively.

## Setup and configuration

Install the local package with:

```bash
uv tool install basic-memory --prerelease=allow
```

The prerelease flag is needed because the package depends on a FastMCP 4 prerelease and `uv` otherwise may select an older compatible dependency. Use the same flag with `uvx` and upgrade commands. Deployments that store semantic vectors in Milvus can install the optional package extra:

```bash
uv tool install "basic-memory[milvus]" --prerelease=allow
```

After installation, configure the MCP client to launch the local server. The repository lists Claude Desktop, Claude Code, Codex, Cursor, and VS Code as supported clients for local stdio connections. The cloud option is connected through the Basic Memory web application and uses HTTPS, avoiding a local Python installation.

## Tools and capabilities

- `bm_write` creates or writes knowledge entries.
- `bm_read` retrieves stored content.
- `bm_edit` updates an existing entry.
- `bm_move` reorganizes stored content.
- `bm_delete` removes content.
- `bm_search` and `search` support finding relevant knowledge.
- `bm_list` enumerates available entries.
- `bm_find` locates matching content.
- `bm_context` retrieves surrounding or related context.
- `bm_man` exposes tool or usage information.
- `fetch` retrieves content for clients that use search-and-fetch workflows, including ChatGPT Custom GPT actions.
- `basic_memory_diagnostics` provides diagnostic information.

The cloud service additionally supports cross-device access, shared workspaces, real-time collaborative note editing, snapshots, backups, and export to Markdown.

## Limitations and notes

The local and cloud modes have different operational requirements. Local mode keeps data on disk and supports air-gapped use, but cross-device synchronization and backups are handled by the user. Cloud mode supplies hosted storage and synchronization but is not air-gapped and is a paid service after its trial period.

The project is licensed under AGPL-3.0. Markdown remains the storage format in both modes, so users can export their notes and continue working with the files outside the MCP server.

_Full upstream README: https://allmcps.com/mcp/basicmachines-co-basic-memory/readme_