CLAUDE.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

New Packages (shipped 2026-04-11/12)

Rhythms — nature-based scheduling (time → signals)
Memory — four-layer memory (substrate, epigenetic marks, daily, compost)
Spore — declarative deployment DNA (spore.yaml)
Cortex Persona Router — persona domain_trigger matching for Discord messages

Obadiah Brain

The Obadiah deployment runs as a launchd daemon on the Mac Mini. One process, many organs sharing one SignalBus. Entry point: deployments/obadiah/bridge/start-rhythms.ts. Spore config: deployments/obadiah/spore.yaml.

Commands

pnpm install                          # Install all dependencies
pnpm --filter @cambium/db migrate     # Run migrations (native Postgres on localhost:5432)
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

Obadiah daemon

# Check daemon status
launchctl list | grep cambium

# View daemon logs
tail -f ~/Library/Logs/cambium-obadiah-rhythms.out

# Restart daemon (picks up new code)
launchctl kickstart -k gui/501/land.unicorn.cambium.obadiah.rhythms

# Memory CLI
cd deployments/obadiah/bridge
pnpm exec tsx cambium-bridge.ts memory substrate     # Print substrate content
pnpm exec tsx cambium-bridge.ts memory recall <subj>  # Query memory by subject
pnpm exec tsx cambium-bridge.ts memory seeds          # List pending seeds

PostgreSQL

Native Postgres on localhost:5432 (not Docker). Connection: postgres://cambium:cambium_dev@localhost:5432/cambium.

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).