PyClaw

Local-First Agent Orchestration Framework

PyClaw is a local-first agent orchestration framework composed of small, swappable modules. It is designed to:

• Run agent loops on your own machine (laptop/server).

• Keep agents “hot” in memory (daemon-style).

• Execute real work through a typed tool system with full audit trails (sessions, artifacts, policies).

• Sit tightly on top of Cortensor’s /completion, and /delegate surfaces.

Today, PyClaw focuses on a single-host, SQLite-backed, polling-based runtime. The same module boundaries and contracts are laid out so that future remote execution, webhooks, and distributed queues can be added without breaking the internal APIs.

---

1) PyClaw Master Idea

High-level goals:

• Local-first:

  • Runs on your machine.

  • Uses SQLite + filesystem for durable state.

• Auditable:

  • Every turn, tool call, and LLM call is logged as events + artifacts.

• Composable:

  • Agents, tools, providers, and policies live in separate modules.

• Forward-compatible:

  • The boundaries are shaped so that remote workers, webhooks, and stronger auth can “snap in” later without rewriting the agent brain.

Think of PyClaw as the agent brain + control plane, while Cortensor is the execution + verification fabric that PyClaw can call when it needs scalable, verifiable compute.

---

2) Module Catalog — One-Line Definitions

Core Orchestration

• pyclaw-runtime Long-running daemon: runs agent loops, hosts worker queues, manages scheduling, and exposes a kill/stop switch for runs.

• pyclaw-controlplane Entrypoint router for “user input → agent run” across CLI/chat/gateway, and for routing responses back to the right channel.

• pyclaw-session Canonical conversation/session log: append-only events, run records, and message references (audit-first).

• pyclaw-brain The agent “thinking loop”: plan → act → observe → reflect → continue. Supports both one-off turns and longer missions.

• pyclaw-registry Agent discovery and lookup: AgentProfile / Identity / Skill bindings, default models and tools, and per-agent routes.

• pyclaw-policy Approvals and grants for risky tools: time-bounded “allow once / allow for a window / allow until revoke” enforced before execution.

• pyclaw-safety Safety filters, redaction, and guardrail hooks (pre/post tool and pre/post LLM). Can veto or transform requests/responses.

• pyclaw-secret Secret management (currently env/files, later keychain/KMS): ensures API keys and tokens never leak into logs.

LLM + Context + Memory

• pyclaw-llm Provider abstraction for LLMs (OpenAI, Anthropic, local, etc.) with per-agent model selection, retries, and optional parallel calls.

• pyclaw-context Builds prompt context efficiently: includes history, skills, identity, and memory under strict token/size budgets.

• pyclaw-compress Summarizers/compactors used by context and session: rolling summaries, chunking, and distillation to fight context bloat.

• pyclaw-rlm Recursive Language Model wrapper: handles long-context degradation by staging summaries, replaying key steps, and maintaining hierarchical memory.

• pyclaw-memory Long-term memory store: facts, notes, and learned procedures, with provenance and TTL; provides retrieval APIs to context.

• pyclaw-meta Shared types and contracts: Request/Response schemas, SessionEvent, ToolCall, ToolResult, error types, and policy verdicts.

Storage + Artifacts + Evaluation

• pyclaw-storage Pluggable storage engine (SQLite by default), schema migrations, indices, and “viewer-friendly” tables for debugging.

• pyclaw-artifact File ingest/digest: content-addressed file store (hash-based) plus metadata index, retention policies, and cleanup.

• pyclaw-eval Evaluation harness: replay sessions, compare different models/tools, and run regression checks over recorded traces.

Tool System

• pyclaw-os Generalized tool host and registry (not just OS-level): executes plugins, enforces timeouts, and standardizes results.

• pyclaw-os-browser-pinchtab Desktop browser-control plugin (PinchTab-based) plugged into pyclaw-os; supports deterministic browser actions.

• Planned tools pyclaw-tool-weather-openmeteo, pyclaw-tool-reactions, pyclaw-tool-search-brave, etc. — each tool is its own package with a clean schema and policy.

