LAYER 1
Ledger
Immutable, content-addressed entries chained in a DAG. The source of truth. id = sha256(content + parents).
[#0001] bootstrap · the context runtime
Git for reasoning.
Your project remembers why it is what it is — and any AI connects and already knows. An append-only, content-addressed, anchored ledger of decisions, delivered over MCP. No human re-explaining. Ever.
[problem] the memory bus is human
AIs are stateless
across sessions.
Every new session, agent, or provider, you become the memory bus — re-explaining decisions that already existed. The naive fix (a living markdown log) works until it blows past the context window. And "memory" tools store text or vectors with no provenance → hallucinated recall.
The cost isn't tokens. It's that the why evaporates the moment the window scrolls.
[north-star] time-to-context → 0
One metric.
One acceptance test.
A fresh AI connects, with no human in the loop, and correctly answers: what / why / what's decided / what's next?
Lifeline keeps the project's lifeline queryable, compressible, and anchored — so it never overflows the window and never invents recall. The why outweighs the what.
[proof] not a mockup · this repo is its own ledger
A fresh AI connects.
This is what it reads.
The context a fresh AI reads from this very repo — what / why / decided / next, assembled to a budget. Every line anchored to its event id; built by AIs + a human from #0001.
# Lifeline — project context · 107 entries · head f252d9f1 # built by claude-opus · claude-fable · human — every line anchored ## Why / what's decided (12 in force) - Hash v2: injective content-addressing — no id collisions [e9a37ea2] - Adopt Supabase's native OAuth Server as the AS; we are the RS [04ac751c] ## Open / next - [open] F3: revenue activation — team lines, billing $ lifeline exam Context Health: 100/100 (A) — integrity · why-density · ttc-probe
The site you're reading dogfoods itself. Live ledger → LIFELINE.md · ▶ watch the 60s loop
[architecture] three layers, one anchor
An event-sourced
reasoning ledger.
LAYER 2
State
Pure reducers fold the stream into the current truth. Status is a projection, not a state machine. Corrections supersede.
LAYER 3
Recall
Relevance search where every hit is anchored to its source event. Lexical by default; dense embeddings opt-in.
[constitution] seven non-negotiable laws
The invariants.
01No memory without an immutable anchor. Every item carries its source event's hash. The anti-hallucination spine.
02Append-only. Corrections are new entries referencing the prior id. The past is never edited.
03Deterministic content-addressing. Same content + parents → same id, on any machine.
04Provider-agnostic storage; deliver in the provider's format.
05The why outweighs the what.
06Budget is first-class. Context fits the window; truncation is always explicit.
07MCP-native. The AI's interface is the product surface.
[the-loop] read on connect · append on work
Do both sides.
CONNECT
Load the context before acting
Run lifeline context or read the MCP resource lifeline://project/context. It's the assembled current truth.
WORK
Append on each meaningful decision
lifeline log or lifeline_append. Reversed something? lifeline_recontextualize supersedes it by id.
# in any project — each gets its own .lifeline/ledger.db lifeline log --kind decision --summary "DB: PostgreSQL" --body "ACID required by audit." lifeline context # what an AI reads lifeline verify # the chain is tamper-evident → OK
[#0070] adopting mid-project
Already deep in
a project? Bootstrap it.
Lifeline records the why going forward — it never guesses it from your code or git history. So on a live project, run lifeline init (or just connect your AI). It runs a one-time context checkpoint, human-in-the-loop:
01 · READ
Your reasoning docs
The AI reads README, ADRs, PR descriptions — never infers the why from code (Laws 1 & 5).
02 · ASK
3–7 why-questions
Only the tacit reasoning that isn't written down anywhere. Short. Targeted.
03 · PROPOSE
Granular entries
1 bootstrap + N decisions + M open threads, as proposals. You approve the batch. Nothing enters unapproved.
[mcp-native] the interface is the product
Connect it to
your AI.
Lifeline ships a local MCP server (lifeline-mcp). On connect, the AI gets the context resource + tools — and write tools are HITL: they propose, a human approves. Claude Code reads .mcp.json automatically.
{ "mcpServers": { "lifeline": {
"command": "lifeline-mcp",
"env": { "LIFELINE_DB": ".lifeline/ledger.db" } } } }
[distribution] no MCP required for the read
Your AI already reads it.
It lives in the repo.
The ledger projects to a plain LIFELINE.md committed in your repo. So any AI that can read the repo already inherits your why — Gemini, ChatGPT, Claude, Copilot, Cursor — with no MCP, no OAuth, no per-vendor setup.
MCP is the live surface — relevance recall, propose-to-approve, always current. But the floor is zero-friction: the file travels with the clone. Point any model at the repo and ask it why. That's the whole onboarding.
[docs] the whole manual
Read everything.
Getting started →Install, the loop, brownfield bootstrap.
Concepts & laws →Entries, the 3 layers, supersession.
Architecture →Event model, reducers, projection.
Integration →Wire it into Claude, Cursor, Gemini.
MCP & remote →stdio, HTTP/SSE, OAuth resource server.
CLI reference →Every command, end to end.
vs alternatives →ADRs, RAG, memory MCPs — and when not to.
Curate well →Keep the ledger signal; avoid rot.