genesis-trace 🧬

Provenance tracking for agent workspaces — inspired by the Machine Genome Protocol (paxlabs-inc).

A lightweight CLI that creates verifiable, content-addressed provenance records for your project directories. Think "git describe meets blockchain lite" — but for your whole workspace.

npm install -g genesis-trace

Why?

Modern agents are assembled from prompts, scaffolds, tools, datasets, and runtime policy. When something breaks or produces unexpected output, you need to know exactly what was in your workspace. genesis-trace gives you:

• 🧬 Content-addressed identity — Every workspace state gets a unique Gene (SHA-256 multihash)
• 🔗 Explicit lineage — Compare any two snapshots to see what changed
• 🔐 Verifiable records — Signed genesis records with proof values
• 📸 Quick snapshots — Fingerprint your workspace in one command

Usage

Quick fingerprint

genesis-trace snapshot
# 📸 Snapshot fingerprint: zQmUHE3mY9RRA4cUGJoCB42JumEgcND2dvVmTqot5xp9eV8

Create a signed genesis record

genesis-trace init -n "my-agent" -t agent -v 1.0.0 -o record.json
# 🧬 Gene: zQmVbhmwFtMtjBscHFNwCV9kjPBG7aUHxJXaJhLUXVBZWHQ

Generate a Gene (content-addressed hash)

genesis-trace gene -i record.json
# zQmVbhmwFtMtjBscHFNwCV9kjPBG7aUHxJXaJhLUXVBZWHQ

Verify a record

genesis-trace verify -i record.json
# ✅ VERIFY PASSED — Record is structurally valid

Compare two snapshots

genesis-trace diff before.json after.json
# Shows added/removed/changed files + lineage classification

Commands

| Command | Description | |---------|-------------| | init | Create a signed genesis record for the current workspace | | gene | Compute the Gene (SHA-256 multihash) of a record | | verify | Verify a record's integrity and signature | | snapshot | Quick fingerprint of workspace state | | diff | Compare two snapshots and show provenance lineage | | help | Show help |

How it works

1. Scan — Hashes every file in the directory (SHA-256, skipping node_modules/.git/etc.)
2. Record — Builds a genesis record with identity, artifacts, git state, and timestamp
3. Sign — Computes a Data Integrity Proof (mgs-demo format)
4. Gene — Generates a content-addressed Gene: z + base58btc(SHA-256(multicodec || JCS(record)))

The Gene changes if any file changes, any git commit changes, or the identity metadata changes. This gives you a rock-solid fingerprint of your workspace at a point in time.

Inspired by

This tool is a lightweight, JS-based implementation of concepts from the Machine Genome protocol — an open identity and provenance protocol for models, agents, harnesses, and datasets built by paxlabs-inc. Read their concepts for the full picture.

License

Apache-2.0