Context Capsules

Git stores what changed. Context Capsules stores why.

Durable, project-owned memory for the intent, decisions, and reasoning behind your code.
Local-first, open, and shared by every human and every AI tool that touches the repo.

Context should belong to the project, not the tool.

You've felt this before

You explain the project to your AI agent. Again. You open a new chat and re-paste the same three paragraphs of background. Again. A teammate asks "wait, why did we do it this way?" and the honest answer is "someone explained it to me on a call in March, ask them."

• The decision your team debated for an hour, then forgot to write down anywhere durable.
• The constraint a newcomer (human or agent) will violate on day one, because nobody told them it exists.
• The thing you already tried that didn't work, so nobody wastes another week trying it again.
• The cold start, repeated every session, every tool switch, every new hire.

None of that lives in your code. Git only remembers what changed. The reasoning, the why, is scattered across chat windows, Slack threads, PR comments, and people's heads, and it quietly evaporates.

The thesis

AI coding tools have memory for a session. Projects need memory for years.

Your code already has a source of truth that outlives any person, branch, or tool: it's called Git. The reasoning behind your code has no equivalent. Context Capsules is that missing source of truth: owned by the project, readable and writable by anyone and anything working on it.

Why everything else falls short

Each tool you already use holds a fragment of the answer. None of them holds the answer.

The insight

We solved source control for code. We never solved source control for context.

The single most valuable artifact in a software project, the accumulated reasoning behind it, is also the most fragile. It's the first thing lost between sessions and the last thing anyone writes down.

The fix isn't another doc, another wiki, or a smarter chat search. It's a new primitive: a durable, project-owned memory that lives next to the code, captures the why the moment a decision is made, and is read by every tool before it acts.

That primitive is a Context Capsule.

What Context Capsules is

Context Capsules is an open standard and a local-first system for durable project memory. Today it ships as a CLI called capsule, built on four properties:

Local-first No account, no telemetry, no SaaS. Lives in your repo, not a vendor's database.

Append-only A durable ledger of intent, decisions, questions, resolutions, and progress. Nothing is ever rewritten.

Evidence-checked Decisions can cite a file, commit, test, or URL. The engine confirms it exists: locally, deterministically.

Tool-agnostic One standard, versioned independently of any vendor. Cursor, Claude Code, Codex, or a human at a terminal: same record.

The CLI is the first implementation of the idea, not the idea itself. The product is the primitive: a place where a project's reasoning is captured once and reused everywhere.

How it works

A capsule is a single append-only log of typed events, stored as .capsule/log.jsonl. Every human and every agent reads and writes the same log.

flowchart LR
    Dev["Developer<br/>at a terminal"] -->|capsule record / load| CLI(("capsule CLI"))
    Agent["AI agent<br/>Cursor · Claude Code · Codex"] -->|capsule record / load| CLI
    CLI --> Log[["log.jsonl<br/>append-only source of truth"]]
    Log --> Fold{{fold}}
    Fold --> Render["capsule.md<br/>regenerable render"]
    Log -.versioned by.-> Git[("git history")]

Five event types capture the parts of project memory that nothing else records:

Two more, task_start / task_end, optionally wrap a unit of work end-to-end (see capsule task).

Decisions and progress can cite evidence: a file:, commit:, test:, or url: reference. The engine checks each one for existence only, locally and deterministically:

sequenceDiagram
    participant You as You (or an agent)
    participant CLI as capsule CLI
    participant Verify as Evidence verifier
    participant Log as log.jsonl
    You->>CLI: capsule record decision --evidence file:auth/google.py
    CLI->>Verify: does auth/google.py exist?
    Verify-->>CLI: yes → verified: true / no → verified: false
    CLI->>Log: append event (never rewritten)
    Log-->>You: capsule.md re-rendered

It confirms the thing you cited is real; it never judges whether the code is correct. A missing reference is recorded as data, never raised as an error: verified: false is a fact about the world, not a bug in the tool.

Reading the log folds it into a current-state view (capsule load / capsule show). Writing to it only ever appends: an "edit" is a new event, so history is never rewritten and the record stays honest.

Quickstart

# Initialize empty capsule storage under .capsule/
capsule init

# Start of every session: a human or an agent reads the current state of the project
capsule load

# Capture a decision the moment it's made, with evidence
capsule record decision \
  --decision "Use OAuth2 authorization-code flow" \
  --rationale "server-side secret; no token in the browser" \
  --evidence file:auth/google.py \
  --by cursor

That's the whole loop: load at the start, record as you go. A week later, in a different tool, on a different machine, capsule load brings the reasoning straight back.

Who it's for

Installation

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
capsule --version

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
capsule --version

If capsule isn't on your PATH, use python -m capsule instead. On macOS, the system Python is often older than 3.11; install a newer interpreter with Homebrew or pyenv first.

Commands

Technical details

By default, capsule data lives at:

your-project/
  .capsule/
    log.jsonl     # append-only source of truth (UTF-8 JSONL, one event per line)
    capsule.md    # regenerable human-readable render
    .lock         # transient advisory lock

• log.jsonl is the source of truth. Events are immutable and append-only. Nothing is ever rewritten in place.
• capsule.md is a render. Regenerated by folding the log, never read back as truth.
• Local-first. Zero network I/O: no telemetry, no phone-home, no API calls. The CLI and core engine stay on-device.
• Crash-safe. Writes are atomic. An interrupted append leaves a recoverable "torn" tail that's quarantined automatically on the next write, instead of corrupting history.
• Forward-compatible. Unknown fields are preserved and round-tripped, so the format can evolve without breaking older logs.

Because capsule data is just files in the working tree, Git versions it for free: git log .capsule/log.jsonl is its durable, shareable history.

Documentation

Contributing

Issues, discussions, and PRs are genuinely welcome; this is an early-stage, alpha-quality project and the easiest way to shape it is to use it and tell us where it breaks.

If this solved a problem you've personally felt, a star helps other people find it before they reinvent it badly.

Git remembers what changed. Now your project can remember why.

License

Apache License 2.0.