msgvault

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
# Expected: {"status":"ok"}

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:[e-mail]	Sender email
to:	to:[e-mail]	Recipient
cc:	cc:[e-mail]	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

# Full-text search
msgvault search "project update" --json --limit 10

# From a specific person with attachments
msgvault search "from:[e-mail] has:attachment" --json

# Semantic search (finds conceptually related emails)
msgvault search "quarterly financial review" --mode vector --json

# Hybrid (combines FTS + vector for best results)
msgvault search "contract negotiation" --mode hybrid --json --explain

# Recent emails from a specific account
msgvault search "newer_than:7d" --account <account.com> --json

# Date range search
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

# Top senders
msgvault list-senders --json --limit 20

# Top sender domains
msgvault list-domains --json --limit 20

# Labels with message counts
msgvault list-labels --json

# Database statistics
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:

# Check for zombie MCP processes (common cause of DB locks)
ps aux | grep "msgvault mcp" | grep -v grep

# Kill them if found
pkill -9 -f "msgvault mcp"

# Verify DB is accessible
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

• gws-shared — Account profile wrapper and GWS routing
• google-docs-automation — Non-email Google Workspace access