Knowledge Cortex — Mine
Mine your Gmail history into structured flat files — contacts, clients, communications, and key facts — stored in ~/.cortex/. No server required. Files you own.
When invoked
Read {skill_path}/references/file-schema.md for the storage format before any file operations.
Commands
| What user says | Action |
|---|---|
| "run the cortex" / "cortex run" | Run mining pass |
| "cortex dry run" | Mine without writing — pass --dry-run |
| "cortex from DATE" | Mine from specific date — pass --from YYYY-MM-DD |
| "set up the cortex" | Run first-time setup |
Setup (first run)
Check prerequisites:
which gws || echo "MISSING: npm install -g @googleworkspace/cli"
python3 -c "import anthropic" 2>/dev/null || echo "MISSING: pip install anthropic"
ls ~/.cortex/state.json 2>/dev/null || echo "FIRST RUN"If gws missing: tell user npm install -g @googleworkspace/cli then gws auth setup. If anthropic missing: tell user pip install anthropic (or pip install anthropic --break-system-packages on managed Python). If first run: initialise storage.
mkdir -p ~/.cortex/originals
echo '{}' > ~/.cortex/contacts.json
echo '{}' > ~/.cortex/clients.json
touch ~/.cortex/communications.jsonl ~/.cortex/knowledge.jsonl ~/.cortex/files.jsonlWrite ~/.cortex/state.json:
{"version":"1.0","cursors":{"gmail":null},"last_run":null,"totals":{"contacts":0,"clients":0,"communications":0,"knowledge":0,"files":0},"runs":[]}Mining
python3 {skill_path}/scripts/cortex-mine.py
python3 {skill_path}/scripts/cortex-mine.py --dry-run
python3 {skill_path}/scripts/cortex-mine.py --from 2024-01-01
python3 {skill_path}/scripts/cortex-mine.py --batch-size 25The script prints a run report on completion. Show it to the user verbatim.
Common errors:
gws: command not found— install gws CLIAuthError/403— rungws auth setupANTHROPIC_API_KEY not set— set env var or add to~/.cortex/.envModuleNotFoundError: anthropic—pip install anthropic
Scheduling
- Claude Code Desktop: Cowork > Scheduled > New Task >
Run the cortex-mine skill> Daily - CLI:
/loop 24h run the cortex-mine skill - Cron:
0 6 * * * cd ~ && ANTHROPIC_API_KEY=sk-... python3 /path/to/cortex-mine.py
Exporting data
See {skill_path}/references/export-adapters.md for patterns to export cortex data to Obsidian, SQLite, Notion, CRM systems, or custom APIs.
Environment
| Variable | Default | Purpose |
|---|---|---|
CORTEX_DIR | ~/.cortex | Storage root |
ANTHROPIC_API_KEY | — | Required for extraction |
CORTEX_BATCH_SIZE | 50 | Threads per run |
CORTEX_OWNER_EMAIL | — | Your email — excluded from contacts |
References
- File schemas:
{skill_path}/references/file-schema.md - Pre-filter rules:
{skill_path}/references/prefilter-patterns.md - Export patterns:
{skill_path}/references/export-adapters.md