OpenReflex

---

什么是 OpenReflex

OpenReflex 为 AI 编码 Agent 提供常驻的项目肌肉记忆，涵盖编码、调查和推理工作。 生命周期钩子会在后台记录实际工作过程，将反复出现的项目行为整理成可复用的 Reflex， 并在新任务中仅注入相关的项目流程。模型无需记得调用 OpenReflex， 而且 MCP 诊断是可选的，不会加载到 Agent 的常规上下文中。

只需安装一次，即可照常工作。核心记忆保存在本机的 SQLite 数据库中。 OpenReflex 不需要账户，也不提供托管服务。Claude Code 的令牌用量会从 Claude Code 已在本地写入的会话记录中读取，且只存储用量数字。openreflex tokens enable 可选地通过 Claude Code 的 OpenTelemetry 导出功能，向仅限环回地址的接收器添加估算费用。

_{Claude Code 会话录屏。OpenReflex 会在工作开始前注入精简的相关上下文；生命周期钩子会记录工具调用和验证过程，并自动结束执行。常规流程不需要 MCP。分步操作指南见 docs/walkthrough.md。}

## 为什么选择 OpenReflex

• 它会学习项目的行为。 OpenReflex 会将成功的工作整理为项目专属的 Reflex，例如身份验证变更、Helm 配置、数据库迁移或 CI 工作。解析会结合语义意图、任务类别和模块／文件的局部性，因此新任务可以复用项目流程，而不必重复之前的任务。
• 它会在循环发生时及时发现。 重复失败的命令、完全相同的重试、进度停滞和上下文失控增长都会触发一条提醒，说明应该继续、改用其他方法，还是停止并向你确认，而不是不断发出唠叨式提醒。
• 它会在每项任务后学习。 构建工作会根据测试、lint 和构建证据完成；调查工作可以根据交叉核实的来源完成；仅涉及推理的工作则可以不借助外部工具完成。只有在可比较的过往任务确实支持更好的选项时，简单的路径检查才会指出该选项。
• 它从设计上就注重隐私。 只存储粗略的项目相对元数据，不会存储文件内容、命令、工具输出或对话记录；在你批准项目之前，数据采集功能始终关闭。

快速开始

需要 Python 3.11 或更高版本。

Claude Code — 推荐： 安装插件、重新加载，然后检查当前状态，最后明确启用项目记忆。

/plugin marketplace add vishnu-77/openreflex
/plugin install openreflex@openreflex
/reload-plugins
/openreflex
/openreflex approve

Claude 可能会将规范的插件命名空间显示为 /openreflex:openreflex；如果裸别名可用，两者都指向由用户调用的同一 OpenReflex 控制界面。不带参数的命令是只读的，且输出简洁。approve 会明确为当前项目启用本地记忆。插件会在 ~/.openreflex/runtime/ 下准备精确版本的运行时，批准后，常规 Agent 工作仍会在后台进行。

Claude 插件不会从 PATH 执行全局 openreflex。较旧的 pipx/uv/pip 安装可以与插件共存，而不会接管插件运行时。

CLI / 其他 Agent： 使用持久化的包安装方式。

pipx install openreflex            # or: uv tool install openreflex
cd your-project
openreflex install codex           # or cursor / opencode / claude-code

完成几项任务后：

openreflex context "fix the login redirect bug"   # preview the context a task would receive
openreflex status                                 # what has been captured and learned
openreflex doctor                                 # installation checks and recent hook errors
openreflex update --check                         # check the latest stable release

更新软件包会保留本地记忆和项目配置。由 pipx 和 uv tool 管理的安装可以使用 openreflex update、openreflex update --reinstall 或 openreflex self reinstall。Claude 插件会自动管理自己的固定版本运行时；这些包管理器命令仅适用于独立 CLI 安装。

与 Agent 搭配使用

OpenReflex 可通过 openreflex install <agent> 按项目安装，也可作为插件安装。

Agent	连接方式	安装	已验证
Claude Code	插件钩子或项目钩子	claude plugin marketplace add vishnu-77/openreflex，然后执行 claude plugin install openreflex@openreflex；或执行 openreflex install claude-code	实时会话
Codex	插件钩子或项目钩子	codex plugin marketplace add vishnu-77/openreflex，或执行 openreflex install codex，然后在 /hooks 中信任这些钩子一次	实时会话
Cursor	生命周期钩子	openreflex install cursor	协议和模糊测试
OpenCode	本地生命周期插件	openreflex install opencode	协议和模糊测试

