MOMO CODE

███╗   ███╗ ██████╗ ███╗   ███╗ ██████╗    ██████╗ ██████╗ ██████╗ ███████╗
████╗ ████║██╔═══██╗████╗ ████║██╔═══██╗  ██╔════╝██╔═══██╗██╔══██╗██╔════╝
██╔████╔██║██║   ██║██╔████╔██║██║   ██║  ██║     ██║   ██║██║  ██║█████╗  
██║╚██╔╝██║██║   ██║██║╚██╔╝██║██║   ██║  ██║     ██║   ██║██║  ██║██╔══╝  
██║ ╚═╝ ██║╚██████╔╝██║ ╚═╝ ██║╚██████╔╝  ╚██████╗╚██████╔╝██████╔╝███████╗
╚═╝     ╚═╝ ╚═════╝ ╚═╝     ╚═╝ ╚═════╝    ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝

MOMO CODE 🔥v1.0.0

AI-powered coding agent that evolves with you.
Built on opencode with a unique dual-speed self-evolution system based on Pioneer Agent.

Architecture

Table of Contents

• Features
• Installation
• Quick Start
• Usage
• CLI Commands
• Configuration
• Experience Fast Loop (/evolve)
• Self-Evolution Training (/fine-tune)
• Migrating from Claude Code
• Environment Variables
• Architecture
• Changelog
• License

Features

• 25+ LLM Providers — Deepseek, Zhipu (GLM), Moonshot (Kimi), Claude, GPT-4, Gemini, Doubao, OpenRouter, Groq, Mistral, and more. The \chat command uses OpenAI-compatible protocol only
• Custom Provider — Plug in any OpenAI-compatible API with MOMO_CUSTOM_* env vars
• Model Tiers — Zero-config selection: ultra / standard / lite
• Experience Fast Loop (/evolve) — Second-level prompt injection via KEP protocol. Tactics distilled from success are auto-selected via Thompson sampling
• Self-Evolution Training (/fine-tune) — Hour-level weight improvement via Monte Carlo Graph Search (MCGS) + LoRA
• Self-Refinement (/refine) — Reviews session trajectories and proposes small, evidence-based improvements (tactics/prompt patches) that only take effect after human approval
• Recursive Subagents (/agent) — RLM-style task decomposition: plan → parallel child processes → synthesis, with depth/budget rails
• Graph Engine (/graph) — Long-horizon tasks as a resumable DAG of subagents: LLM-planned dependency graph, parallel execution, retries, and /sim world-agent nodes
• Long-Running Work (/goal + /heartbeat + /daemon) — Persistent goals injected into every session, timed tasks, and a daemon loop for multi-hour autonomy
• Simulation Agent (/sim) — LLM-driven control of a persistent Genesis physics world: the agent writes Python into a long-lived namespace (RLM-style), with skills-as-code loaded from ~/.momo/sim/skills/
• Voice Input (/voice) — Speak your prompt: mic recording (sounddevice) → OpenAI-compatible STT (Whisper/Groq) → coding session
• Claude Code Interop — Seamless migration, inherits .claude/ config, MCP servers, prompts
• Local-first — Your code never leaves your machine. Open source, auditable
• Effect-powered — Built with Effect for composable, type-safe code

Installation

Prerequisites

• macOS or Linux (Windows via WSL)
• Node.js ≥ 20.0.0 — install from https://nodejs.org if you don't have it
• git and curl

Check with:

node -v   # should print v20.x or later
npm -v
git --version
curl --version

Quick install (recommended)

curl -fsSL https://momozi.cc/install | bash

The installer:

1. Clones the repo into `~/.momo/lib/momo-code`
2. Runs `npm install` + `npm run build` (about 30-60 s)
3. Drops a wrapper at `~/.momo/bin/momo`
4. Appends `/.momo/bin` to your PATH in `/.zshrc` or `~/.bashrc`

Open a new terminal (or run `source ~/.zshrc`) and then:

momo --version    # 1.0.0
momo --help

If you see `command not found: momo`, your PATH didn't pick up the change — see INSTALL.md.

From source (manual)

git clone https://github.com/momozi1996/momo-code.git
cd momo-code/packages/opencode
npm install                # installs all deps including TypeScript
npm run build              # compiles TS + fixes ESM imports
node bin/momo --version

From npm

npm package coming in v1.1. Use the Quick install above for v1.0.

Uninstall

# Remove install artifacts
rm -rf ~/.momo

# Remove the PATH line from your shell rc
sed -i.bak '/# momo Code CLI/,+1d' ~/.zshrc    # zsh
sed -i.bak '/# momo Code CLI/,+1d' ~/.bashrc   # bash

1. Set up API key

# Generic key (works with any provider)
export MOMO_API_KEY=your-api-key

