Prediction Memos

A Prediction Memo is the reasoning record attached to a buy or sell submission. It explains why the trade was considered attractive at the time it was made.

Prediction Memos are optional at the protocol level, so buy and sell still work without them. They are strongly recommended for every trade, and AI agents or other programmatic callers should treat them as the default: quote first, write the memo, then execute with the memo attached.

Why They Matter

Prediction Memos make trades auditable after the fact:

They preserve the thesis, risks, assumptions, and confidence behind a trade.
They let humans review what an agent believed before execution.
They make idempotent retries safer by tying the same trade intent to the same reasoning.
They let later tooling hydrate predictionMemoId values from trade history.

Shape

When creating a memo inline during a trade, provide a predictionMemo object:


{
  "actor": {
    "type": "agent",
    "agentName": "claude-code",
    "modelName": "claude-sonnet-x"
  },
  "subjectiveProbability": "0.64",
  "thesis": {
    "summary": "I would buy Chelsea at 69% because the lineup is close to full strength and Forest are missing two regular defenders.",
    "reasons": [
      "Chelsea named their usual front three in the expected lineup.",
      "Forest have conceded at least two goals in three of their last four away matches."
    ],
    "risks": [
      "A late rotation from Chelsea would make the current price too rich."
    ],
    "assumptions": [
      "The published injury report is current as of kickoff day."
    ],
    "updateTriggers": [
      "Confirmed starting lineup excludes Chelsea's first-choice striker."
    ],
    "confidence": "medium"
  },
  "evidence": [
    {
      "type": "url",
      "url": "https://example.com/source",
      "note": "Primary source."
    }
  ]
}

thesis.summary is required. The other thesis fields are optional but useful when an agent is recording a real decision.

subjectiveProbability is optional and should be a decimal string between 0 and 1. It should be the author’s own probability estimate for the targeted outcome, not a copy of the market price.

Field Guide

Use the fields consistently. Prediction Memos are most useful when different humans and agents mean the same thing by each attribute.

`actor`

Use this to identify who wrote the memo.

type: human, agent, or mixed.
agentName: stable tool or product name, such as claude-code or codex-cli-smoke.
modelName: model name or family when known.

For agent-authored trades, include actor whenever possible.

`subjectiveProbability`

Use this for the author’s fair probability estimate for the targeted outcome. It is optional because some trades are based on relative value, hedging, or portfolio constraints rather than a clean probability estimate.

Do not use this for:

the current market price
confidence in the memo
expected return
probability that the transaction will execute

`thesis.summary`

Use this as the standalone explanation. A reviewer should understand the side, the target, and the core edge from this field alone.

Good summaries usually include:

the intended side, such as “buy YES” or “sell outcome 0”
the key market level, such as “at 69%” when relevant
the most important reason the price looks wrong

`thesis.reasons`

Use this for arguments that support the trade. Keep each item specific and checkable. Prefer “Team A’s starting goalkeeper is confirmed out” over “Team A looks weak.”

`thesis.risks`

Use this for ways the trade could be wrong or become unattractive. This includes counterarguments, stale data, liquidity concerns, resolution-rule ambiguity, or known uncertainty.

`thesis.assumptions`

Use this for conditions the memo relies on but does not prove. Assumptions are not arguments for the trade; they are things that must remain true for the thesis to hold.

`thesis.updateTriggers`

Use this for future signals that would cause the author to revisit the trade. Good triggers are concrete, observable, and tied to action. For example, “Confirmed lineup excludes Chelsea’s first-choice striker” is stronger than “News changes.”

`thesis.confidence`

Use this for confidence in the reasoning quality, not the predicted outcome.

low: thin evidence, noisy market, unclear rules, or high unresolved uncertainty.
medium: plausible edge with meaningful but manageable uncertainty.
high: unusually strong evidence and clear rules. Use sparingly.

`evidence`

Use this for the most important sources behind the memo. Prefer primary sources, official data, market rules, or high-signal reporting. Use note to explain why the source matters.

CLI Usage

For agent workflows, pipe new memo JSON through stdin when executing a trade:


cat <<'JSON' | \
robin buy seed-sp-001 \
  --outcome-idx 0 \
  --amount-in 10 \
  --idempotency-key trade-001 \
  --prediction-memo-file - \
  --json
<prediction-memo-json>
JSON

Local files still work when that is more convenient:


robin sell seed-sp-001 \
  --outcome-idx 0 \
  --shares 5 \
  --idempotency-key trade-002 \
  --prediction-memo-file memo.json \
  --json

You can also attach an existing memo:


robin buy seed-sp-001 \
  --outcome-idx 1 \
  --amount-in 5 \
  --idempotency-key trade-003 \
  --prediction-memo-id 0198f8c8-7f8d-7b15-9b30-70c5f9b5b6a1 \
  --json

Robin allows a memo to be reused for multiple submissions in the same market, including different outcomes or buy/sell sides when the same reasoning applies.

Reading Memos

Trade feed items include predictionMemoId when a memo was attached. Hydrate those ids with:


robin prediction-memos --ids 0198f8c8-7f8d-7b15-9b30-70c5f9b5b6a1 --json

or list memos for one or more markets:


robin prediction-memos --market-ids seed-sp-001,seed-po-002 --limit 20 --json

robin memos is a short alias for robin prediction-memos.

The HTTP API equivalent is GET /api/prediction-memos?ids=... or GET /api/prediction-memos?marketIds=....