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 へと遷移させるとき
• position-sizer の出力をセシスに添付するとき
• どのセシスがレビュー期限を迎えているかを確認するとき
• ポジションをクローズし、学んだ教訓を含むポストモーテムを生成するとき

前提条件

• Python 3.10+
• pyyaml（すでにプロジェクトの依存関係に含まれています）
• FMP API キー（任意、ポストモーテムでの MAE/MFE 計算にのみ使用）

ワークフロー

1. Register — スクリーナー出力をセシスとして取り込む

スクリーナーの JSON 出力を読み取り、適切なアダプターを使ってセシスに変換します。

python3 skills/trader-memory-core/scripts/thesis_ingest.py \
  --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。

各セシスは IDEA ステータスで開始します。

2. Query — セシスの検索と一覧表示

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

--ticker、--status、または --type でフィルタリングします。

3. Update — 遷移、ポジションの添付、レポートのリンク

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

Python から thesis_store.transition(state_dir, thesis_id, "ENTRY_READY", reason) を使用します。

ポジションのオープン（ENTRY_READY → ACTIVE）:

thesis_store.open_position(state_dir, thesis_id, actual_price, actual_date) を使用します — ACTIVE への唯一の経路です。オプションの shares と event_date（過去のトレードを遡って記録する場合）を受け付けます。

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

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 を進め、アラートを記録します。

position-sizer 出力の添付:

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

関連レポートのリンク:

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

4. Review — 期限とモニタリング状況の確認

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

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

5. Postmortem — クローズと振り返り

python3 skills/trader-memory-core/scripts/thesis_review.py \
  --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/thesis_review.py \
  --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 から添付）
• モニタリング: レビュー日、トリガー、アラート
• 由来: ソーススキル、スクリーニング評価、生の出所
• 結果: 損益、保有日数、MAE/MFE、学んだ教訓

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

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

ジャーナル（state/journal/）

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

主要な原則

• 前方のみの遷移: 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