@alan512/experienceengine 0.1.3 → 0.2.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "experienceengine",
   "description": "Context-aware experience intervention controller for Claude Code.",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "author": {
     "name": "ExperienceEngine"
   },

package/README.md

@@ -1,39 +1,95 @@
 # ExperienceEngine
 
-[简体中文版 README](./README.zh-CN.md)
+English | [简体中文](./README.zh-CN.md)
 
-ExperienceEngine is a local experience-intervention layer for coding agents.
+ExperienceEngine is a governance layer for coding agents that reuses real execution experience without turning memory into noise. It injects short task-specific guidance only when relevant, then tracks whether that intervention helped or harmed.
 
-It learns short, task-specific guidance from real coding work, injects that guidance into later similar tasks, and records whether the intervention helped or harmed the outcome.
+**Memory does addition. ExperienceEngine does governance.**
+
+Supported hosts today: `OpenClaw`, `Claude Code`, `Codex`
+
+## 10-Second Example
+
+Without ExperienceEngine:
+- the agent repeats the same SQLite migration mistake in a similar repo
+- it opens the DB before running the migration, then wastes turns retrying the wrong path
+
+With ExperienceEngine:
+- before tool use, it injects one short constraint like: `Run the migration before opening the DB connection`
+- the host agent avoids the same failed path instead of rediscovering it from scratch
+- after the task, ExperienceEngine usually updates that guidance automatically from the real outcome
+- if the guidance later starts harming similar tasks, ExperienceEngine can cool, quarantine, or retire it
+
+Task flow: `task signals -> distilled experience -> retrieval -> short intervention -> feedback -> governance`
+
+<details>
+<summary>Example host transcript</summary>
+
+User: Fix the SQLite startup failure in this repo.
+
+Host agent: ExperienceEngine found a prior successful fix pattern in this repo: `Run the migration before opening the DB connection.` I’ll apply the migration first, then retry startup.
+
+User: Why did that ExperienceEngine hint match?
+
+Host agent: It matched a prior task in this repo with the same SQLite startup pattern and a successful migration-first fix.
+
+User: So ExperienceEngine is trying to keep me off the same bad path?
+
+Host agent: Yes. It reused a repo-local success pattern before the next tool call, and it will usually score the outcome automatically after this run.
+
+</details>
+
+![Example `ee inspect --last --verbose` output](./docs/assets/readme/inspect-last-example.svg)
+
+## Quick Start
+
+Fastest host-specific install paths:
 
-Supported hosts today:
 - `OpenClaw`
-- `Claude Code`
+  - `openclaw plugins install @alan512/experienceengine`
+  - `openclaw gateway restart`
+  - `ee init`
 - `Codex`
+  - `ee install codex`
+  - `ee init`
+- `Claude Code`
+  - `/plugin marketplace add https://github.com/Alan-512/ExperienceEngine.git`
+  - `/plugin install experienceengine@experienceengine`
+  - `ee init`
 
-OpenClaw compatibility:
-- requires a working OpenClaw installation with native plugin support
-- the documented OpenClaw path assumes `openclaw plugins install` and `openclaw gateway restart` are available
-- Node.js `>=20` is required for the published package
+`ee init` initializes shared ExperienceEngine state after the host-specific installation step.
 
