@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"]
        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' }]
});

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

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

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

Class	Purpose
AgentEmbeddingService	Generates and manages embeddings for AI agents, enabling semantic agent discovery
ActionEmbeddingService	Generates and manages embeddings for actions, enabling semantic action matching

Match Result Types

Type	Fields	Description
AgentMatchResult	agent, score, metadata	Agent found via semantic similarity
ActionMatchResult	action, score, metadata	Action found via semantic similarity
NoteMatchResult	note, score, metadata	Agent note found via semantic similarity
ExampleMatchResult	example, score, metadata	Agent example found via semantic similarity

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

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