trader-memory-core

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Trader Memory Core

Overview

概述

Persistent state layer that bundles screening → analysis → position sizing → portfolio management outputs into a single "thesis object" per investment idea. Tracks what you thought, what happened, and what you learned — across conversations.

Phase 1 supports single-ticker theses: dividend_income, growth_momentum, mean_reversion, earnings_drift, pivot_breakout.

持久化状态层，将筛选→分析→仓位规模设置→投资组合管理的输出捆绑为每个投资想法对应的单个“论点对象”。跨对话记录你的想法、实际发生的情况以及你学到的经验。

第一阶段支持单标的论点：股息收益（dividend_income）、增长动量（growth_momentum）、均值回归（mean_reversion）、收益漂移（earnings_drift）、突破反转（pivot_breakout）。

When to Use

使用场景

After a screener (kanchi, earnings-trade-analyzer, vcp, pead, canslim, edge-candidate-agent) produces candidates
When transitioning a thesis from IDEA → ENTRY_READY → ACTIVE → CLOSED
When attaching position-sizer output to a thesis
When checking which theses are due for review
When closing a position and generating a postmortem with lessons learned

当筛选工具（kanchi、earnings-trade-analyzer、vcp、pead、canslim、edge-candidate-agent）生成候选标的后
当论点从IDEA（想法）→ENTRY_READY（准备入场）→ACTIVE（持仓中）→CLOSED（已平仓）状态转换时
当为论点附加仓位规模计算输出时
当需要查看哪些论点即将到期需要复查时
当平仓并生成包含经验总结的复盘报告时

Prerequisites

前置要求

Python 3.10+
```
pyyaml
```
(already in project dependencies)
FMP API key (optional, only for MAE/MFE calculation in postmortem)

Python 3.10+
```
pyyaml
```
（已包含在项目依赖中）
FMP API密钥（可选，仅用于复盘中的MAE/MFE计算）

Workflow

工作流程

1. Register — Ingest screener output as thesis

1. 登记——将筛选工具输出导入为论点

Read the screener's JSON output and convert to thesis using the appropriate adapter.

bash

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/

Supported sources:

kanchi-dividend-sop

earnings-trade-analyzer

vcp-screener

pead-screener

canslim-screener

edge-candidate-agent

Each thesis starts in

IDEA

status.

读取筛选工具的JSON输出，通过对应的适配器转换为论点格式。

bash

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 — Search and list theses

2. 查询——搜索并列出论点

bash

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

Filter by

--ticker

--status

, or

--type

bash

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

可通过

--ticker

（标的代码）、

--status

（状态）或

--type

（类型）筛选。

3. Update — Transition, attach position, link reports

3. 更新——状态转换、附加仓位、关联报告

State transition (IDEA → ENTRY_READY only):

Use

thesis_store.transition(state_dir, thesis_id, "ENTRY_READY", reason)

from Python.

Open position (ENTRY_READY → ACTIVE):

Use

thesis_store.open_position(state_dir, thesis_id, actual_price, actual_date)

— the only path to ACTIVE. Accepts optional

shares

and

event_date

(for backfilling past trades).

Close or invalidate (→ CLOSED or INVALIDATED):

Use

thesis_store.terminate(state_dir, thesis_id, terminal_status, exit_reason, actual_price, actual_date)

. For CLOSED, delegates to

close()

which computes P&L. For INVALIDATED, P&L is computed if entry/exit prices are available.

Record review (any non-terminal):

Use

thesis_store.mark_reviewed(state_dir, thesis_id, review_date=..., outcome="OK"|"WARN"|"REVIEW")

to advance next_review_date and record alerts.

Attach position-sizer output:

Use

thesis_store.attach_position(state_dir, thesis_id, report_path)

to link position sizing data. Validates that the report mode is "shares" (not budget).

Link related reports:

Use

thesis_store.link_report(state_dir, thesis_id, skill, file, date)

to cross-reference analysis documents.

状态转换（仅支持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()

方法计算盈亏（P&L）。对于INVALIDATED状态，如果提供了入场/出场价格，也会计算盈亏。

记录复查结果（适用于所有非终结状态）：

调用

thesis_store.mark_reviewed(state_dir, thesis_id, review_date=..., outcome="OK"|"WARN"|"REVIEW")

