# PyClaw

PyClaw is a local-first agent orchestration framework that runs on your own machine, accepts commands from multiple channels (CLI / chat / Telegram / etc.), and safely executes work using tools (OS, browser, APIs) under a durable, auditable event log.

PyClaw is designed to sit tightly on top of Cortensor’s router surfaces (`/completion`, `/delegate`, `/validate`, `factcheck`):\
PyClaw orchestrates the agent brain and tools locally; Cortensor provides scalable, verifiable inference when the agent needs remote compute.

The system is built as a set of small, swappable modules (runtime, context, tools, policy, memory, etc.) so it can grow from single-machine to mixed local+remote without rewriting core logic.

***

### 1) Core Principles

* Local-first
  * V1 runs entirely on a single host (laptop / server) with local storage (SQLite + filesystem CAS).
  * You keep control of logs, artifacts, and secrets.
* Durable by default
  * Every turn is recorded as structured events.
  * Agents can resume after crashes or restarts with full history preserved.
* Bounded context
  * Full history is stored in the event log, but prompt context is compacted and token-budgeted (rolling summaries, retrieval, skill snippets).
* Tool-safe
  * Tool execution (OS, browser, APIs, infra) is gated by policy with approvals (once / time-window / until revoked).
* Composable modules
  * Providers, tools, channels, and even the “brain” loop are modules.
  * Adding new capabilities is a plugin, not a rewrite.
* Debuggable
  * Events, artifacts, and packing telemetry make it easy to answer:
    * “What did the agent do?”
    * “What did it see in context?”
    * “Why did it choose that action?”

***

### 2) Major Modules

The names below are public-facing; under the hood they are backed by smaller `*-ctl` cores (for storage, context, policy, etc.).

#### 2.1 Orchestration & Runtime

`pyclaw-runtime` (turn orchestrator / daemon host)

* The “kernel” that runs each agent turn or background job.
* Reads and writes session events, coordinates context/LLM/tools, and loops until the turn is complete.
* In daemon mode, keeps agents “hot” (LLM clients, SSH/browser handles, caches).

`pyclaw-brain` (agent thinking loop)

* Implements the hierarchical state machine for a single turn:\
  `interpret → plan → policy-gate → act → observe → verify → reflect → respond`.
* Calls into context, LLM, tools, memory, and policy modules.
* Writes the canonical audit trail to the session store.

`pyclaw-metagovernor` (optional meta-control)

* Computes risk/uncertainty/budget signals for the current turn.
* Emits directives like “require validation”, “escalate tier”, “stop using risky tools”, or “ask human to confirm”.

#### 2.2 Session, Storage & Artifacts

`pyclaw-session` (event log + working state)

* Append-only event store for:
  * user messages, agent messages
  * tool requests/results
  * plans, approvals, verification verdicts
  * summaries and memory references
* Exposes session slices (recent windows, specific phases) to context and memory modules.

`pyclaw-storage` (SQLite + record store)

* Backing storage for sessions, memory, skills, registry, and policy.
* Handles migrations and indexing.

`pyclaw-artifact` (content-addressed file store)

* Stores larger outputs:
  * tool stdout/stderr
  * downloaded or generated files
  * ingested documents
* Tracks metadata, aliases, retention rules, and garbage collection.

#### 2.3 Context, LLM & Memory

`pyclaw-context` (prompt packing + context budgets)

* Builds the PromptPack that is sent to the LLM:
  * identity capsule
  * rolling summary
  * recent message window
  * retrieved memory snippets
  * selected skill excerpt(s)
  * minimal tool schemas / traces
* Enforces strict token budgets and records what was included, truncated, or dropped.

`pyclaw-llm` (provider abstraction & routing)

* Unified interface to LLMs (OpenAI / Anthropic / local / Cortensor Router).
* Supports:
  * per-agent model config
  * “second opinion” / panel-and-judge patterns
  * timeouts and structured output schemas.
* In router-aligned setups, routes heavy work via Cortensor (`/completion` or `/delegate`) instead of calling vendors directly.

`pyclaw-compress` (summaries & compaction)

* Maintains rolling summaries when sessions grow.
* Provides tools for:
  * summarizing long histories into short narrative chunks
  * distilling large artifacts or logs
  * reducing context-rot while preserving the full event log.

`pyclaw-memory` (long-term & working memory)

* Stores and retrieves durable knowledge:
  * facts, preferences, lessons learned, procedures.
