Google Activity Assistant

Local-first tools over your Google Takeout activity — keyword search in SQLite, MCP tools for any compatible client, and an optional local web dashboard.

Not a live Google API. You export Takeout once (or periodically), ingest locally, then query with Claude Desktop, Cursor, Grok, or gaa search.

Doc	Use when
docs/HOW_TO.md	Full walkthrough: what it can/can’t do, Takeout, CLI, MCP, FAQ
docs/MCP_AND_TAKEOUT.md	Short MCP + export reference
SECURITY.md	Privacy / what not to commit
CONTRIBUTING.md	Dev setup & PRs

---

Why

Mainstream chatbots don’t have your Search/YouTube history. This project turns a Takeout export into:

1. Structured + full-text search (SQLite + FTS5)
2. MCP tools so agents can answer with citations from your real activity
3. Optional local dashboard (timeline / journeys)

Privacy-first: processing stays on disk under data/ (gitignored).

---

Similar work & positioning

This is not “the only personal-data project” and not “the only MCP.” Adjacent work exists; the packaging here is specific.

Category	Examples / reality	Overlap with this repo
Google Takeout itself	Official takeout.google.com	Data source only
Offline Takeout parsers / privacy research	Scripts, blogs, personal-data tooling	Ingest inspiration
Personal RAG (“chat with my notes/PDFs”)	Common portfolio pattern	Same idea (local memory + LLM), different corpus
MCP for browser history	e.g. local browser-history MCP servers	Same shape (history → tools), not Google Takeout
Google Workspace / product MCPs	Gmail, Drive, Calendar, Looker, SecOps, etc.	Live product APIs — not My Activity dumps
Live “My Activity API” for third parties	Does not exist as a simple public stream	Why we use Takeout + local DB

What this project emphasizes

• Takeout-first Search / YouTube history (JSON and HTML history files)
• SQLite + FTS5 as system of record (portable, offline)
• MCP tools so any compatible host can query your export with citations
• Explicit honesty: no live My Activity sync, multi-GB media exports out of scope for v0.1

How to describe it (interviews / README pitch)

Prefer: “Most Google MCPs hit Drive/Gmail; this wires Takeout My Activity / YouTube history into a local index and MCP tools.”
Avoid: “Nobody has ever built personal history + AI.”

---

Features (v0.1)

Feature	Status
Ingest Takeout JSON (My Activity / YT history)	✅
Ingest Takeout HTML watch/search history	✅
Selective zip extract (skips huge media)	✅
SQLite + FTS5 keyword search	✅
Hybrid search (FTS + embeddings, RRF)	✅ v0.2
Embeddings: hashing default; FastEmbed optional	✅
CLI: ingest, status, search, reindex	✅
MCP: search (modes), stats, import_takeout, reindex_embeddings	✅
Insights (top channels/searches, by hour/weekday/month)	✅ v0.3
Period summary, on this day, journeys, similar, random	✅ v0.3
Local CSV/JSON export	✅ v0.3
Local FastAPI + React dashboard (serve-ui)	✅
Synthetic fixtures for demos/tests	✅
Google Data Portability auto-sync	🔜 later

---

Quick start

Requirements

• Python 3.12+
• uv (recommended)

git clone https://github.com/Daemon-Killer/google-activity-assistant.git
cd google-activity-assistant
uv sync

Sample data (no Google account needed)

uv run gaa ingest-fixtures
uv run gaa reindex          # embeddings for hybrid/semantic search
uv run gaa status
uv run gaa search "React Server"              # hybrid by default
uv run gaa search "React Server" --mode keyword
uv run gaa insights
uv run gaa on-this-day
uv run gaa journeys
uv run gaa random
uv run gaa export ./data/export.csv

Optional better semantic model (ONNX, no PyTorch):

uv sync --extra semantic
uv run gaa reindex   # rebuilds missing rows with FastEmbed when available

Your Takeout

1. Open takeout.google.com
2. Prefer My Activity (Search + YouTube) and/or YouTube → History, format JSON if available (HTML also works)
3. Avoid exporting full Photos/video libraries if you only want activity search
4. Ingest:

uv run gaa ingest /path/to/takeout.zip
# or extracted folder
uv run gaa ingest /path/to/Takeout
uv run gaa status

Real exports and data/activity.db are gitignored. Never commit them.

---

MCP (Claude / Cursor / Grok / …)

Start the stdio server:

uv run gaa serve-mcp

Grok Build (~/.grok/config.toml)

[mcp_servers.google_activity]
command = "uv"
args = [
  "run",
  "--directory",
  "/absolute/path/to/google-activity-assistant",
  "gaa",
  "serve-mcp",
]
enabled = true
startup_timeout_sec = 60

Claude Desktop

claude_desktop_config.json:

{
  "mcpServers": {
    "google-activity": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/google-activity-assistant",
        "gaa",
        "serve-mcp"
      ]
    }
  }
}

Tools

Tool	Purpose
search_activity	Search with mode: keyword | semantic | hybrid (default)
get_activity_stats	Counts / date range / embedding coverage
get_db_info	Local paths only
import_takeout	Ingest a local Takeout zip/folder path
reindex_embeddings	Build vectors for hybrid/semantic search
get_insights	Top channels/searches, hour/weekday heat
summarize_period	Counts + samples for a date range
on_this_day	Same calendar day across years
find_journeys	Search→watch pairs (local heuristic)
similar_activity	Embedding neighbors for a hit id
random_memories	Random rows
export_activity	Write CSV/JSON to a local path

After ingest + reindex, ask: “Search my YouTube for romantic Bollywood songs and cite titles + dates.”
Or: “Use get_insights and summarize my peak hours.”

Full walkthrough (export, FAQ, demo script): docs/HOW_TO.md · MCP config short ref: docs/MCP_AND_TAKEOUT.md

---

Local dashboard

# If web/dist is missing:
cd web && npm install && npm run build && cd ..

uv run gaa serve-ui
# → http://127.0.0.1:8788

API routes under /api/* (stats, activity list, journeys). Binds to localhost by default.

---

Project layout

google-activity-assistant/
├── src/google_activity_assistant/
│   ├── cli.py            # gaa commands
│   ├── mcp_server.py     # FastMCP tools
│   ├── parse_takeout.py  # JSON + HTML parsers
│   ├── ingest.py
│   ├── db.py             # SQLite + FTS5
│   ├── search.py
│   ├── journeys.py       # search→watch proximity
│   └── api.py            # FastAPI dashboard API
├── web/                  # React + Vite dashboard
├── fixtures/             # synthetic Takeout samples
├── docs/
│   ├── HOW_TO.md         # full user guide
│   └── MCP_AND_TAKEOUT.md
├── tests/
└── data/                 # gitignored — your DB + exports

---

Development

uv sync --extra dev
uv run pytest

See CONTRIBUTING.md.

---

Privacy & license

• SECURITY.md — local-first, what not to commit
• LICENSE — MIT

Takeout is Google’s official data export. This project is unaffiliated with Google.

---

Roadmap

1. Better multi-product My Activity coverage (Search slice, Chrome)
2. Optional Data Portability OAuth re-import (bulk jobs, not live My Activity)
3. Drive-folder watch / auto-ingest helpers
4. Packaging / one-command installers

PRs welcome.