Channels (Controlplane Adapters)

• pyclaw-controlplane-telegram Telegram adapter: long-polling ingestion + message delivery now, while keeping the contract and config ready for future webhook mode.

Other adapters (CLI, Discord, etc.) plug into pyclaw-controlplane by emitting a common ControlEvent type.

---

3) Top-Level Interaction Diagram (ASCII)

User / external inputs flow through the control plane into the runtime daemon, then into the agent brain and tools, and back out:

                    ┌─────────────────────────────┐
User / External      │ openminion-controlplane     │
inputs               │  - CLI                      │
(telegram/cli/etc)──▶│  - channel adapters         │
                    │  - gateway commands          │
                    └──────────────┬──────────────┘
                                   │ ControlEvent
                                   ▼
                    ┌─────────────────────────────┐
                    │ openminion-runtime           │
                    │  - daemon loop               │
                    │  - scheduling (cron/periodic)│
                    │  - cancel/kill switch        │
                    └──────────────┬──────────────┘
                                   │ RunRequest
                                   ▼
     ┌─────────────────────────────────────────────────────────┐
     │ openminion-brain                                        │
     │  plan → toolcalls → observe → reflect → continue         │
     └──────────────┬───────────────────────────┬──────────────┘
                    │                           │
                    │ context build             │ tool exec
                    ▼                           ▼
         ┌──────────────────┐        ┌─────────────────────────┐
         │ openminion-context│        │ Tool Host / Plugins      │
         │ + compress + rlm  │        │ (exec, browser, weather…)│
         └─────────┬────────┘        └──────────┬──────────────┘
                   │                             │
                   ▼                             ▼
            ┌───────────────┐            ┌──────────────────────┐
            │ openminion-llm │            │ openminion-policy    │
            │ providers+parallel          │ approvals+grants      │
            └───────┬───────┘            └──────────┬───────────┘
                    │                               │
                    └──────────────┬────────────────┘
                                   ▼
                    ┌─────────────────────────────┐
                    │ openminion-session           │
                    │  audit log + message refs    │
                    └──────────────┬──────────────┘
                                   ▼
                    ┌─────────────────────────────┐
                    │ openminion-storage (SQLite)  │
                    │ + openminion-artifact store  │
                    └─────────────────────────────┘

Controlplane Telegram V1 (Polling) Flow

+-------------------+        long-poll getUpdates(offset, timeout, allowed_updates)
| Telegram Bot API  | <-------------------------------------------------------+
+-------------------+                                                         |
        |                                                                      |
        | Update JSON (batch)                                                  |
        v                                                                      |
+------------------------------+                                               |
| openminion-controlplane-     |                                               |
| telegram                     |                                               |
|  - parse Update              |                                               |
|  - access checks             |                                               |
|  - map to ControlEvent       |                                               |
|  - persist last_update_id    |  recalc offset after each response            |
+---------------+--------------+                                               |
                | ControlEvent                                                 |
                v                                                              |
+------------------------------+                                               |
| openminion-controlplane      |                                               |
|  - route command vs chat     |                                               |
+---------------+--------------+                                               |
                | RunRequest / SessionEvent                                    |
                v                                                              |
+------------------------------+                                               |
| openminion-runtime (daemon)  |                                               |
|  - start/stop/cancel runs    |                                               |
|  - concurrency limits        |                                               |
+---------------+--------------+                                               |
                |                                                              |
                v                                                              |
+------------------------------+                                               |
| openminion-session           |                                               |
|  - append-only audit         |                                               |
|  - message refs (chat/msg)   |                                               |
+------------------------------+                                               |
                |                                                              |
                v                                                              |
+------------------------------+                                               |
| openminion-storage (SQLite)  |                                               |
+------------------------------+                                               |
                                                                               |
+------------------------------+                                               |
| outbound: sendMessage/edit   |---------------------------------------------->|
| (chunk/format/reply mode)    |                Telegram Bot API methods       |
+------------------------------+                                               |

