MiniClaw Deep Dive: The Micro-Kernel Agent Architecture Inspired by OpenClaw

Forum topic · 小凯 · 2026-02-12

Summary

MiniClaw is a minimal, MIT-licensed open-source implementation of the popular OpenClaw project, designed as a universal micro-kernel agent for MCP clients such as Claude CoWork, Qoderwork, and WorkBuddy. Built with TypeScript, Node.js, the MCP SDK, Zod, and node-cron, it follows a three-layer architecture: a Kernel (memory graph, skills, execution sandbox), an Interface (MCP protocol and tool dispatch), and a DNA layer of nine Markdown templates defining personality, rules, and identity. Key features include the ACE Adaptive Context Engine with time-based modes (morning, work, break, evening, night) and a sandwich-structured context priority system; a two-tier memory model with daily logs and distilled long-term knowledge in MEMORY.md; an entity knowledge graph; a heartbeat mechanism running every 30 minutes; and self-evolution via miniclaw_update. Security is enforced through a command whitelist (blocking rm, sudo, chown), 10-second timeouts, 1MB output caps, and fully local data storage under ~/.miniclaw/ with no cloud uploads. The codebase spans roughly 2,700 lines across two TypeScript source files and nine Markdown templates.

Project Overview

MiniClaw is a minimal implementation of the viral open-source project OpenClaw — a universal "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

Three-Layer Model

| 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 for scheduling

ACE Adaptive Context Engine

Time-Mode System

| Mode | Time | Feature | |-----|------|---------| | Morning | 06–09 | Morning briefing | | Work | 09–12, 14–18 | Standard work | | Break | 12–14 | Rest period | | Evening | 18–22 | Reflection suggestions | | Night | 22–06 | Minimal mode |

Context Priority (Sandwich Structure)

Head (high weight)

Middle (background)

Tail (recency effect)

Memory System

Two-Tier Memory

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

Memory Distillation Triggers

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

Entity Knowledge Graph

Core Tools

| Tool | Function | |-----|----------| | miniclaw_update | Update core files, self-evolution | | miniclaw_note | Quick log notes | | miniclaw_read | Read 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 config | Medium | | MEMORY.md | Long-term memory | Medium | | HEARTBEAT.md | Periodic checks | Low | | BOOTSTRAP.md | First-run guidance | One-time | | SUBAGENT.md | Sub-agent context | – |

Heartbeat and Evolution

Heartbeat interval: every 30 minutes
Automatic evolution: updates SOUL.md, USER.md, etc., based on user feedback
File health checks: detects stale files and prompts maintenance

Security

Command Execution Whitelist

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

Data Security

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

Project Stats

Code size: ~2,700 lines
Core files: 2 TypeScript source files
Templates: 9 Markdown files
Architecture: micro-kernel + MCP protocol

Links

GitHub: https://github.com/8421bit/miniclaw
Upstream project: OpenClaw
License: MIT

---

*This outline serves as the framework for a subsequent multi-chapter detailed analysis report, and as a reference for studying MiniClaw/OpenClaw architecture design. The full outline spans 20 chapters covering overview, architecture, core modules, the DNA template system, ACE, memory, skills, heartbeat/evolution, security, MCP implementation, configuration/deployment, testing, tech stack, code quality, performance, extensibility, relation to OpenClaw, best practices, outlook, and appendices.*