Architecture

ClawAgen is a workspace for AI assistants that belong to the people who use them. Each staff member in your company gets their own tenant — a folder on disk where they design as many agents as they need, with their own skills, memory, and channel surfaces. This guide walks the whole stack, from the folder on disk up to the streamed reply.

{['Channel','Agent runtime','Tenant filesystem'].map((s,i) => (

{['◐','◉','◆'][i]}

{s}

))}

message in

prompt + tools

md + sqlite

The round-trip of a single message.

The mental model

If you've used OpenClaw{' '} on your laptop, you already know this model — ClawAgen is the same idea, scaled for teams. One Tenant is a folder. Inside that folder, one or more Agents{' '} share the same Skills and Memory foundation, while each carries its own identity, toolset, and routing rules.

The LLM is handed a curated registry of first-party tools — grouped by domain and gated by role. The admin agent sees the full set (file I/O, shell, web, memory, media, channels, sessions, cron, skills). The customer-facing agent sees a read-only + message subset — sensitive tools like bash, write, and cron are admin-only.

The four pieces

Tenants

Each user is a tenant. A tenant is a directory /data/tenants/{accountId}/{' '} with its own SQLite file, its own Markdown context, and its own channel credentials. A query against tenant A physically cannot see tenant B — they open different database files.

# who the agent is ├── SOUL.md # values, tone ├── USER.md # facts about the owner ├── AGENTS.md # agent catalog ├── TOOLS.md # tool preferences ├── HEARTBEAT.md # dynamic state (updated every 5 min) ├── MEMORY.md # accumulating narrative ├── BOOTSTRAP.md # first-turn-only context ├── data.db # sqlite + sqlite-vec + FTS5 ├── skills/{name}/SKILL.md ├── memories/*.md ├── sessions/{id}.json └── config/ ├── personality.md ├── providers.yaml └── channels/*.yaml` }]} />

Agents

A tenant can run as many agents as they need. One staff member might keep a single general-purpose assistant; another might maintain several — a research agent, an operations agent, a customer-response agent — each with its own IDENTITY.md, its own allowed tools, and its own channel bindings.

Agents in the same tenant share Skills and Memory by default, so knowledge gathered by one is available to the others. What differs is voice, permissions, and routing. A bindings.yaml file maps{' '} (channel, sender) tuples to whichever agent should answer — so the same inbound surface can hit different agents depending on who is asking.

Add an agent by creating its entry in agents.yaml and, optionally, its own IDENTITY.md. No code changes, no redeploy — the tenant's workspace picks it up on the next request.

Skills

A skill is a directory containing a SKILL.md file. The front-matter has a name, description, and optional trigger phrase. The body describes — in natural language — what the agent should do. Skill names and descriptions are always in the system prompt (compact); bodies load only when the agent calls load_skill.

Skills are the source of truth. Edit skills/weekly-summary/SKILL.md, push the change, and the agent picks it up on the next turn — no redeploy, no compile step.

Memory & context files

Memory is not a single concept — it's a layered system of Markdown files. IDENTITY.md, SOUL.md, USER.md change rarely and define{' '} who the agent is.{' '} HEARTBEAT.md is auto-updated every 5 minutes with dynamic state.{' '} MEMORY.md accumulates narrative turn-by-turn and is LLM-compacted nightly. The memories/ directory holds key-value memories, indexed for hybrid search (vec cosine + FTS5 BM25 + Reciprocal Rank Fusion).

Life of a message

When a message lands on an agent endpoint, the runtime goes through the same steps regardless of which agent is answering or which surface the request came from:

authMiddleware validates the API key against platform.db and resolves the accountId.
resolveAgent inspects (accountId, channel, sender) against the tenant's bindings.yaml and picks which agent should answer.
prompt-builder reads the tenant's context files (IDENTITY.md et al) and the chosen agent's identity, then assembles the system prompt.
Skill names + descriptions are appended. The full bodies are not included.
The configured LLM is called with the agent's role-filtered tool registry (~28 first-party tools plus any tenant plugin tools).
Tool calls stream back. Each tool has a typed handler that runs against the tenant DB/FS, the sandbox, or an external provider (web search, image gen, channel adapters).
Text deltas stream to the client over SSE. When the model stops, the session is persisted to sessions/{id}.json.

Steps 1–4 are under a few milliseconds (filesystem reads + in-memory lookups). Step 5 dominates — an average turn is 1.5–4 seconds of streamed tokens. Step 7 writes on completion, not turn-by-turn. For a deeper trace with a worked example, see the{' '} Message flow page.

The tool registry

The brain runner aggregates every first-party tool from{' '} agents/src/brain/tools/ and surfaces them to the LLM. Tools are grouped by domain and each one declares an agents allowlist:

File I/O: read, ls, find, grep (both agents) · write, edit, apply_patch (admin only)
Web: web_search, web_fetch (both)
Shell: bash, exec (admin only — sandbox + host-side command execution)
Memory & search: memory_query, faq_search, session_status (both) · update_plan (admin)
Media: pdf (both) · image_generate (admin)
Channels: message (both) — sends through the tenant's configured channel adapters
Sessions: sessions_list, sessions_history, sessions_yield (both) · sessions_spawn, sessions_send, subagents (admin)
Multi-agent: agents_list (both)
Ops: cron, process (admin only)
Skills: load_skill (both) — progressive disclosure, full body only on demand

Per-tenant plugins extend the registry via{' '} api.registerTool(accountId, tool) — a plugin can ship an API client, a domain-specific aggregator, or a channel adapter and the LLM sees it on the next turn. First-party tools win on name collisions.

// Excerpt of what the admin agent sees — 28 first-party tools + any plugin tools [ { "name": "read", "description": "Read a file from the tenant filesystem.", ... }, { "name": "web_search", "description": "Search the web via the configured provider.", ... }, { "name": "bash", "description": "Run a shell command in the tenant sandbox.", ... }, { "name": "memory_query", "description": "Hybrid search over memories (vec + FTS5).", ... }, { "name": "message", "description": "Send a reply through a connected channel adapter.", ... }, { "name": "cron", "description": "Schedule a recurring task.", ... }, { "name": "load_skill", "description": "Load a SKILL.md body by name.", ... } /* ... 21 more ... */ ]` }]} />

How isolation actually works

Tenant isolation is enforced at two layers. First, every SQL query routes through{' '} getTenantDb(accountId) which opens a specific SQLite file. Second, every filesystem path is joined onto /data/tenants/{accountId}/ before use. There is no cross-tenant query path, because the DB handle itself is different.

The bash tool runs in an ephemeral Docker sandbox (alpine + jq + ripgrep + fd + gh), mounted read-only everywhere except the tenant's own directory. Even if a prompt injection made the model try rm -rf /, it couldn't reach past the tenant boundary.

Recap

Tenants are folders on disk, one per staff member, fully isolated.
Agents are configurable — each tenant runs one or many, each with its own identity and toolset.
Skills are Markdown — edit the file, behavior changes live.
Memory is layered Markdown + a hybrid-searchable vector/FTS index.
The LLM sees a curated, role-gated tool registry (~28 first-party tools + per-tenant plugin tools) — not a flat 60-tool dump.

Ready to build? Jump to the API reference and start writing code.