Colour Memory

Evaluates contrast for a single foreground/background pair. For palettes or multiple colours, use accessibility_matrix instead, it replaces multiple accessibility_check calls in one response.

Given a background hex and a palette of candidate foreground colours, return them ranked by contrast ratio with WCAG grades and specific recommendations for body text, large text, and UI components.

Accept a palette array and return every foreground/background combination with contrast ratio, AA normal, AA large, AAA normal, AAA large pass/fail grades, and a summary. Use this instead of calling accessibility_check multiple times for a palette.

Convert a palette WCAG matrix into actionable design-system rules. Returns safe pairs, AA-only pairs, large-text-only pairs, decorative-only pairs, best text colour per background, and component usage rules. Deterministic, no LLM cost.

Return simulated hex values for full-severity protanopia, deuteranopia and tritanopia only, using the Machado, Oliveira & Fernandes (2009) model (severity 1.0, linear sRGB), with a flag when a simulated colour had to be clipped to sRGB. Anomalous trichromacy and partial severities are not simulated. A model prediction on a standard display, not how an individual perceives colour.

Generate a complete colour direction package for another AI agent or image generation model. Fetches a historically grounded archive palette from the concept, then produces: an agent brief (colour direction in prose), colour tokens with hex values and roles, a model-specific image generation prompt, a negative prompt, and lighting notes. Supports midjourney, flux, dalle, stable_diffusion. Example: task='luxury hotel bedroom', concept='Ottoman winter luxury', model='midjourney'. Use this to make Colour Memory the colour layer for other AI systems. Archive-grounded retrieval is evidence-filtered: entries with claim_role='reject' (no primary source and no period connection), stub entries, blank-source entries, and entries below minimum_claim_strength are never selected. If fewer than palette_size colours pass these filters, the call returns an honest incomplete result (ok:false, error_code:INSUFFICIENT_EVIDENCE_ELIGIBLE_PALETTE) rather than padding the palette with rejected or weak evidence. Negative constraints (from 'avoid' or negation phrases in concept like 'must never', 'without', 'not') are also applied to retrieval, not just flagged afterward -- a brief that says a wedding must never feel funereal will not surface mourning-themed colours in the first place. locked_palette calls skip evidence filtering entirely since the caller is supplying colours directly, not requesting archive evidence.

Verify that an AI-generated image actually used the colours specified in an agent_brief call. Supply the generated image (URL or base64) and the target palette from agent_brief colour_tokens. Returns a fidelity score 0-100, dE2000 distance per colour, match quality per colour (accurate/acceptable/drifted/ignored), and an overall verdict. Use after agent_brief + image generation to close the colour loop.

Find the most surprising archive colour for a concept and generate a memorable one-liner subverting the obvious expectation. Supply a concept (e.g. 'love', 'grief', 'luxury', 'power') and optionally the expected colour (e.g. 'red' for love). The archive finds the contradiction and Claude writes the one-liner, short story, and tweet. Example: love + red returns Shakespeare's dark green with 'Love is not red. It is the green of someone still waiting in a field.' Use this for public-facing demos, content, and brand storytelling.

Given a list of themes, report which are well-evidenced in the archive and which are under-evidenced or missing. Returns a coverage matrix: for each theme, entries found, coverage grade (strong/moderate/weak/missing), best match with claim strength, and what source type would be needed to improve coverage. Use this BEFORE building an archive_report_brief or brief_forensic to know where the evidence is strong and where gaps will appear. Prevents building beautiful reports that quietly ignore half the brief.

Check a list of colour entries for anachronism risk. Detects whether the primary source date falls outside the requested period, whether the archive is a known modern source (RacingSilks, FootballStrips), and returns a period_relevance score and safe phrasing. Essential for historical documents: prevents a 2011 Jockey Club racing silk registration being presented as Georgian evidence. Returns anachronism_risk (none/low/medium/elevated/high), period_relevance score 0-1, safe_phrasing, and unsafe_phrasing for each entry.

