verdigraph-neurogenesis

Clone this repo, run one script, and within 60 seconds you're building deterministic, content-addressed brain artifacts from any agent file — Claude project export, OpenAI Assistant config, raw prompt list, or Verdigraph genome JSON. Pure Python core; zero external services required.

60-second quickstart

git clone https://github.com/viridis-security/verdigraph-neurogenesis
cd verdigraph-neurogenesis
bash quickstart.sh

That's it. The script creates a venv, installs the package editable, runs the brain builder against an example genome, and prints the deterministic brain_id + content_hash. No Cloudflare account, no Stripe key, no `verdigraph.dev` account needed. Everything runs locally.

The default quickstart builds the bundled synthetic example locally and makes no hosted comparison request. Setup still uses pip to install the package and development dependencies. To compare that synthetic example with the hosted Worker, explicitly opt in:

VERDIGRAPH_VERIFY_HOSTED=1 bash quickstart.sh

This sends the bundled example to https://verdigraph.dev/app/import and compares the returned brain_id. Use the local build commands below for private agent files; do not substitute private inputs into the hosted comparison.

What it is

Verdigraph turns an agent file into an inspectable cognitive graph with a content-addressed identifier you can pin in git, cite in an audit, or paste into a code review. Three things make this useful:

1. Determinism. Identical input bytes always produce identical brain_id, content_hash, and graph structure. Run it twice, get the same answer twice. Run it in Python locally; run it in TypeScript on the Worker; same answer either way.
2. Inspectable structure. Every brain carries 9 firing invariants + 1 advisory check (I9_fitness_metric_wired) so you can prove what the agent file actually compiles to without trusting a black box.
3. Self-contained build pipeline. No external dependencies beyond the Python stdlib. No SaaS lock-in. You can audit every line of verdigraph/brain.py (≈ 660 lines) in an afternoon.

Use it

Build a brain from a Verdigraph genome

python -m verdigraph build --file examples/hypothetical_research_agent.genome.json --format verdigraph_genome --pretty

Or pipe input:

cat my_agent.json | python -m verdigraph build --stdin --format auto --summary --pretty

Build from a Claude project export

python -m verdigraph build --file my_claude_project_export.json --format claude_project_export --pretty

Build from an OpenAI Assistant config

python -m verdigraph build --file my_assistant.json --format openai_assistant --pretty

Build from a flat prompt list

echo -e "You are a helpful assistant.\nSummarize the user's request.\nPlan steps and execute." \
  | python -m verdigraph build --stdin --format prompt_list --pretty

Re-verify a saved brain artifact

python -m verdigraph build --file my_agent.json --pretty > brain.json
python -m verdigraph verify brain.json

Use it as a Python library

from verdigraph.brain import extract, verify_brain, to_dict

genome = b'{"agent_name":"my_agent","purpose":"...","initial_nodes":["planner","executor"],"fitness_metrics":["task_success_rate"]}'

brain = extract("verdigraph_genome", genome)
print(brain.brain_id)        # e.g. RMX124YY916WP0TCSEHFYX7M30
print(brain.brain_uri)       # verdigraph://brain/RMX124YY916WP0TCSEHFYX7M30
print(brain.content_hash)    # sha256 hex
print(len(brain.nodes), "nodes,", len(brain.edges), "edges")

report = verify_brain(brain)
assert report.passed         # all non-advisory invariants pass

print(to_dict(brain))        # serialize for storage / round-trip

Expose it as an MCP server for your LLM agent

pip install -e ".[mcp]"
verdigraph-mcp                 # runs over stdio

Then in Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "verdigraph": {
      "command": "/absolute/path/to/repo/.venv/bin/verdigraph-mcp",
      "args": []
    }
  }
}

Or in Claude Code: claude mcp add --transport stdio verdigraph /absolute/path/to/repo/.venv/bin/verdigraph-mcp.

Restart your client. Your agent now has verdigraph_* tools to create developmental agents, feed them task evaluations, inspect their graphs and ledgers, and choose compute profiles. Brain artifacts are built with python -m verdigraph build (above). No network calls; everything runs on your machine.