使用 Claude 插件时，/openreflex 会显示精简的只读状态视图。使用 /openreflex approve 为当前项目启用 本地记忆，然后照常工作。其他显式控制项包括 status、reflexes、 memory、doctor、why、trace 和 revoke。OpenReflex 控制轮次不会被学习为项目 经验，也不会触发常规任务验证。控制技能仅由用户调用，不会启用 MCP 诊断，也不会参与常规模型路由。Claude 可能会显示规范的命名空间形式 /openreflex:openreflex。各 Agent 指南： Claude Code、Codex、Cursor、 OpenCode。

工作原理

钩子会将生命周期事件（提示词、工具启动、工具结束、压缩、停止）发送到 OpenReflex 引擎，由它 将事件存储在 Experience Graph 中：

Task -caused-> Execution -used-> Context -used-> Experience
CandidatePath -recommended_for-> Task            Lesson -recommended_for-> Task
Execution -failed_with-> ToolCall -resolved_by-> ToolCall
Execution -caused-> Outcome -caused-> Experience -caused-> Lesson

• 任务开始前： 检索相似经验，并由 OpenReflex 首先识别工作模式。BUILD 使用 inspect-first、test-first 和 incremental；INVESTIGATE 使用 source-first、 cross-check 和 broad-then-deep；THINK 使用 reason-first、compare-options 和 evidence-first。根据过往证据、估算成本、风险、不确定性和可逆性为路径排序。 注入的文本会被之后的每次 API 调用重新读取，因此只有在内容与任务具体相关时才会注入上下文： 匹配的 Reflex，或关于本项目中已发生故障的经验教训。每五个较重要的任务中就有一个（由 evaluation.holdout_percent 策略值决定）会作为留出任务：OpenReflex 会记录该任务，但不显示任何内容， 因此 openreflex status 可以比较有无 OpenReflex 时每项任务使用的模型 token 数。
• 任务之间（Claude Code）： 如果会话中已有大量历史记录（context.reset_hint_tokens），而一个新的、不相关的任务开始， OpenReflex 会向你建议使用 /clear；模型不会看到这条建议。执行 /clear 后，新会话会获得已清除任务的简短摘要，而非完整历史记录。
• 任务进行中： 如果某个完全相同的调用已失败两次，且此后没有编辑或通过检查，系统会在运行前拒绝该调用（Claude Code），或发出标记（其他 Agent）。如果项目以前解决过某个错误，首次出现该错误时会显示当时的解决方法。当检测器发现失败循环、重复调用、进展停滞或上下文增长时，OpenReflex 会估算继续工作的边际价值。默认关闭超预算提醒；设置 detectors.over_budget_tiers 即可开启。每次调用没有取得进展或失败时，系统都会更新当前路径的成功率估算，并将其与剩余工作的成本及最佳的未尝试替代方案进行比较。提醒会以建议继续、转向 其他策略或停止并询问用户作结。每个问题、转向或停止建议只会发出一次，消息之间会有冷却间隔。
• **任务结束后：**生命周期钩子会根据适合当前工作模式的证据自动结束执行；模型无需调用 OpenReflex。显式的 MCP 结果/路径操作仍可用于手动或诊断工作流。路径检查会显示以下任一结果： 更好的选项：<path>（如果有可比的已完成任务作为依据），或 更好的选项：无已证实结果。 系统绝不会把建议说成是实际执行过的路径。

每条建议都会保存为决策快照，并附带一个 Reflex Score（0-100），表示建议的可信度；它与任务成功的估算概率是分开的。openreflex why 会解释最新决策，openreflex trace 会显示时间线。在 Claude Code 中，任务开始时、OpenReflex 建议转向或停止或检测到问题时，以及任务完成时，都会显示简短回顾。

使用 OPENREFLEX_BUDGET 为每项任务设置可选限制，例如 calls=40,minutes=20,tokens=60000。 路由、评分、预算和回顾设置来自版本化策略：先应用打包默认值，再由 ~/.openreflex/config.toml 覆盖，最后由项目中的 .openreflex.toml 覆盖。

正常工作不会加载 OpenReflex MCP 工具。如果你明确希望在项目中启用面向模型的自省功能，请运行 openreflex diagnostics enable <agent>。运行 openreflex diagnostics disable <agent> 可再次将其禁用。 独立的 MCP Registry 包仍可供有意将 OpenReflex 安装为 MCP 服务的用户使用。

可选的 MCP 诊断/管理工具

