Skip to content

Commit fb91325

Browse files
QUSETIONSclaude
QUSETIONS
and
claude
committed
docs: definitive README — MiniCode as self-regulating coding agent
Focused on the single most distinctive feature: closed-loop cybernetic self-regulation. Every coding agent has tools and memory — only MiniCode has PID controllers that auto-fix problems in real time. - "It's like ABS for your AI agent" — one-sentence value prop - Problem/fix comparison table vs traditional approaches - 15 controllers in a clean scannable table - Verified test results upfront - Zero fluff, every section earns its place Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent 22bbe09 commit fb91325

1 file changed

Lines changed: 106 additions & 137 deletions

File tree

‎README.md‎

Lines changed: 106 additions & 137 deletions
Original file line numberDiff line numberDiff line change
@@ -1,196 +1,165 @@
1-
# MiniCode — Cybernetic AI Coding Agent
1+
# MiniCode
22

3-
> **Terminal-first AI coding assistant with closed-loop self-regulation**
3+
> **The coding agent that regulates itself.**
44
>
5-
> 钱学森工程控制论驱动 · 15+ 自适应控制器 · 737 tests
5+
> 15 cybernetic controllers watch your agent in real time —
6+
> auto-fixing context overflow, tool errors, cost spikes, and irrelevant memory.
7+
> No other coding agent does this.
68
7-
MiniCode is a terminal AI coding agent. It reads your codebase, executes tools, and writes code — like Claude Code or Aider. **What makes it different: it regulates itself.**
8-
9-
Every coding agent hits the same walls — context overflow, runaway costs, tool errors, irrelevant memory. MiniCode uses **engineering cybernetics** (PID loops, Kalman filters, feedback control) to detect these problems and auto-correct in real time. No human intervention needed.
10-
11-
---
12-
13-
## Quick Start
14-
15-
```bash
16-
git clone https://github.com/QUSETIONS/MiniCode-Python.git
17-
cd MiniCode-Python
18-
pip install -e .
19-
python -m minicode.main
20-
```
21-
22-
Mock mode (no API key):
23-
```bash
24-
MINI_CODE_MODEL_MODE=mock python -m minicode.main
25-
```
9+
[![Tests](https://img.shields.io/badge/tests-737%20passed-brightgreen)]()
2610

2711
---
2812

29-
## What It Can Do
30-
31-
MiniCode handles real coding tasks end-to-end. **10/10 real API tests pass with zero errors:**
32-
33-
| Task | Time | Result |
34-
|------|------|--------|
35-
| `Create hello.py with a hello() function` | 33s | ✓ |
36-
| `Find all files containing "cybernetic"` | 25s | ✓ |
37-
| `Read README and summarize` | 15s | ✓ |
38-
| `Edit: rename function + change return value` | 39s | ✓ |
39-
| `Multi-step: grep → read → analyze` | 68s | ✓ |
40-
| `Create utils with ISO 8601 timestamp` | 42s | ✓ |
41-
42-
---
13+
## Why MiniCode
4314

44-
## Architecture: The Cybernetic Loop
15+
Every AI coding agent hits the same problems: context fills up, tools fail, costs spiral, memory is noise. The industry answer is "better prompts" or "bigger models." We took a different path.
4516

46-
MiniCode wraps the LLM in a **Sense → Predict → Control → Act** feedback loop:
17+
MiniCode wraps the LLM in a **closed-loop cybernetic control system** — PID controllers, Kalman filters, feedback loops — that watches the agent in real time and auto-corrects before you even notice.
4718

4819
```
49-
User Input → Agent Loop → Response
50-
│
51-
┌───────────┼───────────┐
52-
│ │ │
53-
SENSE CONTROL ACT
54-
sensors PID ×4 tools
55-
Kalman×5 feedback budget
56-
metrics adaptive compact
20+
Your prompt → Agent Loop → Response
21+
│
22+
┌────────────┼────────────┐
23+
│ │ │
24+
SENSE CONTROL ACT
25+
Kalman×5 PID ×4 tools
26+
metrics feedback budget
5727
```
5828

59-
### What Gets Auto-Regulated
60-
61-
| Problem | Controller | Action |
62-
|---------|-----------|--------|
63-
| Context near limit | ContextPIDController | Auto-compaction, strategy selection |
64-
| Tool errors spiking | SelfHealingEngine | Safe mode, reduce concurrency |
65-
| Cost exceeding budget | BudgetPIDController | Tighten token budget |
66-
| Agent oscillating | FeedbackController | Reduce parallelism, dampen PID |
67-
| Task stalling | ProgressController | Switch strategy, narrow scope |
68-
| Memory irrelevant | DomainClassifier + Reranker | Domain-filter, LLM-curate top-3 |
69-
70-
### Controller Matrix
71-
72-
| Controller | Type | What It Does |
73-
|-----------|------|-------------|
74-
| ContextPIDController | PID | Usage → compaction strength |
75-
| BudgetPIDController | PID | Cost → token budget |
76-
| FeedbackController | Dual-PID | System state → 13-dim control signal |
77-
| AdaptivePIDTuner | Self-tuning | Auto-tunes every 20 turns |
78-
| StateObserver | Kalman ×5 | Hidden state from observables |
79-
| FeedforwardController | Preemptive | Intent → tool config |
80-
| PredictiveController | Forecast | Time series → proactive actions |
81-
| DecouplingController | RGA | Multi-variable coupling |
82-
| SelfHealingEngine | Recovery | 8 fault types auto-heal |
83-
| StabilityMonitor | Health | 6-dim health scoring |
84-
| ProgressController | Stall | Strategy suggestions |
85-
| MemoryInjectionController | PID | Controls injection rate |
86-
| ModelSelectionController | Router | Risk/cost model selection |
87-
| DomainClassifier | Classifier | 9 domains from file extensions |
29+
**It's like ABS for your AI agent.**
30+
31+
| Problem | Traditional Fix | MiniCode |
32+
|---------|----------------|----------|
33+
| Context overflow | Retry with bigger window | PID auto-compacts |
34+
| Tool errors pile up | Restart the session | Self-heals in real time |
35+
| Cost runs away | Manual budget check | Budget PID throttles |
36+
| Memory returns noise | Skip memory entirely | Domain filter + LLM curation |
8837

8938
---
9039

91-
## Smart Memory
40+
## What It Can Do
9241

93-
Remembers your project conventions across sessions — not just keyword search, but a full adaptive pipeline:
42+
Verified with DeepSeek V4 Pro. **10 real coding tasks, zero errors.**
9443

9544
```
96-
Task + Files → DomainClassifier → BM25 + SparseVector(RRF)
97-
→ Value(rel×fresh×util) → LLM Reranker → Spreading Activation → Inject
45+
Create hello.py with hello() 33s ✓
46+
Find all files with "cybernetic" 25s ✓
47+
Read + summarize README 15s ✓
48+
Edit: rename function + change val 39s ✓
49+
Multi-step: grep → read → analyze 68s ✓
9850
```
99-
100-
**Ablation study: 80 memories × 20 queries × 5 domains**
101-
102-
| Configuration | P@3 | Noise |
103-
|-------------|-----|-------|
104-
| BM25 (baseline) | 0.350 | 65% |
105-
| + Domain + Expansion | 0.450 | 38% |
106-
| + LLM Reranker (Full) | **0.717** | **6.7%** |
107-
108-
**2.05× precision improvement, 58% noise reduction.**
51+
Full results: [`docs/test_results.md`](docs/test_results.md)
10952

11053
---
11154

112-
## Terminal Experience
113-
114-
| Feature | How |
115-
|---------|-----|
116-
| Colored diffs | `edit_file` output: +green/-red/@@cyan with word emphasis |
117-
| Multi-line input | `Ctrl+J` inserts newline, multi-line rendering |
118-
| Word-level editing | `Ctrl+←→` jump words, `Ctrl+W` delete word, `Ctrl+K` to end |
119-
| Visual scrollbar | █ thumb, ▲▼ hints, ░ track |
120-
| Bracketed paste | Batch insertion, control character stripping |
121-
| Animated spinner | `⠋⠙⠹` 8fps during tool execution |
122-
| Focus tracking | Auto-refresh on terminal tab switch |
123-
| Fuzzy autocomplete | Prefix → subsequence fallback |
124-
125-
---
55+
## Quick Start
12656

127-
## Slash Commands
57+
```bash
58+
git clone https://github.com/QUSETIONS/MiniCode-Python.git
59+
cd MiniCode-Python
60+
pip install -e .
61+
python -m minicode.main
62+
```
12863

129-
| Command | Description |
130-
|---------|-------------|
131-
| `/help` | Show all commands |
132-
| `/memory` | Memory system status |
133-
| `/context` | Context window usage |
134-
| `/cybernetics` | Controller health dashboard |
135-
| `/skills` | List discoverable skills |
136-
| `/exit` | Save session and exit |
64+
No API key? Mock mode works out of the box:
65+
```bash
66+
MINI_CODE_MODEL_MODE=mock python -m minicode.main
67+
```
13768

13869
---
13970

14071
## Configuration
14172

142-
`~/.mini-code/settings.json`:
14373
```json
14474
{
145-
"model": "deepseek-v4-pro[1m]",
75+
"model": "your-model",
14676
"env": {
14777
"ANTHROPIC_BASE_URL": "https://your-endpoint",
14878
"ANTHROPIC_AUTH_TOKEN": "your-token"
14979
}
15080
}
15181
```
15282

153-
Environment variables:
154-
- `ANTHROPIC_BASE_URL` — API endpoint
155-
- `ANTHROPIC_AUTH_TOKEN` — API key
156-
- `MINICODE_MODEL_TIMEOUT` — API timeout in seconds
157-
- `MINICODE_TOOL_TIMEOUT` — Tool execution timeout
83+
---
84+
85+
## The 15 Controllers
86+
87+
Every turn, MiniCode's controllers measure, decide, and act:
88+
89+
| Controller | Job |
90+
|-----------|-----|
91+
| **ContextPIDController** | Usage → compaction strength |
92+
| **BudgetPIDController** | Spending → token budget |
93+
| **FeedbackController** | System health → 13-dim control signal |
94+
| **AdaptivePIDTuner** | Auto-tunes PID gains every 20 turns |
95+
| **StateObserver** | Kalman estimates of 5 hidden states |
96+
| **SelfHealingEngine** | Detects and recovers 8 fault types |
97+
| **FeedforwardController** | Pre-configures from task intent |
98+
| **PredictiveController** | Forecasts and acts before problems hit |
99+
| **DecouplingController** | Untangles multi-variable interactions |
100+
| **StabilityMonitor** | Multi-dimensional health scoring |
101+
| **ProgressController** | Detects task stalling |
102+
| **DomainClassifier** | Auto-detects frontend/backend/db/devops |
103+
| **MemoryInjectionController** | PID-controls memory injection rate |
104+
| **ModelSelectionController** | Risk/cost-driven model selection |
105+
| **CyberneticSupervisor** | Aggregates all controller states |
158106

159107
---
160108

161-
## Testing
109+
## Memory That Actually Works
162110

163-
```bash
164-
pytest # 737 passed, 2 skipped
111+
Not keyword search. A full adaptive pipeline:
112+
113+
```
114+
Task → DomainClassifier → BM25 + Vector(RRF) → Value Scoring
115+
→ LLM Reranker (curates top-3 from 15) → Spreading Activation → Inject
165116
```
166117

118+
**80 memories × 20 queries: P@3 0.35 → 0.72, noise 65% → 7%.**
119+
120+
The LLM Reranker uses the same model you're coding with to pick which memories actually matter.
121+
122+
---
123+
124+
## Terminal Polish
125+
126+
| Feature | Key |
127+
|---------|-----|
128+
| Colored diffs | `edit_file` output: +green/-red with word highlights |
129+
| Multi-line input | `Ctrl+J` — paste code blocks directly |
130+
| Word editing | `Ctrl+←→` `Ctrl+W` `Ctrl+K` |
131+
| Visual scrollbar | █ • ▲ ▼ |
132+
| Bracketed paste | Batch insert, strip control chars |
133+
| Spinner | `⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏` at 8fps |
134+
| Focus tracking | Auto-refresh on tab switch |
135+
| Fuzzy complete | `/mem` matches `/memory` |
136+
167137
---
168138

169-
## MiniCode Ecosystem
139+
## Testing
170140

171-
| Repo | Role |
172-
|------|------|
173-
| [MiniCode](https://github.com/LiuMengxuan04/MiniCode) | Main project |
174-
| [MiniCode-Python](https://github.com/QUSETIONS/MiniCode-Python) | Python (this repo) |
175-
| [MiniCode-rs](https://github.com/harkerhand/MiniCode-rs) | Rust |
141+
```bash
142+
pytest
143+
# 737 passed, 2 skipped
144+
```
176145

177146
---
178147

179148
## Theory
180149

181-
MiniCode's control loop is mathematically grounded:
150+
The control loop isn't heuristic — it's mathematically grounded:
182151

183-
- **Lyapunov stability**: V̇ = -(kp/m)·e² < 0, proving PID convergence
184-
- **Memory value function**: V(m,t,c) = relevance × freshness × utility
185-
- **Kalman optimality**: minimum-variance unbiased state estimation
186-
- **RRF fusion**: reciprocal rank fusion of BM25 + vector results
152+
| Concept | Formalization |
153+
|---------|--------------|
154+
| PID Stability | V̇ = -(kp/m)·e² < 0 (Lyapunov) |
155+
| Memory Value | V(m,t,c) = relevance × freshness × utility |
156+
| State Estimation | 5 Kalman filters, minimum-variance unbiased |
157+
| Retrieval Fusion | RRF: BM25 + SparseVector cosine |
187158

188-
See [`docs/memory_theory.md`](docs/memory_theory.md) for the full formal treatment.
159+
[`docs/memory_theory.md`](docs/memory_theory.md)
189160

190161
---
191162

192163
## Acknowledgments
193164

194-
- 钱学森《工程控制论》(Engineering Cybernetics, 1954)
195-
- Wiener, *Cybernetics* (1948)
196-
- Mem0, Letta/MemGPT, True Memory
165+
钱学森《工程控制论》(1954) · Wiener *Cybernetics* (1948) · Mem0 / Letta / True Memory

0 commit comments

Comments
 (0)