{
  "markdown": "# verdigraph-neurogenesis\n\n> 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.\n\n[![python](https://img.shields.io/badge/python-3.10+-blue?style=flat-square)](https://www.python.org)\n[![tests](https://img.shields.io/badge/tests-python%20%C2%B7%20typescript-success?style=flat-square)](#run-the-tests)\n[![license](https://img.shields.io/badge/license-MIT-blue?style=flat-square)](LICENSE)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.20261687.svg)](https://doi.org/10.5281/zenodo.20261687)\n[![Glama](https://glama.ai/mcp/servers/viridis-security/verdigraph-neurogenesis/badges/score.svg)](https://glama.ai/mcp/servers/viridis-security/verdigraph-neurogenesis)\n\n---\n\n## 60-second quickstart\n\n```bash\ngit clone https://github.com/viridis-security/verdigraph-neurogenesis\ncd verdigraph-neurogenesis\nbash quickstart.sh\n```\n\nThat'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.\n\nIf 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.\n\n---\n\n## What it is\n\nVerdigraph 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:\n\n1. **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.\n2. **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.\n3. **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.\n\n---\n\n## Use it\n\n### Build a brain from a Verdigraph genome\n\n```bash\npython -m verdigraph build --file examples/hypothetical_research_agent.genome.json --format verdigraph_genome --pretty\n```\n\nOr pipe input:\n\n```bash\ncat my_agent.json | python -m verdigraph build --stdin --format auto --summary --pretty\n```\n\n### Build from a Claude project export\n\n```bash\npython -m verdigraph build --file my_claude_project_export.json --format claude_project_export --pretty\n```\n\n### Build from an OpenAI Assistant config\n\n```bash\npython -m verdigraph build --file my_assistant.json --format openai_assistant --pretty\n```\n\n### Build from a flat prompt list\n\n```bash\necho -e \"You are a helpful assistant.\\nSummarize the user's request.\\nPlan steps and execute.\" \\\n  | python -m verdigraph build --stdin --format prompt_list --pretty\n```\n\n### Re-verify a saved brain artifact\n\n```bash\npython -m verdigraph build --file my_agent.json --pretty > brain.json\npython -m verdigraph verify brain.json\n```\n\n---\n\n## Use it as a Python library\n\n```python\nfrom verdigraph.brain import extract, verify_brain, to_dict\n\ngenome = b'{\"agent_name\":\"my_agent\",\"purpose\":\"...\",\"initial_nodes\":[\"planner\",\"executor\"],\"fitness_metrics\":[\"task_success_rate\"]}'\n\nbrain = extract(\"verdigraph_genome\", genome)\nprint(brain.brain_id)        # e.g. RMX124YY916WP0TCSEHFYX7M30\nprint(brain.brain_uri)       # verdigraph://brain/RMX124YY916WP0TCSEHFYX7M30\nprint(brain.content_hash)    # sha256 hex\nprint(len(brain.nodes), \"nodes,\", len(brain.edges), \"edges\")\n\nreport = verify_brain(brain)\nassert report.passed         # all non-advisory invariants pass\n\nprint(to_dict(brain))        # serialize for storage / round-trip\n```\n\n---\n\n## Expose it as an MCP server for your LLM agent\n\n```bash\npip install -e \".[mcp]\"\nverdigraph-mcp                 # runs over stdio\n```\n\nThen in Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"verdigraph\": {\n      \"command\": \"/absolute/path/to/repo/.venv/bin/verdigraph-mcp\",\n      \"args\": []\n    }\n  }\n}\n```\n\nOr in Claude Code: `claude mcp add --transport stdio verdigraph /absolute/path/to/repo/.venv/bin/verdigraph-mcp`.\n\nRestart your client. Your agent now has `verdigraph_*` tools to build/verify/evolve brains directly. No network calls; everything runs on your machine.\n\n---\n\n## Determinism and verifiability\n\n| Field | What it is | How to verify |\n|---|---|---|\n| `brain_id` | 26-char Crockford-base32; derived from `sha256(input_bytes + b\":\" + format)` | `python -m verdigraph build --file <same bytes>` — same id every time |\n| `brain_uri` | `verdigraph://brain/<brain_id>` | Self-describing form; safe for content-safety classifiers |\n| `content_hash` | `sha256(canonicalize(brain_body_minus_content_hash))` | See [docs/CANONICALIZATION.md](docs/CANONICALIZATION.md) for the exact algorithm |\n| `input_sha256` | `sha256(raw_input_bytes)` | `sha256sum your_file.json` |\n| Invariant report | 9 required checks + 1 advisory `I9_fitness_metric_wired` | All carry `id`, `description`, `passed`, optional `passed_with_default`, `advisory`, `detail` |\n\n### Canonicalization rule (one sentence)\n\nApply `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).\n\n---\n\n## Layout\n\n```\nverdigraph-neurogenesis/\n├── README.md                     ← you are here\n├── quickstart.sh                 ← clone → first brain in 60 seconds\n├── pyproject.toml                ← Python package metadata\n├── verdigraph/                   ← Python core (no external deps)\n│   ├── brain.py                  ← deterministic build pipeline (extract / canonicalize / verify / evolve)\n│   ├── cli.py                    ← `python -m verdigraph` CLI\n│   ├── genome.py                 ← AgentGenome / GrowthRules / SafetyAxioms (live-agent runtime)\n│   ├── graph.py                  ← CognitiveGraph / CognitiveNode / CognitiveEdge\n│   ├── agent.py                  ← DevelopmentalAgent (live-agent runtime)\n│   ├── growth.py / pruning.py    ← evolution operators\n│   ├── evaluation.py             ← task-outcome ledger\n│   ├── compute.py                ← compute-routing helpers\n│   └── ledger.py                 ← immutable event log\n├── verdigraph_mcp/               ← optional: stdio MCP server (`pip install -e \".[mcp]\"`)\n├── tests/                        ← pytest, all green on a clean clone\n├── examples/                     ← runnable demos with fixture genomes\n├── docs/                         ← canonicalization spec, architecture, invariants\n├── papers/                       ← three companion papers (Zenodo-archived)\n└── hosted-mcp/                   ← OPTIONAL: Cloudflare Workers deployment if you want a hosted instance\n```\n\n---\n\n## Optional: deploy your own hosted instance\n\nA 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](hosted-mcp/README.md) for deployment instructions.\n\nA live reference deployment runs at [https://verdigraph.dev](https://verdigraph.dev) — same byte-equivalent pipeline. The local Python implementation is the canonical source; the Worker is a reimplementation for hosting convenience.\n\n---\n\n## Run the tests\n\nPython core:\n\n```bash\nsource .venv/bin/activate\npip install -e \".[dev]\"\npytest -q\n```\n\nTypeScript hosted-MCP (Cloudflare Worker):\n\n```bash\ncd hosted-mcp\nnpm ci\nnpm run typecheck\nnpm test\n```\n\nBoth suites run in CI (`.github/workflows/tests.yml`) on every push and pull\nrequest: the Python job across 3.10 / 3.11 / 3.12, and the hosted-mcp job on\nNode 22 — where the cross-core `parity.test.ts` executes against a real Python\ninstall rather than self-skipping. A secret-scan job fails the build if a live\nStripe identifier is ever committed.\n\nThe `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.\n\n---\n\n## Companion papers\n\nIn `papers/`:\n\n1. `PAPER_1_Physical_NeuroGenesis_SynapseForge.md` — physical version: AI-agent-architected, 3D-printed, solution-grown neuromorphic substrates.\n2. `PAPER_2_Verdigraph_Digital_NeuroGenesis.md` — software version: self-evolving digital cognitive graphs.\n3. `PAPER_3_Verdigraph_Compute_Efficiency.md` — compute-efficiency layer.\n\nTo cite:\n\n> 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\n\n---\n\n## License & contact\n\nMIT. Maintained by Viridis LLC. Contact: `hartjustin6@gmail.com`.\n\nThis 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.\n",
  "bytes": 10086,
  "sha": "3aef1647fc5d6853b294b2f241c80687320625498770dbc2b68d04f90eb2443f",
  "repo_slug": "viridis-security/verdigraph-neurogenesis",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_jdhart81_verdigraph_mcp_53e0727c/readme"
}