msgvault-query

Keep your communications and relationships in an archive you own.

msgvault is a local-first, open-source archive for email, chat, meetings, calendars, and contacts. Keep your history on your own hardware, find messages and files, and connect the addresses and handles that belong to the same person. Use the browser, terminal, CLI, HTTP API, or an AI assistant through MCP.

Alpha software. APIs, storage format, and CLI flags may change. Back up your data. This README follows current main; see the 0.20.0 changelog for features and upgrade steps.

What you can do

• Bring your history together. Sync mail, chat, calendars, meeting notes, and contacts, or import local exports. See the source guide.
• Find the message or file you need. Search by sender, date, mailing list, or words. Optionally enable search by meaning, document text extraction, and image search with a provider you choose.
• Keep track of people. Connect identities, curate profiles and relationships, browse contact activity, and sync contacts with CardDAV. Optional profile automation and conversation briefs require separate consent.
• Explore the archive. Group messages by people, domains, time, source, and type in the Web UI or TUI. Save useful views and monitor background work.
• Use your own tools. Query with SQL, export messages and attachments, or connect an agent to the MCP server.
• Preserve and maintain it. Deduplicate copies, back up the archive, and review staged mail deletions before explicitly removing messages upstream. Remote deletion preserves archived messages and attachments.

Keyword search and analytics read your archive without contacting its source services. Sync needs access to those services. Optional model and enrichment features send selected data to the endpoints you configure; local embedding servers are also supported. See recommended configuration for the choices and consent steps.

Installation

macOS / Linux:

curl -fsSL https://msgvault.io/install.sh | bash

macOS via Homebrew

brew install msgvault

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://msgvault.io/install.ps1 | iex"

The installer detects your OS and architecture, downloads the latest release from GitHub Releases, verifies the SHA-256 checksum, and installs the binary. You can review the script (bash, PowerShell) before running, or download a release binary directly from GitHub.

To build from source on macOS or Linux instead (requires Go 1.27+, Bun 1.3.14+, Node.js 20.19+ on 20.x, 22.13+ on 22.x, or 24+, and a C/C++ compiler for CGO and to statically link DuckDB; on Debian/Ubuntu also install libsqlite3-dev for the sqlite3.h header used by the default sqlite_vec build):

git clone https://github.com/kenn-io/msgvault.git
cd msgvault
make install

Conda-Forge:

You can install msgvault from conda-forge using Pixi or Conda:

pixi global install msgvault
conda install -c conda-forge msgvault

Quick Start

For Gmail, first create an OAuth credential with the OAuth setup guide. Then archive a small first batch:

msgvault init-db
msgvault add-account [email protected]
msgvault sync-full [email protected] --limit 100
msgvault serve

Open the API server URL printed by msgvault serve. The release binary includes the browser application; it needs no separate Node or Bun installation at runtime. Use msgvault tui for the terminal interface.

For another provider or a local export, start with choosing a source. Google credentials are needed only for Google-backed sources. The setup guide covers installation, first sync, and running on your own server.

Find your next step

Community

Join the msgvault Discord, report an issue, or read the full documentation.

License

MIT