環境変数

このページでは、minara-agent-v2 が環境変数を読み込む規約と、新しい変数を導入する際の手順を説明します。エージェントが読み込む各変数のデフォルト値・フォーマット・利用ファイル・「未設定時に何が壊れるか」については、リファレンス → 環境変数 を参照してください。

公式テンプレートはプロジェクトルートの .env.example です。このファイルと両ページを常に同期させてください。

MINARA_ は Minara プラットフォーム固有の変数（MINARA_API_KEY、MINARA_BASE_URL、MINARA_SKIP_FUND_CONFIRM、MINARA_DATA_DIR、MINARA_OPENAI_BASE_URL、MINARA_OPENAI_CHAT_PATH）に予約されています。エージェントループの基盤変数（ゲートウェイ、ログ、モデル、シナリオ、メモリ設定）にはこのプレフィックスを付けません。

ユーザー向けのつまみは Settings（settings.json#preferences）に保存します。シークレットは credentials.json（設定 → API Keys / Messaging）に保存します。呼び出し側は prefs.get / secrets.* / infra.get で読みます。Env は起動時のオペレーター層であり、上書きチェーン上の文書化されたフォールバックです。

規約の要点

API キー・シークレット・token・上書き可能な URL が必要なスキルやツールは、必ず次の手順に従ってください。

1. 正しい保存先に書き、façade から読む。 シークレットは API-key / messaging レジストリと secrets.dataSource / secrets.messaging。ユーザー向けつまみは preferences schema と prefs.get。オペレーター基盤（GATEWAY_PORT、MINARA_DATA_DIR）は config/infra/schema.ts と infra.get。シークレットをハードコードしないでください。CLI 引数として受け取りエコーすることも禁止です。

2. 同じコミットで apps/agent/src/config/env-docs/ にドキュメント付きエントリを追加し、.env.example を再生成する。 エントリには次の情報を記載してください。制御する内容・利用するスキル / ツール・オペレーターが設定するタイミング・未設定時のデフォルト動作・有効な値のフォーマット。1 行だけのスタブ（# FOO_KEY=）は却下されます。

