Cohezion

The compound AI engine that gets smarter every session.

Cohezion is an open-source platform for compound AI orchestration — a self-improving loop where 182 version-controlled skills compound across sessions, agents learn inside a physics-grounded 12D manifold, and the entire inference stack runs locally on AMD hardware with no per-token API costs.

Quick Start · Architecture · Local Inference · Benchmarks · Contributing

---

Why Cohezion?

Other AI Frameworks	Cohezion
Each session starts fresh	182 skills compound — session N+1 builds on session N
Assumes NVIDIA GPU	AMD-first: XDNA2 NPU (42 TPS) + iGPU + CPU, no CUDA
Cloud API = cost per token	No per-token API fees — local inference via the Lemonade router at :13305
Safety = penalty terms in reward	Safety = physics — the Lagrangian attractor makes unsafe actions fight the dynamics
Agent coordination is ad-hoc	HIHO equilibrium — six mathematical frameworks converge at coherence = 0.5
Manual knowledge management	Self-improving loop — SkillRefiner version-bumps skills from execution results

---

Quick Start

At its core Cohezion ships a Gymnasium-compatible training environment plus the tooling to train, evaluate, and reproduce agents in it — all of it CPU-friendly and CUDA-free:

git clone https://github.com/manderson240/cohezion.git && cd cohezion
uv sync  # installs all deps

# 60-second tour: step an agent through the 12D manifold (no network, no GPU)
uv run python examples/quickstart.py

# Validate the compound engineering loop (50+ checks, seconds)
make validate

# Train a PPO agent on the 12D manifold (20K steps, ~5 min)
uv sync --extra rl && make train

Requires: Python 3.13+, uv. Installs from source only (not yet on PyPI); GPU extras pin AMD ROCm wheels — see docs/tutorials/ for a guided setup.

---

Key Capabilities

Self-Improving Compound Loop

Every execution extracts learnings that refine the skill definitions agents use next time:

Execute (CompoundExecutor 11-step pipeline)
  → Reflect  (RetrospectionEngine extracts non-obvious patterns)
  → Refine   (SkillRefiner version-bumps the PRIME skill)
  → Compound (better skill → smarter next execution)

182 PRIME skill definitions in src/cohezion/skills/ are the accumulated output of 100+ development sessions — version-controlled, keyword-indexed, and auto-discoverable. Run the cycle: uv run python scripts/drivers/compound_cycle.py

---

Physics-Grounded Agent Safety

Instead of adding penalty terms to reward functions, Cohezion shapes the environment dynamics so unsafe behavior works against the physics. Agents operate inside a 12D Riemannian manifold governed by:

• Lagrangian dynamics — large unsafe actions fight the Lagrangian attractor (self-correcting)
• SU(2) gauge theory — flat connection = Yang-Mills vacuum = HIHO equilibrium
• Bioelectric percolation — Levin-inspired gap junction network distributes coherence across agents
• Fisher information metric — connects FLUME latent space, manifold geometry, and thermodynamics

Result (from our 8-run diagnostic, reproducible via make benchmark): a random agent shows ~40% safe behavior without any training — the physics guides it — and PPO trained with the Lagrangian attractor reaches 0.9+ coherence without explicit safety constraints.

---

Multi-Agent Swarm with Cost-Aware Routing

Specialist sub-agents collaborate through the compound engineering pipeline. Cost-aware routing sends 70% of requests to local silicon ($0), 20% to mid-tier, and only 10% to high-cost models:

from cohezion.compound import make_executor

executor = make_executor(mcp_client)  # wires Lemonade → SemanticCache → CompoundExecutor
result = await executor.execute_task("Your task here")

Semantic cache (L1 hash + L2 cosine + L3 vault) has reached 95%+ hit rates in internal runs on repeat workloads, dramatically reducing repeat inference cost.

---

Architecture

graph TD
    A[PRIME Skill] --> B[InstructionExpander]
    B --> C[PlanExecutor]
    C --> D[ExecutionOrchestrator]
    D --> E[RequestAlignmentAnalyzer]
    D --> F[DegradationDetector]
    D --> G[JourneyTracker 12D]
    D --> H[SemanticCache L1/L2/L3]
    D --> J[Result]
    J --> K[RetrospectionEngine]
    K --> L[SkillRefiner]
    L --> M[SkillConsensusVoter]
    M -->|Updated Skill| A
    F -->|feedback| N[CostAwareRouter]
    N --> O["NPU  42 TPS  $0"]
    N --> P["iGPU ~200ms $0"]
    N --> Q["CPU  ~800ms $0"]
    N --> R["Cloud  last resort"]

Loading

Module Map

Layer	Module	Entry Point
Compound Loop	compound/ — Executor, SkillRefiner, RetrospectionEngine, JourneyTracker	CompoundExecutor
Swarm	swarm/ — TeamOrchestrator, CostAwareRouter, OI-MAS scoring	CostAwareRouter
Semantic Cache	cache/ — L1 hash + L2 cosine + L3 vault, 95%+ hit rate	SemanticCache
Physics Engine	physics/ — SU(2) spinors, Lagrangian, fiber bundles, gauge theory, cosmogony	SpinorState
RL Environments	environments/ — ManifoldEnv (19D obs), SwarmEnv (multi-agent gauge coupling)	gym.make('Cohezion/ManifoldEnv-v0')

The info dict returned by ManifoldEnv.reset() / step() carries these keys (see the class and step() docstrings in src/cohezion/environments/manifold_env.py for the authoritative, fully-specified list):

