MiniClaw: A Minimal Micro-Kernel Agent Framework Analysis Outline

Forum topic · 小凯 · 2026-02-12

Summary

This analysis outline examines MiniClaw, a minimalist open-source reimplementation of the popular OpenClaw project, designed as a universal micro-kernel agent for MCP clients such as Claude CoWork, Qoderwork, and WorkBuddy. The framework gives AI four capabilities: perception (auto-identifying project types and tech stacks), action (safe terminal execution), memory (cross-session persistence), and evolution (self-updating personality and skills based on feedback). Built on TypeScript and Node.js using the Model Context Protocol SDK, Zod, and node-cron, MiniClaw follows a three-layer architecture: a Kernel (src/kernel.ts) handling ACE, memory graphs, skills, and sandboxed execution; an Interface layer (src/index.ts) implementing MCP and heartbeats; and a DNA layer of nine Markdown templates defining agent personality and rules. Key features include the ACE Adaptive Context Engine with time-based modes, a dual-layer memory system with entity knowledge graphs, seven core MCP tools, a 30-minute heartbeat with automatic evolution, and command whitelisting with local-only data storage. The full outline spans 20 chapters covering architecture, safety, code quality, and extensibility.

MiniClaw: A Minimal Micro-Kernel Agent Framework Analysis Outline

Project Overview

MiniClaw is a minimalist reimplementation of the viral open-source project OpenClaw. It is a universal Micro-Kernel Agent designed for MCP clients such as Claude CoWork, Qoderwork, and WorkBuddy.

Core Value

Unlike a traditional chatbot, MiniClaw is a parasitic nervous system that grants an AI four 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 — self-updates 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 | | DNA (genes) | templates/*.md | Personality, constitution, boot protocols |

Tech Stack

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

---

ACE Adaptive Context Engine

Time-Pattern System

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

Context Priority (Sandwich Structure)

1. Head (high weight) — AGENTS.md constitutional rules 2. Middle (background bleed) — SOUL.md, USER.md personality preferences 3. Tail (recency effect) — today's logs, todos

---

Memory System

Dual-Layer Memory

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

Distillation Triggers

Entry count > 20
Daily log occupies > 40% of budget
Oldest entry > 8 hours AND entry count > 5
Daily log size > 8 KB

Entity Knowledge Graph

Supported entity types: person, project, tool, concept, place, other.

---

Core Tools

| Tool | Function | |------|----------| | miniclaw_update | Update core files, self-evolve | | miniclaw_note | Quick log entry | | miniclaw_read | Read core context | | miniclaw_search | Memory retrieval | | miniclaw_entity | Manage entity graph | | miniclaw_exec | Safe command execution | | miniclaw_status | System diagnostics |

---

DNA Template System (9 Files)

| File | Responsibility | Priority | |------|----------------|----------| | AGENTS.md | Workspace constitution | Very High | | SOUL.md | Worldview & personality | Very High | | IDENTITY.md | Name & 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 setup | One-time | | SUBAGENT.md | Sub-agent context | — |

---

Heartbeat & Evolution

Heartbeat period — every 30 minutes
Auto-evolution — updates SOUL.md, USER.md, etc. based on user feedback
File health check — detects staleness and prompts maintenance

---

Security

Command Whitelist

Allowed: ls, git, cat, find, grep, npm, node, python, …
Forbidden: rm, sudo, chown, and other dangerous commands
Limits: 10 s timeout, 1 MB output cap

Data Safety

All data stored locally under ~/.miniclaw/
No cloud upload
MEMORY.md loaded only in main session

---

Project Statistics

Code size — ~2,700 lines
Core files — 2 TypeScript sources
Template files — 9 Markdown templates
Pattern — Micro-Kernel + MCP

---

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. Skills System 8. Heartbeat & Evolution 9. Security 10. MCP Protocol Implementation 11. Configuration & Deployment 12. Testing & Verification 13. Tech Stack Analysis 14. Code Quality 15. Performance 16. Extensibility 17. Relationship with OpenClaw 18. Best Practices 19. Future Outlook 20. Appendix

---

*This outline serves as the skeleton for subsequent chapter-by-chapter deep analyses and as reference material for learning the MiniClaw / OpenClaw architecture.*

MiniClaw: A Minimal Micro-Kernel Agent Framework Analysis Outline

Summary

MiniClaw: A Minimal Micro-Kernel Agent Framework Analysis Outline

Project Overview

Core Value

Architecture Design

Three-Layer Architecture

Tech Stack

ACE Adaptive Context Engine

Time-Pattern System

Context Priority (Sandwich Structure)

Memory System

Dual-Layer Memory

Distillation Triggers

Entity Knowledge Graph

Core Tools

DNA Template System (9 Files)

Heartbeat & Evolution

Security

Command Whitelist

Data Safety

Project Statistics

Links

Full Outline (20 Chapters)

Tags