What is OpenReflex
OpenReflex gives AI coding agents ambient project muscle memory across coding, investigation, and reasoning work.
Lifecycle hooks quietly record how work actually goes, compile repeated project behaviour into reusable Reflexes,
and inject only the relevant project procedure into new tasks. The model does not need to remember to call OpenReflex,
and MCP diagnostics are opt-in rather than loaded into normal agent context.
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. Claude Code token counts are read from the session transcript
Claude Code already writes locally, and only counts are stored. openreflex tokens enable optionally adds estimated
cost through Claude Code's OpenTelemetry export to a loopback-only receiver.
[Recording of a Claude Code session with OpenReflex: OpenReflex injects compact prior context, Claude fixes the task and runs verification, and lifecycle hooks close the outcome automatically]
A recorded Claude Code session. OpenReflex injects compact relevant context before work; lifecycle hooks capture tools and verification and close the execution automatically. MCP is not required for the normal path. The step-by-step walkthrough is in docs/walkthrough.md.
Why OpenReflex
- It learns how the project behaves. OpenReflex compiles successful work into project-scoped Reflexes such as
authentication changes, Helm configuration, database migrations or CI work. Resolution combines semantic intent,
task family and module/file locality, so a novel task can reuse a project procedure without repeating an
earlier task.
- 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.
[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: close the outcome using evidence appropriate to the work, run a simple Path check, extract lessons. Lessons feed the Experience Graph for the next task.]
Quick start
Requires Python 3.11 or newer.
Claude Code — recommended: install the plugin, reload it, inspect the current state, then explicitly enable
project memory.
Claude may display the canonical plugin namespace as /openreflex:openreflex; both refer to the same user-invoked
OpenReflex control surface when the bare alias is available. The no-argument command is read-only and compact.
approve explicitly enables local memory for the current project. The plugin prepares an exact-version runtime
under ~/.openreflex/runtime/ and normal agent work remains ambient after approval.
The Claude plugin does not execute a global openreflex from PATH. An older pipx/uv/pip installation can coexist
without taking over the plugin runtime.
CLI / other agents: use a persistent package install.
After a few tasks:
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. The Claude plugin manages
its own pinned runtime automatically; these package-manager commands are only needed for standalone CLI installs.
Use it with your agent
OpenReflex installs per project with openreflex install <agent>, or as a plugin.
With the Claude plugin, /openreflex shows a compact read-only state view. Use /openreflex approve to enable
local memory for the current project, then work normally. Other explicit controls include status, reflexes,
memory, doctor, why, trace, and revoke. OpenReflex control turns are not learned as project
experiences and do not trigger normal task verification. The control skill is user-invoked only and does not enable
MCP diagnostics or participate in normal model routing. Claude may show the canonical namespaced form
/openreflex:openreflex. 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:
- 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.
Injected text is re-read by every later API call, so context is injected only when it is specific to the task:
a matched Reflex, or a lesson about a failure already seen in this project. One substantial task in five (the
evaluation.holdout_percent policy value) is a holdout: OpenReflex records it but shows nothing, so
openreflex status can compare model tokens per task with and without OpenReflex.
- Between tasks (Claude Code): when a new, unrelated task starts in a session already carrying a large history
(
context.reset_hint_tokens), OpenReflex suggests /clear to you; the model never sees the suggestion. After
/clear, the new session gets a short summary of the cleared task instead of its full history.
- During a task: an identical call that already failed twice, with no edit or passing check since, is refused
before it runs (Claude Code) or flagged (other agents). The first failure with an error this project has resolved
before shows what resolved it. When a detector finds a failure loop, repeated calls, stalled progress or context
growth, OpenReflex estimates the marginal value of more work. Over-budget alerts are off by default; set
detectors.over_budget_tiers to turn them on. 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: lifecycle hooks close the execution automatically from work-mode-appropriate evidence; the model
does not need to call OpenReflex. Explicit MCP outcome/path operations remain available only for manual or diagnostic
workflows. 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.
Normal work does not load OpenReflex MCP tools. If you explicitly want model-facing introspection for a project,
enable it with openreflex diagnostics enable <agent>. Disable it again with
openreflex diagnostics disable <agent>. The standalone MCP Registry package remains available for users who
deliberately install OpenReflex as an MCP server.
The optional MCP diagnostics/admin tools
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.
The reproducible evaluation protocol, pinned real-agent corpus, exact prompts, and claim boundaries are documented in docs/evaluation.md.
Community & Contributing
[Contributors]
OpenReflex is listed in the MCP Registry as io.github.vishnu-77/openreflex and on Glama:
[OpenReflex MCP server: quality and maintenance score on Glama]
License
OpenReflex is released under the MIT License.
