@alan512/experienceengine 0.2.0 → 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.2.0",
+  "version": "0.2.1",
   "author": {
     "name": "ExperienceEngine"
   },

package/README.md

@@ -12,40 +12,30 @@ Supported hosts today: `OpenClaw`, `Claude Code`, `Codex`
 
 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:
-- 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
+- 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
 
-```text
-task signals -> distilled experience -> retrieval -> short intervention -> feedback -> governance
-```
+Task flow: `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: 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.
 
-Host agent:
-  I’ll apply the migration first, then retry startup.
+User: Why did that ExperienceEngine hint match?
 
-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.
 
-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?
 
-User:
-  Mark the last ExperienceEngine intervention as helpful.
-
-Host agent:
-  Recorded. That experience gets stronger for similar future tasks.
-```
+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>
 
@@ -110,44 +100,50 @@ ExperienceEngine is designed for intervention governance, not general memory acc
 | 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
 
 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
-```
+- `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 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
+- 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
 
 - MCP-native interaction surfaces plus CLI/operator 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:
@@ -165,9 +161,10 @@ For a more detailed explanation of what ExperienceEngine records and how an expe
 
 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
+- 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
@@ -243,23 +240,26 @@ After installation, ExperienceEngine should orient the user toward the next setu
 
 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
-```
+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 or feedback actions, for example:
+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.
+
+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."
 
+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?"
@@ -303,6 +303,7 @@ ExperienceEngine separates:
 
 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.
 
 ## Advanced Per-Host Commands (Operator / Development Only)
 

package/README.zh-CN.md

@@ -12,40 +12,30 @@ ExperienceEngine 是一个面向编程 Agent 的治理层。它复用真实执
 
 没有 ExperienceEngine：
 - agent 会在相似仓库里重复犯同样的 SQLite migration 错误
+- 它会先打开数据库、再补 migration，然后在错误方向上浪费几轮
 
 有 ExperienceEngine：
-- 它会注入一条提示，例如：`先执行 migration，再打开数据库连接`
-- 后续你可以把这次介入标记为 `helpful` 或 `harmful`
-- 这条经验会据此进入 active、降温或退役
+- 它会在真正调用工具之前注入一条很短的约束，例如：`先执行 migration，再打开数据库连接`
+- 宿主 agent 会直接避开上次已经踩过的错路，而不是重新试错
+- 任务结束后，ExperienceEngine 通常会根据真实结果自动更新这条 guidance
+- 如果这条 guidance 后面开始伤害相似任务，ExperienceEngine 会把它降温、隔离或退役
 
-```text
-任务信号 -> 提炼经验 -> 检索 -> 短提示注入 -> 反馈 -> 治理
-```
+任务流：`任务信号 -> 提炼经验 -> 检索 -> 短提示注入 -> 反馈 -> 治理`
 
 <details>
 <summary>宿主里的示例对话</summary>
 
-```text
 用户：修一下这个仓库里的 SQLite 启动失败问题。
 
-ExperienceEngine：
-  Hint: 先执行 migration，再打开数据库连接。
-
-宿主 agent：
-  我会先补 migration，然后再重试启动。
+宿主 agent：ExperienceEngine 在这个仓库里找到了一个之前成功过的修复模式：`先执行 migration，再打开数据库连接。` 我会先补 migration，然后再重试启动。
 
-用户：
-  为什么这条 ExperienceEngine 提示会命中？
+用户：为什么这条 ExperienceEngine 提示会命中？
 
-宿主 agent：
-  它匹配到了这个仓库里过去一次相同的 SQLite 启动失败，以及当时成功的 migration-first 修复路径。
+宿主 agent：它匹配到了这个仓库里过去一次相同的 SQLite 启动失败，以及当时成功的 migration-first 修复路径。
 
-用户：
-  把刚才那次 ExperienceEngine 介入标记为 helpful。
+用户：所以 ExperienceEngine 的作用，是提前把我从同样的错路上拉回来？
 