* Supports candidate → promotion workflow:
  * not everything the agent reads becomes long-term memory.
* Returns bounded memory slices for use in `pyclaw-context`.

`pyclaw-identity` (agent profile capsule)

* Compresses role, style, constraints, and risk posture into a small identity capsule.
* Versioned so you can track how the agent’s “persona” changes over time.

#### 2.4 Tools, Policy & Safety

`pyclaw-tools` (tool host + plugin system)

* General tool framework:
  * each tool defines a schema, policy requirements, and execution result type.
* Hosts plugins like:
  * OS/exec, file operations
  * SSH/systemd/journalctl
  * browser automation (PinchTab)
  * HTTP / search / APIs.
* Executes tools requested by the model (or forced by rules), producing:
  * structured results
  * artifact references
  * tool events written to `pyclaw-session`.

`pyclaw-policy` (approvals & grants)

* Central gate for risky or irreversible actions, e.g.:
  * file modifications
  * remote exec / SSH / Docker / k8s
  * browser actions that submit / pay / delete
  * financial or infra-changing API calls.
* Supports grants such as:
  * approve once
  * approve for N minutes
  * approve for this session
  * approve until revoked.
* Grants are stored durably and surfaced in the audit trail.

`pyclaw-safety` (guardrails & hard stops)

* Runs pre- and post-checks on LLM outputs and tool intents.
* Can enforce:
  * redaction rules (secrets, PII)
  * domain allowlists / denylists
  * global “panic / stop” states that block execution.

#### 2.5 Skills & Knowledge

`pyclaw-skill` (procedural knowledge)

* Skills are versioned markdown/text playbooks that explain “how to do X with these tools”.
* Indexed as small SkillCards; only the top-N are surfaced per turn.
* When selected, a skill is expanded into a small, bounded skill excerpt injected into context.
* Skills guide the model; tools still do the actual execution.

`pyclaw-registry` (agent discovery / capabilities)

* Registry of agents and their:
  * capabilities
  * default toolsets
  * identity profiles
  * preferred models / router routes.
* Used by the runtime and controlplane to route commands to the right agent.

`pyclaw-a2a` (agent-to-agent queue; future-leaning)

* Local agent-to-agent messaging and delegation queue.
* Backed by SQLite initially; can later be replaced by remote transports.
* Enables multi-agent setups where one agent delegates tasks to another using the same event/audit model.

#### 2.6 Channels, Secrets & Diagnostics

`pyclaw-controlplane` (channel adapters)

* Entry point for “user input → agent run”.
* Normalizes messages from:
  * CLI / REPL
  * Telegram / Discord (via adapters)
  * future gateways / HTTP APIs.
* Resolves `session_id` + `agent_id`, binds identity, logs the inbound message, and hands work to `pyclaw-runtime`.

`pyclaw-controlplane-telegram` (Telegram adapter)

* Telegram integration using polling in V1 (webhook-ready later).
* Translates updates into controlplane events and sends responses back as Telegram messages.

`pyclaw-secret` (secrets management)

* Loads secrets from env / files / keychain.
* Provides them to tools and providers without writing them into logs or prompts.

`pyclaw-diagnostics` (health & recovery)

* Health checks for:
  * storage
  * artifacts
  * providers
  * tools.
* Optional guided recovery workflows (“reset this agent”, “clear session cache”, etc.).

***

### 3) How a Turn Works

A single user turn through PyClaw looks like this:

1. Input via channel
   * A channel (CLI / Telegram / future UI) sends a message to `pyclaw-controlplane`.
   * Controlplane:
     * resolves `agent_id` and `session_id`,
     * binds identity / user metadata,
     * appends a `user.message` event to `pyclaw-session`.
2. Runtime kicks off
   * `pyclaw-runtime` starts an agent turn:
     * looks up agent config in `pyclaw-registry`,
     * initializes a turn context object,
     * hands control to `pyclaw-brain`.
3. Interpret / plan
   * `pyclaw-brain`:
     * consults `pyclaw-metagovernor` (risk / budget hints),
     * calls `pyclaw-context` to build a PromptPack:
       * identity capsule
       * rolling summary
       * recent messages
       * memory snippets
       * skill shortlist and, if chosen, a skill excerpt
       * minimal tool schemas.
     * calls `pyclaw-llm` to interpret intent and draft a plan.
