AI Context Registry

A WordPress service plugin that provides a shared context store for AI-enabled plugins. It stores, normalizes, ranks, and serves context items so consuming plugins can retrieve the smallest useful set of knowledge for any task — without each plugin building its own store.

AI Context Registry is infrastructure, not a product. It does not ship a model provider, chat UI, or prompt builder. It is the knowledge layer that sits beneath all of them.

Why This Exists

Every AI-powered WordPress plugin needs context — product descriptions, support articles, company policies, how-to guides — to generate useful output. Without a shared registry, each plugin reinvents the wheel: scraping content, storing duplicates, guessing what matters, and ignoring what worked before.

AI Context Registry solves this by providing:

• One canonical store for all context items across your site
• Intelligent retrieval that ranks items by relevance, usefulness, and token budget
• Usage tracking that learns from real consumption — items that help get ranked higher, items that don't get ranked lower
• Quality hygiene that flags stale, unused, or duplicate content for human review
• A clean PHP API that any plugin can call without coupling to implementation details

The result: better AI output, less wasted tokens, no duplicated effort, and a context library that improves over time.

Requirements

• WordPress 7.0+
• PHP 8.1+ (8.3+ recommended)
• MySQL 8.0+ or MariaDB 10.6+

Installation

1. Upload the ai-context-registry folder to /wp-content/plugins/
2. Activate through the Plugins screen in WordPress
3. The plugin creates its custom tables and capabilities automatically on activation

No configuration is required. The plugin is ready to accept and serve context items immediately.

How It Works

The Data Model

Each context item stores:

Field	Purpose
title	Human-readable label
content_raw	Full original content
content_summary	A shorter summary representation
content_compact	A minimal representation for tight token budgets
source_type / source_ref	Where this content came from (e.g., post / 42)
freshness_class	evergreen or time_sensitive
sensitivity	public, internal, or restricted
manual_priority	Admin-assigned importance (1-10)
usefulness_score	Automatically adjusted based on real usage feedback

Items are tagged with facets — normalized task_type, domain, and audience values — stored in a dedicated lookup table for fast, portable filtering without relying on JSON column operators.

The Retrieval Pipeline

When a consuming plugin calls aicx_find_context(), the registry runs a three-phase pipeline:

1. Hard Filters — Exclude archived items, known duplicates, and items the current user lacks permission to see. Apply facet filters (task type, domains, audiences). Cap candidates at 200.

2. Deterministic Scoring — Rank surviving candidates using a weighted formula:

Signal	Weight
Task type match	25
Domain overlap	18
Audience overlap	8
Manual priority	3
Usefulness score	20
Recent usage	5
Keyword relevance	4
Staleness penalty	-20

3. Token Budget Fitting — Walk the ranked list and pack items into the requested token budget. In adaptive mode, items start at their compact representation and the top-scoring items are upgraded to summaries if budget remains.

Usage Tracking

Every time a consuming plugin reports what happened after using context items, the registry updates the item's usefulness score:

Signal	Score Change
Item was selected	+0.01
Item was expanded	+0.02
Item was used in a prompt	+0.03
AI output was accepted	+0.06
Human thumbs-up	+0.08
Heavy editing required	-0.04
Human thumbs-down	-0.10
Dismissed as irrelevant	-0.12

Scores are clamped to [0.05, 0.95] so no item is ever permanently buried or permanently dominant. Over time, the registry learns which context actually helps and surfaces it first.

Raw user queries are never stored. Only a SHA-256 fingerprint is kept for analytics deduplication.

Review Queue

Automated hygiene scans flag items that need human attention:

• Stale — time-sensitive items past their review date
• Unused — items that haven't been retrieved in a long time
• Duplicate — items with identical content hashes

The review engine creates review records only. It never deletes or silently mutates content.

Public PHP API

All functions are available after plugins_loaded and are safe to call conditionally:

if ( function_exists( 'aicx_upsert_context' ) ) {
    aicx_upsert_context( $payload );
}

Register a Context Item

$item_id = aicx_register_context( [
    'title'           => 'Return Policy',
    'content_raw'     => 'Full return policy text...',
    'content_summary' => 'We accept returns within 30 days...',
    'content_compact' => '30-day returns, receipt required.',
    'freshness_class' => 'evergreen',
    'sensitivity'     => 'public',
    'manual_priority' => 7,
    'domains'         => [ 'support', 'ecommerce' ],
    'audiences'       => [ 'customer' ],
] );

Upsert by Source Identity (Preferred for Adapters)

$item_id = aicx_upsert_context( [
    'source_type'     => 'post',
    'source_ref'      => '42',
    'title'           => get_the_title( 42 ),
    'content_raw'     => get_post_field( 'post_content', 42 ),
    'content_summary' => 'A shorter version...',
    'domains'         => [ 'blog' ],
] );

Calling this again with the same source_type and source_ref updates the existing item instead of creating a duplicate. A source_checksum field lets adapters detect meaningful content changes without storing diffs.

Update an Existing Item

aicx_update_context( $item_id, [
    'content_raw'     => 'Updated policy text...',
    'manual_priority' => 9,
] );

Retrieve Ranked Context

$result = aicx_find_context( [
    'task_type'     => 'customer_reply',
    'domains'       => [ 'support' ],
    'query'         => 'how do I return a product',
    'token_budget'  => 2000,
    'max_items'     => 10,
    'content_depth' => 'adaptive',
] );

