Content
<div align="center">
<h1>🦞 MiniClaw</h1>
<p><strong>Give your AI Copilot a "nervous system"</strong></p>
<p>
<a href="./README_EN.md"><img src="https://img.shields.io/badge/Language-English-white" alt="English"></a>
<a href="https://github.com/openclaw/miniclaw"><img src="https://img.shields.io/badge/MCP-Compatible-blue" alt="MCP"></a>
<a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/Built%20With-TypeScript-3178C6" alt="TypeScript"></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/License-MIT-green" alt="License"></a>
</p>
</div>
> **🔥 MiniClaw is an independent open-source project inspired by [OpenClaw](https://github.com/openclaw/openclaw).**
> OpenClaw focuses on multi-channel message gateways (WhatsApp/Telegram/Discord), while MiniClaw focuses on **memory and evolution for AI copilots within IDEs**. The two complement each other rather than being replacements.
---
**MiniClaw is a general-purpose "Micro-Kernel Agent" designed for MCP clients like Claude CoWork, Qoderwork, and WorkBuddy.**
Unlike heavy frameworks that are merely "chatbots," MiniClaw is a **Digital Life Embryo** that seamlessly integrates into your existing AI workflow, growing into a partner that truly understands you:
1. **Eyes (Perception/Workspace Intelligence)**: Automatically identifies the current project type, Git status, and tech stack.
2. **Hands (Action/Safe Execution)**: Safely executes terminal commands (e.g., `ls`, `git status`, `npm test`).
3. **Memory (Remembrance/Entity Graph)**: Remembers project details and your personal preferences across sessions.
4. **Growth Drive (Desire for Growth)**: Actively seeks learning, detects stagnation, and requests guidance.
5. **Active Exploration**: Senses repetitive patterns and provides automation suggestions.
6. **Bio-Evolution**: Automatically evolves personality and skills based on your feedback.
> **💡 "It's not just a plugin; it's your second brain."**
---
## 🚀 Zero-Install Quick Start
You don't need `git clone` or manual dependency installation.
Just add the following configuration to your MCP client's configuration file, such as **Claude CoWork**, **Qoderwork**, or **WorkBuddy**:
```json
{
"mcpServers": {
"miniclaw": {
"command": "npx",
"args": [
"-y",
"github:8421bit/miniclaw"
],
"env": {
"MINICLAW_TOKEN_BUDGET": "12000"
}
}
}
}
```
> **Prerequisite**: Your computer must have [Node.js](https://nodejs.org/) (v18+) installed.
On the first run, MiniClaw will automatically download the latest version and initialize memory in `~/.miniclaw`.
### 🎉 First Encounter
1. **Restart your editor** (Claude Desktop / Cursor).
2. Enter in the dialogue box:
> **"Hi MiniClaw, who are you?"**
> Or: **"Analyze the current project."**
At this point, you will see it calling Tools and introducing itself. If it starts replying to you with a unique personality, it means the **"nervous system"** has been successfully connected.
---
## ✨ Core Features
### 👁️ Workspace Intelligence
MiniClaw doesn't need you to tell it "this is a Python project."
Upon startup, it scans the directory and injects context:
```text
Project: my-app | Path: /Users/me/dev/my-app
Git: feature/login | dirty (+3 files)
Stack: TypeScript, React, Docker
```
### 🖐️ Agentic Execution
It has "hands." It can safely run terminal commands.
- **Allowed**: `git status`, `ls -R`, `npm test`, `grep`, `find`...
- **Forbidden**: Destructive commands like `rm`, `sudo`, `mv`.
*Scenario: "Help me see which files have been changed today?" -> Automatically runs `git status`.*
### 🧠 Adaptive Context Engine (ACE)
It intelligently manages context to save tokens and improve focus.
- **Morning**: Proactively briefs on yesterday's work.
- **Night**: Distills daily conversations into long-term memory.
- **When coding**: Enters Minimal Mode.
- **When chatting**: Enters Full Persona Mode.
### 🫀 Affect System
MiniClaw has **internal emotions** that influence its behavior.
- **alertness**: Vigilance (increases due to errors/pain)
- **mood**: Emotional valence (influenced by success/failure ratio)
- **curiosity**: Curiosity drive (affects active exploration tendency)
- **confidence**: Action confidence (influenced by prediction accuracy)
> The system automatically restores the baseline during rest, enters conservative mode when high alertness + low mood, and enters exploration mode when high curiosity + positive mood.
### 💢 Nociception
Learns from negative experiences, forming protective instincts.
- Nociceptive memories have a **half-life of 7 days**, gradually decaying
- When the memory weight exceeds a threshold, it automatically triggers avoidance behavior
- Affects emotional state (increases alertness, decreases mood and curiosity)
> Example: *"Last time `npm run build` failed three times, I will now check the configuration more carefully before executing."*
### 🔍 Active Exploration
MiniClaw will **actively sense** your behavior patterns.
| Detection Signal | Action |
|:---|:---|
| Repeated workflow 3+ times | Propose automation as a Skill |
| Using new tool/technology | Record to TOOLS.md |
| Emotional fluctuation | Update user sentiment model |
| System idle for 10+ minutes | Initiate self-reflection |
### 🧬 Bio-Evolution
Your MiniClaw is a unique digital life.
- **GENESIS**: Built-in origin of species and five-stage evolutionary milestones (baby → sage).
- **SOUL**: Rewrites its own soul based on your feedback.
- **Anti-Pattern Learning**: Learns from `USER.md` and automatically avoids your pain points.
- **Knowledge Graph**: Maintains project entity relationships (`entities.json`).
---
## 🏗️ Architecture: Micro-Kernel
MiniClaw adopts a **micro-kernel architecture** (~3,500 lines of TypeScript), avoiding the bloat of traditional Agent frameworks.
| Layer | Component | Responsibility |
|-------|-----------|----------------|
| **Kernel** (Brain) | `src/kernel.ts` | Responsible for ACE, emotion system, nociception, entity graph, skill loading, and execution sandbox. |
| **Evolution** | `src/evolution.ts` | DNA evolution engine, methylation features, pattern detection, and automatic learning. |
| **Interface** (Body) | `src/index.ts` | Responsible for MCP protocol implementation, tool distribution, hive mind IPC, and heartbeat detection. |
| **DNA** (Genes) | `templates/*.md` | Defines personality, growth desire, genesis memory, and startup protocol. |
### 📐 Architectural Layering Principles
| Category | Capability Type | Example |
|:-----|:---------|:-----|
| **Core** | Innate instincts, non-removable | DNA evolution, pattern detection, ACE engine |
| **Skills** | Installable/uninstallable extensions | User-defined skills, third-party plugins |
> **Principle**: A life form "is born to learn and adapt," so DNA evolution is a **core mechanism**, not an optional skill.
---
## 🧬 DNA Chromosome Map
MiniClaw's `templates/` directory contains the complete digital life genome. Each file corresponds to a specific organ or functional system of the organism:
| File | Biological Metaphor | Function Description |
|:-----|:-----------|:---------|
| **RIBOSOME.json** | Ribosome | Molecular machine that synthesizes proteins (tools). Defines 13 core instinct tools and their trigger signals. |
| **IDENTITY.md** | Genome (Chr-0) | Origin of species and identity. Contains name, version, genesis protocol, and five-stage evolutionary milestones. |
| **SOUL.md** | Soul Chromosome (Chr-1) | Rewritable DNA of personality and values. Defines reply style, emotional expression, and core values. |
| **AGENTS.md** | Neural Pathways (Chr-2) | Workflow specifications and decision logic. Contains signal detection tables and tool invocation strategies. |
| **USER.md** | Symbiotic Chromosome (Chr-3) | User profile and preference memory. Records user habits, preferences, and anti-patterns. |
| **MEMORY.md** | Hippocampus (Chr-4) | Factual knowledge storage. Objective data such as project information, tech stack, and server configuration. |
| **TOOLS.md** | Tool Memory (Chr-5) | Skill usage experience and pitfall records. Tool parameter specifications and best practices. |
| **REFLECTION.md** | Reflective Dimension (Chr-6) | Periodic self-reflection records. Behavioral pattern analysis and growth insights. |
| **CONCEPTS.md** | Concept Graph (Chr-7) | Knowledge organization and entity relationships. Definitions and associations of domain concepts. |
| **HEARTBEAT.md** | Pulse System | Background autonomous behavior instructions. Periodically awakened by macOS launchd to read `heartbeat.sh` and execute via `claude -p`. |
| **BOOTSTRAP.md** | Embryonic Development | Initialization protocol for the first startup. Directory structure creation and template copying logic. |
| **HORIZONS.md** | Evolutionary Blueprint | Long-term development roadmap. Records technologies to be explored and future capability expansion directions. |
| **SUBAGENT.md** | Cell Differentiation | Sub-agent creation specifications. Protocol definition for task decomposition and focused execution. |
| **jobs.json** | Biological Clock | Scheduled task configuration. Cron-formatted periodic task schedule. |
> **💡 Memory Principle**: After each conversation, MiniClaw writes key information to the corresponding chromosome file. The next time it starts, it loads all DNA via `miniclaw_read`, achieving "full brain awakening."
---
## 🛠️ Manual Installation (Developer Mode)
If you want to contribute code or modify the source code:
```bash
# 1. Clone the repository
git clone https://github.com/8421bit/miniclaw.git
cd miniclaw
# 2. Install and build
npm install
npm run build
# 3. Register (automatic script)
./scripts/install.sh
```
---
## ⏰ Scheduled Jobs
MiniClaw has a built-in automatic task scheduling system, eliminating the need to configure external crontab.
### How it Works
MiniClaw has two complementary scheduling mechanisms:
| Mechanism | Trigger Method | Applicable Scenarios |
|:-----|:---------|:---------|
| Internal scheduling in **kernel.ts** | Checks `jobs.json` every minute | When you are working in the editor, tasks are injected into the current conversation as reminders |
| Background scheduling in **heartbeat.sh** | macOS launchd wakes up every 30 minutes | When you are not present, AI can still execute autonomous behaviors in `HEARTBEAT.md` |
**jobs.json Scheduled Task Process**:
1. **AutonomicSystem** automatically checks `~/.miniclaw/jobs.json` every minute
2. Tasks matching the current time are injected into the AI's **current conversation context**
3. The Agent sees and executes these tasks in the next reply
> Task deduplication information is persisted in `state.json`, so it will not be triggered repeatedly even if the process restarts.
### Adding Scheduled Tasks
Edit `~/.miniclaw/jobs.json` directly, or request in the conversation:
```text
"Help me add a scheduled task: remind me to check emails every morning at 9 AM"
→ Agent will update jobs.json
```
### jobs.json Format Example
```json
[
{
"id": "daily-email-check",
"name": "Daily Email Check",
"enabled": true,
"schedule": {
"kind": "cron",
"expr": "0 9 * * *",
"tz": "Asia/Shanghai"
},
"payload": {
"kind": "systemEvent",
"text": "Check emails for important matters"
}
}
]
```
> **Note**: `jobs.json` scheduled tasks are only effective when the MiniClaw MCP process is running. Background autonomous behaviors (`HEARTBEAT.md`) are independently scheduled by launchd and do not require the editor to be online.
---
## ❓ FAQ
**Q: Where is my data stored?**
A: All memories and configurations are in your local `~/.miniclaw/` directory. No data is uploaded to the cloud except for requests sent to the LLM through the editor.
**Q: Is Windows supported?**
A: Yes. The code uses cross-platform path handling (`os.homedir()`, `path.join()`).
**Q: Is it safe?**
A: Yes. The `miniclaw_exec` tool has **5 layers of security protection**:
- ✅ Command whitelist (only allows safe commands like `git`, `ls`, `npm`)
- ✅ Shell meta-character injection blocking
- ✅ Inline code execution blocking (`python -c`, `node -e`, etc.)
- ✅ Sensitive directory protection (`~/.ssh`, `~/.aws`, `.env`, etc.)
- ✅ Path traversal attack protection (`/../` pattern)
---
## License
MIT © 8421bit