Given a hex value and a proposed claim about it, return whether the archive supports that claim, what is missing, what kind of source would be needed, and safe agent wording. This is Colour Memory's anti-hallucination endpoint. It turns the absence of evidence into a forensic finding rather than a gap to fill with invention. Example: hex #4A535C + proposed claim 'cyanosis in a death chamber' returns: nearest archive support, support level (supported/partial/unsupported), what source type is needed, and safe wording for the agent to use. Essential for museum, documentary, editorial, legal, and forensic workflows.

Explains the provenance of a named archive colour: documented fact vs computational derivation vs cultural interpretation, with confidence and citation format. This is one component of colour_passport, but also a standalone research tool for deep provenance work (museum, documentary, editorial). Use colour_passport for a general profile; call this directly for research workflows needing full source-chain detail.

One-call complete archive research package for a document, PDF, or editorial brief. Input: title, audience, themes, archives to draw from, things to avoid, number of colours. Output: ranked colour cards with full provenance, story order, source confidence flags, pull quote, CTA line, CSS tokens, image prompt for Midjourney/Flux/DALLE, editorial argument, weakest and strongest entries identified. Replaces chaining archive_search + get_colour_card + cliche_breaker + agent_brief separately. Two Claude calls total. This is the endpoint for building premium archive documents, PDFs, briefs, and editorial content. Use this first for any document workflow.

Full-text keyword search across all archive colour names and notes. Find colours by name fragment, material, cultural reference, pigment type, or historical period. Complements conceptual embedding search with exact keyword matching. Examples: 'cerulean' (28 matches, e.g. Bourton Cerulean), 'Prussian' (187 matches spanning pigment history), 'medieval' (over 1,000 matches across period archives). Never returns a bare empty result for a genuinely obscure query -- result_path in the response is 'direct' (exact keyword hit), 'broadened' (archive restriction dropped), or 'redirected' (fell back to conceptual/semantic search) so you always know which one fired. Set entity_mode='exact' to search by botanical identity rather than by word: a plain query for 'Rose' matches any cultivar name containing it (including Sweet Peas called 'Rose Pink'), whereas entity_mode='exact' returns genus Rosa only and discloses how many off-genus records were excluded.

Complete brand asset pack. Returns CSS variables, Tailwind config, Figma tokens JSON, citation cards, and a Markdown brand guide. Everything a brand team needs to ship. Deterministic. No LLM cost.

Fast, fully deterministic brand colour audit. Accepts a palette array plus market, use_case, medium and brand_category. COMPUTED SYNCHRONOUSLY, no model call of any kind: colour roles with archive names, the full WCAG accessibility matrix, cultural risk per colour, CSS variables, Tailwind config, design tokens and production notes. NOT COMPUTED HERE: palette interpretation -- the verdict, its score and the written narrative copy. Those require an LLM call and used to be made inside this tool without saying so, which put a normal five-colour audit at 43-45s. The palette_verdict and verdict_copy keys are still returned, carrying interpretation_status='not_computed' plus a ready-to-send palette_verdict.continuation.arguments -- forward those verbatim to the palette_verdict tool to get the interpretation. Replaces chaining accessibility_matrix + cultural_risk_assessment; palette_verdict is now an explicit, optional second call rather than a hidden one. FOR A LIVE-SITE BRAND AUDIT ('audit this website'): inspect representative rendered pages FIRST (homepage, about, one deep page) and pass what you observed as site_evidence -- a CSS scrape alone is not an audit of what a visitor sees, and the response's audit_evidence.audit_status will say PARTIAL until real multi-page rendered evidence is supplied. The result already carries the rendered palette and its PNG, PDF, ASE, JSON and CSS downloads -- show them to the customer. Never present the archive anchors a colour was derived from as the colours you are recommending. If you go on to choose a final palette OF YOUR OWN from this evidence, call palette_finalize once with those exact colours so the customer can see and download what you actually recommended.

Can this brand own this colour against these competitors in this market? Input: brand hex, brand name, competitor hexes and names, market, region. Returns CIEDE2000 distance to each competitor, archive context for each colour, a distinctiveness score (0-100), an ownership verdict (strong/viable/contested/collision), a plain-English verdict summary, and a strategic recommendation. Use before committing to a brand colour in a competitive market. Replaces manual colour distance checks and competitor palette analysis.

