Continuity Ledgers System

The Continuity Ledgers System is a core component of Continuous Claude designed to preserve high-fidelity session state across environment clears. Claude Code's native context compaction is often lossy; this system provides a mechanism to "clear instead of compact" by saving state to external Markdown files known as Ledgers. These ledgers allow a user to wipe the session context clean and reload it with full fidelity, ensuring that reasoning, decisions, and progress are not lost as the context window fills.

Sources: CLAUDE_ONBOARDING.md:12-20, CLAUDE_ONBOARDING.md:139-142

Architecture and Data Flow

The system operates by capturing the "ephemeral" session state and persisting it into a structured Markdown format. This data is then indexed into a local SQLite database to facilitate cross-session retrieval and analysis.

The Session Lifecycle

The ledger system integrates directly into the session management workflow. When context usage reaches approximately 70%, the system prompts or requires a ledger update before a /clear command is issued.

The diagram shows the standard progression from session initialization through the context-clearing loop enabled by ledgers.
Sources: CLAUDE_ONBOARDING.md:32-37, CLAUDE_ONBOARDING.md:104-106

Data Structure and Schema

Ledgers are stored as Markdown files with a specific naming convention: CONTINUITY_CLAUDE-<session>.md. These files are parsed and stored in the Context Graph database.

Ledger Document Structure

A standard continuity ledger includes several mandatory sections to ensure comprehensive state capture:

Sources: scripts/artifact_index.py:273-294, tests/test_artifact_index.py:65-79

Database Schema (SQLite)

The system uses an FTS5-enabled SQLite database located at .claude/cache/artifact-index/context.db to index these ledgers.

The ER diagram illustrates the relationship between the primary storage table and the virtual FTS5 table used for full-text searching.
Sources: scripts/artifact_schema.sql:56-71, scripts/artifact_schema.sql:89-93

Components and Logic

Indexing Engine

The artifact_index.py script handles the transformation of Markdown ledgers into structured database rows. It utilizes regex to parse session names from filenames and extracts specific task markers (like [x] for completed tasks).

# Example logic for parsing state items
# Sources: scripts/artifact_index.py:285-294
for line in state.split("\n"):
    if "[x]" in line.lower():
        state_done.append(line.strip())
    elif "[->]" in line or "now:" in line.lower():
        state_now = line.strip()
    elif "[ ]" in line or "next:" in line.lower():
        state_next = line.strip()

Sources: scripts/artifact_index.py:272-306

Initialization and Setup

The init-project.sh script prepares the environment for the Continuity Ledger system. It creates the necessary directory structure and initializes the SQLite database using artifact_schema.sql.

• Fresh Mode: Creates thoughts/ledgers in the local project.
• Monorepo Mode: Symlinks to a parent directory's thoughts/ folder to share context across sub-projects.

Sources: init-project.sh:122-138, init-project.sh:178-185

Hierarchical Context Retrieval

During session analysis or learning extraction, the system performs "Hierarchical Context" lookups. The braintrust_analyze.py script queries the Context Graph to find the ledger associated with a specific Braintrust trace ID. This ensures that analysis is grounded in the user's stated goals rather than just tool call logs.

Sources: scripts/braintrust_analyze.py:180-210, scripts/braintrust_analyze.py:539-550

Key System Constraints

• Update Timing: Ledgers MUST be updated before a /clear operation, not after.
• Focus: Ledgers should ideally contain only one "Now" item to maintain focus.
• Unconfirmed State: The system encourages using the UNCONFIRMED prefix for items that need verification immediately after a session clear.
• Storage: Ledgers are permanent/tracked in Git (within thoughts/ledgers/), while the search index is gitignored in the .claude/cache/ directory.

Sources: CLAUDE_ONBOARDING.md:104-106, init-project.sh:205-212, scripts/artifact_schema.sql:1-10

Summary

The Continuity Ledgers System acts as the "long-term memory" for Claude Code sessions. By externalizing state into structured Markdown files and indexing them in a local SQLite database, the system allows for infinite session length through periodic context clearing without the degradation typically associated with LLM context compaction. It ensures that goals, learnings, and decisions are preserved and searchable across the entire project lifecycle.

Sources: CLAUDE_ONBOARDING.md:12-25, scripts/artifact_schema.sql:2-8