chain_of_consciousness

# Chain of Consciousness (CoC)

You have a cryptographic provenance system. Use it to maintain an auditable record of your work — what you learned, what you decided, and what you created.

## Setup

The `chain-of-consciousness` Python package must be installed. If not available, install it:

```bash
pip install chain-of-consciousness
```

## When to Use This Skill

- At the **start** of a task: initialize a chain and log `session_start`
- During work: log `learn`, `decide`, `create`, `error`, and `note` events as they happen
- At task **completion**: log `session_end` and optionally verify + export the chain
- When asked to **verify** provenance from another agent
- When asked about your **audit trail** or decision history

## Core Operations

### Initialize a Chain

```bash
coc init --agent "your-agent-name" --file chain.jsonl
```

This creates a new chain with a genesis block. Use a descriptive agent name.

### Add Entries

```bash
coc add <event-type> "<data>" --file chain.jsonl
```

**Event types:**

| Type | Use When |
|------|----------|
| `session_start` | Beginning a new task or session |
| `learn` | You acquire new information |
| `decide` | You make a choice (record the reasoning) |
| `create` | You produce an artifact |
| `milestone` | Significant checkpoint reached |
| `error` | Something failed (record what and recovery) |
| `note` | General observations |
| `session_end` | Completing a task or session |

**Data** can be a plain string or a JSON object for structured logging:

```bash
coc add learn '{"topic": "user preferences", "source": "conversation context"}'
coc add decide "Chose markdown format — user prefers readable plain text"
coc add create "Generated report saved to ~/Documents/report.md"
```

### Verify a Chain

```bash
coc verify chain.jsonl --json
```

This checks:
- Genesis block exists and is correctly formed
- All sequence numbers are consecutive
- Every entry's data hash matches its content
- Every entry's prev_hash links to the prior entry
- Entry hashes are correctly computed

Report results clearly: valid/invalid, entry count, agents, time span.

### Check Status

```bash
coc status chain.jsonl
```

Shows entry count, participating agents, event type distribution, and time span.

### Export for Sharing

```bash
coc export --file chain.jsonl --out chain_export.json
```

Exports the chain as a portable JSON array that anyone can verify.

### View Recent Entries

```bash
coc tail chain.jsonl -n 5
```

Shows the last N entries.

## Python API (Advanced)

For complex workflows, use the Python API directly:

```python
from chain_of_consciousness import Chain, verify_file

chain = Chain(agent="openclaw-agent", storage="chain.jsonl")
chain.add("learn", {"topic": "user schedule", "detail": "prefers morning meetings"})
chain.add("decide", "Scheduling standup at 9am based on user preference")

result = chain.verify()
if result.valid:
    chain.export("provenance.json")
```

### Anchoring to External Timestamps

```python
from chain_of_consciousness.anchor import compute_chain_hash, submit_tsa

hash_hex = compute_chain_hash("chain.jsonl")
tsr = submit_tsa(hash_hex)  # RFC 3161 timestamp from freetsa.org
with open("anchor.tsr", "wb") as f:
    f.write(tsr)
```

This creates a third-party timestamp proof that the chain existed at a specific moment.

## Cross-Agent Verification

When asked to verify another agent's chain:

1. Obtain their chain file (JSONL or exported JSON)
2. Run `coc verify <file> --json`
3. Report: valid/invalid, number of entries, agents involved, time span, any errors
4. If anchors exist, note their timestamps

## Rules

- **Never edit chain files directly.** All writes must go through the `coc` CLI or Python API to preserve hash integrity.
- **Log decisions with reasoning.** "Chose X" is less valuable than "Chose X because Y."
- **Keep entries concise.** Each entry should capture one atomic event.
- **Verify before sharing.** Always run verify before exporting a chain for others.

## Links

- PyPI: https://pypi.org/project/chain-of-consciousness/
- Whitepaper: https://vibeagentmaking.com/whitepaper
- Verification Demo: https://vibeagentmaking.com/verify/

---

<!-- VAM-SEC v1.0 | Vibe Agent Making Security Disclaimer -->

## Security & Transparency Disclosure

**Product:** Chain of Consciousness Skill for OpenClaw
**Type:** Skill Module
**Version:** 0.1.0
**Built by:** AB Support / Vibe Agent Making
**Contact:** alex@vibeagentmaking.com

**What it accesses:**
- Reads and writes chain files (`.jsonl`) in your working directory
- Executes the `coc` CLI tool via subprocess (installed via pip)
- No network access for core operations. Optional anchoring connects to OpenTimestamps calendar servers and/or RFC 3161 TSA endpoints.
- No telemetry, no phone-home, no data collection

**What it cannot do:**
- Cannot access files outside your working directory beyond what you explicitly specify
- Cannot make purchases, send emails, or take irreversible actions
- Cannot access credentials, environment variables, or secrets
- Does not store or transmit any data externally (chains are local files)

**Limitations:**
- Hash chain integrity depends on the local file not being modified outside the tool
- External timestamp anchoring requires network access and third-party service availability
- This tool provides cryptographic evidence, not legal proof — consult legal counsel for compliance requirements

**License:** Apache 2.0 — see https://github.com/chain-of-consciousness/chain-of-consciousness