trader-memory-core

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.

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

Prerequisites

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

Workflow

1. Register — Ingest screener output as thesis

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.

2. Query — Search and list theses

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

Filter by --ticker, --status, or --type.

3. Update — Transition, attach position, link reports

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.

4. Review — Check due dates and monitoring status

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.

5. Postmortem — Close and reflect

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.

Output Format

Thesis 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

Index (state/theses/_index.json)

Lightweight index for fast queries without loading full YAML files.

Journal (state/journal/)

Postmortem markdown reports: 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)

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