trader-memory-core

Trader Memory Core

概要

スクリーニング → 分析 → ポジションサイズ調整 → ポートフォリオ管理の出力を、投資アイデアごとに単一の「投資仮説オブジェクト」にまとめる永続状態レイヤーです。会話をまたいで、考えたこと、起きたこと、学んだことを追跡します。

フェーズ 1 では、単一ティッカーの投資仮説に対応します：dividend_income、growth_momentum、mean_reversion、earnings_drift、pivot_breakout。

使用する場面

• スクリーナー（kanchi、earnings-trade-analyzer、vcp、pead、canslim、edge-candidate-agent）が候補を出力した後
• 投資仮説のステータスを IDEA → ENTRY_READY → ACTIVE → CLOSED に移行する場合
• ポジションサイズ調整の出力を投資仮説に添付する場合
• レビュー期限を迎えた投資仮説を確認する場合
• ポジションを決済し、学んだ教訓を含む事後分析を作成する場合

前提条件

• Python 3.10+
• pyyaml（プロジェクトの依存関係にすでに含まれています）
• jsonschema（pyproject.toml にすでに含まれています。thesis_store.py と、それをインポートするすべてのコマンド（thesis_ingest.py や thesis_review.py など）で必要です）
• FMP API キー（任意。事後分析で MAE/MFE を計算する場合のみ必要です）

CLI の呼び出し方法

CLI の操作にはすべて、標準ライブラリのみを使用するランチャー trader_memory_cli.py を使ってください。uv が利用可能な場合は、透過的に uv run --project <repo> 経由で実行されるため、別の作業ディレクトリからでも、またはグローバルに jsonschema がインストールされていない python3 からでも（cron / Hermes プロファイルでの実行など）、リポジトリに固定された jsonschema を利用できます。

# From inside the repo
python3 skills/trader-memory-core/scripts/trader_memory_cli.py store --state-dir state/theses list

# From any other cwd (cron, profile, distribution runner) — point the launcher at the repo
export CLAUDE_TRADING_SKILLS_REPO=/path/to/claude-trading-skills
python3 "$CLAUDE_TRADING_SKILLS_REPO/skills/trader-memory-core/scripts/trader_memory_cli.py" \
  store --state-dir /path/to/state/theses list

サブコマンドは、store → thesis_store.py、ingest → thesis_ingest.py、review → thesis_review.py です。サブコマンド以降のすべての引数はそのまま転送されるため、既存の引数フラグ（--state-dir、transition、open-position など）は変更せずに使えます。

ランチャーで jsonschema をインポートできず、かつ uv が PATH にないと報告された場合は、次の順に対処してください。

1. uv（https://docs.astral.sh/uv/）をインストールし、ランチャーを再実行します。
2. 現在のインタープリターにプロジェクトの依存関係をインストールします。

   uv pip install -e /path/to/claude-trading-skills
   # or, as a last resort:
   python3 -m pip install jsonschema
   

