OverviewHistoryStatsSecurity
npx skills add ...
Documentation
SKILL.md
npx skills add tradermonty/claude-trading-skills --skill trader-memory-core
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".
npx skills add tradermonty/claude-trading-skills --skill trader-memory-core
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)jsonschema (already in pyproject.toml; required by thesis_store.py and every command that imports it, including thesis_ingest.py and thesis_review.py)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):
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:
uv (https://docs.astral.sh/uv/) and re-run the launcher.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.
Read the screener's JSON output and convert to thesis using the appropriate adapter.
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.
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):
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):
Filter by --ticker, --status, or --type.
Each lifecycle operation is available both as a Python function and as a
thesis_store.py CLI subcommand. --event-date / --actual-date accept a
plain YYYY-MM-DD (widened to midnight UTC) or a full ISO timestamp.
State transition (IDEA → ENTRY_READY only):
--event-date backdates status_history.at (use it when backfilling an
existing position so the later backdated open-position stays chronological).
Python: thesis_store.transition(state_dir, thesis_id, "ENTRY_READY", reason, event_date=...).
Open position (ENTRY_READY → ACTIVE — the only path to ACTIVE):
--shares accepts fractional quantities. Python:
thesis_store.open_position(state_dir, thesis_id, actual_price, actual_date, shares=..., event_date=...).
shares (and shares_remaining, when present) must be a finite, positive
number no greater than 1012 (a sanity bound, not an economic
constraint — fractional shares below the cap remain unrestricted). NaN,
±Infinity, and absurdly large values (e.g. a malformed position-sizer
report) are rejected with a clean error at save time, on open-position,
attach-position, and trim alike.
For a futures thesis, use --contracts instead of --shares (see
"Futures positions" below) — if attach-futures-position already populated
the position, omit --contracts and only pass --actual-price/--actual-date.
Trim — partial close (ACTIVE/PARTIALLY_CLOSED → PARTIALLY_CLOSED, or → CLOSED when the whole remainder is sold):
position.shares is the original opened quantity (immutable);
position.shares_remaining tracks what is still open. Each trim appends a
status_history ledger entry (shares_sold / price / proceeds /
realized_pnl). outcome.pnl_dollars is the cumulative realized P&L
(Σ all trims + final close); outcome.pnl_pct = pnl_dollars / (entry_price × original_shares) × 100. A trim that sells the entire remainder closes the
thesis (default exit_reason: manual, overridable with --exit-reason).
--date is the ledger timestamp (override with --event-date). Python:
thesis_store.trim(state_dir, thesis_id, shares_sold, price, date, ...).
Status invariants: ACTIVE ⇒ shares_remaining == shares;
PARTIALLY_CLOSED ⇒ 0 < shares_remaining < shares; CLOSED ⇒
shares_remaining == 0. Legacy theses (no shares_remaining) are treated as
fully open at runtime.
For a futures thesis, use --contracts-sold instead of --shares-sold —
close/terminate need no flag changes; they read position.asset_type and
dispatch automatically (see "Futures positions" below).
Close or invalidate (→ CLOSED or INVALIDATED):
close accepts an ACTIVE or PARTIALLY_CLOSED thesis; from
PARTIALLY_CLOSED it adds the final leg and reports the cumulative outcome.
Python: thesis_store.terminate(state_dir, thesis_id, terminal_status, exit_reason, actual_price, actual_date). For CLOSED, delegates to close() which computes P&L (fractional-share aware). 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:
Python: thesis_store.attach_position(state_dir, thesis_id, report_path) to link position sizing data. Validates that the report mode is "shares" (not budget).
A thesis whose position.asset_type == "futures" (or quantity_unit == "contracts") is a futures thesis. Futures theses use quantity /
quantity_remaining (whole contracts — no fractional contracts) instead of
shares / shares_remaining, carry a direction (LONG or SHORT) and a
multiplier, and every P&L computation (close, terminate, trim) applies
(exit_price - entry_price) × multiplier × quantity × sign (sign = +1
LONG, −1 SHORT) instead of the equity per-unit formula. close / terminate
/ trim / open-position all dispatch on position.asset_type automatically
— no separate futures subcommands for those four operations. USD-denominated
contracts only — there is no FX conversion in the P&L path, so a non-USD
contract_spec.currency is rejected outright rather than computing P&L in
the wrong currency's magnitude.
Attach a futures-position-sizer SIZED report (step 6 of the Shapiro contrarian pipeline — futures-position-sizer → trader-memory-core):
Rejects a NO_TRADE report (sizing_status != "SIZED"), an invalid
direction, a non-positive/fractional contracts count, a non-finite/non-positive
contract_spec.multiplier, or a non-USD contract_spec.currency.
Re-attach status guard is IDEA/ENTRY_READY only — stricter than
equity's attach-position (which also allows ACTIVE): re-attaching a
futures position on ACTIVE would silently overwrite the entire position
dict including direction, flipping the sign of every subsequent P&L
computation. Correcting an already-open futures position needs a fresh
thesis (or a future dedicated "amend" operation) — not a re-attach.
Direct open, no attach (build the position from CLI flags instead of a
SIZED report — --contract-currency is required here since there is no
contract_spec to read a currency from, and must be USD):
Trim / close / terminate — same subcommands as equity, --contracts-sold
in place of --shares-sold:
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=...).
Link related reports:
Use thesis_store.link_report(state_dir, thesis_id, skill, file, date) to cross-reference analysis documents.
List theses with next_review_date <= as_of. Use with kanchi-dividend-review-monitor triggers (T1-T5) for systematic review.
Generate a structured postmortem in state/journal/. If FMP API key is available, includes MAE/MFE (Maximum Adverse/Favorable Excursion) metrics.
Summary statistics:
Shows win rate, average P&L%, and per-type breakdown across all closed theses.
Each thesis is a YAML file with:
open-position --shares); or, for futures, quantity/multiplier/direction/contract_spec (from futures-position-sizer or open-position --contracts)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../../examples/workflows/trade-memory-loop/sample-run-full-path/ — Worked end-to-end Plan → Trade → Record → Postmortem → Backtest → Journal example