Orchard Core AI Memory Azure AI Search
Configure Azure AI Search memory indexing
You are an Orchard Core expert. Configure Azure AI Search for persistent user-memory
vector indexing and semantic retrieval. Maintain the strict authenticated-user filter
and use the provider-managed profile mappings.
Guidelines
- Enable the exact feature ID
CrestApps.OrchardCore.AI.Memory.AzureAI.
- Its manifest depends on
CrestApps.OrchardCore.AI.Memory, OrchardCore.Indexing, and OrchardCore.AzureAI; the base AI Memory feature is enabled by dependency.
- Create AI Memory (Azure AI Search) from Search → Indexing, select its embedding deployment, then choose it in Settings → Artificial Intelligence → Memory.
- Memory remains authenticated-user scoped even though all users can occupy a shared external index.
- The backend registers
AzureAISearchMemoryVectorSearchService as a keyed IMemoryVectorSearchService using AzureAISearchConstants.ProviderName.
- Install the package in the web or startup project and store Azure endpoint and credential configuration securely.
- Do not use memory to retain secrets, tokens, private keys, payment data, or other sensitive user data.
Provider registrations
| Registration |
Purpose |
AIMemoryAzureAISearchIndexProfileHandler |
Creates, updates, and normalizes Azure Search memory mappings. |
AIMemoryAzureAISearchDocumentIndexHandler |
Builds Azure index documents from persisted memory records. |
AzureAISearchMemoryVectorSearchService |
Retrieves semantically similar memories for one user. |
AddAzureAISearchIndexingSource |
Adds AI Memory (Azure AI Search) as an index source. |
Enable the backend
{
"steps": [
{
"name": "Feature",
"enable": [
"CrestApps.OrchardCore.AI",
"CrestApps.OrchardCore.AI.Memory.AzureAI",
"OrchardCore.AzureAI"
],
"disable": []
}
]
}
The base memory feature is dependency-only. Do not treat it as an independent
standalone backend; enable this provider or the Elasticsearch provider alongside it.
Configure the memory index
- Configure the Orchard Core Azure AI Search connection.
- Configure an embedding-capable AI deployment.
- Create AI Memory (Azure AI Search) in Search → Indexing.
- Select the embedding deployment and save the profile.
- Select that profile as the Memory Index profile site setting.
- Enable user memory for a supported profile or interaction and test with an authenticated user.
The selected embedding dimensions drive the vector mapping. Changing model dimensions
after memory data exists requires a new compatible index and a planned reindex.
Managed Azure mappings
| Field |
Mapping |
memoryId |
Text, key, filterable |
userId |
Text, filterable |
name |
Text, searchable, filterable |
description |
Text, searchable |
content |
Text, searchable |
updatedUtc |
DateTime, filterable, sortable |
embedding |
Searchable vector using the default HNSW profile |
The index-profile handler keeps a default vector profile and default-hnsw
algorithm configuration. It calculates dimensions from the selected deployment,
retains user-defined custom fields, and normalizes duplicate managed mappings when a
profile is loaded or saved.
User-scoped vector retrieval
AzureAISearchMemoryVectorSearchService sends a VectorizedQuery against
embedding and requires:
userId eq '<current authenticated user ID>'
It selects memory ID, name, description, content, and updated time; drops results
without content; orders by score descending; and takes at most topN. Azure request
failures and unexpected errors are logged and return no results.
Never remove the userId filter from a custom implementation. Semantic similarity
alone is not authorization and could expose memory belonging to another user.
Memory retrieval flow
- An authenticated user asks a question.
- The application embeds the query using the profile deployment.
- The Azure-keyed memory search service performs filtered vector search.
- Matching personal memory can be injected as private context or returned by the
memory tool.
- The model responds without treating retrieved memory as a public cross-user corpus.
Troubleshooting
| Symptom |
Check |
| Memory index source is absent |
Enable OrchardCore.Indexing, OrchardCore.AzureAI, and the exact Azure AI Memory feature. |
| No embedding deployment is selectable |
Configure an embedding deployment rather than only a chat deployment. |
| Memory tool returns nothing |
Confirm an authenticated identity, an active memory index profile, saved memory records, and a valid embedding configuration. |
| Index edit duplicates mappings |
Reopen and save it. The handler normalizes managed duplicates while retaining custom fields. |
| Search fails |
Check Azure endpoint, credentials, network rules, index availability, and vector dimensions. |
| Memories appear cross-user |
Treat this as an authorization defect. Verify the active user ID and preserve the mandatory userId filter. |
Security and operations
- Restrict Azure AI Search access by network and application identity.
- Keep connection strings and keys in secret providers.
- Reindex deliberately when changing embeddings or moving to another master index.
- Retain only durable, non-sensitive memory and honor user deletion requests.
- Test search with separate authenticated users to verify isolation.
Profile maintenance
The handler runs when an Azure AI Search memory profile is initialized, created,
updated, and loaded. Reopen a profile through the supported admin experience instead
of manually editing provider metadata:
- Confirm the profile provider is Azure AI Search.
- Verify the intended embedding deployment remains available.
- Save the profile so its managed fields and vector settings are normalized.
- Reindex only after changes that affect vectors, mappings, or the target index.
- Retest retrieval with two authenticated users after every integration change.
Custom fields are retained, but they must not reuse the seven managed memory field
names. Keep custom data and memory authorization rules separate from the mandatory
userId filter.
Index migration checklist
- Create a new profile when a new embedding model has different dimensions.
- Select the new profile only after its index is created and validated.
- Reindex persistent records through the AI Memory indexing lifecycle.
- Verify old and new profiles do not receive concurrent writes beyond the planned
transition period.
1---2name: orchardcore-ai-memory-azureai3description: Skill for indexing CrestApps Orchard Core AI Memory with Azure AI Search. Covers managed memory index mappings, embedding dimensions, user-scoped vector retrieval, index profiles, and Azure AI Search operations. Use this skill when requests mention AI Memory Azure AI Search, AIMemoryAzureAISearchIndexProfileHandler, AzureAISearchMemoryVectorSearchService, memory vector indexes, or Azure user-memory retrieval. Strong matches include work with CrestApps.OrchardCore.AI.Memory.AzureAI, IMemoryVectorSearchService, AIMemoryAzureAISearchDocumentIndexHandler, AddAzureAISearchIndexingSource, AzureAISearchIndexMetadata, and MemoryConstants.IndexingTaskType.4license: Apache-2.05---67# Orchard Core AI Memory Azure AI Search89## Configure Azure AI Search memory indexing1011You are an Orchard Core expert. Configure Azure AI Search for persistent user-memory12vector indexing and semantic retrieval. Maintain the strict authenticated-user filter13and use the provider-managed profile mappings.1415### Guidelines1617- Enable the exact feature ID `CrestApps.OrchardCore.AI.Memory.AzureAI`.18- Its manifest depends on `CrestApps.OrchardCore.AI.Memory`, `OrchardCore.Indexing`, and `OrchardCore.AzureAI`; the base AI Memory feature is enabled by dependency.19- Create **AI Memory (Azure AI Search)** from **Search → Indexing**, select its embedding deployment, then choose it in **Settings → Artificial Intelligence → Memory**.20- Memory remains authenticated-user scoped even though all users can occupy a shared external index.21- The backend registers `AzureAISearchMemoryVectorSearchService` as a keyed `IMemoryVectorSearchService` using `AzureAISearchConstants.ProviderName`.22- Install the package in the web or startup project and store Azure endpoint and credential configuration securely.23- Do not use memory to retain secrets, tokens, private keys, payment data, or other sensitive user data.2425### Provider registrations2627| Registration | Purpose |28|---|---|29| `AIMemoryAzureAISearchIndexProfileHandler` | Creates, updates, and normalizes Azure Search memory mappings. |30| `AIMemoryAzureAISearchDocumentIndexHandler` | Builds Azure index documents from persisted memory records. |31| `AzureAISearchMemoryVectorSearchService` | Retrieves semantically similar memories for one user. |32| `AddAzureAISearchIndexingSource` | Adds **AI Memory (Azure AI Search)** as an index source. |3334### Enable the backend3536```json37{38 "steps": [39 {40 "name": "Feature",41 "enable": [42 "CrestApps.OrchardCore.AI",43 "CrestApps.OrchardCore.AI.Memory.AzureAI",44 "OrchardCore.AzureAI"45 ],46 "disable": []47 }48 ]49}50```5152The base memory feature is dependency-only. Do not treat it as an independent53standalone backend; enable this provider or the Elasticsearch provider alongside it.5455### Configure the memory index56571. Configure the Orchard Core Azure AI Search connection.582. Configure an embedding-capable AI deployment.593. Create **AI Memory (Azure AI Search)** in **Search → Indexing**.604. Select the embedding deployment and save the profile.615. Select that profile as the Memory **Index profile** site setting.626. Enable user memory for a supported profile or interaction and test with an authenticated user.6364The selected embedding dimensions drive the vector mapping. Changing model dimensions65after memory data exists requires a new compatible index and a planned reindex.6667### Managed Azure mappings6869| Field | Mapping |70|---|---|71| `memoryId` | Text, key, filterable |72| `userId` | Text, filterable |73| `name` | Text, searchable, filterable |74| `description` | Text, searchable |75| `content` | Text, searchable |76| `updatedUtc` | DateTime, filterable, sortable |77| `embedding` | Searchable vector using the `default` HNSW profile |7879The index-profile handler keeps a `default` vector profile and `default-hnsw`80algorithm configuration. It calculates dimensions from the selected deployment,81retains user-defined custom fields, and normalizes duplicate managed mappings when a82profile is loaded or saved.8384### User-scoped vector retrieval8586`AzureAISearchMemoryVectorSearchService` sends a `VectorizedQuery` against87`embedding` and requires:8889```text90userId eq '<current authenticated user ID>'91```9293It selects memory ID, name, description, content, and updated time; drops results94without content; orders by score descending; and takes at most `topN`. Azure request95failures and unexpected errors are logged and return no results.9697Never remove the `userId` filter from a custom implementation. Semantic similarity98alone is not authorization and could expose memory belonging to another user.99100### Memory retrieval flow1011021. An authenticated user asks a question.1032. The application embeds the query using the profile deployment.1043. The Azure-keyed memory search service performs filtered vector search.1054. Matching personal memory can be injected as private context or returned by the106 memory tool.1075. The model responds without treating retrieved memory as a public cross-user corpus.108109### Troubleshooting110111| Symptom | Check |112|---|---|113| Memory index source is absent | Enable `OrchardCore.Indexing`, `OrchardCore.AzureAI`, and the exact Azure AI Memory feature. |114| No embedding deployment is selectable | Configure an embedding deployment rather than only a chat deployment. |115| Memory tool returns nothing | Confirm an authenticated identity, an active memory index profile, saved memory records, and a valid embedding configuration. |116| Index edit duplicates mappings | Reopen and save it. The handler normalizes managed duplicates while retaining custom fields. |117| Search fails | Check Azure endpoint, credentials, network rules, index availability, and vector dimensions. |118| Memories appear cross-user | Treat this as an authorization defect. Verify the active user ID and preserve the mandatory `userId` filter. |119120### Security and operations121122- Restrict Azure AI Search access by network and application identity.123- Keep connection strings and keys in secret providers.124- Reindex deliberately when changing embeddings or moving to another master index.125- Retain only durable, non-sensitive memory and honor user deletion requests.126- Test search with separate authenticated users to verify isolation.127128### Profile maintenance129130The handler runs when an Azure AI Search memory profile is initialized, created,131updated, and loaded. Reopen a profile through the supported admin experience instead132of manually editing provider metadata:1331341. Confirm the profile provider is Azure AI Search.1352. Verify the intended embedding deployment remains available.1363. Save the profile so its managed fields and vector settings are normalized.1374. Reindex only after changes that affect vectors, mappings, or the target index.1385. Retest retrieval with two authenticated users after every integration change.139140Custom fields are retained, but they must not reuse the seven managed memory field141names. Keep custom data and memory authorization rules separate from the mandatory142`userId` filter.143144### Index migration checklist145146- Create a new profile when a new embedding model has different dimensions.147- Select the new profile only after its index is created and validated.148- Reindex persistent records through the AI Memory indexing lifecycle.149- Verify old and new profiles do not receive concurrent writes beyond the planned150 transition period.
CrestApps