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 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 "" [flags]

Flags

| Flag | Default | Description | |------|---------|-------------| | --account | 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

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

# From a specific person with attachments
msgvault search "from:alice@example.com 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  --json

# Date range search
msgvault search "after:2026-01-01 before:2026-03-31 subject:invoice" --json

Show Full Message

msgvault show-message  --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](../gws-shared/SKILL.md) — Account profile wrapper and GWS routing
• [google-docs-automation](../google-docs-automation/SKILL.md) — Non-email Google Workspace access

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dbmcco
• Source: dbmcco/claude-agent-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.