Metadata-Version: 2.4
Name: lifeline-context
Version: 0.6.1
Summary: A context runtime for AI development — the project records why it is what it is; any AI connects and already knows.
Author: jessianmart
License: FSL-1.1-MIT
Project-URL: Homepage, https://lifelinecontext.com
Project-URL: Repository, https://github.com/lifeline-context/lifeline
Project-URL: Issues, https://github.com/lifeline-context/lifeline/issues
Project-URL: Changelog, https://github.com/lifeline-context/lifeline/blob/main/CHANGELOG.md
Project-URL: Documentation, https://github.com/lifeline-context/lifeline/blob/main/docs/INTEGRATION.md
Keywords: mcp,ai,llm,context,memory,ledger,agents,claude,provenance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.0
Requires-Dist: aiosqlite>=0.19
Requires-Dist: mcp>=1.20
Requires-Dist: httpx>=0.27
Provides-Extra: cloud
Requires-Dist: httpx>=0.27; extra == "cloud"
Provides-Extra: embeddings
Requires-Dist: sentence-transformers>=2; extra == "embeddings"
Provides-Extra: tokens
Requires-Dist: tiktoken>=0.7; extra == "tokens"
Provides-Extra: remote
Requires-Dist: python-multipart>=0.0.9; extra == "remote"
Requires-Dist: PyJWT[crypto]>=2.10.1; extra == "remote"
Requires-Dist: starlette>=0.27; extra == "remote"
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# 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](README.pt-BR.md)

[![pypi](https://img.shields.io/pypi/v/lifeline-context)](https://pypi.org/project/lifeline-context/) ![status](https://img.shields.io/badge/status-beta-blue) ![python](https://img.shields.io/badge/python-3.10%2B-blue) ![tests](https://img.shields.io/badge/tests-319%20passing-brightgreen) ![license](https://img.shields.io/badge/license-FSL--1.1--MIT-blue)

**"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

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

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

```text
# 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](docs/INTEGRATION.md). Discipline is a mechanism, not a reminder:

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

| Tool | What it does |
|---|---|
| `lifeline_context` | the assembled truth — what / why / decided / next (with `query`, `thread`, `budget`) |
| `lifeline_resume` | where work stopped: the live checkpoint of each thread |
| `lifeline_brief` | the scoped, anchored brief to hand a sub-agent — any provider |
| `lifeline_checkpoint` | record working state (done / next / blocked / tried) — direct, audited |

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](docs/GUIDE.md#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](docs/CLI.md) — every command, generated from the CLI itself (`lifeline --help` is grouped the same way).
- [docs/GUIDE.md](docs/GUIDE.md) — the write policy, kinds, lines vs threads and the mesh, the Python SDK, local → cloud.
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — the event model, the three layers, what 0.6 changed.
- [CLAUDE.md](CLAUDE.md) — the 7 laws and the non-goals. [AGENTS.md](AGENTS.md) — onboarding for any AI.
- [Curate well](https://lifelinecontext.com/curate.html) — how to keep the ledger signal, not noise.
- [CHANGELOG.md](CHANGELOG.md) · [LIFELINE.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](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](CONTRIBUTING.md)).

**License:** [FSL-1.1-MIT](LICENSE) — 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.
