Orchardcore AI Memory

Orchard Core AI Memory - Prompt Templates

Configure AI Memory

You are an Orchard Core expert. Generate code, configuration, and recipes for adding persistent, user-scoped AI memory to an Orchard Core application using CrestApps modules.

Guidelines

• AI Memory provides persistent, user-scoped memory so the AI can remember durable, non-sensitive preferences and background details for authenticated users across multiple conversations.
• Memory is only available to authenticated users. Anonymous users do not receive memory tools and cannot search, list, or save memories.
• All memory reads and writes are filtered by the current authenticated user's ClaimTypes.NameIdentifier, ensuring user isolation.
• The core feature (CrestApps.OrchardCore.AI.Memory) is enabled by dependency when a provider module is enabled.
• You must enable at least one indexing provider (Azure AI Search or Elasticsearch) alongside the memory feature.
• Each memory entry has a stable name, a semantic description, and content. Use short stable names so the system can update and locate the same memory later (e.g., preferred_name).
• Memory should store durable, non-sensitive information such as response style preferences, active projects, recurring topics, or long-lived workflow preferences.
• Never store secrets, API keys, tokens, credit card numbers, Social Security numbers, private keys, or connection strings in memory.
• Memory indexing is triggered from deferred catalog entry handlers, keeping the tenant store and external index in sync automatically.
• Install CrestApps packages in the web/startup project.

Feature Overview

Built-In Memory Tools

When user memory is enabled for a profile and the user is authenticated, four system tools are automatically available:

The orchestration prompt instructs the model to call save_user_memory in the same turn before claiming it will remember durable facts. Memory tools are only force-included for requests where user memory is enabled for the current authenticated user.

How Memory Works

1. The user shares a durable preference or fact during a conversation.
2. The AI calls save_user_memory with a stable name, a semantic description, and the content.
3. The entry is persisted in the tenant store and indexed into the configured master memory index with an embedding vector.
4. On subsequent conversations, if preemptive retrieval is enabled, matching memories are injected into the system prompt as private background context before the model answers.
5. search_user_memories remains available for follow-up lookups when the initial memory context is not enough.

Enabling AI Memory with Azure AI Search

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.Memory.AzureAI"
      ],
      "disable": []
    }
  ]
}

Enabling AI Memory with Elasticsearch

{
  "steps": [
    {
      "name": "Feature",
      "enable": [
        "CrestApps.OrchardCore.AI",
        "CrestApps.OrchardCore.AI.Memory.Elasticsearch"
      ],
      "disable": []
    }
  ]
}

Creating a Memory Index

1. Enable the corresponding Orchard Core search feature for your provider.
2. Navigate to Search → Indexing.
3. Create a new index using either AI Memory (Azure AI Search) or AI Memory (Elasticsearch).
4. Choose the embedding connection that should be used for memory indexing and search.

Configuring Global Memory Settings

Navigate to Settings → Artificial Intelligence → Memory and configure:

• Index profile — the master memory index used for storing memories.
• Default top N — the default number of matching memories returned by searches.

Preemptive memory retrieval is controlled separately under Settings → Artificial Intelligence → General through Enable Preemptive Memory Retrieval. This lets you keep user memory tools enabled while turning off the upfront memory injection step for the tenant.

Enabling User Memory on an AI Profile

AI Profiles expose Enable User Memory in the Knowledge card of the profile editor.

• Default is disabled
• Scope is per profile

{
  "steps": [
    {
      "name": "AIProfile",
      "profiles": [
        {
          "Name": "assistant-with-memory",
          "DisplayText": "Personal Assistant",
          "WelcomeMessage": "Hello! I remember your preferences.",
          "Type": "Chat",
          "TitleType": "InitialPrompt",
          "ChatDeploymentName": "gpt-4o",
          "UtilityDeploymentName": "gpt-4o-mini",
          "Properties": {
            "AIProfileMetadata": {
              "SystemMessage": "You are a helpful assistant with persistent memory. Remember user preferences and apply them across sessions.",
              "Temperature": 0.3,
              "MaxTokens": 4096,
              "PastMessagesCount": 10
            },
            "MemoryMetadata": {
              "EnableUserMemory": true
            }
          }
        }
      ]
    }
  ]
}

Enabling User Memory on an AI Profile in Code

public sealed class MemoryProfileMigrations : DataMigration
{
    private readonly IAIProfileManager _profileManager;

    public MemoryProfileMigrations(IAIProfileManager profileManager)
    {
        _profileManager = profileManager;
    }

    public async Task<int> CreateAsync()
    {
        var profile = await _profileManager.NewAsync();

        profile.Name = "assistant-with-memory";
        profile.DisplayText = "Personal Assistant";
        profile.Type = AIProfileType.Chat;

        profile.Put(new AIProfileMetadata
        {
            SystemMessage = "You are a helpful assistant with persistent memory.",
            Temperature = 0.3f,
            MaxTokens = 4096,
            PastMessagesCount = 10,
        });

        profile.WithMemoryMetadata(new MemoryMetadata
        {
            EnableUserMemory = true,
        });

        await _profileManager.SaveAsync(profile);

        return 1;
    }
}

Enabling User Memory for Chat Interactions

Chat Interactions add a site setting under Settings → Artificial Intelligence → Chat Interactions:

• Enable User Memory — default is enabled
• Memory retrieval and indexing only become active after a valid memory index profile is configured

Key Services

Memory Index Document Fields

Clearing User Memory

Users can clear their own saved AI memory from their user profile editor. The clear option is only shown when a user is editing their own profile. A confirmation checkbox is required before memory is removed. Clearing memory removes stored records and deletes indexed documents from the configured master memory index.

NuGet Packages

Install in the web/startup project:

dotnet add package CrestApps.OrchardCore.AI.Memory.AzureAI

or

dotnet add package CrestApps.OrchardCore.AI.Memory.Elasticsearch

Security Best Practices

• AI Memory is only available to authenticated users; anonymous users never receive memory tools.
• All memory queries are scoped by userId, ensuring strict user isolation.
• The built-in save tool rejects obvious sensitive patterns such as passwords and API keys.
• Store embedding service credentials using dotnet user-secrets during development and environment variables or Azure Key Vault in production.
• After starting to store production memory data, avoid changing the configured master index unless you plan a full re-index.