来更新下一次复查日期并记录告警信息。

附加仓位规模计算输出：

调用

thesis_store.attach_position(state_dir, thesis_id, report_path)

来关联仓位规模数据。会验证报告模式为“shares”（股数模式，而非预算模式）。

关联相关报告：

调用

thesis_store.link_report(state_dir, thesis_id, skill, file, date)

来交叉引用分析文档。

4. Review — Check due dates and monitoring status

4. 复查——检查到期日期和监控状态

bash

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

List theses with

next_review_date <= as_of

. Use with kanchi-dividend-review-monitor triggers (T1-T5) for systematic review.

bash

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 — Close and reflect

5. 复盘——平仓与反思

bash

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

Generate a structured postmortem in

state/journal/

. If FMP API key is available, includes MAE/MFE (Maximum Adverse/Favorable Excursion) metrics.

Summary statistics:

bash

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

Shows win rate, average P&L%, and per-type breakdown across all closed theses.

bash

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（最大不利偏移/最大有利偏移）指标。

汇总统计：

bash

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

展示所有已平仓论点的胜率、平均盈亏百分比以及按类型划分的细分数据。

Output Format

输出格式

Thesis YAML (state/theses/)

论点YAML文件（state/theses/目录下）

Each thesis is a YAML file with:

Identity: thesis_id, ticker, created_at
Classification: thesis_type, setup_type, catalyst
Lifecycle: status, status_history
Entry/Exit: target prices, actual prices, conditions
Position: shares, value, risk (attached from position-sizer)
Monitoring: review dates, triggers, alerts
Origin: source skill, screening grade, raw provenance
Outcome: P&L, holding days, MAE/MFE, lessons learned

每个论点对应一个YAML文件，包含以下内容：

标识信息：thesis_id（论点ID）、ticker（标的代码）、created_at（创建时间）
分类信息：thesis_type（论点类型）、setup_type（交易架构类型）、catalyst（催化剂）
生命周期：status（当前状态）、status_history（状态历史）
入场/出场：target prices（目标价格）、actual prices（实际价格）、conditions（条件）
仓位：shares（股数）、value（市值）、risk（风险，来自仓位规模工具）
监控：review dates（复查日期）、triggers（触发器）、alerts（告警）
来源：source skill（来源工具）、screening grade（筛选评级）、raw provenance（原始溯源数据）
结果：P&L（盈亏）、holding days（持有天数）、MAE/MFE、lessons learned（经验总结）

Index (state/theses/_index.json)

索引文件（state/theses/_index.json）

Lightweight index for fast queries without loading full YAML files.

轻量级索引，无需加载完整YAML文件即可快速查询。

Journal (state/journal/)

日志目录（state/journal/）

Postmortem markdown reports:

pm_{thesis_id}.md

复盘Markdown报告：命名格式为

pm_{thesis_id}.md

。

Key Principles

核心原则

Forward-only transitions: IDEA → ENTRY_READY → ACTIVE → CLOSED (no backtracking)
Raw provenance: All original screener data preserved in
```
origin.raw_provenance
```
Atomic writes: All file operations use tempfile + os.replace
Git-tracked state:
```
state/
```
directory is committed, providing audit trail
Phase 1 scope: Single-ticker theses only (pair trades and options in Phase 2)

单向状态转换：仅支持IDEA → ENTRY_READY → ACTIVE → CLOSED（不允许回溯）
原始溯源保留：所有原始筛选数据均保留在
```
origin.raw_provenance
```
字段中
原子写入：所有文件操作均使用临时文件+os.replace实现
Git追踪状态：
```
state/
```
目录会被提交到Git，提供审计追踪能力
第一阶段范围：仅支持单标的论点（配对交易和期权交易将在第二阶段支持）

Resources

资源

```
references/thesis_lifecycle.md
```
— Status states and valid transitions
```
references/field_mapping.md
```
— Source skill → canonical field mapping
```
schemas/thesis.schema.json
```
— JSON Schema for thesis validation

```
references/thesis_lifecycle.md
```
——状态定义及有效转换规则
```
references/field_mapping.md
```
——来源工具→标准字段映射关系
```
schemas/thesis.schema.json
```
——论点验证用JSON Schema