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.