Basic Memory: A Local-First MCP Server That Puts Your AI Conversations in Markdown

The Problem: AI Conversations Forget Project Context

Every engineer who works with an AI assistant has hit the same wall. You explain your project structure, your coding conventions, your API design. Then you start a new session and the AI greets you like a stranger. Basic Memory addresses this by giving the AI a persistent memory that lives in Markdown files on your disk. It is designed for developers using Claude, Codex, Cursor, ChatGPT, or any client that speaks the Model Context Protocol (MCP). The README frames it as a way to never re-explain your project to your AI again. The tool is not a chatbot itself; it is a memory layer that sits between you and your AI client.

How It Works: Markdown Files, Wikilinks, and a Knowledge Graph

Basic Memory stores knowledge as plain Markdown files that both you and your AI can read, write, and search. The README describes it as a real knowledge graph where observations and wikilinks compound into context. The mechanism is simple: you write notes in Markdown, link them with wikilinks, and the AI uses those files as its memory. The system includes semantic search, which finds notes by meaning rather than just keywords. For higher-quality results, it offers optional cross-encoder reranking for vector and hybrid searches. This is not a vector database in the traditional sense; the source of truth is the text files themselves. The MCP server exposes tools that let the AI create, read, edit, and search these files. The documentation emphasizes progressive tool discovery: every tool is tagged with behavior hints such as read-only, destructive, or idempotent, so the agent can pick the right tool without wasting context on trial and error.

Getting It Running: uv Install and the Prerelease Flag

The local install path requires Python and the `uv` package manager. The README gives the exact command: `uv tool install basic-memory --prerelease=allow`. The `--prerelease=allow` flag is not optional. Basic Memory 0.23 depends on a FastMCP 4 pre-release, and `uv` will silently install an older release unless you tell it to accept pre-releases. The same flag must be used on every `uvx` or `uv tool upgrade` command. For Postgres deployments that store semantic vectors in Milvus, there is a first-party extra: `uv tool install "basic-memory[milvus]" --prerelease=allow`. After installation, you configure your AI client. The README lists supported clients including Claude Desktop, Claude Code, Codex, Cursor, and VS Code, with transport options of stdio or http. The cloud version skips all of this: you sign up and connect your client in 30 seconds, no terminal required.

Local vs. Cloud: The Same Engine, Different Trade-Offs

The README presents two deployment paths that run the same product on the same Markdown. The local edition is free, AGPL-3.0, and air-gapped friendly. All data stays on your disk. The cloud edition costs $15.00 per month, locked in for life during beta, and adds cross-device sync, mobile access, and built-in backups. The cloud is built on WorkOS AuthKit, Neon Postgres, and Tigris S3. The local edition has no mobile access and no built-in sync; the README suggests Git or Syncthing for manual synchronization. This is a genuine trade-off. If you need to edit a note on your phone and see it in Obsidian on your laptop, you need the cloud or a third-party sync tool. The local path gives you full control but shifts the operational burden to you.

A Real Limitation: The Prerelease Dependency and Sync Burden

The most concrete limitation is the dependency on a FastMCP 4 pre-release. The README warns that without the `--prerelease=allow` flag, `uv` silently installs an older release. That older release may not work correctly with Basic Memory 0.23. This is a maintenance hazard: every upgrade requires the same flag, and you are relying on a pre-release of a core dependency. The second limitation is the lack of built-in sync in the local edition. The README lists Git and Syncthing as options, but those are manual processes. If you work across multiple machines, you will need to set up and maintain that sync yourself. For teams, the README now promotes Basic Memory Teams, a shared cloud workspace, which suggests that the local edition is not designed for real-time collaboration. If you need a single shared knowledge base across a team, the local path is the wrong tool.

Alternatives: How It Differs from Other Memory Layers

The obvious alternative is a proprietary memory service like Mem0 or a vector database with an MCP wrapper. The difference is that Basic Memory keeps the source of truth in plain Markdown files on your disk, not in a hosted database. You can read, edit, and export your notes with any text editor. The README emphasizes no lock-in: your notes are plain Markdown, and you can export to local Markdown anytime. Another alternative is to roll your own memory by giving your AI a directory of text files and a retrieval tool. That approach lacks the semantic search and knowledge graph features that Basic Memory provides out of the box. The trade-off is that Basic Memory is a specific MCP server with its own tool conventions, whereas a hand-rolled solution would be fully custom but would require you to build the retrieval and search logic yourself.

Maintenance and License: What You Need to Know

The project is licensed under AGPL-3.0. That means if you modify the source and deploy it as a network service, you must release your modifications under the same license. For internal use, this is rarely a problem, but it is a real consideration for companies that want to embed the code in a proprietary product. The README does not provide a changelog or migration guide, but the recent releases (v0.23.0, v0.23.1, v0.23.2) suggest an active maintenance cadence. The dependency on a FastMCP pre-release means you should expect to follow release notes closely. The README also mentions a Discord community, which is where you would likely get support. There is no documentation in the README about upgrading from older versions, so you should verify the upgrade path before adopting it in a production workflow.

Who Should Adopt It, and What to Verify First

Basic Memory is a solid choice for individual developers who want a free, local-first memory layer for their AI assistants and are comfortable with Python and uv. If you are already using Claude Code or Cursor and you are tired of re-explaining your project, this tool can give you a persistent memory without a cloud dependency. You should not adopt it if you need mobile access or team collaboration without paying for the cloud. The local edition is not a drop-in solution for those needs. Before you commit, verify that the `--prerelease=allow` flag works on your platform, test that your AI client can connect via stdio or http, and check whether the FastMCP 4 pre-release causes any instability in your environment. The README does not provide a detailed troubleshooting guide, so be prepared to rely on the Discord community.

Editorial conclusion

Adopt Basic Memory if you want a free, local-first memory layer for Claude, Codex, or Cursor and you are comfortable with AGPL-3.0 and a Python/uv setup. Skip it if you need mobile access without paying for the cloud, or if pre-release dependencies and manual sync are unacceptable. Before committing, verify that the FastMCP 4 pre-release dependency works with your client, test the `--prerelease=allow` flag on your machine, and confirm that your workflow tolerates the lack of built-in cross-device sync in the local edition.

Official sources

1. Official documentation
2. Official README
3. Project repository
4. Release notes