Basic Memory: Markdown-Based LLM Memory via MCP
basicmachines-co/basic-memory
Basic Memory is a local-first tool that turns AI conversation memory into plain Markdown files with wikilinks, instead of locking it in a vector database or a chat log. Reach for it if you want a knowledge base you can read, edit, and grep yourself. Skip it if you want zero setup — the $15.00/mo cloud tier removes the install step but still means trusting a hosted sync.
The LLM Memory Problem
Every new AI chat starts from zero. Chat history logs what was said but isn't structured knowledge a model can navigate. RAG lets an LLM query your documents but can't write back to them. A vector database solves retrieval but needs its own infrastructure, usually hosted somewhere you don't control. And a proper knowledge graph needs specialized tooling most developers never set up. Basic Memory's README frames this directly: none of the usual workarounds let a human and an LLM read and write the same knowledge store.
What Basic Memory Does
Basic Memory is an MCP (Model Context Protocol) server and CLI that stores an LLM's knowledge as structured Markdown files on your disk, not inside a vector database or a proprietary format. Each note is an Entity with tagged Observations and wikilink Relations, so the AI follows links instead of stuffing your whole context window every turn. It plugs into Claude, Cursor, VS Code, Codex, ChatGPT, and Obsidian over the same files.
Core Capabilities
- ✓Two-way Markdown sync: both you and the AI read and write the same files, so an edit in Obsidian shows up in the next chat and vice versa.
- ✓Entity/Observation/Relation grammar: notes carry bracketed observation categories (e.g. [method], [fact]) and wikilink relations that form a traversable knowledge graph.
- ✓Hybrid semantic search: full-text plus vector ranking via FastEmbed embeddings, running on SQLite or Postgres, with optional cross-encoder reranking (off by default).
- ✓MCP-native tool surface: write_note, read_note, edit_note, move_note, delete_note, search_notes, build_context, and more, each tagged with read-only/destructive/idempotent hints.
- ✓Schema tooling: schema_infer, schema_validate, and schema_diff let you check the shape of your knowledge base as it grows.
- ✓Per-project cloud routing: bm project set-cloud/set-local flips individual projects between local and hosted storage without touching the rest of the setup.
- ✓Auto-updates for uv tool and Homebrew installs, checked every 24 hours and applied silently, plus a manual bm update when you want control.
How Developers Use Basic Memory
- •Carrying project context across Claude Code or Cursor sessions — a simple form of LLM context management — instead of re-pasting architecture notes every time.
- •Building a running log of decisions and 'ProTips' the AI can reference weeks later; one person quoted in the README describes using it this way instead of keeping an active chat thread open.
- •Importing existing history with basic-memory import claude conversations or import chatgpt to seed a knowledge base from past chats.
- •Editing the same notes in Obsidian's graph view while an AI client writes to them through MCP.
- •Running air-gapped, since the local install needs nothing but Python (via uv) and a local SQLite index.
Getting Started: Cloud or Local
Two paths, same underlying engine and the same Markdown files. Cloud: sign up at basicmemory.com, connect an AI client, and you're running in about 30 seconds — no Python, no terminal. It costs $15.00/mo locked in for the life of the subscription (list price $19), with a 7-day free trial and an OSS discount code (BMFOSS) for 20% off the first three months. Local: install the CLI with uv — `uv tool install basic-memory` — which takes about 2 minutes and is free under AGPL-3.0. Running Postgres and want vectors stored in Milvus? Install the optional extra instead: `uv tool install "basic-memory[milvus]"`. Either way you then point an MCP client at it — for Claude Code that's `claude mcp add basic-memory -- uvx basic-memory mcp`; Claude Desktop, Cursor, and VS Code each take a short JSON or TOML snippet in their MCP config instead.
Working with Basic Memory
Every note is a Markdown file with YAML frontmatter (title, type, permalink, optional tags) and two sections that give the format its structure. Observations are bullet facts tagged with a bracketed category, like `[method] Pour over highlights subtle flavors`, and Relations are wikilinks such as `requires [[Burr Grinder]]` that connect one entity to another. You don't design a schema up front — ask the AI to make a note and it writes the file in that grammar; Basic Memory's own example has it capturing a coffee-brewing conversation this way. Once you have enough notes to want consistency, `schema_infer` and `schema_validate` check what structure has actually accumulated, and `basic-memory doctor` catches drift between the files on disk and the SQLite index.
Why Choose Basic Memory
- ✓Files are just Markdown on your disk — local-first AI notes with no export step and no proprietary database to dump if you switch tools later.
- ✓Works across almost every MCP client at once (Claude, Cursor, VS Code, Codex, ChatGPT, Obsidian), so you're not locked into one AI vendor's memory feature.
- ✓Local install costs nothing and runs air-gapped; the cloud tier is optional, not required, for any of the core functionality.
- ✓Tool annotations (read-only, destructive, idempotent hints) mean an agent can pick the right MCP tool without probing first.
Considerations and Trade-offs
- △Local install requires Python tooling via uv — not a one-click install, and the README itself frames the cloud tier as the path for people who don't want a terminal.
- △Cross-device sync isn't part of the free local path; you're rolling your own with Git or Syncthing, or paying $15.00/mo for the cloud plan to get it built in.
- △Cross-encoder reranking is off by default and triggers a first-run model download the first time you turn it on — one more thing to budget for if you want better search relevance.
- △AGPL-3.0 is a copyleft license, which some companies avoid for anything they might bundle into a proprietary product.
Alternatives to Basic Memory
Basic Memory FAQs
Basic Memory is free to use locally — the local install is free forever under the AGPL-3.0 license. Only the hosted cloud version, at $15.00/mo, carries a cost, and even that comes with a 7-day free trial.
Basic Memory is licensed under AGPL-3.0, a copyleft open-source license, and that applies to the local install as well as the cloud product's source code.
Basic Memory supports cross-device sync as a built-in feature of the paid cloud tier, using rclone-powered bidirectional sync with conflict resolution. The free local install doesn't sync on its own — you'd need to add Git or Syncthing yourself.
Basic Memory integrates with Obsidian directly, with no separate setup: point Obsidian at the same folder (`~/basic-memory` by default) and its wikilinks, frontmatter, and Markdown show up in Obsidian's graph view.
Basic Memory connects to Claude Desktop, Claude Code, Codex, Cursor, VS Code, and ChatGPT (via Custom GPT actions), plus any other client that speaks MCP.
Basic Memory offers a hosted cloud version called Basic Memory Cloud, priced at $15.00/mo locked in for the life of the subscription, that adds cross-device sync, mobile access, and automatic snapshots and backups on top of the same open-source engine.
Who should try it — and who should skip
Try Basic Memory if you already work across multiple AI clients — say Claude Code for one project and Cursor for another — and want one knowledge base instead of re-explaining context to each. It also fits developers who want their AI's memory in a format they can open in a text editor, put under version control, or read without asking the tool's permission. Skip it if you just want retrieval over a pile of existing documents (that's RAG's job, not this), or if a Python CLI install is more setup than you're willing to do just for project memory — the cloud tier removes that friction but adds a recurring cost the free local path doesn't have.