How pushingsquares/ari-os works
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: retrieve.py Hybrid retrieval · embed.py Embedding service · db.py Brain database · monitor.py Worker monitor
Components 31
Work orchestration
- Worker dispatch
ari_os/tools/dispatch.py - Background workers
Operator tools
- Worker monitor
ari_os/tools/monitor.py - Worker state
ari_os/tools/state.py - Status line
ari_os/tools/statusline.py - Reply formatting
ari_os/tools/format.py - Model requests
ari_os/tools/ask.py
Cortex memory
- Session context hook
ari_os/hooks/session_start_cortex.py - Cortex commands
ari_os/tools/cortex/cortex.py - Embedding service
ari_os/tools/cortex/embed.py - Brain database
ari_os/tools/cortex/db.py - Brain configuration
ari_os/tools/cortex/config.py - Memory consolidation
ari_os/tools/cortex/dream.py - Memory distillation
ari_os/tools/cortex/distill.py
Recall and cognition
- Hybrid retrieval
ari_os/tools/cortex/retrieve.py - Mode routing
ari_os/tools/cortex/mode_router.py - Routing configuration
ari_os/tools/cortex/mode_routing.py - Mode profiles
ari_os/tools/cortex/modes/loader.py - Task classification
ari_os/tools/cortex/task_classifier.py - Region weights
ari_os/tools/cortex/task_region_weights.py - Context assembly
ari_os/tools/cortex/context_assembler.py - Council reranking
ari_os/tools/cortex/council.py
Cortex extensions
- Knowledge graph
ari_os/tools/cortex/kg/sweep.py - Entity extraction
ari_os/tools/cortex/kg/extractor.py - Graph storage
ari_os/tools/cortex/kg/store.py - Recall scheduling
ari_os/tools/cortex/fsrs/sweep.py - Media ingestion
ari_os/tools/cortex/media/capture.py - Media engines
ari_os/tools/cortex/media/media_engines.py
Other components
- User
- Ollama service
- Human review
Connections 29
- User → Worker dispatch: starts work
README.md - Worker dispatch → Background workers: spawns workers
README.md - Background workers → Worker monitor: tracked by
README.md - User → Worker monitor: watches progress
README.md - Worker monitor → Worker state: reads state
ari_os/tools/monitor.py - User → Human review: reviews results
README.md - Session context hook → Hybrid retrieval: requests context
ari_os/hooks/session_start_cortex.py - Session context hook → Embedding service: creates client
ari_os/hooks/session_start_cortex.py - Hybrid retrieval → Brain database: queries memories
ari_os/tools/cortex/retrieve.py - Hybrid retrieval → Embedding service: embeds query
ari_os/tools/cortex/retrieve.py - Hybrid retrieval → Mode routing: selects posture
ari_os/tools/cortex/retrieve.py - Hybrid retrieval → Routing configuration: loads posture
ari_os/tools/cortex/retrieve.py - Hybrid retrieval → Mode profiles: loads profile
ari_os/tools/cortex/retrieve.py - Hybrid retrieval → Task classification: classifies query
ari_os/tools/cortex/retrieve.py - Hybrid retrieval → Region weights: uses weights
ari_os/tools/cortex/retrieve.py - Hybrid retrieval → Context assembly: assembles context
ari_os/tools/cortex/retrieve.py - Hybrid retrieval → Council reranking: requests reranking
ari_os/tools/cortex/retrieve.py - Hybrid retrieval → Recall scheduling: uses review boosts
ari_os/tools/cortex/retrieve.py - Embedding service → Brain configuration: loads settings
ari_os/tools/cortex/embed.py - Embedding service → Model requests: resolves API key
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
ari_os/tools/cortex/kg/sweep.py - Knowledge graph → Graph storage: persists graph
ari_os/tools/cortex/kg/sweep.py - Graph storage → Brain database: writes graph
ari_os/tools/cortex/kg/store.py - Recall scheduling → Brain database: reads review state
ari_os/tools/cortex/fsrs/sweep.py - Media ingestion → Media engines: uses engines
- Media engines → Brain configuration: checks settings
ari_os/tools/cortex/media/media_engines.py