WhatsApp Total Recall

A Zero-Cost, Privacy-First Conversational Intelligence Engine & MCP Server for WhatsApp (macOS)

WhatsApp Total Recall is an edge-native conversational intelligence platform and Model Context Protocol (MCP) server for macOS. It passively reads local WhatsApp Catalyst SQLite archives (ChatStorage.sqlite) with zero cloud egress, zero network traffic, and zero account ban risk.

What This Package Delivers

Installing whatsapp-total-recall via pip, pipx, or uv provides:

1. Model Context Protocol (MCP) Server: Plug into Claude Desktop, Cursor, Windsurf, or Claude Code for live conversational search across personal and group chats.
2. Local Hybrid Search Engine: Single-file local SQLite storage combining keyword search (FTS5 BM25) and dense semantic vector search (sqlite-vec SIMD KNN) via Reciprocal Rank Fusion (RRF).
3. Privacy Vault Perimeter: Opt-In Chat Vault with strict contact isolation and cryptographic revocation purges (PRAGMA secure_delete).
4. Local Web UI & API Server: Embedded zero-dependency web interface running locally on http://127.0.0.1:8765.

Prerequisites (macOS Full Disk Access)

WhatsApp on macOS stores messages in an App Group container: ~/Library/Group Containers/group.net.whatsapp.WhatsApp.shared/ChatStorage.sqlite

Reading this local container requires granting macOS Full Disk Access:

1. Open System Settings > Privacy & Security > Full Disk Access.
2. Toggle ON your terminal emulator (Terminal, iTerm2, Ghostty) and/or your AI client (Claude Desktop, Cursor).

Installation

Install globally using uv (recommended) or pipx:

# With SIMD-accelerated vector search (recommended):
uv tool install "whatsapp-total-recall[vec]"

# Or via pipx:
pipx install "whatsapp-total-recall[vec]"

# Or standard pip:
pip install "whatsapp-total-recall[vec]"

Note: Both whatsapp-total-recall and total-recall executable commands are provided.

Model Context Protocol (MCP) Integration

Connect WhatsApp Total Recall directly to your AI desktop clients without manual environment setup:

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "whatsapp-total-recall": {
      "command": "uvx",
      "args": ["--from", "whatsapp-total-recall[vec]", "whatsapp-total-recall", "mcp"]
    }
  }
}

(Or use "command": "whatsapp-total-recall" if installed globally).

Cursor & Windsurf

In Cursor (Settings > Features > MCP) or .cursor/mcp.json:

{
  "mcpServers": {
    "whatsapp-total-recall": {
      "command": "uvx",
      "args": ["--from", "whatsapp-total-recall[vec]", "whatsapp-total-recall", "mcp"]
    }
  }
}

Claude Code (CLI)

claude mcp add whatsapp-total-recall -- uvx --from "whatsapp-total-recall[vec]" whatsapp-total-recall mcp

Exposed MCP Tools

• search_messages: Hybrid lexical + vector search across approved WhatsApp conversations with RRF ranking.
• get_thread_context: Reconstruct multi-turn reply DAGs and conversation branches around specific messages.
• stage_reply_draft: Synthesize tone-matched reply drafts staged in the local Review Box (no autonomous sending).

CLI Quick Start

1. Approve Chats in Privacy Vault

# Quick approve all discovered WhatsApp chats at once:
whatsapp-total-recall vault approve --all

# Or approve a specific contact or group JID:
whatsapp-total-recall vault approve "123456789@s.whatsapp.net"

2. Ingest Messages

# Ingest approved 1:1 chats:
whatsapp-total-recall ingest

# Ingest approved group chats with reply DAG attribution:
whatsapp-total-recall ingest --include-groups

3. Search Locally

whatsapp-total-recall search "project deadline" --k 5

4. Launch Desktop Web UI

whatsapp-total-recall ui

Links & Resources

• GitHub Repository: https://github.com/vyavahareyash/whatsapp-total-recall
• Mac Menu Bar DMG Installer: GitHub Releases
• Architecture Documentation: docs/architecture.md
• Issues & Feedback: GitHub Issues
• License: MIT License