About the Project
pieBot is a local-first AI agent runtime built around a simple conviction: the model should not be the system.
Most agent projects still rely on a large language model to hold the thread of execution together. The model is given memory, tools, instructions, and broad discretion, then trusted to behave coherently. pieBot takes the opposite approach. Models are treated as replaceable compute workers. Authority lives outside them.
The project is built as a Rust authoritative control plane that owns state, memory boundaries, tool execution, policy enforcement, audit history, and provenance. Models can propose. They cannot decide what is true, mutate storage directly, bypass approvals, or quietly invent their own execution path.
The result is not a chatbot with more scaffolding around it. It is a hardened agent execution substrate: deterministic, inspectable, replayable, and designed so that intelligent behaviour can be built without surrendering control of the system to the model inside it.
Why pieBot Exists
pieBot grew out of a wider frustration with how many modern “agent” systems are assembled.
A typical agent stack often becomes a mixture of:
- prompt instructions treated as policy,
- raw conversation history treated as memory,
- model output treated as execution intent,
- tool use treated as something to be hoped for rather than structurally constrained.
That can be impressive in demos, but it becomes fragile when the system needs to be understood, audited, secured, or trusted over time.
pieBot exists to explore a harder alternative: an agent runtime where behaviour is produced through explicit system architecture rather than implicit model compliance.
Its design is grounded in a few core principles:
- The orchestrator is the authority. Models are workers, not autonomous owners of state.
- Memory is externalized. State, episodes, retrieval, and artifacts live outside the model and are handled explicitly.
- Side-effects are controlled. Tools are the only mutation path, and they are policy-gated, approval-aware, and auditable.
- Execution is replayable. Runs are recorded through canonical artifacts, hash chains, and provenance capsules.
- Failure is safer than guesswork. Invalid policy, broken contracts, unsafe paths, or malformed outputs fail closed rather than degrading silently.
How the System Works
At its core, pieBot operates through a deterministic orchestration loop.
A run begins by loading the current authoritative state, selecting an intent, assembling bounded context, and routing a request to a provider. Before that provider sees anything, its input is minimized and redacted. When a response returns, it must satisfy an explicit output contract before any tool execution can even be considered.
If a tool is selected, it passes through policy, approval, and workspace enforcement before producing an artifact. Any resulting state change is expressed as a replayable delta and applied by the Rust control plane. The run then appends an episodic record, updates bounded working memory, and emits a provenance capsule that binds together the important refs and hashes from that execution.
The system is divided into a few major layers:
Rust Control Plane
The authoritative runtime owns:
- orchestration and scheduling,
- state transitions,
- skill selection,
- retrieval and context binding,
- provider routing,
- redaction and output contract validation,
- tool execution gates,
- audit logging and provenance artifacts.
Externalized Memory
pieBot uses a layered memory model rather than treating prompt history as truth:
- GSAMA state for authoritative internal system state,
- episodic records as append-only execution history,
- working memory for bounded run-local scratch,
- optional non-authoritative mirrors for retrieval support.
Skills and Tools
Capabilities are exposed through explicit Skills.
A skill defines what the system is attempting to do, what tools may be proposed, which prompt template is used, and which contract must validate the provider output.
Tools are the only route to mutation. They do not execute because a model asks nicely. They execute only when the runtime permits it.
Artifacts, Audit, and Replay
pieBot writes execution evidence as artifacts and links those artifacts through audit events and deterministic hashes. Prompts, redacted provider inputs, provider outputs, tool calls, tool outputs, state deltas, retrieval results, run capsules, and explain views are all represented explicitly.
This makes the system inspectable after the fact and, critically, allows runs to be reasoned about from evidence rather than reconstructed from vague logs.
Current Development State
The hardened runtime kernel is now substantially complete and locked.
The core system already includes:
- deterministic GSAMA backed state handling,
- a Rust owned orchestration loop,
- memory stratification,
- provider boundaries,
- tool registry and execution gates,
- skill manifests,
- redaction before provider egress,
- bounded context assembly,
- output contracts,
- run capsules and explain artifacts,
- workspace containment,
- deterministic retrieval,
- a lens pipeline for post retrieval refinement,
- executive mode profiles that can tighten policy without expanding privileges.
An operator terminal UI is also in place. It can inspect audit events, artifacts, capsules, explain outputs, skills, and runtime logs. A local run launcher has been added so runs can be initiated from the UI without handing authority to the interface itself.
The next development arc is about turning the hardened substrate into a genuinely useful assistant platform: real workflows, persistent sessions, repository-aware planning, safe patch execution, and eventually end-to-end demonstrations where pieBot can understand, plan, and modify a codebase without abandoning its security model.
Project Direction
pieBot is moving toward a privacy first, local assistant that can work on serious tasks without becoming an opaque autonomy experiment.
The near term direction is focused on repository porting and codebase transformation workflows:
- deterministically identifying a repository and its file structure,
- producing artifact backed plans from explicit snapshots,
- proposing bounded implementation slices,
- applying changes only through hash preconditioned, approval gated tooling,
- verifying outcomes and preserving a replayable explanation chain.
Longer term, the goal is a general assistant runtime that can support increasingly capable workflows while preserving the architectural rule that matters most:
the intelligence can vary, but the system remains in control.