/trader-memory-core

name: trader-memory-core
description: 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".

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)
• `jsonschema` (already in `pyproject.toml`; required by `thesis_store.py` and every command that imports it, including `thesis_ingest.py` and `thesis_review.py`)
• FMP API key (optional, only for MAE/MFE calculation in postmortem)

How to invoke the CLI

Use the stdlib-only launcher `trader_memory_cli.py` for all CLI work. It transparently routes through `uv run --project <repo>` when `uv` is available, so the repo's pinned `jsonschema` is reachable even from a foreign cwd or from `python3` with no global `jsonschema` (e.g. cron / Hermes profile runs):

# 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

Subcommands: `store` → `thesis_store.py`, `ingest` → `thesis_ingest.py`, `review` → `thesis_review.py`. Everything after the subcommand is forwarded verbatim, so existing argument flags (`--state-dir`, `transition`, `open-position`, etc.) work unchanged.

If the launcher reports that `jsonschema` is not importable AND `uv` is not on `PATH`, the actionable fixes (in priority order) are:

1. Install `uv` (https://docs.astral.sh/uv/) and re-run the launcher. 2. Install the project's dependencies into the current interpreter:

   uv pip install -e /path/to/claude-trading-skills
   # or, as a last resort:
   python3 -m pip install jsonschema

Do **not** treat the thesis store as unavailable and do **not** mutate `state/theses/*.yaml` by hand to work around a missing dependency — schema validation is part of thesis state integrity.

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/trader_memory_cli.py ingest \
  --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`, `manual`.

Each thesis starts in `IDEA` status.

For `kanchi-dividend-sop`, registration is fail-closed: each row must carry one of `CLEAN-PASS`, `PASS-CAUTION`, or `CONDITIONAL-PASS` in `verdict`. Missing verdicts and `HOLD-REVIEW` / `STEP1-RECHECK` / `FAIL` rows are skipped and never written to thesis state.

Manual brokerage entry (fractional shares)

For trades that did **not** come from a screener — e.g. fractional-share brokers (IBKR, Robinhood, IBI Smart, Alpaca, eToro) or hand journaling — use the `manual` source with a free-form JSON file (a single object or an array):

{
  "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/

Required: `ticker`, `thesis_statement`, `thesis_type` (one of `dividend_income`, `growth_momentum`, `mean_reversion`, `earnings_drift`, `pivot_breakout`). `stop_price`/`stop_loss` and `target_price`/`take_profit` map to `exit.stop_loss`/`exit.take_profit`; `entry_price`/`entry_date`/`shares` are kept in `origin.raw_provenance` — the authoritative entry price/date and share count are set when you open the position (below). `shares` may be **fractional** (the schema accepts any positive number). Like every adapter, manual ingest creates an `IDEA` thesis only — it never mutates status directly.

To record an **already-open broker position**, run the explicit lifecycle sequence (the `--event-date` flags backdate the history so it stays chronological):

# 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-