Metadata-Version: 2.4
Name: lifedb
Version: 0.1.0
Summary: Local-first personal timeline DB — locations, photos, workouts, sleep on one time axis. Your data never leaves your machine.
License: MIT License
        
        Copyright (c) 2026 LifeDB contributors
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/SPA3K/lifedb
Project-URL: Repository, https://github.com/SPA3K/lifedb
Project-URL: Issues, https://github.com/SPA3K/lifedb/issues
Keywords: lifelog,timeline,quantified-self,mcp,local-first,sqlite
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Database
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=1.0
Dynamic: license-file

<div align="center">

# LifeDB

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

[![GitHub stars](https://img.shields.io/github/stars/SPA3K/lifedb?style=flat&logo=github&label=stars)](https://github.com/SPA3K/lifedb/stargazers)
[![GitHub forks](https://img.shields.io/github/forks/SPA3K/lifedb?style=flat&logo=github&label=forks)](https://github.com/SPA3K/lifedb/network/members)
[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)

> “一切你无法喂给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 git+https://github.com/SPA3K/lifedb.git   # PyPI package coming soon
# or: pipx install git+https://github.com/SPA3K/lifedb.git
```

```bash
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)

## ⭐ Star it

If your AI agent can finally see your life — star the repo. It's the only
distribution a local-first, zero-marketing project gets.

**Want an adapter that's missing?** Open an issue or grab one from the
wanted list above — a manifest and a script is all it takes.

## License

MIT — see [LICENSE](LICENSE).
