metame-cli 1.4.34 → 1.5.1

package/README.md

@@ -24,27 +24,18 @@ No cloud. Your machine, your data.
 curl -fsSL https://raw.githubusercontent.com/Yaron9/MetaMe/main/install.sh | bash
 ```
 
-**Already have Node.js ≥ 22.5:**
-```bash
-npm install -g metame-cli
-metame
-```
-
-**Windows (PowerShell):**
-```powershell
-npm install -g metame-cli
-metame
-```
-
 ---
 
-> ### 🚀 v1.4.33 — 6-Dimension Soul Schema + Nightly Reflection + Auto-Provisioning
+> ### 🚀 v1.5.0 — Dynamic Engine Default + Distill Coupling
 >
-> - **6-dimension soul schema**: cognitive profile upgraded from key-value pairs to a structured 67-field model covering Values, Drive, Cognition Style, Stress & Shadow, Relational, and Identity Narrative — with tier-based lock protection.
-> - **Nightly reflection**: every night, hot-zone facts are distilled into searchable decision logs and lessons learned.
-> - **Memory index**: auto-generated global index of all memory documents for instant retrieval.
-> - **Auto-provisioning**: first run automatically deploys default CLAUDE.md, docs, and `dispatch_to` — zero manual setup.
-> - **Token budget tracking**: daily token usage monitoring with per-category breakdown and 80% warning threshold.
+> - **Dynamic default engine**: auto-detects installed CLI (claude/codex) at startup; pure-codex users work out of the box with zero config.
+> - **`/engine` command**: switch global default engine from mobile (`/engine codex`), with three-layer priority: `project.engine > /engine setting > auto-detect`.
+> - **Engine–distill coupling**: switching engine auto-pairs the distill model (claude→haiku, codex→gpt-5.1-codex-mini) and distill binary.
+> - **Engine-aware distill**: `callDistillModel` now routes through the correct CLI binary and parses codex JSON stream output.
+> - **`/doctor` engine checks**: health check now validates CLI availability against the configured default engine.
+> - **Multi-engine runtime adapter**: daemon supports engine routing by project (`project.engine`) with shared execution flow for Claude/Codex.
+> - **Codex session continuity**: supports `exec`/`resume`, thread id backfill, one-shot resume fallback, and auth/rate-limit error mapping.
+> - **Mentor mode hooks**: pre-flight emotion breaker, context-time mentor prompt, and post-flight reflection debt registration.
 > - **Multi-user ACL**: role-based permissions (admin / member / stranger) with binding protection.
 > - **Windows native support**: cross-platform path handling, Named Pipes IPC, GBK-safe encoding.
 >
@@ -69,9 +60,10 @@ $ metame
 Link Established. What are we building?
 ```
 
-### 2. Full Claude Code From Your Phone
+### 2. Full Claude/Codex Sessions From Your Phone
 
-Your Mac runs a daemon. Your phone sends messages via Telegram or Feishu. Same Claude Code engine — same tools, same files, same session.
+Your Mac runs a daemon. Your phone sends messages via Telegram or Feishu.
+Engine is selected per project (`project.engine: claude|codex`) — same tools, same files, same session continuity.
 
 ```
 You (phone):  Fix the auth bug in api/login.ts
@@ -87,7 +79,7 @@ Start on your laptop, continue on the train. `/stop` to interrupt, `/undo` to ro
 MetaMe's memory system runs automatically in the background — no prompts, no manual saves. Five layers, fully autonomous.
 
 **Layer 1 — Long-term Facts**
-When you go idle, MetaMe runs memory consolidation: extracts key decisions, patterns, and knowledge from your sessions into a persistent facts store. These are semantically recalled on every session start.
+When you go idle, MetaMe runs memory consolidation: extracts key decisions, patterns, and knowledge from your sessions into a persistent facts store. Facts can also carry concept labels (`fact_labels`) for faster cross-domain retrieval.
 
 **Layer 2 — Session Continuity**
 Resuming a conversation after 2+ hours? MetaMe injects a brief summary of what you were working on last time — so you pick up where you left off without re-explaining context.
@@ -96,10 +88,10 @@ Resuming a conversation after 2+ hours? MetaMe injects a brief summary of what y
 Every session gets tagged with topics and intent. This powers future session routing: when you reference "that thing we worked on last week", MetaMe knows where to look.
 
 **Layer 4 — Nightly Reflection**
-Every night at 01:00, MetaMe reviews your most-accessed facts from the past week and distills them into high-level decision logs and operational lessons — searchable documents that grow your personal knowledge base over time.
+Every night at 01:00, MetaMe reviews your most-accessed facts from the past week and distills them into high-level decision logs and operational lessons. Distilled outputs are also written back to `memory.db` as `synthesized_insight`, enabling retrieval in future sessions.
 
 **Layer 5 — Memory Index**
-At 01:30, an auto-generated global index (`INDEX.md`) maps every memory document across all categories. This serves as a fast lookup table so MetaMe always knows where to find relevant context.
+At 01:30, an auto-generated global index (`INDEX.md`) maps every memory document across all categories (including capsules and postmortems). This serves as a fast lookup table so MetaMe always knows where to find relevant context.
 
 ```
 [Background, while you sleep]