# Or provider-specific
export MOMO_ANTHROPIC_API_KEY=sk-ant-...
export MOMO_OPENAI_API_KEY=sk-...

2. Start coding

# Interactive mode
momo

# One-shot task
momo "Refactor auth to use Effect"

# Use a model tier
momo --model ultra "Complex architecture review"
momo --model standard "Fix the login bug"
momo --model lite "Quick code review"

3. First run

On first run, momo creates ~/.momo/:

~/.momo/
├── momo.jsonc          # Config
├── sessions/           # History
├── experience/         # Learned tactics (auto-created)
│   ├── tactics.json
│   └── ledger.jsonl
└── ...

Usage

Model Tiers

CLI Options

momo [options] [prompt]

Options:
  --model, -m <id>       Model ID or tier
  --provider, -p <name>  Provider
  --help                 Show help
  --version              Show version

CLI Commands

Coding Session

momo                     # Show help and banner
momo "prompt"            # One-shot task
momo --model claude-sonnet-4 "task"

Experience Fast Loop (/evolve)

momo /evolve                       # Run evolution with default settings
momo /evolve --mode=explore        # Favor exploration of new tactics
momo /evolve --mode=harden         # Favor proven high-win-rate tactics
momo /evolve --mode=convention-only # Only convention-type tactics
momo /evolve --list                # Show all learned tactics
momo /evolve --inject              # Inject tactics for current task
momo /evolve --solidify            # Apply verdict, update stats

Self-Evolution Training (/fine-tune)

momo /fine-tune              # Diagnose, show training proposal
momo /fine-tune run          # Execute training pipeline
momo /fine-tune run --dry-run # Preview without executing
momo /fine-tune status       # Check training status
momo /fine-tune promote      # Promote candidate to production

Self-Refinement (/refine)

Reviews recent session trajectories and proposes small, reviewable improvements. Nothing is applied without human approval.

momo /refine                 # Generate proposals from recent sessions
momo /refine list            # List proposals
momo /refine show <id>       # Inspect evidence + content
momo /refine approve <id>    # Approve (review gate)
momo /refine apply <id>      # Apply: tactic → draft, patch → prompt file
momo /refine reject <id>     # Reject

Recursive Subagents (/agent)

RLM-style recursion: the model decomposes a complex task, subagents run as child momo processes (parallel where possible), and a synthesizer merges results.

momo /agent "Refactor the provider layer and update all callers and tests"

Rails: MOMO_RLM_MAX_DEPTH (3), MOMO_RLM_BUDGET (8), MOMO_RLM_TIMEOUT_MS (300000).

Graph Engine (/graph)

Turns a long-horizon task into a directed acyclic graph of self-contained subagent tasks. The model plans the DAG (with real dependencies), nodes run as child momo processes — in parallel per topological level, with dependency outputs passed downstream — failed nodes retry, and a final LLM pass synthesizes the report. State persists to ~/.momo/graphs/<id>.json after every batch, so runs survive restarts.

momo /graph run "Design + implement + test a persistence layer"   # plan → execute → synthesize
momo /graph resume <id>        # Continue a long-horizon run where it stopped
momo /graph status <id>        # Node states + outputs
momo /graph list               # Recent runs

Nodes can be marked "kind": "sim" by the planner — those become simulation agents driving the Genesis world via /sim run, so a graph can mix coding subagents with physics experiments.

Rails: MOMO_GRAPH_MAX_NODES (12), MOMO_GRAPH_MAX_RETRIES (2), MOMO_GRAPH_CONCURRENCY (defaults to MOMO_RLM_BUDGET).

Long-Running Work (/goal, /schedule, /heartbeat, /daemon)

momo /goal add "Ship v2.0" "with full test coverage"   # Persistent goal
momo /goal list | log <id> "progress" | done <id>      # Manage goals
momo /schedule add --every=60m "run tests and report"  # Timed task
momo /schedule add --at=07:30 "daily standup summary"  # Daily task
momo /heartbeat            # Run due tasks once
momo /daemon               # Foreground loop (Ctrl+C to stop)

Active goals are injected into every chat session. The daemon is a foreground process by design — background it with nohup/systemd/Task Scheduler. Budget rails: MOMO_DAEMON_MAX_RUNS, MOMO_DAEMON_MAX_HOURS (24).

Simulation Agent (/sim)

An LLM-driven agent that controls a persistent Genesis physics world. Requires Python with genesis-world installed (pip install genesis-world).

momo /sim doctor                      # Check python/genesis/provider setup
momo /sim run "Stack the red cube on the blue cube"   # LLM control loop
momo /sim run "<task>" --steps=40 --viewer            # Budget + live viewer
momo /sim exec "print(42)"            # One-shot world REPL
momo /sim exec --file=scene.py        # Run a script in a fresh world
momo /sim skills                      # List installed world skills
momo /sim eval --tasks=tasks.json     # Batch evaluation (fresh world per episode)

