@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
Metadata Cache"]
    style AIB fill:#2d6a9f,stroke:#1a4971,color:#fff

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

    subgraph "Server Capabilities"
        LLM["LLM Execution
ChatCompletion"]
        style LLM fill:#7c5295,stroke:#563a6b,color:#fff

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

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

        ATT["Attachment Service
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
Copy

Installation

npm install @memberjunction/aiengine
Copy

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;
Copy

LLM Execution

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

Classification and summarization run as AI Prompts through AIPromptRunner (@memberjunction/ai-prompts).

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
);
Copy

Local Embeddings

Every platform path that embeds locally (entity save hooks, agent memory, QueryGen, the semantic search fallback) uses one model, DefaultLocalEmbeddingModel: the active local embedding model named by the MJ_DEFAULT_LOCAL_EMBEDDING_MODEL environment variable, or the highest-PowerRank active one when it is unset. Every process that embeds (MJAPI, the mj CLI, MCP/A2A servers, workers) reads it, so they all judge stored vectors against the same model. A name that matches no active local model turns local embedding off with an error. The model is resolved once per process, so changing it takes a restart.

const model = AIEngine.Instance.DefaultLocalEmbeddingModel;

// Search text is a query; stored text is a document (the default).
const query = await AIEngine.Instance.EmbedTextLocal('which charts does the user like?', { inputType: 'query' });
const doc = await AIEngine.Instance.EmbedText(model!, 'User prefers bar charts.', undefined, { inputType: 'document', dimensions: 256 });
Copy

EmbedText prepends the model's catalog prefix for the input type (ModelConfiguration.Embedding QueryPrefix / DocumentPrefix, resolved through GetEffectiveModelConfiguration), passes the model-vendor row's MaxInputTokens as the input cap, and caches per model, input type, dimensions and prefixed text. A failed embed returns null. PrepareEmbeddingInput exposes the same shaping to AIEmbeddingRunner.

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', it has a stored vector (EmbeddingVectorBinary or EmbeddingVector), AND that vector came from DefaultLocalEmbeddingModel (EmbeddingModelID). Vectors from another model can't share the index: the load leaves them out with one warning naming the count, and they rejoin when re-embedded (on their next save, or with the "Re-embed Local Vectors" action).
• Loading. Notes and examples are hydrated with ReadStoredVector(EmbeddingVectorBinary, EmbeddingVector) from @memberjunction/ai-vectors-memory — the binary float32 column when valid, the JSON column as fallback. See the Binary Fields Guide.
• 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);
Copy

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);
Copy

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