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.
If you also have an internet connection, the script will additionally hit https://verdigraph.dev/app/import with the same input bytes and confirm the hosted Worker produces the exact same brain_id — that's your proof the local build is byte-equivalent to the production reference implementation.
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:
- 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. - 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. - 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 build/verify/evolve brains directly. No network calls; everything runs on your machine.
Determinism and verifiability
| Field | What it is | How to verify |
|---|---|---|
brain_id | 26-char Crockford-base32; derived from sha256(input_bytes + b":" + format) | python -m verdigraph build --file <same bytes> — same id every time |
brain_uri | verdigraph://brain/<brain_id> | Self-describing form; safe for content-safety classifiers |
content_hash | sha256(canonicalize(brain_body_minus_content_hash)) | See docs/CANONICALIZATION.md for the exact algorithm |
input_sha256 | sha256(raw_input_bytes) | sha256sum your_file.json |
| Invariant report | 9 required checks + 1 advisory I9_fitness_metric_wired | All carry id, description, passed, optional passed_with_default, advisory, detail |
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).
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 / evolve)
│ ├── 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-mcp/ ← OPTIONAL: Cloudflare Workers deployment if you want a hosted instance
Optional: deploy your own hosted instance
A reference Cloudflare Workers deployment lives in hosted-mcp/. It serves the same deterministic-build pipeline over HTTPS + OAuth 2.1 + PKCE, adds prepaid USD credits via Stripe, and Ed25519-signed compliance attestations. You do not need this to use the Python core. It exists because the same protocol can run hosted if you want a shared multi-caller environment. See hosted-mcp/README.md for deployment instructions.
A live reference deployment runs at https://verdigraph.dev — same byte-equivalent pipeline. The local Python implementation is the canonical source; the Worker is a reimplementation for hosting convenience.
Run the tests
Python core:
source .venv/bin/activate
pip install -e ".[dev]"
pytest -q
TypeScript hosted-MCP (Cloudflare Worker):
cd hosted-mcp
npm ci
npm run typecheck
npm test
Both suites run in CI (.github/workflows/tests.yml) on every push and pull
request: the Python job across 3.10 / 3.11 / 3.12, and the hosted-mcp job on
Node 22 — where the cross-core parity.test.ts executes against a real Python
install rather than self-skipping. A secret-scan job fails the build if a live
Stripe identifier is ever committed.
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/:
PAPER_1_Physical_NeuroGenesis_SynapseForge.md— physical version: AI-agent-architected, 3D-printed, solution-grown neuromorphic substrates.PAPER_2_Verdigraph_Digital_NeuroGenesis.md— software version: self-evolving digital cognitive graphs.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: hartjustin6@gmail.com.
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.