Memoreei

Remember every conversation you've ever had.

Memoreei is an open-source MCP server that gives your AI assistant a searchable memory of your messages: iMessage, WhatsApp, Signal, Discord, Telegram, Slack, Gmail, Instagram and more. It keeps them in one SQLite file on your machine and searches them by keyword and by meaning at once.

"What's my friend's favorite restaurant?"
"What did my sister say she wanted for her birthday?"
"How many times have I asked Dory to send that link again?"

Every assistant starts each conversation knowing nothing about you. With Memoreei, it can look.

• Local-first. One SQLite file. The default search model runs offline.
• Hybrid search. BM25 keywords and vector similarity, fused with Reciprocal Rank Fusion.
• On your network. One always-on machine serves every other one, each client with its own key.
• Read-only to the network. A key can search what's stored, never add to it or read a file.

Install

Pick one. Each is the whole server; they differ in how it's packaged.

Everything Memoreei knows lives in one home directory: config.env for settings and credentials, memoreei.db for the memories. That's ~/Library/Application Support/Memoreei on macOS, ~/.local/share/memoreei on Linux and ~/.memoreei elsewhere. Point it somewhere else with --home <dir> or MEMOREEI_HOME.

On a Mac: Memoreei.app

1. Download the DMG from the latest release: Memoreei-arm64.dmg for Apple silicon (About This Mac says Chip Apple M…), Memoreei-x86_64.dmg for Intel. macOS 11 or newer.
2. Drag Memoreei into Applications.
3. Open it the first time from Finder. The app isn't signed by Apple yet, so a double-click, Launchpad or Spotlight won't open it. On macOS 11–14, right-click → Open, then Open. On macOS 15 and later, double-click once, then System Settings → Privacy & Security → Open Anyway. Once per download.
4. Full Disk Access, which iMessage needs. macOS gives apps no way to ask, so a window walks you through dragging Memoreei into the list, and notices when it's done.
5. The firewall may ask whether Memoreei Server may accept incoming connections. Allow, or other machines can't reach it.
6. The dashboard opens in your browser. Set up iMessage under Sources, and WhatsApp or Signal too if WhatsApp for Mac or Signal Desktop is installed (Signal's Connect asks macOS once for its key: choose Allow). Then create a key under Clients for each machine or app that will search.

Memoreei then lives in the menu bar and starts at login. Open Dashboard signs you in to the dashboard; Quit stops the server too.

Updates. The menu says Update to X…. Download the new DMG and replace the app. Until Memoreei is signed, macOS treats each new version as a stranger and switches its Full Disk Access off; the setup window reopens, and you switch it back on.

Data is in ~/Library/Application Support/Memoreei, logs in ~/Library/Logs/Memoreei (Show Log in the menu). A pip-installed memoreei on the same Mac shares that data, so memoreei key list in Terminal shows the app's keys. Don't run both servers at once; the app will tell you if you try.

On Linux: a package

Ubuntu 20.04, Debian 11, RHEL and Rocky 8, current Fedora, or newer; x86_64 or ARM64.

1. Download from Releases:
   • Ubuntu, Debian: memoreei_X.Y.Z_amd64.deb (arm64 on ARM, such as a Raspberry Pi)
   • Fedora, RHEL, Rocky: memoreei-X.Y.Z.x86_64.rpm (aarch64 on ARM)
   • anything else, or without root: memoreei-X.Y.Z-linux-x86_64.tar.gz (aarch64 on ARM)
2. Install it, by double-clicking it or:

   sudo apt install ./memoreei_*.deb        # Ubuntu, Debian
   sudo dnf install ./memoreei-*.rpm        # Fedora, RHEL, Rocky
   tar xzf memoreei-*-linux-*.tar.gz && memoreei-*-linux-*/install.sh   # into ~/.local, no root
   

3. Open Memoreei from your applications. It starts the server, sets it to start at login, and opens the dashboard. Create a key under Clients for each machine or app that will search.
4. Add sources. Signal, if Signal Desktop is set up, is under Sources in the dashboard: Connect reads its key from your desktop's keyring. The other live connectors are set up in a terminal for now, with memoreei setup, and chat exports with memoreei import ….

No desktop? The same package, from a terminal:

memoreei service install     # start now and at every login; offers to start at boot too
memoreei key create laptop   # one key per client
memoreei admin-url           # how to reach the dashboard from your own computer

The server is the systemd user unit memoreei.service. Data is in ~/.local/share/memoreei, the program in /opt/memoreei (or ~/.local/opt/memoreei from the tarball). Settings go in config.env, except MEMOREEI_HOME itself, which goes in ~/.config/memoreei/env.

Updates. The dashboard says when there's a new release. Install it the same way; a running Memoreei restarts on the new version by itself.

Two people, one computer? The first to start gets port 3679; the second sets MEMOREEI_PORT=3680 in their config.env.

Coming from pip? Before 0.4, Linux data lived in ~/.memoreei, and nothing moves it. Either mv ~/.memoreei ~/.local/share/memoreei, or put MEMOREEI_HOME=~/.memoreei in ~/.config/memoreei/env.

Uninstall with sudo apt remove memoreei, sudo dnf remove memoreei, or install.sh --uninstall. Your data stays.

Anywhere else: pip

python3 -m venv ~/memoreei-venv && source ~/memoreei-venv/bin/activate
pip install memoreei          # --pre for a release candidate
memoreei setup                # pick connectors, enter credentials, make the first key
memoreei sync                 # pull in messages

On Debian and Ubuntu, sudo apt install python3-venv first. To keep the network server running in the background (launchd on macOS, a systemd user unit on Linux):

memoreei service install      # starts at login, restarts if it crashes
memoreei service status | logs | uninstall

On a headless Linux box, loginctl enable-linger $USER once, so it starts at boot rather than at your first login. To update: pip install --upgrade memoreei, then memoreei service install again.

macOS via pip. iMessage needs Full Disk Access for the Python behind your virtualenv, which is buried somewhere nobody finds by hand. memoreei service grant-access opens System Settings and a Finder window with the right file already selected; drag it in, switch it on, and it checks the result. The firewall asks about the same Python the first time the server starts: Allow. The app does all of this for you, which is the argument for the app.

Connect a client

On the same machine

The client starts Memoreei itself and talks over stdio: no network, no key, and every tool, including the imports. For Claude Code, claude mcp add memoreei -- memoreei serve. Elsewhere (.mcp.json, claude_desktop_config.json):

{
  "mcpServers": {
    "memoreei": { "command": "memoreei", "args": ["serve"] }
  }
}

Use the full path (which memoreei) if it's in a virtualenv your client doesn't know.

Over the network

Create a key per client, in the dashboard or with memoreei key create laptop. The key is shown once, with ready-to-paste setup and this machine's address filled in:

claude mcp add --transport http memoreei http://<server-ip>:3679/mcp \
  --header "Authorization: Bearer <key>"

or, in a project's .mcp.json, with the key kept in an environment variable:

{
  "mcpServers": {
    "memoreei": {
      "type": "http",
      "url": "http://<server-ip>:3679/mcp",
      "headers": { "Authorization": "Bearer ${MEMOREEI_KEY}" }
    }
  }
}

Any MCP client with Streamable HTTP and custom headers works the same way. A lost laptop costs one memoreei key revoke laptop; memoreei key list shows when each key was last used.

claude.ai connectors call from Anthropic's servers, not your browser, so they can't reach your home network. They need a public HTTPS URL (below), with the key in an Authorization: Bearer <key> header.

Run it as a network server

The network server speaks MCP's Streamable HTTP at /mcp on port 3679, and refuses every request without a key. There is no way to run it open. The app, the Linux package and memoreei service install all run it for you; by hand, it's memoreei serve --http.

Port 3679 spells DORY on a phone keypad. It is officially registered to the Apple Newton's dock sync, a device discontinued in 1998, which is not expected to object. Change it with --port or MEMOREEI_PORT.

What the network can do

Search, and press one refresh button. A network client gets search_memoreei, get_context, list_sources and sync, and nothing else. Several local tools take a path on the server, and a key holder shouldn't be able to point one at your SSH keys and search them back out. Filling the database is a local job.

sync takes no arguments: it runs the connectors configured on the server and re-reads registered import files that have changed.

The dashboard

/admin shows status, sources, client keys and the log, and switches start-at-login. It answers only on the server itself, after a one-time sign-in link:

memoreei admin-url     # http://localhost:3679/admin/login?token=…

The link works once, within five minutes, and signs that browser in for a month. With no display, admin-url also prints the ssh -L that brings the dashboard to your laptop. Dashboard sessions and API keys are separate: neither opens the other.

HTTPS

Plain HTTP is fine on a home network or a VPN. For anything public, put HTTPS in front. Caddy gets its own certificate:

memories.example.com {
    reverse_proxy <server-ip>:3679
}

and MEMOREEI_PUBLIC_URL=https://memories.example.com in config.env makes key create print that URL. Or, with a certificate already in hand, memoreei serve --http --tls-cert cert.pem --tls-key key.pem (or MEMOREEI_TLS_CERT and MEMOREEI_TLS_KEY in config.env).

Sources

WhatsApp is read from where WhatsApp for Mac keeps the chats it has synced from your phone: texts, photo and video captions, shared links and document names. Stickers, voice notes and reactions have no words to search, so they're skipped. Its database has the same layout as the one in an iPhone backup, so WHATSAPP_DB_PATH can point at that instead, on any OS. WhatsApp on Windows and Linux is WhatsApp Web, whose local copy is encrypted with a key held by WhatsApp's servers, so there is nothing there to read.

Signal is read from Signal Desktop's database on the same computer. Its key is sealed by the system keyring (the Keychain on a Mac, GNOME Keyring or KWallet on Linux), so connecting reads it once, when you choose Connect under Sources, and saves it; a Mac asks first. Texts, captions, links, group changes and calls are kept. Reactions and edits follow the message they belong to, with both wordings of an edit searchable, and a message deleted for everyone is marked rather than forgotten. Photos and files become labels, never copies. Disappearing messages are never stored.

Live sources sync incrementally, fetching only what's new. Imports are remembered: memoreei sync re-reads a file when it changes.

Set up live sources with memoreei setup (or memoreei setup gmail for one), and import with memoreei import …. memoreei import --help lists the formats.

MCP tools

A local (stdio) client gets all of them. Each tool's parameters are in its MCP description, which your client shows it, and the server sends a short set of instructions on how to use them.

Finding people. participant takes a name, part of one ("Jane", "jan do") or a phone number in any format, and finds that person on every app: iMessage stores a number, WhatsApp and Signal a name, and the two are joined through your contacts and the number each WhatsApp or Signal message came from. People who only share a name are never merged; a name that fits several people searches all of them and says so in the result's note. participant_scope decides how much: conversation (the default) is what they wrote anywhere plus both sides of your one-to-one chats, sent only what they wrote, any_chat every chat they're in. me is you, as is your own name.

Every filter narrows the search before anything is ranked, so a filtered search returns the best matches among those messages. A search returns results, plus people when you named one and a note whenever there's something to explain, such as a name that fits several people or why nothing came back.

CLI

memoreei setup [connector]          # configure connectors; offers the first API key
memoreei serve                      # stdio, for a local client
memoreei serve --http [--port 3679] [--tls-cert … --tls-key …]
memoreei open                       # the dashboard, starting Memoreei if needed
memoreei admin-url                  # a one-time dashboard sign-in link
memoreei key create | list | revoke <name>
memoreei service install | status | logs | uninstall | grant-access
memoreei status                     # message counts, sources, last sync times
memoreei config                     # settings, tokens masked
memoreei sync [source]              # everything, or one of discord, telegram, matrix,
                                    #   slack, email, mastodon, imessage, whatsapp,
                                    #   signal
memoreei search "printer issue" --limit 5 --person "Jane" --after 2026-01-01
memoreei import sms backup.xml      # also discord-package, messenger, instagram,
                                    #   json, csv, contacts
memoreei import list | forget <id>  # the files `sync` re-reads

Every command takes --home <dir>, and --help.

How search works

Every query runs two searches at once, and fuses them:

"that weird API rate limit issue"
   ├─▶ keyword (SQLite FTS5, BM25)   matches "API", "rate", "limit"
   └─▶ vector (cosine similarity)    matches "throttling", "429 errors", "backoff"
          │
          ▼
   Reciprocal Rank Fusion: score = Σ 1 / (60 + rank)

Results that both searches found rise to the top; results only one found still count. RRF works on ranks, so the two scores never need to agree on a scale.

The default embedding model is BAAI/bge-small-en-v1.5 via FastEmbed: 384 dimensions, about 67 MB of ONNX, fully offline. EMBEDDING_PROVIDER=openai swaps in OpenAI's.

Configuration

memoreei setup and the dashboard write config.env; .env.example lists every setting for editing by hand. The environment wins over a .env in the current directory, which wins over config.env.

Connector settings:

API keys aren't settings. They live in the database, hashed.

Privacy

• Everything is stored in one SQLite file on your machine. The home directory is readable only by you, and config.env is mode 600.
• The default search model runs offline. No telemetry, no analytics, no cloud.
• Network traffic happens only when you ask for it: live connectors call their own services, and EMBEDDING_PROVIDER=openai sends message text to OpenAI.
• The network server is off until you start it, never runs without a key, and stores only hashes of its keys. Over the network it can search, not add or read files.

Contributing

CONTRIBUTING.md covers building from source, running the tests and adding a connector.

License

MIT