@memberjunction/aiengine

Server-side AI Engine for MemberJunction. Wraps AIEngineBase and adds server-only capabilities including LLM execution, embedding generation, vector-based semantic search for agents and actions, and conversation attachment management. This package is the main orchestration layer for AI operations on the server.

Architecture

graph TD
    AIB["AIEngineBase<br/>Metadata Cache"]
    style AIB fill:#2d6a9f,stroke:#1a4971,color:#fff

    AIE["AIEngine<br/>Server-Side Singleton"]
    style AIE fill:#2d8659,stroke:#1a5c3a,color:#fff

    subgraph "Server Capabilities"
        LLM["LLM Execution<br/>ChatCompletion, Classify, Summarize"]
        style LLM fill:#7c5295,stroke:#563a6b,color:#fff

        EMB["Embedding Services<br/>Agent & Action Embeddings"]
        style EMB fill:#7c5295,stroke:#563a6b,color:#fff

        VS["Vector Search<br/>Semantic Agent/Action/Note Matching"]
        style VS fill:#b8762f,stroke:#8a5722,color:#fff

        ATT["Attachment Service<br/>Conversation Media Management"]
        style ATT fill:#b8762f,stroke:#8a5722,color:#fff
    end

    AIB --> AIE
    AIE --> LLM
    AIE --> EMB
    AIE --> VS
    AIE --> ATT

    subgraph "Result Types"
        AMR["AgentMatchResult"]
        style AMR fill:#7c5295,stroke:#563a6b,color:#fff

        ACMR["ActionMatchResult"]
        style ACMR fill:#7c5295,stroke:#563a6b,color:#fff

        NMR["NoteMatchResult"]
        style NMR fill:#7c5295,stroke:#563a6b,color:#fff

        EMR["ExampleMatchResult"]
        style EMR fill:#7c5295,stroke:#563a6b,color:#fff
    end

    VS --> AMR
    VS --> ACMR
    VS --> NMR
    VS --> EMR

Installation

npm install @memberjunction/aiengine

Note: This package is server-side only. For metadata access on the client, use @memberjunction/ai-engine-base directly.

Key Exports

AIEngine (Singleton)

The main server-side engine. Uses composition (not inheritance) to delegate metadata operations to AIEngineBase.Instance while adding server-specific features.

import { AIEngine } from '@memberjunction/aiengine';

// Initialize
await AIEngine.Instance.Config(false, contextUser);

// All AIEngineBase properties are delegated:
const models = AIEngine.Instance.Models;
const agents = AIEngine.Instance.Agents;

LLM Execution

// Direct chat completion
const result = await AIEngine.Instance.ChatCompletion({
    model: 'gpt-4',
    messages: [{ role: 'user', content: 'Explain quantum computing' }]
});

// Summarize text
const summary = await AIEngine.Instance.SummarizeText({
    model: 'gpt-4',
    text: longDocument
});

// Classify text
const classification = await AIEngine.Instance.ClassifyText({
    model: 'gpt-4',
    text: inputText,
    categories: ['positive', 'negative', 'neutral']
});

Semantic Search

Find agents, actions, notes, and examples using vector similarity:

// Find agents matching a user query
const agentMatches: AgentMatchResult[] = await AIEngine.Instance.FindSimilarAgents(
    'Help me analyze sales data',
    5,           // topK
    contextUser
);

// Find relevant actions
const actionMatches: ActionMatchResult[] = await AIEngine.Instance.FindSimilarActions(
    'Send an email notification',
    5,
    contextUser
);

// Find relevant notes for an agent
const noteMatches: NoteMatchResult[] = await AIEngine.Instance.FindSimilarNotes(
    agentId,
    'Customer wants a refund',
    10,
    contextUser
);

// Find relevant examples for an agent
const exampleMatches: ExampleMatchResult[] = await AIEngine.Instance.FindSimilarExamples(
    agentId,
    'How do I reset my password?',
    5,
    contextUser
);

Embedding Services

Match Result Types

Vector Store Invariant Preservation

AIEngine exposes FindSimilarAgentNotes over the in-process _noteVectorService. Since v5.30.x the vector store is kept strictly in sync with the persisted note state:

• Invariant. _noteVectorService contains an entry for an AIAgentNote if and only if its persisted Status='Active' AND its EmbeddingVector is non-null.
• Write-side enforcement. MJAIAgentNoteEntityServer.Save() and .Delete() (in @memberjunction/core-entities-server) update the in-process vector store inline with each note write — adding entries when a note becomes Active with a non-null embedding, removing them when Status flips away from Active or when the note is deleted.
• What this fixes. Before this change, revoking a note (e.g. during MemoryManagerAgent consolidation, or when a contradiction was resolved) would leave a stale entry in _noteVectorService until MJAPI was restarted. Subsequent calls to FindSimilarAgentNotes would surface revoked notes back to retrieval. The invariant now holds without a restart.

The relevant code paths live in src/AIEngine.ts and packages/MJCoreEntitiesServer/src/custom/MJAIAgentNoteEntityServer.server.ts.

ConversationAttachmentService

Manages media attachments (images, audio, video, files) in agent conversations:

import { ConversationAttachmentService } from '@memberjunction/aiengine';

const service = new ConversationAttachmentService();

// Process uploaded attachments for a conversation
await service.ProcessAttachments(conversationId, attachments, contextUser);

Usage Pattern

import { AIEngine } from '@memberjunction/aiengine';

// 1. Initialize at server startup
await AIEngine.Instance.Config(false, contextUser);

// 2. Access metadata (delegated to AIEngineBase)
const model = AIEngine.Instance.Models.find(m => m.Name === 'GPT-4');
const agent = AIEngine.Instance.GetAgentByName('Sales Assistant');

// 3. Use server-side capabilities
const similar = await AIEngine.Instance.FindSimilarAgents(userQuery, 5, contextUser);

Dependencies

• @memberjunction/ai-engine-base -- Base metadata cache (AIEngineBase)
• @memberjunction/ai -- Core AI abstractions (BaseLLM, BaseEmbeddings)
• @memberjunction/ai-core-plus -- Extended entity classes
• @memberjunction/ai-vectors-memory -- In-memory vector service for semantic search
• @memberjunction/core -- MJ framework core
• @memberjunction/core-entities -- Generated entity classes
• @memberjunction/actions-base -- Action framework integration
• @memberjunction/storage -- File storage integration for attachments