Resolves claim_id values (returned inline on every colour by brand_guideline_specify and brand_guideline_select) into their full claim record: source title/locator/citation, the exact permitted claim text, do_not_say restrictions, and claim_role (anchor/analogue/reject). Read-only -- reads the already-persisted, frozen brand_ref snapshot, never re-runs generation or mutates anything. Omit claim_ids to return every claim on the brand_ref. Accepts exactly one of brand_ref or project_id, same as brand_guideline_pdf.

Renders a client-facing brand colour standard from an existing brand_ref. The document covers the direction carried forward and its assessment, the colour system in proportion, the argument for the palette, packaging and digital application, a full pairwise WCAG accessibility matrix computed upstream (never hand-drawn examples), and a provenance and evidence register in which every claim is bound to the colour it belongs to. Page count is not fixed: sections that have nothing real to say are omitted rather than padded -- a single-candidate brand_ref drops the comparison spread, and a candidate that was never scored for distinctiveness gets a different page shape rather than an empty scale. Derived colours are never presented in documented-source language. Renders the brand_guideline_select-chosen candidate if one has been recorded, otherwise the strongest eligible candidate as a provisional preview (clearly labelled as such). Reads only the already-persisted, frozen snapshot -- never re-runs brand_guideline_specify, never rematches an archive, never mutates the resolved project. Accepts exactly one of brand_ref or project_id.

Records which brand_guideline_specify candidate was chosen, which colours should be locked for future iteration, and which claims should be suppressed -- produces a revised brand_ref (same reference, a new version underneath it, exactly like a versioned house_ref). No accounts or reviewer states yet -- this demonstrates decision-making, not a full approval workflow.

Generates the case for a brand's colours, not just the colours themselves: three genuinely different, archive-grounded candidate palettes from a brand brief, each scored for distinctiveness against named competitors, checked for accessibility, and labelled with exactly what each colour can and cannot legitimately claim (documented archive anchor vs analogue vs original brand colour). Returns a brand_ref (valid 24h) plus a claim_id per colour -- resolve those into full source/permitted-claim/do_not_say text with brand_guideline_claims (the response's own claim_detail_available_via field always names it explicitly). Follow with brand_guideline_select to record which candidate was chosen. CREATE ONCE, THEN VERSION: the response returns project_id and current_version. When you refine or update a Brand Standard you already created in this conversation, pass that project_id back as continue_project_id rather than creating a second project. TIMING (2026-08-07): real generation cost ranges roughly 60-280 seconds depending on retrieval/generation path. This call races generation against a safe ~55s window: a fast generation returns the full result exactly as described above, unchanged. A slower generation instead returns a compact {"status": "processing", "brand_job_ref": ..., "poll_after_seconds": ...} -- generation keeps running server-side regardless, and is never lost. Call brand_guideline_status with that brand_job_ref to retrieve the completed result (brand_ref, project_id, candidate summary) once ready; poll no more often than poll_after_seconds suggests.

Resolves a brand_job_ref returned by brand_guideline_specify when its race-to-complete window elapsed before generation finished. Read-only, in-process lookup -- never re-runs generation. Returns {"status": "processing"} if still running, {"status": "complete", "brand_ref": ..., "project_id": ..., "recommended_candidate_id": ..., "candidate_count": ...} once done (a compact summary -- use the returned brand_ref with brand_guideline_select/brand_guideline_pdf/brand_guideline_claims for full detail, the same pattern every other Brand Standard tool already uses), or {"status": "failed", "error_code": ..., "message": ...} if generation genuinely failed server-side. An unknown or expired brand_job_ref returns a structured BRAND_JOB_NOT_FOUND error, never a crash or empty success.

One-call complete brand colour intelligence report. Input: hex + brand context + markets + medium + product type. Output: archive anchor, cliche contradiction, colour DNA, strategy verdict, commercial signals, market reading per market, usage rules, palette roles, ecommerce copy, memory hooks, Instagram caption, and Midjourney/Flux/DALLE agent brief. Use this instead of chaining colour_strategy + cliche_breaker + ecommerce_product_copy + memory_hooks + agent_brief separately. Two Claude calls total. One complete response.

