gws-cache

gws-cache is a fast, local SQLite caching layer for Gmail threads and Google Calendar events accessed via the gws CLI.

It provides token-efficient, 0ms local offline queries, keyword search, timeline exporting, and high-watermark delta synchronization for Gmail messages and Google Calendar invites.

Features

• Topic & Feed Management: Group related Gmail search queries into named topics (e.g. newsletters, billing, projects).
• Incremental Delta Sync: Uses Gmail historyId and message internal timestamps for fast, high-watermark syncs.
• Fast Local Search: Query cached messages instantly by keyword, topic, date range, or sender without making remote Gmail API calls.
• Token-Efficient Exporter: Export formatted message timelines in Markdown or JSON for local analysis or LLM contexts.
• Inbox Scanning: Scan inbox queries with pre-fetch deduplication to cache matching emails in SQLite.
• Google Calendar Sync: Synchronize calendar invites using Google Calendar syncToken delta ingestion and dual-horizon lookback/lookahead windows.
• Email Classifier: Automatically identifies automated system notifications, bulk lists, and transactional emails versus human messages.

Prerequisites

• gws CLI installed and authenticated with your Google Workspace account.
• SQLite database storage (CGO-free via modernc.org/sqlite).

Installation

Download Pre-Built Binaries

Download the latest release binary for your platform from GitHub Releases:

# macOS (Apple Silicon / ARM64)
curl -L https://github.com/alexgorbatchev/gws-cache-cli/releases/download/v0.1.0/gws-cache-darwin-arm64 -o /usr/local/bin/gws-cache
chmod +x /usr/local/bin/gws-cache

# Linux (x86_64)
curl -L https://github.com/alexgorbatchev/gws-cache-cli/releases/download/v0.1.0/gws-cache-linux-amd64 -o /usr/local/bin/gws-cache
chmod +x /usr/local/bin/gws-cache

Build From Source

Requires Go 1.22+ installed:

git clone https://github.com/alexgorbatchev/gws-cache-cli.git
cd gws-cache-cli
just build
# Binary output is at ./bin/gws-cache

Or install directly into $GOPATH/bin:

go install github.com/alexgorbatchev/gws-cache-cli/cmd/gws-cache@latest

Quick Start & Usage

1. Register Topics to Track

Register topics with custom Gmail queries:

# Register topics with specific Gmail queries
gws-cache topic add newsletters --name "Tech Newsletters" --query "category:promotions"
gws-cache topic add billing --name "Invoices & Receipts" --query "from:billing@"

# List tracked topics
gws-cache topic list

# Remove a topic
gws-cache topic remove newsletters

2. Synchronize Email Topics (sync)

Fetch and cache emails for tracked topics into local SQLite:

# Sync recent emails for a topic (defaults to --since 4w and max 25 threads)
gws-cache sync newsletters

# Custom lookback window and max thread limit
gws-cache sync newsletters --since 2w --max-threads 10

# Sync all tracked topics
gws-cache sync --all

3. Search Cached Emails (search)

Query cached messages instantly from local SQLite with 0ms network latency:

# Search cached emails across all topics
gws-cache search "Digest"

# Filter search by topic, date, or human-only emails
gws-cache search "Invoice" --topic billing --since 14d --format table
gws-cache search --human-only --format json

4. Scan Inbox (scan)

Scan inbox threads with pre-fetch deduplication (skips already cached threads in 0ms):

# Scan recent inbox (default query 'in:inbox', lookback --since 7d)
gws-cache scan --since 7d --max-threads 30

# Scan inbox with custom search query
gws-cache scan --query "is:unread" --since 3d

5. Export Message Timelines (export)

Emit formatted message timelines in Markdown or JSON:

# Export Markdown timeline (human emails only)
gws-cache export newsletters --format markdown

# Export full history or specific lookback window
gws-cache export newsletters --since all --format markdown
gws-cache export newsletters --since 2w --format markdown

# Export JSON payload
gws-cache export newsletters --format json --human-only

6. Synchronize Google Calendar (calendar)

Sync Google Calendar events using syncToken delta ingestion:

# Sync primary calendar events (defaults to 4 weeks past, 4 weeks future lookahead)
gws-cache calendar sync

# Expand lookback and lookahead windows
gws-cache calendar sync --past 8w --future 6w

# List cached calendar events
gws-cache calendar list newsletters
gws-cache calendar list --format json --since 4w

7. Database Health & Statistics (status)

Inspect database statistics and count of tracked topics, cached threads, and cached messages:

gws-cache status

Configuration & Flags

• --db <path>: Custom path to SQLite cache database (defaults to cache.db adjacent to executable).

Development

Run unit tests and generate coverage reports:

# Run unit tests
just test

# Build executable
just build

# Generate test coverage report
just coverage

License

MIT