This is the entry point for Maka Agent backend architecture. It does not repeat each deep-dive article. It establishes the system spine and helps readers reach the right chapter by engineering question. The current series covers Runtime, tools and context, durable Headless tasks, Self-check, the AHE self-iteration boundary, Graph scheduling over child Sessions, and crash-safe Runtime continuation.
Maka is a log-first, projection-driven Agent Runtime. Execution facts enter append-only logs; Session state, model context, TaskRun, Self-check, and evolution evidence are projections of those facts for different consumers.
Read left to right. Entry points hand user intent to Runtime; model and tool execution produce facts; those facts are projected into model context, interactive views, crash-recovery decisions, Graph scheduling inputs, durable task state, and evolution evidence. Graph coordinates child Sessions from durable schedule metadata but sends execution back through the same Runtime. Providers, concrete storage implementations, and UI components are omitted so the diagram can preserve the backend spine shared by this series.
An Agent Run produces model messages, Tool Calls, Tool Results, permission decisions, and termination facts. Runtime Event Log is the canonical source for those interaction semantics except hosted permission answers: InteractionStore is their canonical authority, while the Runtime ledger stores only answer identity and audit facts. The embedded/legacy path retains its existing decision-event semantics. Context pruning and Compaction may change what the model sees next, but cannot rewrite facts that already occurred.
Relevant chapters: 1, 2, 3, and 8.
When dependent Agent work benefits from dynamic topology, Graph treats child Sessions as operator containers, Session-inline AgentRuns as activations, and committed RuntimeEvents as reference-only records. SQLite owns schedule, topology, admission, and supervisor-wake metadata; Runtime keeps execution authority. The main Agent stays beside the graph to observe, intervene, and synthesize without gating normal record delivery.
Relevant chapter: 7.
When a task outlives one Turn or process, Headless uses an independent task identity, Task Event Log, and TaskRun projection to preserve progress across Attempts. Self-check provides bounded feedback inside that task loop but does not own final fact authority.
Relevant chapters: 4 and 5.
AHE organizes outcomes and traces from multiple TaskRuns into evolution evidence bound to target identity. It remains outside the interactive Runtime and advances system changes through a constrained change surface, falsifiable manifests, candidate evaluation, and rollback lineage.
Relevant chapter: 6.
| Chapter | Core question | Implementation status | Read |
|---|---|---|---|
| 1. Log Is the Runtime | How does Maka preserve and replay the state space of an Agent Run? | Current | English · 中文 |
| 2. Evidence Before Compression | How can a large Tool Result leave Turn-level evidence without exhausting active context? | Current + Target | English · 中文 |
| 3. Compaction Is a Projection | How can the LLM forget old context without losing historical facts? | Current | English · 中文 |
| 4. The Durable Task Loop | How does Maka continue a task that outlives a Turn, Run, or process? | Current + Target | English · 中文 |
| 5. Self-Check Is Not Self-Trust | How can an Agent inspect and repair its work without turning self-report into authority? | Current + Target | English · 中文 |
| 6. Self-Iteration Happens Outside the Runtime | How does Maka turn run experience into falsifiable and reversible system improvement? | Current + Target | English · 中文 |
| 7. Graph Is a Schedule, Not a Second Runtime | How does Maka coordinate dynamic dependent Agent work while the main Agent supervises beside the data path? | Current | English · 中文 |
| 8. Resume Is Not Retry | How does Maka recover crash facts, avoid duplicate side effects, and create a provably safe new execution? | Current + Target | English · 中文 |
Current + Target means the article covers verified implementation and visibly labeled target direction. It does not mean Target sections are implemented. The implementation_status and last_verified fields in each article's front matter are the more precise status source.
Read 1 → 2 → 3 → 8. Start with the fact log, then learn the tool-evidence and context projections that recovery later consumes. Finish with crash repair and safe continuation.
Read 1 for the canonical-fact boundary, then 2 → 3. Add 8 when the change affects T1/T2, recovery, or continuation, and add 4 when it affects evidence consumed by durable tasks.
Read 1 → 8. Chapter 1 establishes RuntimeEvent and AgentRun authority; Chapter 8 explains startup repair, T1/T2, RecoveryResolver, safe-boundary continuation, and the Phase 3–4 workspace path. Add 4 for Headless Attempt recovery and 7 when recovery affects Graph activations or supervisor wakes.
Read 1 → 8 → 4 → 5. Chapter 8 separates Runtime continuation from Attempt retry and workspace restore. Chapter 3 adds context recovery, while Chapter 2 adds the Tool Result evidence boundary.
Read 4 → 5, then revisit Chapter 2's rule that context pruning must not delete evidence.
Read 1 → 4 → 5 → 6. Chapter 6 depends on the Event Log, TaskRun projection, and authority boundaries established earlier.
Read 1 → 7. Chapter 1 establishes RuntimeEvent and AgentRun authority; Chapter 7 explains how Graph projects those facts into records, binds operators to child Sessions, linearizes schedule and admission in SQLite, and returns control to the root supervisor Agent. Add 2 → 3 when changing how child output is retrieved or compacted.
| Area | Primary responsibility |
|---|---|
packages/core | Pure contracts for Session, Runtime Event, AgentRun, and permission |
packages/storage | Durable stores for sessions, settings, run ledgers, and the SQLite metadata control plane |
packages/runtime | SessionManager, AgentRun, model adapters, tool execution, context, recovery, and Graph reconciliation |
packages/headless | TaskRun, Autonomous Loop, Self-check, result export, and AHE protocol |
apps/desktop/src/main | Electron main-process composition, IPC, and product-entry adapters |
The “code map” in each deep-dive article is the preferred implementation entry point. Earlier design and evolution material remains available in:
docs/archive/runtime-kernel.mddocs/archive/runtime-v2-architecture-evolution.mddocs/archive/runtime-v2-implementation-notes.mdThose documents provide historical design context and implementation notes. The eight chapters indexed here are the narrative entry point for current backend mechanisms.
docs/architecture/ remains flat. One mechanism owns one stable slug: the default .md file is English and .zh-CN.md is its Chinese counterpart. While the collection is still easy to scan, avoiding another chapters/ level keeps links shallow.
Maintenance rules:
doc_id, implementation status, verification date, and owner;-draft filename suffix must agree with front matter document_status; publication should remove the suffix and update all index links in the same change.