| 工具 | 功能 | |---|---| | `get_execution_context` | 规划任务：相似的过往任务、建议策略及备选方案、预算、可能涉及的文件和经验教训。可选参数：`max_tool_calls`、`max_minutes`、`max_context_tokens`。 | | `check_progress` | 判断是否值得沿当前路径继续：继续、调整方向或停止。 | | `choose_path` | 当采用的策略与建议不同时，声明正在采用的策略。 | | `record_outcome` | 记录已确认的结果（测试/构建、交叉核对的研究、用户确认或失败），并从中汲取经验。 | | `explain_decision` | 说明最新建议的理由：Reflex Score、信号、置信度、次优方案。 | | `get_execution_trace` | 显示最近任务的决策时间线。 | | `get_reflex_score` | 以 JSON 格式显示最新的 Reflex Score 及其组成部分。 | | `search_experience` | 根据描述相似度搜索项目中的过往任务及其经验教训。 | | `explain_node` | 说明 Experience Graph 中的一个节点及其关联。 | | `get_project_insights` | 查看项目中已记录、复用和积累的经验。 | | `approve_project` | 启用记录功能，仅在用户明确要求时执行。 | | `forget_experience` | 删除一项过往任务的记忆，仅在用户明确要求时执行。 |

CLI

命令	用途
install <agent> [--dry-run]	安装仅包含钩子的环境运行时并启用项目
diagnostics enable/disable <agent>	明确选择启用/停用面向模型的 MCP 诊断功能
uninstall <agent> [--dry-run]	移除 OpenReflex 的集成条目；保留已记录的记忆
update [--check] [--reinstall]	检查或更新由 pipx/uv-tool 管理的安装；也可强制重新安装
self reinstall	修复/重新安装由 OpenReflex 管理的软件包，同时保留记忆/配置
self uninstall --yes	仅移除由 OpenReflex 管理的软件包；记忆/配置仍保留在磁盘上
approve / revoke	为当前项目启用或停用记录功能
context "<task>"	预览任务将获得的 Execution Context
status [--json]	查看已记录、复用和积累的经验，以及模型令牌用量对比
why / trace	说明最新建议，或显示决策时间线
doctor	检查安装、项目解析和最近的钩子活动
forget --yes	删除项目数据
tokens enable / tokens status / tokens disable	令牌计数无需设置；选择通过本地 Claude Code 遥测估算费用、查看费用，或移除 OpenReflex 拥有的遥测设置
benchmark	运行模拟基准测试
hook <agent> <event>	供环境 Agent 集成使用
mcp	显式运行可选的诊断/管理 MCP 服务

隐私

存储内容	永不存储
工具名称和粗略类别（read、edit、search、test 等）	文件内容
参数的指纹	命令文本
相对于项目的文件路径	工具输出
成功或失败、耗时、输出大小	对话记录和模型输出
从本地 Claude 对话记录中读取的每次 API 调用的模型令牌数；模型/来源标签；可选的费用估算	对话记录或 Claude 遥测中的提示词/响应/工具内容
经屏蔽的单行错误特征	项目外的路径
作为任务描述的提示词（最多 1,000 个字符，并会删除机密信息）	发送至 OpenReflex 托管服务的任何内容：不存在此类服务

数据存储在 ~/.openreflex/projects/<hash>/experience.sqlite3 中。设置 OPENREFLEX_HOME 可更改存储位置， 设置 OPENREFLEX_DISABLE=1 可在所有地方关闭记录功能，运行 openreflex forget --yes 可删除项目数据，或让 你的 Agent 使用 forget_experience 删除单项任务。

研究

OpenReflex 也是一个研究预算感知执行的项目：它不再将成功视为非此即彼，而是研究 Agent 如何选择执行路径、花费工具调用次数、模型令牌和上下文、应对不确定性，以及过去的工作能否在不降低结果质量的前提下，让类似的未来工作成本更低。整个循环包括经验检索、基于证据的路径选择、预算感知执行、针对不同工作模式的完成机制，以及以通俗语言比较路径。网站上的研究者视图介绍了这一理念，让你可以逐步查看一个 reflex 如何在图中形成，并将其与相关研究并列展示。

可复现的评估协议、固定的真实 Agent 语料库、精确提示词和声明边界记录在 docs/evaluation.md 中。

社区与贡献

• 问题与想法： GitHub Issues

• 支持项目： 请我喝杯咖啡

• 本地开发：

  git clone https://github.com/vishnu-77/openreflex && cd openreflex
  pip install -e ".[dev]"
  pytest && ruff check src tests scripts
  

OpenReflex 已列入 MCP Registry，标识为 io.github.vishnu-77/openreflex，也已收录在 Glama：

许可证

OpenReflex 基于 MIT 许可证发布。