@@ -133,9 +125,9 @@ Five tasks shipped out of the box. They are precondition-gated and run only when
 
 ```yaml
 - cognitive-distill   # 4h · has signals? → distill preferences into profile
-- memory-extract      # 4h · scan sessions → extract long-term facts + topic tags
+- memory-extract      # 4h · scan sessions → extract long-term facts + concept labels
 - skill-evolve        # 6h · has signals? → evolve skills from task outcomes
-- nightly-reflect     # 01:00 daily · hot facts → decision logs + lessons learned
+- nightly-reflect     # 01:00 daily · hot facts → decisions/lessons + synthesized facts + capsules
 - memory-index        # 01:30 daily · regenerate global memory index
 ```
 
@@ -195,70 +187,91 @@ Chain skills into multi-step workflows — research → write → publish — fu
 
 ### 5. Skills That Evolve Themselves
 
-MetaMe has a living skill ecosystem. Skills aren't static configs — they grow.
+MetaMe's current skill loop is queue-driven and reviewable (not magic black-box automation).
 
-- **Auto-discovery**: When a task fails or a capability is missing, MetaMe's skill-scout automatically searches for, installs, and verifies new skills.
-- **Learning by watching**: Can't automate a complex browser workflow? Say "我来演示" and MetaMe records your actions, then converts them into a reusable skill.
-- **Post-task evolution**: After every significant task, the skill-evolution-manager reviews what worked and what didn't, then surgically updates the relevant skills with new knowledge.
-- **Composable**: Skills chain together in workflows. A `deep-research` skill feeds into `tech-writing`, which feeds into `wechat-publisher` — each one improving from real usage.
+- **Signal capture**: task outcomes and failures are captured into evolution signals.
+- **Hot/cold evolution**: `skill-evolution` runs on task hot path and heartbeat cold path.
+- **Workflow proposals**: repeated multi-tool patterns are merged into workflow sketches and queued as proposals.
+- **Human approval gate**: review and operate with `/skill-evo list`, `/skill-evo approve <id>`, `/skill-evo done <id>`, `/skill-evo dismiss <id>`.
+- **Skill manager fallback**: when capability is missing, runtime routes to `skill-manager` skill guidance instead of blind guessing.
 
 ```
-Task fails → skill-scout finds a skill → installs → retries → succeeds
-                                                      ↓
-                                      skill-evolution-manager
-                                      updates skill with lessons learned
+task outcome/failure → skill signal buffer
+                     → hot/cold evolution
+                     → proposal queue
+                     → /skill-evo approve|done|dismiss
 ```
 
 ---
 
-## Quick Start
+## Install
 
-```bash
-curl -fsSL https://raw.githubusercontent.com/Yaron9/MetaMe/main/install.sh | bash
-```
+MetaMe is the orchestration layer. Claude Code and Codex are the engines. You install them together.
 
-**Already have Node.js ≥ 22.5:**
-```bash
-npm install -g metame-cli
-metame
-```
+### One-liner by user type
+
+| You use | Install command | First login |
+|---------|----------------|-------------|
+| **Claude Code** | `npm install -g @anthropic-ai/claude-code metame-cli` | `claude` |
+| **Codex** | `npm install -g @openai/codex metame-cli` | `codex login` |
+| **Both** | `npm install -g @anthropic-ai/claude-code @openai/codex metame-cli` | `claude` + `codex login` |
+| **Claude plugin** (no npm) | `claude plugin install github:Yaron9/MetaMe/plugin` | `claude` |
 
