# Unified System Architecture: Plan Forge + OpenBrain + OpenClaw

> **Purpose**: Architecture reference for integrating Plan Forge, OpenBrain, and OpenClaw into a single automated development system.
>
> **Full version**: [planforge.software/manual/how-it-works.html](https://planforge.software/manual/how-it-works.html)
>
> **Last Updated**: 2026-05-16

---

## Executive Summary

| Project | Problem Solved | Analogy |
|---------|---------------|---------|
| **Plan Forge** | AI agents drift without guardrails | The **blueprint** — what to build, how, and when to stop |
| **OpenBrain** | Every AI session starts from zero | The **memory** — why we decided, what we learned, what failed |
| **OpenClaw** | AI is locked inside one tool/surface | The **nervous system** — always-on orchestration across every channel |

Together they form a closed-loop system: describe a feature from any device → Plan Forge hardens into execution contract → Copilot builds it → OpenBrain captures every decision → OpenClaw notifies you on Slack/Telegram → fresh session reviews with full history.

## Architecture (Simplified)

```
┌─────────────────────────────────────────────────────────────────┐
│                   UNIFIED DEVELOPMENT SYSTEM                     │
│                                                                  │
│  OpenClaw (orchestrator + reach)                                │
│    └── Routes requests from any channel, sends notifications     │
│                                                                  │
│  Plan Forge (methodology + guardrails)                          │
│    └── 7-step pipeline, instruction files, validation gates      │
│                                                                  │
│  Memory subsystem (v2.95.0)                                     │
│    ├── Anvil  ─── Δ-only write-through cache (L2 write path)    │
│    ├── Lattice ── Structural code index (callers, blast radius)  │
│    └── Hallmark ─ Provenance envelope on every L3 write          │
│                                                                  │
│  OpenBrain (memory + context)                                   │
│    └── Semantic search over prior decisions, cross-session       │
│        Supports Hallmark provenance (v0.7.0+)                   │
└─────────────────────────────────────────────────────────────────┘
```

## Integration Points

| Integration | How |
|-------------|-----|
| Plan Forge → OpenBrain | Skills run `search_thoughts` before acting, `capture_thought` after completing — wrapped in Hallmark envelope |
| Plan Forge → OpenClaw | Orchestrator sends webhook notifications on slice completion/failure |
| Plan Forge Audit Loop | `forge_tempering_drain` iterates scan → triage → fix; findings route to bug registry or Crucible |
| OpenBrain → Copilot Memory | `forge_sync_memories` generates hints Copilot Memory auto-discovers |
| OpenClaw → Plan Forge | Routes "build this feature" requests → triggers `forge_run_plan` |

## Memory Layers

| Layer | Scope | Persistence | Content |
|-------|-------|-------------|---------|
| **Copilot Memory** | Repo | 28 days (auto-expire) | Auto-discovered conventions |
| **Plan Forge** | Per-run | Permanent (`.forge/runs/`) | Slice results, gate outcomes, cost |
| **Anvil cache** | Per-repo | Until source changes | Δ-only content hashes (`.forge/anvil/`) |
| **Lattice index** | Per-repo | Until rebuild | Code structure — callers, blast radius (`.forge/lattice/`) |
| **OpenBrain** | Cross-project | Permanent (pgvector) | Architecture decisions, lessons learned — provenance-stamped (v0.7.0+) |

### Memory subsystem integration (v2.95.0)

| Integration | How |
|-------------|-----|
| Plan Forge → Anvil | Every `captureMemory()` call routes through Anvil for Δ-dedup before writing L2 |
| Plan Forge → Lattice | Code-emitting tools notify Lattice; `forge_run_plan` queries `forge_lattice_blast` per slice |
| Plan Forge → Hallmark | Every L3 write via `captureMemory()` is wrapped in a Hallmark provenance envelope |
| Hallmark → OpenBrain | Capability negotiation via `/health` before first write; graceful fallback to bare thoughts |
| Anvil DLQ → Slag-Heap | Rejected L3 writes land in `.forge/anvil/dlq/` for replay via `forge_anvil_dlq_drain` |

## Configuration

Plan Forge works standalone. OpenBrain and OpenClaw are optional enhancements:

```json
// .forge.json
{
  "openbrain": {
    "enabled": true,
    "endpoint": "http://localhost:5200",
    "project": "my-project"
  },
  "notifications": {
    "enabled": true,
    "webhookUrl": "https://hooks.slack.com/...",
    "events": ["run-complete", "slice-failed", "review-passed"]
  },
  "audit": {
    "mode": "off",
    "maxRounds": 5,
    "autoThresholds": { "minFilesChanged": 5, "minDaysSinceLastDrain": 3, "requireFindings": true },
    "environments": ["dev", "staging"],
    "forbidProduction": true
  }
}
```

> **Audit Loop** (v2.80+): The `audit` object controls automatic audit drain activation. Set `mode` to `"auto"` for threshold-gated runs or `"always"` for unconditional drains after plan completion. `"off"` (default) disables automatic drains. Use `pforge audit-loop` for manual one-shot runs regardless of config.

> **Full architecture details** including deployment topology, workspace layout, security model, session management, notification flows, and worked examples are available in the [Interactive Manual](https://planforge.software/manual/how-it-works.html) and preserved in git history (pre-v2.21).