AGENTS.md

Overview

Cambium is a nature-based orchestration platform for resilient agent systems. It is the mycelial alternative to bureaucratic agent platforms like Paperclip.

Architecture

Modular monolith. TypeScript strict mode. PostgreSQL. In-process event bus.

Core Components

Cambium Core — platform substrate (identity, persistence, contracts)
Hypha — graph-based orchestration engine
Loom — operator workflow surface (Next.js + React Flow)
Quorum — threshold-based governance
Health — homeostasis and stress detection
Seed — checkpoints, replay, recovery
Immune — anomaly detection, trust scoring
Stigmergy — shared environment coordination (markers, regions)
Genesis — agent templates, lifecycle, composting
Signals — nervous system (typed signals, receptors, cascades, heartbeat)

Key Differentiators

Signal protocol with decay, cascades, and receptor binding (not flat event logs)
Stigmergic coordination (environment-based routing, not command-based)
Agent lifecycle with Genesis (birth) and Composting (death → learning)
Hardwired safety cascades that fire regardless of subscription state

Commands

pnpm install                          # Install all dependencies
docker compose up -d                  # Start PostgreSQL
pnpm --filter @cambium/db migrate     # Run migrations
pnpm turbo dev                        # Start all packages + Loom
pnpm turbo test                       # Run all tests
pnpm turbo build                      # Build all packages
pnpm turbo typecheck                  # Type check all packages

Non-Negotiables

TypeScript strict mode — no any types
Signals persist to PostgreSQL BEFORE delivery
Package boundaries enforced (no circular deps)
Cascade chains must have tests
Conventional commits (feat:, fix:, test:, docs:, refactor:)
No in-memory-only state for important data

Specs

Full PRDs in .ralph/specs/ (7 documents covering all subsystems).