Purpose
Basic Memory solves the problem of "AI forgetting as soon as the conversation ends." It saves knowledge as Markdown files on disk, which both humans and AI can read, write, and search, thereby allowing AI to continue context across different sessions without having to repeatedly explain the project background.
Main Capabilities
- Local-first: Knowledge is stored on disk as plain-text Markdown, under the user's control; no server is needed, only a local SQLite index.
- Two-way read/write: Humans and AI write to the same set of files, staying synchronized and consistent; they can be edited directly in editors such as Obsidian and VS Code.
- A real knowledge graph: Each file is an Entity, containing Observations (facts) and Relations (wikilink relationships), and can be traversed link by link.
- Semantic search: Find notes by meaning rather than only keywords, using hybrid full-text + vector ranking with FastEmbed embeddings, supporting SQLite or Postgres; optional cross-encoder reranking improves the quality of vector and hybrid results.
- MCP-native: Compatible with mainstream AI clients and IDEs; each tool carries behavior hints (read-only, destructive, idempotent, open-world), making it easy for agents to progressively discover tools as needed.
- Optional cloud: Cross-device sync, snapshot backups, and team-shared workspaces; not required.
How to Use
There are two paths, using the same product and the same set of Markdown:
Cloud: After signing up, connect an AI client, and it can be used in the browser, on mobile, and on desktop, with built-in cross-device sync, while hosting, backups, and snapshots are handled by the service provider. The official list price is $15.00/month (locked for life), with an additional annual plan at $12.50/month; a 7-day free trial is provided. Open-source users can use code BMFOSS to get an additional 20% discount for 3 months (about $11.40/month). Prices for sign-ups during the Beta period remain unchanged as long as the subscription is maintained. The team edition, Basic Memory Teams, supports a single shared cloud workspace, enabling real-time collaborative editing and human/agent handoff, at the same price, increasing per user.
Local: After installation, configure an AI client and it can run. Free (AGPL-3.0), with data on the local disk, suitable for isolated environments; requires Python (via uv). Note: Basic Memory 0.23 depends on the FastMCP 4 pre-releaseversion,uv and will only accept pre-release versions of transitive dependencies when using --prerelease=allow , otherwise it will silently install an older version; all uvx / uv tool upgrade commands need to include that flag.
Client configuration: For Claude Desktop, edit ~/Library/Application Support/Claude/claude_desktop_config.json and restart; notes are located by default at ~/basic-memory; for Codex, add to ~/.codex/config.toml, and you can keep the default MCP approval behavior, or pre-approve eligible Basic Memory tools (writes, edits, and deletions with destructive annotations still require approval); for Cursor, add .cursor/mcp.json(project) or ~/.cursor/mcp.json(global); for ChatGPT, add it in user settings (JSON); Basic Memory provides OpenAI-compatible search and fetch tools for Custom GPT actions.
Official agent package: The repository is also the host-native agent package source for Basic Memory, with the core Python package, Claude Code plugin, shared skills, Hermes plugin, and OpenClaw plugin released from the same source. The Claude Code plugin provides session-start briefings, pre-compaction checkpoints, an optional capture output style, and the /basic-memory:bm-setup、:remember、:share、:status command, and requires connecting to the MCP server first; the installation command registers the marketplace and installs the plugin, and you can use --scope project to declare it for the team, or --dry-run to preview. The framework-agnostic SKILL.md is located at skills/; Claude and ChatGPT can upload the corresponding zip. The Hermes plugin is located at integrations/hermes, and the mcp package must also be added to the Hermes virtual environment; OpenClaw is located at integrations/openclaw.
Markdown format: each file is an Entity, Observations are separated by [方括号] categories,# tags, optional context in parentheses; Relations are wiki-style links, relation types are a single token or a quoted multi-word phrase.- [[Target]] and in the text [[Target]] are both indexed as links_to.
MCP tools (all default to text output, can pass output_format="json"): content-type write_note、read_note、edit_note、move_note、delete_note、read_content、view_note; search and discovery search_notes、recent_activity、list_directory; knowledge graph build_context(navigate memory:// URLs); project list_memory_projects、list_workspaces、create_memory_project、delete_project; schema schema_infer、schema_validate、schema_diff; compatibility and diagnostics search、fetch、basic_memory_diagnostics.
Other features: auto-update (uv tool and Homebrew installations check and silently update every 24 hours, uvx skips;bm update manually checks and applies,bm update --check only checks, can be disabled in ~/.basic-memory/config.json ); optional cross-encoder reranking (off by default, default model jinaai/jina-reranker-v1-tiny-en, hosted rerankers can also be used via LiteLLM, fails fast on invalid configuration with no silent fallback); schema system; per-project cloud routing (bm project set-cloud); smarter edits (edit_note 's append/prepend automatically creates the note if missing,write_note prevents accidental overwrites); richer search results include matching text chunks.
Use cases
- Let MCP clients such as Claude, Codex, Cursor, and ChatGPT remember project context across multiple sessions.
- Maintain a knowledge base in editors such as Obsidian while letting AI read and write the same files.
- Teams share a single knowledge space, with humans and agents handing off work.
- Users who need an offline or isolated environment use the local version.
- Users who need inference, validation, and diff analysis of knowledge base structure.
Limitations and caveats
The cloud version is a paid subscription ($15.00/month, $12.50/month billed annually, includes a 7-day free trial); the team version is the same price but increases per user; the local version is free but requires Python and uv, and must use --prerelease=allow. Reranking is off by default; the local provider needs to download the model on first run and adds inference latency. Telemetry collects minimal anonymous events (cloud promotion exposure, login attempts and results, promotion opt-outs); it does not collect file contents, note titles, knowledge base data, PII, IP addresses, or per-command/per-tool tracking; events are sent to Umami Cloud, the background thread does not block the CLI, and it can be disabled in configuration. Logging uses Loguru, and the default log file is ~/.basic-memory/basic-memory.log(10MB rotation, retained for 10 days). The official docs mention that Postgres deployments storing semantic vectors in Milvus require installing the first-party optional extra. The remaining installation details, specific command-line contents, and some configuration items are not fully provided in the materials.
