PyPI - openreflex - Versions diffs - 0.3.1__tar.gz → 0.3.2__tar.gz - Mend

openreflex 0.3.1tar.gz → 0.3.2tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (40) hide show

{openreflex-0.3.1/src/openreflex.egg-info → openreflex-0.3.2}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openreflex
-Version: 0.3.1
+Version: 0.3.2
 Summary: Muscle memory for AI coding agents: learns from every task, advises the next one, and flags failure loops live
 Author: vishnu-77
 License-Expression: MIT
@@ -35,19 +35,18 @@ Dynamic: license-file
 <a href="https://openreflex.cc" target="_blank">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-logo-dark.svg">
-    <img alt="OpenReflex" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-logo-light.svg" width="380" height="auto">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-banner-dark.svg">
+    <img alt="OpenReflex: muscle memory for AI coding agents" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-banner-light.svg" width="720" height="auto">
   </picture>
 </a>
-### OpenReflex: muscle memory for AI coding agents
-<a href="https://openreflex.cc">Website</a> · <a href="https://github.com/vishnu-77/openreflex">GitHub</a> · <a href="https://pypi.org/project/openreflex/">PyPI</a> · <a href="https://github.com/vishnu-77/openreflex/issues">Issues</a> · <a href="https://buymeacoffee.com/vishnuprashanth">Buy me a coffee</a>
+<a href="https://openreflex.cc">Website</a> · <a href="https://openreflex.cc/docs">Docs</a> · <a href="docs/walkthrough.md">Walkthrough</a> · <a href="https://pypi.org/project/openreflex/">PyPI</a> · <a href="https://github.com/vishnu-77/openreflex/issues">Issues</a> · <a href="https://buymeacoffee.com/vishnuprashanth">Buy me a coffee</a>
 [![PyPI](https://img.shields.io/pypi/v/openreflex?style=flat-square&labelColor=black&color=286a70)](https://pypi.org/project/openreflex/)
 [![Python](https://img.shields.io/pypi/pyversions/openreflex?style=flat-square&labelColor=black&color=7cc9c8)](https://pypi.org/project/openreflex/)
 [![CI](https://img.shields.io/github/actions/workflow/status/vishnu-77/openreflex/ci.yml?branch=main&style=flat-square&labelColor=black&label=CI)](https://github.com/vishnu-77/openreflex/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-white?style=flat-square&labelColor=black)](https://github.com/vishnu-77/openreflex/blob/main/LICENSE)
+[![Glama score](https://glama.ai/mcp/servers/vishnu-77/openreflex/badges/score.svg)](https://glama.ai/mcp/servers/vishnu-77/openreflex)
 </div>
@@ -62,28 +61,33 @@ before: the approach, the files that mattered, and the fix for the error you hit
 You install it once and keep working normally. Everything stays on your machine in a local SQLite database.
 There is no account, no service, and no telemetry.
+<p align="center">
+  <a href="docs/walkthrough.md">
+    <img alt="Recording of a real Claude Code session with OpenReflex: OpenReflex reports one similar past task and adds 162 context tokens, Claude finds and fixes the coupon bug, runs the tests, records the verified outcome through OpenReflex's MCP tool, and OpenReflex shows the completion recap with the path taken, cost and regret" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/docs/screenshots/claude-code-session.gif" width="860">
+  </a>
+  <br>
+  <sub>A real Claude Code session, recorded from the terminal and sped up. OpenReflex had seen one similar task in this repository, so it adds 162 tokens of context before the first tool call; after the fix, Claude records the outcome through OpenReflex's MCP tool. The step-by-step walkthrough is in <a href="docs/walkthrough.md">docs/walkthrough.md</a>.</sub>
+</p>
 ## Why OpenReflex
 - **It remembers what worked.** Before a substantial task, OpenReflex retrieves similar past tasks and injects a
   compact Execution Context: a suggested approach with alternatives, the files that were changed, and lessons
   such as which edit resolved a recurring error.
 - **It catches loops while they happen.** Repeated failing commands, identical retries, stalled progress, and
-  runaway context growth raise a single, specific alert with an alternative path, never a stream of nags.
+  runaway context growth raise one alert that says whether to continue, pivot to another approach, or stop and
+  check in with you, never a stream of nags.
 - **It learns after every task.** OpenReflex infers the outcome from real verification (a test or build that
   passed or failed after the last edit), estimates Execution Regret against the alternatives, and extracts lessons.
 - **It is private by design.** Only coarse, project-relative metadata is stored. File contents, commands, tool
   output, and transcripts never are, and capture is off until you approve a project.
-```
-        before a task                  during a task                 after a task
-  ┌──────────────────────┐    ┌──────────────────────────┐    ┌───────────────────────┐
-  │ retrieve experience  │    │ watch tool calls         │    │ infer outcome         │
-  │ score candidate paths│ →  │ flag loops and stalls    │ →  │ estimate regret       │
-  │ inject context       │    │ suggest an alternative   │    │ extract lessons       │
-  └──────────────────────┘    └──────────────────────────┘    └───────────────────────┘
-                 ▲                                                        │
-                 └──────────────────── Experience Graph ◄─────────────────┘
-```
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/how-it-works-dark.svg">
+    <img alt="Before a task: retrieve similar experience, score candidate paths, inject context and a budget. During a task: watch every tool call, flag loops and stalls, advise continue, pivot or stop. After a task: infer the outcome from checks, estimate Execution Regret, extract lessons. Lessons feed the Experience Graph for the next task." src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/how-it-works-light.svg" width="860">
+  </picture>
+</p>
 ## Quick start
@@ -95,6 +99,19 @@ cd your-project
 openreflex install claude-code     # writes hooks + MCP config and enables this project
 ```
+```
+OPENREFLEX / CONNECT
+  agent       claude-code
+  project     D:\demo\shop
+  config      updated 2 files
+              D:\demo\shop\.claude\settings.json
+              D:\demo\shop\.mcp.json
+  memory      enabled
+  storage     local
+  [ok] reflex active
+```
 Then work as usual. After a few tasks:
 ```bash
@@ -107,37 +124,16 @@ openreflex doctor                                 # installation checks and rece
 OpenReflex installs per project with `openreflex install <agent>`, or as a plugin.
-<table>
-  <tbody>
-    <tr>
-      <td align="center" valign="bottom" width="25%"><strong>Claude&nbsp;Code</strong><br><sub>Plugin&nbsp;or&nbsp;hooks&nbsp;+&nbsp;MCP</sub></td>
-      <td align="center" valign="bottom" width="25%"><strong>Codex</strong><br><sub>Plugin&nbsp;or&nbsp;hooks&nbsp;+&nbsp;MCP</sub></td>
-      <td align="center" valign="bottom" width="25%"><strong>Cursor</strong><br><sub>Hooks&nbsp;+&nbsp;MCP</sub></td>
-      <td align="center" valign="bottom" width="25%"><strong>OpenCode</strong><br><sub>Plugin&nbsp;+&nbsp;MCP</sub></td>
-    </tr>
-  </tbody>
-</table>
-| Agent | Install |
-|---|---|
-| Claude Code | `claude plugin marketplace add vishnu-77/openreflex` and `claude plugin install openreflex@openreflex`, or `openreflex install claude-code` |
-| Codex | `codex plugin marketplace add vishnu-77/openreflex`, or `openreflex install codex`, then trust the hooks once in `/hooks` |
-| Cursor | `openreflex install cursor` |
-| OpenCode | `openreflex install opencode` |
-With a plugin install, enable each project with `openreflex approve`. Claude Code and Codex are verified in live
-sessions; the Cursor and OpenCode integrations follow each agent's documented hook protocol.
-## See it work
+| Agent | Connects through | Install | Verified |
+|---|---|---|---|
+| **Claude Code** | Plugin, or hooks + MCP | `claude plugin marketplace add vishnu-77/openreflex` then `claude plugin install openreflex@openreflex`, or `openreflex install claude-code` | Live sessions |
+| **Codex** | Plugin, or hooks + MCP | `codex plugin marketplace add vishnu-77/openreflex`, or `openreflex install codex`, then trust the hooks once in `/hooks` | Live sessions |
+| **Cursor** | Hooks + MCP | `openreflex install cursor` | Protocol and fuzz tests |
+| **OpenCode** | Plugin + MCP | `openreflex install opencode` | Protocol and fuzz tests |
-A real Claude Code session in a repository where OpenReflex has seen one similar task before. The
-`UserPromptSubmit` line shows the past experience found and the context added; the `Stop` line shows the verified
-outcome, the path taken and the cost.
-![Claude Code session with OpenReflex](https://raw.githubusercontent.com/vishnu-77/openreflex/main/docs/screenshots/claude-code-session-2.png)
-The full walkthrough, with both sessions, the exact context the model received and the CLI output, is in
-[docs/walkthrough.md](docs/walkthrough.md).
+With a plugin install, enable each project with `openreflex approve`. Per-agent guides:
+[Claude Code](https://openreflex.cc/claude-code), [Codex](https://openreflex.cc/codex), [Cursor](https://openreflex.cc/cursor),
+[OpenCode](https://openreflex.cc/opencode).
 ## How it works
@@ -177,10 +173,27 @@ Set optional limits for every task with `OPENREFLEX_BUDGET`, for example `calls=
 Routing, scoring, budget and recap settings come from a versioned policy: the packaged defaults, overridden by
 `~/.openreflex/config.toml` and then by `.openreflex.toml` in the project.
-Agents can also query OpenReflex directly through its MCP server: `get_execution_context` (optionally with
-`max_tool_calls`, `max_minutes`, `max_context_tokens`), `choose_path`, `check_progress`, `explain_decision`,
-`get_execution_trace`, `get_reflex_score`, `record_outcome`, `search_experience`, `explain_node`,
-`get_project_insights`, `approve_project`, and `forget_experience` (deletes one past task's memory, only when the user asks).
+Agents can also query OpenReflex directly through its MCP server.
+<details>
+<summary><strong>The 12 MCP tools</strong></summary>
+| Tool | What it does |
+|---|---|
+| `get_execution_context` | Plan a task: similar past tasks, the suggested strategy with alternatives, a budget, likely files, lessons. Optional `max_tool_calls`, `max_minutes`, `max_context_tokens`. |
+| `check_progress` | Whether more work on the current path is worth it: continue, pivot or stop. |
+| `choose_path` | Declare the strategy being followed when it differs from the suggestion. |
+| `record_outcome` | Record a verified outcome (tests passed, user confirmed, or failure) and learn from it. |
+| `explain_decision` | Why the latest recommendation was made: Reflex Score, signals, confidence, next-best route. |
+| `get_execution_trace` | The decision timeline of the most recent task. |
+| `get_reflex_score` | The latest Reflex Score and its components as JSON. |
+| `search_experience` | Past tasks in the project by description similarity, with their lessons. |
+| `explain_node` | One Experience Graph node and its relations. |
+| `get_project_insights` | What has been recorded, reused and learned in the project. |
+| `approve_project` | Enable capture, only when the user explicitly asks. |
+| `forget_experience` | Delete one past task's memory, only when the user explicitly asks. |
+</details>
 ## CLI
@@ -199,12 +212,26 @@ Agents can also query OpenReflex directly through its MCP server: `get_execution
 ## Privacy
-- Stored per tool call: tool name, a coarse category (`read`, `edit`, `search`, `test`, ...), a fingerprint of the
-  arguments, project-relative file paths, status, duration, output size, and a masked one-line error signature.
-- Never stored: file contents, command text, tool output, transcripts, or paths outside the project.
-- Prompts are kept as task descriptions (up to 1,000 characters) with secrets such as API keys and tokens redacted.
-- Data lives in `~/.openreflex/projects/<hash>/experience.sqlite3`. Set `OPENREFLEX_HOME` to move it,
-  `OPENREFLEX_DISABLE=1` to turn capture off everywhere, or run `openreflex forget --yes` to delete a project's data.
+| Stored | Never stored |
+|---|---|
+| Tool name and a coarse category (`read`, `edit`, `search`, `test`, ...) | File contents |
+| A fingerprint of the arguments | Command text |
+| Project-relative file paths | Tool output |
+| Pass or fail, duration, output size | Transcripts and model output |
+| A masked one-line error signature | Paths outside the project |
+| The prompt as a task description (up to 1,000 characters, secrets redacted) | Anything sent to a server: there is none |
+Data lives in `~/.openreflex/projects/<hash>/experience.sqlite3`. Set `OPENREFLEX_HOME` to move it,
+`OPENREFLEX_DISABLE=1` to turn capture off everywhere, `openreflex forget --yes` to delete a project's data, or ask
+your agent to `forget_experience` a single task.
+## Research
+OpenReflex is also a research project in budget-aware execution: instead of treating success as a yes or no, it
+studies how agents choose execution paths, spend tool calls and context, respond to uncertainty, and whether more
+computation still adds value. The loop is experience retrieval, Pareto path selection, budget-aware execution and
+counterfactual regret. The [Researcher view](https://openreflex.cc/?view=research) on the site explains the idea,
+lets you step through one reflex forming in the graph, and places it next to related work.
 ## Community & Contributing
@@ -222,6 +249,12 @@ Agents can also query OpenReflex directly through its MCP server: `get_execution
   <img src="https://contrib.rocks/image?repo=vishnu-77/openreflex" alt="Contributors">
 </a>
+OpenReflex is listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.vishnu-77/openreflex` and on Glama:
+<a href="https://glama.ai/mcp/servers/vishnu-77/openreflex">
+  <img src="https://glama.ai/mcp/servers/vishnu-77/openreflex/badges/card.svg" alt="OpenReflex MCP server: quality and maintenance score on Glama" width="380">
+</a>
 ## License
 OpenReflex is released under the [MIT License](https://github.com/vishnu-77/openreflex/blob/main/LICENSE).

{openreflex-0.3.1 → openreflex-0.3.2}/README.md RENAMED Viewed

@@ -3,19 +3,18 @@
 <a href="https://openreflex.cc" target="_blank">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-logo-dark.svg">
-    <img alt="OpenReflex" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-logo-light.svg" width="380" height="auto">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-banner-dark.svg">
+    <img alt="OpenReflex: muscle memory for AI coding agents" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-banner-light.svg" width="720" height="auto">
   </picture>
 </a>
-### OpenReflex: muscle memory for AI coding agents
-<a href="https://openreflex.cc">Website</a> · <a href="https://github.com/vishnu-77/openreflex">GitHub</a> · <a href="https://pypi.org/project/openreflex/">PyPI</a> · <a href="https://github.com/vishnu-77/openreflex/issues">Issues</a> · <a href="https://buymeacoffee.com/vishnuprashanth">Buy me a coffee</a>
+<a href="https://openreflex.cc">Website</a> · <a href="https://openreflex.cc/docs">Docs</a> · <a href="docs/walkthrough.md">Walkthrough</a> · <a href="https://pypi.org/project/openreflex/">PyPI</a> · <a href="https://github.com/vishnu-77/openreflex/issues">Issues</a> · <a href="https://buymeacoffee.com/vishnuprashanth">Buy me a coffee</a>
 [![PyPI](https://img.shields.io/pypi/v/openreflex?style=flat-square&labelColor=black&color=286a70)](https://pypi.org/project/openreflex/)
 [![Python](https://img.shields.io/pypi/pyversions/openreflex?style=flat-square&labelColor=black&color=7cc9c8)](https://pypi.org/project/openreflex/)
 [![CI](https://img.shields.io/github/actions/workflow/status/vishnu-77/openreflex/ci.yml?branch=main&style=flat-square&labelColor=black&label=CI)](https://github.com/vishnu-77/openreflex/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-white?style=flat-square&labelColor=black)](https://github.com/vishnu-77/openreflex/blob/main/LICENSE)
+[![Glama score](https://glama.ai/mcp/servers/vishnu-77/openreflex/badges/score.svg)](https://glama.ai/mcp/servers/vishnu-77/openreflex)
 </div>
@@ -30,28 +29,33 @@ before: the approach, the files that mattered, and the fix for the error you hit
 You install it once and keep working normally. Everything stays on your machine in a local SQLite database.
 There is no account, no service, and no telemetry.
+<p align="center">
+  <a href="docs/walkthrough.md">
+    <img alt="Recording of a real Claude Code session with OpenReflex: OpenReflex reports one similar past task and adds 162 context tokens, Claude finds and fixes the coupon bug, runs the tests, records the verified outcome through OpenReflex's MCP tool, and OpenReflex shows the completion recap with the path taken, cost and regret" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/docs/screenshots/claude-code-session.gif" width="860">
+  </a>
+  <br>
+  <sub>A real Claude Code session, recorded from the terminal and sped up. OpenReflex had seen one similar task in this repository, so it adds 162 tokens of context before the first tool call; after the fix, Claude records the outcome through OpenReflex's MCP tool. The step-by-step walkthrough is in <a href="docs/walkthrough.md">docs/walkthrough.md</a>.</sub>
+</p>
 ## Why OpenReflex
 - **It remembers what worked.** Before a substantial task, OpenReflex retrieves similar past tasks and injects a
   compact Execution Context: a suggested approach with alternatives, the files that were changed, and lessons
   such as which edit resolved a recurring error.
 - **It catches loops while they happen.** Repeated failing commands, identical retries, stalled progress, and
-  runaway context growth raise a single, specific alert with an alternative path, never a stream of nags.
+  runaway context growth raise one alert that says whether to continue, pivot to another approach, or stop and
+  check in with you, never a stream of nags.
 - **It learns after every task.** OpenReflex infers the outcome from real verification (a test or build that
   passed or failed after the last edit), estimates Execution Regret against the alternatives, and extracts lessons.
 - **It is private by design.** Only coarse, project-relative metadata is stored. File contents, commands, tool
   output, and transcripts never are, and capture is off until you approve a project.
-```
-        before a task                  during a task                 after a task
-  ┌──────────────────────┐    ┌──────────────────────────┐    ┌───────────────────────┐
-  │ retrieve experience  │    │ watch tool calls         │    │ infer outcome         │
-  │ score candidate paths│ →  │ flag loops and stalls    │ →  │ estimate regret       │
-  │ inject context       │    │ suggest an alternative   │    │ extract lessons       │
-  └──────────────────────┘    └──────────────────────────┘    └───────────────────────┘
-                 ▲                                                        │
-                 └──────────────────── Experience Graph ◄─────────────────┘
-```
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/how-it-works-dark.svg">
+    <img alt="Before a task: retrieve similar experience, score candidate paths, inject context and a budget. During a task: watch every tool call, flag loops and stalls, advise continue, pivot or stop. After a task: infer the outcome from checks, estimate Execution Regret, extract lessons. Lessons feed the Experience Graph for the next task." src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/how-it-works-light.svg" width="860">
+  </picture>
+</p>
 ## Quick start
@@ -63,6 +67,19 @@ cd your-project
 openreflex install claude-code     # writes hooks + MCP config and enables this project
 ```
+```
+OPENREFLEX / CONNECT
+  agent       claude-code
+  project     D:\demo\shop
+  config      updated 2 files
+              D:\demo\shop\.claude\settings.json
+              D:\demo\shop\.mcp.json
+  memory      enabled
+  storage     local
+  [ok] reflex active
+```
 Then work as usual. After a few tasks:
 ```bash
@@ -75,37 +92,16 @@ openreflex doctor                                 # installation checks and rece
 OpenReflex installs per project with `openreflex install <agent>`, or as a plugin.
-<table>
-  <tbody>
-    <tr>
-      <td align="center" valign="bottom" width="25%"><strong>Claude&nbsp;Code</strong><br><sub>Plugin&nbsp;or&nbsp;hooks&nbsp;+&nbsp;MCP</sub></td>
-      <td align="center" valign="bottom" width="25%"><strong>Codex</strong><br><sub>Plugin&nbsp;or&nbsp;hooks&nbsp;+&nbsp;MCP</sub></td>
-      <td align="center" valign="bottom" width="25%"><strong>Cursor</strong><br><sub>Hooks&nbsp;+&nbsp;MCP</sub></td>
-      <td align="center" valign="bottom" width="25%"><strong>OpenCode</strong><br><sub>Plugin&nbsp;+&nbsp;MCP</sub></td>
-    </tr>
-  </tbody>
-</table>
-| Agent | Install |
-|---|---|
-| Claude Code | `claude plugin marketplace add vishnu-77/openreflex` and `claude plugin install openreflex@openreflex`, or `openreflex install claude-code` |
-| Codex | `codex plugin marketplace add vishnu-77/openreflex`, or `openreflex install codex`, then trust the hooks once in `/hooks` |
-| Cursor | `openreflex install cursor` |
-| OpenCode | `openreflex install opencode` |
-With a plugin install, enable each project with `openreflex approve`. Claude Code and Codex are verified in live
-sessions; the Cursor and OpenCode integrations follow each agent's documented hook protocol.
-## See it work
+| Agent | Connects through | Install | Verified |
+|---|---|---|---|
+| **Claude Code** | Plugin, or hooks + MCP | `claude plugin marketplace add vishnu-77/openreflex` then `claude plugin install openreflex@openreflex`, or `openreflex install claude-code` | Live sessions |
+| **Codex** | Plugin, or hooks + MCP | `codex plugin marketplace add vishnu-77/openreflex`, or `openreflex install codex`, then trust the hooks once in `/hooks` | Live sessions |
+| **Cursor** | Hooks + MCP | `openreflex install cursor` | Protocol and fuzz tests |
+| **OpenCode** | Plugin + MCP | `openreflex install opencode` | Protocol and fuzz tests |
-A real Claude Code session in a repository where OpenReflex has seen one similar task before. The
-`UserPromptSubmit` line shows the past experience found and the context added; the `Stop` line shows the verified
-outcome, the path taken and the cost.
-![Claude Code session with OpenReflex](https://raw.githubusercontent.com/vishnu-77/openreflex/main/docs/screenshots/claude-code-session-2.png)
-The full walkthrough, with both sessions, the exact context the model received and the CLI output, is in
-[docs/walkthrough.md](docs/walkthrough.md).
+With a plugin install, enable each project with `openreflex approve`. Per-agent guides:
+[Claude Code](https://openreflex.cc/claude-code), [Codex](https://openreflex.cc/codex), [Cursor](https://openreflex.cc/cursor),
+[OpenCode](https://openreflex.cc/opencode).
 ## How it works
@@ -145,10 +141,27 @@ Set optional limits for every task with `OPENREFLEX_BUDGET`, for example `calls=
 Routing, scoring, budget and recap settings come from a versioned policy: the packaged defaults, overridden by
 `~/.openreflex/config.toml` and then by `.openreflex.toml` in the project.
-Agents can also query OpenReflex directly through its MCP server: `get_execution_context` (optionally with
-`max_tool_calls`, `max_minutes`, `max_context_tokens`), `choose_path`, `check_progress`, `explain_decision`,
-`get_execution_trace`, `get_reflex_score`, `record_outcome`, `search_experience`, `explain_node`,
-`get_project_insights`, `approve_project`, and `forget_experience` (deletes one past task's memory, only when the user asks).
+Agents can also query OpenReflex directly through its MCP server.
+<details>
+<summary><strong>The 12 MCP tools</strong></summary>
+| Tool | What it does |
+|---|---|
+| `get_execution_context` | Plan a task: similar past tasks, the suggested strategy with alternatives, a budget, likely files, lessons. Optional `max_tool_calls`, `max_minutes`, `max_context_tokens`. |
+| `check_progress` | Whether more work on the current path is worth it: continue, pivot or stop. |
+| `choose_path` | Declare the strategy being followed when it differs from the suggestion. |
+| `record_outcome` | Record a verified outcome (tests passed, user confirmed, or failure) and learn from it. |
+| `explain_decision` | Why the latest recommendation was made: Reflex Score, signals, confidence, next-best route. |
+| `get_execution_trace` | The decision timeline of the most recent task. |
+| `get_reflex_score` | The latest Reflex Score and its components as JSON. |
+| `search_experience` | Past tasks in the project by description similarity, with their lessons. |
+| `explain_node` | One Experience Graph node and its relations. |
+| `get_project_insights` | What has been recorded, reused and learned in the project. |
+| `approve_project` | Enable capture, only when the user explicitly asks. |
+| `forget_experience` | Delete one past task's memory, only when the user explicitly asks. |
+</details>
 ## CLI
@@ -167,12 +180,26 @@ Agents can also query OpenReflex directly through its MCP server: `get_execution
 ## Privacy
-- Stored per tool call: tool name, a coarse category (`read`, `edit`, `search`, `test`, ...), a fingerprint of the
-  arguments, project-relative file paths, status, duration, output size, and a masked one-line error signature.
-- Never stored: file contents, command text, tool output, transcripts, or paths outside the project.
-- Prompts are kept as task descriptions (up to 1,000 characters) with secrets such as API keys and tokens redacted.
-- Data lives in `~/.openreflex/projects/<hash>/experience.sqlite3`. Set `OPENREFLEX_HOME` to move it,
-  `OPENREFLEX_DISABLE=1` to turn capture off everywhere, or run `openreflex forget --yes` to delete a project's data.
+| Stored | Never stored |
+|---|---|
+| Tool name and a coarse category (`read`, `edit`, `search`, `test`, ...) | File contents |
+| A fingerprint of the arguments | Command text |
+| Project-relative file paths | Tool output |
+| Pass or fail, duration, output size | Transcripts and model output |
+| A masked one-line error signature | Paths outside the project |
+| The prompt as a task description (up to 1,000 characters, secrets redacted) | Anything sent to a server: there is none |
+Data lives in `~/.openreflex/projects/<hash>/experience.sqlite3`. Set `OPENREFLEX_HOME` to move it,
+`OPENREFLEX_DISABLE=1` to turn capture off everywhere, `openreflex forget --yes` to delete a project's data, or ask
+your agent to `forget_experience` a single task.
+## Research
+OpenReflex is also a research project in budget-aware execution: instead of treating success as a yes or no, it
+studies how agents choose execution paths, spend tool calls and context, respond to uncertainty, and whether more
+computation still adds value. The loop is experience retrieval, Pareto path selection, budget-aware execution and
+counterfactual regret. The [Researcher view](https://openreflex.cc/?view=research) on the site explains the idea,
+lets you step through one reflex forming in the graph, and places it next to related work.
 ## Community & Contributing
@@ -190,6 +217,12 @@ Agents can also query OpenReflex directly through its MCP server: `get_execution
   <img src="https://contrib.rocks/image?repo=vishnu-77/openreflex" alt="Contributors">
 </a>
+OpenReflex is listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.vishnu-77/openreflex` and on Glama:
+<a href="https://glama.ai/mcp/servers/vishnu-77/openreflex">
+  <img src="https://glama.ai/mcp/servers/vishnu-77/openreflex/badges/card.svg" alt="OpenReflex MCP server: quality and maintenance score on Glama" width="380">
+</a>
 ## License
 OpenReflex is released under the [MIT License](https://github.com/vishnu-77/openreflex/blob/main/LICENSE).

{openreflex-0.3.1 → openreflex-0.3.2}/pyproject.toml RENAMED Viewed

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 [project]
 name = "openreflex"
-version = "0.3.1"
+version = "0.3.2"
 description = "Muscle memory for AI coding agents: learns from every task, advises the next one, and flags failure loops live"
 readme = "README.md"
 license = "MIT"

{openreflex-0.3.1 → openreflex-0.3.2}/src/openreflex/__init__.py RENAMED Viewed

@@ -1,3 +1,3 @@
 """Ambient, local execution intelligence."""
-__version__ = "0.3.1"
+__version__ = "0.3.2"

{openreflex-0.3.1 → openreflex-0.3.2}/src/openreflex/engine.py RENAMED Viewed

@@ -257,7 +257,13 @@ class Engine:
                               budget_for(paths[0], limits, self.policy), self.policy)
     def decision_snapshots(self, execution_id: str | None = None) -> list[DecisionSnapshot]:
-        execution = self.store.get(execution_id) if execution_id else self.current_execution(max_age=float("inf"))
+        """Snapshots of the given execution, or of the most recent one that made decisions. Activity without a
+        captured prompt (a resumed session, a tool call before any prompt) must not hide the latest explanation."""
+        if execution_id:
+            execution = self.store.get(execution_id)
+        else:
+            decided = [e for e in self.store.list("Execution", limit=200) if e.decision_history]
+            execution = max(decided, key=lambda e: e.started_at, default=None)
         if execution is None:
             return []
         return [DecisionSnapshot.from_dict(item) for item in execution.decision_history]

{openreflex-0.3.1 → openreflex-0.3.2}/src/openreflex/hooks.py RENAMED Viewed

@@ -212,7 +212,8 @@ def handle(agent: str, name: str, payload: dict, engine_factory=Engine) -> str:
     agent = detect_agent(agent, payload)
     name = name or payload.get("hook_event_name") or payload.get("event") or ""
     event = normalize(agent, name, payload)
-    if event.kind == "ignored" or not event.session:
+    # A tool event that names no tool is malformed; recording it would create a nameless call and a phantom task.
+    if event.kind == "ignored" or not event.session or (event.kind in ("tool_start", "tool_end") and not event.tool):
         return render(agent, name, None)
     project = project_root(event.cwd)
     if not approval(project):

{openreflex-0.3.1 → openreflex-0.3.2/src/openreflex.egg-info}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: openreflex
-Version: 0.3.1
+Version: 0.3.2
 Summary: Muscle memory for AI coding agents: learns from every task, advises the next one, and flags failure loops live
 Author: vishnu-77
 License-Expression: MIT
@@ -35,19 +35,18 @@ Dynamic: license-file
 <a href="https://openreflex.cc" target="_blank">
   <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-logo-dark.svg">
-    <img alt="OpenReflex" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-logo-light.svg" width="380" height="auto">
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-banner-dark.svg">
+    <img alt="OpenReflex: muscle memory for AI coding agents" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/openreflex-banner-light.svg" width="720" height="auto">
   </picture>
 </a>
-### OpenReflex: muscle memory for AI coding agents
-<a href="https://openreflex.cc">Website</a> · <a href="https://github.com/vishnu-77/openreflex">GitHub</a> · <a href="https://pypi.org/project/openreflex/">PyPI</a> · <a href="https://github.com/vishnu-77/openreflex/issues">Issues</a> · <a href="https://buymeacoffee.com/vishnuprashanth">Buy me a coffee</a>
+<a href="https://openreflex.cc">Website</a> · <a href="https://openreflex.cc/docs">Docs</a> · <a href="docs/walkthrough.md">Walkthrough</a> · <a href="https://pypi.org/project/openreflex/">PyPI</a> · <a href="https://github.com/vishnu-77/openreflex/issues">Issues</a> · <a href="https://buymeacoffee.com/vishnuprashanth">Buy me a coffee</a>
 [![PyPI](https://img.shields.io/pypi/v/openreflex?style=flat-square&labelColor=black&color=286a70)](https://pypi.org/project/openreflex/)
 [![Python](https://img.shields.io/pypi/pyversions/openreflex?style=flat-square&labelColor=black&color=7cc9c8)](https://pypi.org/project/openreflex/)
 [![CI](https://img.shields.io/github/actions/workflow/status/vishnu-77/openreflex/ci.yml?branch=main&style=flat-square&labelColor=black&label=CI)](https://github.com/vishnu-77/openreflex/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-MIT-white?style=flat-square&labelColor=black)](https://github.com/vishnu-77/openreflex/blob/main/LICENSE)
+[![Glama score](https://glama.ai/mcp/servers/vishnu-77/openreflex/badges/score.svg)](https://glama.ai/mcp/servers/vishnu-77/openreflex)
 </div>
@@ -62,28 +61,33 @@ before: the approach, the files that mattered, and the fix for the error you hit
 You install it once and keep working normally. Everything stays on your machine in a local SQLite database.
 There is no account, no service, and no telemetry.
+<p align="center">
+  <a href="docs/walkthrough.md">
+    <img alt="Recording of a real Claude Code session with OpenReflex: OpenReflex reports one similar past task and adds 162 context tokens, Claude finds and fixes the coupon bug, runs the tests, records the verified outcome through OpenReflex's MCP tool, and OpenReflex shows the completion recap with the path taken, cost and regret" src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/docs/screenshots/claude-code-session.gif" width="860">
+  </a>
+  <br>
+  <sub>A real Claude Code session, recorded from the terminal and sped up. OpenReflex had seen one similar task in this repository, so it adds 162 tokens of context before the first tool call; after the fix, Claude records the outcome through OpenReflex's MCP tool. The step-by-step walkthrough is in <a href="docs/walkthrough.md">docs/walkthrough.md</a>.</sub>
+</p>
 ## Why OpenReflex
 - **It remembers what worked.** Before a substantial task, OpenReflex retrieves similar past tasks and injects a
   compact Execution Context: a suggested approach with alternatives, the files that were changed, and lessons
   such as which edit resolved a recurring error.
 - **It catches loops while they happen.** Repeated failing commands, identical retries, stalled progress, and
-  runaway context growth raise a single, specific alert with an alternative path, never a stream of nags.
+  runaway context growth raise one alert that says whether to continue, pivot to another approach, or stop and
+  check in with you, never a stream of nags.
 - **It learns after every task.** OpenReflex infers the outcome from real verification (a test or build that
   passed or failed after the last edit), estimates Execution Regret against the alternatives, and extracts lessons.
 - **It is private by design.** Only coarse, project-relative metadata is stored. File contents, commands, tool
   output, and transcripts never are, and capture is off until you approve a project.
-```
-        before a task                  during a task                 after a task
-  ┌──────────────────────┐    ┌──────────────────────────┐    ┌───────────────────────┐
-  │ retrieve experience  │    │ watch tool calls         │    │ infer outcome         │
-  │ score candidate paths│ →  │ flag loops and stalls    │ →  │ estimate regret       │
-  │ inject context       │    │ suggest an alternative   │    │ extract lessons       │
-  └──────────────────────┘    └──────────────────────────┘    └───────────────────────┘
-                 ▲                                                        │
-                 └──────────────────── Experience Graph ◄─────────────────┘
-```
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/how-it-works-dark.svg">
+    <img alt="Before a task: retrieve similar experience, score candidate paths, inject context and a budget. During a task: watch every tool call, flag loops and stalls, advise continue, pivot or stop. After a task: infer the outcome from checks, estimate Execution Regret, extract lessons. Lessons feed the Experience Graph for the next task." src="https://raw.githubusercontent.com/vishnu-77/openreflex/main/assets/how-it-works-light.svg" width="860">
+  </picture>
+</p>
 ## Quick start
@@ -95,6 +99,19 @@ cd your-project
 openreflex install claude-code     # writes hooks + MCP config and enables this project
 ```
+```
+OPENREFLEX / CONNECT
+  agent       claude-code
+  project     D:\demo\shop
+  config      updated 2 files
+              D:\demo\shop\.claude\settings.json
+              D:\demo\shop\.mcp.json
+  memory      enabled
+  storage     local
+  [ok] reflex active
+```
 Then work as usual. After a few tasks:
 ```bash
@@ -107,37 +124,16 @@ openreflex doctor                                 # installation checks and rece
 OpenReflex installs per project with `openreflex install <agent>`, or as a plugin.
-<table>
-  <tbody>
-    <tr>
-      <td align="center" valign="bottom" width="25%"><strong>Claude&nbsp;Code</strong><br><sub>Plugin&nbsp;or&nbsp;hooks&nbsp;+&nbsp;MCP</sub></td>
-      <td align="center" valign="bottom" width="25%"><strong>Codex</strong><br><sub>Plugin&nbsp;or&nbsp;hooks&nbsp;+&nbsp;MCP</sub></td>
-      <td align="center" valign="bottom" width="25%"><strong>Cursor</strong><br><sub>Hooks&nbsp;+&nbsp;MCP</sub></td>
-      <td align="center" valign="bottom" width="25%"><strong>OpenCode</strong><br><sub>Plugin&nbsp;+&nbsp;MCP</sub></td>
-    </tr>
-  </tbody>
-</table>
-| Agent | Install |
-|---|---|
-| Claude Code | `claude plugin marketplace add vishnu-77/openreflex` and `claude plugin install openreflex@openreflex`, or `openreflex install claude-code` |
-| Codex | `codex plugin marketplace add vishnu-77/openreflex`, or `openreflex install codex`, then trust the hooks once in `/hooks` |
-| Cursor | `openreflex install cursor` |
-| OpenCode | `openreflex install opencode` |
-With a plugin install, enable each project with `openreflex approve`. Claude Code and Codex are verified in live
-sessions; the Cursor and OpenCode integrations follow each agent's documented hook protocol.
-## See it work
+| Agent | Connects through | Install | Verified |
+|---|---|---|---|
+| **Claude Code** | Plugin, or hooks + MCP | `claude plugin marketplace add vishnu-77/openreflex` then `claude plugin install openreflex@openreflex`, or `openreflex install claude-code` | Live sessions |
+| **Codex** | Plugin, or hooks + MCP | `codex plugin marketplace add vishnu-77/openreflex`, or `openreflex install codex`, then trust the hooks once in `/hooks` | Live sessions |
+| **Cursor** | Hooks + MCP | `openreflex install cursor` | Protocol and fuzz tests |
+| **OpenCode** | Plugin + MCP | `openreflex install opencode` | Protocol and fuzz tests |
-A real Claude Code session in a repository where OpenReflex has seen one similar task before. The
-`UserPromptSubmit` line shows the past experience found and the context added; the `Stop` line shows the verified
-outcome, the path taken and the cost.
-![Claude Code session with OpenReflex](https://raw.githubusercontent.com/vishnu-77/openreflex/main/docs/screenshots/claude-code-session-2.png)
-The full walkthrough, with both sessions, the exact context the model received and the CLI output, is in
-[docs/walkthrough.md](docs/walkthrough.md).
+With a plugin install, enable each project with `openreflex approve`. Per-agent guides:
+[Claude Code](https://openreflex.cc/claude-code), [Codex](https://openreflex.cc/codex), [Cursor](https://openreflex.cc/cursor),
+[OpenCode](https://openreflex.cc/opencode).
 ## How it works
@@ -177,10 +173,27 @@ Set optional limits for every task with `OPENREFLEX_BUDGET`, for example `calls=
 Routing, scoring, budget and recap settings come from a versioned policy: the packaged defaults, overridden by
 `~/.openreflex/config.toml` and then by `.openreflex.toml` in the project.
-Agents can also query OpenReflex directly through its MCP server: `get_execution_context` (optionally with
-`max_tool_calls`, `max_minutes`, `max_context_tokens`), `choose_path`, `check_progress`, `explain_decision`,
-`get_execution_trace`, `get_reflex_score`, `record_outcome`, `search_experience`, `explain_node`,
-`get_project_insights`, `approve_project`, and `forget_experience` (deletes one past task's memory, only when the user asks).
+Agents can also query OpenReflex directly through its MCP server.
+<details>
+<summary><strong>The 12 MCP tools</strong></summary>
+| Tool | What it does |
+|---|---|
+| `get_execution_context` | Plan a task: similar past tasks, the suggested strategy with alternatives, a budget, likely files, lessons. Optional `max_tool_calls`, `max_minutes`, `max_context_tokens`. |
+| `check_progress` | Whether more work on the current path is worth it: continue, pivot or stop. |
+| `choose_path` | Declare the strategy being followed when it differs from the suggestion. |
+| `record_outcome` | Record a verified outcome (tests passed, user confirmed, or failure) and learn from it. |
+| `explain_decision` | Why the latest recommendation was made: Reflex Score, signals, confidence, next-best route. |
+| `get_execution_trace` | The decision timeline of the most recent task. |
+| `get_reflex_score` | The latest Reflex Score and its components as JSON. |
+| `search_experience` | Past tasks in the project by description similarity, with their lessons. |
+| `explain_node` | One Experience Graph node and its relations. |
+| `get_project_insights` | What has been recorded, reused and learned in the project. |
+| `approve_project` | Enable capture, only when the user explicitly asks. |
+| `forget_experience` | Delete one past task's memory, only when the user explicitly asks. |
+</details>
 ## CLI
@@ -199,12 +212,26 @@ Agents can also query OpenReflex directly through its MCP server: `get_execution
 ## Privacy
-- Stored per tool call: tool name, a coarse category (`read`, `edit`, `search`, `test`, ...), a fingerprint of the
-  arguments, project-relative file paths, status, duration, output size, and a masked one-line error signature.
-- Never stored: file contents, command text, tool output, transcripts, or paths outside the project.
-- Prompts are kept as task descriptions (up to 1,000 characters) with secrets such as API keys and tokens redacted.
-- Data lives in `~/.openreflex/projects/<hash>/experience.sqlite3`. Set `OPENREFLEX_HOME` to move it,
-  `OPENREFLEX_DISABLE=1` to turn capture off everywhere, or run `openreflex forget --yes` to delete a project's data.
+| Stored | Never stored |
+|---|---|
+| Tool name and a coarse category (`read`, `edit`, `search`, `test`, ...) | File contents |
+| A fingerprint of the arguments | Command text |
+| Project-relative file paths | Tool output |
+| Pass or fail, duration, output size | Transcripts and model output |
+| A masked one-line error signature | Paths outside the project |
+| The prompt as a task description (up to 1,000 characters, secrets redacted) | Anything sent to a server: there is none |
+Data lives in `~/.openreflex/projects/<hash>/experience.sqlite3`. Set `OPENREFLEX_HOME` to move it,
+`OPENREFLEX_DISABLE=1` to turn capture off everywhere, `openreflex forget --yes` to delete a project's data, or ask
+your agent to `forget_experience` a single task.
+## Research
+OpenReflex is also a research project in budget-aware execution: instead of treating success as a yes or no, it
+studies how agents choose execution paths, spend tool calls and context, respond to uncertainty, and whether more
+computation still adds value. The loop is experience retrieval, Pareto path selection, budget-aware execution and
+counterfactual regret. The [Researcher view](https://openreflex.cc/?view=research) on the site explains the idea,
+lets you step through one reflex forming in the graph, and places it next to related work.
 ## Community & Contributing
@@ -222,6 +249,12 @@ Agents can also query OpenReflex directly through its MCP server: `get_execution
   <img src="https://contrib.rocks/image?repo=vishnu-77/openreflex" alt="Contributors">
 </a>
+OpenReflex is listed in the [MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.vishnu-77/openreflex` and on Glama:
+<a href="https://glama.ai/mcp/servers/vishnu-77/openreflex">
+  <img src="https://glama.ai/mcp/servers/vishnu-77/openreflex/badges/card.svg" alt="OpenReflex MCP server: quality and maintenance score on Glama" width="380">
+</a>
 ## License
 OpenReflex is released under the [MIT License](https://github.com/vishnu-77/openreflex/blob/main/LICENSE).

{openreflex-0.3.1 → openreflex-0.3.2}/tests/test_hooks.py RENAMED Viewed

@@ -167,3 +167,30 @@ def test_codex_apply_patch_exit_code_zero_is_success():
                                                      "tool_input": {"command": "*** Begin Patch\n*** Update File: dates.py\n"},
                                                      "tool_response": response})
     assert event.success is True
+@pytest.mark.parametrize("tool_name", ["", None, ["Bash"], 7])
+def test_tool_event_without_a_tool_name_records_nothing(project, factory, tool_name):
+    approve(project)
+    payload = {"session_id": "s", "cwd": str(project), "tool_name": tool_name, "tool_input": {"command": "ls"},
+               "tool_use_id": "t1", "tool_response": {"stdout": "ok"}}
+    assert call("claude-code", "PreToolUse", payload, factory) == ""
+    assert call("claude-code", "PostToolUse", payload, factory) == ""
+    engine = factory(project)
+    assert engine.store.list("Task") == [] and engine.store.list("ToolCall") == []
+def test_why_and_trace_survive_later_activity_without_a_prompt(project, factory, clock):
+    approve(project)
+    base = {"session_id": "planned", "cwd": str(project)}
+    call("claude-code", "UserPromptSubmit", {**base, "prompt": "Fix the pricing bug where the SAVE15 coupon takes too little off"},
+         factory)
+    clock.advance(30)
+    # A different session then runs a tool with no captured prompt, which creates an untracked task.
+    other = {"session_id": "resumed", "cwd": str(project), "tool_name": "Read", "tool_input": {"file_path": "README.md"},
+             "tool_use_id": "r1", "tool_response": {"content": "x"}}
+    call("claude-code", "PreToolUse", other, factory)
+    call("claude-code", "PostToolUse", other, factory)
+    engine = factory(project)
+    assert "No decision snapshot" not in engine.why() and "Recommendation" in engine.why()
+    assert "START" in engine.trace()