-宿主 agent：
-  已记录。之后遇到类似任务时，这条经验会更容易再次命中。
-```
+宿主 agent：对。它在下一次工具调用前复用了这个仓库里的成功路径，而且这次任务结束后通常会自动判断这条经验到底帮到了还是干扰了结果。
 
 </details>
 
@@ -110,44 +100,50 @@ ExperienceEngine 的目标不是通用 memory 累积，而是**介入治理**。
 | 保持提示短小、任务相关 | 不是核心目标 | 是 |
 | 通用文档检索 | 常见适用场景 | 不是核心目标 |
 
+## 为什么它不是另一层记忆
+
+ExperienceEngine 不是想比宿主“记住更多东西”。它的核心价值，是持续治理一条已经学到的 guidance 还应不应该继续影响后续任务。
+
+- 大部分学习动作发生在任务之后，所以当前任务不需要等待整条经验处理链路跑完
+- 每条经验节点都会经历 `candidate`、`active`、`cooling`、`retired` 这样的生命周期
+- “存下来” 和 “还能不能继续上线” 是分开的，所以有害 guidance 可以被降温、隔离，或者退出正常注入路径
+- 任务结束后的审查会继续判断这条 hint 到底是帮到了、伤害了，还是仍然不确定
+- 即使这次没有注入 hint，delivery decision 也会被记录下来，所以之后仍然能解释为什么跳过
+- 同仓库高匹配经验在成功复用后可以从保守投放提升到正常投放；跨仓库复用默认仍保持保守，除非后续证据更强
+- 这个产品追求的是“生产安全的经验复用”，不是“尽量多记、尽量多召回”
+
 ## 它在 Agent Loop 里的位置
 
 从高层看，ExperienceEngine 围绕 agent loop 的位置是这样的：
 
-```text
-用户任务
-  -> before_prompt_build：检索并注入匹配经验
-  -> agent 推理 + 工具调用：捕获失败、重试、修正和结果
-  -> task finalize：把候选信号提炼成可复用经验
-  -> helped / harmed：提升、降温或退役节点
-```
+- `用户任务`
+- `before_prompt_build`：检索并注入匹配经验
+- `agent 推理 + 工具调用`：捕获失败、重试、修正和结果
+- `task finalize`：把候选信号提炼成可复用经验
+- `helped / harmed`：提升、降温或退役节点
 
 ExperienceEngine 工作在 context 层，不会修改宿主模型权重。
 
 ## 经验生命周期
 
-```text
-任务信号
-  -> candidate
-  -> active
-  -> cooling
-  -> retired
-```
+`任务信号 -> candidate -> active -> cooling -> retired`
 
 每条经验都根据真实任务结果演化，而不是按时间粗暴清理。帮到任务的经验会被强化，反复有害的经验会被降温或退役。
 
 ## 现在能做什么
 
 - 在相似编码任务里复用短 guidance
-- 查看某条 hint 为什么命中
-- 把最近一次介入标记为 helpful 或 harmful
-- 查看 active、cooling、retired 等生命周期状态
+- 查看某条 hint 为什么命中，或者为什么这次没有注入
+- 让 ExperienceEngine 根据真实任务结果自动强化、降温、隔离或退役 guidance
+- 当自动判断不准时，手动把最近一次介入标记为 helpful 或 harmful
+- 查看 active、cooling、quarantined、retired 等生命周期状态
 - 在 `OpenClaw`、`Claude Code`、`Codex` 三个宿主中使用
 
 ### 底层实现
 
 - MCP 原生交互面，加上 CLI / operator fallback
 - 支持 API 与本地回退的语义检索
+- 确定性的 match scorecard，用来区分同仓库高置信匹配和更宽泛的跨仓库复用
 - 宿主 agent 内可直接查看和反馈经验，CLI fallback 包括 `ee inspect --last`、`ee helped`、`ee harmed`
 
 如果你想看 ExperienceNode 结构和治理字段，见：
@@ -165,9 +161,10 @@ ExperienceEngine 工作在 context 层，不会修改宿主模型权重。
 
 安装并初始化后，第一次真正体现价值的信号通常是：
 
-- ExperienceEngine 在真实任务里注入了一条短 hint
-- 宿主能解释为什么这条 hint 会命中
-- 你对最近一次介入的反馈，会影响后续复用
+- 一类重复任务不再重走之前已经犯过的错路
+- ExperienceEngine 只注入一条很短、和当前仓库直接相关的约束，而不是把上下文塞满
+- 宿主能解释为什么这条 hint 会命中，或者为什么这次没有注入
+- 任务结果通常会自动影响以后是否继续投放这条经验
 - `ee inspect --last` 能看到最近的介入和相关节点状态
 
 ## 前置条件
@@ -242,23 +239,26 @@ ExperienceEngine 现在不再把 `ee` CLI 当成适用于所有宿主的统一
 
 最小共享初始化示例：
 
-```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
-```
+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`
 
 如果你更想用 Gemini 或 Jina 做 embedding，可以沿用同样的 `ee init embedding` 流程，只替换 provider 和 model。
 
 ### 日常使用与 Operator 使用
 
