Adds sample documentation for two separate Neo4j context providers fo…

agent-framework/TOC.yml

@@ -164,6 +164,10 @@ items:
     href: integrations/purview.md
   - name: M365
     href: integrations/m365.md
+  - name: Neo4j GraphRAG Provider
+    href: integrations/neo4j-graphrag.md
+  - name: Neo4j Memory Provider
+    href: integrations/neo4j-memory.md
   - name: A2A Protocol
     href: integrations/a2a.md
   - name: AG-UI Protocol

agent-framework/agents/rag.md

@@ -555,6 +555,10 @@ Each connector provides the same `create_search_function` method that can be bri
 
 ::: zone-end
 
+## Graph RAG
+
+For GraphRAG using graph traversal enriched search with Cypher queries, see the [Neo4j GraphRAG Provider](../integrations/neo4j-graphrag.md).
+
 ## Next steps
 
 > [!div class="nextstepaction"]

agent-framework/integrations/index.md

@@ -70,8 +70,9 @@ Here is a list of existing providers that can be used.
 | Memory AI Context Provider                                         | Release Status  |
 | ------------------------------------------------------------------ | --------------- |
 | [Mem0 Memory Provider](https://github.com/microsoft/agent-framework/blob/main/python/packages/mem0/agent_framework_mem0/_provider.py) | Preview         |
-| [Redis Provider](https://github.com/microsoft/agent-framework/blob/main/python/packages/redis/agent_framework_redis/_provider.py)     | Preview         |
+| [Neo4j Memory Provider](./neo4j-memory.md) | Preview         |
 | [Purview Context Provider](./purview.md) | Preview         |
+| [Redis Provider](https://github.com/microsoft/agent-framework/blob/main/python/packages/redis/agent_framework_redis/_provider.py)     | Preview         |
 
 ::: zone-end
 
@@ -85,6 +86,7 @@ Here is a list of existing providers that can be used.
 
 | RAG AI Context Provider                                            | Release Status  |
 | ------------------------------------------------------------------ | --------------- |
+| [Neo4j GraphRAG Provider](./neo4j-graphrag.md) | Preview         |
 | [Text Search Provider](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/TextSearchProvider.cs) | Preview         |
 
 ::: zone-end
@@ -94,6 +96,7 @@ Here is a list of existing providers that can be used.
 | RAG AI Context Provider                                            | Release Status  |
 | ------------------------------------------------------------------ | --------------- |
 | [Azure AI Search Provider](https://github.com/microsoft/agent-framework/blob/main/python/packages/azure-ai-search/agent_framework_azure_ai_search/_search_provider.py) | Preview         |
+| [Neo4j GraphRAG Provider](./neo4j-graphrag.md) | Preview         |
 
 ::: zone-end
 

agent-framework/integrations/neo4j-graphrag.md

@@ -0,0 +1,202 @@
+---
+title: Neo4j GraphRAG Context Provider for Agent Framework
+description: Learn how to use the Neo4j GraphRAG Context Provider to add knowledge graph retrieval capabilities to your Agent Framework agents
+zone_pivot_groups: programming-languages
+author: retroryan
+ms.topic: article
+ms.author: westey
+ms.date: 03/29/2026
+ms.service: agent-framework
+---
+
+# Neo4j GraphRAG Context Provider
+
+The Neo4j GraphRAG Context Provider adds Retrieval Augmented Generation (RAG) capabilities to Agent Framework agents using a Neo4j knowledge graph. It supports vector, fulltext, and hybrid search modes, with optional graph traversal to enrich results with related entities via custom Cypher queries.
+
+For knowledge graph scenarios where relationships between entities matter, this provider retrieves relevant subgraphs rather than isolated text chunks, giving agents richer context for generating responses.
+
+## Why use Neo4j for GraphRAG?
+
+- **Graph enhanced retrieval**: Standard vector search returns isolated chunks; graph traversal follows connections to surface related entities, giving agents richer context.
+- **Flexible search modes**: Combine vector similarity, keyword/BM25, and graph traversal in a single query.
+- **Custom retrieval queries**: Cypher queries let you control exactly which relationships to traverse and what context to return.
+
+> [!NOTE]
+> Neo4j offers two separate integrations for Agent Framework. This provider is for **GraphRAG** — searching an existing knowledge graph to ground agent responses. For **persistent memory** that learns from conversations and builds a knowledge graph over time, see the [Neo4j Memory Provider](./neo4j-memory.md).
+
+::: zone pivot="programming-language-csharp"
+
+## Prerequisites
+
+- A Neo4j instance (self-hosted or [Neo4j AuraDB](https://neo4j.com/cloud/aura/)) with a vector or fulltext index configured
+- An Azure AI Foundry project with a deployed chat model and an embedding model (e.g. `text-embedding-3-small`)
+- Environment variables set: `NEO4J_URI`, `NEO4J_USERNAME`, `NEO4J_PASSWORD`, `AZURE_AI_SERVICES_ENDPOINT`, `AZURE_AI_EMBEDDING_NAME`
+- Azure CLI credentials configured (`az login`)
+- .NET 8.0 or later
+
+## Installation
+
+```bash
+dotnet add package Neo4j.AgentFramework.GraphRAG
+```
+
+## Usage
+
+```csharp
+using Azure.AI.OpenAI;
+using Azure.Identity;
+using Microsoft.Agents.AI;
+using Microsoft.Agents.AI.OpenAI;
+using Microsoft.Extensions.AI;
+using Neo4j.AgentFramework.GraphRAG;
+using Neo4j.Driver;
+
+// Read connection details from environment variables
+var neo4jSettings = new Neo4jSettings();
+var azureEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_SERVICES_ENDPOINT")!;
+
+// Create embedding generator
+var credential = new DefaultAzureCredential();
+var azureClient = new AzureOpenAIClient(new Uri(azureEndpoint), credential);
+
+IEmbeddingGenerator<string, Embedding<float>> embedder = azureClient
+    .GetEmbeddingClient("text-embedding-3-small")
+    .AsIEmbeddingGenerator();
+
+// Create Neo4j driver
+await using var driver = GraphDatabase.Driver(
+    neo4jSettings.Uri, AuthTokens.Basic(neo4jSettings.Username, neo4jSettings.Password!));
+
+// Create the Neo4j context provider
+await using var provider = new Neo4jContextProvider(driver, new Neo4jContextProviderOptions
+{
+    IndexName = "chunkEmbeddings",
+    IndexType = IndexType.Vector,
+    EmbeddingGenerator = embedder,
+    TopK = 5,
+    RetrievalQuery = """
+        MATCH (node)-[:FROM_DOCUMENT]->(doc:Document)
+        OPTIONAL MATCH (doc)<-[:FILED]-(company:Company)
+        RETURN node.text AS text, score, doc.title AS title, company.name AS company
+        ORDER BY score DESC
+        """,
+});
+
+// Create an agent with the provider
+AIAgent agent = azureClient
+    .GetChatClient("gpt-4o")
+    .AsIChatClient()
+    .AsBuilder()
+    .UseAIContextProviders(provider)
+    .BuildAIAgent(new ChatClientAgentOptions
+    {
+        ChatOptions = new ChatOptions
+        {
+            Instructions = "You are a financial analyst assistant.",
+        },
+    });
+
+var session = await agent.CreateSessionAsync();
+Console.WriteLine(await agent.RunAsync("What risks does Acme Corp face?", session));
+```
+
+## Key features
+
+- **Index-driven**: Works with any Neo4j vector or fulltext index
+- **Graph traversal**: Custom Cypher queries enrich search results with related entities
+- **Search modes**: Vector (semantic similarity), fulltext (keyword/BM25), or hybrid (both combined)
+
+## Resources
+
+- [Neo4j Context Provider repository](https://github.com/neo4j-labs/neo4j-maf-provider)
+- [NuGet package page](https://www.nuget.org/packages/Neo4j.AgentFramework.GraphRAG)
+- [Workshop: Neo4j Context Providers for Agent Framework](https://github.com/neo4j-partners/maf-context-providers-lab)
+
+::: zone-end
+
+::: zone pivot="programming-language-python"
+
+## Prerequisites
+
+- A Neo4j instance (self-hosted or [Neo4j AuraDB](https://neo4j.com/cloud/aura/)) with a vector or fulltext index configured
+- An Azure AI Foundry project with a deployed chat model and an embedding model (e.g. `text-embedding-ada-002`)
+- Environment variables set: `NEO4J_URI`, `NEO4J_USERNAME`, `NEO4J_PASSWORD`, `AZURE_AI_PROJECT_ENDPOINT`, `AZURE_AI_EMBEDDING_NAME`
+- Azure CLI credentials configured (`az login`)
+- Python 3.10 or later
+
+## Installation
+
+```bash
+pip install agent-framework-neo4j
+```
+
+## Usage
+
+```python
+from agent_framework import Agent
+from agent_framework.azure import AzureAIClient
+from agent_framework_neo4j import Neo4jContextProvider, Neo4jSettings, AzureAISettings, AzureAIEmbedder
+from azure.identity import DefaultAzureCredential
+from azure.identity.aio import AzureCliCredential
+
+# Reads NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD from environment variables
+neo4j_settings = Neo4jSettings()
+
+# Reads AZURE_AI_PROJECT_ENDPOINT, AZURE_AI_EMBEDDING_NAME from environment variables
+azure_settings = AzureAISettings()
+
+sync_credential = DefaultAzureCredential()
+embedder = AzureAIEmbedder(
+    endpoint=azure_settings.inference_endpoint,
+    credential=sync_credential,
+    model=azure_settings.embedding_model,
+)
+
+neo4j_provider = Neo4jContextProvider(
+    uri=neo4j_settings.uri,
+    username=neo4j_settings.username,
+    password=neo4j_settings.get_password(),
+    index_name=neo4j_settings.vector_index_name,
+    index_type="vector",
+    embedder=embedder,
+    top_k=5,
+    retrieval_query="""
+        MATCH (node)-[:FROM_DOCUMENT]->(doc:Document)
+        OPTIONAL MATCH (doc)<-[:FILED]-(company:Company)
+        RETURN node.text AS text, score, doc.title AS title, company.name AS company
+        ORDER BY score DESC
+    """,
+)
+
+async with (
+    neo4j_provider,
+    AzureCliCredential() as credential,
+    AzureAIClient(credential=credential, project_endpoint=azure_settings.project_endpoint) as client,
+    Agent(
+        client=client,
+        instructions="You are a financial analyst assistant.",
+        context_providers=[neo4j_provider],
+    ) as agent,
+):
+    session = agent.create_session()
+    response = await agent.run("What risks does Acme Corp face?", session=session)
+```
+
+## Key features
+
+- **Index-driven**: Works with any Neo4j vector or fulltext index
+- **Graph traversal**: Custom Cypher queries enrich search results with related entities
+- **Search modes**: Vector (semantic similarity), fulltext (keyword/BM25), or hybrid (both combined)
+
+## Resources
+
+- [Neo4j Context Provider repository](https://github.com/neo4j-labs/neo4j-maf-provider)
+- [PyPI package page](https://pypi.org/project/agent-framework-neo4j/)
+- [Workshop: Neo4j Context Providers for Agent Framework](https://github.com/neo4j-partners/maf-context-providers-lab)
+
+::: zone-end
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Neo4j Memory Provider](./neo4j-memory.md)

agent-framework/integrations/neo4j-memory.md

@@ -0,0 +1,128 @@
+---
+title: Neo4j Memory Provider for Agent Framework
+description: Learn how to use the Neo4j Memory Provider to add persistent knowledge graph memory to your Agent Framework agents
+zone_pivot_groups: programming-languages
+author: retroryan
+ms.topic: article
+ms.author: westey
+ms.date: 03/29/2026
+ms.service: agent-framework
+---
+
+# Neo4j Memory Provider
+
+The Neo4j Memory Provider gives Agent Framework agents persistent memory backed by a knowledge graph. Unlike RAG providers that retrieve from static knowledge bases, the memory provider stores and recalls agent interactions, automatically extracting entities and building a knowledge graph over time.
+
+The provider manages three types of memory:
+
+- **Short-term memory**: Conversation history and recent context
+- **Long-term memory**: Entities, preferences, and facts extracted from interactions
+- **Reasoning memory**: Past reasoning traces and tool usage patterns
+
+## Why use Neo4j for agent memory?
+
+- **Knowledge graph persistence**: Memories are stored as connected entities, not flat records, so the agent can reason about relationships between things it remembers.
+- **Automatic entity extraction**: Conversations are parsed into structured entities and relationships without manual schema design.
+- **Cross-session recall**: Preferences, facts, and reasoning traces persist across sessions and surface automatically via context providers.
+
+> [!NOTE]
+> Neo4j offers two separate integrations for Agent Framework. This provider (`neo4j-agent-memory`) is for **persistent memory** — storing and recalling agent interactions, extracting entities, and building a knowledge graph over time. For **GraphRAG** from an existing knowledge graph using vector, fulltext, or hybrid search, see the [Neo4j GraphRAG Context Provider](./neo4j-graphrag.md).
+
+::: zone pivot="programming-language-csharp"
+
+This provider is not yet available for C#. See the Python tab for usage examples.
+
+::: zone-end
+
+::: zone pivot="programming-language-python"
+
+## Prerequisites
+
+- A Neo4j instance (self-hosted or [Neo4j AuraDB](https://neo4j.com/cloud/aura/))
+- An Azure AI Foundry project with a deployed chat model
+- An OpenAI API key or Azure OpenAI deployment (for embeddings and entity extraction)
+- Environment variables set: `NEO4J_URI`, `NEO4J_PASSWORD`, `AZURE_AI_PROJECT_ENDPOINT`, `OPENAI_API_KEY`
+- Azure CLI credentials configured (`az login`)
+- Python 3.10 or later
+
+## Installation
+
+```bash
+pip install neo4j-agent-memory[microsoft-agent]
+```
+
+## Usage
+
+```python
+import os
+from pydantic import SecretStr
+from agent_framework import Agent
+from agent_framework.azure import AzureAIClient
+from azure.identity.aio import AzureCliCredential
+from neo4j_agent_memory import MemoryClient, MemorySettings
+from neo4j_agent_memory.integrations.microsoft_agent import (
+    Neo4jMicrosoftMemory,
+    create_memory_tools,
+)
+
+# Pass Neo4j and embedding configuration directly via constructor arguments.
+# MemorySettings also supports loading from environment variables or .env files
+# using the NAM_ prefix (e.g. NAM_NEO4J__URI, NAM_EMBEDDING__MODEL).
+settings = MemorySettings(
+    neo4j={
+        "uri": os.environ["NEO4J_URI"],
+        "username": os.environ.get("NEO4J_USERNAME", "neo4j"),
+        "password": SecretStr(os.environ["NEO4J_PASSWORD"]),
+    },
+    embedding={
+        "provider": "openai",
+        "model": "text-embedding-3-small",
+    },
+)
+
+memory_client = MemoryClient(settings)
+
+async with memory_client:
+    memory = Neo4jMicrosoftMemory.from_memory_client(
+        memory_client=memory_client,
+        session_id="user-123",
+    )
+    tools = create_memory_tools(memory)
+
+    async with (
+        AzureCliCredential() as credential,
+        AzureAIClient(
+            credential=credential,
+            project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
+        ) as client,
+        Agent(
+            client=client,
+            instructions="You are a helpful assistant with persistent memory.",
+            tools=tools,
+            context_providers=[memory.context_provider],
+        ) as agent,
+    ):
+        session = agent.create_session()
+        response = await agent.run("Remember that I prefer window seats on flights.", session=session)
+```
+
+## Key features
+
+- **Bidirectional**: Automatically retrieves relevant context before invocation and saves new memories after responses
+- **Entity extraction**: Builds a knowledge graph from conversations using a multi-stage extraction pipeline
+- **Preference learning**: Infers and stores user preferences across sessions
+- **Memory tools**: Agents can explicitly search memory, remember preferences, and find entity connections
+
+## Resources
+
+- [Neo4j Agent Memory repository](https://github.com/neo4j-labs/agent-memory)
+- [PyPI package page](https://pypi.org/project/neo4j-agent-memory/)
+- [Sample: Retail Assistant with Neo4j Agent Memory](https://github.com/neo4j-labs/agent-memory/tree/main/examples/microsoft_agent_retail_assistant)
+- [Workshop: Neo4j Context Providers for Agent Framework](https://github.com/neo4j-partners/maf-context-providers-lab)
+
+::: zone-end
+
+## Next steps
+
+> [!div class="nextstepaction"]
+> [Neo4j GraphRAG Context Provider](./neo4j-graphrag.md)