-> **First run auto-provisioning:** MetaMe automatically deploys a default `CLAUDE.md`, documentation files, and the `dispatch_to` tool to `~/.metame/`. No manual setup needed.
+> **No Node.js?** Run `curl -fsSL https://raw.githubusercontent.com/Yaron9/MetaMe/main/install.sh | bash` — it installs Node + MetaMe for you.
+>
+> **Windows?** Use PowerShell/CMD natively. WSL has proxy and path issues.
+
+### Setup (3 minutes)
 
-**Setup guide (3 minutes):**
+| Step | What to do |
+|------|-----------|
+| 1. Launch | `metame` (Claude) or `metame codex` (Codex) |
+| 2. Genesis Interview | Just chat — MetaMe auto-starts a deep soul interview on first run → builds `~/.claude_profile.yaml` |
+| 3. Connect phone | Say "help me set up mobile access" → interactive Telegram/Feishu bot wizard |
+| 4. Start daemon | `metame start` → background daemon launches, bot goes online |
+| 5. Register with OS | macOS: `metame daemon install-launchd` · Windows: `metame daemon install-task-scheduler` |
 
-| Step | What to do | What happens |
-|------|-----------|-------------|
-| 1. Log in to Claude | Run `claude` and complete the login (Anthropic account or API key) | Claude Code is ready to use |
-| 2. Launch MetaMe | Run `metame` | Opens a Claude session with MetaMe loaded |
-| 3. Genesis Interview | Just chat — MetaMe will automatically start a deep soul interview on first run | Builds `~/.claude_profile.yaml` (6-dimension cognitive profile) |
-| 4. Connect phone | Say "help me set up mobile access" or "connect my phone" | Interactive wizard for Telegram/Feishu bot setup → `~/.metame/daemon.yaml` |
-| 5. Start daemon | `metame start` | Background daemon launches, bot goes online |
-| 6. Register with system | macOS: `metame daemon install-launchd` · Windows: `metame daemon install-task-scheduler` · Linux: see below | Always-on, crash recovery |
+> **First time?** Just run `metame` and talk naturally. Everything is conversational.
 
-> **First time?** Just run `metame` and talk naturally. The interview and setup are conversational — no commands to memorize.
+### Create your first Agent
+
+1. In any existing group, say: `Create an agent, directory ~/xxx, responsible for xxx`
+2. Bot replies: Agent created — **send `/activate` in your new group to bind it**
+3. Create a new group, add the bot, send `/activate` → binding complete
+
+> Want more Agents? Repeat the flow. Each group = independent AI workspace.
+
+### Update / Uninstall
 
-**Update MetaMe:**
 ```bash
+# Update
 npm install -g metame-cli
-```
 
-> **What does system registration mean?**
-> Once registered, MetaMe runs in the background automatically — screen locked, lid closed, woken from sleep — as long as the machine is on. Scheduled tasks fire on time. No terminal window needed.
+# Uninstall
+metame stop && npm uninstall -g metame-cli
 
-**Windows — register with Task Scheduler:**
-
-```powershell
-metame daemon install-task-scheduler
+# Optional: remove data
+rm -rf ~/.metame ~/.claude_profile.yaml
 ```
 
-> The daemon auto-starts at login. Remove with: `schtasks /delete /tn "MetaMe-Daemon" /f`
+Optional service cleanup:
+- macOS: `launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/com.metame.daemon.plist && rm -f ~/Library/LaunchAgents/com.metame.daemon.plist`
+- Windows: `schtasks /delete /tn "MetaMe-Daemon" /f`
+- Linux/WSL: `systemctl --user disable --now metame && rm -f ~/.config/systemd/user/metame.service`
+
+### Platform notes
 
-> **Windows notes:** Emoji display uses ASCII fallback (`[OK]`, `[FAIL]`) for GBK terminal compatibility. Named Pipes replace Unix sockets for IPC. `/mac` commands are not available.
+<details>
+<summary>Windows</summary>
 
