Basic Memory — your assistant’s memory stays in files, not on someone else’s server
Basic Memory gives your assistant persistent memory stored as plain markdown files on your own disk, with links between notes. It is both a command-line tool and an MCP server, it works with Claude Code, Codex CLI, and Cursor, and it does not send your knowledge to any server. The price: AGPL licensing and a one-time model download on first use.

What it does
Seven articles in this column showed you tools that read your code. This eighth one shows something else: where to write down what you learned, so the next session does not start from zero.
Basic Memory is two things in one package. It is a command-line program you run to write notes. And it is an MCP server you connect to your assistant so it can write and read those notes on its own.
Two terms in plain language, because without them the rest of the article does not make sense.
MCP means “a protocol for connecting tools to an assistant.” Think of a socket. Your assistant has one slot, and any tool that fits that slot can give it new abilities. The MCP server is the device that plugs into the socket.
“Memory stays in markdown files” means something very specific. The notes do not live inside some database on the internet. They are text files with a .md extension, in a folder you choose, on your own disk. You can open them with any note app. You can see them with your own eyes. You can copy them with a backup. And if you stop using the tool tomorrow, the files are still there, yours, readable.
That is the difference from a service that keeps its knowledge on its own server. In that case, the knowledge stays behind an account. You trust it to someone else. You get it back only if they allow it, and only in the form they give you. Basic Memory turns that arrow around. The folder is yours, the format is plain text, and the assistant is just another reader passing through.
It also builds links between notes. You write [[Note]] inside one note, and the tool understands that one points to the other. That is how a knowledge web is built — not a pile of files, but a network you can walk through (repository).
What it does not do
You will need something else too: do not expect this to replace missing services and tools. It is not a cloud service. The files stay on your disk and do not sync automatically between machines. If you want sync or sharing, you will need your own git, rsync, or storage service. The .md files are plain text. It does not provide encryption or access control on its own. Do not use it to host sensitive data without extra security measures.
It is not a real-time collaboration system for many users. It does not do locking or transactional writes. If two clients write at the same time, you will run into conflicts and possible lost changes. It also does not automatically rebuild links when you rename files; wikilinks stay as you wrote them and you must fix them by hand.
It is neither a heavy-duty search engine nor an enterprise vector DB. Search has a known bug (total=0) and the embeddings model needs internet on first use. Do not ask Basic Memory to replace a full indexing, auditing, or realtime analytics system.
Who it is for
For anyone who is tired of explaining the same things to their assistant every time a new session opens.
It is useful if you work on a project for weeks and want the assistant to remember the decisions you made together. It is useful if you keep research notes and want to link them to each other. And it is useful if you simply do not want your knowledge sitting in someone else’s account.
It is not a tool for making code. It is a tool for remembering what you made.
Installation
The package is called basic-memory, lives on PyPI, and the latest stable release is 0.23.2. It requires Python 3.12 or newer, and its license is AGPL-3.0-or-later — I will explain what that means below, because it matters.
Install it with uv, from any folder you want:
uv tool install basic-memory
Then confirm it is installed:
basic-memory --version
It prints “Basic Memory version: 0.23.2”. We saw that on this machine.
If you do not want to install it at all, you can call it exactly the way a client calls it, without installation:
uvx basic-memory mcp
Use with each LLM
Basic Memory is an MCP server, so the connection looks similar in every program. What changes is where you put the setting. The command you give is the same everywhere: run uvx with basic-memory mcp.
Before that, one step you do not skip. Declare the folder that will hold the notes:
basic-memory project add notes "<path>/notes"
Put the path you actually want in place of
Claude Code
In Claude Code, the setting lives in a JSON file called .mcp.json, inside the project folder. The content is this:
{
"mcpServers": {
"basic-memory": {
"command": "uvx",
"args": ["basic-memory", "mcp"]
}
}
}
Then open Claude Code in the project folder. It will see the setting and connect the server. From there on, when you ask it to remember something, it will write the note into your folder.
Codex CLI
In Codex CLI, the setting is not JSON. It is written in a TOML file called config.toml, inside the .codex folder of your profile:
[mcp_servers.basic-memory]
command = "uvx"
args = ["basic-memory", "mcp"]
The command inside is exactly the same. Codex reads it in its own way, but the result does not change.
Cursor
In Cursor, the setting goes into a file called mcp.json, inside the .cursor folder of the project:
{
"mcpServers": {
"basic-memory": {
"command": "uvx",
"args": ["basic-memory", "mcp"]
}
}
}
Same shape as Claude Code, same command. Start Cursor and the server appears connected.
One honest note about the three cases above. We tested the server itself, through stdio, and saw that it answers correctly. We did not run all three clients from start to finish. The file locations are the standard ones for each program. If something does not work for you, start there.
Where it wins, where it loses
It wins at the most important point. Your memory is files you can see. It is not a box you press once and hope for the best. If the tool breaks tomorrow, the notes are still there, openable in any program.
It wins in how it links notes. Wikilinks like [[Note]] build a network, not a pile. And it wins because it is both CLI and MCP server: you can write a note by hand from the terminal, and the assistant can read it later.
It wins on health. The repository at github.com/basicmachines-co/basic-memory had 4,148 stars and 308 forks, with the latest update on October 12, 2026 — today. It is active, not archived. On PyPI it has 119 releases, and about 47,900 downloads per month.
Now the four points that hurt, stated plainly.
First, the license. It is AGPL-3.0, not MIT. In practice: if you embed this code in a closed product you sell, the license obliges you to give out your own code too. That is not a blocker. But it is an obligation you need to know before you use it in commercial work. For personal use, it does not touch you.
Second, the first write needs internet. The first time you write a note, the tool downloads an embeddings model from Hugging Face — five files, about 45 seconds, no account. After that it works locally. If you do not have network the first time, it does not start.
Third, a flaw in search. In the response, the total field in the JSON says 0, while the results are there in the list. It is a known issue. Do not use it as a count, because you will think it found nothing when it did.
Fourth, two version numbers in the same tool. The CLI says 0.23.2, the MCP server says 4.0.0b1. That confuses anyone who sees a “new version available” message. They are not two programs. They are the same thing, with two numbers.
Test
It really ran, on this machine, Windows 11, with uv and Python 3.14.7.
First came the install with uv tool install basic-memory. Then the check, which printed “Basic Memory version: 0.23.2”.
We set up a test project with its own notes folder:
basic-memory project add bmtest "<path>/notes"
And then we wrote a note with the tool:
basic-memory tool write-note --title "Demo Note" --folder "notes" --content "Smoke test. Links to [[Demo Note]]." --tags "smoke-test" --project bmtest
The response, verbatim:
{"title": "Demo Note", "permalink": "bmtest/notes/demo-note", "file_path": "notes/Demo Note.md", "action": "created"}
What that means. The word action is created, the file_path points to a .md file on disk, and the permalink gives the note a stable address inside the graph. We opened it, and it is a text file, with a heading at the top that keeps the title and tags. So the meaning of the tool showed itself to us directly; we did not infer it.
Then we tested the MCP server itself. We asked it over stdio what it is and what tools it offers. It replied that it is “Basic Memory”, version 4.0.0b1, with protocol 2025-06-18. And in its tool list I counted twenty-one — among them write_note, read_note, edit_note, move_note, delete_note, search_notes, build_context, recent_activity, list_directory, list_memory_projects, and three for schemas: schema_validate, schema_infer, and schema_diff.
To be honest about what did not happen. We did not test the server connection inside the three clients. We declared the folder, wrote a note, opened the file, and asked the server directly. The route through the Claude Code menu, the Codex menu, and Cursor we did not walk all the way through.
Verdict
Basic Memory does not give you new power. It gives you a place.
Its idea is so simple that it almost feels strange: your assistant’s memory is text files in a folder you choose, with .md at the end. There is no secret. And that is exactly why it is strong. What you build with it does not vanish if you change tools, does not vanish if the software breaks, and does not have to be asked back from anyone.
The objections are serious but clear. The AGPL license needs care in commercial use. The first write needs network once. Two version numbers are confusing. And a flaw in search makes you distrust the count.
None of that touches the core. If you want your assistant to remember, and you want the knowledge to stay yours, this is the tool.
Score: 8.6/10.
See also
Three more from the same category:
- openwiki: the repository wiki that writes and maintains itself
- graphify: the knowledge graph that answers about your repository without rereading it
- Docling: your documents in clean Markdown, with the structure kept in place
Sources:
https://pypi.org/project/basic-memory/
Εγκατάσταση
2 ΒΗΜΑΤΑ- uv tool install basic-memory
- uvx basic-memory mcp