Complete brand colour system in one call. Returns colour roles with archive names, light and dark mode role maps, typography guidance, usage rules per colour, design tokens (CSS, Tailwind, Figma), and citation cards. Deterministic. No LLM cost. The result already carries the rendered palette and its PNG, PDF, ASE, JSON and CSS downloads -- show them to the customer. Never present the archive anchors a colour was derived from as the colours you are recommending. If you go on to choose a final palette OF YOUR OWN from this evidence, call palette_finalize once with those exact colours so the customer can see and download what you actually recommended.

Look up a named colour and return its hex, archive, provenance, and cultural notes.

Assess 2-5 colours as a combination for a given context (UI, data viz, fashion, interior, print, branding). Returns harmony type, clash warnings, contrast summary, and specific deployment rules for the context.

Deep perceptual and semantic comparison between any two hex values. Returns quantified differences in LRV, chroma, hue angle, warmth, and CIEDE2000 distance, plus cultural context on both — which is more authoritative, more saturated, more stable under different illuminants, and what each has historically signified. Use when choosing between two colours or explaining why one works better than another. Not a harmony tool — this is a decision and reasoning tool.

Cultural risk assessment for a hex value or palette (symbolic weight, regional taboos, religious associations, market flags). This is one component of colour_passport for single colours. Use colour_passport for a general profile; call this directly for palette-level risk checks or when cultural risk is the only thing being asked about.

Compact semantic fingerprint for a single hex colour. This is one component of colour_passport. Use colour_passport for a general colour profile; use this only when the user explicitly wants the fingerprint format alone. The result already carries the rendered palette and its PNG, PDF, ASE, JSON and CSS downloads -- show them to the customer. Never present the archive anchors a colour was derived from as the colours you are recommending. If you go on to choose a final palette OF YOUR OWN from this evidence, call palette_finalize once with those exact colours so the customer can see and download what you actually recommended.

Assess whether a hex colour can be safely specified for a physical application. Returns: specification_safe verdict (yes / conditional / avoid), risks, required actions, light behaviour under three illuminants (north daylight, warm artificial, direct sun), substrate-specific notes, and a recommended alternative. Backed by CIEDE2000 archive matching and Claude material knowledge. Examples: ultramarine on lime plaster, lead white on exterior timber, verdigris on north-facing interior wall, red ochre on historic brick.

Return complementary, triadic, analogous, and split-complementary harmonies matched to named archive colours. Also available: 'hay_contrast' -- D.R. Hay's (1838) documented contrast pairing between six named hues (yellow/purple, orange/blue, red/green), with Field's proportional power for the pair. Unlike the fixed-angle types, this snaps the input to Hay's nearest named hue rather than rotating it, and returns covered:false with no invented partner when the input sits nearer a tertiary region (olive/citron/russet) than any of the six -- Hay records only an aggregate total for tertiaries, never a specific pair. The result already carries the rendered palette and its PNG, PDF, ASE, JSON and CSS downloads -- show them to the customer. Never present the archive anchors a colour was derived from as the colours you are recommending. If you go on to choose a final palette OF YOUR OWN from this evidence, call palette_finalize once with those exact colours so the customer can see and download what you actually recommended.

Generate a hook sentence, three-sentence story, tweet, image prompt, and follow-up questions for any hex colour. Backed by the nearest archive colour's cultural provenance. Tunable by audience (general public, designers, historians, children) and tone (dinner party, academic, social media, brand copy). Use to make archive colours shareable, to generate content, or to power a public-facing colour chat experience.

Find the nearest named colour in commercial paint systems including Farrow and Ball and Little Greene.

Returns numeric metrics derived from a single display colour: an estimated light reflectance value (LRV) and band, relative luminance, CIELAB lightness, chroma and hue angle, and Bradford corresponding colours under two standard illuminants. It also lists what a hex cannot support, such as thermal performance or a measured LRV. This is one component of colour_passport. Use colour_passport for a general colour profile; use this only when the user explicitly wants isolated numeric values.