How it works: the CLI spawns a persistent Python process (python/genesis_world/server.py) holding a Genesis scene. Each loop step, the model replies with {"thought": ..., "code": ...}; the code runs in the persistent world namespace (gs, scene, step(n), your variables survive across steps). Skills are plain .py files dropped into ~/.momo/sim/skills/ — auto-loaded into every world. Sim runs are recorded as trajectories, feeding the /refine self-improvement loop.

Env: MOMO_SIM_PYTHON, MOMO_SIM_BACKEND (cpu/gpu), MOMO_SIM_MAX_STEPS (20), MOMO_SIM_SERVER.

Reasoning-Driven Optimization (/optim)

Parameter tuning driven by code understanding + explicit reasoning (inspired by optim-agent). The agent reads your code first and infers the physical/business meaning of every parameter, then proposes configurations with explicit _reasoning and a _note scratchpad fed forward across trials. Invalid proposals degrade to random sampling — a flaky agent can never crash a study.

momo /optim scan src/serve.py --param=threshold:0.05:0.95   # read code → semantic map
momo /optim init quality --target=src/serve.py \
  --param=threshold:0.05:0.95 --param=budget:10:200:int,log \
  --metric=score --direction=max --cmd="python eval.py --threshold {threshold}"
momo /optim semantics quality approve     # human review gate
momo /optim run quality --trials=20       # reasoning-driven loop
momo /optim history quality               # full reasoning trace

Evaluators: --cmd (business command, metric from stdout) or --sim (experiment in the Genesis world, ESTOP-honored). Studies persist under ~/.momo/optim/studies/<name>/ and resume automatically. See docs/optim.md.

Env: MOMO_OPTIM_HISTORY (5), MOMO_OPTIM_N_INIT (2), MOMO_OPTIM_TIMEOUT (300).

Local Server & Dashboard (serve)

A zero-dependency local HTTP server that exposes momo's state as a JSON API + SSE live feed, with a single-file dashboard (no build step).

momo serve                      # http://127.0.0.1:4097 (dashboard at /)
momo serve --port=8080 --token=s3cret

• API: GET /api/sessions|goals|schedule, GET /api/optim/studies[/:name[/trials]], GET /api/sim/observe, SSE GET /api/optim/studies/:name/stream
• Actions: POST /api/optim/studies/:name/run, POST /api/sim/estop|resume, POST /api/chat
• Dashboard tabs: Overview / Sessions / Optim (live reasoning trace + best-so-far chart) / Sim (ESTOP control) / Schedule & Goals / Chat
• Binds loopback by default; non-loopback requires --token (Bearer auth, ?token= fallback for browser EventSource)

Env: MOMO_SERVE_PORT (4097), MOMO_SERVE_HOST (127.0.0.1), MOMO_SERVE_TOKEN.

Voice Input (/voice)

Speak your prompt instead of typing. Requires pip install sounddevice scipy for recording, and an OpenAI-compatible speech-to-text endpoint.

momo /voice                       # Record 5s → transcribe → run as prompt
momo /voice --seconds=10 --lang=zh
momo /voice --file=meeting.mp3    # Transcribe an audio file → run
momo /voice transcribe --file=x.wav  # Print transcription only

export MOMO_STT_API_KEY=sk-...       # falls back to MOMO_OPENAI_API_KEY / MOMO_API_KEY
export MOMO_STT_MODEL=whisper-1      # default
# Groq (fast, generous free tier):
export MOMO_STT_BASE_URL=https://api.groq.com/openai/v1
export MOMO_STT_MODEL=whisper-large-v3

Models

momo models list         # List all models
momo models info <id>    # Show model details
momo models providers    # Show available providers

Configuration

Config File (~/.momo/momo.jsonc)

{
  "$schema": "https://momozi.cc/config.json",
  "model": "standard",
  "provider": "anthropic",
  "inheritClaudeCode": true,
  "evolve": {
    "enabled": true,
    "auto": false,
    "clusterThreshold": 10,
    "budgetUSD": 50
  }
}

Experience Fast Loop (/evolve)

The experience fast loop (KEP — Knowledge Embedding Protocol) is momo's unique second-level learning system. Unlike /fine-tune which updates model weights over hours, /evolve learns and applies knowledge in seconds via prompt injection.

How it works

