lil memory

Your AI memory as a folder of Markdown files. Works with any model. No account, no cloud, no company in the middle.

lil memory is a small local MCP server. Every AI client you connect (Claude Desktop, Claude Code, and others) reads and writes the same memories. The memories are plain files in a folder you own, so you can read and edit them in Obsidian or any text editor.

Quickstart

You need uv. Then:

Create the vault at ~/lil-memory:
```
uvx lil-memory init
```
Connect a client (claude-desktop or claude-code):
```
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."

Open ~/lil-memory in Obsidian to see and edit your memories. Run lil-memory doctor if something does not work.

Usage

You do not call lil memory yourself; your AI client does. Just ask 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 old version is kept, marked as superseded.
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.

File format

One memory is one Markdown file. Its folder is its scope.

~/lil-memory/
├── global/prefers-british-spelling.md
├── projects/acme-site/deploys-to-cloudflare.md
└── .lil-memory/          # search index and trash; safe to delete the index

---
id: 01J9XK3M7Q2R8S5T6V7W8X9Y0Z
type: preference
status: active
tags:
  - writing
source: claude-desktop 1.0
created: 2026-10-05T09:12:00Z
updated: 2026-10-05T09:12:00Z
---
Prefers British spelling and short paragraphs in client-facing copy.

type is one of fact, preference, project, decision, note.
status is active, pending or superseded.
Updating a memory never overwrites it. The old file is marked superseded and links to the new one.
Forgetting a memory moves it to .lil-memory/trash/.
Fields you add yourself in Obsidian are kept.
The search index is a cache. Delete it any time; lil-memory reindex rebuilds it from the files.

The full format is in SPEC.md. Other tools can implement it without reading the code.

Tools

What the connected AI can use:

Name	What it does
`remember`	Save one memory. Also returns up to 3 similar existing memories.
`recall`	Full-text search over active memories, filtered by scope, type or tags.
`get`	Fetch one memory by id, title or path.
`update`	Replace a memory with new content; the old one is kept as superseded.
`forget`	Move a memory to the trash.
`list_scopes`	List folders with their number of memories.
`memory://profile`	Resource: all your global preferences, the "who is this user" card.
`load_context`	Prompt: your profile plus the latest memories in one scope.

CLI

lil-memory init [path]           create a vault (default ~/lil-memory)
lil-memory install <client>      add to claude-desktop or claude-code
lil-memory serve                 run the MCP server over stdio
lil-memory serve --http          run at a secret URL on 127.0.0.1 (--port, --rotate)
lil-memory reindex               rebuild the search index from the files
lil-memory doctor                check FTS5, the vault and client installs

Every command takes --vault PATH.

Security

Local by default. Claude Desktop and Claude Code start lil memory as a local process and talk to it over stdio. Nothing listens on the network.
Memories are untrusted input. Memories written by one AI are read by another, so stored text could try to give instructions. lil memory returns memories inside clearly marked <memory> blocks, labeled as data and not instructions. It never acts on their content itself.
Remote clients such as ChatGPT can only reach a server through an HTTPS URL, and cannot send a static token. So HTTP mode keeps things minimal: the URL itself is the secret. Use it with caution, because anyone who has the URL gets full access to your memories (see the trade-off below).

lil-memory serve --http                         # prints http://127.0.0.1:8765/mcp/<secret>
cloudflared tunnel --url http://127.0.0.1:8765  # or any other tunnel

In ChatGPT, turn on developer mode in the settings, then add https://<tunnel-host>/mcp/<secret> as a custom connector with no authentication.

The trade-off: anyone who has that URL can read, change and forget all of your memories. A URL leaks more easily than a password, for example through screenshots, shell history or the tunnel provider. OpenAI also stores it in your connector settings and sees every memory ChatGPT reads. HTTP mode only runs while you keep serve --http open. lil-memory serve --http --rotate replaces the secret, and the old URL stops working immediately. It is good practice to rotate the URL once in a while, and right away if you think it has leaked.

lil memory is MIT licensed.