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.
- 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
- 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
Last activity Sep 2, 2026. Fit: adaptable 2, operable 3.
Editions
Free (local) · Free open source
- Clone
git clone https://github.com/basicmachines-co/basic-memory - Install
uv tool install basic-memory --prerelease=allow - ImageContainer
Team (cloud) · $15 per month closed source
- HostedOpen the hosted app
Business · $30 per month closed source
- HostedOpen the hosted app
Adaptable: what is yours to change
Make it yours
Config only18 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_BACKENDBASIC_MEMORY_DATABASE_URLBASIC_MEMORY_SEMANTIC_SEARCH_ENABLEDBASIC_MEMORY_RERANKER_ENABLEDBASIC_MEMORY_RERANKER_PROVIDERBASIC_MEMORY_RERANKER_MODELBASIC_MEMORY_LOG_LEVELBASIC_MEMORY_FORCE_LOCALBASIC_MEMORY_FORCE_CLOUDBASIC_MEMORY_CLOUD_MODEBASIC_MEMORY_IMPORT_UPLOAD_MAX_BYTESBASIC_MEMORY_NO_PROMOS- Config files
~/.basic-memory/config.json.envdocker-compose.yml- Prompt files
plugins/claude-code/skills/*/SKILL.mdplugins/claude-code/output-styles/basic-memory.mdplugins/claude-code/- Accounts you need
- Basic Memory account (cloud editions only)
Source
- github.com/basicmachines-co/basic-memory
- AGPL-3.0 license
- Last commit Sep 2, 2026
- 3,841 stars
Operable: what an agent can drive
Interface
NativeMCP serverpublished by the builderremote or local
How an agent can drive an Operable Listing, in five levels: native (built for the agent as the primary interface), official (the Builder ships an agent interface), wrapped (a third party wraps the software's API), config (an agent can only drive it by editing files), gui (screen control only). An interface is official only when it is published by the same organization that ships the software. GUI-level Listings are allowed and sorted last.
- Docs
- github.com/basicmachines-co/basic-memory
- Tools
write_noteread_noteedit_notemove_notesearch_notesrecent_activitylist_directorybuild_context
Reach
Partial coverage. 7 of 8 jobs reachable through the stated interface.
| Job | Through the interface | Evidence |
|---|---|---|
| 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
- FastMCPSQLAlchemy
- Package manager
- uv
- Database
- SQLitePostgreSQLMilvus
- Hosting target
- localdocker
- Built
- Mixed (recorded, never ranked)
Model stack
- Providers
- any MCP client
- Models
- none
- Keys you need
- none
- Prompts live in
plugins/claude-code/skills/*/SKILL.mdplugins/claude-code/
Skills
Ships a set of memory-* skills and a Claude Code plugin that drive the MCP server; a separate .agents/skills/ tree is contributor tooling.
- Kind
- bundled
- Paths
skills/memory-*/SKILL.mdplugins/claude-code/.claude-plugin/skills-lock.json- Install
npx skills add basicmachines-co/basic-memory/skills
Evidence and confidence
| Field | Where it was seen | Confidence |
|---|---|---|
| formFactor | README: MCP-native; installed as a uv tool and registered with MCP clients | 95% |
| executionModel | server stores and searches files; the model is the client; embeddings optional | 75% |
| operability | MCP is the primary interface by design; published by basicmachines-co | 95% |
| effort | README and .env.example name BASIC_MEMORY_* vars and ~/.basic-memory/config.json | 85% |
| editions | basicmemory.com/pricing: Team $15/seat/mo, Business $30/seat/mo; local AGPL free | 80% |
| active | pushedAt 2026-09-02 | – |
| provenance | CLAUDE.md and AGENTS.md at root; no statement on authorship | 30% |
| reach | 80% |
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
- github.com/basicmachines-co/basic-memory sourcing:notes-knowledge:curated
- basicmemory.com/pricing analysis