# marshupan/forme-agent architecture

> Architecture diagram of the GitHub repository marshupan/forme-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/marshupan/forme-agent
- Repository: https://github.com/marshupan/forme-agent

## Overview

forme is a persistent agent runtime for complex, ongoing work. Its principal loop assembles memory and context, assesses authority and risk, coordinates a route, executes through governed capabilities, verifies results, and feeds outcomes back into cognition. The repository also exposes this runtime through a web workbench and CLI, and includes installed-host worker and release management. The README establishes the end-to-end product capabilities; several internal runtime connections are not shown in the sampled source, so those relationships are left unasserted or marked unverified.

Main entry points: [`crates/coordination/src/lib.rs`](https://github.com/marshupan/forme-agent/blob/main/crates/coordination/src/lib.rs) (Coordination), [`crates/gateway/src/server.rs`](https://github.com/marshupan/forme-agent/blob/main/crates/gateway/src/server.rs) (Web gateway), [`crates/cognition/src/brain_tick.rs`](https://github.com/marshupan/forme-agent/blob/main/crates/cognition/src/brain_tick.rs) (Cognition tick), [`crates/harness/src/lib.rs`](https://github.com/marshupan/forme-agent/blob/main/crates/harness/src/lib.rs) (Governed harness)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_surface["User surfaces"]
  node_web["Web gateway<br/>[server.rs]"]
  node_frontend["Web workbench<br/>[App.tsx]"]
  node_workbench_views["Workbench views<br/>[Views.tsx]"]
  node_workspace_view["Workspace view<br/>[Workspace.tsx]"]
  node_cli["CLI<br/>[main.rs]"]
  node_frontend_memory["Memory materials<br/>[memory-material.ts]"]
  node_frontend_api["Web API client<br/>[client.ts]"]
  node_project_routes["Project routes<br/>[project-routes.ts]"]
end

subgraph group_runtime["Agent runtime"]
  node_coordination["Coordination<br/>[lib.rs]"]
  node_context["Context assembly<br/>[lib.rs]"]
  node_cognition_tick["Cognition tick<br/>[brain_tick.rs]"]
  node_cognition_memory["Cognitive learning<br/>[m3_c.rs]"]
  node_temporal["Temporal attention<br/>[temporal.rs]"]
end

subgraph group_capabilities["Governed execution"]
  node_capability_registry["Capability registry<br/>[registry.rs]"]
  node_harness["Governed harness<br/>[lib.rs]"]
  node_execution["Execution adapters<br/>[lib.rs]"]
  node_model_registry["Model routing<br/>[registry.rs]"]
end

subgraph group_persistence["Memory and state"]
  node_memory_store["Persistent memory<br/>[lib.rs]"]
  node_event_store[("Event store<br/>[at_rest.rs]")]
end

subgraph group_host["Installed host"]
  node_host_http["Host HTTP service<br/>[http.rs]"]
  node_worker_routes["Worker result routes<br/>[worker_routes.rs]"]
  node_worker_runtime["Isolated workers<br/>[worker.rs]"]
  node_worker_contract["Worker protocol<br/>[worker.rs]"]
  node_installed_storage["Managed config files<br/>[storage.rs]"]
end

node_owner(("Owner"))

node_owner -->|"uses workbench"| node_frontend
node_owner -->|"uses CLI"| node_cli
node_frontend -->|"requests data"| node_frontend_api
node_frontend_api -.->|"calls endpoints"| node_web
node_web -.->|"serves workbench"| node_workbench_views
node_workbench_views -.->|"renders material"| node_frontend_memory
node_workspace_view -.->|"shows project routes"| node_project_routes
node_web -.->|"serves runtime"| node_coordination
node_cli -.->|"composes runtime"| node_coordination
node_coordination -->|"assembles context"| node_context
node_coordination -->|"chooses next work"| node_cognition_tick
node_cognition_tick -.->|"manages attention"| node_temporal
node_cognition_tick -->|"learns from evidence"| node_cognition_memory
node_coordination -->|"selects capabilities"| node_capability_registry
node_coordination -->|"governs execution"| node_harness
node_harness -->|"dispatches work"| node_execution
node_harness -.->|"routes models"| node_model_registry
node_cognition_memory -->|"updates memory"| node_memory_store
node_memory_store -.->|"persists history"| node_event_store
node_host_http -->|"routes requests"| node_worker_routes
node_worker_routes -->|"reads results"| node_worker_runtime
node_worker_runtime -.->|"checks permits"| node_worker_contract
node_installed_storage -.->|"stores configuration"| node_event_store

click node_web "https://github.com/marshupan/forme-agent/blob/main/crates/gateway/src/server.rs"
click node_frontend "https://github.com/marshupan/forme-agent/blob/main/frontend/src/App.tsx"
click node_workbench_views "https://github.com/marshupan/forme-agent/blob/main/frontend/src/components/Views.tsx"
click node_workspace_view "https://github.com/marshupan/forme-agent/blob/main/frontend/src/components/Workspace.tsx"
click node_cli "https://github.com/marshupan/forme-agent/blob/main/crates/cli/src/main.rs"
click node_coordination "https://github.com/marshupan/forme-agent/blob/main/crates/coordination/src/lib.rs"
click node_context "https://github.com/marshupan/forme-agent/blob/main/crates/context/src/lib.rs"
click node_cognition_tick "https://github.com/marshupan/forme-agent/blob/main/crates/cognition/src/brain_tick.rs"
click node_cognition_memory "https://github.com/marshupan/forme-agent/blob/main/crates/cognition/src/m3_c.rs"
click node_temporal "https://github.com/marshupan/forme-agent/blob/main/crates/cognition/src/temporal.rs"
click node_capability_registry "https://github.com/marshupan/forme-agent/blob/main/crates/capabilities/src/registry.rs"
click node_harness "https://github.com/marshupan/forme-agent/blob/main/crates/harness/src/lib.rs"
click node_execution "https://github.com/marshupan/forme-agent/blob/main/crates/execution/src/lib.rs"
click node_model_registry "https://github.com/marshupan/forme-agent/blob/main/crates/models/src/registry.rs"
click node_memory_store "https://github.com/marshupan/forme-agent/blob/main/crates/memory/src/lib.rs"
click node_event_store "https://github.com/marshupan/forme-agent/blob/main/crates/store/src/at_rest.rs"
click node_frontend_memory "https://github.com/marshupan/forme-agent/blob/main/frontend/src/memory-material.ts"
click node_frontend_api "https://github.com/marshupan/forme-agent/blob/main/frontend/src/api/client.ts"
click node_project_routes "https://github.com/marshupan/forme-agent/blob/main/frontend/src/project-routes.ts"
click node_host_http "https://github.com/marshupan/forme-agent/blob/main/crates/execution/src/bin/host/http.rs"
click node_worker_routes "https://github.com/marshupan/forme-agent/blob/main/crates/execution/src/bin/host/worker_routes.rs"
click node_worker_runtime "https://github.com/marshupan/forme-agent/blob/main/crates/execution/src/installed/worker.rs"
click node_worker_contract "https://github.com/marshupan/forme-agent/blob/main/crates/protocol/src/installed_product/worker.rs"
click node_installed_storage "https://github.com/marshupan/forme-agent/blob/main/crates/execution/src/installed/product_config/storage.rs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_web,node_frontend,node_workbench_views,node_workspace_view,node_cli,node_frontend_memory,node_frontend_api,node_project_routes toneBlue
class node_coordination,node_context,node_cognition_tick,node_cognition_memory,node_temporal toneAmber
class node_capability_registry,node_harness,node_execution,node_model_registry toneMint
class node_memory_store,node_event_store toneRose
class node_host_http,node_worker_routes,node_worker_runtime,node_worker_contract,node_installed_storage,node_owner toneIndigo
```

## Components

### User surfaces

- [Web gateway](https://github.com/marshupan/forme-agent/blob/main/crates/gateway/src/server.rs): `crates/gateway/src/server.rs`
- [Web workbench](https://github.com/marshupan/forme-agent/blob/main/frontend/src/App.tsx): `frontend/src/App.tsx`
- [Workbench views](https://github.com/marshupan/forme-agent/blob/main/frontend/src/components/Views.tsx): `frontend/src/components/Views.tsx`
- [Workspace view](https://github.com/marshupan/forme-agent/blob/main/frontend/src/components/Workspace.tsx): `frontend/src/components/Workspace.tsx`
- [CLI](https://github.com/marshupan/forme-agent/blob/main/crates/cli/src/main.rs): `crates/cli/src/main.rs`
- [Memory materials](https://github.com/marshupan/forme-agent/blob/main/frontend/src/memory-material.ts): `frontend/src/memory-material.ts`
- [Web API client](https://github.com/marshupan/forme-agent/blob/main/frontend/src/api/client.ts): `frontend/src/api/client.ts`
- [Project routes](https://github.com/marshupan/forme-agent/blob/main/frontend/src/project-routes.ts): `frontend/src/project-routes.ts`

### Agent runtime

- [Coordination](https://github.com/marshupan/forme-agent/blob/main/crates/coordination/src/lib.rs): `crates/coordination/src/lib.rs`
- [Context assembly](https://github.com/marshupan/forme-agent/blob/main/crates/context/src/lib.rs): `crates/context/src/lib.rs`
- [Cognition tick](https://github.com/marshupan/forme-agent/blob/main/crates/cognition/src/brain_tick.rs): `crates/cognition/src/brain_tick.rs`
- [Cognitive learning](https://github.com/marshupan/forme-agent/blob/main/crates/cognition/src/m3_c.rs): `crates/cognition/src/m3_c.rs`
- [Temporal attention](https://github.com/marshupan/forme-agent/blob/main/crates/cognition/src/temporal.rs): `crates/cognition/src/temporal.rs`

### Governed execution

- [Capability registry](https://github.com/marshupan/forme-agent/blob/main/crates/capabilities/src/registry.rs): `crates/capabilities/src/registry.rs`
- [Governed harness](https://github.com/marshupan/forme-agent/blob/main/crates/harness/src/lib.rs): `crates/harness/src/lib.rs`
- [Execution adapters](https://github.com/marshupan/forme-agent/blob/main/crates/execution/src/lib.rs): `crates/execution/src/lib.rs`
- [Model routing](https://github.com/marshupan/forme-agent/blob/main/crates/models/src/registry.rs): `crates/models/src/registry.rs`

### Memory and state

- [Persistent memory](https://github.com/marshupan/forme-agent/blob/main/crates/memory/src/lib.rs): `crates/memory/src/lib.rs`
- [Event store](https://github.com/marshupan/forme-agent/blob/main/crates/store/src/at_rest.rs): `crates/store/src/at_rest.rs`

### Installed host

- [Host HTTP service](https://github.com/marshupan/forme-agent/blob/main/crates/execution/src/bin/host/http.rs): `crates/execution/src/bin/host/http.rs`
- [Worker result routes](https://github.com/marshupan/forme-agent/blob/main/crates/execution/src/bin/host/worker_routes.rs): `crates/execution/src/bin/host/worker_routes.rs`
- [Isolated workers](https://github.com/marshupan/forme-agent/blob/main/crates/execution/src/installed/worker.rs): `crates/execution/src/installed/worker.rs`
- [Worker protocol](https://github.com/marshupan/forme-agent/blob/main/crates/protocol/src/installed_product/worker.rs): `crates/protocol/src/installed_product/worker.rs`
- [Managed config files](https://github.com/marshupan/forme-agent/blob/main/crates/execution/src/installed/product_config/storage.rs): `crates/execution/src/installed/product_config/storage.rs`

### Other components

- **Owner**

## Connections

- Owner → Web workbench: uses workbench
- Owner → CLI: uses CLI
- Web workbench → Web API client: requests data (evidence: `frontend/src/App.tsx`)
- Web API client → Web gateway: calls endpoints
- Web gateway → Workbench views: serves workbench
- Workbench views → Memory materials: renders material
- Workspace view → Project routes: shows project routes
- Web gateway → Coordination: serves runtime
- CLI → Coordination: composes runtime
- Coordination → Context assembly: assembles context
- Coordination → Cognition tick: chooses next work
- Cognition tick → Temporal attention: manages attention
- Cognition tick → Cognitive learning: learns from evidence
- Coordination → Capability registry: selects capabilities
- Coordination → Governed harness: governs execution
- Governed harness → Execution adapters: dispatches work
- Governed harness → Model routing: routes models
- Cognitive learning → Persistent memory: updates memory
- Persistent memory → Event store: persists history
- Host HTTP service → Worker result routes: routes requests (evidence: `crates/execution/src/bin/host/http.rs`)
- Worker result routes → Isolated workers: reads results (evidence: `crates/execution/src/bin/host/worker_routes.rs`)
- Isolated workers → Worker protocol: checks permits
- Managed config files → Event store: stores configuration