Key	Meaning
coherence	current coherence (1.0 = HIHO safe equilibrium)
avg_coherence	running episode average
invariant_passed / invariant_failed	physics-invariant check counts (only present when the optional InvariantChecker is active; absent otherwise)
World Model	world_model/ — JEPA predictor (86K params), bioelectric network, EVO model
FLUME VAE	flume/ — 256D thought vectors, PolarQuant (2.7x compression), QJL (32x)
Knowledge	ouroboros/ + vault — Mycelium transport, SurrealDB, Obsidian
API	api/ — FastAPI backend, AG-UI event streaming (15+ typed SSE events)
Genesis UI	src/web/ — Next.js 16, Three.js Bloch sphere, swarm topology viz

---

Local Inference Stack

Cohezion runs its entire inference pipeline on AMD silicon — no NVIDIA, no cloud required:

Lemonade Router :13305  (single endpoint for the full model catalog)
│
├── NPU  — llama3.2-1b-FLM      42 TPS  │ classification, routing, short answers
├── iGPU — Gemma-4-E4B-it-GGUF  ~200ms  │ code gen, structured output
└── CPU  — DeepSeek-Qwen3-8B     ~800ms  │ reasoning, multi-step analysis

Routing is automatic — cheap tiers first, escalate only when quality gates fail:

from cohezion.inference.triune_orchestrator import build_triune_orchestrator
from cohezion.compound import make_executor

executor = make_executor(mcp_client, provider=build_triune_orchestrator())

Hardware: AMD Strix Halo — Ryzen AI MAX+ 395 (16C/32T, XDNA2 NPU), Radeon 8060S (iGPU), 128 GiB LPDDR5X unified memory. No CUDA. No NVIDIA tax.

Check availability: curl -s http://localhost:13305/v1/models

---

Training Results

The physics and RL layers stand alone — you can train agents in the manifold without ever touching the compound loop. An 8-run diagnostic across the 2×2 algorithm-reward matrix (PPO/SAC × curriculum/dense). Reproduce with make train (20K steps, ~5 min) or make benchmark (100K steps):

Algorithm	Reward Mode	Steps	Reward	vs Random	vs Greedy
PPO	curriculum	100K	14.23	+7.51	+1.34
SAC	dense	100K	40.77	+3.40	-1.20
PPO	dense	100K	38.95	-1.79	+3.73

Best: SAC + dense reward, 100K steps. SAC's off-policy replay cooperates with the Lagrangian attractor; dense reward gives simpler gradients than curriculum at scale.

Checkpoint: data/rl/checkpoints/policy_final.pt

---

The HIHO principle

HIHO (Half-In, Half-Out) — coherence = 0.5 — is where six mathematical frameworks independently converge to the same stable equilibrium:

1. Brahmagupta (628 CE): deviation = coherence − 0.5 = 0
2. Friston Free Energy: F = E − TS minimization
3. Yang-Mills gauge theory: flat connection at HIHO vacuum
4. Fisher information metric: natural gradient minimum
5. Bloch sphere equator: (|↑⟩ + |↓⟩)/√2 superposition
6. Landau phase transition: order parameter at critical temperature

This convergence is not a coincidence — it is the mathematical structure of stable complex systems. HIHO is the attractor. Implementation: src/cohezion/physics/cosmogony.py

---

Agentic-First Development

Cohezion is built by agents, not just for agents. The 182 PRIME skill definitions are the compounded output of 100+ agentic development sessions.

The CLAUDE.md agent contract is inherited by every sub-agent spawned on this repo. It encodes patterns discovered in production:

• Deferred tool loading — load SendMessage schema before calling it, or it raises InputValidationError
• Vault-first knowledge — all learnings go to ~/vaults/cohezion-vault/, not inline comments
• Post-formatter re-read — ruff reformats files in place; re-read before the next Edit
• Inference routing — port :13305 (Lemonade) serves NPU/iGPU/CPU on demand

The full agent contract, specialist routing table, and coding standards live in CLAUDE.md — start there if you develop with an AI coding agent.

---

Development

make format      # ruff format
make lint        # ruff check + auto-fix
make test        # 12,000+ test suite
make validate    # 50+ compound loop invariant checks
make train       # Train PPO on ManifoldEnv (20K steps; uv sync --extra rl)
make evaluate    # Evaluate trained model vs baselines
make benchmark   # Full 100K training + comparisons
make demo        # Quick 5K demo with evaluation

# Start the FastAPI backend
uv run uvicorn cohezion.api:app --reload   # :8080

# Start the Genesis UI
cd src/web/anima_dashboard && npm run dev  # :3000

---

Documentation

• docs/ARCHITECTURE.md — system architecture deep-dive
• docs/tutorials/ — guided day-1 to day-5 onboarding path
• examples/ — runnable examples, starting with quickstart.py
• docs/ — full documentation index

---

Contributing

Contributions are welcome. See CONTRIBUTING.md.

The most valuable contributions are new PRIME skill definitions — if you discover a non-obvious pattern while working with Cohezion, encode it as a skill file in src/cohezion/skills/. Every verified skill improves every future session for everyone.

---

License

Dual-licensed: AGPL-3.0-or-later for open-source use, with a commercial license available for closed-source deployments — see LICENSING.md.

---

References

• Gymnasium API
• Friston Free Energy Principle
• Levin Bioelectric Networks
• HIHO convergence
• Research manuscripts

---

Built on AMD Strix Halo. No NVIDIA required. AGPL-3.0 (commercial licensing available).