-## The Problem It Solves
+Need detailed per-host setup instructions, fallback paths, readiness states, or operator workflows? Jump to [Full Setup and Operator Details](#full-setup-and-operator-details).
 
-Coding agents repeat the same mistakes for a simple reason: most sessions do not accumulate reusable execution experience in a governed way.
+## Who It's For
 
-The usual failure modes are:
-- a fix worked yesterday, but the next similar session starts from zero again
-- memory systems keep adding facts and preferences, but they rarely retire low-value guidance
-- as recalled memory grows, context gets heavier and the agent's attention gets diluted
+Use ExperienceEngine if:
+- you use coding agents repeatedly in similar repos or workflows
+- you want **small, intervention-focused guidance**, not general memory recall
+- you want to know whether reused experience actually **helped or harmed**
+- you want stale guidance to cool down or retire instead of accumulating forever
 
-ExperienceEngine is designed for that gap. It does not try to remember everything. It tries to decide:
-- when prior experience should intervene
-- which `strategy` or `warning` should be injected
-- whether that intervention actually helped
-- whether the experience should stay active, cool down, or retire
+Do not use ExperienceEngine if:
+- you only want a personal note-taking memory
+- you want generic document RAG
+- you rarely repeat workflows
+- you want the system to remember everything by default
 
-**Memory does addition. ExperienceEngine does governance.**
+## Host Support Matrix
+
+| Host | Install path | Routine interaction | Maturity |
+|---|---|---|---|
+| `OpenClaw` | native plugin install | host-native | most complete today |
+| `Claude Code` | marketplace plugin, with `ee install claude-code` fallback | MCP + plugin hooks | supported |
+| `Codex` | `ee install codex`, with native MCP fallback | MCP-native | supported |
+
+## Why It Exists
 
-## ExperienceEngine vs Memory
+Coding agents often repeat the same mistakes because prior execution experience is not reused in a governed way.
+
+ExperienceEngine is designed for intervention governance, not general memory accumulation.
+
+## Why Not Memory / RAG
 
 | Question | Memory Systems | ExperienceEngine |
 |---|---|---|
@@ -42,51 +98,99 @@ ExperienceEngine is designed for that gap. It does not try to remember everythin
 | Track whether a recalled item helped or harmed | Usually no | Yes, per intervention |
 | Retire stale or harmful guidance automatically | Usually no | Yes, cooling and retirement are built in |
 | Keep context small and intervention-focused | Not the main goal | Yes, it injects short task-specific guidance |
+| Generic document lookup | Common fit | Not the primary job |
+
+## Why It Is Not Just Another Memory Layer
+
+ExperienceEngine is not trying to remember more things than the host. Its core job is to govern whether learned guidance should keep affecting future tasks.
+
+- most learning work happens after the task, so the current task does not need to wait for the full experience pipeline
+- each learned node moves through a lifecycle such as `candidate`, `active`, `cooling`, and `retired`
+- delivery is governed separately from storage, so harmful guidance can be cooled, quarantined, or removed from normal live injection
+- posttask review can revise whether a hint actually helped, harmed, or stayed uncertain
+- delivery decisions are persisted even when no hint is shipped, so skipped turns can still be explained later
+- high-match same-repo experience can move out of conservative delivery after successful reuse, while cross-repo reuse stays cautious unless there is stronger evidence
+- the product goal is production-safe reuse, not maximum recall
 
 ## Where It Sits In The Agent Loop
 
-```text
-User task
-  -> before_prompt_build: retrieve and inject matching experience
-  -> agent reasoning + tools: capture failures, retries, corrections, and outcomes
-  -> task finalization: distill new candidates into reusable experience
-  -> helped / harmed feedback: promote, cool, or retire nodes
-```
+At a high level, ExperienceEngine operates around the agent loop like this:
+
+- `User task`
+- `before_prompt_build`: retrieve and inject matching experience
+- `agent reasoning + tools`: capture failures, retries, corrections, and outcomes
+- `task finalization`: distill new candidates into reusable experience
+- `helped / harmed feedback`: promote, cool, or retire nodes
 
 ExperienceEngine works at the context layer. It does not modify the host model's weights.
 
 ## Experience Lifecycle
 
-```text
-task signals
-  -> candidate
-  -> active
-  -> cooling
-  -> retired
-```
+`task signals -> candidate -> active -> cooling -> retired`
 
 Each node moves through that lifecycle using real task outcomes, not just time-based cleanup. Helpful experience gets reinforced; harmful experience gets cooled or retired.
 
-## What You Can Use Today
+## What You Can Do Today
+
+- reuse short guidance from similar coding work
+- review why a hint matched or why nothing injected
+- let ExperienceEngine automatically reinforce, cool, quarantine, or retire guidance from real task outcomes
+- override the last intervention as helpful or harmful when the automatic judgment needs correction
+- inspect active, cooling, quarantined, and retired experience
+- run across `OpenClaw`, `Claude Code`, and `Codex`
+
+### Under The Hood
 
-Already available in the repository:
-- host integration for `OpenClaw`, `Claude Code`, and `Codex`
 - MCP-native interaction surfaces plus CLI/operator fallback
-- API-first semantic retrieval with graceful fallback:
-  - OpenAI `text-embedding-3-small`
-  - Gemini `gemini-embedding-001`
-  - Jina `jina-embeddings-v3`
-  - managed local embedding fallback
-  - legacy hash-based fallback
+- semantic retrieval with API and local fallback
+- deterministic match scorecards that separate same-repo confidence from broader cross-repo reuse
 - host-agent driven inspection and feedback, with CLI fallback commands such as `ee inspect --last`, `ee helped`, and `ee harmed`
 
 For a more detailed explanation of what ExperienceEngine records and how an experience node is structured, see:
 
 - [Experience Model Overview](./docs/development/experience-model.md)
 
-## Quick Start
+## Current Status
+
+- Stable: core experience lifecycle, inspect/helped/harmed loop, host integrations, CLI/operator fallback
+- Good path today: `OpenClaw` native plugin install
+- Evolving: retrieval tuning, provider strategy, advanced host UX
+- If you want the smoothest first experience today, start with `OpenClaw`.
+
+## What First Success Looks Like
+
+After installation and initialization, the first visible signs of value are:
+
+- a repeated task avoids a previously known bad path instead of rediscovering it
+- ExperienceEngine injects only a short repo-relevant constraint instead of bloating the prompt
+- the host can explain why that hint matched or why nothing was injected
+- the task outcome usually updates future delivery automatically
+- `ee inspect --last` shows the recent intervention and related node state
+
+## Prerequisites
+
+Before installing an adapter, make sure the host CLI already works on this machine:
+
+- `openclaw` for the OpenClaw plugin/runtime integration
+- `claude` for the Claude Code adapter
+- `codex` for the Codex adapter
 
-ExperienceEngine no longer treats the `ee` CLI as the first-install entrypoint.
+**ExperienceEngine does not install those host CLIs for you.** It wires itself into an already working host environment.
+
+OpenClaw notes:
+- requires a working OpenClaw installation with native plugin support
+- the documented OpenClaw path assumes `openclaw plugins install` and `openclaw gateway restart` are available
+- OpenClaw now uses the shared background learning loop by default
+- OpenClaw still keeps async hybrid posttask review disabled by default; `ee status` and `ee doctor openclaw` show that explicitly
+
+General package requirement:
+- Node.js `>=20` is required for the published package
+
+## Full Setup and Operator Details
+
+### Full Setup by Host
+
+ExperienceEngine no longer treats the `ee` CLI as the universal first-install entrypoint across all hosts.
 
 Install ExperienceEngine through the host setup flow for the host you want to use:
 
@@ -99,7 +203,7 @@ Install ExperienceEngine through the host setup flow for the host you want to us
   - EE-managed Codex setup:
     - `ee install codex`
   - native/manual fallback:
-    - `codex mcp add experienceengine --env EXPERIENCE_ENGINE_HOME=$HOME/.experienceengine -- npx -y @alan512/experienceengine codex-mcp-server`
+    - see the advanced example below if you need direct MCP wiring
   - after either path, start a new Codex session in the repo so the MCP wiring and `AGENTS.md` instruction block are picked up
 - `Claude Code`
   - host-native marketplace install:
@@ -110,49 +214,62 @@ Install ExperienceEngine through the host setup flow for the host you want to us
   - `ee install claude-code` remains the operator fallback when you need direct hooks + MCP wiring outside the marketplace flow
   - after installation, start a new Claude Code session so the plugin hooks and bundled MCP config are loaded
 
-Across all three hosts, the intended product journey is the same:
+Across all three hosts, the intended flow is the same:
 
 1. install ExperienceEngine through the host-specific setup path
 2. initialize shared ExperienceEngine state with `ee init`
 3. restart or open a fresh host session until the repo is `Ready`
-4. keep routine review and feedback inside the host agent when the host supports it cleanly
+4. keep routine inspection and feedback inside the host when supported
 5. use `ee` as the operator fallback for validation, repair, and deeper inspection
 
-The host-specific differences are real, but they sit underneath one shared model:
+### Shared Initialization
 
-- installation mechanics differ by host
-- routine interaction should feel similar wherever the host supports it
-- CLI remains the explicit fallback and operator surface
+`ee init` is shared-product initialization, not host-specific setup.
 
-ExperienceEngine now treats onboarding and value as two separate layers:
+- Run it once after your first host installation to configure:
+  - distillation provider/model/auth
+  - embedding mode/provider
+  - any shared provider secrets
+- Later host installations reuse the same ExperienceEngine home, settings, and shared secrets.
 
-- `Setup state`
-  - `Installed`
-  - `Initialized`
-  - `Ready`
-- `Value state`
-  - `Warming up`
-  - `First value reached`
+After installation, ExperienceEngine should orient the user toward the next setup step:
 
-These are not one linear ladder. A repo can already be `Ready` while still `Warming up`.
+- if host wiring is in place, the product is at least `Installed`
+- after shared state is configured with `ee init`, the product is `Initialized`
+- once the host or repo has reloaded correctly for real work, the product is `Ready`
+
+Minimal shared initialization example:
+
+1. `ee init distillation --provider openai --model gpt-4.1-mini --auth-mode api_key`
+2. `ee init secret OPENAI_API_KEY <your-api-key>`
+3. `ee init embedding --mode api --api-provider openai --model text-embedding-3-small`
+4. `ee init show`
+
+If you prefer Gemini or Jina for embeddings, use the same `ee init embedding` flow with the matching provider and model.
+
+### Routine Use vs Operator Use
+
+For routine use, ask the host agent naturally for ExperienceEngine state first. Automatic outcome attribution is the default path; manual feedback is mainly there when you want to correct that judgment.
 
-For routine use, ask the host agent naturally for ExperienceEngine state or feedback actions, for example:
+Examples:
 
 - "What did ExperienceEngine just inject?"
 - "Why did that ExperienceEngine hint match?"
+- "Why didn't ExperienceEngine inject anything just now?"
 - "Mark the last ExperienceEngine intervention as helpful or harmful."
 
-OpenClaw now also supports these additional phase-2 routine questions in-session:
+In normal use, you should not need to manually score every intervention. ExperienceEngine is designed to learn from real task outcomes automatically, while still letting you override the result when the automatic judgment is wrong.
+
+OpenClaw also supports these additional readiness and recent-silence questions in-session:
 
 - "Is ExperienceEngine ready here?"
 - "Is ExperienceEngine still warming up in this repo?"
 - "Why didn't ExperienceEngine inject anything just now?"
 
 For `OpenClaw`, `Codex`, and `Claude Code`, the common review-and-feedback follow-ups should stay in the host session first.
-For the extra readiness, warm-up, and recent-silence questions above, only `OpenClaw` supports the in-session phase-2 path today.
 Use CLI fallback whenever the host-side path is unavailable or you need explicit operator control.
 
-Use the `ee` CLI only when you need explicit operator validation or troubleshooting:
+Use the `ee` CLI when you need explicit operator validation or troubleshooting:
 
 ```bash
 ee init
@@ -161,76 +278,36 @@ ee status
 ee maintenance embedding-smoke
 ```
 
-`ee init` is shared-product initialization, not host-specific setup.
+### Readiness and Value States
 
-- Run it once after your first host installation to configure:
-  - distillation provider/model/auth
-  - embedding mode/provider
-  - any shared provider secrets
-- Later host installations reuse the same ExperienceEngine home, settings, and shared secrets.
+ExperienceEngine treats onboarding and value as two separate layers:
 
-After installation, ExperienceEngine should orient the user toward the next setup step:
+- `Setup state`
+  - `Installed`
+  - `Initialized`
+  - `Ready`
+- `Value state`
+  - `Warming up`
+  - `First value reached`
 
-- if host wiring is in place, the product is at least `Installed`
-- after shared state is configured with `ee init`, the product is `Initialized`
-- once the host or repo has reloaded correctly for real work, the product is `Ready`
+These are not one linear ladder. A repo can already be `Ready` while still `Warming up`.
 
 `First value reached` should only be claimed after visible output from a real task run. A generic warm-up message or static onboarding text does not count as first value.
 
-Minimal shared initialization example:
-
-```bash
-ee init distillation --provider openai --model gpt-4.1-mini --auth-mode api_key
-ee init secret OPENAI_API_KEY <your-api-key>
-ee init embedding --mode api --api-provider openai --model text-embedding-3-small
-ee init show
-```
-
-If you prefer Gemini or Jina for embeddings, use the same `ee init embedding` flow with the matching provider and model.
-
-## Prerequisites
-
-Before installing an adapter, make sure the host CLI already works on this machine:
-
-- `openclaw` for the OpenClaw plugin/runtime integration
-- `claude` for the Claude Code adapter
-- `codex` for the Codex adapter
-
-ExperienceEngine does not install those host CLIs for you. It wires itself into an already working host environment.
-
 ## Installation Model
 
-ExperienceEngine now treats installation and operations as separate concerns:
-
-- installation belongs to the host
-- validation and maintenance belong to `ee`
-
-That means the user-facing concepts stay stable even though the host integrations differ:
-
-- `OpenClaw`
-  - installs through plugin/runtime integration
-  - keeps stronger CLI/operator support today
-- `Claude Code`
-  - installs through Claude-native marketplace/plugin assets
-  - prefers MCP-native routine interaction inside the host session
-- `Codex`
-  - uses the shared ExperienceEngine MCP server
-  - prefers MCP-native routine interaction inside the host session
-
-Once installation is complete, the host agent remains the primary interaction surface.
+ExperienceEngine separates:
+- host installation
+- shared initialization
+- operator workflows
 
-`ee` is the operational surface for:
+The host remains the primary interaction surface.
+`ee` remains the explicit operator surface for setup, validation, repair, status, and maintenance.
+For Codex, `ee status` and `ee doctor codex` also report whether the `ee` CLI fallback is available on `PATH`. Codex MCP wiring can still work when the CLI fallback is missing, but commands such as `ee inspect --last` need either a PATH-visible `ee` binary or an explicit package invocation.
 
-- shared provider/model initialization
-- health checks
-- repair guidance
-- status inspection
-- learning and intervention feedback
+## Advanced Per-Host Commands (Operator / Development Only)
 
-`ee status` is the daily product-progress view.
-`ee doctor <host>` is the explicit validation and troubleshooting view.
-
-## Advanced Per-Host Commands
+Most users can ignore this section and use the host-specific setup flow above.
 
 If you need explicit per-host control as an operator or while developing the product, these commands still exist:
 
@@ -240,6 +317,15 @@ ee install claude-code
 ee install codex
 ```
 
+<details>
+<summary>Native/manual Codex MCP fallback example</summary>
+
+```bash
+codex mcp add experienceengine --env EXPERIENCE_ENGINE_HOME=$HOME/.experienceengine -- npx -y @alan512/experienceengine codex-mcp-server
+```
+
+</details>
+
 Notes:
 - `OpenClaw` uses plugin/runtime integration (not `src/adapters/`) and CLI fallback for management.
 - `Claude Code` installs both hooks and the shared ExperienceEngine MCP server.
@@ -269,10 +355,7 @@ That managed state includes:
 Current default behavior:
 
 - `embeddingProvider = "api"`
-- provider priority:
-  - OpenAI when `OPENAI_API_KEY` is present
-  - Gemini when `GEMINI_API_KEY` is present
-  - Jina when `JINA_API_KEY` is present
+- provider priority: OpenAI -> Gemini -> Jina
 - if no API provider is available, ExperienceEngine falls back to the managed local embedding model
 
 Useful environment variables: