# How the LoopX Event-Ledger Preserves Compact Evidence Across Multiple Agent Sessions

> Discover how the LoopX event-ledger creates immutable audit trails using compact evidence references and deterministic upserts, ensuring thread-safe data across agent sessions.

- Repository: [huangruiteng/loopx](https://github.com/huangruiteng/loopx)
- Tags: internals
- Published: 2026-09-02

---

**The LoopX event-ledger uses domain-scoped JSON-Lines files with deterministic upsert logic to store compact evidence references rather than full payloads, enabling immutable, thread-safe audit trails across concurrent and restarted agent sessions.**

The event-ledger implementation in the `huangruiteng/loopx` repository provides autonomous agents with a lightweight persistence layer designed for multi-session continuity. By storing only essential metadata and cryptographic references to evidence, the system ensures that agent decision trails remain portable and verifiable without accumulating storage bloat across iterative runs.

## Domain-Scoped Ledger Architecture

The event-ledger organizes evidence into isolated domain states to prevent cross-contamination between different goals and capabilities.

### File Path Construction

Each ledger file resides in a hidden directory structure scoped by the agent's current goal and capability. The helper function `default_ml_experiment_domain_state_ledger_path` constructs paths following the pattern:

```

<tmp_dir>/.loopx/domain-state/<goal>/ml_experiment/ledger.jsonl

```

This convention ensures that evidence from distinct agent objectives remains physically separated while maintaining a consistent naming scheme. According to the source in [`tests/test_ml_experiment_volc_packet.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_ml_experiment_volc_packet.py) at line 227, this path construction guarantees that resumed sessions targeting the same goal automatically locate their historical context.

## Compact Evidence Storage Model

Rather than serializing complete output artifacts, the ledger stores compact references that point to external storage, minimizing I/O overhead and file size.

### Evidence References vs. Full Payloads

Each ledger entry deliberately omits full payloads in favor of **evidence_refs**—typically SHA-256 hashes or URLs representing the canonical location of the complete evidence. This design choice ensures that the JSON-Lines file remains small enough to parse quickly while still allowing full reconstruction of the agent's decision trail when needed.

### Row Schema Structure

As implemented in [`loopx/ledger.py`](https://github.com/huangruiteng/loopx/blob/main/loopx/ledger.py), each row adheres to a strict schema containing:

- **classification**: A categorical label (e.g., "improvement", "regression")
- **summary**: A human-readable description of the event
- **evidence_refs**: A list of cryptographic hashes or URIs pointing to full artifacts

This structure enables subsequent agent sessions to rapidly scan historical decisions without downloading large binary objects.

## Session Continuity via Upsert Semantics

The ledger guarantees idempotency across multiple sessions through append-only operations with built-in deduplication.

### Idempotent Append Operations

The core function `upsert_ml_experiment_ledger_jsonl` implements an **append-only** strategy where new rows are added to the end of the file while existing rows sharing the same domain key (goal + capability + unique identifier) are automatically deduplicated. This mechanism, verified in [`tests/test_ml_experiment_volc_packet.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_ml_experiment_volc_packet.py) at lines 161-179, ensures that concurrent writes from parallel agent processes produce consistent, non-duplicative results.

### Legacy Row Cleanup

When older ledger entries lack proper domain key scoping, the upsert routine automatically filters them out during the write operation. The test suite at lines 190-219 validates this legacy-row removal, ensuring that only well-formed, traceable evidence survives across session restarts.

## Concurrency and Immutability Guarantees

The event-ledger provides hard guarantees against race conditions and retroactive tampering.

### Thread-Safe Concurrent Writes

The implementation supports high-concurrency scenarios where multiple agent threads or processes attempt simultaneous ledger updates. As demonstrated in [`tests/test_ml_experiment_volc_packet.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_ml_experiment_volc_packet.py) lines 260-279, the system spawns parallel writers and confirms that the final ledger contains exactly the expected set of deduplicated rows without data corruption.

### Terminal Session Protection

Once an agent run reaches a terminal state, the ledger becomes immutable. The test `test_closed_run_rejects_every_ledger_mutation` in [`tests/test_deepresearch_command.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_deepresearch_command.py) (lines 834-902) asserts that any mutation attempt on a closed session raises an exception, preserving the integrity of the evidence trail recorded up to that point.

## Practical Implementation

The following examples demonstrate how to interact with the event-ledger in production scenarios.

### Writing Compact Evidence

```python
import json
from loopx.ledger import upsert_ml_experiment_ledger_jsonl
from loopx.domain_state import default_ml_experiment_domain_state_ledger_path

# Construct the domain-scoped ledger path

ledger_path = default_ml_experiment_domain_state_ledger_path(
    tmp_path="/tmp/agent_runs",
    goal="improve-accuracy",
    capability="ml_experiment"
)

# Build a compact ledger entry with evidence references

payload = {
    "experiment_id": "exp-42",
    "objective": "improve-accuracy",
    "classification": "improvement",
    "summary": "Accuracy increased from 84% to 88%",
    "evidence_refs": ["sha256:abcd1234...efgh5678"]
}

# Append with automatic deduplication

upsert_ml_experiment_ledger_jsonl(ledger_path, payload)

```

### Reading Cross-Session Evidence

```python

# A subsequent agent session reads the ledger

with open(ledger_path, "r", encoding="utf-8") as f:
    rows = [json.loads(line) for line in f]

for row in rows:
    print(f"Decision: {row['summary']}")
    # Dereference evidence_refs to load full artifacts if needed

```

### Concurrent Safe Writes

```python
from concurrent.futures import ThreadPoolExecutor

def write_evidence(payload):
    """Thread-safe write operation."""
    upsert_ml_experiment_ledger_jsonl(ledger_path, payload)

# Parallel agents writing simultaneously

with ThreadPoolExecutor(max_workers=8) as executor:
    executor.map(write_evidence, list_of_payloads)

```

## Summary

- **Domain-scoped storage**: Ledger files isolate evidence by goal and capability under `.loopx/domain-state` directories.
- **Compact references**: The system stores only hashes and metadata, avoiding payload bloat while maintaining traceability.
- **Idempotent upserts**: The `upsert_ml_experiment_ledger_jsonl` function deduplicates entries by domain key, enabling safe concurrent writes.
- **Legacy cleanup**: Orphaned rows without domain keys are automatically pruned during upsert operations.
- **Immutability guarantees**: Terminal sessions lock the ledger against further modifications, ensuring audit integrity.

## Frequently Asked Questions

### What is the LoopX event-ledger?

The LoopX event-ledger is an append-only JSON-Lines persistence layer that records agent decisions using compact evidence references rather than full artifacts. It enables autonomous agents to maintain continuous audit trails across multiple sessions and concurrent executions.

### How does the ledger prevent duplicate entries across sessions?

The `upsert_ml_experiment_ledger_jsonl` function implements deterministic deduplication based on domain keys—a composite of the goal, capability, and unique identifier. When a session writes an entry that matches an existing row, the ledger automatically removes the stale version and appends the updated record, ensuring idempotency.

### Can multiple agents write to the same ledger simultaneously?

Yes. The ledger I/O layer is thread-safe and supports concurrent writes from parallel agent processes. The test suite validates this by spawning eight simultaneous writers and verifying that the final file contains exactly one copy of each unique entry without corruption.

### What happens to ledger data when an agent session terminates?

Once a session is marked terminal (closed), the ledger enforces read-only access. As verified in [`tests/test_deepresearch_command.py`](https://github.com/huangruiteng/loopx/blob/main/tests/test_deepresearch_command.py), any subsequent mutation attempts raise exceptions, preserving the immutable evidence trail established during the active session.