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 four 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 – or the user – 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, or a context the user attached to an AI Chat conversation.

Every mechanism above is set up by an administrator or an integrator, and the attached contexts stay invisible to users. The config.ai.chat.context.contextLibrary option puts the choice in the hands of the user instead: it adds the library to the “Add context” menu of AI Chat, where the user attaches a context to the conversation like any other resource.

The option is disabled by default:

ClassicEditor
    .create( {
        /* ... */
        // ... Other configuration options ...
        ai: {
            chat: {
                context: {
                    contextLibrary: {
                        enabled: true
                    }
                }
            }
        }
    } )
    .then( /* ... */ )
    .catch( /* ... */ );

When it is enabled, the menu shows a “Context library” item that lists the contexts available to the user by name, falling back to the context ID when a context has no name. Attaching one attaches the whole context – every prompt and every file it holds. Once a message is sent, the reference stays with the conversation and is sent with every following message. Its chip appears only on the message it was sent with: from then on the reference is attached silently, with no way for the user to see or remove it.

Two rules decide what the picker offers:

• Access follows the token. The list contains only the contexts the user token grants access to, so different users can be offered different contexts. Read more about the ai:contexts permissions.
• Default contexts are excluded. A context referenced by config.ai.defaultContext never appears in the picker, even when the entry references a single item or targets only other features. Default contexts are owned by the configuration – to make a context user-selectable, leave it out of config.ai.defaultContext.

The list is fetched once, when the AI plugins initialize, and is not refreshed during the session. Changes in the library reach the picker after the page is reloaded.

The “Add context” menu offers more than the library – see attaching resources to conversations in the AI Chat guide for the document, URL, file, and custom sources.

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.

Deleting a context from the library is immediate, but references to it can outlive it – in the editor configuration, in the picker, and in the AI Chat conversations that attached it. Since references resolve per call, every new request that still carries a reference to a deleted context fails.

We recommend removing a context in the following order:

1. Stop referencing the context. Remove its entries from config.ai.defaultContext, from the custom quick actions and extra review commands that use it, and from programmatic calls. If the context is applied automatically, disable its autoApply setting on the AI service.
2. Revoke access. Stop granting the context in the ai:contexts permissions of the user tokens. Without access, the context disappears from the AI Chat picker and the service rejects any request that still references it. Allow for a transition window: tokens issued earlier keep their access until they are refreshed, and an editor that is already open keeps showing the context in the picker until the page is reloaded.
3. Delete the context. Remove it from the AI service. See the API reference in the Cloud Services documentation for the management call.

Deletion does not touch the stored conversation history, so conversations that used the context remain readable. Writing is a different matter: a conversation sends its attached context references with every message and they cannot be detached, so the next prompt in such a conversation is rejected. The user continues in a new conversation.

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.