cortex
Docs nav

Reference library

The reference library is the training standard for a brand. It tells Cortex what the brand's winners and losers look like in predicted response space.

Winners and losers

Every reference is labeled as a winner or a loser.

  • Winner: an ad whose response pattern you want future candidates to resemble.
  • Loser: an ad whose response pattern you want future candidates to avoid.

Both sides are required. A bank of only winners cannot define the difference between strong and weak creative for your brand.

Upload states

References move through upload and processing states:

  • Pending/uploaded: the file is present or being verified, but not ready for signature builds.
  • Verified: the reference is ready to participate if it is eligible.
  • Duplicate: the file matches an existing verified video and can reuse that effective video.
  • Rejected/failed: the upload or processing did not complete. Retry from the reference card or upload a replacement.

The build button is blocked while eligible references are still processing.

Review status

Each reference has a manual review state:

  • Pending: uploaded but not explicitly reviewed.
  • Approved: intentionally allowed to influence the signature.
  • Excluded: kept in the library but removed from signature eligibility.

Use excluded for ads that are historically useful to keep visible but should not shape the scoring standard.

Weights

Reference weight is a number from 0 to 1.

  • Weight 1: full influence.
  • Weight 0.75 or 0.5: partial influence for useful but noisy references.
  • Weight 0: removes the reference from signature influence without necessarily deleting it from the library.

Weight 0 is useful when a reference is a real historical ad but you no longer trust it as a clean winner or loser example.

KPI metadata

The reference review form can hold KPI metadata as JSON. Use it for notes such as:

{
  "platform": "Meta",
  "spend": 25000,
  "cpa": 42,
  "hook_rate": 0.31,
  "notes": "Strong holdout winner from Q2"
}

KPI metadata is context for review and future analysis. It does not automatically override the winner/loser label or weight.

Minimum viable bank

A brand can build a signature with:

  • 3 eligible winners.
  • 3 eligible losers.

That is the minimum buildable bank, not the ideal bank. Confidence improves as the bank grows, balances, and covers more creative moments. The app warns when results should be treated as directional.

Good reference hygiene

Keep references clean and balanced:

  • Avoid mixing very different offers in one brand unless candidates will also span those offers.
  • Do not label mediocre ads as winners just to reach the minimum.
  • Include losers that are true weak examples, not random unrelated videos.
  • Rebuild the signature after changing labels, weights, or review status.
  • Use diagnostics to find references that behave unlike their assigned label.