# Lineleaf

> Context lineage and invalidation for AI agents. Lineleaf records how every memory, embedding, summary, cached answer and agent plan was derived. When a source is erased, poisoned or corrected, you can see the blast radius, repair only what is affected, and prove it with a signed receipt.

Status: design partner preview · v0.1 spec. The interface below is the specification being built with design partners. Package names are reserved: PyPI `lineleaf`, npm `@lineleaf/sdk`.

## The problem

Memory is write-optimized. One fact fans out into an embedding, a graph edge, a summary, a cached answer and an agent's next action. When the source changes, gets erased, or turns out poisoned, nothing in a typical stack knows what else is now wrong. Deleting the source leaves its descendants in place ("backflow").

## Triggers

- `reason="gdpr_erasure"`: right to erasure (GDPR Art. 17). Purge what was derived only from the source, rebuild what still has valid parents, mark dependent agents stale, issue a signed erasure receipt.
- `reason="poison_detected"`: memory and context poisoning (OWASP ASI06). Map the blast radius across shared memory, purge tainted records and vectors, halt running plans with a staleness webhook.
- `reason="source_changed"`: a correction (stale world model). Rebuild affected records from the new source, evict caches, leave unrelated memories untouched.

## Operations (v0.1 spec)

- `derive(output, inputs, op, ttl=None)`: record an edge from each input to the output. Writes lineage only.
- `invalidate(source, reason)` → `Plan`: a dry run. `plan.affected` lists every descendant with a proposed action (purge, rebuild, mark stale, review). Nothing is touched until `plan.execute()`, which returns a receipt.
- `why(artifact)`: the path from any artifact back to its sources, with operations, models, times and attribution.

## Zero-code capture (v0.1 spec)

Middleware for LangGraph, MCP servers and OpenTelemetry (`gen_ai.*` spans) records `tool_output → context → memory_write` edges automatically, without `derive()` calls.

## Architecture

Lineleaf runs beside your application. Writes go to your stores unchanged. Lineleaf keeps a ledger of identifiers, edges and sha256 fingerprints, never the content. Invalidation acts through adapters (planned: Mem0, Zep/Graphiti, Letta, LangGraph, pgvector, Pinecone, Redis) and notifies running agents with `lineage.stale` webhooks carrying a directive (`halt` or `replan`).

## Receipts

Every executed plan produces a receipt: one row per action, each row's sha256 committing to the previous row (genesis = sha256(source | reason | issued_at)), signed with ES256. A store that cannot confirm a delete is recorded as `needs_review`, not "done". Schema: https://lineleaf.dev/developers#receipts

## Links

- [Product](https://lineleaf.dev/product): blast-radius inspector, plans, rebuilds, receipts, explainability
- [Developers](https://lineleaf.dev/developers): the v0.1 spec, covering the SDK, middleware, data model, adapters, receipts and webhooks
- [Research](https://lineleaf.dev/research): truth maintenance, agentic unlearning, memory poisoning, context attribution
- [Design partner program](https://lineleaf.dev/design-partners)
- Contact: hello@lineleaf.dev