OpenReflex

---

OpenReflex とは

OpenReflex は、コーディング、調査、推論の作業全体で、AI コーディングエージェントにプロジェクト固有の知識を自然に身につけさせます。 ライフサイクルフックが作業の実際の進め方をひそかに記録し、繰り返されるプロジェクトの振る舞いを再利用可能な Reflex にまとめ、新しいタスクには関連するプロジェクト手順だけを挿入します。モデルが OpenReflex の呼び出しを覚えておく必要はなく、MCP の診断機能は通常のエージェントコンテキストに読み込まれず、必要な場合にのみ有効にできます。

一度インストールすれば、普段どおり作業を続けられます。中核となるメモリは、ローカルの SQLite データベースに保存され、マシンの外に出ることはありません。OpenReflex のアカウントやホスト型サービスはありません。Claude Code のトークン数は、Claude Code がローカルに書き込むセッショントランスクリプトから読み取られ、保存されるのはその数だけです。openreflex tokens enable を実行すると、オプションで Claude Code の OpenTelemetry エクスポートを通じて、ループバック接続のみを受け付けるレシーバーに推定コストを追加できます。

_{Claude Code セッションの録画です。OpenReflex は作業の前に関連するコンテキストを簡潔に挿入します。ライフサイクルフックはツールの使用状況と検証結果を記録し、実行を自動的に完了します。通常の利用に MCP は必要ありません。手順を追った操作ガイドは docs/walkthrough.md にあります。}

## OpenReflex を選ぶ理由

• プロジェクトの動作を学習します。 OpenReflex は、認証の変更、Helm の設定、データベースのマイグレーション、CI の作業など、成功した作業をプロジェクト単位の Reflexes にまとめます。解決時には、意味的な意図、タスクの種類、モジュールやファイルの関連性を組み合わせるため、これまでに取り組んだことのないタスクでも、過去のタスクを繰り返すことなくプロジェクトの手順を再利用できます。
• ループを発生時に検出します。 失敗するコマンドの繰り返し、同じ内容の再試行、進捗の停滞、コンテキストの際限ない増大を検出すると、続行するか、別の方法に切り替えるか、停止して確認を求めるかを示すアラートを1つだけ通知します。通知が何度も繰り返されることはありません。
• タスクのたびに学習します。 ビルド作業は、テスト、lint、ビルドの証拠をもとに完了とします。調査は、複数の情報源を照合して完了とできます。推論のみの作業は、外部ツールを使わずに完了できます。シンプルな Path check は、同等の過去のタスクがよりよい選択肢を実際に裏付けている場合にのみ、その選択肢を示します。
• プライバシーを設計段階から重視しています。 保存されるのは、大まかなプロジェクト相対のメタデータのみです。ファイルの内容、コマンド、ツールの出力、トランスクリプトは保存されません。また、プロジェクトを承認するまでは情報の記録は無効です。

クイックスタート

Python 3.11 以降が必要です。

Claude Code — 推奨： プラグインをインストールして再読み込みし、現在の状態を確認した後、プロジェクトのメモリを明示的に有効にします。

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

Claude では、正規のプラグイン名前空間が /openreflex:openreflex と表示されることがあります。短縮エイリアスが利用可能な場合、どちらもユーザーが呼び出す同じ OpenReflex の操作画面を指します。引数なしのコマンドは読み取り専用で、出力は簡潔です。approve を実行すると、現在のプロジェクトでローカルメモリが明示的に有効になります。プラグインは ~/.openreflex/runtime/ に正確なバージョンのランタイムを用意します。承認後は、通常のエージェント作業がバックグラウンドで行われます。

Claude プラグインが、PATH 上のグローバルな openreflex を実行することはありません。以前にインストールした pipx／uv／pip 版と共存でき、プラグインのランタイムがそれらに置き換わることもありません。

CLI／その他のエージェント： パッケージを常時利用できるようにインストールします。

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

いくつかのタスクを実行した後：

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

