Documentation
OpenReflex docs
OpenReflex is an open-source plugin that helps AI coding agents learn from every task. It reuses what worked, catches failure loops while they happen, and keeps everything on your machine.
Install
OpenReflex needs Python 3.11 or newer. Install the CLI with pipx, uv or pip.
$
pipx install openreflexThen install it for your agent. Nothing is recorded until a project is enabled; openreflex install enables the project for you.
Set up your agent
OpenReflex for Claude CodeMake Claude Code learn from every task. OpenReflex adds lifecycle hooks and an MCP server that reuse past fixes and catch failure loops, locally.OpenReflex for CodexGive OpenAI Codex CLI a memory of what worked. OpenReflex adds hooks and an MCP server that reuse past fixes and flag failure loops, all locally.OpenReflex for CursorHelp Cursor's agent learn from every task. OpenReflex adds Cursor hooks and an MCP server that reuse past fixes and flag failure loops, locally.OpenReflex for OpenCodeAdd learning to OpenCode. The OpenReflex plugin and MCP server reuse past fixes, flag failure loops and keep all data on your machine.
CLI reference
| Command | What it does |
|---|---|
| openreflex install <agent> | Write hooks and MCP config for claude-code, codex, cursor or opencode, and enable the project. Add --dry-run to preview. |
| openreflex approve | Enable capture for the current project (needed after a plugin install). |
| openreflex revoke | Disable capture for the current project. Existing data is kept. |
| openreflex context "<task>" | Preview the Execution Context a task would receive, without recording anything. |
| openreflex status [--json] | Show what has been captured, reused and learned in this project. |
| openreflex doctor | Check the installation and show recent hook errors. |
| openreflex forget --yes | Delete all captured data for the project. |
| openreflex benchmark | Run the simulated benchmark suite. |
| openreflex mcp | Start the MCP server over stdio (used by agent configs). |
MCP tools
The OpenReflex MCP server runs over stdio. Agent installs register it automatically; any other MCP client can add it:
{
"mcpServers": {
"openreflex": { "command": "openreflex", "args": ["mcp"] }
}
}| Tool | What it does |
|---|---|
| get_execution_context | Retrieve relevant past experience, scored candidate strategies, likely files and lessons for a task. |
| choose_path | Declare the strategy the agent is following, so the outcome is compared against the right plan. |
| record_outcome | Record a verified outcome, such as tests passing, with short evidence. |
| search_experience | Search past tasks in the project by description. |
| explain_node | Show an Experience Graph node and its relations. |
| project_insights | Summarise capture, reuse, outcomes and learning for the project. |
| approve_project | Enable the project, only when the user explicitly asks. |
Privacy and data
- Kept: tool names and categories, a fingerprint of each call's arguments, project-relative file paths, pass or fail, duration, output size, and a masked one-line error signature.
- Never kept: file contents, command text, tool output, transcripts, or paths outside the project.
- Prompts: stored as a task description of up to 1,000 characters, with keys and tokens redacted.
- Location:
~/.openreflex/projects/<hash>/experience.sqlite3. SetOPENREFLEX_HOMEto move it orOPENREFLEX_DISABLE=1to turn capture off everywhere.
Troubleshooting
- Nothing is being captured
- Run openreflex doctor. Check the project is enabled (openreflex approve) and that the openreflex command is on your PATH.
- Hooks seem to do nothing in Codex
- Open /hooks in Codex and trust the OpenReflex entries; untrusted hooks do not run.
- Where are hook errors logged?
- In ~/.openreflex/logs/errors.log. Hooks never block your agent, so errors are recorded there instead of shown.
- No context was injected
- Context is only added when relevant past experience exists, so a new project starts silent.
Still stuck? Open an issue on GitHub.