-日常使用时，优先直接问宿主 agent，例如：
+日常使用时，优先直接问宿主 agent 当前的 ExperienceEngine 状态。默认主路径是自动结果归因；手动 feedback 主要用于你觉得自动判断不准时的纠偏。
+
+例如：
 
 - “ExperienceEngine 刚刚注入了什么？”
 - “为什么那条 ExperienceEngine 提示会命中？”
+- “为什么这次 ExperienceEngine 没有注入？”
 - “把刚才那次 ExperienceEngine 介入标记为 helpful 或 harmful。”
 
+正常使用里，你不应该需要手动给每次介入都打分。ExperienceEngine 的默认路径是根据真实任务结果自动学习；只有当自动判断明显不对时，你再手动纠偏。
+
 OpenClaw 还支持这些 readiness / silence 问题：
 
 - “ExperienceEngine 这里 ready 了吗？”
@@ -302,6 +302,7 @@ ExperienceEngine 明确拆分：
 
 宿主仍然是主交互面。
 `ee` 仍然是显式的 operator 面，用于 setup、验证、修复、状态查看和维护。
+对于 Codex，`ee status` 和 `ee doctor codex` 还会显示 `ee` CLI fallback 是否在 `PATH` 上可用。Codex 的 MCP 接入在 CLI fallback 缺失时仍可能正常工作，但 `ee inspect --last` 这类命令需要 PATH 里有 `ee`，或者使用显式的包调用方式。
 
 ## 高级按宿主命令（仅限 Operator / 开发者）
 

package/dist/adapters/codex/mcp-server.js

@@ -371,7 +371,7 @@ export const createCodexMcpServer = (options = {}) => {
     const brokerFacade = createCodexBrokerFacade(actionRegistry);
     const server = new McpServer({
         name: "experienceengine",
-        version: "0.2.0"
+        version: "0.2.1"
     });
     server.registerResource("experienceengine_doctor", new ResourceTemplate("experienceengine://doctor/{adapter}", {
         list: undefined,

package/dist/cli/commands/doctor.js

@@ -153,14 +153,26 @@ const logClaudeRuntimeStatus = (status) => {
     }
 };
 const logCodexRuntimeStatus = (status) => {
-    if (!status?.runtimeTarget) {
+    if (!status?.runtimeTarget && !status?.cliFallback) {
         return;
     }
     console.log("Codex runtime target:");
-    console.log(`- Target: ${status.runtimeTarget}`);
+    if (status.runtimeTarget) {
+        console.log(`- Target: ${status.runtimeTarget}`);
+    }
     if (status.launcherPaths?.mcpServer) {
         console.log(`- MCP launcher: ${status.launcherPaths.mcpServer}`);
     }
+    if (status.cliFallback) {
+        console.log(`- CLI fallback command: ${status.cliFallback.command}`);
+        console.log(`- CLI fallback available on PATH: ${status.cliFallback.available ? "yes" : "no"}`);
+        if (status.cliFallback.path) {
+            console.log(`- CLI fallback path: ${status.cliFallback.path}`);
+        }
+        if (!status.cliFallback.available && status.cliFallback.recommendation) {
+            console.log(`- CLI fallback note: ${status.cliFallback.recommendation}`);
+        }
+    }
 };
 const logCodexLearningLoopStatus = (status) => {
     if (!status?.instruction && !status?.learningLoop) {
@@ -387,6 +399,7 @@ export const runDoctorCommand = async (target, deps = {}) => {
                 transport: status.hostWiring.transport ?? "",
                 command: status.hostWiring.command ?? "",
                 capture_dir: status.captureDir,
+                cli_fallback: status.cliFallback?.available ?? false,
                 instruction_state: status.instruction?.state ?? "",
                 learning_loop: status.learningLoop?.state ?? ""
             }