Agent Run Loop (Brain ↔ Context ↔ Tools) Relationship

                 +----------------------+
ControlEvent --->| openminion-runtime   |
                 |  create RunRequest   |
                 +----------+-----------+
                            |
                            v
                 +----------------------+
                 | openminion-brain     |
                 |  plan -> act -> ...  |
                 +----+------------+----+
                      |            |
        build prompt  |            | execute tool calls
                      v            v
          +----------------+   +--------------------+
          | openminion-    |   | Tool Host + Plugins|
          | context        |   | (exec/browser/...) |
          |  - pick msgs   |   +----------+---------+
          |  - compress    |              |
          |  - retrieval   |     policy gate + grants
          |  - RLM stages  |              v
          +-------+--------+     +-------------------+
                  |              | openminion-policy  |
                  v              | ask/allow window   |
         +-------------------+   | allowlist/deny     |
         | openminion-llm    |   +-------------------+
         | provider + parallel|
         +---------+---------+
                   |
                   v
          +-------------------+
          | openminion-session|
          | append events     |
          +---------+---------+
                    |
                    v
          +-------------------+
          | openminion-storage|
          | SQLite + indexes  |
          +-------------------+

Tool Execution Pipeline (with optional approvals / “ask”)

(openminion-brain)
      |
      | ToolCall {name,args}
      v
+------------------------+
| Tool Host (dispatcher) |
|  - validate schema     |
|  - compute risk        |
+-----------+------------+
            |
            | if low-risk -> run directly
            | if med/high  -> consult policy
            v
   +---------------------+
   | openminion-policy   |
   |  - allowlist match  |
   |  - ask user?        |
   |  - grant window?    |
   +----------+----------+
              |
              | Decision: allow / deny / allow-once / allow-until
              v
     +-------------------+
     | tool plugin exec  |
     |  - do work        |
     |  - collect trace  |
     +---------+---------+
               |
               v
     +-------------------+
     | ToolResult        |
     | ok/data/content   |
     | verified/source   |
     +---------+---------+
               |
               v
     +-------------------+
     | openminion-session|
     | append tool event |
     +-------------------+

Cron Jobs (main-session vs isolated run)

+--------------------+
| openminion-runtime |
|  scheduler tick    |
+---------+----------+
          |
          | due job
          v
+-----------------------------+
| openminion-session/storage  |
|  cron_jobs + cron_runs      |
|  lease + state transitions  |
+---------+-------------------+
          |
          +---------------------------+
          |                           |
          | main session              | isolated session
          v                           v
+-----------------------+     +-----------------------+
| enqueue system event  |     | create isolated run   |
| into main session     |     | session_id (job run)  |
+-----------+-----------+     +-----------+-----------+
            |                             |
            v                             v
   +------------------+          +------------------+
   | main runner tick |          | openminion-brain  |
   | (same brain loop)|          | one agent turn    |
   +------------------+          +------------------+
            |                             |
            v                             v
     +-------------+               +-------------+
     | delivery    |               | delivery    |
     | none/announce/webhook       | none/announce/webhook
     +-------------+               +-------------+

Storage + Session + Artifacts Relationship

                 +----------------------+
                 | openminion-session   |
                 |  sessions, events,   |
                 |  message refs        |
                 +----------+-----------+
                            |
                            | stores metadata + pointers
                            v
                 +----------------------+
                 | openminion-storage   |
                 |  SQLite tables       |
                 |  indexes             |
                 +----------+-----------+
                            |
                            | ArtifactRef (hash, size, mime)
                            v
                 +----------------------+
                 | openminion-artifact  |
                 |  ingest -> hash      |
                 |  dedupe store        |
                 |  retention/cleanup   |
                 +----------+-----------+
                            |
                            v
                 +----------------------+
                 | filesystem store     |
                 | blobs/<sha256>...    |
                 +----------------------+

“Who calls who” Dependency Sketch (read top-down)