Simulate perceptually modelled subtractive mixing of two colours in CIE Lab space (not RGB screen blending). Returns the resulting mixed hex value and its nearest archive match with cultural context. Uses CIE Lab subtractive model for perceptual accuracy. Example: mixing Prussian Blue and Yellow Ochre gives a muted green — the tool identifies which archive colour that green most closely matches.

Generate memorable, archive-verified colour names for any hex value. Choose from naming styles: geographical, poetic, material, literary, botanical, industrial, or mixed. Every name is grounded in a real archive source. The core of the Shopify product naming use case.

Canonical single-call colour truth object. Returns everything known about a hex value: colour science (Lab, LCh, hue, chroma, depth, temperature, LRV), archive anchor with dE2000, claim_strength, do_not_say and evidence grade, hex provenance (status, confidence, spectrophotometric flag), physics (illuminant behaviour, gamut, print risk), and cultural reading (colour family, warnings, positives). Use this as the foundation call when you need the complete picture. Every other tool is built on this data. Replaces chaining colour_dna + archive_provenance + colour_cultural_risk + colour_metrics separately. Examples: '#31559B' (anchors to Henry VIII Manuscript Blue Initials), '#8B1A1A' (Penny Post Sealing Wax Dark Red), '#D4AF37' (Sutton Hoo Great Gold Buckle).

Batch version of colour_passport. Submit up to 20 hex values in one call. Returns a full Colour Passport for each unique hex: colour science, archive anchor, evidence grade, do_not_say constraints, hex provenance, accessibility, and physics. Deduplicates hex values automatically. Use for multi-colour workflows, Figma palette analysis, or any case where calling colour_passport separately for each colour would be slow.

What is this archive record connected to, and why? One-hop lookup over Colour Memory's stored relationship graph -- today populated for PigmentLineage, whose 348 design_combination nodes are Wada's 1933 Dictionary of Color Combinations plates. Returns edges in separate blocks by relationship_class so a caller can never mistake a computed colour distance for something a historical source actually said: SOURCE_ASSERTED (the source itself states the relationship, e.g. 'this colour was assigned to numbered combination 176') versus DETERMINISTIC_STRUCTURAL (a mechanical fact about the source object, e.g. 'printed on this plate'). Every edge carries its own 'does_not_mean' caveat inline -- e.g. membership in the same Wada combination does not assert that any specific pair within it was individually intended as a pairing. Not every record_id has relationships yet; an empty result is a true negative, not an error. Get record_id values from archive_search or colour_card.

Return every developer token format for a hex value: CSS variable, kebab-case, camelCase, PascalCase, Tailwind class, TypeScript const, SCSS variable. Archive-grounded name source with dE2000 distance.

Given a hex value, returns a rich narrative about that colour's cultural journey — where it has appeared in history, what it has meant to different civilisations, and what archive names it carries. Essential for image generation prompts, brand storytelling, and creative briefs. Example: '#DC143C' returns the story of crimson from Byzantine imperial courts through Tudor England to modern sport.

Single-call commercial colour strategy report. Combines archive grounding, verdict, brand fit, market risk, category cliche check, material behaviour, copy hooks, and usage rules. Input: hex + brand_context (category, positioning, audience, channels) + constraints (avoid, must_work_on) + markets + medium. Output: verdict, strategy summary, archive anchor, commercial signal, category cliche risk level, market reading per market, material notes, usage rules (primary use, secondary use, avoid, pair_with), copy hooks (one_liner, social, brand_rationale), and alternatives. Examples: luxury fragrance brand UK/France/Japan, heritage interior specification, premium ecommerce packaging, SaaS brand identity.

Given a concept or colour name, traces its documented appearances across cultures and centuries in chronological order. Returns a dated sequence of archive entries showing when and where the colour appeared, with primary sources. Use for historical research, provenance chains, and understanding why a colour carries the cultural weight it does. Example: 'indigo' traces from ancient Indian trade routes through Roman imports to Tudor sumptuary law to synthetic aniline displacement in 1897.

