[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-74635":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":10,"language":11,"languages":10,"totalLinesOfCode":10,"stars":12,"forks":13,"watchers":14,"openIssues":15,"contributorsCount":16,"subscribersCount":16,"size":16,"stars1d":16,"stars7d":16,"stars30d":16,"stars90d":16,"forks30d":16,"starsTrendScore":16,"compositeScore":17,"rankGlobal":10,"rankLanguage":10,"license":18,"archived":19,"fork":19,"defaultBranch":20,"hasWiki":21,"hasPages":19,"topics":22,"createdAt":10,"pushedAt":10,"updatedAt":23,"readmeContent":24,"aiSummary":25,"trendingCount":16,"starSnapshotCount":16,"syncStatus":26,"lastSyncTime":27,"discoverSource":28},74635,"msgvault","wesm\u002Fmsgvault","wesm","Archive a lifetime of email and chat. Offline search, analytics, and AI query over your full message history. Powered by DuckDB","https:\u002F\u002Fmsgvault.io",null,"Go",1745,108,17,42,0,19.11,"MIT License",false,"main",true,[],"2026-06-12 02:03:26","# msgvault\n\n[![Go 1.25+](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FGo-1.25+-00ADD8?logo=go)](https:\u002F\u002Fgo.dev)\n[![License: MIT](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FLicense-MIT-yellow.svg)](LICENSE)\n[![Docs](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDocs-msgvault.io-blue)](https:\u002F\u002Fmsgvault.io)\n[![Discord](https:\u002F\u002Fimg.shields.io\u002Fbadge\u002FDiscord-Join-5865F2?logo=discord&logoColor=white)](https:\u002F\u002Fdiscord.gg\u002FfDnmxB8Wkq)\n\n[Documentation](https:\u002F\u002Fmsgvault.io) · [Setup Guide](https:\u002F\u002Fmsgvault.io\u002Fguides\u002Foauth-setup\u002F) · [Interactive TUI](https:\u002F\u002Fmsgvault.io\u002Fusage\u002Ftui\u002F)\n\n> **Alpha software.** APIs, storage format, and CLI flags may change without notice. Back up your data.\n\nArchive a lifetime of email. Analytics and search in milliseconds, entirely offline.\n\n## Why msgvault?\n\nYour messages are yours. Decades of correspondence, attachments, and history shouldn't be locked behind a web interface or an API. msgvault downloads a complete local copy and then everything runs offline. Search, analytics, and the MCP server all work against local data with no network access required.\n\nCurrently supports Gmail and IMAP sync, plus offline imports from MBOX exports and Apple Mail (.emlx) directories.\n\n## Features\n\n- **Full Gmail backup**: raw MIME, attachments, labels, and metadata\n- **IMAP sync**: archive mail from any standard IMAP server\n- **MBOX \u002F Apple Mail import**: import email from MBOX exports or Apple Mail (.emlx) directories\n- **Interactive TUI**: drill-down analytics over your entire message history, powered by DuckDB over Parquet — connects to a remote `msgvault serve` instance or runs locally\n- **Full-text search**: FTS5 with Gmail-like query syntax (`from:`, `has:attachment`, date ranges)\n- **MCP server**: access your full archive at the speed of thought in Claude Desktop and other MCP-capable AI agents\n- **DuckDB analytics**: millisecond aggregate queries across hundreds of thousands of messages in the TUI, CLI, and MCP server\n- **Incremental sync**: History API picks up only new and changed messages\n- **Multi-account**: archive several Gmail and IMAP accounts in a single database\n- **Resumable**: interrupted syncs resume from the last checkpoint\n- **Content-addressed attachments**: deduplicated by SHA-256\n\n## Installation\n\n**macOS \u002F Linux:**\n```bash\ncurl -fsSL https:\u002F\u002Fmsgvault.io\u002Finstall.sh | bash\n```\n\n**Windows (PowerShell):**\n```powershell\npowershell -ExecutionPolicy ByPass -c \"irm https:\u002F\u002Fmsgvault.io\u002Finstall.ps1 | iex\"\n```\n\nThe installer detects your OS and architecture, downloads the latest release from [GitHub Releases](https:\u002F\u002Fgithub.com\u002Fwesm\u002Fmsgvault\u002Freleases), verifies the SHA-256 checksum, and installs the binary. You can review the script ([bash](https:\u002F\u002Fmsgvault.io\u002Finstall.sh), [PowerShell](https:\u002F\u002Fmsgvault.io\u002Finstall.ps1)) before running, or download a release binary directly from GitHub.\n\nTo build from source instead (requires **Go 1.25+** and a C\u002FC++ compiler for CGO and to statically link DuckDB):\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fwesm\u002Fmsgvault.git\ncd msgvault\nmake install\n```\n\n**Conda-Forge:**\n\nYou can install msgvault [from conda-forge](https:\u002F\u002Fprefix.dev\u002Fchannels\u002Fconda-forge\u002Fpackages\u002Fmsgvault) using Pixi or Conda:\n\n```bash\npixi global install msgvault\nconda install -c conda-forge msgvault\n```\n\n## Quick Start\n\n> **Prerequisites:** You need a Google Cloud OAuth credential before adding an account.\n> Follow the **[OAuth Setup Guide](https:\u002F\u002Fmsgvault.io\u002Fguides\u002Foauth-setup\u002F)** to create one (~5 minutes).\n\n```bash\nmsgvault init-db\nmsgvault add-account you@gmail.com          # opens browser for OAuth\nmsgvault sync-full you@gmail.com --limit 100\nmsgvault tui\n```\n\n## Commands\n\n| Command | Description |\n|---------|-------------|\n| `init-db` | Create the database |\n| `add-account EMAIL` | Authorize a Gmail account (use `--headless` for servers) or add an IMAP account |\n| `sync-full EMAIL` | Full sync (`--limit N`, `--after`\u002F`--before` for date ranges) |\n| `sync EMAIL` | Sync only new\u002Fchanged messages |\n| `tui` | Launch the interactive TUI (`--account` to filter, `--local` to force local) |\n| `search QUERY` | Search messages (`--account` to filter, `--json` for machine output) |\n| `show-message ID` | View full message details (`--json` for machine output) |\n| `mcp` | Start the MCP server for AI assistant integration |\n| `serve` | Run daemon with scheduled sync and HTTP API for remote TUI |\n| `stats` | Show archive statistics |\n| `list-accounts` | List synced email accounts |\n| `verify EMAIL` | Verify archive integrity against Gmail |\n| `export-eml` | Export a message as `.eml` |\n| `import-mbox` | Import email from an MBOX export or `.zip` of MBOX files |\n| `import-emlx` | Import email from an Apple Mail directory tree |\n| `build-cache` | Rebuild the Parquet analytics cache |\n| `update` | Update msgvault to the latest version |\n| `setup` | Interactive first-run configuration wizard |\n| `repair-encoding` | Fix UTF-8 encoding issues |\n| `list-senders` \u002F `list-domains` \u002F `list-labels` | Explore metadata |\n\nSee the [CLI Reference](https:\u002F\u002Fmsgvault.io\u002Fcli-reference\u002F) for full details.\n\n## Vector Search\n\nmsgvault can search your archive semantically using vector embeddings in addition to the default FTS5 keyword search. Point it at a self-hosted OpenAI-compatible embedding endpoint (Ollama, llama.cpp, LM Studio) and three surfaces accept either pure semantic search or BM25+vector fused via Reciprocal Rank Fusion:\n\n- **CLI:** `msgvault search \"...\" --mode vector` or `--mode hybrid`\n- **HTTP:** `GET \u002Fapi\u002Fv1\u002Fsearch?q=...&mode=vector` or `mode=hybrid`\n- **MCP:** the `search_messages` tool with a `mode` argument set to `vector` or `hybrid`\n\nA separate MCP tool, `find_similar_messages`, returns nearest neighbors for a seed message. See the [Vector Search guide](https:\u002F\u002Fmsgvault.io\u002Fusage\u002Fvector-search\u002F) for setup, backfill, and troubleshooting.\n\n## Importing from MBOX or Apple Mail\n\nImport email from providers that offer MBOX exports or from a local Apple Mail data directory:\n\n```bash\nmsgvault init-db\nmsgvault import-mbox you@example.com \u002Fpath\u002Fto\u002Fexport.mbox\nmsgvault import-mbox you@example.com \u002Fpath\u002Fto\u002Fexport.zip   # zip of MBOX files\nmsgvault import-emlx                                        # auto-discover Apple Mail accounts\nmsgvault import-emlx you@example.com ~\u002FLibrary\u002FMail\u002FV10     # explicit path\n```\n\n## Configuration\n\nAll data lives in `~\u002F.msgvault\u002F` by default (override with `MSGVAULT_HOME`).\n\n```toml\n# ~\u002F.msgvault\u002Fconfig.toml\n[oauth]\nclient_secrets = \"\u002Fpath\u002Fto\u002Fclient_secret.json\"\n\n[sync]\nrate_limit_qps = 5\n```\n\nSee the [Configuration Guide](https:\u002F\u002Fmsgvault.io\u002Fconfiguration\u002F) for all options.\n\n### Multiple OAuth Apps (Google Workspace)\n\nSome Google Workspace organizations require OAuth apps within their org.\nTo use multiple OAuth apps, add named apps to `config.toml`:\n\n```toml\n[oauth]\nclient_secrets = \"\u002Fpath\u002Fto\u002Fdefault_secret.json\"   # for personal Gmail\n\n[oauth.apps.acme]\nclient_secrets = \"\u002Fpath\u002Fto\u002Facme_workspace_secret.json\"\n```\n\nThen specify the app when adding accounts:\n\n```bash\nmsgvault add-account you@acme.com --oauth-app acme\nmsgvault add-account personal@gmail.com              # uses default\n```\n\nTo switch an existing account to a different OAuth app:\n\n```bash\nmsgvault add-account you@acme.com --oauth-app acme   # re-authorizes\n```\n\n### Google Service Accounts\n\nWorkspace admins can use a Google service account with domain-wide delegation instead of per-user OAuth tokens:\n\n```toml\n[oauth.apps.acme]\nservice_account_key = \"\u002Fsecure\u002Fpath\u002Fservice-account.json\"\n```\n\nIn Google Admin Console, authorize the service account client for `https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fgmail.readonly` and `https:\u002F\u002Fwww.googleapis.com\u002Fauth\u002Fgmail.modify`. If you will run `delete-staged` with permanent deletion, also authorize `https:\u002F\u002Fmail.google.com\u002F`. Keep the key file owner-only, for example `chmod 600 \u002Fsecure\u002Fpath\u002Fservice-account.json`.\n\n```bash\nmsgvault add-account you@acme.com --oauth-app acme\nmsgvault sync-full you@acme.com\n```\n\n## MCP Server\n\nmsgvault includes an MCP server that lets AI assistants search, analyze, and read your archived messages. Connect it to Claude Desktop or any MCP-capable agent and query your full message history conversationally. See the [MCP documentation](https:\u002F\u002Fmsgvault.io\u002Fusage\u002Fchat\u002F) for setup instructions.\n\n## Daemon Mode (NAS\u002FServer)\n\nRun msgvault as a long-running daemon for scheduled syncs and remote access:\n\n```bash\nmsgvault serve\n```\n\nConfigure scheduled syncs in `config.toml`:\n\n```toml\n[[accounts]]\nemail = \"you@gmail.com\"\nschedule = \"0 2 * * *\"   # 2am daily (cron)\nenabled = true\n\n[server]\napi_port = 8080\nbind_addr = \"0.0.0.0\"\napi_key = \"your-secret-key\"\n```\n\nThe TUI can connect to a remote server by configuring `[remote].url`. Use `--local` to force local database when remote is configured. See the [Web Server reference](https:\u002F\u002Fmsgvault.io\u002Fapi-server\u002F) for the HTTP API.\n\n## Documentation\n\n- [Setup Guide](https:\u002F\u002Fmsgvault.io\u002Fguides\u002Foauth-setup\u002F): OAuth, first sync, headless servers\n- [Searching](https:\u002F\u002Fmsgvault.io\u002Fusage\u002Fsearching\u002F): query syntax and operators\n- [Interactive TUI](https:\u002F\u002Fmsgvault.io\u002Fusage\u002Ftui\u002F): keybindings, views, deletion staging\n- [CLI Reference](https:\u002F\u002Fmsgvault.io\u002Fcli-reference\u002F): all commands and flags\n- [Multi-Account](https:\u002F\u002Fmsgvault.io\u002Fusage\u002Fmulti-account\u002F): managing multiple Gmail accounts\n- [Configuration](https:\u002F\u002Fmsgvault.io\u002Fconfiguration\u002F): config file and environment variables\n- [Architecture](https:\u002F\u002Fmsgvault.io\u002Farchitecture\u002Fstorage\u002F): SQLite, Parquet, and attachment storage\n- [MCP Server](https:\u002F\u002Fmsgvault.io\u002Fusage\u002Fchat\u002F): AI assistant integration\n- [Troubleshooting](https:\u002F\u002Fmsgvault.io\u002Ftroubleshooting\u002F): common issues and fixes\n- [Development](https:\u002F\u002Fmsgvault.io\u002Fdevelopment\u002F): contributing, testing, building\n\n## Community\n\nJoin the [msgvault Discord](https:\u002F\u002Fdiscord.gg\u002FfDnmxB8Wkq) to ask questions, share feedback, report issues, and connect with other users.\n\n## Development\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002Fwesm\u002Fmsgvault.git\ncd msgvault\nmake install-hooks  # install pre-commit hook (requires prek)\nmake test           # run tests\nmake lint           # run linter (auto-fix)\nmake install        # build and install\n```\n\nPre-commit hooks are managed by [prek](https:\u002F\u002Fprek.j178.dev\u002F) (`brew install prek`).\n\n## License\n\nMIT. See [LICENSE](LICENSE) for details.\n","msgvault 是一个用于归档电子邮件和聊天记录的工具，支持离线搜索、分析及通过AI查询整个消息历史。该项目基于DuckDB数据库，提供快速的数据处理能力。其核心功能包括对Gmail、IMAP服务器邮件的完整备份与同步，以及从MBOX或Apple Mail导出文件的导入；利用交互式TUI界面进行深度数据分析，并支持全文搜索（使用类似Gmail的查询语法）和MCP服务器接入以增强AI助手的功能。此外，msgvault还具备增量同步、多账户管理等特性，确保数据的安全性和完整性。适用于需要长期保存个人通信记录并希望在本地环境中高效管理和检索这些信息的用户。",2,"2026-05-12 11:07:45","high_star"]