Memoreei

Remember every conversation you've ever had.

Memoreei is an open-source MCP server that gives AI assistants a searchable memory of your entire personal communication history. It connects to 13 platforms so far — Discord, WhatsApp, Telegram, Signal, iMessage, Gmail, Slack, Instagram, and more — ingests your messages, and indexes them with a hybrid search engine combining keyword and semantic vector search. Any AI client that supports the Model Context Protocol can then query your memories as naturally as asking a question.

The problem it solves: every AI assistant starts each conversation with no knowledge of who you are, what you've discussed, or what matters to you. Memoreei changes that by turning years of your personal conversations into a living, searchable knowledge base — surfaced exactly when your AI needs it.

"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?"

Your AI can answer these now. Without Memoreei, it can't.

It's Also a Platform

Memoreei isn't just a memory server — any app can be built on top of it. Two of our favorites:

• Movie Ring — Ranks movies based on what your friends are actually talking about in the group chat that never shuts up.

• Contact Dossier — A personal CRM that builds itself from your conversations. No data entry required.

Key Features

• Local-first — all data stays in a single SQLite file on your machine

• 13 sources and counting — WhatsApp, Discord, Telegram, Slack, Matrix, iMessage, Signal, Gmail, Instagram, Mastodon, and more

• MCP-native — 19 tools exposed via the Model Context Protocol, usable by any MCP client

• Hybrid search — BM25 keyword search + vector semantic search, fused with Reciprocal Rank Fusion

• No mandatory cloud — default embedding model runs fully offline via ONNX

• CLI + Docker — pip install memoreei and you're running in under a minute

Supported Sources

File import — one-time or repeated ingest from an exported file. Live sync — incremental sync via API, checkpoint-based (only fetches new messages).

Quick Start

pip install memoreei
memoreei setup           # interactive — pick connectors, enter credentials
memoreei sync            # pull messages from configured sources
memoreei serve           # start the MCP server

Or from source:

git clone https://github.com/CalebChristiansen/Memoreei.git
cd Memoreei
python -m venv .venv && source .venv/bin/activate
pip install -e .

Connect to Your AI

Add to your MCP client config (e.g. .mcp.json, claude_desktop_config.json, or wherever your client reads MCP server definitions):

{
  "mcpServers": {
    "memoreei": {
      "command": "/path/to/memoreei/.venv/bin/python",
      "args": ["-m", "memoreei.server"],
      "cwd": "/path/to/memoreei"
    }
  }
}

If you installed via pip install memoreei, the memoreei-server command is also available:

{
  "mcpServers": {
    "memoreei": {
      "command": "memoreei-server"
    }
  }
}

MCP Tools

All 19 tools are available to any connected MCP client.

Search & Retrieval

search_memory

Hybrid keyword + semantic search across all ingested memories.

get_context

Fetch surrounding messages for a specific memory — essential for understanding the conversation around a result.

add_memory

Manually store a note, fact, or anything worth remembering. Auto-embeds content immediately.

list_sources

Inventory all ingested sources with message counts.

{
  "whatsapp:friends": 1842,
  "discord:1234567890": 391,
  "telegram:-100987654321": 227,
  "manual": 12
}

File Import Tools

ingest_whatsapp

Import a WhatsApp chat export .txt file. Handles multi-line messages, media placeholders, and deduplication on re-import.

import_discord_package

Import a Discord GDPR data export (all channels and DMs). Accepts a ZIP file or extracted folder.

Request your data at: Discord Settings → Privacy & Safety → Request All of My Data

import_messenger

Import Facebook Messenger messages from a GDPR data download (JSON format).

Download at: Facebook Settings → Your Information → Download Your Information

import_instagram

Import Instagram DMs from a GDPR data download (JSON format).

Download at: Instagram Settings → Accounts Center → Your Information → Download Your Information

import_sms_backup

Import SMS/MMS messages from an Android SMS Backup & Restore XML file.

import_json_file

Import messages from any JSON file. Supports JSON arrays, JSON-lines, and wrapped objects. Covers Google Chat takeout, Google Hangouts, LinkedIn data, and custom formats.

import_csv_file

Import messages from any CSV or TSV file. Auto-detects delimiter (comma, tab, semicolon). Covers LinkedIn exports and any custom spreadsheet format.

Live Sync Tools

All sync tools use checkpoint-based incremental sync — only new messages are fetched on subsequent runs.

sync_discord

Sync messages from a Discord channel via the bot API.

sync_telegram

Sync messages received by a Telegram bot via getUpdates. Bot must be a member of the target group or have received DMs.

sync_matrix

Sync messages from a Matrix room using the Client-Server API.

sync_slack

Sync messages from a Slack channel via the Web API (conversations.history). Requires bot token with channels:history and users:read scopes.

sync_email

Sync Gmail messages via IMAP. Uses per-folder UID checkpointing.

sync_mastodon

Sync Mastodon posts. Public and hashtag timelines require no authentication.

sync_imessage

🧪 Beta — macOS only. Requires Full Disk Access for Terminal in System Settings → Privacy & Security.

Sync iMessage/SMS conversations from ~/Library/Messages/chat.db (read-only).

sync_signal

🧪 Beta — requires pysqlcipher3. Signal Desktop must be installed.

Sync Signal Desktop messages from the local encrypted SQLCipher database. Default paths: ~/.config/Signal/sql/db.sqlite (Linux), ~/Library/Application Support/Signal/sql/db.sqlite (macOS).

Utility Tools

refresh_memory

Trigger an immediate sync of all configured sources. Returns count of new messages.

sync_all

