Basic Memory
A knowledge base of plain Markdown files that you and your AI both read and write, through MCP.
by Basic Machines · Built this? Edit this page on GitHub
In short
Basic Memory keeps memory as Markdown files in a folder on your machine. Your AI writes and edits notes through MCP tools, usually when you ask it to. Each note is about one thing and holds short facts ("observations") and links to other notes. A local SQLite index makes the notes searchable by keywords and by meaning. When the AI asks for a note's context, the linked notes come with it. You can open and edit the same files yourself, for example in Obsidian. An optional Claude Code plugin adds a short briefing at the start of each session and saves a checkpoint note before the chat is compacted. A paid cloud version hosts the same files.
Who it’s for
People who use Claude, Codex, Cursor or another MCP client and want a lasting knowledge base they can read and edit themselves. Also teams who share one through the paid cloud.
What it remembers
Whatever you or the AI choose to write down: notes on projects, people, decisions, tasks and topics, each with facts, tags and links to other notes. Facts can carry dates saying when they held. The Claude Code plugin also saves session checkpoints.
- Memory lives
- Your machine (Markdown files and a SQLite index); optional paid cloud
- API keys
- None for local use; a subscription for the cloud
- Works with
- Claude Desktop, Claude Code, Codex, Cursor, VS Code, ChatGPT, Obsidian, Any MCP client
- License
- Open sourceAGPL-3.0
- Price
- Free to run yourself; cloud $15/mo during beta (regular price $19), with a 7-day free trial
Under the hood
- Who writes memories
- The AI you talk to, through write and edit tools, usually when asked. You can also edit the files by hand. The Claude Code plugin saves a checkpoint note, cut from the transcript with no AI call, before compaction.
- Where they're kept
- Markdown files in a folder on your machine (~/basic-memory by default), indexed in SQLite. Postgres is an option, and the cloud version hosts the files for you.
- How they're found
- By keywords, by meaning with local embeddings, or both, with filters for type, tags, dates and metadata. A context tool returns a note with the notes it links to, several steps out.
- Extra AI calls
- None by default: embeddings run locally. An optional reranker can call a hosted model through LiteLLM.
How it works
- 1You talkYou ask your AI to note something, or edit a file yourself.
- 2Write a noteA Markdown file with facts and links to other notes.
- 3IndexSQLite indexes the text and its meaning on your machine.
- 4FindSearch by keywords or meaning, then follow links for context.
What stands out
- The memory is plain Markdown on your disk. You can read, edit, move or back it up with any editor, and the AI sees your changes.
- Notes link to each other, and the context tool walks those links several steps out.
- Facts can say when they held (for example "effective from June 10 until July 27"), and search can ask what was true on a given date.
- The same tools work with many MCP clients, with plugins for Claude Code, Codex, Hermes and OpenClaw.
What it doesn’t do
- Notes are mostly written when you or the AI decide to. Nothing watches the conversation and takes notes on its own, except the Claude Code plugin's checkpoint before compaction.
- Nothing fades, and using a note doesn't make it stronger. Old notes stay as they are until someone edits or deletes them.
- Nothing reworks notes between sessions on its own. The reflect and defrag skills do this only when you or your agent run them.
- Editing a note on your machine overwrites the file; there is no built-in history. Keeping an old fact means writing a date range on it. Snapshots are a cloud feature.
- No emotional weighting, and no beliefs held with a level of certainty.
- Licensed AGPL-3.0. The installed command-line tool sends anonymous events about the cloud offer (promo views, sign-in attempts) unless you set BASIC_MEMORY_NO_PROMOS=1, and it updates itself every 24 hours by default.
Measured against human memory
1 built, 8 partly, 2 not of the Field Guide’s 11 mechanisms
Encoding
Salience
Decides what's worth keeping, and how much, as a memory is written.
The AI decides what to write, usually when asked. The Claude Code plugin's opt-in output style gives it rules: capture real decisions, skip routine chatter. There's no importance score. source
Emotion
Gives memories written with feeling more weight.
No emotional weighting. Nothing in the code reads or records feeling.
Storage
Forgetting
Lets unused memories fade over time on its own.
Nothing fades note by note. The Claude Code plugin's session briefing only lists sessions from the last 3 days by default, and older notes stay searchable as they are. source
Interference
When a new memory closely matches an old one, notices and lets the newer one win.
Nothing spots a new note that clashes with an old one. The defrag skill tells an agent to look for contradictions and duplicates, but only when you run it. source
Retrieval
Retrieval
Remembering something makes that memory stronger.
Finding or reading a note doesn't strengthen it. Nothing counts how often a note is used.
Association
Links memories, so recalling one brings its neighbours.
Notes link to each other with typed wikilinks, and the context tool returns a note with the notes it links to, several steps out, nearest first. Links carry no weights. source
Prospective
Brings a memory back at the right time without being asked.
With the Claude Code plugin, each session starts with a briefing listing active tasks, open decisions and recent sessions. That only happens at session start, and dated items don't come back on their date. source
Transformation
Consolidation
Reworks memories between sessions: strengthening, merging, reorganising.
A reflect skill tells an agent to review recent notes and fold what lasts into the notes it belongs in. It runs only when you or your agent start it; nothing schedules it. source
Reconsolidation
Corrects a memory when it's contradicted, and keeps what it used to say.
A fact can carry the dates it held, so a replaced decision can stay in the note with its range closed, and search can ask what was true on a date. The writer has to do this; an ordinary edit overwrites the old text. source
Gist
Turns many specific moments into general knowledge.
The reflect skill tells an agent to pull lasting decisions, lessons and preferences out of meeting notes and logs into durable notes. It runs only when started. source
Schemas
Forms beliefs about people and projects, and weighs new facts against them.
Each note is about one thing (a person, a project, a topic) and holds its facts and links, so there's a kept page per subject. Nothing weighs new facts against it; the AI or you edit it. source
Not every system is trying to be a human memory, so a hollow dot isn’t a flaw. It just says what the system doesn’t do. What the mechanisms are.
Basic Memory’s makers haven’t shared what they’re building next, so only today shows here. Makers can add their roadmap the same way they correct an entry.
Compare Basic Memory with the others, side by sideQuestions
- Who is Basic Memory for?
People who use Claude, Codex, Cursor or another MCP client and want a lasting knowledge base they can read and edit themselves. Also teams who share one through the paid cloud.
- Where does Basic Memory keep its memories?
Your machine (Markdown files and a SQLite index); optional paid cloud. Markdown files in a folder on your machine (~/basic-memory by default), indexed in SQLite. Postgres is an option, and the cloud version hosts the files for you.
- Does Basic Memory forget?
Forgetting: a little. Nothing fades note by note. The Claude Code plugin's session briefing only lists sessions from the last 3 days by default, and older notes stay searchable as they are. source
- Does Basic Memory correct a memory when it turns out to be wrong?
Reconsolidation: a little. A fact can carry the dates it held, so a replaced decision can stay in the note with its range closed, and search can ask what was true on a date. The writer has to do this; an ordinary edit overwrites the old text. source
- Is Basic Memory open source?
Yes, it's open source. License: AGPL-3.0. Code: github.com/basicmachines-co/basic-memory.
- Does Basic Memory work with Claude Code?
Yes. Works with: Claude Desktop, Claude Code, Codex, Cursor, VS Code, ChatGPT, Obsidian, Any MCP client.
- Does Basic Memory need an API key?
API keys: None for local use; a subscription for the cloud.
- How much does Basic Memory cost?
Price: Free to run yourself; cloud $15/mo during beta (regular price $19), with a 7-day free trial.