Track investment theses across their lifecycle — from screening idea to closed position with postmortem. Register theses from screener outputs, manage state transitions, attach position sizing, review due dates, and generate postmortem reports with P&L and MAE/MFE analysis. Trigger when user says "register thesis", "track this idea", "thesis status", "review due", "close position", "postmortem", or "trading journal".
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.
pyyaml (already in project dependencies)Read the screener's JSON output and convert to thesis using the appropriate adapter.
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.
python3 skills/trader-memory-core/scripts/thesis_store.py \
--state-dir state/theses/ list --ticker AAPL --status ACTIVE
Filter by --ticker, --status, or --type.
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.
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.
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:
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.
Each thesis is a YAML file with:
Lightweight index for fast queries without loading full YAML files.
Postmortem markdown reports: pm_{thesis_id}.md.
origin.raw_provenancestate/ directory is committed, providing audit trailreferences/thesis_lifecycle.md — Status states and valid transitionsreferences/field_mapping.md — Source skill → canonical field mappingschemas/thesis.schema.json — JSON Schema for thesis validation