パッケージを更新しても、ローカルメモリとプロジェクト設定は保持されます。管理対象の pipx および uv tool のインストールでは、openreflex update、openreflex update --reinstall、または openreflex self reinstall を使用できます。Claude プラグインは固定されたランタイムを自動で管理するため、これらのパッケージマネージャー用コマンドが必要なのは、単独で CLI をインストールした場合のみです。

エージェントで使用する

OpenReflex は、プロジェクトごとに openreflex install <agent> でインストールするか、プラグインとしてインストールできます。

エージェント	接続方法	インストール	検証済み
Claude Code	プラグインフック、またはプロジェクトフック	claude plugin marketplace add vishnu-77/openreflex を実行してから claude plugin install openreflex@openreflex を実行するか、openreflex install claude-code を実行	ライブセッション
Codex	プラグインフック、またはプロジェクトフック	codex plugin marketplace add vishnu-77/openreflex を実行するか、openreflex install codex を実行してから、/hooks でフックを一度信頼する	ライブセッション
Cursor	ライフサイクルフック	openreflex install cursor	プロトコルテストとファズテスト
OpenCode	ローカルライフサイクルプラグイン	openreflex install opencode	プロトコルテストとファズテスト

Claude プラグインでは、/openreflex を実行すると、読み取り専用の簡潔な状態ビューが表示されます。/openreflex approve を使用して現在のプロジェクトでローカルメモリを有効にしてから、通常どおり作業してください。ほかにも、status、reflexes、memory、doctor、why、trace、revoke などの明示的な操作を利用できます。OpenReflex の制御ターンはプロジェクトの経験として学習されず、通常のタスク検証も実行されません。制御スキルはユーザーが呼び出した場合にのみ動作し、MCP 診断を有効にしたり、通常のモデルルーティングに参加したりすることはありません。Claude では、正規の名前空間付き形式である /openreflex:openreflex が表示される場合があります。エージェントごとのガイド： Claude Code、Codex、Cursor、 OpenCode。

仕組み

フックはライフサイクルイベント（プロンプト、ツールの開始、ツールの終了、コンパクション、停止）を OpenReflex エンジンに送信し、エンジンはそれらを経験グラフに保存します。

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

• タスク開始前： 類似した経験を検索し、OpenReflex がまず作業モードを特定します。BUILD では inspect-first、test-first、incremental を使用し、INVESTIGATE では source-first、 cross-check、broad-then-deep を使用します。THINK では reason-first、compare-options、 evidence-first を使用します。過去の根拠、推定コスト、リスク、不確実性、可逆性に基づいて経路を順位付けします。 注入されたテキストは後続の API 呼び出しごとに再度読み込まれるため、タスクに固有の場合に限ってコンテキストを注入します。 具体的には、一致する Reflex、またはこのプロジェクトですでに発生した失敗に関する教訓です。5 件に 1 件の重要なタスク （evaluation.holdout_percent ポリシー値）はホールドアウトです。OpenReflex は記録しますが、何も表示しないため、 openreflex status を使って、OpenReflex の有無によるタスクあたりのモデルのトークン数を比較できます。
• タスク間（Claude Code）： セッションにすでに大量の履歴 （context.reset_hint_tokens）がある状態で、新しい無関係なタスクが始まると、OpenReflex が /clear を提案します。 この提案がモデルに表示されることはありません。/clear の後、新しいセッションには、クリアしたタスクの全履歴ではなく、 短い要約が引き継がれます。
• タスク実行中： すでに 2 回失敗しており、その後に編集もチェックの成功もない同一の呼び出しは、実行前に拒否されます （Claude Code）。その他のエージェントでは警告が表示されます。このプロジェクトで過去に解決済みのエラーが発生した場合は、 最初の失敗時に、その解決方法が示されます。検出器が失敗ループ、呼び出しの繰り返し、進捗の停滞、またはコンテキストの増大を 検出すると、OpenReflex は作業を続けることによる限界価値を推定します。予算超過のアラートは既定でオフです。有効にするには detectors.over_budget_tiers を設定してください。現在の経路の成功見込みは、進捗がなかった、または失敗した呼び出しごとに 更新され、残りの作業コストおよび試していない最善の代替策と比較されます。アラートの最後には、続行、別の戦略への 切り替え、または停止してユーザーに確認するという推奨が表示されます。各問題、切り替え、停止は 1 回だけ通知され、 メッセージ間にはクールダウン期間が設けられます。
• タスク完了後： ライフサイクルフックが、作業モードに適した根拠に基づいて実行を自動的に終了するため、モデルが OpenReflex を呼び出す必要はありません。明示的な MCP の結果／経路操作は、手動または診断のワークフローでのみ引き続き 利用できます。Path check には、比較可能な完了済みタスクが根拠を示している場合は better option: <path>、そうでない場合は better option: none proven と表示されます。 推奨が実際に実行された経路として提示されることはありません。

