<div align="center">

# LifeDB

**Your life, one SQLite file — and any AI agent can read it.**

> “一切你无法喂给AI的数据，都是白做的。” —— 孙哥

[中文](README.zh-CN.md) · English · [Product Vision](docs/PRODUCT.md)

<img src="docs/assets/lifedb-movie.gif" width="720" alt="LifeDB life movie — 8 years of GPS tracks igniting on a map">

*A 32-second movie generated by one command from 295,135 GPS points, 1,668 photos and 125 workouts. [Full video →](docs/assets/lifedb-movie.mp4)*

</div>

---

## The problem

You generate more personal data every day than any generation before you —
location history, photos, workouts, sleep, heart rate, notes. And it's all
**stranded**: locked in separate apps, on someone else's server, unreachable
by the one thing that could actually make sense of it.

**Your AI agent can't see any of it.** So all of it is wasted.

Google just deleted the Timeline web viewer for billions of users. Your
location history shouldn't live on a server that can turn it off tomorrow.

## Two promises

### 🤖 Bring Your Own Agent

LifeDB is not an app. It's a **local MCP server** — a database your AI agent
can actually use.

```json
{ "mcpServers": { "lifedb": { "command": "lifedb-mcp" } } }
```

That's the entire integration. Claude, or any MCP-capable agent, instantly
gains seven tools over your life: *what happened that day, where was I that
week, build me a map of 2024, how far did I commute.* Seven indexed queries —
no arbitrary SQL, no full-table scans.

The demos below aren't a product roadmap. They're **examples** — proof of
what agents can build on this contract. The demo layer is yours to extend:
connect the MCP, write your app, done.

### 🔒 Bring Your Own Data

- **Nothing leaves your machine.** No cloud, no account, no telemetry, no upload.
  One SQLite file you own, back up, and delete.
- **Import adapters are plugins** — a manifest + a script. The kernel defines
  one contract; the community builds the connectors. (Want your app supported?
  See the wanted list below — PRs welcome.)
- **Open format.** It's just SQLite. Query it with `sqlite3` today, forever.
  No lock-in, by design.

## What people build with it

<table>
<tr>
<td width="50%">
<b>📍 Day Replay</b><br>
One day, replayed in real time: the camera follows your GPS across the city and
photos pop up where you took them. Pairs with a cross-modal
<a href="docs/assets/day-card.jpg">hero-day card →</a>.
<img src="docs/assets/day-replay.gif" alt="Single-day replay — camera follows GPS across the city"><br>
<a href="docs/assets/day-replay.mp4">Watch full →</a>
</td>
<td width="50%">
<b>🧭 Trip Replay</b><br>
Multi-day trips stitched into one journey: pass a second date and the tracks
concatenate — cross-city stops, photo clusters, a single continuous timeline.
<img src="docs/assets/trip-replay.gif" alt="Multi-day trip replay — one continuous journey"><br>
<a href="docs/assets/trip-replay.mp4">Watch full →</a>
</td>
</tr>
<tr>
<td width="50%">
<b>📊 Annual Wrapped</b><br>
Spotify-Wrapped-style share cards, 9:16, fully self-hosted. Nights witnessed by
GPS, kilograms lifted, cities photographed.
<img src="docs/assets/wrapped-2026.jpg" alt="2026 annual wrapped — 5 share cards">
</td>
<td width="50%">
<b>🗓️ Weekly Review</b><br>
Every Monday, a card lands in your chat: commute times, step rhythm, training
volume, resting HR trend. Generated by a cron job through the same MCP tools an
external agent would use.
<img src="docs/assets/weekly-review.jpg" alt="Weekly review — commute, rhythm, training, body">
</td>
</tr>
</table>

Every one of these is a **demo**, not a walled garden. All data flows through
the same seven MCP tools listed below.

## Quick start

```bash
pip install lifedb            # or: pipx install lifedb

life-db init                            # create your timeline.db
life-db ingest events.jsonl             # unified JSONL contract, idempotent
life-db query 2026-10                   # one month, every modality
life-db around 2026-10-13T09:00 --window 2h   # what happened around then
life-db stats                           # coverage & counts
```

Connect your agent (Claude Desktop / Claude Code / any MCP client):

```json
{
  "mcpServers": {
    "lifedb": {
      "command": "lifedb-mcp",
      "env": { "LIFEDB_DB": "/path/to/timeline.db" }
    }
  }
}
```

### MCP tool surface (v0.1)

| Tool | What it gives your agent |
|---|---|
| `lifedb_stats` | Schema version, modality counts, time coverage |
| `lifedb_query_month` | Full timeline for a month |
| `lifedb_around` | Cross-modal events around any moment |
| `lifedb_geo_track` | Raw GPS track for any window (map rendering) |
| `lifedb_export_atlas` | One-stop pack: track + events + photos |
| `lifedb_ingest_jsonl` | The only write path — idempotent, dry-run by default |
| `lifedb_adapters` | Discover installed data-source plugins |

Tools only grow, never change or disappear — that's the contract.

## Data sources

Adapters are **plugins**: one JSON manifest + one script, discovered
automatically. Currently supported:

| Source | Data | Mode |
|---|---|---|
| Phone GPS tracks | 11 years of second-level points | periodic |
| 训记 (xunji) | Strength workouts: sets, volume, movements | periodic |
| Apple Health export | Sleep, workout routes, ECG, metrics | manual |
| Google Timeline | Stays & segments | manual |
| Photo libraries | EXIF GPS → photo layer | manual |
| iCloud sync | Automated download pipeline | periodic |

**Wanted — PRs welcome:** Hevy / Strong / Strava CSV · GPX / FIT ·
Google Takeout (new Records.json) · Obsidian vault · Keep / Mi Fitness /
Huawei Health · Garmin export. See [docs/PRODUCT.md](docs/PRODUCT.md) §3.3
for the interface contract — a manifest and a script is all it takes.

## Architecture

```
Your agent        Claude / Cursor / anything that speaks MCP
    ⬇  stdio (localhost only)
MCP server        lifedb-mcp — the contract (7 tools, no arbitrary SQL)
    ⬇
Kernel            SQLite timeline.db + unified JSONL import layer + CLI
    ⬇
Your data         phone GPS · workouts · health · photos · timeline
```

## Docs

- [Product vision & roadmap](docs/PRODUCT.md) — architecture, wanted adapters, phases
- [Kernel design](docs/DESIGN.md) · [Ingestion guide](docs/INGESTION.md)
- [PRD (feature specs)](docs/PRD-lifedb-visual-app.md)

## License

MIT — see [LICENSE](LICENSE).