OpenReflex

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

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. Optional Claude token accounting uses Claude Code's local OpenTelemetry export to a loopback-only OpenReflex receiver and stores counts only.

_{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.

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.

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

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.

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

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. 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:

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