Skip to content

Commit 22bbe09

Browse files
QUSETIONSclaude
QUSETIONS
and
claude
committed
docs: README rewrite — real API test results, cleaner structure
- Added verified test results table (10/10 API tests pass) - Moved memory ablation to supporting section - Simplified architecture description - Removed redundant sections, kept practical content - Clear "What It Can Do" section upfront Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent b351770 commit 22bbe09

1 file changed

Lines changed: 91 additions & 138 deletions

File tree

‎README.md‎

Lines changed: 91 additions & 138 deletions
Original file line numberDiff line numberDiff line change
@@ -2,14 +2,11 @@
22

33
> **Terminal-first AI coding assistant with closed-loop self-regulation**
44
>
5-
> 钱学森工程控制论驱动 · 15+ 自适应控制器 · 718 tests
6-
>
7-
> [![Tests](https://img.shields.io/badge/tests-718%20passed-brightgreen)]()
8-
> [![Python](https://img.shields.io/badge/python-3.12-blue)]()
5+
> 钱学森工程控制论驱动 · 15+ 自适应控制器 · 737 tests
96
10-
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**.
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.**
118

12-
Every coding agent hits the same walls — context overflow, runaway costs, tool errors, irrelevant memory. MiniCode uses classic **engineering cybernetics** (PID loops, Kalman filters, feedback control) to detect these problems and auto-correct in real time. No human intervention needed.
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.
1310

1411
---
1512

@@ -29,27 +26,37 @@ MINI_CODE_MODEL_MODE=mock python -m minicode.main
2926

3027
---
3128

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+
---
43+
3244
## Architecture: The Cybernetic Loop
3345

3446
MiniCode wraps the LLM in a **Sense → Predict → Control → Act** feedback loop:
3547

3648
```
37-
┌──────────────────────────┐
38-
User Input ───→ │ Agent Loop │ ───→ Response
39-
│ (run_agent_turn) │
40-
└──────────┬───────────────┘
41-
│
42-
┌─────────────────────┼─────────────────────┐
43-
│ │ │
44-
┌────▼─────┐ ┌────▼─────┐ ┌────▼─────┐
45-
│ SENSE │ │ CONTROL │ │ ACT │
46-
│ sensors │────────→│ PID ×4 │─────────→│ tool │
47-
│ Kalman×5 │ │ feedback │ │ budget │
48-
│ metrics │ │ adaptive │ │ compact │
49-
└──────────┘ └──────────┘ └──────────┘
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
5057
```
5158

52-
### What gets auto-regulated
59+
### What Gets Auto-Regulated
5360

5461
| Problem | Controller | Action |
5562
|---------|-----------|--------|
@@ -60,142 +67,73 @@ MiniCode wraps the LLM in a **Sense → Predict → Control → Act** feedback l
6067
| Task stalling | ProgressController | Switch strategy, narrow scope |
6168
| Memory irrelevant | DomainClassifier + Reranker | Domain-filter, LLM-curate top-3 |
6269

63-
---
64-
65-
## Key Features
66-
67-
### Smart Agents
68-
- **15 cybernetic controllers** — your agent doesn't just run; it watches itself
69-
- **Dual-PID loop** — context PID (inner) + feedback PID (outer), closed-loop stability
70-
- **Kalman state estimation** — 5 hidden variables estimated from observable outputs
71-
- **Self-healing** — 8 fault types auto-detected and recovered
72-
- **Feedforward pre-configuration** — intent detection → pre-emptive tool/timeout/token tuning
73-
74-
### Memory That Learns
75-
- Remembers your project conventions across sessions
76-
- **Domain-aware retrieval**: auto-detects frontend/backend/database/devops context
77-
- **3-layer retrieval pipeline**: BM25 → LLM Reranker → Spreading Activation
78-
- **Auto-curation**: background agent consolidates, de-duplicates, validates, and links memories
79-
- **Multi-tier storage**: WORKING → SHORT_TERM → LONG_TERM → ARCHIVAL
80-
81-
### Terminal Experience
82-
- TUI-based interactive mode
83-
- Tool calling with concurrent execution
84-
- Session persistence and recovery
85-
- Permission-gated local operations
86-
- MCP server integration
87-
88-
---
89-
90-
## How It Works
70+
### Controller Matrix
9171

92-
```
93-
$ python -m minicode.main
94-
95-
> Add a login form component with email validation
96-
97-
[MiniCode senses: frontend task, React codebase]
98-
[Feedforward: pre-configures token budget=6000, timeout=45s]
99-
[Context PID: usage at 45%, no compaction needed]
100-
[Memory: domain classifier → frontend memories → LLM reranker → 3 curated memories injected]
101-
[Agent: generates Login.tsx with react-hook-form + zod]
102-
[Verification: runs tests, all pass]
103-
[Feedback: pattern reinforced, memory utility boosted]
104-
[Cost PID: $0.03 spent, well within budget]
105-
```
106-
107-
**The agent doesn't just respond — it manages itself.**
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 |
10888

10989
---
11090

111-
## Memory Retrieval Pipeline
91+
## Smart Memory
11292

113-
One of MiniCode's most advanced subsystems. Traditional agents inject memories by simple keyword search. MiniCode runs a full adaptive pipeline:
93+
Remembers your project conventions across sessions — not just keyword search, but a full adaptive pipeline:
11494

11595
```
116-
Task + Files
117-
│
118-
▼
119-
Domain Classification (9 domains, 60+ file extension mappings)
120-
│
121-
▼
122-
BM25 + Domain Weight (bm25×0.7 + jaccard×0.3)
123-
+ Query Reformulation fallback
124-
+ Vector Search fusion (optional, RRF)
125-
│
126-
▼
127-
LLM Reranker (curates top-15 → top-3 with reasoning)
128-
│
129-
▼
130-
Spreading Activation (related_to graph, depth=1)
131-
│
132-
▼
133-
Adaptive Injection (context-pressure-aware cooldown)
134-
│
135-
▼
136-
System Prompt
96+
Task + Files → DomainClassifier → BM25 + SparseVector(RRF)
97+
→ Value(rel×fresh×util) → LLM Reranker → Spreading Activation → Inject
13798
```
13899

139-
### Ablation Study: 80 memories × 20 queries × 5 domains
100+
**Ablation study: 80 memories × 20 queries × 5 domains**
140101

141-
| Configuration | P@3 | R@5 | Noise |
142-
|-------------|-----|-----|-------|
143-
| BM25 (baseline) | 0.350 | 0.362 | 65.0% |
144-
| + Domain Weight | 0.383 | 0.446 | 42.0% |
145-
| + Query Expansion | 0.450 | 0.496 | 38.0% |
146-
| + Reranker (Full) | **0.717** | **0.704** | **6.7%** |
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%** |
147107

148108
**2.05× precision improvement, 58% noise reduction.**
149109

150110
---
151111

152-
## Controller Matrix
112+
## Terminal Experience
153113

154-
| Controller | Type | What it does |
155-
|-----------|------|-------------|
156-
| ContextPIDController | PID | Usage → compaction strength |
157-
| BudgetPIDController | PID | Cost rate → token budget |
158-
| FeedbackController | Dual-PID | System state → 13-dim control signal |
159-
| AdaptivePIDTuner | Self-tuning | Auto-tunes PID every 20 turns |
160-
| StateObserver | Kalman ×5 | Hidden state from observables |
161-
| FeedforwardController | Preemptive | Intent → tool config |
162-
| PredictiveController | Forecast | Time-series → proactive actions |
163-
| DecouplingController | RGA | Multi-variable coupling analysis |
164-
| SelfHealingEngine | Recovery | 8 fault types auto-heal |
165-
| StabilityMonitor | Health | 6-dim health scoring |
166-
| CyberneticSupervisor | Aggregate | Global risk view |
167-
| ProgressController | Stall detect | Strategy suggestions |
168-
| MemoryInjectionController | PID | Controls injection rate |
169-
| ModelSelectionController | Router | Risk/cost model selection |
170-
| DomainClassifier | Classifier | 9 domains from file extensions |
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 |
171124

172125
---
173126

174-
## Project Structure
127+
## Slash Commands
175128

176-
```
177-
minicode/
178-
├── agent_loop.py # Main agent loop
179-
├── cybernetic_orchestrator.py # 15-controller facade
180-
├── feedback_controller.py # Dual-PID outer loop
181-
├── context_cybernetics.py # 7-layer context control
182-
├── cost_control.py # Budget PID
183-
├── self_healing_engine.py # Fault detection + recovery
184-
├── memory.py # BM25 search, multi-tier storage
185-
├── memory_pipeline.py # Unified read/write/maintain
186-
├── memory_reranker.py # LLM curation
187-
├── memory_injector.py # PID-controlled injection
188-
├── memory_curator_agent.py # Background optimization
189-
├── domain_classifier.py # File ext → domain
190-
├── agent_reflection.py # Post-task TaskContext
191-
├── progress_controller.py # Stall detection
192-
└── ...
193-
194-
tests/ # 718 tests across 30+ files
195-
docs/
196-
├── memory_theory.md # V(m,t,c) + Lyapunov + info bounds
197-
└── CODE_WIKI.md
198-
```
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 |
199137

200138
---
201139

@@ -204,13 +142,28 @@ docs/
204142
`~/.mini-code/settings.json`:
205143
```json
206144
{
207-
"model": "claude-sonnet-4-20250514",
145+
"model": "deepseek-v4-pro[1m]",
208146
"env": {
147+
"ANTHROPIC_BASE_URL": "https://your-endpoint",
209148
"ANTHROPIC_AUTH_TOKEN": "your-token"
210149
}
211150
}
212151
```
213152

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
158+
159+
---
160+
161+
## Testing
162+
163+
```bash
164+
pytest # 737 passed, 2 skipped
165+
```
166+
214167
---
215168

216169
## MiniCode Ecosystem
@@ -225,7 +178,7 @@ docs/
225178

226179
## Theory
227180

228-
MiniCode's control loop is not heuristic — it's mathematically grounded:
181+
MiniCode's control loop is mathematically grounded:
229182

230183
- **Lyapunov stability**: V̇ = -(kp/m)·e² < 0, proving PID convergence
231184
- **Memory value function**: V(m,t,c) = relevance × freshness × utility

0 commit comments

Comments
 (0)