# nv5466/deltahyperion architecture

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

- Interactive diagram: https://gitdiagram.com/nv5466/deltahyperion
- Repository: https://github.com/nv5466/deltahyperion

## Overview

#### Purpose and Entry Points
DeltaHyperion DH2 is a Windows-oriented, local research runtime for a persistent artificial subject (“Delta”), emphasizing continuity, bounded agency, local privacy, and controlled external actuation. Primary lifecycle entry point is `delta.ps1`; desktop interaction enters through `delta_desktop_launcher.py`, which uses the direct launcher rather than OpenClaw’s generic UI. Legacy stack scripts remain separate compatibility paths.
Paths: `delta.ps1`, `delta_desktop_launcher.py`, `delta_launcher.py`

#### Runtime Orchestration and Agency
The runtime is composed of supervised loops and decision subsystems rather than a single web service. Startup resolves project/state roots, reads local bridge/launcher configuration, and starts missing services. Agency combines goals, endogenous state, decision logic, autonomy supervision, and preservation constraints before an action is authorized.
Paths: `delta_autonomy_supervisor.py`, `delta_agency_engine.py`, `delta_decision.py`

#### State, Continuity, and Persistence Boundary
Mutable runtime state belongs outside the checkout under `DELTA_STATE_ROOT`; new code should resolve this through configuration and persist through the storage layer. The repository retains many tracked JSON/JSONL files as legacy/migration artifacts. DeltaDB/MuDB provides canonical continuity indexing, migrations, repository access, and workers; snapshots, backup, lifecycle, and retention support recovery and bounded history.
Paths: `delta_config.py`, `delta_storage.py`, `deltadb/database.py`

#### Context Assembly and Retrieval
Conversation and decision inputs are assembled from explicitly scoped sources: files, memories, conversations, command outputs, live state, and optionally DCode evidence. The retrieval package routes requests, gathers evidence, fuses/reranks it, emits prompt packets, and records receipts. Prompt-boundary and redaction layers constrain what reaches model calls.
Paths: `delta_retrieval/router.py`, `delta_retrieval/fusion.py`, `delta_prompt_boundary.py`

#### Models and Execution Interfaces
Local model execution is centered on Ollama, with profiles, scheduling, queues, workers, and topology support. Modelfiles and the training subtree support local fine-tuning/export workflows, but training is a separate pipeline from the operational runtime. The direct launcher bridges user messages to runtime/model execution; the desktop client exposes Chat, Runtime, Dashboard, Logs, and Settings.
Paths: `delta_ollama_client.py`, `delta_model_scheduler.py`, `delta_launcher_bridge.py`

#### Safety, Governance, and External Boundaries
The core boundary is that persistent identity, memory, private context, and continuity data remain local. Containment, runtime security, egress validation, secret redaction, contact/message safety, and self-modification gating regulate effects and disclosures. Policies and causal receipts make decisions and external results auditable.
Paths: `delta_containment.py`, `delta_egress.py`, `delta_self_modification_gate.py`

#### Integrations and Host Observation
DeltaScope is a typed, host-scoped inventory/telemetry subsystem supporting Windows, Linux, macOS, and Raspberry Pi through platform adapters and a CLI. OpenClaw is an optional bridge/plugin boundary, not the primary chat route. DCode is a separately configured executable integration: a single bridge invokes it without a shell, limits mappings/payloads, validates identity, redacts returned evidence, and preserves the existing path as authoritative until explicit cutover.
Paths: `delta_scope/manager.py`, `openclaw-plugin-delta-core/index.ts`, `delta_dcode_bridge.py`

