@alan512/experienceengine 0.1.2 → 0.2.0

package/.claude-plugin/plugin.json

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

package/.mcp.json

@@ -2,15 +2,11 @@
   "mcpServers": {
     "experienceengine": {
       "type": "stdio",
-      "command": "node",
-      "args": [
-        "${CLAUDE_PLUGIN_ROOT}/dist/cli/index.js",
-        "mcp-server"
-      ],
+      "command": "/mnt/d/ExperienceEngineData/.experienceengine/bin/experienceengine-mcp-server",
+      "args": [],
       "env": {
-        "NODE_PATH": "${CLAUDE_PLUGIN_DATA}/node_modules",
-        "EXPERIENCE_ENGINE_HOME": "${CLAUDE_PLUGIN_DATA}/experienceengine-home"
+        "EXPERIENCE_ENGINE_HOME": "/home/seed/.experienceengine"
       }
     }
   }
-}
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alan-512
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,130 +1,312 @@
 # 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
+
+With ExperienceEngine:
+- it injects a hint like: `Run the migration before opening the DB connection`
+- later you mark that intervention `helpful` or `harmful`
+- the experience can then become active, cool down, or retire
+
+```text
+task signals -> distilled experience -> retrieval -> short intervention -> feedback -> governance
+```
+
+<details>
+<summary>Example host transcript</summary>
+
+```text
+User: Fix the SQLite startup failure in this repo.
+
+ExperienceEngine:
+  Hint: Run the migration before opening the DB connection.
+
+Host agent:
+  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:
+  Mark the last ExperienceEngine intervention as helpful.
+
+Host agent:
+  Recorded. That experience gets stronger for similar future tasks.
+```
+
+</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`
 
-## What It Does
-
-ExperienceEngine is not a general memory store and not a replacement context engine.
-
-It focuses on four things:
-- capture task/tool/outcome signals from the host agent
-- compress useful prior experience into short `strategy` or `warning` nodes
-- decide whether to inject guidance for a similar task
-- update node state from real `helped` / `harmed` outcomes
-
-## Why It Is Not Just Memory
-
-Most agent memory systems answer:
-
-- what facts should be remembered
-- what user preferences should be carried forward
-- what repository context should be loaded next time
-
-ExperienceEngine answers a different question:
-
-- when should prior experience intervene
-- which `strategy` or `warning` should be injected
-- whether that intervention actually helped
-- whether the experience should stay active, cool down, or retire
-
-In practice:
-- memory keeps facts and preferences
-- ExperienceEngine governs reusable coding tactics and failure-avoidance guidance
-
-## What You Can Use Today
-
-Already available in the repository:
-- host integration for `OpenClaw`, `Claude Code`, and `Codex`
-- MCP-native interaction surfaces plus CLI 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
-- quick inspection and feedback commands such as `ee inspect --last`, `ee helped`, and `ee harmed`
-- local Experience Pack workflow:
-  - `draft`
-  - `review`
-  - `publish`
-  - `rollback`
-- compiler and deploy workflow for host instruction files:
-  - `AGENTS.md`
-  - `CODEX.md`
-  - `CLAUDE.md`
-  - GitHub agent profile markdown
+`ee init` initializes shared ExperienceEngine state after the host-specific installation step.
 
-## Quick Start
+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).
+
+## Who It's For
+
+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
+
+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
+
+## 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
+
+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 |
+|---|---|---|
+| Persist facts and preferences across sessions | Yes | Not the primary job |
+| Capture repeated failure → fix → success paths | Partial, usually manual | Yes, from real task signals |
+| 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 |
+
+## Where It Sits In The Agent Loop
+
+At a high level, ExperienceEngine operates around the agent loop like this:
+
+```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
+```
+
+ExperienceEngine works at the context layer. It does not modify the host model's weights.
+
+## Experience Lifecycle
+
+```text
+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 Do Today
+
+- reuse short guidance from similar coding work
+- review why a hint matched
+- mark interventions helpful or harmful
+- inspect active, cooling, and retired experience
+- run across `OpenClaw`, `Claude Code`, and `Codex`
+
+### Under The Hood
+
+- MCP-native interaction surfaces plus CLI/operator fallback
+- semantic retrieval with API and local fallback
+- 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)
 
