<p align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="docs/lil-memory-dark.svg">
    <img src="docs/lil-memory-light.svg" alt="lil memory" width="50%">
  </picture>
</p>

# 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](https://modelcontextprotocol.io) 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](https://obsidian.md) or any text editor.

## Quickstart

```sh
uvx lil-memory init                      # 1. create the vault at ~/lil-memory
uvx lil-memory install claude-desktop    # 2. connect a client (or: claude-code)
```

3. 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.

`lil-memory doctor` checks your setup. `lil-memory reindex` rebuilds the search index from the files. Use `--vault PATH` or `$LIL_MEMORY_VAULT` to keep the vault somewhere else.

## The format at a glance

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
```

```markdown
---
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.
```

- 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/`.
- The full format is in [docs/SPEC.md](docs/SPEC.md). Other tools can implement it without reading this code.

The connected AI exposes six tools: `remember`, `recall`, `get`, `update`, `forget` and `list_scopes`. It also has a `memory://profile` resource and a `load_context` prompt.

## 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 ChatGPT can't 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).

  ```sh
  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.

## License

MIT