Connect your AI

Claude Desktop and Claude Code

lil-memory install claude-desktop
lil-memory install claude-code

Each command adds lil memory to that client's config, keeps every other server, and saves a backup of the old file next to it. Restart the client afterwards.

Codex

lil-memory install codex

This adds a [mcp_servers.lil-memory] table to ~/.codex/config.toml (or $CODEX_HOME/config.toml), keeping your other settings and comments, with a backup next to it. The Codex CLI and IDE extension read this file, and so does the ChatGPT desktop app, which runs Codex. Restart them afterwards, then check with codex mcp list.

Codex does not show an MCP server's own instructions to the model, so it would not know to save memories unprompted. install codex therefore also adds a short, clearly marked lil memory block to your global ~/.codex/AGENTS.md, which Codex reads in every session. The rest of that file is left alone, and running the command again only refreshes the block.

ChatGPT (web)

ChatGPT runs in the cloud, so it cannot start a program on your computer. It needs an HTTPS URL instead. Read Security first: anyone with that URL has full access to your memories.

1. Start HTTP mode. It prints a local URL ending in /mcp/<secret>:

   lil-memory serve --http

2. Put a tunnel in front of it, in a second terminal:

   cloudflared tunnel --url http://127.0.0.1:8765

   This prints a public https://... host. It changes every time the tunnel restarts; for a fixed one, see Run it all the time.
3. In ChatGPT, turn on developer mode. Where the switch is, and whether you have it, depends on your plan; see OpenAI's help article on developer mode.
4. Print the address to paste, using the host from step 2 (on a Mac, | pbcopy puts it on your clipboard):

   lil-memory url --tunnel abc-def.trycloudflare.com

   It prints https://abc-def.trycloudflare.com/mcp/<secret>.
5. Add a custom connector (OpenAI also calls these apps) with that address and no authentication.
6. Turn the connector on in a chat and say "Load my context for acme-site."

On some plans ChatGPT only allows tools that read. Then it can use recall and get, but not remember, update or forget.

Any other MCP client

Most local clients (IDEs, CLI agents, desktop apps) start MCP servers the same way: a command plus arguments. Point yours at the lil-memory program and the serve command. Many use this JSON shape:

{
  "mcpServers": {
    "lil-memory": {
      "command": "/Users/you/.local/bin/lil-memory",
      "args": ["serve"]
    }
  }
}

• Use the full path from which lil-memory. Apps opened from the Dock or Start menu often do not see your shell's PATH.
• Add "--vault", "/path/to/vault" to args if your vault is not at ~/lil-memory.
• Look up where your client keeps this config in its own docs; the key is sometimes called servers or context_servers instead of mcpServers.
• If a client only accepts a URL, run lil-memory serve --http and give it the address lil-memory url prints. A client on the same machine needs no tunnel.

Run it all the time

Local clients need nothing. Claude Desktop, Claude Code and other local clients start lil memory themselves whenever they need it and stop it when they quit. There is no server to keep running.

Only HTTP mode (ChatGPT) needs a process that stays up, plus a tunnel in front of it. Two ways to set that up:

• On your laptop. Simple, but ChatGPT cannot reach your memories while the laptop sleeps or is closed.
• On an always-on machine, such as a Mac mini or a small Linux box. ChatGPT can reach it at any time. On a Mac, turn on "Prevent automatic sleeping when the display is off" in System Settings.

macOS: a launchd agent

Save this as ~/Library/LaunchAgents/lil-memory.plist. Replace the first path with the output of which uvx, and add <string>--vault</string><string>/path/to/vault</string> if your vault is not at ~/lil-memory.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>lil-memory</string>
  <key>ProgramArguments</key>
  <array>
    <string>/Users/YOU/.local/bin/uvx</string>
    <string>lil-memory</string>
    <string>serve</string>
    <string>--http</string>
  </array>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
</dict>
</plist>

launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/lil-memory.plist   # start now and at every login
launchctl bootout gui/$(id -u)/lil-memory                                  # stop it

Linux: a systemd user service

Save this as ~/.config/systemd/user/lil-memory.service:

[Unit]
Description=lil memory (HTTP mode)

[Service]
ExecStart=%h/.local/bin/uvx lil-memory serve --http
Restart=on-failure

[Install]
WantedBy=default.target

systemctl --user enable --now lil-memory   # start now and at every login
loginctl enable-linger $USER                # keep it running without anyone logged in

The URL and the tunnel

The secret URL stays the same across restarts. lil-memory url prints it at any time, even while the server is not running; add --tunnel <host> for the public address.

A quick tunnel (cloudflared tunnel --url ...) gets a new random hostname every time it starts, which breaks the ChatGPT connector. For a setup that runs all the time, use a tunnel with a fixed hostname, such as Tailscale Funnel or a named Cloudflare tunnel, and run it as a service too. Both tools can install themselves as one. Everything in Security still applies.

Using the same vault on several machines

Sync the vault folder with Syncthing, iCloud Drive, Dropbox or git, and run lil memory on each machine. This is safe because the search index lives in each machine's cache folder, outside the vault. Two things to know:

• Keep .lil-memory/http-secret out of sync, for example with an ignore rule. Each machine that serves HTTP gets its own secret.
• If two machines change the same memory before syncing, your sync tool keeps both versions as a conflict copy. Nothing is lost, but you may need to tidy up by hand.

Security

• Local by default. Claude Desktop, Claude Code, Codex and other local clients 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).

The setup steps are under Connect your AI → ChatGPT.

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.