Architecture

Architecture explains how PersonalClaw is put together: the gateway process, the provider boundary, memory and knowledge, loops, tasks and triggers, and the app platform. It is the section to read if you are extending the system rather than running it.

Start with the system overview — it names the parts and how a request moves through them, and the rest of the section assumes it.

Two pages define the contracts an extension is written against, and they are worth reading before writing any code. App platform covers what an app is: its manifest, the permissions that manifest declares and how they are enforced, and the install lifecycle — which stages an app in quarantine and scans it before it runs, on the invariant that the bytes scanned are the bytes installed. Provider boundary covers the rule that makes those apps removable — vendor-specific logic lives in app bundles, apps import core through one narrow surface and nothing else, and the page enumerates the in-core exceptions rather than leaving them implicit. If an app you are writing wants an import the boundary does not offer, that page is the one that says why.

The remaining pages describe subsystems an app can participate in. They are descriptions of shipped behaviour, not proposals — this section carries no roadmap, and designs PersonalClaw has considered and not built are in research instead.

These pages are core’s text, published from the release this site was built from — see release provenance. Corrections land in core, not here.

The subsystems

• AgentActivityFeed: the agent-worlds read contract — An agent world is an ambient scene of what your agents are doing right now — a thing you glance at, not a list you read.
• The App Platform — Apps are how PersonalClaw grows capabilities without core edits: model providers, channels, agents, search engines, tools, and full backend+UI dashboards are all apps.
• Chat & Sessions — How a message becomes a turn: the session model, the dashboard chat pipeline, persistence, and the memory-privacy modes.
• Inbox & Channels — Two seams connect PersonalClaw to the outside conversational world: the inbox (things arriving for the user’s attention) and channels (bidirectional messaging surfaces like Slack — implemented entirely by apps…
• Knowledge & Memory — Two related but distinct subsystems: Knowledge is the user’s ingested content library (notes, documents, media) with a processing pipeline and hybrid search; Memory is what the assistant learns and recalls across…
• Loops — the Autonomous Work Engine — A loop is a long-running autonomous work unit: a worker agent iterates in cycles toward a goal while a supervisor judges progress against ground truth.
• MCP end-user identity propagation without raw-token passthrough — design note — This note answers one question: how does a shared MCP server learn which end user a request is for, when the MCP authorization spec forbids forwarding the end user’s raw token? It exists because the ecosystem…
• PersonalClaw — Architecture Overview — PersonalClaw is a self-hosted personal AI gateway: one long-running process that hosts chat sessions, autonomous loops, a knowledge base, memory, tasks, scheduling, an inbox, and an app platform — all behind a local…
• The Provider Boundary — What Belongs in Core, and Why — PersonalClaw’s central architectural tenet: the core package is provider-agnostic.
• Security Model — Defense in depth for a system that runs an autonomous agent on your machine: authentication modes, command screening, an OS sandbox, one egress chokepoint, scoped tokens, supply-chain gates, untrusted-content…
• Shared-Store Provider Conformance — A shared-store provider is any provider that serves records some of which were attributed to somebody other than the local owner: a multi-tenant task backend, a trigger store (the bundled shared-automations app), a…
• SSO / OIDC integration — design note — Read security.md §“Auth modes” first.
• Tasks, Triggers & Workflows — The “get things done” layer: a task hierarchy shared by chat and the UI, cron/event triggers with pluggable actions, and SOP-style workflows.
• Tool-name wire fidelity — What happens to a tool’s name between its ToolDefinition and the moment the runtime dispatches a call back to it.
• Tool-schema wire fidelity — What happens to a tool’s parameter schema and description between its ToolDefinition and the model provider.
• Widgets: the child→parent wire contract — An agent-authored is arbitrary HTML with arbitrary scripts.
• Workflows — the Deterministic Orchestration Engine — A workflow is a declarative graph the engine executes: a spec tree of typed nodes, driven by one conductor per run, with every outcome journaled.