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
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)
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
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
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
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
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
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 })