-ExperienceEngine no longer treats the `ee` CLI as the first-install entrypoint.
+## Current Status
 
-Install ExperienceEngine through the host-native command for the host you want to use:
+- 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:
+
+- ExperienceEngine injects a short hint during a real task
+- the host can explain why that hint matched
+- feedback on the last intervention affects future reuse
+- `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 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:
 
 - `OpenClaw`
-  - planned one-step command:
+  - host-native plugin install:
     - `openclaw plugins install @alan512/experienceengine`
-  - current status:
-    - blocked until the public npm package `@alan512/experienceengine` is published
+  - after installing, restart the OpenClaw gateway before the first real task:
+    - `openclaw gateway restart`
 - `Codex`
-  - planned one-step command:
-    - `codex mcp add experienceengine --env EXPERIENCE_ENGINE_HOME=$HOME/.experienceengine -- npx -y @alan512/experienceengine codex-mcp-server`
-  - current status:
-    - blocked until the public npm package `@alan512/experienceengine` is published
+  - EE-managed Codex setup:
+    - `ee install codex`
+  - native/manual fallback:
+    - 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`
-  - add the bundled marketplace from GitHub:
+  - host-native marketplace install:
+    - add the bundled marketplace from GitHub:
     - `/plugin marketplace add https://github.com/Alan-512/ExperienceEngine.git`
   - install the bundled plugin:
     - `/plugin install experienceengine@experienceengine`
   - `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 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 inspection and feedback inside the host when supported
+5. use `ee` as the operator fallback for validation, repair, and deeper inspection
+
+### Shared Initialization
+
+`ee init` is shared-product initialization, not host-specific setup.
+
+- 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.
+
+After installation, ExperienceEngine should orient the user toward the next setup step:
+
+- 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:
 
-After the host-native installation completes, use:
+```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.
+
+### Routine Use vs Operator Use
+
+For routine use, ask the host agent naturally for ExperienceEngine state or feedback actions, for example:
+
+- "What did ExperienceEngine just inject?"
+- "Why did that ExperienceEngine hint match?"
+- "Mark the last ExperienceEngine intervention as helpful or harmful."
+
+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.
+Use CLI fallback whenever the host-side path is unavailable or you need explicit operator control.
+
+Use the `ee` CLI when you need explicit operator validation or troubleshooting:
 
 ```bash
+ee init
 ee doctor <openclaw|claude-code|codex>
 ee status
 ee maintenance embedding-smoke
 ```
 
-## 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
+### Readiness and Value States
 
-ExperienceEngine does not install those host CLIs for you. It wires itself into an already working host environment.
+ExperienceEngine treats onboarding and value as two separate layers:
 
-## Installation Model
+- `Setup state`
+  - `Installed`
+  - `Initialized`
+  - `Ready`
+- `Value state`
+  - `Warming up`
+  - `First value reached`
 
-ExperienceEngine now treats installation and operations as separate concerns:
+These are not one linear ladder. A repo can already be `Ready` while still `Warming up`.
 
-- installation belongs to the host
-- validation and maintenance belong to `ee`
+`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.
 
-That means:
+## Installation Model
 
-- `Codex` uses a Codex-native MCP integration flow
-- `Claude Code` uses Claude-native plugin assets and marketplace distribution
-- `OpenClaw` uses plugin/runtime integration
+ExperienceEngine separates:
+- host installation
+- shared initialization
+- operator workflows
 
-Once installation is complete, `ee` becomes the operational surface for:
+The host remains the primary interaction surface.
+`ee` remains the explicit operator surface for setup, validation, repair, status, and maintenance.
 
-- health checks
-- repair guidance
-- status inspection
-- learning and intervention feedback
+## Advanced Per-Host Commands (Operator / Development Only)
 
-## 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:
 
@@ -134,6 +316,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.
@@ -163,10 +354,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:
@@ -182,4 +370,9 @@ See the full user guide here:
 
 - [ExperienceEngine User Guide](./docs/user-guide.md)
 
-The user guide covers installation, host-specific notes, first-run validation, pack workflows, compiler/deploy commands, troubleshooting, and maintenance operations.
+The user guide covers installation, host-specific notes, first-run validation, troubleshooting, and maintenance operations.
+
+## License
+
+This project is licensed under the MIT License.
+See [LICENSE](./LICENSE).