foreach ( $result['items'] as $item ) {
    // $item['title'], $item['content'], $item['mode'], $item['retrieval_score']
}

// $result['remaining_budget'] — tokens left after packing

Content depth options:

Value	Behavior
compact	Always use the compact representation
summary	Always use the summary
raw	Always use full raw content
adaptive	Start compact, upgrade top items to summary if budget allows

Record Usage Feedback

// Single event
aicx_record_usage( [
    'item_id'           => 42,
    'consumer_plugin'   => 'my-chat-plugin',
    'consumer_feature'  => 'reply-composer',
    'was_used_in_prompt' => true,
    'output_accepted'   => true,
    'human_feedback'    => 'up',
] );

// Batch events
aicx_record_usage( [
    'events' => [
        [
            'item_id'         => 42,
            'consumer_plugin' => 'my-chat-plugin',
            'was_selected'    => true,
        ],
        [
            'item_id'         => 43,
            'consumer_plugin' => 'my-chat-plugin',
            'human_feedback'  => 'dismissed',
        ],
    ],
] );

Fetch the Review Queue

$reviews = aicx_get_review_queue( [
    'review_type' => 'stale',
    'status'      => 'open',
] );

Action Hooks

Hook	Fires When	Parameters
aicx_context_registered	After a new item is created	$item_id, $args
aicx_context_upserted	After an item is created or updated by source	$item_id, $args
aicx_context_updated	After an existing item is updated	$item_id, $args
aicx_usage_recorded	After usage events are logged	$args

How Plugins Can Take Advantage

AI Chat Plugins

Before sending a prompt to any AI provider, retrieve relevant context and inject it:

$context = aicx_find_context( [
    'task_type'    => 'chat_response',
    'query'        => $user_message,
    'token_budget' => 3000,
] );

$system_prompt = "Use the following knowledge to answer:\n\n";
foreach ( $context['items'] as $item ) {
    $system_prompt .= "## {$item['title']}\n{$item['content']}\n\n";
}

After the exchange, report what happened:

aicx_record_usage( [
    'item_id'            => $item['id'],
    'consumer_plugin'    => 'my-chat-plugin',
    'was_used_in_prompt'  => true,
    'output_accepted'    => $user_accepted,
] );

Content Generation Plugins

Retrieve domain-specific context to ground AI-generated content in real business knowledge:

$context = aicx_find_context( [
    'domains'       => [ 'product-catalog' ],
    'audiences'     => [ 'shopper' ],
    'content_depth' => 'summary',
    'token_budget'  => 1500,
] );

Source Adapters

Build an adapter that syncs WordPress content into the registry automatically:

add_action( 'save_post', function( $post_id ) {
    $post = get_post( $post_id );

    if ( 'publish' !== $post->post_status ) {
        return;
    }

    aicx_upsert_context( [
        'source_type'   => 'post',
        'source_ref'    => (string) $post_id,
        'title'         => $post->post_title,
        'content_raw'   => $post->post_content,
        'domains'       => wp_get_post_terms( $post_id, 'category', [ 'fields' => 'slugs' ] ),
    ] );
} );

WooCommerce Integration

Sync product data so AI assistants can answer product questions accurately:

aicx_upsert_context( [
    'source_type'     => 'product',
    'source_ref'      => (string) $product->get_id(),
    'title'           => $product->get_name(),
    'content_raw'     => $product->get_description(),
    'content_summary' => $product->get_short_description(),
    'content_compact' => sprintf( '%s - %s', $product->get_name(), $product->get_price_html() ),
    'domains'         => [ 'ecommerce', 'product-catalog' ],
    'audiences'       => [ 'shopper', 'support-agent' ],
    'sensitivity'     => 'public',
] );

Security

Capabilities

The plugin registers five capabilities, seeded on the administrator role at activation:

Capability	Purpose
manage_ai_context	Full administrative access
edit_ai_context	Create and edit context items
review_ai_context	Manage the review queue
read_ai_context_internal	Access internal-sensitivity items
read_ai_context_restricted	Access restricted-sensitivity items

Sensitivity Levels

• public — Safe for the broadest retrieval contexts
• internal — Requires authenticated access; filtered out for users without read_ai_context_internal
• restricted — Requires explicit read_ai_context_restricted capability

v1 does not expose anonymous retrieval routes, even for public items.

Performance

Operation	Target
Retrieval (1,000 items)	< 200ms
Usage logging (per event)	< 10ms overhead
Hygiene scans (5,000 items)	< 60s (chunked)

Uninstalling

When the plugin is deleted through the WordPress admin:

• All four custom tables are dropped
• The aicx_db_version option is removed
• All five capabilities are removed from all roles
• All scheduled cron events are cleared

Deactivation alone does not delete data — it only unschedules cron jobs.

Development

Requirements

• PHP 8.1+
• Composer (for dev dependencies)

Running Tests

composer install
./vendor/bin/phpunit

Roadmap

Milestone 1 (Current)

Core plugin infrastructure: schema, CRUD, retrieval pipeline, usage tracking, REST API, admin UI, review engine, and release hardening.

Milestone 2

Source adapters and content backfills, review queue UI, context profiles, sources dashboard, and CLI maintenance tooling.

Milestone 3

WordPress Abilities API integration, AI Client SDK-powered summaries and compression, and MCP adapter validation.

License

GPL-2.0-or-later

Author

Malcolm Peralty — peralty.com