| name | msgvault |
| description | Search and retrieve email from the offline msgvault archive. Full-text, vector/semantic, and hybrid search across all email accounts. Use this as the PRIMARY tool for finding, searching, and reading emails — NOT gws-gmail. |
| metadata | {"version":"0.14.1","openclaw":{"category":"productivity","requires":{"bins":["msgvault"]}}} |
msgvault — Email Archive Search
msgvault is an offline email archive synced from all Gmail accounts. It holds 105K+ messages and supports full-text search (FTS5), semantic/vector search (Ollama embeddings), and hybrid search.
When to use this skill: ANY time you need to find, search, or read emails. This is the primary email search tool.
When NOT to use this skill: Sending, replying, forwarding, or live inbox mutation. For agents, use n8n email draft webhooks for human-reviewed outbound mail; sending requires a human action or explicitly approved send gateway. For one-off coding-agent live Gmail mutations, use gws-account <profile> gmail ... only when explicitly requested and confirm before sending or changing mail.
Daemon
msgvault runs as a background daemon on port 8080. Verify it's healthy:
curl -s http://127.0.0.1:8080/health
CLI Search
msgvault search "<query>" [flags]
Flags
| Flag | Default | Description |
|---|
--account <email> | all accounts | Limit to specific account |
--mode fts|vector|hybrid | fts | Search mode |
--json | off | JSON output (use for programmatic use) |
--limit N | 50 | Max results |
--offset N | 0 | Pagination |
--explain | off | Show per-signal scores (hybrid/vector) |
Query Operators
| Operator | Example | Description |
|---|
from: | from:alice@example.com | Sender email |
to: | to:bob@example.com | Recipient |
cc: | cc:team@example.com | CC recipient |
subject: | subject:invoice | Subject text |
label: / l: | label:INBOX | Gmail label |
has:attachment | has:attachment | Messages with attachments |
before: | before:2024-01-01 | Before date (YYYY-MM-DD) |
after: | after:2024-01-01 | After date |
older_than: | older_than:30d | Older than N days/weeks/months/years |
newer_than: | newer_than:7d | Newer than relative date |
larger: | larger:5M | Size filter |
smaller: | smaller:100K | Size filter |
| bare words | project report | Full-text search |
| quoted | "exact phrase" | Exact phrase match |
Examples
msgvault search "project update" --json --limit 10
msgvault search "from:alice@example.com has:attachment" --json
msgvault search "quarterly financial review" --mode vector --json
msgvault search "contract negotiation" --mode hybrid --json --explain
msgvault search "newer_than:7d" --account <account.com> --json
msgvault search "after:2026-01-01 before:2026-03-31 subject:invoice" --json
Show Full Message
msgvault show-message <id> --json
Returns full message including headers, body, labels, and attachment info.
Analytics
msgvault list-senders --json --limit 20
msgvault list-domains --json --limit 20
msgvault list-labels --json
msgvault stats
Accounts
msgvault list-accounts --json
Returns all synced accounts with message counts and last sync time.
Performance
CLI searches are fast — typically under 100ms for FTS queries across the full 105K message archive. If searches are slow, check for zombie msgvault mcp processes with ps aux | grep "msgvault mcp" and kill them.
Troubleshooting
If msgvault commands hang:
ps aux | grep "msgvault mcp" | grep -v grep
pkill -9 -f "msgvault mcp"
msgvault list-accounts --json
Do NOT use msgvault mcp (stdio MCP server) — it spawns persistent processes that lock the SQLite database and prevent all other queries. Always use the CLI commands (msgvault search, msgvault show-message, etc.) via bash instead.
See Also
| Mode | Best For | Speed |
|---|
fts | Exact keyword/phrase matches, operator queries | Fastest |
vector | Semantic/conceptual search, finding related emails | Slower |
hybrid | Best of both — combines FTS + vector scores | Moderate |
Default mode is fts. Use vector or hybrid when keyword search isn't finding what you need.
See Also