すべての推奨は、Reflex Score（0～100）を含む意思決定スナップショットとして保存されます。このスコアは推奨の確度を示すもので、 タスクの成功見込みとは別のものです。openreflex why では直近の判断の理由を確認でき、openreflex trace では時系列を確認できます。 Claude Code では、タスク開始時、OpenReflex が切り替えまたは停止を推奨したとき、問題を検出したとき、タスク完了時に短い要約が表示されます。

OPENREFLEX_BUDGET を設定すると、すべてのタスクに任意の上限を設定できます。たとえば calls=40,minutes=20,tokens=60000 のように指定します。 ルーティング、スコアリング、予算、要約の設定は、バージョン管理されたポリシーに従います。パッケージに含まれる既定値に、 ~/.openreflex/config.toml、続いてプロジェクトの .openreflex.toml の設定が上書きされます。

通常の作業では OpenReflex MCP ツールは読み込まれません。プロジェクトでモデル向けのイントロスペクションを明示的に利用するには、 openreflex diagnostics enable <agent> で有効にしてください。無効にするには openreflex diagnostics disable <agent> を実行します。単体の MCP Registry パッケージは、OpenReflex を MCP サーバーとして 意図的にインストールするユーザー向けに引き続き利用できます。

任意の MCP 診断／管理ツール

| ツール | 機能 | |---|---| | `get_execution_context` | タスクを計画します。類似する過去のタスク、代替案を含む推奨戦略、予算、関連する可能性のあるファイル、教訓を提示します。オプションで `max_tool_calls`、`max_minutes`、`max_context_tokens` を指定できます。 | | `check_progress` | 現在の方針で作業を続ける価値があるかを判断します。続行、方針転換、停止のいずれかを提示します。 | | `choose_path` | 推奨と異なる場合に、採用する戦略を宣言します。 | | `record_outcome` | 確認済みの結果（テスト／ビルド、相互検証済みの調査、ユーザーの確認、失敗）を記録し、そこから学習します。 | | `explain_decision` | 最新の推奨の理由（Reflex Score、シグナル、確信度、次善の方針）を説明します。 | | `get_execution_trace` | 直近のタスクの意思決定のタイムラインを表示します。 | | `get_reflex_score` | 最新の Reflex Score とその構成要素を JSON 形式で表示します。 | | `search_experience` | 説明の類似度に基づいて、プロジェクト内の過去のタスクとその教訓を検索します。 | | `explain_node` | Experience Graph のノード 1 つとその関係を説明します。 | | `get_project_insights` | プロジェクトで記録、再利用、学習された内容を表示します。 | | `approve_project` | ユーザーが明示的に依頼した場合に限り、記録を有効にします。 | | `forget_experience` | ユーザーが明示的に依頼した場合に限り、過去のタスクの記憶を 1 つ削除します。 |

CLI