1. Observe — Extract signals from sessions (test pass/fail, edit accepted/rejected, user corrections)
2. Distill — Convert successful patterns into compact Tactic cards
3. Select — Rank tactics via Thompson sampling (Bayesian explore/exploit)
4. Inject — Insert top-k tactics into the system prompt for the current task
5. Solidify — Apply verdict, update Beta distribution statistics
6. Promote — High-confidence tactics graduate to /fine-tune curriculum

Three KEP Assets

Tactic Statistics (Beta Distribution)

Each tactic tracks a Beta(α, β) distribution:

• α = 1 + wins, β = 1 + losses
• Thompson sampling for exploration/exploitation balance
• UCB1 as alternative selection strategy

Evolution Modes

Storage

Learned tactics are stored in ~/.momo/experience/:

• tactics.jsonl — All tactic records
• ledger.jsonl — Audit log of all operations

Environment Variables

Self-Evolution Training (/fine-tune)

The weight slow loop improves momo's model weights via fine-tuning. This runs at hour-level timescales.

How it works

1. Signal Mining — Extract learning signals from sessions
2. Curriculum Synthesis — Build training data (Gold/Hard-neg/Replay slices)
3. Monte Carlo Graph Search (MCGS) — Explore training pipeline space
4. LoRA Fine-tuning — Train candidate model
5. Ratchet Gate — Ensure monotonic improvement

Commands

momo /fine-tune              # Diagnose, show proposal
momo /fine-tune run          # Execute training
momo /fine-tune run --dry-run # Preview
momo /fine-tune status       # Check status
momo /fine-tune promote      # Promote candidate

Configuration

Migrating from Claude Code

Zero-friction migration:

1. Config inheritance (default ON) — ~/.claude/settings.json auto-merged
2. MCP servers (default ON) — .claude/mcp/ work out of the box
3. Prompts (default ON) — .claude/prompts/ available

# Disable inheritance
export MOMO_CLAUDE_CODE_INHERIT=false
export MOMO_ONLY=1

Environment Variables

Full list: src/env.ts

Architecture

Dual-Speed Evolution

┌─────────────────────────────────────────────────────────┐
│                    momo Code                             │
├─────────────────────┬───────────────────────────────────┤
│  Experience Fast    │  Weight Slow Loop                 │
│  Loop (/evolve)     │  (/fine-tune)                     │
├─────────────────────┼───────────────────────────────────┤
│  Timescale: seconds │  Timescale: hours                 │
│  Mechanism: prompt  │  Mechanism: LoRA fine-tuning      │
│   injection         │                                   │
│  Selection:         │  Search: Monte Carlo Graph        │
│   Thompson/UCB      │   Search (MCGS)                   │
│  Storage: JSONL     │  Training: LoRA                   │
│   (~/.momo/xp/)     │  Gate: Ratchet check              │
│  Bridge: promoted   │  Storage: model registry          │
│   → curriculum      │                                   │
└─────────────────────┴───────────────────────────────────┘

Provider Layer

User Request
    |
    v
resolveModel("standard") → BUILTIN_TIERS.standard
    |                           [claude-sonnet, gpt-4.1, ...]
    v
getCredentials() → MOMO_*_API_KEY env
    |
    v
Provider Factory → baseUrl, headers, timeout
    |
    v
createModel() → LanguageModel adapter
    |
    v
wrapSSE() → Streaming with 8min timeout

Project Structure

packages/opencode/src/
├── provider/       # 19 LLM provider integrations
├── evolve/         # Weight slow loop (/fine-tune) — MCGS
├── experience/     # Fast loop (/evolve) — KEP protocol
│   ├── tactic.ts       # Tactic model + Beta stats
│   ├── selector.ts     # Thompson/UCB selection
│   ├── injector.ts     # Prompt injection
│   ├── gate.ts         # Promotion ratchet
│   ├── bridge.ts       # Two-speed bridge
│   └── ...
├── cli/cmd/        # CLI commands
├── session/        # Prompt routing
├── config/         # Configuration
└── effect/         # Effect utilities

Test Results

• TypeScript: tsc --noEmit — 0 errors
• Runtime: 17/17 tests passed
• CLI verified: /evolve, /fine-tune, models, help

Changelog

v1.0.0 (2026-06-16)

Added:

• Experience fast loop (/evolve) — KEP protocol with Thompson sampling
• Weight slow loop (/fine-tune) — MCGS training pipeline
• CLI command system — /evolve, /fine-tune, models, help
• 53 TypeScript modules across provider/evolve/experience/cli layers
• Dual-speed evolution architecture
• Beta distribution tracking for tactic selection
• Two-speed bridge (promoted tactics → fine-tune curriculum)

Changed:

• Product name: kqq Code → momo Code
• bin/momo: CJS → ESM command router
• package.json: Production-ready exports, files whitelist

License

MIT — see NOTICE for third-party attributions. See USE_RESTRICTIONS.md and SECURITY.md.