Determinism and verifiability

Canonicalization rule (one sentence)

Apply json.dumps with separators=(",", ":") after recursively sorting every object's keys lexicographically by codepoint and coercing integer-valued floats to integers (matches JavaScript JSON.stringify byte-for-byte). UTF-8 encoded before hashing. See verdigraph/brain.py::canonicalize (≈ 20 lines, stdlib only).

Identifiers are computed over the exact bytes you submit, so a pretty-printed genome and its minified form get different brain_ids. Pin one serialization (for example jq -c . genome.json). Test vectors, and a reference implementation that reproduces real hashes, are in docs/CANONICALIZATION.md.

Layout

verdigraph-neurogenesis/
├── README.md                     ← you are here
├── quickstart.sh                 ← clone → first brain in 60 seconds
├── pyproject.toml                ← Python package metadata
├── verdigraph/                   ← Python core (no external deps)
│   ├── brain.py                  ← deterministic build pipeline (extract / canonicalize / verify)
│   ├── cli.py                    ← `python -m verdigraph` CLI
│   ├── genome.py                 ← AgentGenome / GrowthRules / SafetyAxioms (live-agent runtime)
│   ├── graph.py                  ← CognitiveGraph / CognitiveNode / CognitiveEdge
│   ├── agent.py                  ← DevelopmentalAgent (live-agent runtime)
│   ├── growth.py / pruning.py    ← evolution operators
│   ├── evaluation.py             ← task-outcome ledger
│   ├── compute.py                ← compute-routing helpers
│   └── ledger.py                 ← immutable event log
├── verdigraph_mcp/               ← optional: stdio MCP server (`pip install -e ".[mcp]"`)
├── tests/                        ← pytest, all green on a clean clone
├── examples/                     ← runnable demos with fixture genomes
├── docs/                         ← canonicalization spec, architecture, invariants
└── papers/                       ← three companion papers (Zenodo-archived)

Hosted

Hosted: verdigraph.dev, paid per call. Viridis commits 25% of the net revenue it keeps (after creator payouts and pass-through costs) to conservation; the ledger is public at https://verdigraph.dev/conservation/public. Self-host: the Python MCP server in verdigraph_mcp/

Run the tests

Python core:

source .venv/bin/activate
pip install -e ".[dev]"
pytest -q

The Python suite runs in CI (.github/workflows/tests.yml) on every push and pull request across Python 3.10 / 3.11 / 3.12. A secret-scan job fails the build if a live Stripe identifier is committed. The hosted service runs its TypeScript and cross-core parity tests in the private service repository.

The tests/test_brain_parity.py suite locks the deterministic-build contract — specifically that b'{"agent_name":"x","purpose":"y","initial_nodes":["a"],"fitness_metrics":["task_success_rate"]}' produces brain_id == "RMX124YY916WP0TCSEHFYX7M30" and content_hash == "20b9e5be0e5a0d34e564df6d0a554b1232ff9cc3ff309ab8da77a97756602c0c". If either side ever drifts, that test fails on the next CI run and we ship the divergence as a deliberate schema bump.

Companion papers

In papers/:

1. PAPER_1_Physical_NeuroGenesis_SynapseForge.md — physical version: AI-agent-architected, 3D-printed, solution-grown neuromorphic substrates.
2. PAPER_2_Verdigraph_Digital_NeuroGenesis.md — software version: self-evolving digital cognitive graphs.
3. PAPER_3_Verdigraph_Compute_Efficiency.md — compute-efficiency layer.

To cite:

Hart, Justin. (2026). Verdigraph NeuroGenesis: A Software Framework for Self-Evolving AI-Agent Cognitive Substrates (Version 0.1.0). Zenodo. https://doi.org/10.5281/zenodo.20261687

License & contact

MIT. Maintained by Viridis LLC. Contact: [email protected].

This is an experimental research framework. It does not create autonomous unrestricted self-modifying AI. All growth and pruning actions are constrained by explicit genome rules, safety invariants, and an auditable ledger.