-> **Windows users: install natively, not via WSL.** WSL often fails to inherit the host's network proxy (causing npm install and Claude API timeouts), has path mapping issues, and process management doesn't interoperate. `npm install -g metame-cli` directly in PowerShell/CMD is the most reliable approach.
+- Emoji auto-degrades to ASCII (`[OK]`, `[FAIL]`) for GBK compatibility
+- IPC uses Named Pipes instead of Unix sockets
+- `/mac` commands are not available
+- **Install natively in PowerShell/CMD, not via WSL**
+</details>
 
-**WSL2 / Linux — register with systemd:**
+<details>
+<summary>WSL2 / Linux — systemd registration</summary>
 
 ```bash
 cat > ~/.config/systemd/user/metame.service << 'EOF'
@@ -279,17 +292,15 @@ systemctl --user enable metame
 systemctl --user start metame
 ```
 
-> WSL2 requires systemd enabled first: add `[boot]\nsystemd=true` to `/etc/wsl.conf`, then restart WSL.
-
-> **WSL limitation:** `/mac` commands (macOS AppleScript/JXA automation) are not available.
+> Requires systemd enabled: add `[boot]\nsystemd=true` to `/etc/wsl.conf`, then restart WSL.
 
-**Create your first Agent:**
+</details>
 
-1. In any existing group, say: `Create an agent, directory ~/xxx, responsible for xxx`
-2. Bot replies: ✅ Agent created — **send `/activate` in your new group to bind it**
-3. Create a new group, add the bot, send `/activate` → binding complete
+### FAQ
 
-> Want more Agents? Repeat: create in any group → new target group → `/activate`. Each group = independent AI workspace.
+- **Does plugin mode support daemon + phone?** Yes. Plugin auto-starts daemon when `daemon.yaml` exists.
+- **Does MetaMe bundle Claude or Codex?** No. `metame-cli` is engine-agnostic — you install engine(s) separately.
+- **One engine only?** Works fine. `/doctor` marks the missing engine as warning, not failure.
 
 ---
 
@@ -298,9 +309,9 @@ systemctl --user start metame
 | Capability | What It Does |
 |-----------|-------------|
 | **Cognitive Profile** | 6-dimension soul schema (Values, Drive, Cognition Style, Stress & Shadow, Relational, Identity Narrative). 67 fields, tier-locked, 800-token budget. First-time Genesis Interview builds your profile from scratch. |
-| **Layered Memory** | Five-tier memory: long-term facts (semantic recall), session summaries (continuity bridge), session index (topic tags), nightly reflection (decision/lesson distillation), memory index (global lookup). All automatic. |
-| **Mobile Bridge** | Full Claude Code via Telegram/Feishu. Stateful sessions, file transfer both ways, real-time streaming status. |
-| **Skill Evolution** | Self-healing skill system. Auto-discovers missing skills, learns from browser recordings, evolves after every task. Skills get smarter over time. |
+| **Layered Memory** | Five-tier memory: long-term facts (+ concept labels), session summaries (continuity bridge), session index (topic tags), nightly reflection (distill + write-back), memory index (global lookup). All automatic. |
+| **Mobile Bridge** | Full Claude/Codex via Telegram/Feishu. Stateful sessions, file transfer both ways, real-time streaming status. |
+| **Skill Evolution** | Queue-driven skill evolution: captures task signals, generates workflow proposals, and supports explicit approval/resolve via `/skill-evo` commands. |
 | **Token Budget** | Daily token usage tracking with per-category breakdown. Configurable daily limit, automatic 80% warning threshold, usage history with rollover. |
 | **Auto-Provisioning** | First run deploys default CLAUDE.md, documentation, and `dispatch_to` to `~/.metame/`. Subsequent runs sync scripts without overwriting user config. |
 | **Heartbeat System** | Three-layer programmable nervous system. Layer 0 kernel always-on (zero config). Layer 1 system evolution built-in (5 tasks: distill + memory + skills + nightly reflection + memory index). Layer 2 your custom scheduled tasks with `require_idle`, `precondition`, `notify`, workflows. |
