# 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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.cortensor.network/community-and-ecosystem/products-and-agents/pyclaw.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.