Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@OpenReflex get execution context for refactoring the auth module"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Website · GitHub · PyPI · Issues · Buy me a coffee
OpenReflex gives AI coding agents muscle memory. 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 what worked before: the approach, the files that mattered, and the fix for the error you hit last time.
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.
Related MCP server: LumenCore
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.
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 ◄─────────────────┘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 projectThen 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 errorsOpenReflex installs per project with openreflex install <agent>, or as a plugin.
Agent | Install |
Claude Code |
|
Codex |
|
Cursor |
|
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.
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-> LessonBefore a task: similar experiences are retrieved, three strategies (inspect-first, test-first,
incremental) are scored on success probability, time, tool calls, context cost, risk, uncertainty, and
reversibility, and a context of at most 1,400 characters is injected. Nothing is injected without relevant
experience.
During a task: each alert fires at most once per task with a cooldown, and names a concrete alternative.
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 tool activity. Execution Regret is withheld when the outcome is unknown.
Agents can also query OpenReflex directly through its MCP server: get_execution_context, choose_path,
record_outcome, search_experience, explain_node, project_insights, and approve_project.
Command | Purpose |
| Write project hooks and MCP config, and enable the project |
| Enable or disable capture for the current project |
| Preview the Execution Context a task would receive |
| What has been captured, reused, and learned |
| Installation checks and recent hook errors |
| Delete the project's data |
| Run the simulated benchmark |
| Used by agent configs |
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.
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 scriptsOpenReflex is released under the MIT License.
Enable OpenReflex capture for this project. Only call when the user explicitly asked to enable it.
| Name | Required | Description | Default |
|---|---|---|---|
| confirm | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the full behavioral load. It does communicate that this is a mutating 'enable' operation and imposes an explicit user-consent guard. However, it does not disclose side effects, idempotence, or what happens if the feature is already enabled or if confirmation is needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, direct sentences: the first states the action and the second states the invocation guard. Every word earns its place and the description is immediately actionable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool itself is simple and has an output schema, but the unexplained confirm parameter leaves the invocation ambiguous. The description is clear about intent and timing but not about the actual input needed to complete the call.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description never mentions the critical confirm parameter, and schema description coverage is 0%. An agent cannot determine from the tool definition whether it should set confirm to true or false, making this the definition's largest gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific action and resource: 'Enable OpenReflex capture for this project.' This clearly identifies what the tool does and distinguishes it from siblings like get_execution_context, choose_path, and record_outcome, which have unrelated responsibilities.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides an explicit precondition: 'Only call when the user explicitly asked to enable it.' This gives the agent clear guidance about when the tool is appropriate and prevents unsolicited invocation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Declare the strategy you are following (a suggested one like 'test-first', or your own with steps). Improves regret analysis, which otherwise infers the path from tool activity.
| Name | Required | Description | Default |
|---|---|---|---|
| steps | No | ||
| strategy | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral burden. It discloses that calling this tool records the declared strategy and that this improves regret analysis, which would otherwise infer the path from tool activity. It does not mention idempotency, overwrite behavior, or persistence, but for a simple declaration tool the key effect is conveyed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loads the core action, and uses the second sentence to explain the benefit. There is no fluff or repetition of schema information, and every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a low-complexity tool with two parameters and an output schema, the description covers the purpose, the main parameter semantics, and the downstream effect on regret analysis. It is complete enough for an agent to invoke it correctly, though a slightly more explicit statement about when to call it would make it fully self-contained.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must add meaning to the parameters. It does this by explaining that 'strategy' can be a suggested one like 'test-first' or a custom one, and that 'steps' belong to a custom strategy. This gives useful semantic context beyond the bare schema titles, though it could be more explicit about the exact role of 'steps'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Declare') and a clear resource ('the strategy you are following'), with a concrete example ('test-first'). It clearly distinguishes this tool from siblings like record_outcome or search_experience by its intent: declaring an intentional strategy rather than recording outcomes or exploring data.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies when to use the tool: whenever you are following a strategy and want to improve regret analysis. It also contrasts with the default behavior of inferring the path from tool activity. It does not explicitly list exclusions or alternative tools, but the context is clear enough for an agent to decide.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show an Experience Graph node and its direct relations (used, caused, failed_with, resolved_by, recommended_for). Embeddings are omitted.
| Name | Required | Description | Default |
|---|---|---|---|
| node_id | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context by noting that embeddings are omitted, which indicates a scope limitation. However, it does not explicitly state that the tool is read-only, nor does it mention any side effects, error conditions, or rate limits. The omission of embeddings is a positive step, but more behavioral detail would be expected for a tool with no annotation safety hints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence that front-loads the core action and resource. It efficiently lists the relation types and the notable omission of embeddings without superfluous words. It sacrifices some usage guidance for brevity, but the structure is clean and directly on point.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter) and the presence of an output schema, the description covers the essential behavior: showing a node and its direct relations. It also discloses the embedding omission. However, it lacks any guidance on error handling, edge cases (e.g., invalid node_id), or how the output is structured beyond what the schema might imply. Still, for a straightforward read tool, it is adequately complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage for the sole parameter `node_id`, and the description does not explicitly explain its meaning or format. While the action 'Show an Experience Graph node' implies that `node_id` identifies the node, the description adds minimal value beyond the schema's type definition. With 0% coverage, the description should compensate by specifying the parameter's semantics, which it fails to do in any detail.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the specific verb 'Show' and clearly identifies the resource as an 'Experience Graph node'. It enumerates the direct relation types, making the tool's focus explicit. However, it does not differentiate from sibling tools like search_experience or get_execution_context, so the purpose is clear but not uniquely positioned.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states what the tool does but offers no guidance on when to use it versus alternatives. It does not mention any preconditions, required permissions, or scenarios where this tool would be preferred over siblings like search_experience or choose_path. The usage context is only implied by the tool's name and action, not explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Retrieve relevant past experience for a task, with 2-3 scored candidate strategies, likely files, and lessons. Call before substantial work when no [OpenReflex] context was injected.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It implies a read-only operation via 'Retrieve' and mentions the output, but it does not explicitly state side-effect behavior, read-only status, or any limitations. It could benefit from stating that it does not modify state, making it a moderate 3.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action and output, followed by a clear usage condition. No extraneous words; every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given only one parameter and the existence of an output schema, the description covers the essential aspects: what it does, what it returns, and when to call it. It does not explain the output schema structure, but that is covered by the output schema itself.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single 'task' parameter. The description mentions 'for a task' which gives some context, but does not elaborate on the expected format or content of the task string. Since the parameter is a simple string, this is acceptable but minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb (Retrieve) and resource (relevant past experience for a task), and specifies the output (2-3 scored candidate strategies, likely files, and lessons). However, it does not explicitly differentiate from sibling tools like search_experience, which might also retrieve past experience, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides an explicit trigger condition: 'Call before substantial work when no [OpenReflex] context was injected.' This tells the agent when to use it, but it does not mention when not to use it or name alternatives, so it is not a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Capture health, experience reuse, efficiency, Execution Regret trend and routing agreement.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not state whether the tool reads or writes, requires permissions, or has side effects. 'Capture' could imply mutation, but it is not explicit. The description lacks any behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence that lists several aspects. It is not verbose and is front-loaded with the verb 'capture.' However, the conciseness comes at the cost of clarity; it is short but cryptic, so it is not a model of effective conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although there is an output schema and no parameters, the description fails to explain the purpose, return value, or when to use the tool. The terms like 'health', 'experience reuse', and 'Execution Regret trend' are unqualified. For a tool with siblings like record_outcome and search_experience, this description is incomplete and leaves an agent guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and the schema fully documents that (100% coverage). The description adds nothing about parameters, but since there are none, the baseline of 4 applies. No extra meaning is needed or provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'capture' which is ambiguous—it could mean retrieve or record. The resource is 'health, experience reuse, efficiency, Execution Regret trend and routing agreement,' but these are abstract concepts and there is no indication of what operation is performed on them. It does not distinguish from siblings like record_outcome or search_experience, so an agent cannot tell what this tool actually does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives. No mention of context, conditions, or exclusions. The description is purely a vague list of topics and does not help an agent decide between this and sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Record the verified outcome of the current task, e.g. status='success', evidence='pytest -q passed'.
| Name | Required | Description | Default |
|---|---|---|---|
| status | Yes | ||
| evidence | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the burden. It discloses that this is a write operation but not whether repeated calls overwrite, whether it finalizes the task, or any authorization requirements. For a mutation tool with zero annotation coverage, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence plus an example, with no filler. The key action and example are front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an output schema, the core call is well specified. However, absence of annotations leaves open questions about side effects and repeatability that a more complete description would address.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate. The example maps status and evidence to concrete values ('success', 'pytest -q passed'), which clarifies intended usage, but it doesn't explain acceptable evidence formats or edge cases beyond the schema's enum.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('record') and resource ('verified outcome of the current task') with a concrete example. It is clearly distinct from sibling tools, though it doesn't explicitly contrast with them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'verified outcome' and 'current task' give contextual guidance for when to call: after verifying a task result. It doesn't explicitly state when not to use it or mention alternatives, but siblings serve different functions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search past task experiences in this project by description similarity.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. The word 'Search' implies a read-only operation, and 'by description similarity' adds a useful behavioral detail about how matching works. However, it does not explicitly disclose side effects, result ordering, or any limitations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, tightly worded sentence conveys the essential purpose without redundancy. The core action and resource are front-loaded, and every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple two-parameter tool with an output schema, the description is minimally adequate. It names the target data and search semantics, but omits when-to-use context and any behavioral caveats, so an agent has enough to invoke it but not to choose it confidently among siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It does clarify that 'query' is matched against description similarity, but it says nothing about the 'limit' parameter beyond the schema's default value, leaving its meaning and constraints implicit.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the verb ('Search'), the resource ('past task experiences'), and the matching method ('by description similarity'). This distinguishes it from sibling tools like project_insights or explain_node, which focus on broader analysis or explanation rather than retrieval.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no guidance on when to use this tool versus alternatives such as project_insights or choose_path. It does not state prerequisite conditions, exclusions, or situations where another sibling would be more appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.3approve_projectchoose_pathexplain_nodeget_execution_contextproject_insightsrecord_outcomesearch_experienceScored across 7 tools
Each tool serves a distinct function: context retrieval, strategy declaration, outcome recording, experience search, graph exploration, insights, and project approval. There is no overlap in purpose.
Most tools follow a consistent verb_noun pattern (get_, choose_, record_, search_, explain_, approve_), but 'project_insights' breaks the pattern by being noun-first. Overall readable and predictable.
Seven tools is well-scoped for an experience management server, covering retrieval, capture, strategy, insights, and activation without being sparse or bloated.
The tool surface covers the core lifecycle (retrieve, capture, declare, search, inspect, analyze) but lacks explicit editing or deletion of experiences, a minor gap for full CRUD coverage.
Shared memory for coding agents. Stop re-explaining your codebase every session.
Persistent memory and knowledge graphs for AI agents. Hybrid search, context checkpoints, and more.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Persistent memory for AI agents. Search, store, and recall across sessions.
