CortexObserver is the natural-language command layer for an AI workforce — Agentic & Ecosystem Command-and-Control. Humans set the rules. Specialized AI agents, each a LangGraph StateGraph, do real work inside those rules. Results render back as live truth. Then humans adjust, and the loop runs again.
This document is the conceptual map: the circular loop, the four layers that make it turn, A.T.O.M and time as the universal index, and where to go for the details.
CortexObserver runs on one operating principle. There is no open end — every action an agent takes flows back to the humans who defined the rules that constrained it.
Humans define policies & budgets → Farms enforce them → Agents work within the constraints → Results flow back as live truth → Humans observe and adjust → repeat.
graph LR
H["<b>HUMANS</b><br/>Define policies<br/>& budgets"]
F["<b>FARMS</b><br/>Enforce rules<br/>& provide services"]
A["<b>AGENTS</b><br/>Execute work<br/>within constraints"]
R["<b>RESULTS</b><br/>Live truth — metrics,<br/>memories, audit trails"]
H -->|"policies, budgets,<br/>grants, quotas"| F
F -->|"governed services<br/>& tool access"| A
A -->|"cost, risk points,<br/>memory writes"| R
R -->|"dashboards, alerts,<br/>spend vs budget"| H
style H fill:#2563eb,stroke:#1e40af,color:#fff
style F fill:#d97706,stroke:#b45309,color:#fff
style A fill:#16a34a,stroke:#15803d,color:#fff
style R fill:#7c3aed,stroke:#6d28d9,color:#fff
Neither half works alone. Policies without agents are unexecuted intent. Agents without policies are ungoverned risk. The Farms are the connective tissue that lets both operate on the same knowledge at different abstraction levels — and the loop closes when what an agent did is verified back against what a human intended.
The key property: enforcement is structural, not prompt-dependent. An agent cannot talk its way past a budget or a tool grant, because the check is code on the path of execution, not an instruction it could ignore.
Humans don't execute infrastructure tasks directly. They define the rules under which agents operate — policies, procedures, standards, budgets, grants, quotas, model tiers, risk scores, retention windows, skills — then observe outcomes and adjust. Everything is managed through the Next.js 15 dashboards, where each Farm has its own human control plane.
Commander is the NLP command surface — Mission Control. You speak intent and @mention a specialist to dispatch it; the agent's reasoning graph then executes node-by-node with live state, human approval gates, and replay.
Mission Control: type a request, @mention a specialist, and watch the agent team execute.
Each agent is an individual LangGraph StateGraph with its own topology, skills, and tool bindings. Agents consume Farm services — they never implement tools themselves.
| Same for every agent | Distinct per agent |
|---|---|
Extends BaseAgent (backend/src/cortex/agents/base/agent_interface.py) |
Graph topology — nodes, conditional edges, approval gates |
Compiles a StateGraph via create_graph() |
Skills — domain expertise injected into the LLM system prompt |
Registered in AgentRegistry at startup |
Tool grants — which MCPFarm tools it may invoke |
Dispatched via POST /api/commander/agents/{key}/dispatch |
Model tier, memory window, and daily risk budget |
The roster spans @allen (Cloud Architect), @amy (ML Engineer), @charles/@charlene/@chad (Trading Desk), @brian (Software Developer), @bishop (Medical Reasoning), @becky, @alice, and @chat. See AGENTS.md for the repeatable pattern and each desk's deep dive.
Farms aren't resource pools — they are governance layers that enforce human-defined rules in code. Every agent action passes through at least one Farm.
| Farm | Enforces | File root |
|---|---|---|
| MCPFarm | Tool grants, risk budgets, deploy prerequisites | backend/src/cortex/mcpfarm/ |
| LLM Gateway | Model budgets, model-tier restrictions | backend/src/cortex/gateway/llm.py |
| Memory Farm | Memory quotas, session limits, scope isolation | backend/src/cortex/memory/ |
| Knowledge Farm | Corpus quotas, source lifecycle, provenance | backend/src/cortex/knowledge/ |
| Allocation | Cross-cutting budgets, quotas, grants (shared state) | backend/src/cortex/models/allocation.py |
When an agent node executes, it reaches into the Farms — and each call both checks a constraint and records a result:
Agent node executes
├─ LLM Gateway · invoke_llm() checks budget + model tier → records cost, tokens
├─ MCPFarm · tool_executor.execute() checks grant + risk budget → records risk points, audit
├─ Memory Farm · store.recall()/write() checks memory quotas → records observed_at
└─ Knowledge Farm · store.retrieve() checks knowledge quotas → records retrieval provenance
Those recorded results are exactly the "live truth" that flows back to humans. See FARMS.md for the deep dive on each control plane.
Humans encode intent as Policies, Procedures, and Standards, which become agent Prompts, Skills, and Tools:
HUMAN LAYER AGENT LAYER
─────────── ───────────
Policy (business intent) → Prompt (reasoning context)
Procedure(how to fulfill) → Skill (domain expertise)
Standard (applied metadata) ←→ Tool output (executed metadata)
The circle closes when applied metadata — what agents did — is verified back against the governing policy — what humans intended. Drift detection, compliance audits, and reconciliation all live here. Agent expertise is itself governed in the Skills Store, and principals (agent / human / service) are unified in the Identity Store with RBAC. See GOVERNANCE.md.
graph TD
subgraph Frontend["<b>HUMANS</b> — Next.js 15 dashboards"]
UI[Mission Control · Farm control planes · Governance]
end
subgraph API["<b>API Layer</b> — FastAPI"]
Routes[REST routes + WebSocket hub]
end
subgraph Cmd["<b>COMMANDER + AGENTS</b>"]
DISP[Dispatch] --> AG[Per-agent LangGraph StateGraphs]
end
subgraph Farms["<b>FARMS</b> — control plane"]
MCP[MCPFarm<br/>tools + risk scoring]
GW[LLM Gateway<br/>model registry + budgets]
MEM[Memory Farm<br/>L1–L4, consolidation]
KN[Knowledge Farm<br/>Qdrant hybrid RAG]
ALLOC[Allocation<br/>budgets + quotas]
end
subgraph Data["<b>DATA & CLOUD</b>"]
PG[(PostgreSQL)]
RD[(Redis)]
QD[(Qdrant)]
AWS[(AWS · CloudFormation · SSM)]
end
UI --> Routes --> DISP
AG --> MCP & GW & MEM & KN & ALLOC
MCP --> PG
GW --> PG
MEM --> RD & PG
KN --> QD & AWS
ALLOC --> PG
MCP --> AWS
style Frontend fill:#1e3a5f,stroke:#3b82f6,color:#fff
style API fill:#1e3a5f,stroke:#3b82f6,color:#fff
style Cmd fill:#14532d,stroke:#16a34a,color:#fff
style Farms fill:#78350f,stroke:#d97706,color:#fff
style Data fill:#1a1a2e,stroke:#6366f1,color:#fff
The home surface (/dashboard/worldmaker) is A.T.O.M — the Agentic Temporal Operating Model: a single pane of glass over the real AWS estate, not an authored model of it. Two intake vectors keep it true to what is actually running:
-
Discovery (absorb) — humans and other teams build in AWS outside CortexObserver. The discovery engine (
cortex/worldmaker/engine/aws_discovery.py) scans via the AWS Resource Groups Tagging API, persists resources to the inventory, and marks vanished resources as drift. -
Deploy (project) — the Cloud Architect agent (
@allen) provisions CloudFormation/CDK stacks through the realBootstrapEngine(describe_stacks, drift detection). Each deployment's stack → resource graph feeds the dependency DAG (cortex/worldmaker/db/graph_queries.py).
Discovery → Inventory → Dependencies
(recon in) (what's running) (how it's wired —
the CFN stack graph)
A.T.O.M: the live AWS estate landing — deployment cards over discovered and agent-deployed infrastructure.
The AWS estate is just another stream of time-indexed truth — governed by the same Farms and indexed by the same ecosystem clock as everything else. See CLOUD.md for @allen, CDK synth → deploy, and the dependency DAG.
Ecosystem generation (authoring products/platforms/services in the UI) and the DLM strategy layer were removed in the 2026-06 baseline. A.T.O.M now reflects only what exists in AWS — discovered or deployed.
A.T.O.M's "Temporal" is not decoration. CortexObserver operates on naturally occurring time: every Farm, memory, observation, and agent action is indexed by UTC. There are no batch jobs and no artificial cycles — time flows, agents work, Farms enforce, the clock ticks, and everything is indexed by when it happened.
The ecosystem clock: backend/src/cortex/core/clock.py is the one true time source.
from cortex.core.clock import utc_now, time_ago, time_window, ensure_utc, format_relative| Helper | Purpose |
|---|---|
utc_now() |
The single source of truth for "now" |
time_ago(hours=24) |
Memory-window queries |
time_window(since, until) |
Validated UTC range for API queries |
ensure_utc(dt) |
Coerces naive/local datetimes |
format_relative(dt) |
Human-readable ("3 hours ago") |
Why a shared clock matters:
- Agents recall only as far back as their skill-defined memory window — e.g. @allen at 72h for slow infrastructure changes, @brian at 24h for session-focused code generation.
- Memory consolidation runs over time windows — recent episodic events distilled into semantic knowledge.
- Budget resets are time-based (monthly spend periods); risk budgets reset daily.
- Knowledge freshness is measured by time since last scan; all audit trails are time-ordered.
sequenceDiagram
participant CLK as clock.py · utc_now()
participant CMD as Commander
participant MEM as Memory Farm
participant KN as Knowledge Farm
participant ALLOC as Allocation
CLK->>CMD: timestamp on dispatch & completion
CLK->>MEM: observed_at on every memory write
CLK->>KN: created_at on ingestion & scan
CLK->>ALLOC: spend periods & resets
Note over CLK,ALLOC: All timestamps UTC — no timezones, no cron, no batch
CMD-->>MEM: agent memories stored
CMD-->>KN: RAG context retrieved
MEM-->>ALLOC: quota counts update
KN-->>ALLOC: corpus-limit checks
| Layer | Technology |
|---|---|
| Frontend | Next.js 15 (App Router), TypeScript, Tailwind CSS, @xyflow/react (React Flow), lucide-react |
| Backend | FastAPI (async), Python 3.12+, SQLAlchemy 2.0 (mapped_column/Mapped), Pydantic |
| Agents | LangGraph — one StateGraph per agent |
| LLM routing | LiteLLM (SDK mode default, proxy mode opt-in) — Anthropic Claude, OpenAI GPT-4o, and more |
| Data | PostgreSQL (pgvector), Redis (L1 memory + pub/sub), Qdrant (per-agent collections) |
| Cloud | AWS CloudFormation · CDK · SSM · Organizations · IAM |
| Real-time | Redis pub/sub, WebSocket hub, event bus |
| Auth | JWT + bcrypt, identity-based require_permission(subsystem, level) |
| Infra | Docker Compose (dev) · ECS/Fargate (prod) |
| Guide | What's inside |
|---|---|
| COMMANDER.md | NLP dispatch, the Graph Workspace, human-in-the-loop approval gates, missions |
| AGENTS.md | The repeatable agent pattern + the roster, with the Trading Desk & ML Studio deep dives |
| CLOUD.md | @allen, CDK synth → deploy, SSM, and the live dependency DAG |
| FARMS.md | The five managed-AI-service control planes |
| GOVERNANCE.md | Policies / Procedures / Standards, Skills Store, Identity Store, risk & approval |
CortexObserver — humans write the policies, agents do the work through skills, and the Farms govern the boundaries.