ESDB — Epistemic State Database¶

specsmith ships two ESDB backends: a free SQLite backend (default, MIT) and the commercial ChronoStore backend (chronomemory, requires a license).

Licensing at a glance¶

	SQLite backend	ChronoStore backend
Package	Built into `specsmith`	`chronomemory` — install via `specsmith[esdb]`
License	MIT — free, no restrictions	Proprietary — commercial license required
Install	`pip install specsmith` (automatic)	`pip install "specsmith[esdb]"` + license key
Default?	✅ Yes — active out of the box	❌ No — must be explicitly installed and activated
Storage	`.specsmith/esdb.sqlite3`	`.chronomemory/events.wal`
SHA-256 WAL chain	—	✅
OEA anti-hallucination fields	partial	✅ full (H15–H22)
Rust acceleration	—	✅
Epistemic rollback	—	✅

In short: every pip install specsmith includes the SQLite backend for free. Install specsmith[esdb] and activate a license only when you need ChronoStore's cryptographic audit trail, full OEA fields, or Rust acceleration.

What is ESDB?¶

The Epistemic State Database is how specsmith persists governance state across sessions. It stores requirements, test cases, decisions, and audit records with metadata that answers questions regular databases cannot:

Was this observed directly, inferred, or hypothesised? (source_type)
How confident is this record? (confidence 0.0–1.0)
What assumptions were in scope when this was written? (epistemic_boundary)
Was this generated by an agent acting on another agent's output? (recursion_depth)
Has anyone tampered with past records? (hash chain)

These fields — derived from the OEA (Ontological Epistemic Anchoring) framework implemented in specsmith's anti-hallucination rules H15–H22 — make ESDB records safe for RAG injection: only records with confidence >= 0.6 and status = active pass the RAG filter.

SQLite backend (default, free, MIT)¶

No installation or license needed. specsmith uses this automatically.

Storage: <project_root>/.specsmith/esdb.sqlite3

What it stores: - Requirements and test cases (synced from YAML or Markdown sources) - Record ID, kind, status, label, confidence, and raw data blob - Tombstones for deleted records (never physically deleted)

Limitations vs ChronoStore: - No SHA-256 WAL hash chain — integrity relies on SQLite ACID, not cryptographic proof - No per-record OEA fields (H15–H22) — confidence is stored but without the full epistemic envelope - No Rust acceleration, dependency graph, context-pack compiler, or epistemic rollback - SQLite file is not human-readable without a SQLite viewer (WAL is NDJSON in ChronoStore)

Check status:

specsmith esdb status

ChronoStore backend (commercial, requires license)¶

ChronoStore is the full Epistemic State Database engine from chronomemory. It is a commercial add-on that requires a valid license from Layer1Labs.

Storage: <project_root>/.chronomemory/events.wal (human-readable NDJSON)

What ChronoStore adds over SQLite¶

Capability	SQLite (free)	ChronoStore (commercial)
Stores requirements & test cases	✓	✓
Confidence filtering (RAG H18)	✓	✓
ACID integrity	✓	✓
SHA-256 WAL hash chain	—	✓ tamper-evident
OEA anti-hallucination fields (H15–H22)	partial	✓ full
Rust-accelerated backend	—	✓ optional
Context-pack compiler	—	✓
Dependency graph (DepGraph)	—	✓
Epistemic rollback	—	✓
WAL replay & audit	—	✓
Human-readable WAL (NDJSON, grep-able)	—	✓
Tamper detection (`chain_valid()`)	—	✓
Record provenance (`source_type`)	—	✓
Model assumption tracking (H21)	—	✓
Recursion depth guard (H16)	—	✓

When to use ChronoStore¶

ChronoStore is the right choice when:

You need cryptographic proof that past governance records were not altered (compliance, audit trails)
You are building multi-agent pipelines where agent outputs need provenance tracking
You need epistemic rollback — reverting the belief state to an earlier point in time
You want a human-readable WAL (cat .chronomemory/events.wal | python -m json.tool)
Performance matters and you want the Rust-accelerated backend (_chronomemory_rust)
You need the context-pack compiler to generate minimal verified context for LLM prompts

SQLite is sufficient when you just need persistence of requirements and test cases between sessions without advanced governance features.

Licensing¶

SQLite backend — MIT, free, always included¶

The SQLite backend is MIT licensed and ships inside specsmith — no separate package, no license key, no configuration required. It is active by default the moment you run pip install specsmith.

ChronoStore backend — proprietary, commercial license required¶

chronomemory is a separate commercial package. A valid Ed25519-signed license key issued by Layer1Labs is required to use it. specsmith enforces this with an offline license check — no internet connection is needed once the license is activated.

The chronomemory package is available on PyPI. Installation (Step 1 below) downloads it like any other PyPI package. The license key (Step 2) is the technical and legal gate.

Obtain a license:

Channel	Details
Email	licensing@layer1labs.com
Web	layer1labs.com/esdb-licensing
Legal terms	chronomemory LICENSE · COMMERCIAL-LICENSE.md

Installation¶

SQLite backend — nothing to do¶

The SQLite backend is built into specsmith. Confirm it is active:

specsmith esdb status
# ● ESDB — SQLite (free, MIT) — /your/project/.specsmith/esdb.sqlite3
#   Records: 0
#   ✔ Integrity OK
#   chronomemory not installed — run 'pip install specsmith[esdb]' for ChronoStore

No further setup is required.

ChronoStore backend — step-by-step¶

Prerequisite: you must hold a valid chronomemory ESDB license. Contact licensing@layer1labs.com to obtain one.

Step 1 — install the chronomemory package

Choose the method that matches how you installed specsmith:

# If you installed specsmith via pip:
pip install "specsmith[esdb]"

# If you installed specsmith via pipx (recommended for CLI use):
pipx inject specsmith "chronomemory>=0.1.7"

Verify the package is present:

python -c "import chronomemory; print(chronomemory.__version__)"

Step 2 — activate your license key

specsmith esdb enable --key-file /path/to/your-org.esdb.key
# ✔ License key validated and installed at ~/.specsmith/esdb.key
# ✔ License: your-org (expires YYYY-MM-DD)

The key is copied to ~/.specsmith/esdb.key. Every subsequent specsmith command automatically uses ChronoStore as long as the key is present and valid.

Step 3 — verify ChronoStore is active

specsmith esdb status
# ● ESDB — ChronoStore WAL (chronomemory commercial)
#   Records: 0
#   ✔ Integrity OK
#   ✔ License: your-org (expires YYYY-MM-DD)

Force SQLite without removing the license (useful in CI environments):

export SPECSMITH_ESDB_BACKEND=sqlite
specsmith esdb status   # confirms SQLite is active despite license being present

CLI reference¶

`specsmith esdb status`¶

Shows the active backend, license status, and record counts.

● ESDB — SQLite (free, MIT) — /path/to/.specsmith/esdb.sqlite3
  Records: 646
    requirement: 321
    testcase: 325
  ✔ Integrity OK
  chronomemory not installed — run 'pip install specsmith[esdb]' for ChronoStore

With ChronoStore active and licensed:

● ESDB — ChronoStore WAL (chronomemory commercial)
  Records: 646
    requirement: 321
    testcase: 325
  ✔ Integrity OK
  ✔ License: acme-corp (expires 2027-06-11)

`specsmith esdb enable --key-file <path>`¶

Validates the Ed25519 signature on the provided license file and installs it at ~/.specsmith/esdb.key. After this command, ChronoStore is automatically selected on every subsequent invocation (if chronomemory is installed).

specsmith esdb enable --key-file ~/Downloads/acme-corp.esdb.key

`specsmith esdb migrate`¶

