# heraclitus0/alfred architecture

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

- Interactive diagram: https://gitdiagram.com/heraclitus0/alfred
- Repository: https://github.com/heraclitus0/alfred

## Overview

Alfred is a persistent, mission-centered executive agent. Its primary user workflow begins at the CLI, where a user can request a consultation or improvement; runtime services manage consultation threads, build prompts, obtain and store responses, and may prepare bounded sandbox rewrites for validation and promotion. The README also describes browser-assisted ChatGPT use, watchers, missions, approvals, and safety foundations. The graph combines documented workflow with relationships visible in excerpts and the source index; unsampled runtime internals are not assumed.

Main entry points: [`alfred/app.py`](https://github.com/heraclitus0/alfred/blob/main/alfred/app.py) (Runtime assembly), [`alfred/consultation/manager.py`](https://github.com/heraclitus0/alfred/blob/main/alfred/consultation/manager.py) (Consultation manager), [`alfred/memory/base.py`](https://github.com/heraclitus0/alfred/blob/main/alfred/memory/base.py) (Memory facade), [`alfred/research_threads/manager.py`](https://github.com/heraclitus0/alfred/blob/main/alfred/research_threads/manager.py) (Research threads)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime and control"]
  node_cli["CLI controls<br/>[commands.py]"]
  node_app["Runtime assembly<br/>[app.py]"]
  node_runtime_core["Runtime loop<br/>[runtime.py]"]
  node_heartbeat["Heartbeat<br/>[heartbeat.py]"]
end

subgraph group_consultation["Consultation and research"]
  node_consultation_manager["Consultation manager<br/>[manager.py]"]
  node_threads["Research threads<br/>[manager.py]"]
  node_prompts["Prompt engineering<br/>[prompt_engineer.py]"]
  node_llm["LLM consultation<br/>[ollama_client.py]"]
  node_browser["ChatGPT browser<br/>[operator.py]"]
end

subgraph group_improvement["Bounded improvement"]
  node_diagnostics["Weakness diagnosis<br/>[diagnostics.py]"]
  node_proposal["Rewrite proposal"]
  node_sandbox["Rewrite sandbox<br/>[sandbox_runner.py]"]
  node_sandbox_manager["Sandbox workspace<br/>[sandbox_manager.py]"]
  node_promotion["Change promotion<br/>[promoter.py]"]
end

subgraph group_operations["Signals and operations"]
  node_missions["Mission management<br/>[manager.py]"]
  node_watchers["Watcher manager<br/>[manager.py]"]
  node_storage_watcher["Device storage signal<br/>[storage.py]"]
  node_notifications["Notifications<br/>[manager.py]"]
end

subgraph group_foundation["Memory and safety"]
  node_memory["Memory facade<br/>[base.py]"]
  node_database[("Persistent database<br/>[db.py]")]
  node_approval["Rewrite approval<br/>[approval_engine.py]"]
  node_audit["Audit logging<br/>[audit.py]"]
  node_kill_switch["Kill switch<br/>[kill_switch.py]"]
end

node_user(("User"))

node_user -->|"issues commands"| node_cli
node_cli -->|"starts runtime"| node_app
node_app -->|"assembles"| node_runtime_core
node_app -->|"configures"| node_consultation_manager
node_app -->|"configures"| node_threads
node_app -->|"configures"| node_prompts
node_app -->|"configures"| node_llm
node_app -->|"configures"| node_browser
node_app -->|"registers"| node_heartbeat
node_consultation_manager -->|"selects thread"| node_threads
node_consultation_manager -->|"builds prompt"| node_prompts
node_consultation_manager -->|"requests response"| node_llm
node_consultation_manager -->|"stores result"| node_memory
node_consultation_manager -->|"updates summary"| node_threads
node_consultation_manager -->|"records consultation"| node_audit
node_consultation_manager -->|"opens ChatGPT"| node_browser
node_threads -->|"reads and writes"| node_memory
node_watchers -->|"ticks watcher"| node_storage_watcher
node_watchers -->|"emits signals"| node_notifications
node_notifications -->|"stores latest"| node_memory
node_missions -->|"saves mission"| node_memory
node_memory -->|"persists state"| node_database
node_app -->|"configures"| node_missions
node_app -->|"configures"| node_watchers
node_app -->|"configures"| node_notifications
node_app -->|"configures"| node_approval
node_app -->|"configures"| node_audit
node_app -->|"configures"| node_kill_switch
node_app -->|"configures"| node_diagnostics
node_app -->|"configures"| node_proposal
node_app -->|"configures"| node_sandbox
node_app -->|"configures"| node_promotion
node_proposal -.->|"sandbox rewrite"| node_sandbox
node_sandbox -.->|"validates then promotes"| node_promotion
node_approval -.->|"bounds targets"| node_proposal

click node_cli "https://github.com/heraclitus0/alfred/blob/main/alfred/cli/commands.py"
click node_app "https://github.com/heraclitus0/alfred/blob/main/alfred/app.py"
click node_runtime_core "https://github.com/heraclitus0/alfred/blob/main/alfred/core/runtime.py"
click node_heartbeat "https://github.com/heraclitus0/alfred/blob/main/alfred/core/heartbeat.py"
click node_consultation_manager "https://github.com/heraclitus0/alfred/blob/main/alfred/consultation/manager.py"
click node_threads "https://github.com/heraclitus0/alfred/blob/main/alfred/research_threads/manager.py"
click node_prompts "https://github.com/heraclitus0/alfred/blob/main/alfred/prompts/prompt_engineer.py"
click node_llm "https://github.com/heraclitus0/alfred/blob/main/alfred/llm/ollama_client.py"
click node_browser "https://github.com/heraclitus0/alfred/blob/main/alfred/actions/browser/operator.py"
click node_missions "https://github.com/heraclitus0/alfred/blob/main/alfred/missions/manager.py"
click node_watchers "https://github.com/heraclitus0/alfred/blob/main/alfred/watchers/manager.py"
click node_storage_watcher "https://github.com/heraclitus0/alfred/blob/main/alfred/watchers/device/storage.py"
click node_notifications "https://github.com/heraclitus0/alfred/blob/main/alfred/notifications/manager.py"
click node_memory "https://github.com/heraclitus0/alfred/blob/main/alfred/memory/base.py"
click node_database "https://github.com/heraclitus0/alfred/blob/main/alfred/storage/db.py"
click node_approval "https://github.com/heraclitus0/alfred/blob/main/alfred/autonomy/approval_engine.py"
click node_audit "https://github.com/heraclitus0/alfred/blob/main/alfred/safety/audit.py"
click node_kill_switch "https://github.com/heraclitus0/alfred/blob/main/alfred/safety/kill_switch.py"
click node_diagnostics "https://github.com/heraclitus0/alfred/blob/main/alfred/self_improvement/diagnostics.py"
click node_proposal "https://github.com/heraclitus0/alfred/blob/main/alfred/self_improvement/proposal_builder.py"
click node_sandbox "https://github.com/heraclitus0/alfred/blob/main/alfred/self_improvement/sandbox_runner.py"
click node_sandbox_manager "https://github.com/heraclitus0/alfred/blob/main/alfred/actions/projects/sandbox_manager.py"
click node_promotion "https://github.com/heraclitus0/alfred/blob/main/alfred/self_improvement/promoter.py"

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_cli,node_app,node_runtime_core,node_heartbeat,node_user toneBlue
class node_consultation_manager,node_threads,node_prompts,node_llm,node_browser toneAmber
class node_diagnostics,node_proposal,node_sandbox,node_sandbox_manager,node_promotion toneMint
class node_missions,node_watchers,node_storage_watcher,node_notifications toneRose
class node_memory,node_database,node_approval,node_audit,node_kill_switch toneIndigo
```

## Components

### Runtime and control

- [CLI controls](https://github.com/heraclitus0/alfred/blob/main/alfred/cli/commands.py): `alfred/cli/commands.py`
- [Runtime assembly](https://github.com/heraclitus0/alfred/blob/main/alfred/app.py): `alfred/app.py`
- [Runtime loop](https://github.com/heraclitus0/alfred/blob/main/alfred/core/runtime.py): `alfred/core/runtime.py`
- [Heartbeat](https://github.com/heraclitus0/alfred/blob/main/alfred/core/heartbeat.py): `alfred/core/heartbeat.py`

### Consultation and research

- [Consultation manager](https://github.com/heraclitus0/alfred/blob/main/alfred/consultation/manager.py): `alfred/consultation/manager.py`
- [Research threads](https://github.com/heraclitus0/alfred/blob/main/alfred/research_threads/manager.py): `alfred/research_threads/manager.py`
- [Prompt engineering](https://github.com/heraclitus0/alfred/blob/main/alfred/prompts/prompt_engineer.py): `alfred/prompts/prompt_engineer.py`
- [LLM consultation](https://github.com/heraclitus0/alfred/blob/main/alfred/llm/ollama_client.py): `alfred/llm/ollama_client.py`
- [ChatGPT browser](https://github.com/heraclitus0/alfred/blob/main/alfred/actions/browser/operator.py): `alfred/actions/browser/operator.py`

### Bounded improvement

- [Weakness diagnosis](https://github.com/heraclitus0/alfred/blob/main/alfred/self_improvement/diagnostics.py): `alfred/self_improvement/diagnostics.py`
- [Rewrite proposal](https://github.com/heraclitus0/alfred/blob/main/alfred/self_improvement/proposal_builder.py): `alfred/self_improvement/proposal_builder.py`
- [Rewrite sandbox](https://github.com/heraclitus0/alfred/blob/main/alfred/self_improvement/sandbox_runner.py): `alfred/self_improvement/sandbox_runner.py`
- [Sandbox workspace](https://github.com/heraclitus0/alfred/blob/main/alfred/actions/projects/sandbox_manager.py): `alfred/actions/projects/sandbox_manager.py`
- [Change promotion](https://github.com/heraclitus0/alfred/blob/main/alfred/self_improvement/promoter.py): `alfred/self_improvement/promoter.py`

### Signals and operations

- [Mission management](https://github.com/heraclitus0/alfred/blob/main/alfred/missions/manager.py): `alfred/missions/manager.py`
- [Watcher manager](https://github.com/heraclitus0/alfred/blob/main/alfred/watchers/manager.py): `alfred/watchers/manager.py`
- [Device storage signal](https://github.com/heraclitus0/alfred/blob/main/alfred/watchers/device/storage.py): `alfred/watchers/device/storage.py`
- [Notifications](https://github.com/heraclitus0/alfred/blob/main/alfred/notifications/manager.py): `alfred/notifications/manager.py`

### Memory and safety

- [Memory facade](https://github.com/heraclitus0/alfred/blob/main/alfred/memory/base.py): `alfred/memory/base.py`
- [Persistent database](https://github.com/heraclitus0/alfred/blob/main/alfred/storage/db.py): `alfred/storage/db.py`
- [Rewrite approval](https://github.com/heraclitus0/alfred/blob/main/alfred/autonomy/approval_engine.py): `alfred/autonomy/approval_engine.py`
- [Audit logging](https://github.com/heraclitus0/alfred/blob/main/alfred/safety/audit.py): `alfred/safety/audit.py`
- [Kill switch](https://github.com/heraclitus0/alfred/blob/main/alfred/safety/kill_switch.py): `alfred/safety/kill_switch.py`

### Other components

- **User**

## Connections

- User → CLI controls: issues commands (evidence: `README.md`)
- CLI controls → Runtime assembly: starts runtime
- Runtime assembly → Runtime loop: assembles (evidence: `alfred/app.py`)
- Runtime assembly → Consultation manager: configures (evidence: `alfred/app.py`)
- Runtime assembly → Research threads: configures (evidence: `alfred/app.py`)
- Runtime assembly → Prompt engineering: configures (evidence: `alfred/app.py`)
- Runtime assembly → LLM consultation: configures (evidence: `alfred/app.py`)
- Runtime assembly → ChatGPT browser: configures (evidence: `alfred/app.py`)
- Runtime assembly → Heartbeat: registers (evidence: `alfred/app.py`)
- Consultation manager → Research threads: selects thread (evidence: `alfred/consultation/manager.py`)
- Consultation manager → Prompt engineering: builds prompt (evidence: `alfred/consultation/manager.py`)
- Consultation manager → LLM consultation: requests response (evidence: `alfred/consultation/manager.py`)
- Consultation manager → Memory facade: stores result (evidence: `alfred/consultation/manager.py`)
- Consultation manager → Research threads: updates summary (evidence: `alfred/consultation/manager.py`)
- Consultation manager → Audit logging: records consultation (evidence: `alfred/consultation/manager.py`)
- Consultation manager → ChatGPT browser: opens ChatGPT (evidence: `alfred/consultation/manager.py`)
- Research threads → Memory facade: reads and writes (evidence: `alfred/research_threads/manager.py`)
- Watcher manager → Device storage signal: ticks watcher (evidence: `alfred/watchers/manager.py`)
- Watcher manager → Notifications: emits signals (evidence: `alfred/watchers/manager.py`)
- Notifications → Memory facade: stores latest (evidence: `alfred/notifications/manager.py`)
- Mission management → Memory facade: saves mission (evidence: `alfred/missions/manager.py`)
- Memory facade → Persistent database: persists state (evidence: `alfred/app.py`)
- Runtime assembly → Mission management: configures (evidence: `alfred/app.py`)
- Runtime assembly → Watcher manager: configures (evidence: `alfred/app.py`)
- Runtime assembly → Notifications: configures (evidence: `alfred/app.py`)
- Runtime assembly → Rewrite approval: configures (evidence: `alfred/app.py`)
- Runtime assembly → Audit logging: configures (evidence: `alfred/app.py`)
- Runtime assembly → Kill switch: configures (evidence: `alfred/app.py`)
- Runtime assembly → Weakness diagnosis: configures (evidence: `alfred/app.py`)
- Runtime assembly → Rewrite proposal: configures (evidence: `alfred/app.py`)
- Runtime assembly → Rewrite sandbox: configures (evidence: `alfred/app.py`)
- Runtime assembly → Change promotion: configures (evidence: `alfred/app.py`)
- Rewrite proposal → Rewrite sandbox: sandbox rewrite (evidence: `README.md`)
- Rewrite sandbox → Change promotion: validates then promotes (evidence: `README.md`)
- Rewrite approval → Rewrite proposal: bounds targets (evidence: `README.md`)