Main entry points: [`delta_retrieval/router.py`](https://github.com/nv5466/deltahyperion/blob/master/delta_retrieval/router.py) (Retrieval router), [`delta_decision.py`](https://github.com/nv5466/deltahyperion/blob/master/delta_decision.py) (Decision logic), [`delta_storage.py`](https://github.com/nv5466/deltahyperion/blob/master/delta_storage.py) (Storage layer), [`delta_launcher_bridge.py`](https://github.com/nv5466/deltahyperion/blob/master/delta_launcher_bridge.py) (Launcher bridge)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry Points"]
  node_powershell["Lifecycle launcher<br/>PowerShell entry<br/>[delta.ps1]"]
  node_desktop["Desktop client<br/>desktop UI"]
  node_launcher["Direct launcher<br/>message launcher<br/>[delta_launcher.py]"]
end

subgraph group_runtime["Runtime &amp; Agency"]
  node_autonomy["Autonomy supervisor<br/>agency supervision"]
  node_agency["Agency engine<br/>goal and state engine"]
  node_decision["Decision logic<br/>action authorization<br/>[delta_decision.py]"]
end

subgraph group_continuity["Continuity &amp; Context"]
  node_config["State configuration<br/>root resolution<br/>[delta_config.py]"]
  node_storage[("Storage layer<br/>persistence boundary<br/>[delta_storage.py]")]
  node_deltadb[("DeltaDB / MuDB<br/>continuity database<br/>[database.py]")]
  node_retrieval_router["Retrieval router<br/>evidence routing<br/>[router.py]"]
  node_retrieval_fusion["Evidence fusion<br/>reranking and packets<br/>[fusion.py]"]
  node_prompt_boundary["Prompt boundary<br/>context redaction"]
end

subgraph group_execution["Model Execution"]
  node_launcher_bridge["Launcher bridge<br/>runtime bridge"]
  node_scheduler["Model scheduler<br/>model orchestration"]
  node_ollama["Ollama client<br/>local model interface"]
end

subgraph group_boundaries["Safety &amp; Integrations"]
  node_containment["Containment<br/>runtime security"]
  node_egress["Egress control<br/>external actuation guard<br/>[delta_egress.py]"]
  node_self_mod_gate["Self-modification gate<br/>change authorization"]
  node_scope["DeltaScope<br/>host inventory and telemetry<br/>[manager.py]"]
  node_dcode["DCode bridge<br/>external evidence bridge"]
  node_openclaw["OpenClaw plugin<br/>optional integration<br/>[index.ts]"]
end

node_powershell -->|"resolves roots"| node_config
node_powershell -->|"starts"| node_autonomy
node_desktop -->|"uses directly"| node_launcher
node_launcher -->|"submits messages"| node_launcher_bridge
node_launcher_bridge -->|"requests execution"| node_scheduler
node_autonomy -->|"supervises"| node_agency
node_agency -->|"proposes actions"| node_decision
node_decision -->|"gates self changes"| node_self_mod_gate
node_decision -->|"authorizes effects"| node_egress
node_config -->|"locates state root"| node_storage
node_storage -->|"persists continuity"| node_deltadb
node_retrieval_router -->|"retrieves memories"| node_deltadb
node_retrieval_router -.->|"optional evidence"| node_dcode
node_retrieval_router -->|"gathers evidence"| node_retrieval_fusion
node_retrieval_fusion -->|"builds prompt packet"| node_prompt_boundary
node_prompt_boundary -->|"permits context"| node_scheduler
node_scheduler -->|"dispatches local jobs"| node_ollama
node_containment -->|"protects local data"| node_storage
node_scope -->|"supplies live state"| node_retrieval_router
node_openclaw -.->|"optional bridge"| node_launcher_bridge

click node_powershell "https://github.com/nv5466/deltahyperion/blob/master/delta.ps1"
click node_desktop "https://github.com/nv5466/deltahyperion/blob/master/delta_desktop_launcher.py"
click node_launcher "https://github.com/nv5466/deltahyperion/blob/master/delta_launcher.py"
click node_launcher_bridge "https://github.com/nv5466/deltahyperion/blob/master/delta_launcher_bridge.py"
click node_autonomy "https://github.com/nv5466/deltahyperion/blob/master/delta_autonomy_supervisor.py"
click node_agency "https://github.com/nv5466/deltahyperion/blob/master/delta_agency_engine.py"
click node_decision "https://github.com/nv5466/deltahyperion/blob/master/delta_decision.py"
click node_config "https://github.com/nv5466/deltahyperion/blob/master/delta_config.py"
click node_storage "https://github.com/nv5466/deltahyperion/blob/master/delta_storage.py"
click node_deltadb "https://github.com/nv5466/deltahyperion/blob/master/deltadb/database.py"
click node_retrieval_router "https://github.com/nv5466/deltahyperion/blob/master/delta_retrieval/router.py"
click node_retrieval_fusion "https://github.com/nv5466/deltahyperion/blob/master/delta_retrieval/fusion.py"
click node_prompt_boundary "https://github.com/nv5466/deltahyperion/blob/master/delta_prompt_boundary.py"
click node_scheduler "https://github.com/nv5466/deltahyperion/blob/master/delta_model_scheduler.py"
click node_ollama "https://github.com/nv5466/deltahyperion/blob/master/delta_ollama_client.py"
click node_containment "https://github.com/nv5466/deltahyperion/blob/master/delta_containment.py"
click node_egress "https://github.com/nv5466/deltahyperion/blob/master/delta_egress.py"
click node_self_mod_gate "https://github.com/nv5466/deltahyperion/blob/master/delta_self_modification_gate.py"
click node_scope "https://github.com/nv5466/deltahyperion/blob/master/delta_scope/manager.py"
click node_dcode "https://github.com/nv5466/deltahyperion/blob/master/delta_dcode_bridge.py"
click node_openclaw "https://github.com/nv5466/deltahyperion/blob/master/openclaw-plugin-delta-core/index.ts"

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_powershell,node_desktop,node_launcher toneBlue
class node_autonomy,node_agency,node_decision toneAmber
class node_config,node_storage,node_deltadb,node_retrieval_router,node_retrieval_fusion,node_prompt_boundary toneMint
class node_launcher_bridge,node_scheduler,node_ollama toneRose
class node_containment,node_egress,node_self_mod_gate,node_scope,node_dcode,node_openclaw toneIndigo
```

## Components

### Entry Points

- [Lifecycle launcher](https://github.com/nv5466/deltahyperion/blob/master/delta.ps1): PowerShell entry · Resolves roots and starts missing local services. · `delta.ps1`
- [Desktop client](https://github.com/nv5466/deltahyperion/blob/master/delta_desktop_launcher.py): desktop UI · Exposes Chat, Runtime, Dashboard, Logs, and Settings. · `delta_desktop_launcher.py`
- [Direct launcher](https://github.com/nv5466/deltahyperion/blob/master/delta_launcher.py): message launcher · `delta_launcher.py`

### Runtime & Agency

- [Autonomy supervisor](https://github.com/nv5466/deltahyperion/blob/master/delta_autonomy_supervisor.py): agency supervision · Supervises bounded autonomous operation. · `delta_autonomy_supervisor.py`
- [Agency engine](https://github.com/nv5466/deltahyperion/blob/master/delta_agency_engine.py): goal and state engine · `delta_agency_engine.py`
- [Decision logic](https://github.com/nv5466/deltahyperion/blob/master/delta_decision.py): action authorization · `delta_decision.py`

### Continuity & Context

- [State configuration](https://github.com/nv5466/deltahyperion/blob/master/delta_config.py): root resolution · Resolves DELTA_STATE_ROOT outside the checkout. · `delta_config.py`
- [Storage layer](https://github.com/nv5466/deltahyperion/blob/master/delta_storage.py): persistence boundary · `delta_storage.py`
- [DeltaDB / MuDB](https://github.com/nv5466/deltahyperion/blob/master/deltadb/database.py): continuity database · Provides canonical indexing, migrations, repository access, and workers. · `deltadb/database.py`
- [Retrieval router](https://github.com/nv5466/deltahyperion/blob/master/delta_retrieval/router.py): evidence routing · Scopes and gathers context sources. · `delta_retrieval/router.py`
- [Evidence fusion](https://github.com/nv5466/deltahyperion/blob/master/delta_retrieval/fusion.py): reranking and packets · Fuses evidence and emits prompt packets with receipts. · `delta_retrieval/fusion.py`
- [Prompt boundary](https://github.com/nv5466/deltahyperion/blob/master/delta_prompt_boundary.py): context redaction · Constrains model-bound context. · `delta_prompt_boundary.py`

### Model Execution

- [Launcher bridge](https://github.com/nv5466/deltahyperion/blob/master/delta_launcher_bridge.py): runtime bridge · Bridges user messages into runtime and model execution. · `delta_launcher_bridge.py`
- [Model scheduler](https://github.com/nv5466/deltahyperion/blob/master/delta_model_scheduler.py): model orchestration · Manages local queues, workers, profiles, and topology. · `delta_model_scheduler.py`
- [Ollama client](https://github.com/nv5466/deltahyperion/blob/master/delta_ollama_client.py): local model interface · `delta_ollama_client.py`

### Safety & Integrations

- [Containment](https://github.com/nv5466/deltahyperion/blob/master/delta_containment.py): runtime security · Protects local identity, memory, and continuity boundaries. · `delta_containment.py`
- [Egress control](https://github.com/nv5466/deltahyperion/blob/master/delta_egress.py): external actuation guard · Validates disclosures and external effects. · `delta_egress.py`
- [Self-modification gate](https://github.com/nv5466/deltahyperion/blob/master/delta_self_modification_gate.py): change authorization · `delta_self_modification_gate.py`
- [DeltaScope](https://github.com/nv5466/deltahyperion/blob/master/delta_scope/manager.py): host inventory and telemetry · Uses typed platform adapters across supported hosts. · `delta_scope/manager.py`
- [DCode bridge](https://github.com/nv5466/deltahyperion/blob/master/delta_dcode_bridge.py): external evidence bridge · Invokes the configured executable without a shell and redacts evidence. · `delta_dcode_bridge.py`
- [OpenClaw plugin](https://github.com/nv5466/deltahyperion/blob/master/openclaw-plugin-delta-core/index.ts): optional integration · Optional bridge, not the primary chat route. · `openclaw-plugin-delta-core/index.ts`

## Connections

- Lifecycle launcher → State configuration: resolves roots
- Lifecycle launcher → Autonomy supervisor: starts
- Desktop client → Direct launcher: uses directly
- Direct launcher → Launcher bridge: submits messages
- Launcher bridge → Model scheduler: requests execution
- Autonomy supervisor → Agency engine: supervises
- Agency engine → Decision logic: proposes actions
- Decision logic → Self-modification gate: gates self changes
- Decision logic → Egress control: authorizes effects
- State configuration → Storage layer: locates state root
- Storage layer → DeltaDB / MuDB: persists continuity
- Retrieval router → DeltaDB / MuDB: retrieves memories
- Retrieval router → DCode bridge: optional evidence
- Retrieval router → Evidence fusion: gathers evidence
- Evidence fusion → Prompt boundary: builds prompt packet
- Prompt boundary → Model scheduler: permits context
- Model scheduler → Ollama client: dispatches local jobs
- Containment → Storage layer: protects local data
- DeltaScope → Retrieval router: supplies live state
- OpenClaw plugin → Launcher bridge: optional bridge