Overview

Basic Memory is an MCP (Model Context Protocol) server that stores conversational knowledge in local Markdown files, letting LLMs both read from and write to a personal knowledge graph. It exposes a set of MCP tools so AI assistants (e.g., Claude) can load conversation context, add structured notes, and update or search your local corpus in real time — all while keeping source files editable with any Markdown editor (Obsidian, VS Code, etc.).

The server is local-first by default but supports optional cloud routing per project. Data is stored as plain .md files and indexed in a lightweight SQLite store; newer releases also include semantic vector search for meaning-based retrieval. This makes it easy to build persistent, traversable knowledge from natural conversations without requiring proprietary vector databases or complex infra.

Features

Local-first Markdown storage: notes are plain .md files you control.
Bi-directional access: LLMs can read and write the same notes you edit.
MCP-compatible: exposes tools via the Model Context Protocol for seamless LLM integration.
Obsidian-friendly: files and links follow standard Markdown conventions.
Hybrid search: full-text search plus semantic vector similarity (FastEmbed).
Schema tooling: infer, validate, and diff note/schema structure.
CLI with JSON output for scripting and automation.
Auto-update flow for supported installs (configurable).
Per-project cloud routing (optional) with API-key based authentication.
FastMCP 3.0 tool annotations for better client/tooling integration.

Installation / Configuration

Install via Python/PyPI or through uv (recommended for desktop integrations):

# pip
pip install basic-memory

# uv (recommended)
uv tool install basic-memory

Run the MCP server:

# start the MCP server (desktop use)
basic-memory mcp

Configure Claude Desktop (example JSON fragment):

{
  "mcpServers": {
    "basic-memory": {
      "command": "uvx",
      "args": [
        "basic-memory",
        "mcp"
      ]
    }
  }
}

Default local directory and config:

Notes default to ~/basic-memory (changeable per project).
Global config at ~/.basic-memory/config.json

Example config.json keys:

{
  "auto_update": true,
  "update_check_interval": 86400
}

Auto-update commands:

# check for updates and install if supported
bm update

# check only
bm update --check

Per-project cloud routing:

# route a specific project through Basic Memory cloud (stores API key in project settings)
basic-memory project set-cloud --project my-project --api-key YOUR_KEY

Available Tools / Resources

The server exposes MCP tools for AI clients. Typical tool names and behaviors:

write_note: create or overwrite a Markdown note (with guards to prevent accidental overwrite).
edit_note: append/prepend or patch an existing note; auto-creates if missing for append/prepend.
read_note / read_notes: fetch note content by path or query.
search: full-text + semantic search, returns matched chunks and metadata.
list_notes: list files in a project or folder.
schema_infer: infer a schema from existing notes.
schema_validate: validate notes against a schema.
schema_diff: show differences between schemas or note sets.
project_set_cloud / project_unset_cloud: manage optional cloud routing.

Return values are JSON structured for programmatic use; the CLI supports a –json flag for scripting.

Note File Patterns

Notes are plain Markdown. A simple example:

# Coffee Brewing: Pour Over

tags: #coffee #brewing

Summary:
- Preferred water temp: 94°C
- Grind: medium-fine

Links:
- [[Coffee: Beans]]

The server indexes headlines, tags, links, and small content chunks to support retrieval and traversal.

Use Cases

Obsidian + LLM assistant: let Claude read relevant notes from your vault and write new ones directly as you chat, keeping your Obsidian graph up to date.
Persistent chat memory: have LLMs remember project decisions, meeting notes, and preferences across sessions without manual copy/paste.
Structured knowledge capture: during a conversation, instruct the assistant to create or update notes in a consistent schema (e.g., meeting.md with participants and action items) and validate via schema tooling.
Local RAG replacement: combine local Markdown + semantic search to retrieve context for LLM prompts without sending documents to an external vector DB.
Hybrid cloud routing: keep most projects fully local while routing a specific collaboration workspace through the optional cloud layer for team sync.

Getting Help & Resources

Repo: https://github.com/basicmachines-co/basic-memory
Docs: check the docs site in the repo for CLI references and schema examples.
Community: project maintains community links for discussion and troubleshooting.

If you are integrating this with a custom LLM client, use the FastMCP tool annotations and the –json CLI output mode to make automation robust and predictable.

Basic Memory MCP Server for Markdown Knowledge Graph