Context library

The Context Library stores reusable knowledge on the CKEditor AI service, so the AI features work with your organization’s own rules and reference material instead of generic instructions. A context is a named container that can hold reusable prompts, reference files, or both:

• Prompts – reusable instruction text, such as a tone-of-voice rule, an editorial standard, or a compliance requirement.
• Files – reference documents, such as a brand guidelines PDF, a product glossary, or a policy handbook.

1. An administrator creates a context on the AI service, adds prompts to it, and uploads files – directly or from a URL. See Creating a context in the Cloud Services documentation for the how-to.
2. An AI request references the context – either the editor sends the reference, or the service applies the context automatically.
3. The service expands the reference before the model sees the request: the context’s prompts are added to the instructions and its files are attached as reference material.

Resolution happens per call, so a request always uses the current content of the context. Updating a prompt or replacing a file in the library changes the behavior of every request that references it, with no deployment.

A context attached this way stays invisible to the user.

A context can reach a request at three levels of scope. Pick the one that matches how universal the knowledge is:

Some knowledge should shape every AI response in your environment, no matter which feature produced it and who asked. The typical case is a house style: a context holding the style guide file plus a prompt describing when and how the guide applies. With it in place, every conversation, review, action, and translation follows the style guide – and neither the users nor the editor manage anything.

This is what the autoApply setting of a context does. An administrator enables it on the AI service and the service injects the context into every matching call. No editor configuration is involved, and the editor sends nothing. See Applying a context automatically in the Cloud Services documentation to set it up.

Use the mechanisms below when the environment-wide scope is too broad and the editor should decide which contexts apply.

The config.ai.defaultContext option holds a list of context references that CKEditor AI attaches automatically to the requests made by its features. It is set per editor instance, so the attached knowledge can follow the application state – the type of the edited document, its workflow status, or the current user:

// Every document gets the house style guide.
const defaultContext = [ { id: 'style-guide' } ];

// Clinical reports additionally get the medical terminology context.
if ( documentType === 'clinical-report' ) {
    defaultContext.push( { id: 'medical-terminology' } );
}

ClassicEditor
    .create( {
        /* ... */
        ai: {
            defaultContext
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

An entry without a features property is attached to every AI feature: AI Chat, AI Quick Actions, AI Review, and AI Translate.

A context reference points either at a whole context or at a single item inside it:

The promptId and fileId properties are mutually exclusive.

All three shapes go into the same config.ai.defaultContext list:

ClassicEditor
    .create( {
        /* ... */
        // ... Other configuration options ...
        ai: {
            defaultContext: [
                // The whole context: every prompt and every file it holds.
                { id: 'style-guide' },

                // A single prompt from another context.
                { id: 'brand-voice', promptId: 'V1StGXR8_Z5jdHi6B-myT' },

                // A single file from another context.
                { id: 'legal-rules', fileId: 'k7Qk2Anpd9WjU7scF3xVv' }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

The id of a context is chosen by whoever creates it, so it can be a readable name such as style-guide. The promptId and fileId values are generated by the service when a prompt or a file is added to a context. Read them from the context itself before referencing a single item.

Add a features property to an entry to narrow down where it applies. Each key targets one AI feature. A key set to true attaches the entry to every invocation of that feature. A key set to a RegExp attaches it only when one of the invocation IDs matches. A key that is omitted, or set to false, excludes the feature:

ClassicEditor
    .create( {
        /* ... */
        // ... Other configuration options ...
        ai: {
            defaultContext: [
                // Attached to every AI feature.
                { id: 'style-guide' },

                // Attached to every review command, and only to the translate quick actions.
                {
                    id: 'glossary',
                    features: {
                        review: true,
                        quickActions: /^translate/
                    }
                }
            ]
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

The table below lists the keys and the IDs a RegExp is matched against:

The quickActions, review, and translate entries are selected separately for each run. The chat entries are selected once, when a conversation is initialized, and then attached to every message of that conversation – so an entry with a RegExp matched by the starting chat shortcut applies to the whole conversation, while a conversation started in any other way receives only the entries set to true. Each feature guide covers its own configuration, with examples, in detail.

References reach a request in a fixed order: first the matching ai.defaultContext entries, in configuration order, then any reference the invocation itself carries, such as the context of a custom quick action or of an extra review command.

A custom quick action or an extra review command can reference a context instead of carrying an inline prompt string, so the instruction and its reference material live in the library. This keeps them maintained in one place – they change without a deployment – and out of the frontend: the curated prompt text is not stored in the editor configuration and does not show up in the network traffic of the request. See custom quick actions and extra review commands for the configuration.

Driving a feature from code does not change how the mechanisms above apply. A method that starts the user interface flow of a feature attaches the matching ai.defaultContext entries, just like the user interface does. A headless run bypasses the user interface, and with it the editor configuration, so it works only with the references the call carries in its contexts option. The programmatic usage guide documents that option for every flow that accepts it: chat conversations – where the passed references are merged with the configured ones rather than replacing them – quick actions, reviews, translations, and document processing.

The Context Library is configured through config.ai.defaultContext and can be inspected from code – read the contexts available to the current token and build your own user interface around them.

• Using CKEditor AI programmatically – drive the AI features and gateways from code.
• Context Library in Cloud Services – creating and managing contexts, automatic application, and the REST API details.
• Permissions – the ai:contexts scopes that control access to contexts.