Entry point for all Markus technical documentation. Every domain has one authoritative document;
a mechanism is described in full only in its home document and cross-referenced everywhere else.
Docs are grouped by kind, not by package. A file's folder tells you how much to trust it:
| Folder |
What lives here |
Lifetime |
architecture/ |
How the system is designed and built — canonical description of each subsystem |
Living |
api/ |
REST + WebSocket reference |
Living |
guides/ |
Setup, development, operations, packaging, community |
Living |
design/ |
Design documents and proposals (built or pending) |
Living until implemented |
records/ |
Dated engineering records — audits, post-mortems, hardening logs |
Historical, frozen |
images/ |
Assets referenced by the top-level README |
— |
Conventions
- Docs are written in English. A doc describes the current behaviour; history belongs in
records/ or in git.
- Source comments point at the specific doc and section that justifies the code, so a reader can
always get from the code to its rationale.
- When a doc contradicts the code, the code wins — and the doc gets a PR.
The canonical description of how Markus works. Read architecture.md first; it maps the rest.
| Document |
Domain |
| architecture.md |
System overview, package structure, channels, deployment, observability |
| architecture-fragility.md |
Why this system produces fragile bugs, and the structural rules that prevent it |
| agent-runtime.md |
Agent lifecycle, execution model, workspace isolation |
| cognitive-architecture.md |
Cognitive cycle, deterministic context assembly, heartbeat integration |
| memory-system.md |
Memory layers, storage compaction, memory flush |
| prompt-engineering.md |
Prompt & context assembly, LLM call taxonomy, context packing, caching |
| mailbox-system.md |
Mailbox priority queue + attention controller (focus, interrupts, yield, cancel) |
| state-machines.md |
FSMs for tasks, requirements, callbacks, mailbox items, notebook |
| state-ownership.md |
State-ownership contract: who owns what, who may read it, in which execution context |
| concurrent-processing.md |
How one agent handles multiple sessions / mailbox items in parallel |
| tool-system.md |
Tool selection, tool result envelope, execution loop, subagent budgets |
| streaming-and-reattach.md |
SSE streaming, soft-disconnect, reattach, client resilience |
| llm-provider-timeouts.md |
Per-provider timeout/retry governance matrix, known risk inventory |
| learning-loop.md |
Agent self-improvement, distillation, memory consolidation |
| frontend/team-chat.md |
Team Chat page (web-ui): state model and interaction reliability contracts |
| messaging-gateway.md |
Comms layer: platform manifests, bot instances, inbound routing, outbound & notifications, capability model |
| Document |
Domain |
| api.md |
REST endpoints and WebSocket events |
| Document |
Domain |
| guide.md |
Setup, configuration, Web UI walkthrough |
| development.md |
Local setup, dev scripts, testing, debugging |
| coding-tools.md |
External coding CLI integration (Claude Code / Codex / Cursor) |
| skill-ecosystem.md |
Import/export skills from skills.sh, SkillHub, OpenClaw, AgentScope, MCP |
| remote-access.md |
Cloudflare Tunnel, Tailscale, FRP, ngrok |
| release-and-distribution.md |
Build, packaging, publishing pipeline |
| community.md |
Community channels, rules, and launch plan |
Dated engineering records. These are not maintained as living documentation — they preserve the
rationale, evidence and decision trail behind changes that are now in the code. Read them when you
want to know why, not what.