3. ドメインスキル（apps/agent/src/skills/builtin/*.ts または apps/agent/src/skills/external/<id>/）の場合は、資格情報が存在しないときにスキルが完全に非表示になるよう requires_env で宣言してください。

   export const myNewSkill: DomainSkill = {
     id: "research.my_provider",
     // ...
     requires_env: ["MY_PROVIDER_API_KEY"],
   };

4. ツール（apps/agent/src/tools/*.ts）の場合、シークレットが存在しないときはファクトリ関数が空の ToolEntry[] を返すようにしてください。ツールレジストリは未登録の名前を静かに除外するため、下流スキルの tool_names 参照はグレースフルにデグレードします。

   export function createMyProviderTools(): ToolEntry[] {
     const apiKey = secrets.dataSource("MY_PROVIDER_API_KEY");
     if (!apiKey) return [];
     // ...
   }

5. 本物のシークレットをコミットしないでください。 .env は git-ignore 済みです。コミットするテンプレートは空の値を持つ .env.example です。

.env の読み込み方

読み込みは apps/agent/src/config/load-env.ts が担います。これは Node 22 の組み込み process.loadEnvFile(".env") を呼び出す副作用モジュールで、すべてのエントリーポイントの最初の行でインポートされます。

• apps/agent/src/gateway/cli.ts, REPL モード
• apps/agent/src/gateway/server.ts, HTTP モード

ESM の評価順序により、process.env.<NAME> をインポート時に読み込む下流モジュールよりも前にローダーが実行されることが保証されます。

優先順位: シェル / CI / systemd がすでにエクスポートしている変数は .env の値より優先されます。ローダーは既存のキーを上書きしません。これは Node のデフォルト動作に合致しており、CI が注入したシークレットを意図せず隠してしまうことがない、最も安全なルールです。

dotenv 依存なし。 Node 22.5 以降で安定している process.loadEnvFile のみを使用します。.env が存在しない場合はエラーにならず、何も起きません。

変数一覧

各変数の詳細ドキュメント（デフォルト値・フォーマット・利用ファイル・「未設定時に何が壊れるか」）は、リファレンス → 環境変数 を参照してください。以下の表はクイックリファレンスです。

LLM プロバイダー

少なくとも 1 つが解決（直接、または minara auth login で保存した OAuth プロファイル経由）しなければ、エージェントは起動を拒否します。

Minara コア

HTTP ゲートウェイ

セーフティと資金移動

ハイブリッドメモリ検索

EMBEDDING_PROVIDER=disabled（デフォルト）の場合、ハイブリッド検索のコードパスは非アクティブです。すべてのメモリ行は embedding_state='pending' のままで embedding カラムは NULL になり、searchMemoriesHybrid は既存の FTS5 BM25 パスにフォールスルーして同一のバイト結果を返します。クロスボキャブラリーの検索精度向上（例: 中国語クエリ 山寨币最近怎么样 が英語の altcoin drawdown レッスンを検索できるようにする）が必要な場合にのみ、オペレーターがこれを有効化します。書き込みパスは同期のままです。エンベディングは行のコミット後に queueMicrotask で実行されるため、ユーザー向けレイテンシは変わりません。

プロバイダーが有効でも一時的な API 障害が発生した場合、行は embedding_state='failed' になります。minara doctor（フェーズ E1）は状態ごとのカウントを表示するため、オペレーターは蓄積状況を確認できます。minara doctor --fix --apply（フェーズ E2）は MemoryStore.backfillEmbeddings() でバックフィルします。failed と pending の両方がバックフィルの対象になり、同じ行が成功するまで循環することがあります。10 文字未満の行やメソドロジー注入スキャナーに引っかかった行は skipped になり、エンベディングされません。

バックテストフィードバックループ（Sprint 6, オンライン結果フィラー）

対象実行の学習ループを閉じる定期ジョブです。決定論的な取引後市場結果（"+5.20% in 24h" など）を計算・保存し、その後に任意の推論評価を実行します。統一 Trading Memory の発生元ルールが先に適用され、自動または発生元不明の perps は手動評価経路に入りません。

過去の判断を再実行しません。 trade_executions にある pending 行だけを評価します。有効時は通常間隔の前に gateway 起動時に期限超過分を一度処理します。デフォルトは無効です（BACKTEST_ENABLED=false）。

ロールアウトプロトコル（plan dapper-coalescing-shell § Sprint 6）:

1. BACKTEST_ENABLED=true と BACKTEST_DRY_RUN=true を設定して 1 クロンサイクル実行します。shadow_runs WHERE facet='backtest_outcome' を確認し、結果文字列が ±N.NN% in Xh に一致し、スキップ理由が妥当かを確認します。
2. BACKTEST_DRY_RUN=false に切り替えます。Runner は決定論的 outcome と終端 state を trade_executions に書き、evaluation run と observation は append-only のままです。
3. 帰属が正常な場合だけ LEARNING_RECORD_USAGE=true にします。evaluation_runs、methodology_observations、methodology_metric_stats を profile version ごとに監視します。新統計に影響するのは promoted primary run だけです。

パーソナライゼーションリビルド（M3.2 イベント駆動型閾値）

Minara は PersonalizationRebuilder を通じて、すべての会話からトレード嗜好を学習します。M3.2 以前はリビルダーがクールダウン付きで 10 分ごとに実行されていました。M3.2 ではイベント駆動型 + 閾値ゲートに変わりました。データ書き込み（トレード、メモリ、チャットターン）がイベントを発行してリビルダーを起動し、各リビルドは「最小新規入力数」と「最終リビルドからの最小経過時間」という独立した 2 つのゲートをどちらも満たす必要があります。どちらか一方だけでは起動しません。

60 分ごとの安全網スケジューラーは引き続き存在し（例: プロセス再起動によって書き込みとサブスクライバーの間でイベントが失われた場合に対応します）、静かなシステムでは LLM 呼び出しも info ログも発生しません。

トレードサマリーの閾値

トレード頻度が高くサマリーが頻繁に更新される場合は閾値を上げてください。バックテストやオンボーディング中にサマリーをできるだけ早く収束させたい場合は下げてください。

メモリ抽出の閾値

rebuildMemories はカーソル last_indexed_chat_id 以降に書き込まれた chat_turns 行をスキャンし、個別の事実を抽出します。既定では ADD のみのプロンプト（UPDATE/DELETE なし）を使い、矛盾は先行する事実と並んで ADD され、検索時に解決されます。MEMORY_CONSOLIDATION_ENABLED が有効な場合は、後続のリゾルバパスが各事実について ADD / UPDATE / SUPERSEDE を判定し、古い行や矛盾する行を書き込み時に整理します（Minara Memory を参照）。抽出された各事実は fact_type、attributed_to、entities_json、linked_memory_ids のメタデータとともに共有 memories テーブルに行として書き込まれます。

共通の設定

運用上のヒント: 新規デプロイ時は、リビルダーが素早くウォームアップできるよう初日だけ FIN_PROFILE_TRADING_SUMMARY_MIN_NEW_TRADES=1 と FIN_PROFILE_MEMORIES_MIN_NEW_TURNS=2 を設定してください。プロファイルが安定したらデフォルトに戻してください。

エージェント外履歴ミラー

パーソナライズ・リビルダーは 3 つのデータソースを利用します: ローカル trade_history（エージェント内）、perps_fills（Minara /v1/perp-wallets/fills のサブウォレット横断ミラー）、external_spot_activities（Minara /v1/tx/cross-chain/activities）。以下のノブで MinaraHistorySync の同期戦略と LLM が読む量を調整します。

同期トリガーモデル。 3 つの経路で MinaraHistorySync.scheduleSync() が発火します: (1) 任意の trade:recorded イベント（エージェントが取引を実行した直後はユーザーも web/mobile で操作した可能性が高い）、(2) PersonalizationRefreshTask の毎時セーフティネット tick（取り逃したイベントの補完）、(3) 明示的な /refresh-personalization --force / POST /v1/profile/refresh 経路。5 分のスロットルでウィンドウ内 API は 1 回しか叩かれません。

ウォーターマーク粒度。 minara_history_sync_state のキーは (source, sub_account_id) です。単一サブアカウントの一時的な失敗が他サブのウォーターマークやグローバル spot カーソルを汚染しません。

Hyperliquid パーペチュアル

MINARA_HL_DEX_DISCOVERY は、パーペチュアルのスナップショット構築と取引履歴の同期時に、Minara が Hyperliquid の名前付きパーペチュアル DEX をどこまで探索するかを制御します。

Strategy Studio（ベータ版）

1 つのオペレーター設定で、strategy-rl ベンチマークランナーが使用するオフラインのストラテジーコード生成サブエージェントを制御します。デフォルト値が適切に設定されているため、未設定のままでも問題ありません。

Harness RL

機関投資家モード（マルチエージェント運用チームシミュレーション）

minara_institution_analyze ツールは、高リスクな単一アセット分析のために 6 フェーズのパイプライン（4 アナリストの並列実行 → ブル/ベア討論 → リサーチマネージャー → トレーダー → 3 者リスク討論 → ポートフォリオマネージャー）を実行します。TradingAgents をモデルにしており、ラウンド数のデフォルト値はそのプロジェクトの default_config.py に準拠。タイムアウト / token 上限は Minara の deep-research とエージェントループの規約に従います。

以下の変数はすべてエージェントループのインフラ変数であり、プロジェクト規約に従って MINARA_ プレフィックスはありません。すべて未設定にすると TradingAgents 準拠のデフォルト値が使用されます。

単一モデルポリシー。 パイプライン内のすべてのロール（アナリスト、討論参加者、リサーチマネージャー、トレーダー、リスクペルソナ、ポートフォリオマネージャー、アロケーター）は、オペレーターが選択したエージェントモデル（エージェントの残りの部分と同じプロバイダー / モデル）で実行されます。ロールごとのオーバーライドはありません。合成に強力なモデルを使用したい場合は、セッション全体のデフォルトモデルを切り替えてください。

コストに関する注記: 1 回の institution 実行は約 25 LLM 呼び出し × 4K 出力 token ≈ 10⁵ 出力 token です。デフォルト設定の Sonnet クラスモデルで約 1〜3 ドルになります。エンドユーザーにツールを公開する場合はこれを明示してください。

ハードコードされた定数（v1 ではオペレーターが調整可能な環境変数ではありません）:

• フェーズ 1 のアナリスト並列数 = 4（アナリスト数。セマフォライブラリなしで 4 スロットに対して Promise.all）。
• サブエージェントの内部ループターン上限 = 5 ターン。Minara の strategy-code-subagent の規律に一致します。アナリストはレポートを作成するまでに通常 1〜3 回のツール呼び出しで済みます。
• LLM 呼び出しごとのタイムアウト = wallClock / 10（5 秒のフロア付き）。
• 出力言語 = 既存のユーザーメッセージ言語検出から継承（deep-research が使用するのと同じパターン）。内部討論ターンは英語のまま。最終レポートのみローカライズされます。

ハードコードされた定数を実際の運用でチューニングする必要がある場合は、フォローアップ PR で環境変数に

メソドロジー監査サブシステム（受動オブザーバー）

学習ループの上に重なる読み取り専用の監査サブシステムで、複合的な健全性スコアを出力します。6 つの次元が複合スコアを構成: synthesis 判定の安定性、卒業後の早期降格率、帰属健全性、アセットクラス カバレッジ、隔離フラッピング検知、cron 健全性。サブシステムは学習状態を一切変更せず、唯一の書き込みは methodology_audit_reports への 1 パス 1 行のみです。エンドツーエンドテストが監査パス前後で 4 つの学習テーブルをハッシュし、書き込みを導入する回帰を即座に検出します。

cron はエージェントループと協調します。各 tick は共有 BusyTracker をチェックし、ユーザーターンが進行中、またはエージェントのアイドル時間が閾値未満なら tick を延期します。連続 N 回延期後はスターベーション ガードが強制実行し、常時忙しい環境でも監査カバレッジを失わせません。パス実行中、オーケストレーターは SQL ステージ間でイベントループに譲り、ターンが入ってくると busy tracker で一時停止します。

デフォルト周期は 1 日 1 回。cron_health は methodology_cron_runs ハートビート テーブル（src/learning/methodology-cron.ts が各学習 tick の末尾で書き込み）を読みます。帰属レーンが静か（処理対象 case なし）でもループ停止と誤判定されません。

CLI:

minara learning audit run [--window-days N]  # インライン単一パス
minara learning audit show [--latest|--pass <id>]
minara learning audit trend [--days N]       # 複合スコア履歴 + sparkline
minara learning audit findings [--severity high|medium|low]

プロアクティブ・ウェルス・エージェント

有効化された各マンデートをバックグラウンドで動かす監督ループ（ポジションの時価評価、利確/損切り/リバランス、損益スナップショット、作業ログの記録）と、新しい機会を探す低頻度の再探索です。3つとも 設定 → プロアクティブ（およびプロアクティブモジュール内の設定タブ）でライブ編集できます。以下の環境変数は起動時のフォールバックです。マルチワーカー構成では IS_PRIMARY_WORKER=1 のワーカーでのみループが動作します。

Point-in-time 財務スナップショット

履歴スナップショットには、SEC accepted time が要求された締切以前の fact だけを含めます。FMP データは SEC filing と決定的に一致した場合だけ fact を補完します。Yahoo の現在サマリー、時価総額、セクター、業種、TTM 値、DCF は latest-only approximation として扱います。

行動メモリ

BEHAVIOR_MEMORY_ENABLED=true でオプトインします。カテゴリは個別に切り替えられ、資産コンテキスト・取引・会話は明示的に有効化しない限り収集されません。本文、秘密情報、アドレス、注文パラメータ、個別ポジションは保存しません。