Log inSubmit server
Basic Memory logo

Basic Memory

by basicmachines-co

Stores and searches a local Markdown knowledge graph through MCP, with optional cloud sync and shared workspaces.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Basic Memory

Pick your client, then add it in one click or paste the config.

STDIOPython
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "basicmachines-co-basic-memory": {
      "command": "uvx",
      "args": [
        "--prerelease=allow",
        "basic-memory"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

Install not yet sandbox-tested— we haven't run this command through our automated sandbox yet. Not a red flag; we're working through the catalog.

Overview

basicmachines-co/basic-memory gives MCP clients read/write access to a semantic knowledge graph stored in plain Markdown files. Its tools cover note creation, editing, moving, deletion, listing, semantic search, context retrieval, and diagnostics. Local installations keep data on disk and can support air-gapped workflows, while the optional cloud service adds cross-device sync, backups, and team workspaces. Reach for it when an agent needs persistent, human-readable memory that people and models can update together.

Use cases

  • Store durable project notes for agents
  • Search a personal knowledge graph by meaning
  • Update Markdown memory from an MCP client
  • Share synchronized knowledge across a team
  • Retrieve related context across conversations

Key features

  • Plain Markdown storage
  • Semantic and hybrid search
  • Knowledge graph with wikilinks
  • Read and write MCP tools
  • Optional cloud synchronization
  • Progressive tool discovery hints

Tools13

What Basic Memory lets your agent do. Expand a tool for its parameters.

Self-reported~28 tokens of context

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked Today

Recent health check succeeded.

28/28 checks healthy over the last 77d

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 17d ago via OSV.dev · basic-memory (PyPI)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars4.4kStargazers on the source repository.
Last commitTodayMost recent push to the default branch.
Tools exposed13Callable tools this server registers over MCP.
Directory activity2 viewsConfig copies, upvotes, and views on AllMCPs.

How Basic Memory works

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.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Basic Memory

basicmachines-co/basic-memory is an MCP server that connects AI clients to a semantic knowledge graph stored in plain Markdown files. Its main tools write, read, edit, move, delete, list, search, find, and retrieve context from notes, with additional fetch and diagnostics tools. Local storage and optional cloud synchronization are supported.

Install it locally with `uv tool install basic-memory --prerelease=allow`, then configure your MCP client to launch it. Python 3.12 or newer is required. The prerelease flag is needed because the package depends on a FastMCP 4 prerelease.

Yes, basicmachines-co/basic-memory works with Cursor through stdio for local installations or HTTPS through Basic Memory Cloud. Cursor is listed among the supported clients, and the cloud service provides a connection flow from its web application.

Yes, the local installation stores knowledge as plain Markdown files on disk. This mode is free, keeps data on the user’s machine, and is described as suitable for air-gapped workflows. Cross-device synchronization and backups are then managed separately.

Yes, Basic Memory Cloud adds bidirectional synchronization across devices, hosted storage, snapshots, backups, and team workspaces. The cloud mode uses the same Markdown-based product and MCP tools, while local mode remains available without requiring cloud synchronization.

Related MCP servers

All in Knowledge & Memory All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewBasic Memory AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/basicmachines-co-basic-memory?style=directory)](https://allmcps.com/mcp/basicmachines-co-basic-memory)
HTML Embed
<a href="https://allmcps.com/mcp/basicmachines-co-basic-memory"><img src="https://allmcps.com/api/badge/basicmachines-co-basic-memory?style=directory" alt="Basic Memory on AllMCPs" /></a>