依存関係が見つからないことを理由に、投資仮説ストアを利用不可として扱ったり、回避策として state/theses/*.yaml を手作業で変更したりしないでください。スキーマ検証は投資仮説の状態の整合性を保つための仕組みです。

ワークフロー

1. 登録 — スクリーナーの出力を投資仮説として取り込む

スクリーナーの JSON 出力を読み込み、適切なアダプターを使って投資仮説に変換します。

python3 skills/trader-memory-core/scripts/trader_memory_cli.py ingest \
  --source kanchi-dividend-sop \
  --input reports/kanchi_entry_signals_2026-03-14.json \
  --state-dir state/theses/

対応するソース：kanchi-dividend-sop、earnings-trade-analyzer、vcp-screener、pead-screener、canslim-screener、edge-candidate-agent、manual。

各投資仮説は IDEA ステータスで開始します。

kanchi-dividend-sop の登録はフェイルクローズ方式です。各行の verdict には、CLEAN-PASS、PASS-CAUTION、CONDITIONAL-PASS のいずれかが必要です。 verdict がない行、および HOLD-REVIEW / STEP1-RECHECK / FAIL の行はスキップされ、投資仮説の状態には書き込まれません。

手動の証券口座入力（端株）

スクリーナーを通していない取引（端株に対応する証券会社（IBKR、Robinhood、IBI Smart、Alpaca、eToro）での取引や、手動での記録など）には、自由形式の JSON ファイル（単一オブジェクトまたは配列）で manual ソースを使います。

{
  "ticker": "AMD",
  "thesis_statement": "AMD AI accelerator momentum, fractional IBI Smart position",
  "thesis_type": "growth_momentum",
  "entry_price": 142.10,
  "entry_date": "2026-05-02",
  "shares": 7.86,
  "stop_price": 128.00
}

python3 skills/trader-memory-core/scripts/trader_memory_cli.py ingest \
  --source manual --input amd.json --state-dir state/theses/

必須項目：ticker、thesis_statement、thesis_type（dividend_income、growth_momentum、mean_reversion、earnings_drift、pivot_breakout のいずれか）。stop_price / stop_loss と target_price / take_profit は exit.stop_loss / exit.take_profit に対応します。entry_price / entry_date / shares は origin.raw_provenance に保持されます。正式なエントリー価格／日付と株数は、ポジションを開く際（下記）に設定されます。shares には端株を指定できます（スキーマでは正の数値ならすべて受け入れられます）。他のすべてのアダプターと同様に、manual ingest で作成されるのは IDEA の投資仮説のみです。ステータスが直接変更されることはありません。

すでに開いている証券口座のポジションを記録するには、明示的なライフサイクル手順を実行します（--event-date フラグで履歴の日付をさかのぼらせ、時系列順を保ちます）。

# 1. ingest → IDEA (stamped at entry_date)
python3 .../trader_memory_cli.py ingest --source manual --input amd.json --state-dir state/theses/
# 2. IDEA → ENTRY_READY (backdated)
python3 .../trader_memory_cli.py store --state-dir state/theses/ transition <id> ENTRY_READY \
  --reason "existing IBI Smart position" --event-date 2026-05-02
# 3. ENTRY_READY → ACTIVE (fractional shares, backdated)
python3 .../trader_memory_cli.py store --state-dir state/theses/ open-position <id> \
  --actual-price 142.10 --actual-date 2026-05-02 --shares 7.86 --event-date 2026-05-02

2. 検索 — 投資仮説を検索して一覧表示する

python3 skills/trader-memory-core/scripts/trader_memory_cli.py store \
  --state-dir state/theses/ list --ticker AAPL --status ACTIVE

--ticker、--status、または --type で絞り込みます。

3. 更新 — 遷移、ポジションの紐付け、レポートのリンク

各ライフサイクル操作は、Python 関数と thesis_store.py の CLI サブコマンドの両方で利用できます。--event-date／--actual-date には、通常の YYYY-MM-DD（UTC の午前 0 時に拡張）または完全な ISO タイムスタンプを指定できます。

状態遷移（IDEA → ENTRY_READY のみ）：

python3 skills/trader-memory-core/scripts/trader_memory_cli.py store --state-dir state/theses/ \
  transition <id> ENTRY_READY --reason "validated" [--event-date YYYY-MM-DD]

--event-date は status_history.at の日付を遡らせます（既存のポジションを遡及入力する際に使用すると、後から日付を遡らせて実行する open-position の時系列が保たれます）。 Python：thesis_store.transition(state_dir, thesis_id, "ENTRY_READY", reason, event_date=...)。

ポジションを開く（ENTRY_READY → ACTIVE — ACTIVE になる唯一の経路）：

python3 .../trader_memory_cli.py store --state-dir state/theses/ open-position <id> \
  --actual-price 142.10 --actual-date 2026-05-02 [--shares 7.86] [--event-date 2026-05-02]

--shares には端数のある数量を指定できます。Python： thesis_store.open_position(state_dir, thesis_id, actual_price, actual_date, shares=..., event_date=...)。 shares（および存在する場合は shares_remaining）は、10¹² 以下の有限な正の数である必要があります（これは妥当性確認の上限であり、経済的な制約ではありません。上限未満の端数株数には制限がありません）。NaN、±Infinity、異常に大きな値（形式が不正なポジションサイザーのレポートなど）は、保存時、open-position、attach-position、trim のいずれでも、明確なエラーとともに拒否されます。

先物のテーゼでは、--shares の代わりに --contracts を使用します（下記の「先物ポジション」を参照）。attach-futures-position ですでにポジションが入力されている場合は、--contracts を省略し、--actual-price／--actual-date のみを指定してください。

トリム — 部分決済（ACTIVE／PARTIALLY_CLOSED → PARTIALLY_CLOSED、または残り全てを売却した場合は → CLOSED）：

python3 .../trader_memory_cli.py store --state-dir state/theses/ trim <id> \
  --shares-sold 4 --price 120.00 --date 2026-05-10

position.shares は当初の建玉数量（変更不可）であり、position.shares_remaining は現在も保有している数量を記録します。トリムのたびに、status_history 台帳エントリ（shares_sold／price／proceeds／realized_pnl）が追加されます。outcome.pnl_dollars は実現損益の累計（Σ すべてのトリム＋最終決済）であり、outcome.pnl_pct = pnl_dollars / (entry_price × original_shares) × 100 です。残りをすべて売却するトリムでは、テーゼがクローズされます（デフォルトの exit_reason: manual は --exit-reason で変更できます）。--date は台帳のタイムスタンプです（--event-date で上書きできます）。Python： thesis_store.trim(state_dir, thesis_id, shares_sold, price, date, ...)。

ステータスの不変条件：ACTIVE ⇒ shares_remaining == shares；PARTIALLY_CLOSED ⇒ 0 < shares_remaining < shares；CLOSED ⇒ shares_remaining == 0。従来のテーゼ（shares_remaining がないもの）は、実行時に全数量が未決済として扱われます。

先物のテーゼでは、--shares-sold の代わりに --contracts-sold を使用します。close／terminate ではフラグを変更する必要はありません。position.asset_type を読み取り、自動的に処理を振り分けます（下記の「先物ポジション」を参照）。

クローズまたは無効化（→ CLOSED または INVALIDATED）：

python3 .../trader_memory_cli.py store --state-dir state/theses/ close <id> \
  --exit-reason target_hit --actual-price 165.00 --actual-date 2026-06-01
python3 .../trader_memory_cli.py store --state-dir state/theses/ terminate <id> \
  --terminal-status INVALIDATED --exit-reason "thesis broke"

close は、ACTIVE または PARTIALLY_CLOSED のテーゼを受け付けます。PARTIALLY_CLOSED から実行すると、最終分を追加し、累計の結果を報告します。

Python：thesis_store.terminate(state_dir, thesis_id, terminal_status, exit_reason, actual_price, actual_date)。CLOSED の場合は close() に処理を委譲して損益を計算します（端数株数に対応）。INVALIDATED の場合は、エントリー価格と決済価格が利用可能であれば損益が計算されます。

レビューを記録する（終端状態以外）：

thesis_store.mark_reviewed(state_dir, thesis_id, review_date=..., outcome="OK"|"WARN"|"REVIEW") を使用すると、next_review_date を更新し、アラートを記録できます。

ポジションサイザーの出力を紐付ける：

python3 .../trader_memory_cli.py store --state-dir state/theses/ attach-position <id> \
  --report reports/position_report.json

Python：thesis_store.attach_position(state_dir, thesis_id, report_path) を使用して、ポジションサイジングデータをリンクします。レポートのモードが「shares」（budget ではない）であることを検証します。

先物ポジション（契約数 / 乗数 / 方向）

position.asset_type == "futures"（または quantity_unit == "contracts"）であるテーゼは先物テーゼです。先物テーゼは shares / shares_remaining の代わりに quantity / quantity_remaining（整数の契約数 — 端数の契約は不可）を使用し、direction（LONG または SHORT）と multiplier を持ち、すべての損益計算（close、terminate、trim）は株式の単位あたりの計算式ではなく (exit_price - entry_price) × multiplier × quantity × sign（sign = +1 は LONG、−1 は SHORT）を適用します。close / terminate / trim / open-position はすべて position.asset_type に基づいて自動的にディスパッチされます — これら 4 つの操作に個別の先物サブコマンドはありません。米ドル建ての契約のみ — 損益計算の経路に FX 換算は存在しないため、米ドル以外の contract_spec.currency は、誤った通貨の桁で損益を計算するのではなく、そのまま拒否されます。

futures-position-sizer の SIZED レポートをアタッチします（Shapiro コントラリアン パイプラインのステップ 6 — futures-position-sizer → trader-memory-core）:

python3 .../trader_memory_cli.py store --state-dir state/theses/ \
  attach-futures-position <id> --report reports/futures_position_es_2026-05-10.json

NO_TRADE レポート（sizing_status != "SIZED"）、無効な direction、正でない/端数の contracts 数、非有限/正でない contract_spec.multiplier、または米ドル以外の contract_spec.currency を拒否します。再アタッチのステータスガードは IDEA/ENTRY_READY のみです — 株式の attach-position（ACTIVE も許可）よりも厳格です。ACTIVE の先物ポジションを再アタッチすると、direction を含むポジション dict 全体が黙って上書きされ、以降のすべての損益計算の符号が反転してしまいます。すでにオープンしている先物ポジションを修正するには、新しいテーゼ（または将来の専用の「amend」操作）が必要です — 再アタッチではいけません。

直接オープン、アタッチなし（SIZED レポートの代わりに CLI フラグからポジションを構築します — ここでは contract_spec から通貨を読み取れないため --contract-currency が必須であり、USD でなければなりません）:

python3 .../trader_memory_cli.py store --state-dir state/theses/ open-position <id> \
  --actual-price 5000 --actual-date 2026-05-10 \
  --contracts 2 --multiplier 50 --direction SHORT --contract-symbol ES \
  --contract-currency USD

Trim / close / terminate — 株式と同じサブコマンドで、--shares-sold の代わりに --contracts-sold を使用します:

python3 .../trader_memory_cli.py store --state-dir state/theses/ trim <id> \
  --contracts-sold 1 --price 4950.00 --date 2026-05-12
python3 .../trader_memory_cli.py store --state-dir state/theses/ close <id> \
  --exit-reason target_hit --actual-price 4900.00 --actual-date 2026-05-15

Python: thesis_store.attach_futures_position(state_dir, thesis_id, report_path)、 thesis_store.open_position(state_dir, thesis_id, actual_price, actual_date, contracts=..., multiplier=..., direction=...)。

関連レポートをリンク:

thesis_store.link_report(state_dir, thesis_id, skill, file, date) を使用して分析ドキュメントを相互参照します。

4. レビュー — 期日とモニタリング状況を確認する

python3 skills/trader-memory-core/scripts/trader_memory_cli.py review \
  --state-dir state/theses/ review-due --as-of 2026-04-15

next_review_date <= as_of のテーゼを一覧表示します。体系的なレビューのために kanchi-dividend-review-monitor のトリガー（T1〜T5）と併用します。

5. ポストモーテム — クローズして振り返る

python3 skills/trader-memory-core/scripts/trader_memory_cli.py review \
  --state-dir state/theses/ postmortem th_aapl_div_20260314_a3f1

state/journal/ に構造化されたポストモーテムを生成します。FMP API キーが利用可能な場合は、MAE/MFE（Maximum Adverse/Favorable Excursion）指標を含みます。

要約統計:

python3 skills/trader-memory-core/scripts/trader_memory_cli.py review \
  --state-dir state/theses/ summary

クローズされたすべてのテーゼにわたる勝率、平均損益%、およびタイプ別の内訳を表示します。

出力形式

テーゼ YAML（state/theses/）

各テーゼは以下を含む YAML ファイルです:

• 識別情報: thesis_id、ticker、created_at
• 分類: thesis_type、setup_type、catalyst
• ライフサイクル: status、status_history
• エントリー/エグジット: 目標価格、実際価格、条件
• ポジション: shares（端数対応）、value、risk（position-sizer または open-position --shares から）; または先物の場合は quantity/multiplier/direction/contract_spec（futures-position-sizer または open-position --contracts から）
• モニタリング: レビュー日、トリガー、アラート
• 起源: ソーススキル、スクリーニング評価、生の出所
• 結果: 損益、保有日数、MAE/MFE、得られた教訓

インデックス（state/theses/_index.json）

完全な YAML ファイルを読み込まずに高速にクエリするための軽量インデックス。

ジャーナル（state/journal/）

ポストモーテムの Markdown レポート: pm_{thesis_id}.md。

サポート対象の Python 読み取り・検証 API

再生処理やその他の Python 利用側では、scripts/thesis_store.py の以下の公開関数を使用してください。

from pathlib import Path
import thesis_store

thesis = thesis_store.get(Path("state/theses"), thesis_id)
thesis_store.validate_thesis(thesis)

• get(state_dir, thesis_id) は、テーゼファイルやインデックスを変更せずに、新しい YAML データを読み込みます。読み込んだ内容は検証しません。ファイルが見つからない場合は FileNotFoundError、YAML の形式が不正な場合は yaml.YAMLError が発生します。
• validate_thesis(thesis) は、JSON Schema とビジネス上の不変条件を検証し、成功時には None を返し、検証に失敗すると ValueError を発生させます。入力を変更したり、状態を書き込んだりすることはありません。
• 読み込んだレコードや正規化済みのレコードのスキーマとビジネス上の不変条件を前提とする前に、明示的に検証してください。利用側では、サポート対象のこれらの関数を使用してください。アンダースコアで始まるヘルパーは内部実装の詳細です。

主な原則

• 前進のみの遷移：IDEA → ENTRY_READY → ACTIVE → CLOSED（後戻りはできません）
• 生のデータ来歴：スクリーナーの元データはすべて origin.raw_provenance に保持されます
• アトミックな書き込み：すべてのファイル操作で tempfile + os.replace を使用します
• Git で追跡される状態：監査証跡を提供するため、state/ ディレクトリをコミットします
• フェーズ 1 の範囲：単一ティッカーのテーゼのみ（ペアトレードとオプションはフェーズ 2）

リソース

• references/thesis_lifecycle.md — ステータスと有効な遷移
• references/field_mapping.md — ソーススキルから標準フィールドへのマッピング
• schemas/thesis.schema.json — テーゼ検証用の JSON Schema
• ../../examples/workflows/trade-memory-loop/sample-run-full-path/ — Plan → Trade → Record → Postmortem → Backtest → Journal の一連の流れを通した例