@@ -309,6 +320,7 @@ systemctl --user start metame
 | **Cross-Platform** | Native support for macOS and Windows. Platform abstraction layer handles spawn, IPC, process management, and terminal encoding automatically. |
 | **Provider Relay** | Route through any Anthropic-compatible API. Use GPT-4, DeepSeek, Gemini — zero config file mutation. |
 | **Metacognition** | Detects behavioral patterns (decision style, comfort zones, goal drift) and injects mirror observations. Zero extra API cost. |
+| **Mentor Mode** | `/mentor on|off|level|status` controls friction mode. Emotion breaker, zone-adaptive mentor prompts, and reflection debt run as optional hooks. |
 | **Multi-User ACL** | Role-based permission system (admin / member / stranger). Share bots with teammates safely. Dynamic user management via `/user` commands with hot-reload config. |
 | **Team Task** | Multi-agent task board for cross-agent collaboration. Agents can create, assign, and track tasks across workspaces. N-agent session scoping for parallel team workflows. |
 | **Emergency Tools** | `/doctor` diagnostics, `/mac` macOS control helpers, `/sh` raw shell, `/fix` config restore, `/undo` git-based rollback. |
@@ -417,6 +429,9 @@ All agents share your cognitive profile (`~/.claude_profile.yaml`) — they all
 | `/undo <hash>` | Roll back to a specific git checkpoint |
 | `/list` | Browse & download project files |
 | `/model` | Switch model (sonnet/opus/haiku) |
+| `/engine` | Show/switch default engine (`claude`/`codex`) |
+| `/distill-model` | Show/update background distill model (default: `haiku`) |
+| `/mentor` | Mentor mode control: on/off/level/status |
 | `/activate` | Activate and bind the most recently created pending agent in a new group |
 | `/agent bind <name> [dir]` | Manually register group as dedicated agent |
 | `/mac` | macOS control helper: permissions check/open + AppleScript/JXA execution |
@@ -434,6 +449,34 @@ All agents share your cognitive profile (`~/.claude_profile.yaml`) — they all
 | `/teamtask <task_id>` | View task detail |
 | `/teamtask resume <task_id>` | Resume a task |
 