4. Policy-gate & act (tools, router, LLM)
   * If the plan includes tool calls:
     * `pyclaw-policy` checks approvals / grants.
     * `pyclaw-safety` performs extra checks if needed.
     * `pyclaw-tools` executes the tool:
       * records events to `pyclaw-session`,
       * stores outputs in `pyclaw-artifact` when large,
       * returns structured results to `pyclaw-brain`.
   * For heavy inference steps, the brain may route via:
     * local LLMs, or
     * Cortensor router (`/completion`, `/delegate`, `/validate`, `factcheck`) using `pyclaw-llm`.
5. Observe, verify, reflect
   * `pyclaw-brain`:
     * observes results (tool outputs, LLM responses),
     * optionally runs verification steps (via tools or `/validate` on Cortensor),
     * updates memory candidates in `pyclaw-memory`,
     * writes observation / verification events into `pyclaw-session`.
   * `pyclaw-compress` may update rolling summaries to keep context tight.
6. Respond
   * When the turn is ready to answer:
     * `pyclaw-brain` writes an `assistant.message` event.
     * `pyclaw-runtime` returns the response payload to `pyclaw-controlplane`.
     * Controlplane sends it back through the original channel (CLI / Telegram / etc.).

Throughout the process:

* Everything is logged into `pyclaw-session` (with trace/step IDs).
* Artifacts are stored by `pyclaw-artifact` with content hashes.
* Telemetry and packing stats are available for debugging/replay.

***

### 4) Skills vs Tools (Public Concept)

* Tools are executable capabilities:
  * run a command, query an API, control a browser, manage services, etc.
* Skills are procedural playbooks:
  * “How to do X using these tools,” written in human-readable markdown/text.

To avoid context explosion:

* Prompt packs include only top-N SkillCards relevant to the current turn.
* At most one or a small handful of skill excerpts are expanded into the prompt at once.
* Tools always run under `pyclaw-policy` and `pyclaw-safety`, regardless of which skills are active.

***

### 5) Safety & Control Model

By default, PyClaw assumes that any action that can:

* modify local or remote state
* move money or credentials
* affect infrastructure or production systems

must be explicitly approved.

Approval options (through `pyclaw-policy`):

* approve once (single action)
* approve for a time window (e.g. N minutes)
* approve for this session (until session ends)
* approve until revoked (persistent grant)

All approvals and denials are:

* logged into `pyclaw-session` as events,
* auditable after the fact.

For high-risk domains, PyClaw can:

* require `/validate` checks via Cortensor before executing,
* escalate to stricter policies based on `pyclaw-metagovernor` risk assessment,
* block specific tools entirely via configuration.

***

### 6) Scaling Path (Design Intent)

While this doc is written as a single architecture, PyClaw is intentionally designed to support two deployment “modes” without changing its core contracts:

* Local-only mode (first implementation)
  * everything runs on one host: LLM calls, tools, storage.
  * channels use polling (CLI, Telegram, etc.).
  * ideal for power users and small teams.
* Local + remote / multi-agent mode (future)
  * PyClaw nodes can:
    * call remote tools (SSH, HTTP, MCP),
    * delegate tasks to other PyClaw agents via `pyclaw-a2a`,
    * rely more heavily on Cortensor for heavy, verifiable inference.
  * the same event/audit model (`pyclaw-session` + `pyclaw-artifact`) continues to apply.

The contracts between modules (sessions, context packs, tool calls, policy decisions) are kept stable so implementations can evolve from “single daemon on a laptop” to “small cluster of cooperating PyClaw agents” without breaking user-facing behavior.

***

### 7) Dependency Summary (For Implementers)

At minimum, a functional PyClaw setup needs:

* `pyclaw-runtime`, `pyclaw-brain`, `pyclaw-session`, `pyclaw-storage`
* `pyclaw-context`, `pyclaw-llm`
* `pyclaw-tools`, `pyclaw-policy`, `pyclaw-safety`
* `pyclaw-controlplane` (+ at least one channel adapter)

Strongly recommended:

* `pyclaw-identity`, `pyclaw-skill`, `pyclaw-compress`, `pyclaw-memory`, `pyclaw-artifact`, `pyclaw-registry`

Optional but useful:

* `pyclaw-metagovernor`, `pyclaw-a2a`, `pyclaw-secret`, `pyclaw-diagnostics`

This document is meant as the master reference another agent (or human writer) can use to build public docs, diagrams, and module-by-module API descriptions for PyClaw.