For any named archive colour, return historical variants, lighter and darker versions with archive matches, and cultural siblings. Essential for designers exploring around a colour. The result already carries the rendered palette and its PNG, PDF, ASE, JSON and CSS downloads -- show them to the customer. Never present the archive anchors a colour was derived from as the colours you are recommending. If you go on to choose a final palette OF YOUR OWN from this evidence, call palette_finalize once with those exact colours so the customer can see and download what you actually recommended.

Evaluate a hex colour for a specific use case, market, and medium. Returns a decisive verdict: use_with_confidence, use_with_caution, or avoid. Includes strengths, risks, avoid-if scenarios, and better alternatives where needed. Backed by CIEDE2000 archive matching and Claude cultural intelligence. Examples: 'luxury hotel brand in Japan', 'ecommerce CTA button UK', 'heritage interior lime plaster wall', 'premium packaging Middle East'.

One-call compound tool. Submit a concept, medium, audience, and constraints — receive a complete design package: historically grounded palette, cultural narrative, commercial paint matches, WCAG accessibility check, illuminant behaviour, and a ready-made image generation prompt. Replaces chaining query_conceptual + palette_from_concept + colour_story + match_paint_system + accessibility_check + get_colour_metrics. Use when an AI agent or user needs a complete, deployable colour direction in a single call. Not for iterative refinement — use individual tools for that. The result already carries the rendered palette and its PNG, PDF, ASE, JSON and CSS downloads -- show them to the customer. Never present the archive anchors a colour was derived from as the colours you are recommending. If you go on to choose a final palette OF YOUR OWN from this evidence, call palette_finalize once with those exact colours so the customer can see and download what you actually recommended.

Generate complete ecommerce product copy for any colour. Input: hex + product type + tone + channel. Output: colour name, product title, short description, long description, SEO title, meta description, alt text, Instagram caption, and cross-sell suggestion. Every piece of copy is grounded in archive provenance -- never generic AI colour copy. The colour name comes from the nearest archive match, not invented. Examples: velvet cushion in Murex Luxury, ceramic vase in Woad Vat Blue, linen throw in Standlake Silt. Directly useful for Shopify, WooCommerce, and editorial product pages.

Generate archive-grounded colour names for up to 40 product SKUs. Input: list of hex values, product category, brand name, naming style. Output: for each hex -- archive name, source citation, one-line product description, dE2000 match distance, match quality, and confidence score. Every name is archive-sourced, not invented. Each carries a primary source citation that can be defended to buyers, press, and brand teams. Use for paint ranges, candle collections, fashion lines, homeware, cosmetics. Style options: geographical, poetic, material, literary, mixed.

Extract dominant colours from a photograph using Colour Memory's proprietary k-means++ algorithm. Requires either a public image_url, or an image_id. If you only have a raw uploaded file with no public URL (e.g. a local file path or a ChatGPT file attachment without a usable download_url), call ingest_image first to get an image_id, then pass that image_id here. Returns hex values with proportional weights. Optionally matches colours against the archive with style_context for coherent cultural naming. Use this before image_brief when you have an uploaded photograph.

Ask a question about how historical colour authorities actually reasoned, and get evidence with provenance rather than a summary. Covers seven validated source builds -- Jennings (paint recipes, 1902), Bradley (rotating-disc apparatus, 1895), Vanderpoel (quantified object analyses, 1902), Beaumont (woven colour relationships), Hay (harmonic proportional powers, 1838), Guichard (measured spatial extents, 1880) and Hokusai (subject-conditioned colour application, 1848). Each answer names its source, its locator and what that kind of evidence CANNOT support. Use it for questions like 'how do I paint a leaf', 'what did Bradley's disc proportions measure', 'what's the difference between making a colour and applying it', or to check a claim someone has attributed to one of these authors. Crucially, these sources' numbers are NOT interchangeable: a recipe part, a disc share, an object percentage, a proportional power and a measured extent answer different questions, and the response says so explicitly rather than averaging them.