darkmatter

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