コマンド	目的
install <agent> [--dry-run]	フックのみのアンビエントランタイムをインストールし、プロジェクトを有効にします
diagnostics enable/disable <agent>	モデル向け MCP 診断を明示的に有効／無効にします
uninstall <agent> [--dry-run]	OpenReflex の統合エントリを削除します。記録済みのメモリは保持されます
update [--check] [--reinstall]	管理対象の pipx／uv-tool インストールを確認または更新します。オプションで再インストールを強制できます
self reinstall	メモリ／設定を保持したまま、管理対象の OpenReflex パッケージを修復／再インストールします
self uninstall --yes	管理対象の OpenReflex パッケージのみを削除します。メモリ／設定はディスク上に残ります
approve / revoke	現在のプロジェクトで記録を有効または無効にします
context "<task>"	タスクに提供される Execution Context をプレビューします
status [--json]	記録、再利用、学習された内容と、モデルのトークン使用量の比較を表示します
why / trace	最新の推奨の理由を説明するか、意思決定のタイムラインを表示します
doctor	インストール、プロジェクトの解決、最近のフック動作を確認します
forget --yes	プロジェクトのデータを削除します
tokens enable / tokens status / tokens disable	トークン数の確認にセットアップは不要です。ローカルの Claude Code テレメトリによる推定コストを有効にする、確認する、または OpenReflex が管理するテレメトリ設定を削除します
benchmark	シミュレーションベンチマークを実行します
hook <agent> <event>	アンビエントエージェント統合で使用されます
mcp	オプションの診断／管理用 MCP サーバーを明示的に実行します

プライバシー

保存される情報	保存されない情報
ツール名と大まかなカテゴリ（read、edit、search、test、...）	ファイルの内容
引数のフィンガープリント	コマンドのテキスト
プロジェクト相対のファイルパス	ツールの出力
成功または失敗、所要時間、出力サイズ	トランスクリプトとモデルの出力
ローカルの Claude トランスクリプトから読み取った API 呼び出しごとのモデルのトークン数、モデル／ソースのラベル、任意の推定コスト	トランスクリプトまたは Claude のテレメトリに含まれるプロンプト／応答／ツールの内容
マスキングされた 1 行のエラーシグネチャ	プロジェクト外のパス
タスクの説明としてのプロンプト（最大 1,000 文字、シークレットはマスキング）	OpenReflex がホストするサービスに送信される情報（そのようなサービスはありません）

データは ~/.openreflex/projects/<hash>/experience.sqlite3 に保存されます。保存先を変更するには OPENREFLEX_HOME を設定し、 すべての記録を無効にするには OPENREFLEX_DISABLE=1 を設定します。プロジェクトのデータを削除するには openreflex forget --yes を実行するか、 エージェントに forget_experience を使って 1 つのタスクを忘れるよう依頼してください。

研究

OpenReflex は、予算を考慮した実行に関する研究プロジェクトでもあります。成功を単なる「はい」か「いいえ」として扱うのではなく、エージェントが実行経路をどのように選択し、ツール呼び出し、モデルのトークン、コンテキストをどのように使い、不確実性にどう対処するのか、また、過去の作業によって成果の質を落とさずに同様の将来の作業をより低コストで実行できるのかを研究します。このループは、経験の検索、根拠を考慮した経路選択、予算を考慮した実行、作業モードに応じた完了、平易な言葉での経路比較で構成されます。サイトの研究者向けビューでは、この考え方を説明し、グラフ内でひとつの反射が形成される過程をたどり、関連研究と並べて確認できます。

再現可能な評価プロトコル、固定された実エージェントのコーパス、正確なプロンプト、主張の範囲については、docs/evaluation.mdに記載されています。

コミュニティとコントリビューション

• 課題やアイデア： GitHub Issues

• プロジェクトを支援： コーヒーをおごる

• ローカルで開発：

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

OpenReflex は、MCP Registryにio.github.vishnu-77/openreflexとして登録されており、Glamaにも掲載されています。

ライセンス

OpenReflex はMIT Licenseの下で公開されています。