codel00p

Architecture

Overview

codel00p is a few Rust crates with one job each. This chapter explains how a single agent turn flows through them, and how that turn becomes durable memory.

At the center is the harness: it runs the turn loop, calls the selected provider, executes the tools the model asks for, and emits a typed event for every step. Around it sit the memory engine, the provider router, and the storage layer that makes sessions and memory durable.

   developer / CLI
         │  prompt + scope
         ▼
   ┌───────────────┐     reviewed memory     ┌──────────────┐
   │    harness    │ ◀────────────────────── │    memory    │
   │  (turn loop)  │ ──────────────────────▶ │  candidates  │
   └───────┬───────┘     new candidates      └──────────────┘
           │  ▲
   route   │  │ tool results
           ▼  │
   ┌───────────────┐   workspace + git    ┌──────────────┐
   │   providers   │   tools, MCP tools   │   storage    │
   │    (router)   │                      │   (sqlite)   │
   └───────────────┘                      └──────────────┘

The life of a turn

A single agent run moves through these steps:

  1. The CLI parses the scope and flags, opens the local database, and builds the harness with the chosen tool set and provider.
  2. The harness assembles context for the turn: the prompt, prior session messages, workspace metadata, and any approved memory relevant to the task.
  3. It calls the provider through a normalized model client and receives assistant text, tool calls, or both.
  4. Requested tools run against the workspace under the active permission mode. Results are appended to the session and emitted as events.
  5. The loop repeats until the model returns a final answer or hits the iteration limit, producing a structured outcome.
  6. At safe boundaries the harness can extract memory candidates from what happened, ready for review.

Why it is split this way

Each crate owns a single product concern so the CLI, a future desktop app, and a future cloud platform can share the same behavior without forking it.

  • codel00p-protocol holds the data-only contracts every crate exchanges: session and turn ids, messages, events, tool calls, and memory entries.
  • codel00p-storage is the only crate that talks to a backend. Everything else stores data through backend-neutral traits.
  • The harness, memory, and provider crates depend on the contracts, not on each other's internals.

The next pages walk through each piece: the harness turn loop, the memory lifecycle, provider routing, and the storage and session layer.