openreflex 0.5.0

Website · Docs · Walkthrough · PyPI · Issues · Buy me a coffee

What is OpenReflex

OpenReflex gives AI coding agents muscle memory across coding, investigation, and reasoning work. It plugs into Claude Code, Codex, Cursor, and OpenCode through lifecycle hooks and MCP, quietly records how each task actually went, and hands the next similar task the useful parts of that experience.

You install it once and keep working normally. Core memory stays on your machine in a local SQLite database. There is no OpenReflex account or hosted service. Optional Claude token accounting uses Claude Code's local OpenTelemetry export to a loopback-only OpenReflex receiver and stores counts only.

_{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 docs/walkthrough.md.}

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 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. Build work closes against tests/lint/build evidence; investigations can close against cross-checked sources; reasoning-only work can complete without external tools. A simple Path check only names a better option when comparable past tasks actually support one.
• 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.

Quick start

Requires Python 3.11 or newer.

pipx install openreflex            # or: uv tool install openreflex
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:

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

Package updates preserve local memory and project configuration. Managed pipx and uv tool installs can use openreflex update, openreflex update --reinstall, or openreflex self reinstall. To remove only the package, use openreflex self uninstall --yes; project memory is preserved. A fresh bootstrap still starts with pipx install openreflex or uv tool install openreflex because the openreflex command does not exist before installation.

Use it with your agent

OpenReflex installs per project with openreflex install <agent>, or as a plugin.

With a plugin install, enable each project with openreflex approve. Per-agent guides: Claude Code, Codex, Cursor, OpenCode.

How it works

Hooks send lifecycle events (prompt, tool start, tool end, compaction, stop) to the OpenReflex engine, which stores them in an 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

• Before a task: similar experiences are retrieved and OpenReflex first identifies the work mode. BUILD uses inspect-first, test-first, and incremental; INVESTIGATE uses source-first, cross-check, and broad-then-deep; THINK uses reason-first, compare-options, and evidence-first. Paths are ranked using past evidence, estimated cost, risk, uncertainty and reversibility. A compact context is injected only when relevant experience exists.
• During a task: when a detector finds a failure loop, repeated calls, stalled progress, context growth, or work past the budget, OpenReflex estimates the marginal value of more work. The current path's success estimate is updated with each call that makes no progress or fails, and compared with the cost of the work left and with the best untried alternative. The alert ends with a recommendation to continue, pivot to another strategy, or stop and ask the user. Each problem, pivot, or stop is raised once, with a cooldown between messages.
• After a task: outcome and chosen path come from the agent's record_outcome / choose_path MCP calls when available, and are otherwise inferred from work-mode-appropriate evidence. The Path check says either better option: <path> when comparable completed tasks support it or better option: none proven. Recommendations are never presented as paths that were actually executed.

Every recommendation is stored as a decision snapshot with a Reflex Score (0-100): how strong the recommendation is, which is separate from the estimated chance that the task succeeds. openreflex why explains the latest decision and openreflex trace shows the timeline. In Claude Code, a short recap appears when a task starts, when OpenReflex recommends a pivot or stop or detects trouble, and when the task completes.

Set optional limits for every task with OPENREFLEX_BUDGET, for example calls=40,minutes=20,tokens=60000. 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.

CLI

Privacy

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, model tokens and context, respond to uncertainty, and whether past work makes similar future work cheaper without reducing outcome quality. The loop is experience retrieval, evidence-aware path selection, budget-aware execution, work-mode-specific completion and plain-language path comparison. The Researcher view 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

• Issues and ideas: GitHub Issues

• Support the project: Buy me a coffee

• Develop locally:

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

OpenReflex is listed in the MCP Registry as io.github.vishnu-77/openreflex and on Glama:

License

OpenReflex is released under the MIT License.