@memberjunction/ai-core-plus

Shared type definitions and extended entity classes for the MemberJunction AI Framework. This package bridges the gap between the standalone @memberjunction/ai core and the full MJ entity system, providing types that are usable on both server and client. It defines prompt execution result types, agent execution types, system placeholder management, conversation utilities, and extended entity classes with additional computed properties.

Architecture

graph TD
    AI["@memberjunction/ai"]
    style AI fill:#2d6a9f,stroke:#1a4971,color:#fff

    CORE["@memberjunction/core"]
    style CORE fill:#2d6a9f,stroke:#1a4971,color:#fff

    CE["@memberjunction/core-entities"]
    style CE fill:#2d6a9f,stroke:#1a4971,color:#fff

    ACP["@memberjunction/ai-core-plus"]
    style ACP fill:#2d8659,stroke:#1a5c3a,color:#fff

    subgraph "ai-core-plus Modules"
        PT["Prompt Types
AIPromptParams, AIPromptRunResult"]
        style PT fill:#7c5295,stroke:#563a6b,color:#fff

        AT["Agent Types
ExecuteAgentParams, ExecuteAgentResult"]
        style AT fill:#7c5295,stroke:#563a6b,color:#fff

        SP["System Placeholders
Date/Time, User Context"]
        style SP fill:#b8762f,stroke:#8a5722,color:#fff

        EXT["Extended Entities
AIPrompt, AIModel, AIAgent"]
        style EXT fill:#2d6a9f,stroke:#1a4971,color:#fff

        CU["ConversationUtility"]
        style CU fill:#b8762f,stroke:#8a5722,color:#fff

        RF["Response Forms
& UI Commands"]
        style RF fill:#7c5295,stroke:#563a6b,color:#fff
    end

    AI --> ACP
    CORE --> ACP
    CE --> ACP
    ACP --> PT
    ACP --> AT
    ACP --> SP
    ACP --> EXT
    ACP --> CU
    ACP --> RF
Copy

Installation

npm install @memberjunction/ai-core-plus
Copy

Key Exports

Prompt Types (prompt.types.ts)

AIPromptParams.PreRenderedChildTemplates (placeholder name → rendered child text) lets a caller that has already rendered the child prompts — via AIPromptRunner.RenderChildPromptTemplates — hand the text to ExecutePrompt so the children are not rendered twice; the loop agent uses it when relocating a volatile specialization into its trailing runtime-state message.

Agent Types (agent-types.ts)

Consolidation Observability in ExecuteAgentResult

ExecuteAgentResult surfaces the agent run's step list. As of v5.30.x, MemoryManagerAgent runs emit two new step types when its consolidation pipeline executes:

Run-level payload additions include scoreDistribution, entityTriplesExtracted, decayScoreDistribution, protectedPreserved, ephemeralAccelerated, and triggerType ('forced' / 'time' / 'event' / 'count'). These flow through unchanged via ExecuteAgentResult.steps[*].outputData — consumers that already deserialize step output data will pick them up without code changes.

For pipeline mechanics, see @memberjunction/ai-agents.

Realtime Channel Contract v2 (realtime-channel-*.ts, realtime-session-policy.ts, agent-settings.ts, json-schema-subset.ts)

Framework-neutral types and pure functions shared by the browser runtime (@memberjunction/realtime-runtime) and the server (@memberjunction/ai-agents), so both make the same channel decisions from the same inputs.

FormatClientToolsForPrompt was removed: no caller ever adopted it (the async path words its own section; realtime renders compact signatures via FormatAppContextNote), and keeping a second, tempting wording with no caller is a liability.

System Placeholders (prompt.system-placeholders.ts)

The SystemPlaceholderManager automatically injects common values into all prompt templates:

• {{CurrentDate}}, {{CurrentTime}}, {{CurrentDateTime}} -- Current date/time in user's timezone
• {{CurrentTimezone}} -- User's timezone identifier
• {{UserName}}, {{UserEmail}}, {{UserFirstName}}, {{UserLastName}} -- User context
• Custom placeholders can be registered at runtime

Extended Entity Classes

Other Exports

Usage

Prompt Execution Parameters

import { AIPromptParams, ChildPromptParam } from '@memberjunction/ai-core-plus';

const params = new AIPromptParams();
params.prompt = myPromptEntity;
params.data = { customerName: 'Acme Corp', orderCount: 42 };
params.contextUser = currentUser;
params.effortLevel = 75;

// Hierarchical prompt composition
params.childPrompts = [
    new ChildPromptParam(analysisParams, 'analysis'),
    new ChildPromptParam(summaryParams, 'summary')
];

// Model override at runtime
params.override = {
    modelId: 'specific-model-id',
    vendorId: 'specific-vendor-id'
};

// Force the runner to credential-check EVERY candidate model-vendor combination
// instead of short-circuiting at the first usable one. Default false — only enable
// for diagnostics that need a complete per-candidate availability report, since it
// runs a credential lookup for every configured model on the run.
params.forceFullModelEvaluation = true;
Copy

AIPromptParams field reference

Agent Execution Parameters

import { ExecuteAgentParams, UserScope } from '@memberjunction/ai-core-plus';

const params: ExecuteAgentParams = {
    agent: myAgent,
    conversationMessages: [{ role: 'user', content: 'Analyze this data' }],
    contextUser: currentUser,
    userScope: {
        primaryEntityName: 'Organizations',
        primaryRecordId: orgId,
        secondary: { TeamID: teamId }
    },
    onProgress: (step) => console.log(`${step.step}: ${step.message}`)
};
Copy

Runtime Action Changes

import { ExecuteAgentParams, ActionChange } from '@memberjunction/ai-core-plus';

const params: ExecuteAgentParams = {
    agent: myAgent,
    conversationMessages: messages,
    actionChanges: [
        { scope: 'global', mode: 'add', actionIds: ['crm-action-id'] },
        { scope: 'all-subagents', mode: 'remove', actionIds: ['dangerous-action-id'] }
    ]
};
Copy

Message Lifecycle Management

import { ExecuteAgentParams, MessageLifecycleEvent } from '@memberjunction/ai-core-plus';

const params: ExecuteAgentParams = {
    agent: myAgent,
    conversationMessages: messages,
    messageExpirationOverride: {
        expirationTurns: 2,
        expirationMode: 'Compact',
        compactMode: 'First N Chars',
        compactLength: 500
    },
    onMessageLifecycle: (event: MessageLifecycleEvent) => {
        console.log(`[Turn ${event.turn}] ${event.type}: ${event.reason}`);
    }
};
Copy

Post-Run Compaction & Scratchpad Pruning (compactAfterRun)

import { ExecuteAgentParams } from '@memberjunction/ai-core-plus';

const params: ExecuteAgentParams = {
    agent: myAgent,
    conversationMessages: messages,
    contextUser: currentUser,
    compactAfterRun: {
        enabled: true,
        messageCountThreshold: 12,
        extractMemories: true,
        maxScratchpadNotes: 20
    }
};
Copy

Effort Level Control

MemberJunction supports a 1-100 scale for AI model reasoning effort. The resolution precedence is:

1. ExecuteAgentParams.effortLevel (runtime override, highest priority)
2. AIAgent.DefaultPromptEffortLevel (agent default)
3. AIPrompt.EffortLevel (prompt default)
4. Provider default behavior (lowest priority)

Provider mappings:

• OpenAI: 1-33 = low, 34-66 = medium, 67-100 = high
• Anthropic: Thinking mode with 25K-2M token budgets
• Groq: Experimental reasoning_effort parameter
• Gemini: Reasoning mode intensity

Dependencies

• @memberjunction/ai -- Core AI abstractions
• @memberjunction/core -- MJ framework core (Metadata, RunView, UserInfo)
• @memberjunction/core-entities -- Generated entity classes
• @memberjunction/global -- Class factory and global utilities
• @memberjunction/actions-base -- Action framework base types
• @memberjunction/templates-base-types -- Template engine base types
• date-fns / date-fns-tz -- Date/time formatting and timezone support