Skip to main content
Glama
inbox-recall

inbox-recall

by joey12725

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, [#id] on every line

Time

Depends on the integration

when: "last spring", "march 2024", "past 2 weeks", "over the holidays", resolved in your time zone

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 (with me for your own messages), person (any chat that includes them), chat, network, direction, and time as plain English or ISO dates.

  • Thread reconstruction. get_conversation reads 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_messages re-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_people merges one person's WhatsApp, Signal and Instagram identities by name. list_conversations shows 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 Postgres NOTIFY the 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 benchmark

demo 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 stats

To 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 mcp

Claude 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_TOKEN

More clients and prompting tips: docs/mcp.md.

Tools

Tool

What it does

search_messages

Hybrid search with filters and plain-English time. Empty query lists every match newest-first. Returns thread excerpts with [#id] citations and a cursor.

get_conversation

Read around a message, across a time range, or the latest messages in a chat, with older/newer cursors.

get_messages

Fetch specific ids, optionally with context, to verify a citation.

list_conversations

Chats by recency with message counts, date span and members; filter by title, network, person or time.

find_people

Resolve a name or handle across networks, with message counts per network.

archive_stats

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

  1. Sync. beeper-pg-sync writes every chat into messages with stable ids, merges the same message seen by two sources, and bumps content_updated_at on edits. Each write sends a NOTIFY.

  2. Embed. inbox-recall embed picks 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 over embedding::vector(dims), so models never mix and swapping one needs no migration.

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

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

  5. 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 extension

Database 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 tools
archive_statsArchive overviewC
Read-only

Networks, message counts, date coverage and embedding coverage of the archive.

Inputs: format.

find_peopleFind peopleA
Read-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 conversationA
Read-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 idB
Read-only

Fetch specific messages by id (to verify a citation), optionally with context.

Inputs: ids (required), format, context.

list_conversationsList conversationsA
Read-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 messagesA
Read-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

    A3.7/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -
    • F
      license
      Not graded
      quality
      A
      maintenance
      Enables 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.
      -