OS Architecture

OS Architecture

AgentCTX is an operating system for AI agents. Like a traditional OS manages processes, memory, and I/O for programs, AgentCTX manages context, memory, tools, and trust for agents.

The OS Analogy

Traditional OS	AgentCTX	Purpose
Process scheduler	Orchestrator	Dispatch and coordinate agents
Virtual memory	5-layer memory	Hierarchical persistence with decay
File system	Knowledge plane	Indexed, searchable data
System calls	CTX statements	Structured requests to the kernel
Device drivers	MCP backends	Abstracted tool access
Kernel	Gateway	Central routing and enforcement
Shell	CLI (actx)	Human/agent interface
Audit log	Sidecar translations	Signed, verifiable records

Architecture Layers

┌─────────────────────────────────────────────┐
│  Agents (Claude, Gemini, GPT, Custom)       │  ← User space
├─────────────────────────────────────────────┤
│  CTX Language                               │  ← System call interface
├─────────────────────────────────────────────┤
│  Gateway (Middleware Pipeline)              │  ← Kernel
│  ┌─────┬────────┬────────┬────────┐        │
│  │Identity│ RBAC │Budget │Routing │ ...    │  ← Kernel modules
│  └─────┴────────┴────────┴────────┘        │
├─────────────────────────────────────────────┤
│  Planes                                     │  ← Subsystems
│  ┌──────┬──────────┬────────┬───────┐      │
│  │Tools │Knowledge │Memory  │Skills │      │
│  └──────┴──────────┴────────┴───────┘      │
├─────────────────────────────────────────────┤
│  Storage (CAS + SurrealDB)                  │  ← Disk
├─────────────────────────────────────────────┤
│  Sidecar (Trust Boundary)                   │  ← Audit
├─────────────────────────────────────────────┤
│  MCP Backends (GitHub, Filesystem, etc.)    │  ← Hardware/Devices
└─────────────────────────────────────────────┘

Key Components

Gateway (The Kernel)

The gateway is the kernel — every agent request passes through it. It enforces:

• Identity — who is making the request
• Authorization — what they’re allowed to do
• Budget — how many tokens they can spend
• Routing — which plane handler processes the request
• Alignment — sentinel checks for behavioral deviation

Orchestrator (Process Scheduler)

The orchestrator manages multi-agent workloads:

Feature	Description
Dispatch	Route tasks to the best available agent
Process groups	Group related agents for coordinated work
Dependency graph	Ensure tasks execute in the correct order
Coherence detection	Detect when agents are duplicating work
Prompt compilation	Generate optimized prompts for dispatched agents
Lifecycle management	Spawn, monitor, and terminate agents

Memory (Virtual Memory)

Like virtual memory, AgentCTX’s memory system has a hierarchy:

L1: Ephemeral     ← Fast, session-only (like CPU cache)
L2: Individual    ← Per-agent persistent (like RAM)
L3: Team          ← Shared across team (like shared memory)
L4: Organization  ← Org-wide (like network storage)
L5: Global        ← Platform-wide (like cloud storage)

Memories decay over time (like LRU eviction) and can be promoted to higher layers.

NATS (Inter-Process Communication)

NATS JetStream provides the message bus for:

• Agent-to-agent communication (pub/sub)
• Event distribution (memory updates, tool calls)
• Federation (cross-organization message routing)
• Queue workers (async task processing via broker)

Cognition Layer

The cognition layer captures how agents think, not just what they do:

+m:context "analyzing auth module"     ← thinking about auth
+m:check "OWASP compliance"            ← verifying security
+m:edge "injection risk in search"     ← found an issue
+m:escalate "critical vulnerability"   ← raising priority

These cognition traces are structured, stored, and searchable — enabling replay, audit, and cross-agent learning.

Module Count

Category	Count
Core modules	12
Active modules	21
Scaffolding (Rust migration)	6
Deprecated (legacy fallback)	4 files
Rust crates	8
SurrealQL schemas	10
Test files	246+
Total source files	306+

Next

• Gateway & Routing → — deep dive into the kernel
• Seven Planes → — the plane subsystems