Validates .specsmith/requirements.json and .specsmith/testcases.json and migrates them into the active ESDB backend (SQLite or ChronoStore). Run this once when first setting up ESDB in an existing project.

specsmith esdb migrate

`specsmith esdb status --json`¶

JSON output for scripting and CI:

{
  "backend": "sqlite",
  "backend_label": "SQLite (free, MIT) — /project/.specsmith/esdb.sqlite3",
  "record_count": 646,
  "chain_valid": true,
  "counts": {"requirement": 321, "testcase": 325},
  "license": {"chronomemory_installed": false, "active": false}
}

Python API¶

SQLite backend¶

from specsmith.esdb.sqlite_store import SqliteStore, SqliteRecord

with SqliteStore("/path/to/project") as store:
    store.upsert(SqliteRecord(
        id="REQ-001",
        kind="requirement",
        label="The system SHALL ...",
        confidence=0.95,
    ))
    reqs = store.query(kind="requirement", rag_filter=True)
    print(store.record_count())

Backend-agnostic (recommended)¶

open_default_store() returns the correct backend based on the license gate:

from specsmith.esdb import open_default_store, ESDB_BACKEND

with open_default_store("/path/to/project") as store:
    print(f"Using {ESDB_BACKEND} backend")
    reqs = store.query(kind="requirement")

ChronoStore (when licensed)¶

from specsmith.esdb import ChronoStore, ChronoRecord

with ChronoStore("/path/to/project") as store:
    store.upsert(ChronoRecord(
        id="REQ-001",
        kind="requirement",
        label="...",
        source_type="observed",
        confidence=0.95,
        evidence=["REQUIREMENTS.md §2"],
        epistemic_boundary=["platform:linux", "version:1.0"],
    ))
    context = store.query(rag_filter=True)   # H18: confidence >= 0.6 only
    assert store.chain_valid()               # tamper detection

Migration from legacy JSON¶

If your project previously used the flat .specsmith/requirements.json format (before ESDB was introduced), migrate with:

specsmith esdb migrate

This imports all requirements and test cases into the active backend (SQLite or ChronoStore) and writes a migration manifest at .specsmith/esdb_migration_manifest.json.

The migration is idempotent — running it multiple times updates existing records without creating duplicates.

chronomemory availability and distribution¶

chronomemory v0.1.2+ is available on PyPI. pip install specsmith[esdb] resolves it cleanly with no git dependency:

pip install "specsmith[esdb]"
# resolves chronomemory>=0.1.2 from PyPI — no git required

The package carries a proprietary commercial license. PyPI does not restrict non-open-source packages — the license key gate in specsmith (specsmith esdb enable) is the technical enforcement; the chronomemory LICENSE and COMMERCIAL-LICENSE.md govern the legal terms.

Using the `epistemic` library without pipx¶

epistemic ships inside the specsmith wheel and is immediately importable after pip install specsmith in any Python 3.10+ environment — no pipx required:

# After: pip install specsmith
from epistemic import AEESession, BeliefArtifact, StressTester, CertaintyEngine
from specsmith.esdb import SqliteStore, open_default_store, ESDB_BACKEND

The pipx-only guard applies only to the specsmith CLI command, not to library imports. This makes it straightforward to embed the AEE belief-state machinery in any application or data pipeline without managing a dedicated pipx environment.

To use ChronoStore in your own application (library-only, no CLI):

from specsmith.esdb import open_default_store, ESDB_BACKEND

# Place license at ~/.specsmith/esdb.key or set SPECSMITH_ESDB_KEY
with open_default_store("/path/to/project") as store:
    print(f"Backend: {ESDB_BACKEND}")
    recs = store.query(kind="requirement", rag_filter=True)

Environment variables¶

Variable	Effect
`SPECSMITH_ESDB_BACKEND=sqlite`	Force SQLite regardless of license
`SPECSMITH_ESDB_KEY=/path/to/key`	Override license file location