Lifeline

The project's reasoning ledger. It records why the project is what it is — and any AI, in any session, on any provider, connects and already knows. The next one resumes where the last one stopped.

🌐 English · Português

"git for reasoning." git versions what changed; Lifeline versions why — decisions, reversals, open threads, where work stopped — in an append-only ledger that lives inside the repo. Every line an AI reads carries the id of the entry it came from, so it can verify instead of trust. It's for people who work with more than one model, run long agentic sessions, or need to prove where a decision came from.

Try it in 60 seconds

pip install lifeline-context
cd your-project
lifeline init            # writes .mcp.json + the write policy; prints the three lines below

lifeline log --kind bootstrap --summary "Aurora — payments gateway for LATAM" --body "PIX, cards and boleto for marketplaces; multi-tenant from day one."
lifeline log --kind decision  --summary "Database: PostgreSQL" --body "The audit trail needs cross-row ACID; MongoDB was rejected for that."
lifeline log --kind open      --summary "Queue: SQS vs RabbitMQ" --body "Decide after the load test on the PIX path."
lifeline checkpoint --thread <open-id> --next "run the load test on the PIX path" --tried "SQS FIFO — the 300 msg/s cap is too low"
lifeline context

lifeline context prints what a fresh AI reads. This is the real output of the commands above:

# Lifeline — project context
**What:** Aurora — payments gateway for LATAM  _(founded by none/human)_

## Why / what's decided (decisions in force)
- **Database: PostgreSQL** `[e1c29a26]` — _none/human_
  > The audit trail needs cross-row ACID; MongoDB was rejected for that.

## Open / next
- `[02f8c3f9]` Queue: SQS vs RabbitMQ — _next: run the load test on the PIX path_

## Resume (where work stopped)
- **Queue: SQS vs RabbitMQ** `[3a70bac7]` — _claude-code/claude-fable-5-1_, 2026-09-14
  next:
    - run the load test on the PIX path
  tried:
    - SQS FIFO — the 300 msg/s cap is too low

## Recent (what's next)
- [bootstrap] Aurora — payments gateway for LATAM
- [decision] Database: PostgreSQL
- [open] Queue: SQS vs RabbitMQ
- [checkpoint] checkpoint Queue: SQS vs RabbitMQ: next — run the load test on the PIX path

_4 entries · head 3a70bac7_

Decisions first (the part a provider's prompt cache can reuse), then what's open, where work stopped, and what's recent. Under a budget the oldest and the newest decisions survive and the middle is omitted with its ids — nothing is dropped silently.

LIFELINE.md regenerates on every write; don't hand-edit it. lifeline verify proves the chain; lifeline exam scores how ready the ledger leaves a fresh AI (0–100).

Connect your AI

lifeline init wrote .mcp.json, so Claude Code connects automatically; Cursor, Claude Desktop and Gemini CLI use the same stdio server (lifeline-mcp) — snippets in docs/INTEGRATION.md. Discipline is a mechanism, not a reminder:

lifeline install-hooks claude-code   # SessionStart: context + Resume at every start and after compaction
                                     # Stop: if the tree changed and the line didn't, asks once for a checkpoint
lifeline install-rules               # the loop in CLAUDE.md, AGENTS.md, GEMINI.md, .cursor/rules, copilot-instructions
lifeline install-hooks git           # pre-push: code commits after the last entry and nothing recorded → push fails

What the AI gets on connect:

Plus lifeline_recall (relevance, reverted hits marked) and the write tools lifeline_append / lifeline_recontextualize, which propose by default: a human approves before anything becomes truth, unless the project's write policy grants an agent direct, audited writes. The server also tells every connecting AI how to behave — no prompt to write.

The loop

• On connect, and after any compaction: read the context, then resume.
• While working: on each meaningful decision, feature, fix or incident, append the why (lifeline log … or lifeline_append). Reversed something? lifeline_recontextualize supersedes it by id — the past is never edited.
• Before stopping, when blocked, when a step completes: checkpoint. The next AI — the same session after compaction, or a different model tomorrow — continues from next.
• Delegating: give the sub-agent lifeline_brief(task_or_thread) and have it write back on the same thread.

Adopting mid-project? Lifeline records the why going forward; it never reconstructs it from code or git history. Connect your AI to the empty line: it reads your docs, asks a few why-questions and proposes granular entries you approve. One session, and the loop runs.

Learn more

• docs/CLI.md — every command, generated from the CLI itself (lifeline --help is grouped the same way).
• docs/GUIDE.md — the write policy, kinds, lines vs threads and the mesh, the Python SDK, local → cloud.
• docs/ARCHITECTURE.md — the event model, the three layers, what 0.6 changed.
• CLAUDE.md — the 7 laws and the non-goals. AGENTS.md — onboarding for any AI.
• Curate well — how to keep the ledger signal, not noise.
• CHANGELOG.md · LIFELINE.md, this repo's own ledger — start at #0001.

Status

Beta. 0.6.0 is on PyPI — long horizon: checkpoints and resume, threads and briefs, the write policy, the mesh of lines, BM25 recall, provider envelopes, hooks. The local core is solid and test-locked; cloud mode (Supabase, remote MCP with OAuth) is live-validated. Honest limits: recall is BM25 (accent-insensitive, PT↔EN synonyms), not semantic — a dense embedder is opt-in; token budgets are estimates unless you install [tokens]; the mesh of lines is local to .lifeline/.

Built by dogfooding, and license

Lifeline was rebuilt using itself from entry #0001: every decision, reversal and checkpoint is in LIFELINE.md, and 0.6 was planned, built and resumed through it. The rule for contributors is the same: if you touched it, append to the line (CONTRIBUTING.md).

License: FSL-1.1-MIT — source-available; use, modify and self-host it for anything except offering it as a competing service; converts to MIT two years after each release (≤ 0.2.0 stays MIT). The paid layer is the hosted hub, not the code.