# Basic Memory

MCP-native persistent memory over an Obsidian-compatible markdown folder, local and free or hosted.

Basic Memory gives Claude, Codex, Cursor, ChatGPT, and any MCP client a two-way knowledge base of markdown notes with a semantic graph. The MCP server is the primary interface; humans edit the same files in Obsidian or any editor. Local install is AGPL and free; the cloud edition hosts sync and the database for a seat price.

- Capabilities: adaptable, operable
- Vertical: notes-knowledge
- Shape: mcp-server
- Form factor: mcp-server
- Execution model: deterministic
- Provenance: mixed (recorded, never ranked)
- Repo: https://github.com/basicmachines-co/basic-memory (AGPL-3.0), 3841 stars, last commit 2026-09-02
- Last activity: 2026-09-02
- Page: apps/basicmachines-co--basic-memory.html
- JSON: apps/basicmachines-co--basic-memory.json

## Use it when

- you want Claude Code to remember decisions across sessions in files you can open in Obsidian
- your team wants one shared memory that both people and their agents write to

## Gotchas

- AGPL-3.0 for the local edition
- Install needs --prerelease=allow or you silently get an older release (README)
- Semantic search and reranker add model dependencies; off by default
- README describes one $15/mo plan; the pricing page lists Team $15/seat/mo and Business $30/seat/mo (SSO, audit logs), both per active seat

## Editions

- Free (local): Free, open source
  - source: https://github.com/basicmachines-co/basic-memory
  - installable: uv tool install basic-memory --prerelease=allow
  - container: https://github.com/basicmachines-co/basic-memory/blob/main/docker-compose.yml
- Team (cloud): $15 per month, closed source
  - hosted: https://basicmemory.com/pricing
- Business: $30 per month, closed source
  - hosted: https://basicmemory.com/pricing

## Adaptable: make it yours

Effort: config-only (18 things to edit)

~/.basic-memory/config.json holds projects and paths; BASIC_MEMORY_* env vars switch the database backend (BASIC_MEMORY_DATABASE_BACKEND, BASIC_MEMORY_DATABASE_URL), enable semantic search and a reranker, and force local or cloud routing. Prompt-level behavior lives in the Claude Code plugin under plugins/claude-code/ (skills/*/SKILL.md, output-styles/, hooks/).

- Env vars: BASIC_MEMORY_DATABASE_BACKEND, BASIC_MEMORY_DATABASE_URL, BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED, BASIC_MEMORY_RERANKER_ENABLED, BASIC_MEMORY_RERANKER_PROVIDER, BASIC_MEMORY_RERANKER_MODEL, BASIC_MEMORY_LOG_LEVEL, BASIC_MEMORY_FORCE_LOCAL, BASIC_MEMORY_FORCE_CLOUD, BASIC_MEMORY_CLOUD_MODE, BASIC_MEMORY_IMPORT_UPLOAD_MAX_BYTES, BASIC_MEMORY_NO_PROMOS
- Config files: ~/.basic-memory/config.json, .env, docker-compose.yml
- Prompt files: plugins/claude-code/skills/*/SKILL.md, plugins/claude-code/output-styles/basic-memory.md, plugins/claude-code/
- Accounts you'll need: Basic Memory account (cloud editions only)

## Operable: what an agent can drive

Operability: native. Interface: mcp at https://github.com/basicmachines-co/basic-memory (published by the builder, both).

### Reach (partial coverage)

- Write, read, edit, and move notes: reachable. README tools: write_note, read_note, edit_note, move_note
- Search notes: reachable. search_notes; optional semantic search and reranker enabled by BASIC_MEMORY_SEMANTIC_SEARCH_ENABLED
- Recent activity and directory listing: reachable. recent_activity, list_directory
- Navigate the knowledge graph: reachable. build_context navigates memory:// URLs
- Multiple projects: reachable. README and triage: project paths in config.json; project switching tools
- Cross-device sync: reachable. cloud edition only; local is manual (git, Syncthing)
- Import chat exports: undetermined. BASIC_MEMORY_IMPORT_UPLOAD_MAX_BYTES suggests an import path; not verified as a tool
- Automatic context on every prompt: reachable. plugins/claude-code/hooks/session_start.py and pre_compact.py plus skills/bm-*/SKILL.md call the MCP server

## Code stack

- Languages: Python
- Frameworks: FastMCP, SQLAlchemy
- Package manager: uv
- Database: SQLite, PostgreSQL, Milvus
- Hosting target: local, docker

## Model stack

- Providers: any MCP client
- Models: none
- Keys you need (names only): none
- Prompts live in: plugins/claude-code/skills/*/SKILL.md, plugins/claude-code/
- Tools: write_note, read_note, edit_note, move_note, search_notes, recent_activity, list_directory, build_context

## Skills

bundled: Ships a set of memory-* skills and a Claude Code plugin that drive the MCP server; a separate .agents/skills/ tree is contributor tooling.
- Paths: skills/memory-*/SKILL.md, plugins/claude-code/.claude-plugin/, skills-lock.json
- Install: npx skills add basicmachines-co/basic-memory/skills

## Evidence and confidence

- formFactor: README: MCP-native; installed as a uv tool and registered with MCP clients (confidence 0.95)
- executionModel: server stores and searches files; the model is the client; embeddings optional (confidence 0.75)
- operability: MCP is the primary interface by design; published by basicmachines-co (confidence 0.95)
- effort: README and .env.example name BASIC_MEMORY_* vars and ~/.basic-memory/config.json (confidence 0.85)
- editions: basicmemory.com/pricing: Team $15/seat/mo, Business $30/seat/mo; local AGPL free (confidence 0.8)
- active: pushedAt 2026-09-02
- provenance: CLAUDE.md and AGENTS.md at root; no statement on authorship (confidence 0.3)
- reach:  (confidence 0.8)

## Open questions

- Full MCP tool list including project and canvas tools (docs.basicmemory.com landing page did not list them)
- Is there an import tool for chat exports, or is import CLI-only?

## Sources

- https://github.com/basicmachines-co/basic-memory (sourcing:notes-knowledge:curated)
- https://basicmemory.com/pricing (analysis)