Sync every configured connector and return counts per source.

CLI Reference

# Interactive setup — configure connectors, writes to .env
memoreei setup             # pick from a list (spacebar to select, enter to confirm)
memoreei setup gmail       # configure a specific connector directly

# Start the MCP server (stdio transport, default)
memoreei serve

# Start with SSE transport (for HTTP clients)
memoreei serve --sse --port 8080

# Show DB stats: message counts, sources, last sync times
memoreei status

# Sync all configured sources
memoreei sync

# Sync a specific source
memoreei sync discord
memoreei sync telegram
memoreei sync matrix
memoreei sync slack
memoreei sync email
memoreei sync mastodon

# Search from the terminal
memoreei search "API redesign notes"
memoreei search "printer issue" --limit 5 --source whatsapp:friends

# Import files
memoreei import-whatsapp /path/to/WhatsApp\ Chat.txt
memoreei import-sms /path/to/sms-backup.xml
memoreei import-discord-package /path/to/discord-package.zip

# Show current configuration (tokens masked)
memoreei config

Architecture

 ┌──────────────────────────────────────────────────────────────────────┐
 │                          Your Data Sources                           │
 │                                                                      │
 │  File Imports                          Live Sync (API)               │
 │  ─────────────────────────────         ──────────────────────────    │
 │  WhatsApp .txt  Instagram JSON         Discord    Telegram           │
 │  Messenger JSON SMS Backup XML         Slack      Matrix             │
 │  Discord ZIP    Generic JSON/CSV       Gmail      Mastodon           │
 │                                        iMessage   Signal             │
 └──────────────┬───────────────────────────────┬─────────────────────┘
                │                               │
                ▼                               ▼
 ┌──────────────────────────────────────────────────────────────────────┐
 │                        Memoreei MCP Server                           │
 │                                                                      │
 │  ┌────────────────────┐  ┌──────────────────┐  ┌─────────────────┐  │
 │  │    Connectors      │  │  Hybrid Search   │  │   MCP Tools     │  │
 │  │                    │  │                  │  │                 │  │
 │  │  13 sources        │  │  FTS5 (BM25)     │  │  search_memory  │  │
 │  │  file + live sync  │  │  + vector cosine │  │  get_context    │  │
 │  │  checkpoint-based  │  │  + RRF fusion    │  │  add_memory     │  │
 │  │  dedup on import   │  │                  │  │  list_sources   │  │
 │  │                    │  └────────┬─────────┘  │  ingest_*       │  │
 │  │                    │           │            │  import_*       │  │
 │  │                    │           │            │  sync_*         │  │
 │  │                    │  ┌────────▼──────────┐ │  refresh_memory │  │
 │  │                    │  │  SQLite Database  │ │  sync_all       │  │
 │  │                    │  │  memories + FTS5  │ └────────┬────────┘  │
 │  └────────────────────┘  │  embeddings BLOB  │          │           │
 │                          │  sync checkpoints │          │           │
 │                          └───────────────────┘          │           │
 └────────────────────────────────────────────────────────┼────────────┘
 │                                                          │ stdio / SSE
                                                          ▼
                                               ┌─────────────────────┐
                                               │    MCP Clients      │
                                               │                     │
                                               │  Any AI assistant   │
                                               │  that speaks MCP    │
                                               └─────────────────────┘

How Hybrid Search Works

Memoreei runs two searches in parallel and fuses the results:

Query: "that weird API rate limit issue"
         │
         ├──▶ FTS5 BM25 keyword search
         │    Matches "API", "rate", "limit" — fast, exact
         │    Returns ranked list of IDs
         │
         └──▶ Vector search (cosine similarity)
              Matches "throttling", "429 errors", "backoff"
              Returns ranked list of IDs
                  │
                  ▼
         Reciprocal Rank Fusion (RRF)
         ─────────────────────────────
         score(item) = Σ  1 / (60 + rank_i)
                        i ∈ {keyword_rank, vector_rank}

         Items in BOTH result sets are boosted.
         Items in only one set still contribute.
         Top N returned, then filtered by source/participant/date.

Why RRF? Rank-based fusion requires no score normalization across different scales. The constant k=60 is the standard default from the original paper and empirically outperforms weighted linear combinations.

Default embedding model: BAAI/bge-small-en-v1.5 via FastEmbed — 384-dimensional vectors, ~23 MB ONNX model, runs fully offline.

Configuration

Copy .env.example to .env and fill in the credentials for the sources you want to use. Unused connectors can be left blank. Or just run memoreei setup and it'll walk you through it.

Core

Discord

Telegram

Matrix

Slack

Gmail

Mastodon

iMessage (macOS only)

Signal Desktop

Privacy

Local-first by design.

• All data stored in a single SQLite file on your machine

• Default embedding model (FastEmbed) runs entirely offline via ONNX — zero network calls

• OpenAI embeddings are strictly opt-in (EMBEDDING_PROVIDER=openai)

• No telemetry, no analytics, no cloud sync

• Your messages never leave your machine in the default configuration

What requires network access:

• Live sync connectors (Discord, Telegram, Slack, Matrix, Gmail, Mastodon) make outbound API calls to those services

• EMBEDDING_PROVIDER=openai sends message text to OpenAI's API for embedding

The .env file and memoreei.db are in .gitignore.

Docker

docker build -t memoreei .
docker run -v ./data:/data -e MEMOREEI_DB_PATH=/data/memoreei.db memoreei serve

Or with docker-compose:

docker-compose up

Contributing

See CONTRIBUTING.md for guidelines on adding new connectors, running tests, and submitting pull requests.

License

MIT