IronClaw Architecture — For Lyra Comparison

System Architecture

High-level module relationships and data flow

graph TD
  CH["Channels
REPL, HTTP, WASM, WS, Signal"] --> CM["ChannelManager
hot_add, select_all"]
  CM --> SESS["Session Manager
Session-Thread-Turn"]
  SESS --> LLM["LLM Providers
7 backends + decorators"]
  LLM --> TOOLS["Tool System
Built-in + WASM + MCP"]
  TOOLS --> MEM["Memory
Workspace + Dual DB"]
  SESS --> HOOKS["Hooks System
6 interception points"]
  HOOKS -.-> LLM
  RT["Routines
Cron, Event, Webhook"] -.-> SESS
  SAFE["Safety Layer
Multi-layer defense"] -.-> TOOLS
  SAFE -.-> LLM

1. Memory Architecture

Workspace module + dual database backend with hybrid search

Workspace Module

Path-Based Storage

Mirrors file hierarchy with read/write/append/delete operations. Persistent per-agent context.

Dual Database

PostgreSQL + libSQL

pgvector + tsvector + JSONB
libSQL/Turso with FTS5, F32_BLOB vectors

Document Processing

Chunking Strategy

800-word chunks with 15% overlap
Minimum 50 words per chunk

Hybrid Search

Reciprocal Rank Fusion

RRF with k=60
Combines FTS + vector similarity scores

🧠

Identity Injection: System prompt includes AGENTS.md, SOUL.md, USER.md, and IDENTITY.md for persistent agent persona.

Context Compaction Strategies

80-85%

MoveToWorkspace

Offload context to workspace storage

→

85-95%

Summarize

LLM-generated summary replaces full context

→

>95%

Truncate

Hard cut of oldest turns

Memory Tools

Tool	Purpose
`memory_search`	Hybrid search across workspace and database memory
`memory_write`	Store new information to memory with embeddings
`memory_read`	Retrieve specific memory entries by path or ID
`memory_tree`	Browse memory hierarchy as a directory tree

2. Channels

Channel trait with 5 implementations and hot-add runtime management

graph TD
  subgraph Channels
    REPL["REPL/TUI
Ratatui"]
    HTTP["HTTP Webhook
Axum"]
    WASM["WASM Channels
Telegram, Discord,
Slack, WhatsApp"]
    WEB["Web Gateway
SSE + WebSocket"]
    SIG["Signal"]
  end
  REPL --> MGR["ChannelManager"]
  HTTP --> MGR
  WASM --> MGR
  WEB --> MGR
  SIG --> MGR
  MGR -->|select_all| STREAM["Merged
MessageStream"]
  MGR -->|injection| BG["Background Tasks"]

Channel Trait

Interface Methods

start() returns MessageStream
respond() sends reply to channel
broadcast() multi-target delivery
send_status() status indicator
name() channel identifier

Session Model

Session → Thread → Turn

Three-level hierarchy
Mapped by (user_id, channel, external_thread_id)
pending_auth mode bypasses safety for credential input

3. Event System

No central bus — hooks for interception, SSE for streaming, Observer for telemetry

Hooks

6 Interception Points

BeforeInbound
BeforeToolCall
BeforeOutbound
OnSessionStart
OnSessionEnd
TransformResponse

Hook Outcomes

3 Results

Pass — continue unchanged
Modified(data) — altered payload
Reject(reason) — block execution

Observer Trait

record_event()
record_metric()
Pluggable: Noop, Log, Multi

SSE Events

10+ Event Types

MessageReceived
ResponseStarted
ToolCalling
ApprovalNeeded
JobStarted
JobCompleted
ErrorOccurred
+ more...

4. LLM Providers

7 backends wrapped in a decorator chain with smart routing

Backend	Type
`NEAR AI`	Primary (NEAR ecosystem)
`OpenAI`	GPT models
`Anthropic`	Claude models
`Ollama`	Local inference
`OpenAI-compatible`	Any compatible endpoint
`AWS Bedrock`	AWS-managed models
`Tinfoil`	Privacy-focused

Decorator Pattern (wrapping chain)

Base

Raw API call

→

Recording

Log requests

→

Retry

Transient failures

→

CircuitBreaker

Fail fast

→

Failover

Fallback backend

→

Cached

Response TTL

→

SmartRouting

Task complexity

Smart Routing

Task Complexity Levels

Simple — small model, fast response
Moderate — balanced model
Complex — most capable model

Response Caching

Cache Key

Keyed by (model, messages_hash) with configurable TTL. Avoids redundant LLM calls for identical prompts.

5. Tool System

3 tool types with WASM sandboxing and dynamic tool generation

Built-in

45+ Rust Tools

Native performance, full system access. File I/O, shell, HTTP, memory, database operations.

WASM

Wasmtime Sandboxed

Third-party tools run in isolated WASM runtime with resource limits and security controls.

MCP Servers

Model Context Protocol

External tool servers connected via the MCP standard. Extensible without recompilation.

WASM Security Model

Multi-Layer Sandboxing

Fuel metering — CPU budget per execution
ResourceLimiter — 10MB memory cap
Epoch interruption — timeout enforcement

HTTP allowlist — only approved endpoints
Leak detection — watch for data exfil
BLAKE3 verification — binary integrity hash

⚙

Dynamic Tool Building: Agent describes needs in natural language, LLM generates Rust/WASM source, compiles and registers the tool at runtime. Self-extending tool capabilities.

Approval Levels

Level 1

Never

No approval required

→

Level 2

UnlessAutoApproved

Skip if policy allows

→

Level 3

Always

Human-in-the-loop required

6. Database

Dual-backend with 7 sub-trait supertrait and job state machine

PostgreSQL

Primary Backend

Connection pool via deadpool
Native types: pgvector, tsvector, JSONB
Full ACID transactions

libSQL / Turso

Edge Backend

Per-operation connections
WAL mode for concurrency
FTS5 + F32_BLOB vectors

Database Supertrait (7 Sub-traits)

Sub-trait	Responsibility
`ConversationStore`	Sessions, threads, turns, messages
`JobStore`	Background job lifecycle and state
`SandboxStore`	WASM sandbox state and permissions
`RoutineStore`	Scheduled routines and triggers
`ToolFailureStore`	Tool error tracking and retry data
`SettingsStore`	Runtime configuration and preferences
`WorkspaceStore`	Workspace file metadata and content

Job State Machine

Pending → InProgress → Completed → Submitted → Accepted

Error states: Stuck / Failed / Cancelled

7. Routines

Trigger-based automation with guardrails

graph TD
  subgraph Triggers
    CRON["Cron Schedule"]
    EVT["Event Regex"]
    WH["Webhook"]
    MAN["Manual"]
  end
  CRON --> ENGINE["Routine Engine"]
  EVT --> ENGINE
  WH --> ENGINE
  MAN --> ENGINE
  ENGINE --> LP["LightweightPrompt
Single LLM call"]
  ENGINE --> FJ["FullJob
Scheduler to Worker"]
  subgraph Guardrails
    MC["max_concurrent"]
    TO["timeout_secs"]
    MR["max_retries"]
  end
  ENGINE -.-> Guardrails

Triggers

4 Trigger Types

Cron — time-based scheduling
Event — regex pattern matching on events
Webhook — external HTTP trigger
Manual — user-initiated

Actions

2 Execution Modes

LightweightPrompt — single LLM call, immediate response
FullJob — scheduler dispatches to worker, async completion with job state machine

8. Safety

Multi-layer defense with 15+ leak detection patterns

Layer 1

Validator

Input format and bounds

→

Layer 2

Sanitizer

Strip dangerous content

→

Layer 3

Policy Rules

Allowed operations check

→

Layer 4

Leak Detector

15+ regex patterns

→

Layer 5

Credential Detector

Secrets in output

Defense Mechanisms

Additional Protections

Prompt injection defense
Shell environment scrubbing
Tool output wrapping in XML tags

⚠

Critical Path: Safety layer intercepts both tool inputs and LLM outputs. The Leak Detector runs 15+ regex patterns to catch API keys, tokens, passwords, and PII before they leave the system boundary.

IronClaw vs Lyra Comparison

Side-by-side architecture comparison for adoption planning

Aspect	IronClaw	Lyra
Language	Rust (~99k LOC)	Python (asyncio)
Memory	Hybrid RRF search, dual DB (PostgreSQL + libSQL)	TBD
Channels	Channel trait + WASM sandboxed adapters (5 types)	Hub-and-spoke architecture
Events	Hooks (6 points) + SSE (10+ types) + Observer trait	TBD
LLM	7 backends with decorator chain + smart routing	TBD
Tools	Built-in (45+) + WASM sandboxed + MCP servers	TBD
Database	PostgreSQL + libSQL dual-backend, 7 sub-traits	TBD
Safety	Multi-layer defense, 15+ leak patterns, credential detection	TBD

Key Patterns for Lyra

Recommended adoption and study priorities from IronClaw analysis

Adopt

Ready to Implement

Decorator pattern for LLM providers — composable resilience (retry, circuit breaker, cache)
WASM sandboxing for untrusted tool code — fuel metering, resource limits, hash verification
Hook interception points — 6 lifecycle hooks with Pass/Modified/Reject outcomes
Job state machine — Pending through Accepted with error states
Routine engine with triggers — Cron, Event regex, Webhook, Manual

Study

Investigate Further

Dual-database support — PostgreSQL + libSQL tradeoffs, when to use each
Dynamic tool building — LLM-generated WASM tools at runtime, compile and register
Smart routing by complexity — automatic model selection based on task analysis

💡

Strategic Note: IronClaw's Rust implementation provides performance and safety guarantees, but Lyra's Python/asyncio stack enables faster iteration. Focus on adopting the architectural patterns (decorator chain, hook system, state machines) rather than the implementation details.