TxnMem

TxnMem is a transactional shared-memory service for concurrent agent teams. It gives facts, constraints, resources, commitments, evidence, and commutative values explicit update semantics. Every accepted history can be replayed from an append-only event log and checked against a deterministic serial interpreter.

The repository includes the service, the MemoryRace concurrency benchmark, eleven baseline configurations, fault injection, an authenticated API, a command line interface, a PostgreSQL adapter, a bounded semantic-serializability checker, and an interactive trace lab.

This is a research prototype. It makes no claim of novelty, priority, or production readiness. A complete literature review and an independent replication are required before using the artifacts in a publication.

Why this exists

Agent memory is often treated as a text retrieval problem. Shared memory changes the failure model. Two individually reasonable updates can lose information, overbook a resource, revive a retracted claim, or complete a dependent task too early.

TxnMem makes those transitions explicit:

1. An agent begins from a versioned snapshot
2. Reads capture record revisions
3. Typed operations are staged without changing canonical state
4. Local preconditions are checked
5. Noncommutative stale reads are classified as conflicts
6. Only declared commutative values merge automatically
7. Global invariants run inside the atomic commit boundary
8. The state update and event records commit together
9. Unsafe rebases remain proposals until an authorized principal approves them

What is implemented

Surface	Current implementation
Canonical operations	Facts, constraints, resources, commitments, evidence, and commutative values
Isolation	Snapshot reads with optimistic validation over declared read and write sets
Storage	Deterministic SQLite mode and a PostgreSQL single-primary adapter
Recovery	Append-only operations, idempotency fingerprints, replayable snapshots, and audit records
Conflicts	Syntactic and semantic certificates with deterministic rebase candidates
Checker	Exhaustive serial-order search for bounded histories and dependency-graph checking for larger histories
Benchmark	30-task offline smoke set and deterministic generation of 180 full tasks
Baselines	Last writer wins, append all, summary surrogate, mutex, database serial, two CRDT variants, CAS only, two TxnMem variants, and oracle serial
Interfaces	FastAPI, CLI, Docker Compose, and an interactive trace viewer
Verification	Unit, property, authorization, API, benchmark, fault, frontend render, and PostgreSQL integration tests

Quick start

Python 3.11 or newer is required.

python -m venv .venv
python -m pip install -e ".[dev]"
python -m pytest

Run the deterministic smoke benchmark:

txnmem run-race --config configs/smoke.yaml --output runs/smoke

Start the API:

txnmem serve --host 127.0.0.1 --port 8000

Open http://127.0.0.1:8000/docs. The built-in development credential is txnmem-local-research-key. It is only for local use. Configure a secret-backed key registry before exposing the API.

Run the trace lab:

npm ci
npm run dev

For PostgreSQL:

docker compose up --build

The API is available at http://127.0.0.1:8000.

Protocol example

fromtxnmemimportTransactionEnginefromtxnmem.modelsimportAddFactengine=TransactionEngine()
transaction=engine.begin("planner")
operation=AddFact(
transaction_id=transaction.transaction_id,
principal="planner",
base_version=transaction.base_version,
target="trip:budget",
value={"currency": "EUR", "amount": 900},
idempotency_key="trip-budget-initial-v1",
)
engine.stage(transaction.transaction_id, operation)
report=engine.validate(transaction.transaction_id)
result=engine.commit(transaction.transaction_id)

Canonical state never accepts an arbitrary database query or an untyped model summary. Model output may propose an operation, but the operation must pass schema, authorization, revision, and invariant checks before commit.

Architecture

flowchart LR
A["Agent or deterministic worker"] --> B["Typed API and authorization"]
B --> C["Snapshot and staged transaction"]
C --> D["Conflict classifier"]
D --> E["Deterministic invariant gate"]
E --> F["SQLite or PostgreSQL CAS commit"]
F --> G["Canonical state"]
F --> H["Append-only event and audit log"]
H --> I["Replay and semantic serial checker"]
I --> J["Witness or violation certificate"]

Loading

The Python reference interpreter is the source of truth for state transitions. The browser trace lab mirrors selected protocol paths for exploration and does not replace raw experiment artifacts.

Isolation and failure boundaries

TxnMem provides snapshot reads and optimistic serializable commits for operations whose relevant dependencies are present in the declared read and write sets. It also validates deterministic cross-key domain invariants inside the storage transaction.

The current deployment model is a single primary database. It does not claim distributed linearizability, Byzantine fault tolerance, or safe operation through a multi-primary network partition. See docs/consistency.md for the exact contract.

MemoryRace

The committed smoke set contains 30 typed tasks across six conflict families:

• Independent commuting writes
• Same-key revision races
• Resource overbooking
• Retraction versus evidence use
• Duplicate delivery
• Commitment dependency ordering

configs/smoke.yaml runs ten deterministic interleavings per task. configs/full.yaml generates 180 tasks and twenty interleavings per task. Every run records its seed, configuration, operation programs, outcomes, final projection, and checker result.

Current smoke result

The checked artifact in artifacts/smoke contains 30 tasks, 10 interleavings per task, and 300 paired runs per baseline. It was produced on a local single-process SQLite setup.

Protocol	Semantic serializability	Invariant violation	Mean ops/s	p95 commit latency
TxnMem	1.000	0.000	2,925.7	0.692 ms
Global mutex	1.000	0.000	2,830.6	0.620 ms
CAS only	0.833	0.103	4,896.6	0.397 ms
Last writer wins	0.500	0.270	3,971.3	0.457 ms

These measurements validate the harness, not a general performance claim. In this run TxnMem has slightly higher mean throughput than the mutex and higher p95 latency. The result is not enough to establish a speed advantage. PostgreSQL contention sweeps, confidence intervals across machines, and held-out conflict structures remain required.

The raw result, generated table, bootstrap summary, and correctness-throughput plot live under artifacts/smoke and paper.

Reproducing an artifact

txnmem generate-tasks \
--count 30 \
--seed 20260727 \
--output benchmarks/memoryrace-smoke.json
txnmem run-race \
--config configs/smoke.yaml \
--output artifacts/smoke
python scripts/build_paper_artifacts.py

To check a captured history:

txnmem check --history path/to/history.json

To replay a run:

txnmem replay \
--manifest artifacts/smoke/manifest.json \
--output runs/replay

Repository map

src/txnmem/ protocol, state, storage, checker, benchmark, API, CLI
app/ interactive trace lab
benchmarks/ committed MemoryRace smoke tasks
configs/ reproducible benchmark configurations
formal/ bounded TLA+ model
tests/ Python, API, property, integration, and frontend tests
artifacts/smoke/ checked raw smoke result and manifest
paper/ claims, analysis plan, tables, figures, and checklist
docs/ protocol, consistency, threat model, and data cards

Research integrity

The repository does not include private papers, copied figures, third-party benchmark archives, or text presented as original scholarship. It separates implemented behavior, measured observations, hypotheses, and future work. Claims in paper/claims/claims.yaml are marked by evidence status.

Before submission, authors must complete an independent related-work review, add all work that materially influenced the research question or implementation, rerun the full evaluation on documented infrastructure, and retain negative results.

Security

The development API key is intentionally obvious and unsafe for deployment. Production users must replace it with a secret-managed registry, terminate TLS at a trusted boundary, restrict origins, and review per-principal operation scopes.

Report vulnerabilities through the process in SECURITY.md. Do not include secrets or sensitive memory contents in a public issue.

License

TxnMem is available under the MIT License.