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> 进行调用，因此即使当前工作目录不属于该仓库，或运行 python3 时未全局安装 jsonschema（例如 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，且 PATH 中也没有 uv，请按以下优先顺序采取可行的解决办法：

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）进行的交易，或手动记录的交易 — 请使用 manual 来源和自由格式的 JSON 文件（单个对象或数组）：

{
  "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 可以是小数（架构接受任意正数）。与所有适配器一样，手动导入只会创建状态为 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 午夜）或完整的 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 时被拒绝，并给出清晰的错误提示。

对于期货论点，请使用 --contracts，而非 --shares（参见下文的 “期货持仓”）——如果 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）会被视为全部未平仓。

对于期货论点，请使用 --contracts-sold，而非 --shares-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"），则它是期货投资论点。期货投资论点使用 quantity / quantity_remaining（整数合约，不支持小数合约），而不是 shares / shares_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 自动分派——这四种操作无需单独的期货子命令。仅支持以 USD 计价的合约——盈亏计算流程中不会进行外汇换算，因此会直接拒绝非 USD 的 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 不是 USD，则会拒绝该报告。 重新附加的状态限制仅允许 IDEA/ENTRY_READY——比股票的 attach-position 更严格（它还允许 ACTIVE）：在 ACTIVE 状态重新附加期货持仓会静默覆盖整个持仓字典，包括 direction，从而反转后续所有盈亏计算的符号。要更正已开仓的期货持仓，需要创建新的投资论点（或等待未来专用的“amend”操作），不能重新附加。

直接开仓，无需附加（通过 CLI 标志构建持仓，而不是使用 SIZED 报告——此处必须提供 --contract-currency，因为没有可读取币种的 contract_spec，且该值必须为 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

减仓 / 平仓 / 终止——使用与股票相同的子命令，将 --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（最大不利 / 有利波动）指标。

汇总统计：

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 数据，不修改 thesis 文件或索引。它不会验证加载的内容。文件缺失时会引发 FileNotFoundError；YAML 格式错误时会引发 yaml.YAMLError。
• validate_thesis(thesis) 会检查 JSON Schema 和业务不变量，成功时返回 None，验证失败时引发 ValueError。它不会修改输入或写入状态。
• 在依赖记录的 schema 和业务不变量之前，明确验证已加载或规范化的记录。使用方应通过这些受支持的函数进行操作；以下划线开头的辅助函数属于内部实现细节。

关键原则

• 仅允许向前转换：IDEA → ENTRY_READY → ACTIVE → CLOSED（不可回退）
• 原始溯源信息：所有原始筛选器数据均保存在 origin.raw_provenance 中
• 原子写入：所有文件操作均使用 tempfile + os.replace
• 由 Git 跟踪状态：提交 state/ 目录，以提供审计跟踪
• 第一阶段范围：仅支持单一标的的 thesis（配对交易和期权将在第二阶段支持）

资源

• references/thesis_lifecycle.md — 状态及有效转换
• references/field_mapping.md — 源技能到规范字段的映射
• schemas/thesis.schema.json — 用于验证 thesis 的 JSON Schema
• ../../examples/workflows/trade-memory-loop/sample-run-full-path/ — Plan → Trade → Record → Postmortem → Backtest → Journal 的端到端示例