The Seven Work Zones of Emily
A big codebase is easier to work on when you have a map of it. Emily's 192 core modules group into seven zones, each with a distinct purpose and a characteristic kind of engineering risk. If you're thinking about contributing, or trying to understand where a particular concern lives, start here.
Zone 1: Cognitive Core
What it is: The part of Emily that is Emily — memory tiers, frameworks, routing, identity.
Key modules: memory.py, math.py (EMEB), earl_tracker.py, earl_v2.py, ecgl_recomputer.py, attention.py, l3_consolidator.py, embeddings.py.
Engineering risk: Cognitive quality is measured in distribution shape and retrieval behavior, not in unit-test pass/fail. Regressions here are subtle — they manifest as "Emily feels off," not as a stack trace.
Suited for: engineers comfortable with measuring things that aren't binary. You need to think in terms of distributions, thresholds, and calibration.
Recent work: EARL v2 autonomous correction; 14D contrast fix (epsilon 6,983 unique values; stability 6,446 unique values); L4→L3 consolidation tuning.
Zone 2: Autonomous Execution (Project Helios)
What it is: Deterministic task execution, verification, crash recovery, kill switches.
Key modules: task_registry.py, autonomous_worker.py, verification.py, outcome_feedback.py, reaper.py, clone_provisioning_task.py, clone_safety.py.
Engineering risk: Concurrency correctness (atomic claiming, lease expiration); safety under autonomy; integration with LLM tool-calls.
Suited for: distributed-systems engineers. Transactions, leasing, atomic operations, and timeout/retry design are the core skills.
Recent work: 122/122 tests green; autonomous clone provisioning; safety gate refactor.
Zone 3: LLM Orchestration
What it is: Provider routing, prompt control, context management, tool-calling integration.
Key modules: llm_cognitive_processor.py, chat_processor.py, claude_mcp_client.py, apc_metrics.py.
Engineering risk: Provider API drift, prompt drift, cost runaway, tool-first vs narrate-the-action regressions.
Suited for: engineers who like reading provider changelogs and are patient with debugging prompt behavior. This is the zone closest to the LLM substrate's churn.
Recent work: Gemini context caching; Fast Mode (25s → 10.8s); tool-first routing re-enabled.
Zone 4: Governance & Safety
What it is: Health monitoring, coherence validation, command sandboxing, attribution, content gates.
Key modules: comprehensive_health_check.py, behavior_validator.py, coherence_validator.py, command_validator.py, attribution.py, Semantic Membrane.
Engineering risk: False positives paralyze Emily; false negatives let regressions ship. Calibration is the dominant work here.
Suited for: engineers who enjoy tuning thresholds and thinking about failure modes. This is where product safety lives.
Recent work: Golden Baseline drift monitor; six health monitors unified into a single surface.
Zone 5: Interface & UX
What it is: The Next.js/React surface, SSE streaming, Brain Graph visualization, tool-execution terminal, Helios Mission Control, Factory Floor.
Key modules: aistudio/ tree — ChatInterface.tsx, BrainVisualization.tsx, HeliosMissionControl.tsx, DashboardHome.tsx, HeliosTaskBuilder.tsx.
Engineering risk: UX drift from backend behavior; visualization performance at scale (~15K nodes); SSE stream reliability.
Suited for: frontend engineers with taste for data-dense visualizations and real-time streams.
Recent work: Tool execution visibility UI (Jan 2026); Factory Floor live streaming.
Zone 6: Platform & Ops
What it is: Service management, database provisioning, deployment automation, testing, logging.
Key modules: emily-stack service manager, db_manager.py, scripts/clone_provisioning_wrapper.py, scripts/fix_and_validate.py, test suites.
Engineering risk: Per-user DB provisioning complexity; connection-pool sizing; backup/migration tooling; observability gaps for cognitive metrics.
Suited for: platform/SRE engineers. This is the zone with the most headroom — operational tooling is a known-underinvested area.
Recent work: Git worktree multi-session isolation; auto-repair script; test suite organization.
Zone 7: MCP Integration Surface
What it is: Exposing Emily's capabilities to Claude, ChatGPT, and other external tools via MCP servers.
Key modules: tools/mcp/emily_mcp_claude_server.py, emily_mcp_chatgpt_server.py, emily_mcp_stdio_server.py, emily_mcp_http_server.py, mcp_oauth_provider.py.
Engineering risk: Cross-agent contamination; auth scope leakage; tool manifest drift vs server behavior.
Suited for: engineers who like working at integration boundaries and have patience for the rough edges of an evolving protocol.
Recent work: OAuth provider for MCP; helios_create_clone tool; ~40 domain tools across four servers.
Cross-zone themes
A few patterns span zones:
- Drift detection and correction — Zones 1 and 4 collaborate: cognitive core produces signals, governance monitors detect drift, autonomous execution (Zone 2) corrects it via EARL v2
- Provider independence — Zone 3 shields Zones 1, 2, 4 from provider-specific behavior. When a provider changes, only Zone 3 needs touching
- Per-user isolation — Zones 1, 2, 6 all respect
db_manager.get_connection(user_id)boundary. Any cross-zone change must preserve it
Where to start
For a new contributor, the recommended entry points depend on background:
- Distributed-systems background: Zone 2 (Helios) or Zone 6 (Platform)
- ML/retrieval background: Zone 1 (Cognitive Core) or Zone 4 (Governance)
- Frontend background: Zone 5 (Interface)
- LLM-application background: Zone 3 (Orchestration) or Zone 7 (MCP)
Starting in the zone that matches your background means your first PR lands in a familiar context, even though the surrounding architecture is novel.
The big picture
Seven zones. Three with high strategic risk (Cognitive Core, Governance, Helios). Two with high leverage for new capabilities (Helios, MCP). One with the biggest runway for operational investment (Platform).
If you can see the zones, you can navigate the codebase. The zones are the map.
Part of the Emily OS architecture philosophy series.