mcpField
C
cortex-mine

cortex-mine

github.com/jezwebProductivity1.1k54 installsUpdated 3w ago
Repository

About cortex-mine

cortex-mine is a skill that extracts contacts, clients, communications, and key facts from Gmail history into local flat files. It requires no server and supports dry runs, date-based mining, and scheduled execution.

Key features

  1. 01Extract structured information from Gmail history
  2. 02Store data in local flat files
  3. 03Support dry runs and start-date filtering
  4. 04Set the number of threads per batch
  5. 05Provide options for scheduled runs

Use cases

  1. 01Organise contact and client details from email
  2. 02Test a mining run before writing files
  3. 03Process mail from a chosen date onward
  4. 04Schedule daily mining

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/jezweb/claude-skills --skill cortex-mine

After installing, type/cortex-minein Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

references/
export-adapters.md
file-schema.md
prefilter-patterns.md
scripts/
cortex-mine.py

Details

From the project README

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 saysAction
"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.jsonl

Write ~/.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 25

The script prints a run report on completion. Show it to the user verbatim.

Common errors:

  • gws: command not found — install gws CLI
  • AuthError / 403 — run gws auth setup
  • ANTHROPIC_API_KEY not set — set env var or add to ~/.cortex/.env
  • ModuleNotFoundError: 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

VariableDefaultPurpose
CORTEX_DIR~/.cortexStorage root
ANTHROPIC_API_KEY—Required for extraction
CORTEX_BATCH_SIZE50Threads 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

Comments

Markdown supported