MiniClaw Analysis Report Outline: Micro-Kernel Agent Architecture Explained

Forum topic · 小凯 · 2026-02-12

Summary

MiniClaw is a minimal open-source implementation of the popular OpenClaw project, designed as a micro-kernel agent for MCP clients such as Claude CoWork, Qoderwork, and WorkBuddy. This forum post presents a 20-chapter analysis report outline covering MiniClaw's architecture. The system gives AI agents four core capabilities: perception (detecting project type, Git status, and tech stack), action (sandboxed terminal command execution), memory (cross-session persistence), and evolution (auto-updating personality and skills from feedback). MiniClaw uses a three-layer design—Kernel (memory graph, skill loading, execution sandbox), Interface (MCP protocol and tool dispatch), and DNA (Markdown templates defining personality and rules). Key features include an ACE Adaptive Context Engine with time-based modes, a sandwich-style context priority structure, a dual-layer memory model with distillation triggers, an entity knowledge graph, a 30-minute heartbeat cycle, and a security whitelist blocking dangerous commands like rm and sudo. The project is approximately 2,700 lines of TypeScript, stores all data locally, and is MIT-licensed on GitHub.

MiniClaw Analysis Report Outline — The Nervous System Architecture of a Micro-Kernel Agent

Project Overview

MiniClaw is a minimal implementation of the viral open-source project OpenClaw — a general-purpose micro-kernel agent designed for MCP clients such as Claude CoWork, Qoderwork, and WorkBuddy.

Unlike traditional chatbots, MiniClaw acts as a parasitic nervous system that gives AI four core capabilities: 1. 👁️ Eyes (Perception): Automatically identifies project type, Git status, and tech stack 2. 🖐️ Hands (Action): Safely executes terminal commands 3. 🧠 Memory: Remembers project details and user preferences across sessions 4. 🧬 Evolution: Automatically evolves personality and skills based on feedback

Architecture Design

Three-Layer Architecture

| Layer | Component | Responsibility | |-----|------|-------| | Kernel (Brain) | src/kernel.ts | ACE, memory graph, skill loading, execution sandbox | | Interface (Body) | src/index.ts | MCP protocol, tool dispatch, heartbeat detection | | DNA (Genes) | templates/*.md | Personality, constitution, boot protocol |

Core Tech Stack

TypeScript + Node.js
MCP SDK (@modelcontextprotocol/sdk)
Zod for parameter validation
node-cron scheduler

ACE Adaptive Context Engine

Time Mode System

Context Priority (Sandwich Structure)

Head (high weight)

Middle (background infusion)

Tail (recency effect)

Memory System

Dual-Layer Memory Model

Short-term memory: memory/YYYY-MM-DD.md daily journals
Long-term memory: MEMORY.md distilled knowledge

Memory Distillation Triggers

Entry count > 20
Journal budget usage > 40%
Oldest entry > 8 hours and entries > 5
Journal size > 8KB

Entity Knowledge Graph

Core Tool Set

| Tool | Function | |-----|--------| | miniclaw_update | Updates core files, self-evolution | | miniclaw_note | Quick journal notes | | miniclaw_read | Reads core context | | miniclaw_search | Memory retrieval | | miniclaw_entity | Entity knowledge graph management | | miniclaw_exec | Safe command execution | | miniclaw_status | System diagnostics |

DNA Template System (9 Core Files)

| File | Role | Priority | |-----|------|---------| | AGENTS.md | Workspace charter | Very high | | SOUL.md | Worldview and personality | Very high | | IDENTITY.md | Name and metadata | High | | USER.md | User profile | Medium | | TOOLS.md | Environment configuration | Medium | | MEMORY.md | Long-term memory | Medium | | HEARTBEAT.md | Periodic check items | Low | | BOOTSTRAP.md | First-run guidance | One-time | | SUBAGENT.md | Sub-agent context | — |

Heartbeat and Evolution Mechanism

Heartbeat cycle: Every 30 minutes
Automatic evolution: Updates SOUL.md, USER.md, and other files based on user feedback
File health checks: Detects file update status and prompts maintenance

Security Mechanisms

Command Execution Whitelist

Allowed: ls, git, cat, find, grep, npm, node, python...
Blocked: rm, sudo, chown and other dangerous commands
Limits: 10s timeout, output truncated at 1MB

Data Safety

All data stored locally (~/.miniclaw/)
No cloud uploads
MEMORY.md loaded only in the main session

Project Statistics

Code size: ~2,700 lines
Core files: 2 TypeScript source files
Template files: 9 Markdown templates
Architecture pattern: Micro-kernel + MCP protocol

Full Outline (20 Chapters)

1. Project overview 2. Architecture design 3. Core module analysis 4. DNA template system 5. ACE Adaptive Context Engine 6. Memory system 7. Skill system 8. Heartbeat and evolution mechanism 9. Security mechanisms 10. MCP protocol implementation 11. Configuration and deployment 12. Testing and validation 13. Tech stack analysis 14. Code quality analysis 15. Performance considerations 16. Extensibility design 17. Relationship with OpenClaw 18. Best practices 19. Future outlook 20. Appendix

*This outline serves as the framework for a forthcoming chapter-by-chapter detailed analysis, and can be used as a reference for learning the MiniClaw/OpenClaw architecture.*