Architecture

System design

One architecture. Clear seams.

Chronos separates product code, durable runtime concerns, and infrastructure adapters so each can evolve independently.

↓Dependencies flow downward

0Import cycles by design

∞Adapters behind interfaces

01 · Layer stack

Build at the top. Depend only below.

The package boundary is intentionally simple: higher layers orchestrate; lower layers provide reusable capability.

01

ChronosOSos/

Control plane

Auth & RBACApprovalsTracingHTTP API

02

SDKsdk/

Application API

AgentsTeamsMemoryKnowledgeSkillsProtocol

03

Engineengine/

Runtime primitives

StateGraphModelsToolsGuardrailsHooksQueue

04

Storagestorage/

Persistence seams

StorageVectorStoreAdaptersMigrations

Only downward imports are permitted: os/ → sdk/ → engine/ → storage/. sandbox/ is an isolated capability used by the tool runtime.

02 · Runtime flows

Follow the work, not an arrow maze.

Choose a common path to see the responsibility handoff at each stage.

A single request moves through policy, model execution, tools, and durable audit storage.

1. 01
   Request

   Agent receives the user message and assembles system context, memory, and history.

2. 02
   Protect

   Guardrails validate input; hooks apply logging, rate limits, cache, retry, and cost tracking.

3. 03
   Reason

   The selected model provider produces a response or requests one or more tools.

4. 04
   Act

   The registry checks permissions, executes approved tools, and feeds results back to the model.

5. 05
   Persist

   Output is checked, then events, usage, and trace data are appended to storage.

03 · StateGraph

Durability is part of the execution path.

Every completed node produces a checkpoint. Interrupts become first-class, resumable states rather than exceptional control flow.

• Ordered checkpoints use a sequence number, not wall-clock time.
• Checkpoint and event persistence share a transaction.
• Resuming skips only the already-completed interrupt node.

Start

Plan

Tool

needs review

Paused

Resume

✓ checkpoint after every completed node

04 · Extension points

Small interfaces, replaceable infrastructure.

Persistence

Storage

Sessions, memory, audit logs, traces, events, and checkpoints.

storage.Storage

Retrieval

VectorStore

Collection management, vector upsert, search, and deletion.

storage.VectorStore

Intelligence

Provider

Chat and streaming implementations for any model backend.

model.Provider

Safety

Guardrail & Hook

Composable checks and before/after middleware around execution.

guardrails.Guardrail

Isolation

Sandbox

Process, container, WASM, or Kubernetes execution for untrusted code.

sandbox.Sandbox

Coordination

Team strategy

Sequential, parallel, router, coordinator, swarm, and hierarchy topologies.

sdk/team

05 · Deployment

Same application API, from laptop to fleet.

Development

One binary

Chronos with SQLite provides a small, local feedback loop.

chronos→SQLite

Production

Durable workers

Replicas coordinate through PostgreSQL leases and a shared event store.

Ingress→Workers × N→Postgres

Scale

Kubernetes

Use deployment replicas, HPA, disruption budgets, and observability.

HPA→Deployment→Service

Package reference

The visual overview above is a guide to the codebase. Use these source locations when you need the concrete implementation details.

Area	Primary packages	What it owns
Application API	sdk/agent, sdk/team, sdk/memory, sdk/knowledge	Agent construction, teams, memory, retrieval, and skills.
Runtime	engine/graph, engine/model, engine/tool	StateGraph execution, model providers, tools, policy, hooks, streaming, and queueing.
Control plane	os, os/auth, os/approval	HTTP APIs, authentication, human approval, tracing, scheduling, and metrics.
Persistence	storage, storage/adapters	Relational/NoSQL persistence, vector search, migrations, and backend adapters.
Isolation	sandbox	Process, container, WASM, and Kubernetes backends for untrusted execution.

Design guarantees

• Durable graph execution: completed nodes checkpoint progress and can resume from the latest sequence number.
• Policy before action: guardrails, permissions, and optional approval gates sit in the request and tool paths.
• Provider neutrality: models, storage, vectors, and sandboxes are selected through narrow interfaces rather than application rewrites.
• Distributed safety: lease-backed workers and transactional persistence allow runs to move safely between workers.

Continue exploring

• Durable execution — checkpointing, interruption, queueing, and resume behavior.
• Agent builder — the application-facing API.
• Interfaces — exact Go signatures for Chronos extension seams.
• Scaling best practices — operating Chronos across replicas.