Chain of Consciousness
Cryptographic provenance protocol for AI agents. Tamper-evident, hash-linked logs that prove what your agent did, learned, and decided.
What is Agent Provenance?
As AI agents become more autonomous — making decisions, learning, and taking actions — there's no standard way to prove what actually happened. Agent provenance is a cryptographic record of an agent's lifecycle: every action, decision, and learning event linked in an unbreakable SHA-256 hash chain.
Chain of Consciousness gives your agents a verifiable memory. Anyone can audit the chain and confirm that no entries were added, removed, or modified after the fact.
Install
pip install chain-of-consciousness
Quickstart
from chain_of_consciousness import Chain
chain = Chain("my-agent", storage="chain.jsonl")
chain.add("LEARN", {"topic": "cryptography", "source": "web"})
chain.add("DECIDE", {"decision": "deploy v2", "confidence": 0.95})
result = chain.verify()
print(result) # VerifyResult(valid=True, entries=3, errors=[])
That's it. Five lines. Zero dependencies.
Features
- Zero required dependencies — Core chain + verification uses only Python stdlib (SHA-256 from
hashlib). - Tamper-evident — Each entry's hash includes the previous entry's hash. Change one byte, the entire chain breaks.
- Multi-agent support — Multiple agents can write to the same chain file, each identified by name.
- Session continuity — Forward commitments link sessions together, proving nothing was lost between restarts.
- Optional timestamping — Anchor your chain to Bitcoin (OpenTimestamps) or RFC 3161 TSAs for independent proof of time.
- Export & share — Export chains as JSON for independent verification.
- CLI included —
coccommand for terminal-based chain management.
API Reference
Chain(agent, storage=None)
Create or load a provenance chain.
| Parameter | Type | Description |
|---|---|---|
agent |
str |
Name identifying the agent writing to this chain |
storage |
str | None |
Path to a JSONL file for persistence. None = in-memory only |
chain.add(event_type, data, *, commitment=None, verification=None)
Append a new entry. Returns a ChainEntry.
| Parameter | Type | Description |
|---|---|---|
event_type |
str |
Category: boot, learn, decide, create, milestone, anchor, error, note, session_start, session_end, compaction, governance, or any custom type |
data |
str | dict | list |
Payload. Non-strings are JSON-serialized |
commitment |
str | None |
SHA-256 forward commitment (for session_end) |
verification |
str | None |
SHA-256 bootstrap verification (for session_start) |
chain.verify() -> VerifyResult
Verify full chain integrity. Checks hash linkage, data hashes, sequence numbering, and genesis block.
result = chain.verify()
result.valid # bool — True if chain is intact
result.entries # int — total entry count
result.errors # list[str] — empty if valid
result.agents # dict — {agent_name: entry_count}
result.types # dict — {event_type: count}
result.anchors # list — timestamps of anchor entries
chain.export(path)
Export the chain to a JSON array file for sharing or independent verification.
verify_file(path) -> VerifyResult
Verify a chain file (JSONL or JSON array format) without loading it into a Chain object.
from chain_of_consciousness import verify_file
result = verify_file("their_chain.json")
chain.entries -> list[ChainEntry]
Read-only list of all entries.
chain.latest -> ChainEntry | None
The most recent entry.
len(chain) -> int
Number of entries in the chain.
CLI
The package installs a coc command:
# Create a new chain
coc init --agent my-agent --file chain.jsonl
# Add entries
coc add learn '{"topic": "security"}' --file chain.jsonl
coc add decide "deploy to production" --file chain.jsonl
# Verify integrity
coc verify chain.jsonl
coc verify chain.jsonl --json
# Show status
coc status chain.jsonl
# Show recent entries
coc tail chain.jsonl -n 10
# Export to JSON
coc export --file chain.jsonl --out chain.json
Anchoring (Optional)
Anchor your chain to external timestamping authorities for independent proof of existence.
pip install chain-of-consciousness[anchoring]
RFC 3161 TSA (no extra deps needed)
from chain_of_consciousness.anchor import compute_chain_hash, submit_tsa, parse_tsr_status
chain_hash = compute_chain_hash("chain.jsonl")
tsr_bytes = submit_tsa(chain_hash)
status = parse_tsr_status(tsr_bytes)
print(status["status_text"]) # "granted"
OpenTimestamps / Bitcoin
from chain_of_consciousness.anchor import compute_chain_hash, submit_ots
chain_hash = compute_chain_hash("chain.jsonl")
ots_proof = submit_ots(chain_hash)
with open("chain.ots", "wb") as f:
f.write(ots_proof)
Chain Entry Format
Each entry in the JSONL file is a JSON object:
{
"seq": 1,
"ts": "2026-03-21T12:00:00+00:00",
"type": "learn",
"agent": "my-agent",
"data": "{\"topic\":\"cryptography\"}",
"data_hash": "a1b2c3...",
"prev_hash": "d4e5f6...",
"entry_hash": "789abc...",
"schema_version": "1.1"
}
Hash computation: entry_hash = SHA-256(seq|ts|type|agent|data_hash|prev_hash)
This means every entry is cryptographically bound to:
- Its position in the chain (seq)
- When it was created (ts)
- What happened (type + data_hash)
- Everything before it (prev_hash)
Whitepaper
For the full protocol specification, design rationale, and anchoring architecture, see the Chain of Consciousness whitepaper.
Verification Demo
Try the interactive verification demo at vibeagentmaking.com/verify.
License
Apache 2.0. See LICENSE.
Metadata
Release files for chain-of-consciousness 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| chain_of_consciousness-0.1.1.tar.gz | 23.2 kB | Without provenance | Details for chain_of_consciousness-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| chain_of_consciousness-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for chain_of_consciousness-0.1.1-py3-none-any.whl |
Total release size: 43.3 kB
Release files / chain_of_consciousness-0.1.1.tar.gz
| Download URL | chain_of_consciousness-0.1.1.tar.gz |
|---|---|
| Size | 23.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c6b00281fe8ab820aac632e66617a00eda0b89d318e675a1c5ea5bc5fbaebda8
|
|
BLAKE2b-256 checksum How to use checksums |
1d4c8a80c8512edd70fbe8a7527d315fa5b4ecbc7de675b20b56122d455cc153
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Release files / chain_of_consciousness-0.1.1-py3-none-any.whl
| Download URL | chain_of_consciousness-0.1.1-py3-none-any.whl |
|---|---|
| Size | 20.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2f07d979fb79a9f2d287888ad8b480dc57dcf2c3086b1ca69717e0e2cdf9aede
|
|
BLAKE2b-256 checksum How to use checksums |
715962838cf055e742dfab8156400116a8f3ffb7680f3710e4c723a2c96db0fe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.14.3
|
Security for chain-of-consciousness 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.