Getting started

Install Lifeline, run the loop, and bootstrap an existing project. Git for reasoning, in minutes.

Lifeline is a context runtime for AI-assisted development — git for reasoning. It keeps an append-only, content-addressed, anchored ledger of your project's why and delivers it to any AI over MCP, so a fresh model connects and already knows.

Install

pip install lifeline-context        # the lifeline CLI + lifeline-mcp server
pip install -e .                    # from the repo root (dev)
pip install -e ".[cloud]"           # optional: cloud mode (Supabase)
pip install -e ".[embeddings]"      # optional: dense semantic recall

Dependencies: pydantic, aiosqlite, mcp, httpx. Python ≥ 3.10. The core is local and needs no extra dependencies for recall (BM25 over SQLite's FTS5) — the dense semantic embedder and real token counts ([embeddings], [tokens]) are opt-in extras. Licensed FSL-1.1-MIT (source-available; converts to MIT after two years).

Quickstart (CLI)

Each project gets its own .lifeline/ledger.db:

lifeline log --kind bootstrap --summary "Bootstrap project X" --body "Multi-tenant billing API."
lifeline log --kind decision  --summary "DB: PostgreSQL"      --body "ACID required by audit."

lifeline context                    # the assembled current truth (what an AI reads)
lifeline context --query "database" # prioritizes what's relevant to the task
lifeline checkpoint --thread main --next "wire the queue" --tried "SQS FIFO — cap too low"   # where you stopped
lifeline resume                     # the next AI (or you, after compaction) continues from here
lifeline verify                     # checks the chain's integrity → OK

LIFELINE.md regenerates on every log — don't hand-edit it. On a fresh clone without .lifeline/, rebuild the cache with lifeline migrate --from LIFELINE.md.

The loop (do both sides)

• On connect — and after any context compaction: load the context (lifeline context or the lifeline_context tool) and resume (lifeline resume / lifeline_resume) before acting.
• While working: on each meaningful decision / fix / incident, append (lifeline log or lifeline_append). Reversed something? lifeline_recontextualize supersedes it by id.
• Before stopping, when blocked, when a step completes: checkpoint (lifeline checkpoint / lifeline_checkpoint) — the next AI continues from next. lifeline install-hooks claude-code makes both sides automatic: context at every start, a guard that asks for the checkpoint at stop.

Watch the loop run — 60 seconds

Three scenes, all real outputs from this repo's own ledger (no mockups): a fresh AI connects and already knows the what/why/decided/next · a merged PR drafts its own context proposal (you curate) · lifeline exam proves the health with a number.

Connect it to your AI

Lifeline ships a local MCP server (lifeline-mcp, stdio). On connect, the AI gets the tools lifeline_context, lifeline_resume, lifeline_brief (a scoped brief for a sub-agent), lifeline_recall, lifeline_checkpoint and the write tools lifeline_append / lifeline_recontextualize — which propose by default (a human approves) unless the project's write policy grants that agent direct, audited writes. lifeline init writes the config; Claude Code reads .mcp.json automatically:

{ "mcpServers": { "lifeline": {
    "command": "lifeline-mcp", "args": [],
    "env": { "LIFELINE_DB": ".lifeline/ledger.db" } } } }

Cursor, Claude Desktop, and Gemini CLI use copy-paste snippets — see Integration. Web chat apps (claude.ai, ChatGPT) need a remote server + OAuth — see MCP & remote.

Adopting mid-project (brownfield)

Lifeline records the why going forward — it never reconstructs it from your code or git history. So a fresh install on a live project starts empty. Run lifeline init (it writes .mcp.json and the write policy, and prints the three lines that bootstrap the line), or just connect your AI — the empty context tells it to offer a one-time bootstrap, human-in-the-loop:

1. Read the reasoning docs you already wrote (README, ADRs, PR descriptions). The why is never inferred from code or diffs.
2. Ask 3–7 short why-questions — only the tacit reasoning that isn't written down.
3. Propose granular entries: 1 bootstrap + N decision + M open. You approve the batch. Nothing enters unapproved.

After that, the loop runs forward.

Local → cloud (graduation)

Everything is content-addressed, so pushing a local line to the cloud is lossless and idempotent — same ids, re-seed dedupes itself.

lifeline --store supabase migrate --from LIFELINE.md   # seed (repeatable — no dupes)
lifeline --store supabase context                       # operate against the cloud

Just want to share the text (no cloud)? lifeline push syncs the view through git.