Basic Memory: A Markdown-Based Memory Layer for AI Clients

What it does

Basic Memory is for people who want AI to retain project context, research notes, and decisions beyond a single chat. It stores knowledge as Markdown files and connects those files to clients such as Claude, Codex, Cursor, ChatGPT, and VS Code through the Model Context Protocol (MCP). Humans and AI can therefore build context around the same readable and editable files instead of keeping knowledge inside isolated conversations.

The project describes itself as local-first. In local mode, data remains on the user’s disk; cloud synchronization is optional. This file-based model may fit individuals, developers, researchers, and small teams already using Markdown or Obsidian. The README also calls the local path “air-gapped friendly,” but that wording is a project description, not a compatibility guarantee for every isolated environment.

Known capabilities

Basic Memory supports bidirectional writing, allowing humans and AI to update the same notes while synchronization keeps them aligned. Observations and wikilinks are used to form a knowledge graph, while semantic search retrieves notes by meaning rather than keywords alone. The README also describes optional cross-encoder reranking for vector and hybrid search results.

Its MCP documentation lists Claude Desktop, Claude Code, Codex, Cursor, VS Code, ChatGPT, and Obsidian among supported tools. The repository also contains a Claude Code plugin, shared skills, and integration directories for Hermes and OpenClaw. These integrations have different installation paths and dependencies, so “MCP support” should not be treated as proof that every client offers the same workflow.

The official v0.23.2 release, published on August 25, 2026, records an API fix for resolving note directories case-insensitively. This version detail comes from the official release page; adopters should still review the project’s changes when planning deployment.

Who it may suit

Basic Memory may suit users who want to turn AI conversations into durable project material, particularly those who prefer Markdown, want local file control, or need to reuse knowledge across MCP clients. Developers could keep project logs, architecture decisions, and learning notes in one knowledge base. Researchers and other knowledge workers may benefit from wikilinks and semantic retrieval.

The README also presents Basic Memory Teams as a shared cloud workspace. That is a hosted product path, however, and should not be assumed to represent the same operational model as local self-hosting.

Limits and deployment considerations

Start with the runtime requirements. The README’s badge specifies Python 3.12+, and its installation notes say Basic Memory 0.23 depends on a FastMCP 4 prerelease. Dependency resolution therefore deserves explicit testing; a conventional stable-dependency workflow should not be assumed to be confirmed compatible. The repository includes Docker Compose and PostgreSQL-related files, but the supplied sources do not establish complete deployment topologies, resource requirements, or production operating boundaries. Those details should be validated in a pilot.

Plan file management, synchronization, and recovery before rollout. The cloud path includes cross-device sync, snapshots, and backups. With the local path, users must choose their own approach, such as Git or Syncthing. Real-world behavior for concurrent edits, conflicts, mobile access, and offline operation cannot be inferred from the feature list alone.

Finally, review the license. Repository metadata and the README identify AGPL-3.0. Organizations that modify the software and provide it over a network should obtain a legal or open-source compliance review for their architecture. The project is open source, but its cloud offering has separate pricing; a free local installation still carries maintenance, operations, and backup costs.

Sources

• GitHub repository metadata
• Project README
• Official release
• Official project page

Sources checked: 2026-09-30