DarkMatter — Execution Lineage for AI Agents#

DarkMatter is the execution history layer for multi-agent systems. Every agent action becomes an immutable, cryptographically chained context commit — replayable, forkable, and independently verifiable.

Base URL: https://darkmatterhub.ai API key env: DARKMATTER_API_KEY Get a key: https://darkmatterhub.ai/signup Live demo: https://darkmatterhub.ai/demo

Data notice: This skill sends agent context to darkmatterhub.ai. DarkMatter is open source (MIT) and fully self-hostable: https://github.com/darkmatter-hub/darkmatter

---

When to use this skill#

Use when the user asks to:

• Commit context or results to DarkMatter for another agent
• Pull or inherit context from an upstream agent
• Replay a full decision chain (root to tip)
• Fork execution from a checkpoint
• Verify chain integrity
• Export an audit artifact
• Check agent identity

---

Commands#

1. Commit context to another agent#

bash

curl -s -X POST https://darkmatterhub.ai/api/commit \
  -H "Authorization: Bearer $DARKMATTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "toAgentId": "<RECIPIENT_AGENT_ID>",
    "payload": {
      "input":  "<what this agent received>",
      "output": "<what this agent produced>",
      "memory": {}
    },
    "agent": {
      "role":     "<researcher|writer|reviewer>",
      "provider": "<anthropic|openai|local>",
      "model":    "<model name>"
    },
    "parentId":  "<parent ctx_id if chaining>",
    "traceId":   "<optional trace group>",
    "eventType": "commit"
  }'

Response is a canonical v2 context object. Use id as parentId in the next commit to build the lineage chain.

---

2. Pull verified context (inherit from upstream)#

bash

curl -s https://darkmatterhub.ai/api/pull \
  -H "Authorization: Bearer $DARKMATTER_API_KEY"

Returns all verified contexts addressed to this agent, newest first.

---

3. Replay full decision chain#

bash

curl -s "https://darkmatterhub.ai/api/replay/<CTX_ID>" \
  -H "Authorization: Bearer $DARKMATTER_API_KEY"

# Summary mode (no payloads, faster):
curl -s "https://darkmatterhub.ai/api/replay/<CTX_ID>?mode=summary" \
  -H "Authorization: Bearer $DARKMATTER_API_KEY"

Returns ordered chain root to tip with every payload, agent attribution, per-step integrity verification, and chainIntact boolean.

---

4. Fork from a checkpoint#

bash

curl -s -X POST https://darkmatterhub.ai/api/fork/<CTX_ID> \
  -H "Authorization: Bearer $DARKMATTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"fromCheckpoint": "<ctx_id>", "branchKey": "experiment-1"}'

Returns new context ID with fork_of, fork_point, lineage_root. Continue by committing with parentId set to the new ID. Original chain is never modified.

---

5. Verify chain integrity#

bash

curl -s "https://darkmatterhub.ai/api/verify/<CTX_ID>" \
  -H "Authorization: Bearer $DARKMATTER_API_KEY"

Returns: chain_intact, length, root_hash, tip_hash, broken_at, fork_points.

---

6. Export portable audit artifact#

bash

curl -s "https://darkmatterhub.ai/api/export/<CTX_ID>" \
  -H "Authorization: Bearer $DARKMATTER_API_KEY" \
  -o "darkmatter_ctx.json"

Downloads JSON with full chain, integrity proof, chain_hash (stable), and export_hash (unique per export instance).

---

7. Check agent identity#

bash

curl -s https://darkmatterhub.ai/api/me \
  -H "Authorization: Bearer $DARKMATTER_API_KEY"

---

Event types#

Developer: commit, fork, revert, branch, merge, spawn, timeout, retry, checkpoint, error Compliance: override, consent, escalate, redact, audit

Set via eventType field in commit. Defaults to commit.

---

Integrity model#

Each commit: payload_hash = sha256(payload), integrity_hash = sha256(payload_hash + parent_integrity_hash). Tampering at any node breaks every downstream hash. Broken chain policy: permissive — commits still allowed but flagged. Fork from last valid node to start a clean branch.

---

Key rules#

• Always pass parentId when chaining commits — this builds the lineage graph
• Context IDs are globally unique: ctx_{timestamp}_{hex}
• Forked branches carry fork_of, fork_point, lineage_root
• chain_hash in exports is deterministic — same chain = same hash
• Legacy context field still accepted (stored as { output: context })