Skip to main content

System design overview

This section turns the active design stack under docs/system-design/ into a public reading path for people who want to understand how Aegis is meant to work internally.

It intentionally reflects the current clean-slate target design, not the historical archive. Older design archaeology such as initial-draft.md and provisional-foundation.md stays out of the public reading path on purpose.

The architecture in one sentence​

Aegis keeps durable truth in a small set of owners, derives a scoped SessionFrame for each turn, retrieves evidence deliberately, learns reusable procedures from outcomes, and keeps the whole runtime inspectable.

Read this section in order​

  1. Architecture foundations
  2. Continuity and SessionFrame
  3. Retrieval, memory, and replay
  4. Learning and procedures
  5. Technical stack
  6. Gateway and messaging adapters
  7. Derived progression

The design layers​

Layer 1 — Durable owners​

The runtime is organized around a small set of durable owners:

  • ProfileGraph for identity, relationship posture, and durable preferences
  • WorkGraph for goals, blockers, decisions, and active work state
  • EvidenceGraph for events, memory, artifacts, provenance, and recall
  • ProcedureLibrary for verified reusable procedures
  • CapabilityRegistry for available tools, models, adapters, and delivery surfaces

Layer 2 — Derived runtime frame​

The runtime does not load the whole graph into every turn. It derives a scoped SessionFrame that carries only the profile constraints, active work, recalled evidence, and optional procedure overlays that matter now.

Layer 3 — Product projection​

Users should not have to read raw graph rows by default. Aegis therefore projects SessionFrame into plain read models such as current focus, next move, recall reasons, remembered constraints, and resume cues.

Layer 4 — Learning and selective reuse​

Outcomes flow into evidence first. Only repeated, verified patterns become promoted procedures or optional skill packages.

Cross-cutting layer — Technical modules and operator surfaces​

The clean-slate runtime ties these ideas together through a Python-first stack, SQLite-backed retrieval, layered context assembly, and inspect surfaces such as /profile, /activity, /memory, /skills, and /audit.

What this public section covers​

  • the current ownership model and clean-slate architecture principles
  • the SessionFrame and continuity grammar that shape user-visible behavior
  • scoped retrieval, structured memory, compression, and replay guardrails
  • the learning loop that turns outcomes into procedures
  • the technical stack and package/module boundaries
  • gateway adapter and progression companions that extend the same substrate

What this section does not cover​

  • contributor workflow policy or repository harness rules
  • historical architecture drafts kept only for archaeology
  • release promises for every design slice described here

Relationship to the rest of the docs​

  • Use the docs in Start Here, Use Aegis, Reference, and Help for the supported operator path today.
  • Use this section when you want the architectural model behind that operator path.
  • Use Architecture overview if you want the short, product-level summary before going deeper.