Why lil memory
Most people now use more than one AI: Claude in the morning, a coding agent in the afternoon, ChatGPT on the go. Each one keeps its own memory, on its own company's servers, and none of them knows what the others learned. lil memory is one memory that all of them share, and it lives with you.
- Yours, as plain files. One Markdown file per memory, in a folder you own. Read it, edit it, search it, sync it or put it in git. There is nothing to export and nothing to be locked into.
- Every AI, the same memory. Claude Desktop, Claude Code, Codex, ChatGPT and any other MCP client can use it at the same time. Tell one of them something and the others know it too.
- Obsidian is the interface. Memories are linked notes. Browse the graph, fix a memory by hand, and your AI sees the change within two seconds.
- Small and boring on purpose. One small Python program with two dependencies. No account, no cloud, no API keys, no background service and no AI model of its own. The whole core is about 1,250 lines of code you can read in an afternoon. It starts in under half a second and searches 10,000 memories in about 10 ms.
- An open format. The file format is written down in SPEC.md, so other tools can read and write your memories, and they outlive this project.
How it compares
| Where your memory lives | Shared across AIs | Edit by hand | What you need | |
|---|---|---|---|---|
| Built-in memory (ChatGPT, Claude, Gemini) | The provider's servers | No. Each keeps its own; imports are one-time copies that drift apart | In that app's settings | Nothing |
| Hosted memory services | The service's cloud | Yes, through their API or MCP | In their dashboard | An account and an API key |
| Self-hosted memory stacks, such as OpenMemory | Databases on your machine | Yes, through MCP | In a web UI | Docker, Postgres, a vector database and an LLM API key |
| The reference MCP memory server | One JSON Lines file on your machine | Yes, through MCP | Possible, but it is a graph stored as JSON | Node.js |
| Basic Memory | Markdown files on your machine | Yes, through MCP | Yes, in Obsidian or any editor | A Python program (AGPL), with optional cloud sync |
| lil memory | Markdown files on your machine | Yes, through MCP | Yes, in Obsidian or any editor | One small Python program (MIT) |
lil memory and Basic Memory
Basic Memory is the closest relative: Markdown files, Obsidian, MCP. But it is a full knowledge-management platform, with semantic search, schemas, projects, workspaces and a paid cloud. lil memory is only the memory, and you can feel the difference:
| lil memory | Basic Memory | |
|---|---|---|
| Installed size | 28 MB | 383 MB |
| Packages installed | 31 | 167 |
| Direct dependencies | 2 | 42 |
| Lines of code | about 1,250 | about 89,000 |
| Server ready to use | 0.4 s | 3.2 to 4.6 s |
| Save a memory | 4 ms | 95 ms |
| Search | 3 ms | 22 ms |
| Tools the AI has to read on every request | 6 (about 1,200 tokens) | 21 (about 11,000 tokens) |
| License | MIT | AGPL |
- Light enough to forget about. A thirteenth of the disk space and a fifth of the packages. No database drivers, no AI libraries, no web framework.
- Code you can actually read. About 1,250 lines, seventy times less. It holds what your AI knows about you; you should be able to see everything that touches it.
- Instant. Ready in under half a second, about 9 times sooner. Saves about 20 times faster and searches about 7 times faster.
- Leaves room for your conversation. Every connected tool is described to the AI on every request. lil memory costs about 1,200 tokens of that; Basic Memory about 11,000. Six clear tools are also easier for a model to pick from than 21.
- Nothing to run or look after. No projects or workspaces to set up, no database migrations, no file watcher, no automatic updater, no prerelease flags. The search index is a cache: delete it and it rebuilds.
- Made to be used, not managed. It tells every connected AI to save what it learns about you on its own and to use it silently, and it is tested with several AIs writing to the same memory at once.
- Yours to build on. MIT, not AGPL. Use it, change it or ship it inside your own product, no strings attached.
Measured on 2026-10-09 on one MacBook at the same moment: Basic Memory 0.23.2 with default settings and lil memory 0.1, each installed in a clean Python 3.12 environment and driven over MCP the way an AI client does, with 200 notes each. Times are medians. Exact numbers vary by machine; the ratios are the point.
When something else fits better
- You only use one AI and are happy with it. Its built-in memory is less work.
- You need search by meaning rather than by words, schemas, or a hosted cloud with web and phone apps. Basic Memory has all three.
- You want one memory for a whole team. lil memory is built for one person.
Quickstart
You need uv. Then:
- Create the vault at
~/lil-memory:uvx lil-memory init
- Connect a client (
claude-desktop,claude-codeorcodex; for others see Connect your AI):uvx lil-memory install claude-desktop
- Restart the client and talk to it:
- "Remember that I prefer British spelling."
- "Load my context for acme-site."
Run lil-memory open to explore and edit your memories in Obsidian.
The first time, Obsidian asks you to pick the vault folder once ("Open folder as vault"); after that the command goes straight there.
Without Obsidian, it opens the folder in your file manager.
Run lil-memory doctor if something does not work.
Usage
Most of the time you do nothing. lil memory tells every connected AI to treat it as its own memory, and to use it constantly and silently:
- When you start a conversation or a task, it looks up what it knows about you and the project, and simply uses it, as if it had always known.
- Whenever you reveal something about yourself that could matter later, it saves it right away: likes and dislikes, interests, your work and tools, habits, goals, the people in your life, corrections and decisions. "I don't like that, keep it shorter", "we use pnpm here" or "I just moved to Stockholm" each become a memory.
- It never talks about its memory. Say "I like nature" and it saves that, then simply talks about nature with you. Your client still shows the tool calls.
- Ask "what do you remember about me?" or "why did you suggest that?" and it tells you which memories it used. Say "forget that" if it got something wrong.
- Each memory gets a short, descriptive title and is linked to related memories, like notes in Obsidian.
Say "my favorite team are the 49ers" and later "my favorite player is George Kittle": you get
favorite-nfl-team.mdandfavorite-football-player.md, linked to each other in Obsidian's graph. - It keeps one note per subject and grows it over time instead of making copies. People, places and other things you mention get a note each, gathered by a hub note:
talk about your favorite designers and you get
favorite-designers.mdlinking todieter-rams.mdandjony-ive.md. - Notes are written like a Zettelkasten: one idea each, in clear words, with the context the AI can be sure of, not a copy of what you typed.
- Projects are notes too, and the AI keeps them on its own. When you work on something ongoing, a codebase, a client, a thesis or a trip, it creates that project's note the first time
and keeps its goal and current state up to date.
acme-site.mdlinks every note about the project and they link back to it, so "load my context for acme-site" brings all of it back. - Coding agents such as Claude Code start lil memory inside the repository you are working in, so they file that work under a note named after the repository. Every agent that works on the same repository shares one project note.
- It does not save one-off requests, temporary details, its own guesses, or secrets such as passwords and keys.
The AI decides when to save; lil memory never reads your conversations itself.
Most clients follow these instructions. If yours does not, add this line to its instruction file,
such as CLAUDE.md or AGENTS.md:
Use the lil-memory tools on your own: recall my preferences and the current project when a task starts, and remember preferences, corrections and decisions as soon as I state them.
You can also ask directly, in plain words:
- Save something: "Remember that the acme-site deploys to Cloudflare."
- Find something: "What do you know about my writing preferences?"
- Pick up where you left off: "Load my context for acme-site." This loads your profile plus the latest memories for that project.
- Change something: "Update that memory: we now deploy to Fly." The note is edited in place.
- Remove something: "Forget the memory about my old address." It moves to the trash and can be restored by hand.
Edits you make in Obsidian show up in searches within about 2 seconds.
To keep the vault somewhere else, pass --vault PATH or set $LIL_MEMORY_VAULT.
lil memory is MIT licensed.