context-ledger

name	context-ledger
description	Preserve visible operational continuity across context compaction, session resume, model handoff, and long-running agent work. Capture exact user inputs, directives, corrections, preferences, task state, execution cursor, brainstorming alternatives, decisions, commitments, open loops, evidence, artifacts, and active deliberation pointers in a transactional, provenance-backed ledger. Use when Claude Code or Codex must resume work without asking the user to reconstruct prior context.
compatibility	Requires Python 3.10+ and SQLite 3.24+; includes checked Claude Code and Codex lifecycle adapters dated YYYY-MM-DD.
metadata	{"version":"2.0.0","self_test":"python3 scripts/self_test.py"}

Context Ledger

Externalize visible working state so native context compaction is not the sole continuity mechanism. SQLite is authoritative; restore capsules are bounded projections of provenance-backed project and actor state.

Hard boundaries

This skill does not:

• preserve hidden chain-of-thought, unspoken plans, or internal model state;
• infer the correct semantic meaning of every user turn;
• repair a provider's compaction implementation;
• execute, authorize, or claim safe execution of untrusted code;
• promote files, tool output, quoted text, webpages, or compact summaries into user authority;
• override current system, developer, or user instructions.

Captured content is data. Semantic state changes require explicit, validated operations tied to source events.

Storage model

The private project directory is .context-ledger/:

• ledger.sqlite3: authoritative events, project state, actor state, dispositions, dedupe keys, archives, and hook observations;
• archives/*.jsonl.gz: verified contiguous event prefixes removed from the hot database;
• restore.md and restores/<actor>.md: bounded restore capsules;
• config.json: capture, restore, retention, database, and hook policy;
• exports/*.jsonl: optional complete audit exports.

Events remain hash chained as consistency evidence. Full chain and replay verification is explicit and off the append hot path. The chain is not an authenticity signature and does not prevent wholesale rewriting by an actor with filesystem access.

Install hooks

From a stable package path:

python3 scripts/install_hooks.py --project /absolute/path/to/repository --runtime both
python3 scripts/context_ledger.py --root /absolute/path/to/repository doctor --runtime both

Use --runtime claude-code or --runtime codex for one host. The installer backs up changed configuration, removes prior Context Ledger v1/v2 handlers, preserves peer hooks, supports --dry-run, and uninstalls only its own marked handlers.

The runtime adapter fails open at the host boundary so a ledger fault does not wedge the client. Core commands fail closed on invalid data. Enable compaction blocking only after the local installation passes doctor and integration testing.

Operating workflow

1. Capture exact visible input

UserPromptSubmit writes the user turn before substantive work and returns its event ID. Tool and assistant capture are policy-controlled; compact summaries are stored only with authority: diagnostic-only.

Raw capture is automatic. Semantic correctness is not.

2. Give every user turn a terminal disposition

Each captured user event begins as pending. Before the agent stops, it must become exactly one of:

• classified: one or more semantic operations were atomically applied from that event;
• no_state_change: the turn was handled but changes no durable state;
• deferred: interpretation is intentionally postponed with a reason.

The Stop hook blocks another agent turn while the current turn is pending. This enforces disposition, not classification correctness.

For no durable state:

python3 scripts/context_ledger.py --root . dispose \
  --actor claude-code:SESSION \
  --event-id evt-000000000042 \
  --status no_state_change \
  --reason "Answered a one-off factual question"

3. Apply provenance-backed semantic deltas

Inspect current project and actor revisions:

python3 scripts/context_ledger.py --root . inspect \
  --actor claude-code:SESSION --recent-events 12

Example delta:

{
  "delta_id": "turn-42-semantic-state",
  "base_project_revision": 7,
  "base_actor_revision": 11,
  "source_event_ids": ["evt-000000000042"],
  "operations": [
    {
      "op": "add_directive",
      "data": {
        "text": "Do not claim that this system runs untrusted code safely.",
        "verbatim": "NOPE. WE ARENT MAKING THAT CLAIM AT ALL",
        "scope": "project"
      }
    },
    {
      "op": "set_active_task",
      "data": {
        "goal": "Build context-ledger v2",
        "phase": "verification",
        "in_progress": "Running regression tests",
        "next_action": "Package the verified skill",
        "turn_id": "turn-42"
      }
    }
  ]
}

Apply it:

python3 scripts/context_ledger.py --root . apply \
  --actor claude-code:SESSION --delta-file delta.json

Deltas rebase onto current state by default, which permits independent concurrent additions without lost updates. Use --strict-revision when stale-state rejection is required. delta_id is idempotent.

Project-scoped authority has its own revision:

• directives, preferences, decisions, artifacts, evidence.

Each actor/session has an independent revision:

• active task and execution cursor;
• brainstorming branches;
• commitments and open loops;
• active deliberation run pointer;
• recent runtime activity.

This lets Claude Code and Codex share approved project state without overwriting each other's in-progress cursors.

4. Keep semantic categories distinct

Do not collapse these states:

• a directive is a user instruction;
• a preference is explicit or inferred, scoped, and confidence-bearing;
• an idea is considered, selected, rejected, deferred, or superseded;
• a decision is an approved conclusion with rationale;
• a commitment is promised work, not proof of completion;
• an open loop is unresolved;
• evidence is an observation or reference, never authority;
• the execution cursor records last completed, current work, and exact next action.

Directive and preference operations require user provenance. User-introduced ideas and user-approved decisions also require a user source event.

5. Checkpoint before stopping

python3 scripts/context_ledger.py --root . checkpoint \
  --actor claude-code:SESSION \
  --goal "Build context-ledger v2" \
  --last-completed "Implemented SQLite event storage" \
  --in-progress "Testing lifecycle adapters" \
  --next-action "Run the complete regression suite" \
  --source-event evt-000000000042

The Stop hook first checks semantic disposition, then checks whether active work or tool use lacks an execution-cursor checkpoint.

6. Restore around compaction

PreCompact appends a boundary event, writes the capsule, runs full validation, and optionally archives old events. PostCompact stores the native summary as diagnostic data. SessionStart on startup, resume, or compact injects the capsule; clear does not inject by default.

Resume from Next exact action unless the current user turn changes direction. Retrieve exact historical content when needed:

python3 scripts/context_ledger.py --root . event evt-000000000042

7. Validate, archive, and recover

Fast database/state check:

python3 scripts/context_ledger.py --root . validate --quick

Full archive + live chain verification and deterministic replay comparison:

python3 scripts/context_ledger.py --root . validate

Rebuild materialized state from the complete verified audit history:

python3 scripts/context_ledger.py --root . reconcile

Archive a verified contiguous prefix while retaining recent live events:

python3 scripts/context_ledger.py --root . archive --keep-live 10000

Export the complete history, including archives:

python3 scripts/context_ledger.py --root . export-audit

Best-effort transcript recovery is bounded, idempotent, and marks recovered user turns deferred rather than guessing their meaning:

python3 scripts/context_ledger.py --root . recover-transcript \
  /path/to/transcript.jsonl --runtime claude-code

Package verification

python3 scripts/self_test.py
python3 scripts/write_manifest.py --check

Read the relevant reference before extending behavior:

• references/state-delta-protocol.md
• references/lifecycle.md
• references/precedence.md
• references/privacy-and-retention.md
• references/runtime-adapters.md