# msgvault

Email (and chat) archival tool: download a complete local copy of your message history, then search and run analytics over it in milliseconds, entirely offline. The pitch is "archive a lifetime of email." Part of the [[kenn-software-suite]]; the most-starred member (1.8k) but explicitly alpha.

## What it does

Pulls mail from multiple sources into one local database — full Gmail backup with labels and metadata, IMAP sync from any standard server, plus MBOX and Apple Mail `.emlx` import. Sync is incremental (Gmail History API, so unchanged messages aren't re-downloaded) and resumable after interruption. Multi-account in a single database, with Google Workspace service-account support and domain-wide delegation for org-scale archival.

Once archived, you query offline: an interactive TUI with drill-down analytics, Gmail-like FTS5 query syntax, and semantic vector search via local embeddings (Ollama, [[toolbox/llama-cpp|llama.cpp]], LM Studio). Hybrid search combines BM25 and vector. An MCP server exposes the archive to Claude Desktop and other agents.

## How it works technically

Go 1.25+ (~99%). Two storage engines side by side: SQLite holds messages (raw MIME preserved, attachments content-addressed and deduplicated by SHA-256), and DuckDB drives the millisecond aggregate queries, with Parquet for analytics caching. That split is the design point — SQLite for transactional message store and FTS, DuckDB for the OLAP-style "how many emails per month from X over ten years" queries that a row store would crawl on.

Optional daemon mode adds an HTTP API and cron-scheduled sync. Config is TOML; `MSGVAULT_HOME` overrides the data location; multiple OAuth applications are supported for Workspace orgs.

## Basic usage

```bash
msgvault init-db
msgvault add-account you@gmail.com
msgvault sync-full you@gmail.com --limit 100
msgvault tui

msgvault search "invoice 2023" --mode vector   # or --mode hybrid
```

Distribution: bash installer (macOS/Linux), PowerShell (Windows), Conda-Forge, Docker, or build from source. Building needs Go 1.25+ and a C/C++ compiler for CGO and DuckDB static linking.

## Limitations

- **Alpha software.** The README is explicit: APIs, storage format, and CLI flags may change without notice — back up your data.
- DuckDB static linking means a C/C++ toolchain in the build path (not pure-Go like its sibling [[middleman]]).

## Watchlist

v0.14.x and self-described alpha with a storage-format-may-change warning. Tracked on [[toolbox/watchlist]] for a re-check once the format stabilizes and the alpha label drops.

## Related

- [[wacli]] — WhatsApp CLI that syncs messages locally for offline search; same "own your message history offline" instinct, different source.
- [[toolbox/llama-cpp|llama.cpp]] — one of the local embedding backends msgvault's vector search can use.
- [[kenn-software-suite]] — the rest of the suite. msgvault is the personal-data member, the others target agent workflows.

## Repo

[github.com/kenn-io/msgvault](https://github.com/kenn-io/msgvault) — Go (1.25+), MIT, 1.8k stars, v0.14.1 (alpha, 27 releases). [msgvault.io](https://msgvault.io).