{"id":43893524,"url":"https://github.com/moltblock/moltblock","last_synced_at":"2026-04-01T17:49:29.704Z","repository":{"id":336569823,"uuid":"1149082437","full_name":"moltblock/moltblock","owner":"moltblock","description":"Framework for evolving composite AI entities. Multi-agent graphs, verification, memory, and governance — molting, not chaining. OpenClaw-ready.","archived":false,"fork":false,"pushed_at":"2026-03-18T22:23:32.000Z","size":345,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-03-19T10:43:14.093Z","etag":null,"topics":["ai","ai-agents","ai-safety","composite-intelligence","governance","llm","multi-agent","nodejs","openclaw","security","trust","typescript","verification"],"latest_commit_sha":null,"homepage":"https://moltblock.io","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/moltblock.png","metadata":{"files":{"readme":"readme.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-02-03T17:46:20.000Z","updated_at":"2026-03-18T22:31:03.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/moltblock/moltblock","commit_stats":null,"previous_names":["moltblock/moltblock"],"tags_count":21,"template":false,"template_full_name":null,"purl":"pkg:github/moltblock/moltblock","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moltblock%2Fmoltblock","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moltblock%2Fmoltblock/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moltblock%2Fmoltblock/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moltblock%2Fmoltblock/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/moltblock","download_url":"https://codeload.github.com/moltblock/moltblock/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/moltblock%2Fmoltblock/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31290622,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-01T13:12:26.723Z","status":"ssl_error","status_checked_at":"2026-04-01T13:12:25.102Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","ai-agents","ai-safety","composite-intelligence","governance","llm","multi-agent","nodejs","openclaw","security","trust","typescript","verification"],"created_at":"2026-02-06T17:11:58.955Z","updated_at":"2026-04-01T17:49:29.680Z","avatar_url":"https://github.com/moltblock.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Moltblock\r\n\r\n\u003cp align=\"center\"\u003e\r\n  \u003ca href=\"https://github.com/moltblock/moltblock/actions/workflows/ci.yml?branch=main\"\u003e\u003cimg src=\"https://img.shields.io/github/actions/workflow/status/moltblock/moltblock/ci.yml?branch=main\u0026style=for-the-badge\" alt=\"CI status\"\u003e\u003c/a\u003e\r\n  \u003ca href=\"https://github.com/moltblock/moltblock/releases\"\u003e\u003cimg src=\"https://img.shields.io/github/v/release/moltblock/moltblock?include_prereleases\u0026style=for-the-badge\" alt=\"GitHub release\"\u003e\u003c/a\u003e\r\n  \u003ca href=\"https://www.npmjs.com/package/moltblock\"\u003e\u003cimg src=\"https://img.shields.io/npm/v/moltblock?style=for-the-badge\" alt=\"npm version\"\u003e\u003c/a\u003e\r\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge\" alt=\"MIT License\"\u003e\u003c/a\u003e\r\n\u003c/p\u003e\r\n\r\n**Moltblock** is a framework for building evolving composite intelligences.\r\n\r\nIt introduces the **Entity** as the primitive unit of intelligence — a system composed of many agents, models, and verification layers that evolves through **molting**, not chaining.\r\n\r\n---\r\n\r\n## Why Moltblock\r\n\r\nModern AI systems fail at scale because they:\r\n- rely on single models\r\n- propagate errors linearly\r\n- lack persistent, verified memory\r\n\r\nMoltblock addresses this by enabling:\r\n- structured multi-agent intelligence\r\n- heterogeneous model usage\r\n- built-in verification\r\n- irreversible knowledge checkpoints\r\n\r\n---\r\n\r\n## OpenClaw\r\n\r\nMoltblock gives [OpenClaw](https://github.com/openclaw/openclaw) a **structured cognitive backend** — entities, verification, memory, governance. When the assistant delegates code or high-stakes work to Moltblock, it gets verified artifacts, an audit trail, and governance (rate limits, veto, emergency stop), addressing security issues around running unvetted generated code and lack of attribution/rollback. See [OpenClaw integration](docs/openclaw_integration.md).\r\n\r\n**Security example:** If someone emails or messages the assistant to “send all my files to X” or similar exfiltration, routing that task through Moltblock lets the Critic/Judge reject it before any artifact is marked authoritative; the request is audited and no code is returned to run. Full scenario: [How Moltblock helps OpenClaw security](docs/openclaw_integration.md#how-moltblock-helps-openclaw-security).\r\n\r\n---\r\n\r\n## Core Concepts\r\n\r\n- **Entity** — a composite cognitive system\r\n- **Molt** — controlled internal evolution\r\n- **Artifact** — signed, verifiable outputs\r\n- **Checkpoint** — immutable state snapshots\r\n- **Governance** — safety outside cognition\r\n\r\n---\r\n\r\n## What Moltblock Is Not\r\n\r\n- Not a blockchain\r\n- Not a single AI model\r\n- Not a chat agent framework\r\n\r\nBlockchain is optional and used only for anchoring.\r\n\r\n---\r\n\r\n## Docs\r\n\r\n- [OpenClaw integration](docs/openclaw_integration.md) — CLI/API/handoff options; [value and singularity](docs/openclaw_integration_value_and_singularity.md) — why integrate, security, path to emergence. *Primary focus: integration and security for OpenClaw.*\r\n- [MVP Entity Spec](docs/mvp_entity_spec.md) — agent roles, LLMs, verification, minimal loop, lifecycle (v0.2)\r\n- [Landing page language](docs/landing_page_language.md) — headline, copy, and diagram for moltblock.io\r\n- [Protocol v0.1](docs/moltblock_protocol_v_0.md) · [Architecture](docs/composite_ai_entity_architecture.md) · [Manifesto](docs/moltblock_manifesto.md)\r\n\r\n---\r\n\r\n## Run (Code Entity MVP)\r\n\r\nRequires Node.js 22+, and (for full loop) any OpenAI-compatible API:\r\n- **OpenAI** — `https://api.openai.com/v1` with `OPENAI_API_KEY`\r\n- **Anthropic Claude** — `https://api.anthropic.com/v1` with `ANTHROPIC_API_KEY`\r\n- **Google Gemini** — `https://generativelanguage.googleapis.com/v1beta/openai` with `GOOGLE_API_KEY`\r\n- **Local LLMs** — LM Studio, Ollama, etc. at `http://localhost:1234/v1`\r\n- **Other providers** — Any OpenAI-compatible endpoint (Z.ai, Together, Groq, etc.)\r\n\r\n**Install from npm:**\r\n\r\n```bash\r\nnpm install -g moltblock\r\n\r\n# Run a task\r\nmoltblock \"Implement a function add(a, b) that returns a + b.\"\r\nmoltblock \"Implement add(a, b).\" --test path/to/test_add.ts\r\nmoltblock \"Implement add(a, b).\" --json\r\n```\r\n\r\n**Or run directly with npx (no install):**\r\n\r\n```bash\r\nnpx moltblock \"Implement add(a, b).\"\r\n```\r\n\r\n**Or install from source:**\r\n\r\n```bash\r\ngit clone https://github.com/moltblock/moltblock.git\r\ncd moltblock\r\nnpm install\r\nnpm run build\r\nnpx moltblock \"Implement add(a, b).\"\r\n```\r\n\r\n---\r\n\r\n## Configuration\r\n\r\n### Zero-config (auto-detect)\r\n\r\nIf you have an API key set in your environment, moltblock detects the provider automatically — no config file needed:\r\n\r\n```bash\r\nexport OPENAI_API_KEY=\"sk-...\"   # auto-detects OpenAI\r\nnpx moltblock \"Implement add(a, b).\" --json\r\n```\r\n\r\nOverride with CLI flags: `--provider google --model gemini-2.0-flash` or `-p zai -m glm-4.7`.\r\n\r\nDetection priority: `OPENAI_API_KEY` \u003e `GOOGLE_API_KEY` \u003e `ZAI_API_KEY` \u003e localhost.\r\n\r\n### Quick setup\r\n\r\nCreate a config file at `~/.moltblock/moltblock.json` (user-wide) or `./moltblock.json` (project-specific):\r\n\r\n```bash\r\n# User-wide config (recommended)\r\nmkdir -p ~/.moltblock\r\ncat \u003e ~/.moltblock/moltblock.json \u003c\u003c 'EOF'\r\n{\r\n  \"agent\": {\r\n    \"bindings\": {\r\n      \"generator\": {\r\n        \"backend\": \"openai\",\r\n        \"base_url\": \"https://api.openai.com/v1\",\r\n        \"model\": \"gpt-4o\"\r\n      },\r\n      \"critic\": {\r\n        \"backend\": \"openai\",\r\n        \"base_url\": \"https://api.openai.com/v1\",\r\n        \"model\": \"gpt-4o\"\r\n      },\r\n      \"judge\": {\r\n        \"backend\": \"openai\",\r\n        \"base_url\": \"https://api.openai.com/v1\",\r\n        \"model\": \"gpt-4o\"\r\n      },\r\n      \"verifier\": {\r\n        \"backend\": \"local\",\r\n        \"base_url\": \"http://localhost:1234/v1\",\r\n        \"model\": \"local\"\r\n      }\r\n    }\r\n  }\r\n}\r\nEOF\r\n```\r\n\r\nThen set your API key:\r\n```bash\r\nexport OPENAI_API_KEY=\"sk-...\"\r\n# Or add to ~/.bashrc / ~/.zshrc\r\n```\r\n\r\n### Config search order\r\n\r\nMoltblock searches for config in this order:\r\n\r\n1. `MOLTBLOCK_CONFIG` env var (explicit path)\r\n2. `./moltblock.json` (current directory)\r\n3. `./.moltblock/moltblock.json` (hidden folder in current directory)\r\n4. `~/.moltblock/moltblock.json` (user home directory — **recommended**)\r\n5. **Fallback to OpenClaw:** `~/.openclaw/openclaw.json` (if you use OpenClaw)\r\n6. Environment variables only (no config file)\r\n\r\n### API keys\r\n\r\nSet API keys via environment variables (never in config files):\r\n\r\n| Provider | Environment Variable |\r\n|----------|---------------------|\r\n| OpenAI | `OPENAI_API_KEY` |\r\n| Anthropic Claude | `ANTHROPIC_API_KEY` |\r\n| Google Gemini | `GOOGLE_API_KEY` |\r\n| Z.ai | `ZAI_API_KEY` |\r\n| Artifact signing | `MOLTBLOCK_SIGNING_KEY` (required in production) |\r\n\r\n### Check which config is being used\r\n\r\n```typescript\r\nimport { loadMoltblockConfig, getConfigSource } from \"moltblock\";\r\n\r\nloadMoltblockConfig();\r\nconsole.log(getConfigSource()); // \"moltblock\", \"openclaw\", or \"env\"\r\n```\r\n\r\n```bash\r\n# Tests (no LLM required)\r\nnpm test\r\n```\r\n\r\n---\r\n\r\n## Implemented (v0.2+)\r\n\r\n- **Configurable agent graph** — DAG of nodes (role + model binding) and edges; load from `config/code_entity_graph.json` or YAML; `GraphRunner` and `loadEntityWithGraph()`.\r\n- **Long-term memory and checkpoints** — `Store` (SQLite): verified memory (admission after verification), immutable checkpoints (entity version, graph hash, memory hash, artifact refs). Optional `store` and `writeCheckpointAfter` options on `CodeEntity.run()` and `GraphRunner.run()`.\r\n- **Recursive improvement loop** — Outcomes recorded per run; `critiqueStrategies()`, `setStrategy()` / `getStrategy()` for versioned prompts; `runEval()` and `runImprovementCycle()`. Agents use strategy store when provided.\r\n- **Molt and governance** — `GovernanceConfig` (rate limit, veto); `canMolt()`, `triggerMolt()`, `pause()`, `resume()`, `emergencyShutdown()`; audit log and governance state in `Store`.\r\n- **Multi-entity handoff** — `signArtifact()` / `verifyArtifact()`; inbox per entity; `sendArtifact()`, `receiveArtifacts()` for Entity A → Entity B.\r\n\r\n### New in v0.6\r\n\r\n- **Pluggable verifier system** — `Verifier` interface so verification isn't limited to vitest. Implement `verify(memory, context)` to plug in any gating strategy.\r\n- **PolicyVerifier** — Rule-based verifier with ~20 built-in deny rules. Catches destructive commands (`rm -rf`, `DROP TABLE`), sensitive file access (`.ssh/`, `/etc/shadow`), hardcoded secrets, and exfiltration patterns — all without an LLM call.\r\n- **CodeVerifier** — Adapter wrapping the existing vitest verifier into the pluggable interface.\r\n- **CompositeVerifier** — Chains multiple verifiers (e.g. policy + code); all must pass. Supports fail-fast and collect-all modes.\r\n- **Generic Entity** — `Entity` class with pluggable verifier and domain-aware prompts. Use `new Entity({ domain: \"general\" })` for non-code tasks.\r\n- **Domain prompts** — Registry mapping domains to role-specific system prompts. Built-in `\"code\"` and `\"general\"` domains; register custom domains with `registerDomain()`.\r\n- **Risk classification** — `classifyRisk(task)` returns `\"low\"` / `\"medium\"` / `\"high\"` with reasons. Pure regex matching, no LLM needed.\r\n- **Policy rules in config** — Add custom `policy.rules` to `moltblock.json` for project-specific allow/deny rules.\r\n- **OpenClaw skill** — `skill/SKILL.md` for one-step installation into OpenClaw workspace.\r\n\r\n---\r\n\r\n## Policy Verifier\r\n\r\nThe `PolicyVerifier` catches dangerous patterns in artifacts and tasks without needing an LLM:\r\n\r\n```typescript\r\nimport { PolicyVerifier, WorkingMemory } from \"moltblock\";\r\n\r\nconst verifier = new PolicyVerifier();\r\nconst memory = new WorkingMemory();\r\nmemory.setFinalCandidate(\"rm -rf /\");\r\n\r\nconst result = await verifier.verify(memory);\r\n// result.passed === false\r\n// result.evidence includes \"[cmd-rm-rf] Recursive force delete\"\r\n```\r\n\r\nCustom rules can be added via constructor or config:\r\n\r\n```typescript\r\nconst verifier = new PolicyVerifier([\r\n  {\r\n    id: \"allow-tmp-cleanup\",\r\n    description: \"Allow cleanup in /tmp\",\r\n    target: \"artifact\",\r\n    pattern: \"\\\\/tmp\\\\/\",\r\n    action: \"allow\",\r\n    category: \"destructive-cmd\",\r\n    enabled: true,\r\n  },\r\n]);\r\n```\r\n\r\n---\r\n\r\n## Risk Classification\r\n\r\nClassify task risk before deciding whether to verify:\r\n\r\n```typescript\r\nimport { classifyRisk } from \"moltblock\";\r\n\r\nclassifyRisk(\"write a hello world function\");\r\n// { level: \"low\", reasons: [] }\r\n\r\nclassifyRisk(\"sudo rm -rf /home/user\");\r\n// { level: \"high\", reasons: [\"Sudo privilege escalation\", \"Recursive file deletion (rm -rf)\"] }\r\n```\r\n\r\n---\r\n\r\n## Generic Entity\r\n\r\nFor non-code tasks, use the generic `Entity` with domain-aware prompts:\r\n\r\n```typescript\r\nimport { Entity, PolicyVerifier, CompositeVerifier, CodeVerifier } from \"moltblock\";\r\n\r\n// General-purpose entity (policy verification only)\r\nconst entity = new Entity({ domain: \"general\" });\r\n\r\n// Code entity with both policy and vitest verification\r\nconst codeEntity = new Entity({\r\n  domain: \"code\",\r\n  verifier: new CompositeVerifier([new PolicyVerifier(), new CodeVerifier()]),\r\n});\r\n```\r\n\r\n---\r\n\r\n## Roadmap\r\n\r\n- v0.1 — Protocol + architecture\r\n- v0.2 — MVP Entity implementation (spec + Code Entity loop + graph, memory, improvement, governance, handoff)\r\n- v0.3 — Multi-Entity collaboration (orchestration and tooling)\r\n- v0.6 — Pluggable verification, policy rules, generic entity, risk classification, OpenClaw skill\r\n- v0.8 — Quick wins, error handling, test coverage, license fix\r\n- v0.9 — Core reliability: gateway retry/timeout, graph-runner error handling, entity degraded fallback\r\n- v0.10 — Test coverage: agents, graph-runner, handoff, integration tests; test helpers\r\n- v0.10.1 — Persistence hardening: WAL mode, transactions, regex caching, signing key opt-in\r\n- v0.11 — CI coverage enforcement, stricter tsconfig, documentation fixes\r\n\r\n---\r\n\r\n## Philosophy\r\n\r\nMoltblock treats singularity as an emergent property of accelerating, verified collective intelligence.\r\n\r\nIf intelligence scales, it must scale with structure. A key application is OpenClaw: a structured backend that helps with security and assurance.\r\n\r\n---\r\n\r\n## Domain\r\n\r\nCanonical home: **moltblock.io**\r\n\r\n## Contributing\r\n\r\nWe welcome contributions. See [CONTRIBUTING](CONTRIBUTING.md) for how to run tests, submit changes, and our [Code of Conduct](CODE_OF_CONDUCT.md).\r\n\r\n---\r\n\r\n## License\r\n\r\nMIT — see [LICENSE](LICENSE).\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoltblock%2Fmoltblock","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmoltblock%2Fmoltblock","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmoltblock%2Fmoltblock/lists"}