PyClaw

Local-First Agent Orchestration Framework

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.

Last updated