+## Mentor Mode (Why + How)
+
+Mentor Mode is designed for users who want MetaMe to actively improve decision quality, not just execute commands.
+
+- `/mentor on` — enable mentor hooks
+- `/mentor off` — disable mentor hooks
+- `/mentor level <0-10>` — set friction level
+- `/mentor status` — show current mode/level
+
+Runtime behavior:
+- Pre-flight emotion breaker (cooldown-aware)
+- Context-time mentor prompts (zone-aware: comfort/stretch/panic)
+- Reflection debt registration on heavy code outputs (intense mode)
+
+Level mapping:
+- `0-3` → `gentle`
+- `4-7` → `active`
+- `8-10` → `intense`
+
+## Hook Optimizations (Default On)
+
+MetaMe installs and maintains two core Claude hooks automatically on launch:
+
+- `UserPromptSubmit` hook (`scripts/signal-capture.js`): captures high-signal preference/task traces with layered filtering.
+- `Stop` hook (`scripts/hooks/stop-session-capture.js`): records session-end/tool-failure signals with watermark protection.
+
+If hook installation fails, MetaMe logs and continues the session (non-blocking fallback).
+
 ## How It Works
 
 ```
@@ -442,8 +485,8 @@ All agents share your cognitive profile (`~/.claude_profile.yaml`) — they all
 └─────────────┘                           │   (your machine, 24/7)       │
                                           │                              │
                                           │   ┌──────────────┐           │
-                                          │   │ Claude Code   │           │
-                                          │   │ (same engine) │           │
+                                          │   │ Claude/Codex  │           │
+                                          │   │ (same runtime)│           │
                                           │   └──────────────┘           │
                                           │                              │
                                           │   ~/.claude_profile          │
@@ -463,12 +506,19 @@ All agents share your cognitive profile (`~/.claude_profile.yaml`) — they all
 
 - **Profile** (`~/.claude_profile.yaml`): 6-dimension soul schema. Injected into every Claude session via `CLAUDE.md`.
 - **Daemon**: Background process handling Telegram/Feishu messages, heartbeat tasks, Unix socket dispatch, and idle/sleep transitions.
-- **Distillation**: Heartbeat task (4h, signal-gated) that updates your cognitive profile.
-- **Memory Extract**: Heartbeat task (4h, idle-gated) that extracts long-term facts and session topic tags.
-- **Nightly Reflection**: Daily at 01:00. Distills hot-zone facts into decision logs and operational lessons.
+- **Runtime Adapter** (`scripts/daemon-engine-runtime.js`): normalizes engine args/env/event parsing across Claude/Codex.
+- **Distillation**: Heartbeat task (4h, signal-gated) that updates your cognitive profile, merges competence signals, and emits postmortems for significant sessions.
+- **Memory Extract**: Heartbeat task (4h, idle-gated) that extracts long-term facts, then writes concept labels (`fact_labels`) linked by fact id.
+- **Nightly Reflection**: Daily at 01:00. Distills hot-zone facts into decision logs/lessons, writes back `synthesized_insight`, and generates knowledge capsules.
 - **Memory Index**: Daily at 01:30. Regenerates the global memory index for fast retrieval.
 - **Session Summarize**: Generates a brief summary for idle sessions. Injected as context when resuming after a 2h+ gap.
 
+## Scripts Docs Pointer Map
+
+Use `scripts/docs/pointer-map.md` as the source-of-truth map for script entry points and Step 1-4 landing zones (`session-analytics` / `mentor-engine` / `daemon-claude-engine` / `distill` / `memory-extract` / `memory-nightly-reflect`).
+
+For day-2 operations and troubleshooting (engine routing, codex login/rate-limit, compact boundary), use `scripts/docs/maintenance-manual.md`.
+
 ## Security
 
 - All data stays on your machine. No cloud, no telemetry.
@@ -488,24 +538,16 @@ All agents share your cognitive profile (`~/.claude_profile.yaml`) — they all
 | Cognitive profile injection | ~800 tokens/session (0.4% of 200k context) |
 | Dispatch latency (Unix socket) | <100ms |
 | Memory consolidation (per session) | ~1,500–2,000 tokens input + ~50–300 tokens output (Haiku) |
-| Session summary (per session) | ~400–900 tokens input + ≤250 tokens output (Haiku) |
+| Session summary (per session) | ~400–900 tokens input + ≤250 tokens output (distill model configurable) |
 | Mobile commands (`/stop`, `/list`, `/undo`) | 0 tokens |
 
-> Both memory consolidation and session summarization run in the background via Haiku (`--model haiku`). Input is capped by code: skeleton text ≤ 3,000 chars, summary output ≤ 500 chars. Neither runs per-message — memory consolidation follows heartbeat schedule with idle/precondition guards, and summaries trigger once per idle session on sleep-mode transitions.
+> Memory consolidation and session summarization run in the background via the configured distill model (`/distill-model`, default `haiku`). Input is capped by code: skeleton text ≤ 3,000 chars, summary output ≤ 500 chars. Neither runs per-message — memory consolidation follows heartbeat schedule with idle/precondition guards, and summaries trigger once per idle session on sleep-mode transitions.
 
 ## Plugin
 
-Install directly into Claude Code without npm:
-
-```bash
-claude plugin install github:Yaron9/MetaMe/plugin
-```
-
-Includes: cognitive profile injection, daemon (Telegram/Feishu), heartbeat tasks, layered memory, all mobile commands, slash commands (`/metame:evolve`, `/metame:daemon`, `/metame:refresh`, etc.).
-
-**One key difference from the npm CLI:** the plugin daemon starts when you open Claude Code and stops when you close it. It does not run 24/7 in the background. For always-on mobile access (receiving messages while Claude Code is closed), use the npm CLI with `metame daemon install-launchd`.
+Install directly into Claude Code without npm: `claude plugin install github:Yaron9/MetaMe/plugin`
 
-Use the plugin if you prefer not to install a global npm package and only need mobile access while Claude Code is open. Use the npm CLI (`metame-cli`) for 24/7 daemon, the `metame` command, and first-run interview.
+All features included. Plugin auto-starts daemon on `SessionStart` (if `daemon.yaml` exists). Does **not** auto-register OS service — after reboot, open Claude once or start daemon manually.
 
 ## Contributing