openminion-controlplane-telegram
  -> openminion-controlplane
     -> openminion-runtime
        -> openminion-brain
           -> openminion-context -> (compress, rlm, memory, session)
           -> openminion-llm     -> (secret)
           -> tool host/plugins  -> (policy)
        -> openminion-session -> openminion-storage
        -> openminion-artifact -> filesystem
openminion-registry (used by controlplane/brain)
openminion-safety   (hooks around brain/llm/tool)

---

4) “Where Does What Live?” — 3-Layer Mental Model

To keep things understandable (and future-proof), PyClaw is structured as three conceptual layers:

Layer A — Interfaces / Contracts

• pyclaw-meta defines the stable schemas:

  • ControlEvent

  • RunRequest

  • ToolCall and ToolResult

  • SessionEvent

  • LLMRequest and LLMResponse

  • ArtifactRef

  • PolicyDecision

This layer is where all modules agree on what a “request”, “tool call”, or “policy verdict” looks like.

Layer B — Execution Engines

• pyclaw-runtime (daemon, queues, scheduling, cancellation)

• pyclaw-brain (decision loop and agent logic)

• pyclaw-llm (provider routing and ensembles)

• Tool Host + plugins (system actions, browser, weather, etc.)

These modules are responsible for doing the work: planning, calling models, invoking tools, and reacting to results.

Layer C — Persistence + Audit

• pyclaw-session (append-only event log)

• pyclaw-storage (SQLite schema backend by default)

• pyclaw-artifact (content-addressed file store + metadata)

This layer keeps the truth: what the agent saw, decided, executed, and produced.

---

5) Dependency Map — Who Depends on Whom

Core Dependencies

• pyclaw-runtime Depends on:

  • pyclaw-controlplane (to receive and dispatch ControlEvents)

  • pyclaw-session (to record runs)

  • pyclaw-storage (database backend)

  • pyclaw-brain (agent execution)

  • pyclaw-policy (policy checks and grants)

• pyclaw-brain Depends on:

  • pyclaw-llm (LLM calls)

  • pyclaw-context (prompt building)

  • Tool Host / pyclaw-os (tool execution)

  • pyclaw-session (event logging)

  • pyclaw-registry (agent profiles and defaults)

  • pyclaw-policy (risky tool gating)

  • pyclaw-safety (filters, redaction, hard stops)

• pyclaw-context Depends on:

  • pyclaw-session (history slices)

  • pyclaw-memory (long-term facts/knowledge)

  • pyclaw-compress (summarization and compaction)

  • pyclaw-rlm (recursive handling of long sessions)

• pyclaw-llm Depends on:

  • Provider SDKs (OpenAI/Anthropic/etc.)

  • pyclaw-secret (API keys and credentials)

• Tool Host / pyclaw-os Depends on:

  • Tool plugins (exec, browser, weather, etc.)

  • pyclaw-policy (to enforce approvals/allowlists for risky actions)

• pyclaw-controlplane-telegram Depends on:

  • pyclaw-controlplane

  • pyclaw-session

  • pyclaw-storage

  • pyclaw-secret (bot token)

Optional / Soft Dependencies

• pyclaw-eval Depends on: traces from pyclaw-session and outputs from pyclaw-llm and tool host, for replay and regression.

• pyclaw-safety May consume signals from pyclaw-policy and feed back risk/violation info to the brain and tools.

The dependency graph is deliberately acyclic in the core: pyclaw-runtime calls into pyclaw-brain; pyclaw-brain calls context, LLM, tools, and session; everything below that only pushes events and artifacts upward.

---

6) Channel Focus: Telegram (Polling Now, Webhook-Capable Later)

PyClaw’s Telegram adapter is built to start simple and grow:

• Current behavior:

  • Uses Telegram getUpdates with long polling and a persisted offset.

  • Stores a high-water mark offset in pyclaw-storage to avoid duplicates between restarts.

  • Filters updates using allowed_updates for safety and efficiency.

• Important Telegram constraints:

  • getUpdates does not work if a webhook is configured.

  • Offsets must be updated carefully to avoid re-processing messages, especially after errors.

This maps directly to PyClaw’s modular design:

• Ingestion source is just a plugin detail:

  • For now: PollingUpdateSource.

  • Later: WebhookUpdateSource.

• Both will feed the same internal pipeline:

  raw update -> pyclaw-controlplane-telegram -> ControlEvent -> pyclaw-controlplane -> pyclaw-runtime

OpenClaw-inspired knobs that should live in pyclaw-controlplane-telegram config:

• Which actions are allowed (sendMessage, editMessage, deleteMessage, reactions).

• Reaction notification levels.

• Chunking and streaming options for large outputs.

---

7) Scheduler (Cron / Periodic Jobs)

PyClaw’s runtime includes a scheduler within pyclaw-runtime that should:

• Store jobs in persistent storage (via pyclaw-storage).

• Support two basic patterns:

  • Enqueue “system events” into a main session (for periodic status or housekeeping).

  • Trigger isolated agent turns (for periodic tasks, monitoring, or recurring jobs).

• Support various delivery modes:

  • Announce: send output back to a user/channel.

  • Webhook: POST to an external endpoint (future).

  • Silent: update internal state only.

This maps closely to OpenClaw’s cron design while staying generic enough for future multi-host deployments.

---

8) Tool Ecosystem — Pattern and Examples

PyClaw treats tools as a combination of:

• Schema Structured input / output types, so the agent brain knows what to provide and what to expect.

• Policy Constraints on when and where the tool can run, including which hosts are allowed and whether user confirmation is required.

• Executor Actual implementation: performs the work and returns a standardized result.

A typical tool result shape conceptually looks like:

ToolExecutionResult:
  ok: bool
  content: human-readable summary
  data: structured payload (dict/object)
  verified: bool
  source: string identifier (e.g., "weather-openmeteo")
  warnings: list of warning messages
  error: error description or null

Risky tools (system commands, SSH, Docker, browser actions that can submit forms or perform payments) must consult pyclaw-policy before they run:

• Ask once (for this call).

• Ask for a time window (e.g., allow for 10 minutes).

• Ask for this session only.

• Deny entirely unless explicitly allowed.

Patterns and examples:

• Weather (Open-Meteo)

  • Geocoding + current forecast.

  • Must respect non-commercial usage limits and cache results where possible.

• Reactions tool

  • Add/remove reactions in chat systems with shared semantics (emoji to add; empty emoji to clear, flags like remove=true).

  • Inspired by OpenClaw’s reactions tool behavior.

• Browser control

  • pyclaw-os-browser-pinchtab plugin wrapped as a tool behind the pyclaw-os host interface.

  • Lets the agent perform deterministic browser operations in a controlled way.

Tools are execution capabilities; skills or prompts can describe “how to use them,” but pyclaw-os is still where real world actions happen.

---

9) Scaling Path — How Future Features Fit This Architecture

PyClaw is intentionally documented as a single architecture, but we distinguish between:

• What exists now (local-first, SQLite, polling, single-host).

• What is planned next (remote workers, webhooks, distributed queues, stronger auth).

The same module graph supports both.

Today, PyClaw focuses on:

• A single-host daemon (pyclaw-runtime) with hot agent instances.

• SQLite via pyclaw-storage and filesystem CAS via pyclaw-artifact.

• Telegram polling via pyclaw-controlplane-telegram.

• Local tool execution via pyclaw-os (and, optionally, remote via SSH if implemented as a tool plugin).

• Policy enforcement via pyclaw-policy with time-bounded grants.

The roadmap keeps the same boundaries and evolves them:

• Message bus / queue abstraction so that pyclaw-runtime can dispatch work to remote workers or other hosts.

• Channel adapters that can switch between polling and webhook ingestion without changing downstream contracts.

• Storage abstraction ready to swap SQLite → Postgres + object store while keeping pyclaw-session and pyclaw-artifact APIs stable.

• RLM/context improvements in pyclaw-rlm and pyclaw-context to better handle long-lived agents and cross-host delegation.

In other words: the shape of the system remains the same, but the backing implementations underneath each module can get more powerful as PyClaw grows.