# pushingsquares/ari-os architecture

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

- Interactive diagram: https://gitdiagram.com/pushingsquares/ari-os
- Repository: https://github.com/pushingsquares/ari-os

## Overview

ARI-OS is a Claude Code orchestration layer: a user defines work, dispatches detached workers, monitors their progress, answers questions, and reviews results. Its second major capability is Cortex, a local semantic memory that supports recall, consolidation, session-start context, and optional media ingestion. The graph also includes the retrieval and persistence layers that implement Cortex. README statements establish the worker workflow and major capabilities; source-index references and excerpts establish the shown Cortex calls. Some subsystems are documented but unsampled, so their internal connections are omitted.

Main entry points: [`ari_os/tools/cortex/retrieve.py`](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/retrieve.py) (Hybrid retrieval), [`ari_os/tools/cortex/embed.py`](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/embed.py) (Embedding service), [`ari_os/tools/cortex/db.py`](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/db.py) (Brain database), [`ari_os/tools/monitor.py`](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/monitor.py) (Worker monitor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Work orchestration"]
  node_dispatch["Worker dispatch<br/>[dispatch.py]"]
  node_workers["Background workers"]
end

subgraph group_operator["Operator tools"]
  node_monitor["Worker monitor<br/>[monitor.py]"]
  node_worker_state[("Worker state<br/>[state.py]")]
  node_statusline["Status line<br/>[statusline.py]"]
  node_formatting["Reply formatting<br/>[format.py]"]
  node_ask["Model requests<br/>[ask.py]"]
end

subgraph group_memory["Cortex memory"]
  node_session_hook["Session context hook"]
  node_cortex_cli["Cortex commands<br/>[cortex.py]"]
  node_embedding["Embedding service<br/>[embed.py]"]
  node_brain_db[("Brain database<br/>[db.py]")]
  node_brain_config["Brain configuration<br/>[config.py]"]
  node_consolidation["Memory consolidation<br/>[dream.py]"]
  node_distillation["Memory distillation<br/>[distill.py]"]
end

subgraph group_cognition["Recall and cognition"]
  node_retrieval["Hybrid retrieval<br/>[retrieve.py]"]
  node_mode_router["Mode routing<br/>[mode_router.py]"]
  node_mode_config["Routing configuration<br/>[mode_routing.py]"]
  node_mode_loader["Mode profiles<br/>[loader.py]"]
  node_task_classifier["Task classification<br/>[task_classifier.py]"]
  node_region_weights["Region weights"]
  node_context_assembler["Context assembly"]
  node_council["Council reranking<br/>[council.py]"]
end

subgraph group_extensions["Cortex extensions"]
  node_knowledge_graph["Knowledge graph<br/>[sweep.py]"]
  node_kg_extractor["Entity extraction<br/>[extractor.py]"]
  node_kg_store["Graph storage<br/>[store.py]"]
  node_forgetting["Recall scheduling<br/>[sweep.py]"]
  node_media_ingest["Media ingestion<br/>[capture.py]"]
  node_media_engines["Media engines<br/>[media_engines.py]"]
end

node_user(("User"))
node_ollama["Ollama service"]
node_reviewer(("Human review"))

node_user -->|"starts work"| node_dispatch
node_dispatch -->|"spawns workers"| node_workers
node_workers -->|"tracked by"| node_monitor
node_user -->|"watches progress"| node_monitor
node_monitor -->|"reads state"| node_worker_state
node_user -->|"reviews results"| node_reviewer
node_session_hook -->|"requests context"| node_retrieval
node_session_hook -->|"creates client"| node_embedding
node_retrieval -->|"queries memories"| node_brain_db
node_retrieval -->|"embeds query"| node_embedding
node_retrieval -->|"selects posture"| node_mode_router
node_retrieval -->|"loads posture"| node_mode_config
node_retrieval -->|"loads profile"| node_mode_loader
node_retrieval -->|"classifies query"| node_task_classifier
node_retrieval -->|"uses weights"| node_region_weights
node_retrieval -->|"assembles context"| node_context_assembler
node_retrieval -->|"requests reranking"| node_council
node_retrieval -->|"uses review boosts"| node_forgetting
node_embedding -->|"loads settings"| node_brain_config
node_embedding -->|"resolves API key"| node_ask
node_embedding -.->|"requests vectors"| node_ollama
node_consolidation -.->|"updates memories"| node_brain_db
node_distillation -.->|"updates memories"| node_brain_db
node_knowledge_graph -->|"extracts entities"| node_kg_extractor
node_knowledge_graph -->|"persists graph"| node_kg_store
node_kg_store -->|"writes graph"| node_brain_db
node_forgetting -->|"reads review state"| node_brain_db
node_media_ingest -.->|"uses engines"| node_media_engines
node_media_engines -->|"checks settings"| node_brain_config

click node_dispatch "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/dispatch.py"
click node_monitor "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/monitor.py"
click node_worker_state "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/state.py"
click node_statusline "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/statusline.py"
click node_formatting "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/format.py"
click node_ask "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/ask.py"
click node_session_hook "https://github.com/pushingsquares/ari-os/blob/main/ari_os/hooks/session_start_cortex.py"
click node_cortex_cli "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/cortex.py"
click node_retrieval "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/retrieve.py"
click node_mode_router "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/mode_router.py"
click node_mode_config "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/mode_routing.py"
click node_mode_loader "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/modes/loader.py"
click node_task_classifier "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/task_classifier.py"
click node_region_weights "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/task_region_weights.py"
click node_context_assembler "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/context_assembler.py"
click node_council "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/council.py"
click node_embedding "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/embed.py"
click node_brain_db "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/db.py"
click node_brain_config "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/config.py"
click node_consolidation "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/dream.py"
click node_distillation "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/distill.py"
click node_knowledge_graph "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/kg/sweep.py"
click node_kg_extractor "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/kg/extractor.py"
click node_kg_store "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/kg/store.py"
click node_forgetting "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/fsrs/sweep.py"
click node_media_ingest "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/media/capture.py"
click node_media_engines "https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/media/media_engines.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_dispatch,node_workers,node_user,node_reviewer toneBlue
class node_monitor,node_worker_state,node_statusline,node_formatting,node_ask toneAmber
class node_session_hook,node_cortex_cli,node_embedding,node_brain_db,node_brain_config,node_consolidation,node_distillation toneMint
class node_retrieval,node_mode_router,node_mode_config,node_mode_loader,node_task_classifier,node_region_weights,node_context_assembler,node_council toneRose
class node_knowledge_graph,node_kg_extractor,node_kg_store,node_forgetting,node_media_ingest,node_media_engines,node_ollama toneIndigo
```

## Components

### Work orchestration

- [Worker dispatch](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/dispatch.py): `ari_os/tools/dispatch.py`
- **Background workers**

### Operator tools

- [Worker monitor](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/monitor.py): `ari_os/tools/monitor.py`
- [Worker state](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/state.py): `ari_os/tools/state.py`
- [Status line](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/statusline.py): `ari_os/tools/statusline.py`
- [Reply formatting](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/format.py): `ari_os/tools/format.py`
- [Model requests](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/ask.py): `ari_os/tools/ask.py`

### Cortex memory

- [Session context hook](https://github.com/pushingsquares/ari-os/blob/main/ari_os/hooks/session_start_cortex.py): `ari_os/hooks/session_start_cortex.py`
- [Cortex commands](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/cortex.py): `ari_os/tools/cortex/cortex.py`
- [Embedding service](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/embed.py): `ari_os/tools/cortex/embed.py`
- [Brain database](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/db.py): `ari_os/tools/cortex/db.py`
- [Brain configuration](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/config.py): `ari_os/tools/cortex/config.py`
- [Memory consolidation](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/dream.py): `ari_os/tools/cortex/dream.py`
- [Memory distillation](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/distill.py): `ari_os/tools/cortex/distill.py`

### Recall and cognition

- [Hybrid retrieval](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/retrieve.py): `ari_os/tools/cortex/retrieve.py`
- [Mode routing](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/mode_router.py): `ari_os/tools/cortex/mode_router.py`
- [Routing configuration](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/mode_routing.py): `ari_os/tools/cortex/mode_routing.py`
- [Mode profiles](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/modes/loader.py): `ari_os/tools/cortex/modes/loader.py`
- [Task classification](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/task_classifier.py): `ari_os/tools/cortex/task_classifier.py`
- [Region weights](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/task_region_weights.py): `ari_os/tools/cortex/task_region_weights.py`
- [Context assembly](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/context_assembler.py): `ari_os/tools/cortex/context_assembler.py`
- [Council reranking](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/council.py): `ari_os/tools/cortex/council.py`

### Cortex extensions

- [Knowledge graph](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/kg/sweep.py): `ari_os/tools/cortex/kg/sweep.py`
- [Entity extraction](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/kg/extractor.py): `ari_os/tools/cortex/kg/extractor.py`
- [Graph storage](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/kg/store.py): `ari_os/tools/cortex/kg/store.py`
- [Recall scheduling](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/fsrs/sweep.py): `ari_os/tools/cortex/fsrs/sweep.py`
- [Media ingestion](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/media/capture.py): `ari_os/tools/cortex/media/capture.py`
- [Media engines](https://github.com/pushingsquares/ari-os/blob/main/ari_os/tools/cortex/media/media_engines.py): `ari_os/tools/cortex/media/media_engines.py`

### Other components

- **User**
- **Ollama service**
- **Human review**

## Connections

- User → Worker dispatch: starts work (evidence: `README.md`)
- Worker dispatch → Background workers: spawns workers (evidence: `README.md`)
- Background workers → Worker monitor: tracked by (evidence: `README.md`)
- User → Worker monitor: watches progress (evidence: `README.md`)
- Worker monitor → Worker state: reads state (evidence: `ari_os/tools/monitor.py`)
- User → Human review: reviews results (evidence: `README.md`)
- Session context hook → Hybrid retrieval: requests context (evidence: `ari_os/hooks/session_start_cortex.py`)
- Session context hook → Embedding service: creates client (evidence: `ari_os/hooks/session_start_cortex.py`)
- Hybrid retrieval → Brain database: queries memories (evidence: `ari_os/tools/cortex/retrieve.py`)
- Hybrid retrieval → Embedding service: embeds query (evidence: `ari_os/tools/cortex/retrieve.py`)
- Hybrid retrieval → Mode routing: selects posture (evidence: `ari_os/tools/cortex/retrieve.py`)
- Hybrid retrieval → Routing configuration: loads posture (evidence: `ari_os/tools/cortex/retrieve.py`)
- Hybrid retrieval → Mode profiles: loads profile (evidence: `ari_os/tools/cortex/retrieve.py`)
- Hybrid retrieval → Task classification: classifies query (evidence: `ari_os/tools/cortex/retrieve.py`)
- Hybrid retrieval → Region weights: uses weights (evidence: `ari_os/tools/cortex/retrieve.py`)
- Hybrid retrieval → Context assembly: assembles context (evidence: `ari_os/tools/cortex/retrieve.py`)
- Hybrid retrieval → Council reranking: requests reranking (evidence: `ari_os/tools/cortex/retrieve.py`)
- Hybrid retrieval → Recall scheduling: uses review boosts (evidence: `ari_os/tools/cortex/retrieve.py`)
- Embedding service → Brain configuration: loads settings (evidence: `ari_os/tools/cortex/embed.py`)
- Embedding service → Model requests: resolves API key (evidence: `ari_os/tools/cortex/embed.py`)
- Embedding service → Ollama service: requests vectors
- Memory consolidation → Brain database: updates memories
- Memory distillation → Brain database: updates memories
- Knowledge graph → Entity extraction: extracts entities (evidence: `ari_os/tools/cortex/kg/sweep.py`)
- Knowledge graph → Graph storage: persists graph (evidence: `ari_os/tools/cortex/kg/sweep.py`)
- Graph storage → Brain database: writes graph (evidence: `ari_os/tools/cortex/kg/store.py`)
- Recall scheduling → Brain database: reads review state (evidence: `ari_os/tools/cortex/fsrs/sweep.py`)
- Media ingestion → Media engines: uses engines
- Media engines → Brain configuration: checks settings (evidence: `ari_os/tools/cortex/media/media_engines.py`)
