# Msgvault

> 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.

- **Type:** Skill
- **Install:** `agentstack add skill-dbmcco-claude-agent-toolkit-msgvault`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [dbmcco](https://agentstack.voostack.com/s/dbmcco)
- **Installs:** 0
- **Category:** [Communication](https://agentstack.voostack.com/c/communication)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [dbmcco](https://github.com/dbmcco)
- **Source:** https://github.com/dbmcco/claude-agent-toolkit/tree/main/skills/msgvault

## Install

```sh
agentstack add skill-dbmcco-claude-agent-toolkit-msgvault
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

```bash
curl -s http://127.0.0.1:8080/health
# Expected: {"status":"ok"}
```

## CLI Search

```bash
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

```bash
# 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

```bash
msgvault show-message  --json
```

Returns full message including headers, body, labels, and attachment info.

## Analytics

```bash
# 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

```bash
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:
```bash
# 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](https://github.com/dbmcco)
- **Source:** [dbmcco/claude-agent-toolkit](https://github.com/dbmcco/claude-agent-toolkit)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-dbmcco-claude-agent-toolkit-msgvault
- Seller: https://agentstack.voostack.com/s/dbmcco
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.