Architecture Overview

Myrm is composed of five independent repositories, each serving a distinct role in the platform.

Repository Structure

Repository	Description	License
`myrm-agent-harness`	Python agent runtime engine	Closed Source
`myrm-agent-server`	Backend API server (FastAPI)	Open Source
`myrm-agent-frontend`	Next.js web application	Open Source
`myrm-agent-desktop`	Tauri desktop client	Open Source
`myrm-control-plane`	SaaS multi-tenant orchestrator	Closed Source

Separation of Concerns

┌────────────────────────────────┐
│     myrm-control-plane         │  SaaS only: sandbox allocation, tenant routing
├────────────────────────────────┤
│     myrm-agent-server          │  Business logic, API, single-machine deployment
├────────────────────────────────┤
│     myrm-agent-harness         │  Agent runtime engine (model-agnostic)
└────────────────────────────────┘

Harness is the framework layer — model management, middleware chain, context pipeline, security, tools
Server is the business layer — user management, session persistence, API endpoints, single-machine deployment
Control Plane is the orchestration layer — sandbox provisioning, billing, multi-tenant routing (SaaS only)

Frontend Architecture

Next.js App Router with:

Tailwind CSS v4 for styling with dual theme support (light/dark)
next-intl for Chinese/English internationalization
Zustand for client-side state management
WebSocket + SSE for real-time streaming
Responsive design for mobile and desktop

Backend Architecture

Python async service with:

FastAPI for REST API endpoints
LiteLLM for unified multi-model access (100+ models)
LangGraph for agent orchestration and state management
SQLite for primary data storage (single-machine, no distributed DB needed)
Qdrant for vector search (memory, skills, wiki)
38+ Middleware chain for security, logging, approval, and behavior control

Key Architectural Decisions

PPAF (Perception, Planning, Action, Feedback) Loop

Myrm embraces the PPAF framework for its core execution loop:

Perception: Extracting intent from multi-modal user input and reading memory context.
Planning: Breaking down complex instructions via the Planner Middleware or sequentialthinking subagent.
Action: Executing isolated, sandboxed tools and scripts via the Tool Executor.
Feedback: Analyzing tool execution outcomes and performing dynamic replanning or error recovery.

R.E.S.T. Engineering Standard

Myrm’s Harness layer is built around the R.E.S.T. philosophy:

Reliability (可靠性): 14 dynamic self-healing strategies, exponential backoff, and circuit breakers.
Efficiency (高效性): Context compression, caching optimization, and prompt-prefix protection.
Security (安全性): 6-layer defense-in-depth, including zero-trust sandboxing and strict policy gateways.
Traceability (可追溯性): Advanced metrics, structured audit logs, and granular session debugging.

Modular Middleware vs Monolithic Agent

Unlike some frameworks that put all agent logic in a single large class, Myrm uses a middleware chain architecture where each concern (security, approval, loop detection, completion checking, etc.) is an independent, testable module.

Async-First

All I/O operations use asyncio coroutines. This provides better resource utilization than thread pools for I/O-bound workloads (LLM API calls, file operations, network requests).

Framework-Business Separation

The harness engine contains zero business logic. It provides generic agent capabilities (tool execution, memory, security, streaming) that any business application can use. The server layer adds user management, session handling, and API contracts on top.

Fractal Self-Documentation (Open Product Layer)

The open-source myrm-agent tree uses a four-layer doc stack so contributors and LLMs can navigate code without guessing module boundaries:

Layer	Artifact	Role
L1	`ARCHITECTURE.md`	Whole-system map
L2	`*_SYSTEM.md`	Cross-module designs (memory, skills, etc.)
L3	`_ARCH.md` per folder	Module duty + file table
L4	File header `INPUT` / `OUTPUT` / `POS`	Single-file placement

Scale (verified 2026-08-13): 521+ _ARCH.md files across server, frontend, desktop, and shared packages. CI runs check_fractal_docs.py (directory coverage, strict headers, no stubs on api/ and channels/providers/) plus 696 architecture pytest gates (run_architecture_gates.sh). Typical agent competitors ship centralized docs/ only — zero per-module _ARCH maps.

CI Gates & Cross-Language Contract Parity

Beyond docs, the open product layer enforces machine-checkable contracts so frontend and backend can never silently drift apart:

Gate	What it enforces
Server `run_architecture_gates.sh`	Ruff lint + 4-way fractal docs + Prometheus rule semantics + 696 architecture pytest
Frontend `frontend-build.yml`	Oxlint (errors fail), `tsc` strict zero-regression, barrel-export whitelist, i18n completeness, >400-line module budget, Next.js build, Service Worker Push
`test_memory_injection_contract_parity`	Frontend `MemoryBriefInjectionStatus` state/source/reason unions must equal the harness memory-injection contract
`test_sse_event_type_parity`	Frontend SSE event manifest must cover every harness `AgentEventType`
`test_ui_component_type_parity`	Frontend UI component unions match the Python `UIComponentType`
`test_tool_group_factory_parity`	Tool-group factory keys align 1:1 with the tool-group map

These parity gates are proven live: on 2026-08-13 they caught and drove fixes for three real cross-language contract bugs (load_timeout reason missing from the TS union, memory_retrieval_trace missing from ToolEndStreamEvent, and a missing i18n mapping) — failures surfaced at CI time, before merge. The closed-source Harness adds a generic-capability purity gate (test_toolkits_agent_boundary): nothing under toolkits/ may import agent/, runtime/, or backends/ (including importlib string dynamic imports), so third parties reusing a generic capability never drag in the whole runtime; in 2026-09 it caught 7 violations that were fixed back to green. Contributor rule: generic code goes in toolkits/, session/runtime-bound code goes in agent/meta_tools/, business skills go in Server prebuilt skills — wrong layer fails CI. What you get: faster onboarding for self-hosters and integrators; doc drift blocked before merge, not discovered in production; frontend/backend contract drift fails the build instead of shipping a phantom bug.

Security Model

6-layer defense-in-depth. See Security Architecture for the complete model.

Deployment Modes

Mode	Components	Use Case
Local WebUI	Server + Frontend	Personal use, development
Tauri Desktop	Desktop + embedded Server	Native app experience
SaaS Cloud	Control Plane + Server + Frontend	Managed hosting, teams

​Architecture Overview

​Repository Structure

​Separation of Concerns

​Frontend Architecture

​Backend Architecture

​Key Architectural Decisions

​PPAF (Perception, Planning, Action, Feedback) Loop

​R.E.S.T. Engineering Standard

​Modular Middleware vs Monolithic Agent

​Async-First

​Framework-Business Separation

​Fractal Self-Documentation (Open Product Layer)

​CI Gates & Cross-Language Contract Parity

​Security Model

​Deployment Modes