inbox-recall
Indexes Discord messages synced through Beeper into Postgres, making conversations searchable by agents with hybrid semantic/keyword retrieval, sender and time filters, and thread reconstruction with citations.
Indexes Google Messages conversations synced through Beeper, enabling agents to search message history semantically and by keyword, filter by sender or time, and retrieve surrounding thread context.
Indexes iMessage conversations synced through Beeper, allowing agents to search across message history with hybrid retrieval, filters, and cited conversation excerpts.
Indexes Instagram DMs synced via the included Chrome extension, making them searchable by agents with semantic and keyword search, metadata filters, and thread context.
Indexes Messenger conversations synced through Beeper into Postgres, enabling agents to search messages with hybrid retrieval, sender/time filters, and conversation reconstruction.
Indexes Signal messages synced through Beeper, providing agents searchable access to conversations with semantic/keyword ranking, filters, and cited thread excerpts.
Indexes Slack messages synced through Beeper, allowing agents to search workspace conversations with hybrid retrieval, sender and time filters, and surrounding context.
Indexes Telegram conversations synced through Beeper, enabling agents to search message history with hybrid semantic/keyword retrieval, filters, and thread reconstruction.
Indexes WhatsApp messages synced through Beeper into Postgres, making chats searchable by agents with hybrid retrieval, sender/time filters, and cited conversation excerpts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@inbox-recall what did Priya say about the lease renewal? pull the whole thread"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
inbox-recall
Every conversation you've ever had, searchable by your own agents.
inbox-recall gives self-hosted AI agents a memory of your messages. It syncs WhatsApp, Signal, Telegram, iMessage, Discord, Slack, Instagram and the rest of the networks Beeper bridges into one Postgres database on your machine, indexes them for hybrid semantic + keyword search with pgvector, and serves that to Claude Code, Claude Desktop, Cursor, OpenClaw, Hermes Agent or any other MCP client.
Ask "what did Priya say about the lease renewal?" and your agent gets back the actual thread: ranked excerpts with the messages around each hit, who said what, when, and a message id to cite. Assistants are starting to search your texts for you. inbox-recall is that idea built for self-hosted agents and for archives that span every network and many years.
Ask your agent
A Claude Code session against the fabricated demo archive that ships with the repo (every person and message in it is made up):
> What did Maya say about the Lisbon trip last spring? Where did we stay, and do I still owe her?
● inbox-recall · search_messages (query: "lisbon trip", sender: ["Maya"], when: "last spring", limit: 3, context: 1)
⎿ # Results 1-3 of 37 for "lisbon trip" (hybrid search)
filters: sender=Maya · time=2026-03-01 to 2026-05-31 ("last spring")
## Maya Chen · whatsapp dm · conversation 1
[#266] 2026-03-20 10:39 me: fair enough
→ [#267] 2026-03-25 19:02 Maya Chen: ok I'm officially in for Lisbon in May!! flights are cheap from here right now
[#268] 2026-03-25 19:05 me: amazing. I can do May 14 to 20, does that work?
## Maya Chen · whatsapp dm · conversation 1
[#288] 2026-05-19 03:53 me: I forgot my charger again
→ [#289] 2026-05-20 09:30 Maya Chen: still thinking about that custard tart place. best trip we've taken
[#290] 2026-05-21 12:46 Maya Chen: what time works for you
## Maya Chen · whatsapp dm · conversation 1
[#277] 2026-04-24 19:02 Maya Chen: my coworker says Manteigaria has the best pastel de nata, way better than Belem
→ [#278] 2026-04-24 19:06 Maya Chen: also we have to do the day trip to Sintra, she said go early before the tour buses
[#279] 2026-04-24 19:09 me: adding both to the list
● inbox-recall · get_conversation (message_id: 270, before: 1, after: 4)
⎿ ## Maya Chen · whatsapp dm · conversation 1
[#269] 2026-03-25 19:07 Maya Chen: perfect. I'll book the flights tonight, TAP has a direct one
→ [#270] 2026-03-25 19:43 Maya Chen: booked! confirmation code is in your email. we land 7:50am
[#271] 2026-03-28 19:02 Maya Chen: found a place in Alfama, the one with the blue tiled balcony and the view of the river
[#272] 2026-03-28 19:04 me: omg yes book it before someone else does
[#273] 2026-03-28 19:11 Maya Chen: done, 6 nights. you owe me 410 for your half
[#274] 2026-03-28 19:14 me: sending it now
● Maya signed on for Lisbon on March 25 and booked a direct TAP flight that same evening,
landing at 7:50am [#267, #269, #270]. Three days later she found a place in Alfama with a
blue tiled balcony and a river view and booked it for 6 nights [#271, #273].
She said you owed her 410 for your half, and you replied "sending it now" on March 28
[#273, #274]. As far as the chat shows, that's settled.
She also pushed Manteigaria for pastel de nata and an early-morning day trip to Sintra
[#277, #278], and in May called it the best trip you've taken [#289].The agent split the question into a topic, a person and a time range, then opened the thread around a promising hit to read what happened next. Every claim carries the ids it came from.
Related MCP server: loci-mcp
Why it's different
Built-in assistant message search | inbox-recall | |
Networks | One app's messages | Every network Beeper bridges (WhatsApp, Signal, Telegram, iMessage, Google Messages, Discord, Slack, Messenger, LinkedIn, X...) plus Instagram, deduplicated into one index |
Where your archive lives | The vendor decides | Your Postgres, on your hardware. Nothing is uploaded unless you pick a hosted embedding API |
Which agent can use it | That vendor's assistant | Any MCP client over stdio or HTTP, plus a REST API and a CLI |
Retrieval | Whatever the vendor ships | Semantic ANN (pgvector HNSW) + Postgres full-text + trigram fuzzy matching, fused with reciprocal rank fusion. You can read it, tune it and benchmark it |
Answers come as | Depends on the integration | Conversation excerpts: each hit plus surrounding turns, overlapping windows merged, replies quoted, |
Time | Depends on the integration |
|
Scale | Bounded by the integration | Years of history: HNSW and GIN indexes, keyset pagination, and an embedder that only touches new or edited messages |
Your data afterwards | Inside the product | Plain SQL tables with stable ids. Query them, chart them, build on them |
Features
Hybrid retrieval. Three rankers run under the same filters: cosine ANN over the active model's HNSW index, English full-text search with a boost for messages that contain every term, and trigram matching that rescues typos and half-remembered names. Weighted reciprocal rank fusion merges them.
Context-aware embeddings. Each message is embedded with its chat title and the turns just before it, so a bare "booked it!" still matches a search for the trip it was about.
Filters agents actually need.
sender(withmefor your own messages),person(any chat that includes them),chat,network,direction, and time as plain English or ISO dates.Thread reconstruction.
get_conversationreads around any message or across a time range, with cursors to keep scrolling older or newer.Citations everywhere. Every message line starts with its stable id.
get_messagesre-fetches cited ids so an agent can double-check itself.Pagination for huge archives. Relevance results page with consistent cursors; filter-only queries walk every match newest-first with keyset pagination.
People and chats across networks.
find_peoplemerges one person's WhatsApp, Signal and Instagram identities by name.list_conversationsshows who is in each chat and when it was active.Pluggable embeddings. Any OpenAI-compatible endpoint (OpenAI, Ollama, LM Studio, vLLM, llama.cpp, TEI), in-process sentence-transformers, or a deterministic hashing embedder for tests. Models live side by side; switch with one env var.
Incremental and resumable. The embedder works off
content_updated_at, commits per batch, re-embeds edits, drops deleted messages, and wakes on PostgresNOTIFYthe moment the sync writes something new.MCP without the weight. A dependency-free MCP server (stdio and Streamable HTTP), a REST API and a CLI share one tool registry. The only runtime dependency is psycopg.
Sync included. Built on beeper-pg-sync: read-only Beeper Desktop sync with per-chat backfill, plus a Chrome extension for Instagram DMs. See docs/sync.md.
Quickstart
You need Python 3.11+, uv and Postgres with pgvector (the bundled Compose file runs pgvector/pgvector:pg17).
1. Try it on the demo archive
git clone https://github.com/joey12725/inbox-recall.git
cd inbox-recall
docker compose up -d db
uv sync
export DATABASE_URL=postgresql://sync:sync@localhost:5432/messages
export EMBED_PROVIDER=hash # zero-setup embedder; use ollama for real semantic search
uv run inbox-recall demo # ~3,000 fabricated messages across 6 networks, embedded
uv run inbox-recall search lisbon flights --from maya --when "last spring"
uv run inbox-recall search 'from:me "pay you back"'
uv run inbox-recall search alfama --context 4 # a hit plus the thread around it
uv run inbox-recall eval # the retrieval benchmarkdemo refuses to run against a database that already holds real messages, so point it at a scratch database.
2. Index your own messages
cp .env.example .env # add BEEPER_ACCESS_TOKEN; pick an embedding provider
set -a; source .env; set +a
ollama pull nomic-embed-text # or set EMBED_PROVIDER=openai / lmstudio
uv run inbox-recall migrate
uv run beeper-pg-sync sync # first sync from Beeper Desktop
uv run inbox-recall embed # first embedding pass (incremental after this)
uv run inbox-recall statsTo get a Beeper token, open Beeper Desktop → Settings → Integrations, enable the Desktop API and add an approved connection. Instagram DMs can come in through the Chrome extension too (docs/sync.md).
Keep everything fresh with uv run beeper-pg-sync run (sync daemon) and uv run inbox-recall serve --embed (search API, MCP over HTTP and the embedding worker), or docker compose --profile daemon up -d to run both in containers.
3. Connect your agent
Claude Code
claude mcp add inbox-recall \
-e DATABASE_URL=postgresql://sync:sync@localhost:5432/messages \
-e EMBED_PROVIDER=ollama \
-e EMBED_QUERY_PREFIX="search_query: " -e EMBED_DOCUMENT_PREFIX="search_document: " \
-- uv --directory /path/to/inbox-recall run inbox-recall mcpClaude Desktop, Cursor and other JSON-configured clients
{
"mcpServers": {
"inbox-recall": {
"command": "uv",
"args": ["--directory", "/path/to/inbox-recall", "run", "inbox-recall", "mcp"],
"env": {
"DATABASE_URL": "postgresql://sync:sync@localhost:5432/messages",
"EMBED_PROVIDER": "ollama",
"EMBED_QUERY_PREFIX": "search_query: ",
"EMBED_DOCUMENT_PREFIX": "search_document: "
}
}
}
}Agents on another machine (OpenClaw, Hermes Agent, a home-server agent) connect over Streamable HTTP:
RECALL_TOKEN=$(python3 -c "import secrets; print(secrets.token_urlsafe(32))") \
uv run inbox-recall serve --embed --host 0.0.0.0
# MCP endpoint: http://<host>:8766/mcp with Authorization: Bearer $RECALL_TOKENMore clients and prompting tips: docs/mcp.md.
Tools
Tool | What it does |
| Hybrid search with filters and plain-English time. Empty query lists every match newest-first. Returns thread excerpts with |
| Read around a message, across a time range, or the latest messages in a chat, with older/newer cursors. |
| Fetch specific ids, optionally with context, to verify a citation. |
| Chats by recency with message counts, date span and members; filter by title, network, person or time. |
| Resolve a name or handle across networks, with message counts per network. |
| Networks, date coverage and embedding coverage. |
All tools are read-only. Each returns a compact transcript by default, or the full structured result with format: "json". The same tools are on the REST API (GET /v1/search, /v1/conversations, /v1/messages/{id}/thread, /v1/people, /v1/stats) and the CLI.
Retrieval quality
inbox-recall eval runs 24 agent-style queries against the demo archive, each with known answers, in four groups: exact wording, paraphrase (same meaning, different words), filtered (people, chats, networks, time) and fuzzy (typos). CI runs it on every push with nomic-embed-text served by Ollama, through the same OpenAI-compatible provider you'd use at home.
mode (nomic-embed-text) | all R@10 | exact wording | paraphrase | filtered | typos | MRR@10 |
keyword only | 0.71 | 1.00 | 0.36 | 0.67 | 1.00 | 0.71 |
semantic only | 0.85 | 1.00 | 0.64 | 0.86 | 1.00 | 0.71 |
hybrid | 0.90 | 1.00 | 0.64 | 1.00 | 1.00 | 0.80 |
Hybrid matches or beats each ranker alone in every group, and the first relevant message is usually the top hit. Full-text search nails exact wording, the embedding model carries paraphrase, and filters run inside every ranker so "Maya, last spring" never starves the vector search. Methodology, the model-free baseline and a 250k-message latency run: docs/retrieval.md.
How it works
Sync. beeper-pg-sync writes every chat into
messageswith stable ids, merges the same message seen by two sources, and bumpscontent_updated_aton edits. Each write sends aNOTIFY.Embed.
inbox-recall embedpicks up messages with no vector (or a stale one) for the active model, embeds each with its chat title and recent turns, and commits per batch. Each model gets its own partial HNSW index overembedding::vector(dims), so models never mix and swapping one needs no migration.Retrieve. One set of SQL filters feeds three rankers: HNSW cosine search (with pgvector's iterative scan so filters don't starve it), stored
to_tsvector('english')full-text, and trigram similarity. Weighted reciprocal rank fusion merges them, with a bonus for messages that contain every query term.Expand. Each hit pulls N messages either side from the
(conversation_id, sent_at, id)index. Overlapping windows merge into one excerpt and reply targets are quoted inline.Serve. The same tool registry backs MCP (stdio and HTTP), the REST API and the CLI.
Deeper notes: docs/architecture.md, docs/retrieval.md, docs/configuration.md, docs/extending.md.
Development
uv sync
uv run ruff check src tests && uv run ruff format --check src tests
TEST_DATABASE_URL=postgresql://sync:sync@localhost:5432/messages_test uv run pytest
npm ci && npm run lint && npm test # Chrome extensionDatabase tests need Postgres with pgvector and reset the public schema of TEST_DATABASE_URL, so use a throwaway database. The suite covers the sync layer, the embedding pipeline (including resume after failures and NOTIFY wake-ups), retrieval, filters, pagination, the MCP protocol over stdio and HTTP, and the benchmark, all on fabricated conversations with a deterministic embedder.
Tech stack
Python 3.11+ · PostgreSQL 16/17 · pgvector (HNSW) · pg_trgm · Postgres full-text search · psycopg 3 · Model Context Protocol · Ollama / OpenAI-compatible embeddings · sentence-transformers (optional) · Beeper Desktop API · Chrome MV3 extension · pytest · ruff · Docker Compose · GitHub Actions
Credits
Built by Joey Hersh. MIT licensed. A fork of beeper-pg-sync, which provides the sync layer. Not affiliated with Beeper, Anthropic, OpenAI or Meta; use it with your own accounts and follow each network's terms.
Available Tools
6 toolsarchive_statsArchive overviewCRead-only
Networks, message counts, date coverage and embedding coverage of the archive.
Inputs: format.
find_peopleFind peopleARead-only
Look up people by name or handle across every network. One person on WhatsApp and Instagram shows up once, with message counts per network. Use it to resolve who someone is before filtering.
Inputs: limit, query, format, network.
get_conversationRead a conversationARead-only
Reconstruct a thread. Pass message_id to read the messages around it (before/after counts), conversation_id with when to read a time range, or conversation_id alone for the latest messages. Returns cursors to keep reading older or newer messages.
Inputs: when, after, limit, before, +4 more.
get_messagesGet messages by idBRead-only
Fetch specific messages by id (to verify a citation), optionally with context.
Inputs: ids (required), format, context.
list_conversationsList conversationsARead-only
List chats, most recently active first, with message counts, date span and the people in them. Filter by title, network, a person in the chat, or activity in a time range.
Inputs: when, limit, query, cursor, +3 more.
search_messagesSearch messagesARead-only
Hybrid semantic + keyword + fuzzy search across every synced chat and network. Returns ranked matches as conversation excerpts with surrounding messages, each line tagged with a citable message id. Filter by sender, person, chat, network, direction and time (when accepts plain English such as 'last spring' or 'march 2024'). Leave query empty to list messages matching the filters, newest first. Paginate with next_cursor.
Inputs: chat, mode, when, after, +10 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Most tools have clearly distinct roles: find_people resolves identities, archive_stats reports coverage, search_messages discovers messages, list_conversations browses chats, and get_conversation reconstructs threads. There is some overlap between get_conversation around a message_id and get_messages with optional context, but descriptions largely disambiguate.
Tool names are consistently snake_case and mostly follow an action_object pattern (find_people, search_messages, get_conversation, get_messages, list_conversations). archive_stats is the only clear deviation because it is noun-first rather than verb-first.
Six tools are well-scoped for a read-only message archive. Each tool covers a distinct retrieval need: identity resolution, statistics, search, conversation reconstruction, message verification, and chat listing.
The surface covers the core read-only lifecycle: discover people, inspect archive coverage, search messages, list conversations, reconstruct threads, and verify specific message citations. No obvious lifecycle gaps for an archive-recall server.
Maintenance
Related MCP Connectors
Private, multimodal knowledge store for agents: hybrid search with cited, provenance-backed results.
Self-hosted AI workspace: semantic RAG document search, long-term memory, and AI chat via MCP.
Search your knowledge bases from any AI assistant using hybrid RAG.
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables MCP-compatible AI agents to search, ask, and retrieve section-level cited answers from a local hybrid index over scattered notes, documents, and chat logs.-
- FlicenseNot gradedqualityAmaintenanceEnables AI agents and MCP hosts to search and question a local, hybrid-indexed corpus of scattered notes, docs, and chat logs, returning section-level citations rather than whole files.-
- FlicenseNot gradedqualityAmaintenanceEnables AI hosts and agents to search, ask, and retrieve cited sections from a locally indexed collection of notes, documents, PDFs, web pages, org files, and chat logs using hybrid vector and BM25 retrieval.-
- FlicenseNot gradedqualityAmaintenanceEnables AI agents and MCP-compatible hosts to search, ask, and retrieve section-level citations from scattered local notes, docs, PDFs, Word files, web pages, org files, and chat logs using hybrid vector and BM25 retrieval.-