Skip to content

Commit ec7edd9

Browse files
retroryanclaude
retroryan
and
claude
authored
Adds sample documentation for two separate Neo4j context providers fo… (#361)
* Python: Adds sample documentation for two separate Neo4j context providers for retrieval and memory * adding pypi links * Move Neo4j integration docs from inline sections to dedicated integration pages * Add GraphRAG section and address PR review comments Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fixing dotnet docs * fixing dotnet docs --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 496daca commit ec7edd9

5 files changed

Lines changed: 342 additions & 1 deletion

File tree

‎agent-framework/TOC.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -178,6 +178,10 @@ items:
178178
href: integrations/purview.md
179179
- name: M365
180180
href: integrations/m365.md
181+
- name: Neo4j GraphRAG Provider
182+
href: integrations/neo4j-graphrag.md
183+
- name: Neo4j Memory Provider
184+
href: integrations/neo4j-memory.md
181185
- name: A2A Protocol
182186
href: integrations/a2a.md
183187
- name: AG-UI Protocol

‎agent-framework/agents/rag.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -555,6 +555,10 @@ Each connector provides the same `create_search_function` method that can be bri
555555

556556
::: zone-end
557557

558+
## Graph RAG
559+
560+
For GraphRAG using graph traversal enriched search with Cypher queries, see the [Neo4j GraphRAG Provider](../integrations/neo4j-graphrag.md).
561+
558562
## Next steps
559563

560564
> [!div class="nextstepaction"]

‎agent-framework/integrations/index.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -70,8 +70,9 @@ Here is a list of existing providers that can be used.
7070
| Memory AI Context Provider | Release Status |
7171
| ------------------------------------------------------------------ | --------------- |
7272
| [Mem0 Memory Provider](https://github.com/microsoft/agent-framework/blob/main/python/packages/mem0/agent_framework_mem0/_provider.py) | Preview |
73-
| [Redis Provider](https://github.com/microsoft/agent-framework/blob/main/python/packages/redis/agent_framework_redis/_provider.py) | Preview |
73+
| [Neo4j Memory Provider](./neo4j-memory.md) | Preview |
7474
| [Purview Context Provider](./purview.md) | Preview |
75+
| [Redis Provider](https://github.com/microsoft/agent-framework/blob/main/python/packages/redis/agent_framework_redis/_provider.py) | Preview |
7576

7677
::: zone-end
7778

@@ -85,6 +86,7 @@ Here is a list of existing providers that can be used.
8586

8687
| RAG AI Context Provider | Release Status |
8788
| ------------------------------------------------------------------ | --------------- |
89+
| [Neo4j GraphRAG Provider](./neo4j-graphrag.md) | Preview |
8890
| [Text Search Provider](https://github.com/microsoft/agent-framework/blob/main/dotnet/src/Microsoft.Agents.AI/TextSearchProvider.cs) | Preview |
8991

9092
::: zone-end
@@ -94,6 +96,7 @@ Here is a list of existing providers that can be used.
9496
| RAG AI Context Provider | Release Status |
9597
| ------------------------------------------------------------------ | --------------- |
9698
| [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 |
99+
| [Neo4j GraphRAG Provider](./neo4j-graphrag.md) | Preview |
97100

98101
::: zone-end
99102

‎agent-framework/integrations/neo4j-graphrag.md‎

Lines changed: 202 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,202 @@
1+
---
2+
title: Neo4j GraphRAG Context Provider for Agent Framework
3+
description: Learn how to use the Neo4j GraphRAG Context Provider to add knowledge graph retrieval capabilities to your Agent Framework agents
4+
zone_pivot_groups: programming-languages
5+
author: retroryan
6+
ms.topic: article
7+
ms.author: westey
8+
ms.date: 03/29/2026
9+
ms.service: agent-framework
10+
---
11+
12+
# Neo4j GraphRAG Context Provider
13+
14+
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.
15+
16+
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.
17+
18+
## Why use Neo4j for GraphRAG?
19+
20+
- **Graph enhanced retrieval**: Standard vector search returns isolated chunks; graph traversal follows connections to surface related entities, giving agents richer context.
21+
- **Flexible search modes**: Combine vector similarity, keyword/BM25, and graph traversal in a single query.
22+
- **Custom retrieval queries**: Cypher queries let you control exactly which relationships to traverse and what context to return.
23+
24+
> [!NOTE]
25+
> 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).
26+
27+
::: zone pivot="programming-language-csharp"
28+
29+
## Prerequisites
30+
31+
- A Neo4j instance (self-hosted or [Neo4j AuraDB](https://neo4j.com/cloud/aura/)) with a vector or fulltext index configured
32+
- An Azure AI Foundry project with a deployed chat model and an embedding model (e.g. `text-embedding-3-small`)
33+
- Environment variables set: `NEO4J_URI`, `NEO4J_USERNAME`, `NEO4J_PASSWORD`, `AZURE_AI_SERVICES_ENDPOINT`, `AZURE_AI_EMBEDDING_NAME`
34+
- Azure CLI credentials configured (`az login`)
35+
- .NET 8.0 or later
36+
37+
## Installation
38+
39+
```bash
40+
dotnet add package Neo4j.AgentFramework.GraphRAG
41+
```
42+
43+
## Usage
44+
45+
```csharp
46+
using Azure.AI.OpenAI;
47+
using Azure.Identity;
48+
using Microsoft.Agents.AI;
49+
using Microsoft.Agents.AI.OpenAI;
50+
using Microsoft.Extensions.AI;
51+
using Neo4j.AgentFramework.GraphRAG;
52+
using Neo4j.Driver;
53+
54+
// Read connection details from environment variables
55+
var neo4jSettings = new Neo4jSettings();
56+
var azureEndpoint = Environment.GetEnvironmentVariable("AZURE_AI_SERVICES_ENDPOINT")!;
57+
58+
// Create embedding generator
59+
var credential = new DefaultAzureCredential();
60+
var azureClient = new AzureOpenAIClient(new Uri(azureEndpoint), credential);
61+
62+
IEmbeddingGenerator<string, Embedding<float>> embedder = azureClient
63+
.GetEmbeddingClient("text-embedding-3-small")
64+
.AsIEmbeddingGenerator();
65+
66+
// Create Neo4j driver
67+
await using var driver = GraphDatabase.Driver(
68+
neo4jSettings.Uri, AuthTokens.Basic(neo4jSettings.Username, neo4jSettings.Password!));
69+
70+
// Create the Neo4j context provider
71+
await using var provider = new Neo4jContextProvider(driver, new Neo4jContextProviderOptions
72+
{
73+
IndexName = "chunkEmbeddings",
74+
IndexType = IndexType.Vector,
75+
EmbeddingGenerator = embedder,
76+
TopK = 5,
77+
RetrievalQuery = """
78+
MATCH (node)-[:FROM_DOCUMENT]->(doc:Document)
79+
OPTIONAL MATCH (doc)<-[:FILED]-(company:Company)
80+
RETURN node.text AS text, score, doc.title AS title, company.name AS company
81+
ORDER BY score DESC
82+
""",
83+
});
84+
85+
// Create an agent with the provider
86+
AIAgent agent = azureClient
87+
.GetChatClient("gpt-4o")
88+
.AsIChatClient()
89+
.AsBuilder()
90+
.UseAIContextProviders(provider)
91+
.BuildAIAgent(new ChatClientAgentOptions
92+
{
93+
ChatOptions = new ChatOptions
94+
{
95+
Instructions = "You are a financial analyst assistant.",
96+
},
97+
});
98+
99+
var session = await agent.CreateSessionAsync();
100+
Console.WriteLine(await agent.RunAsync("What risks does Acme Corp face?", session));
101+
```
102+
103+
## Key features
104+
105+
- **Index-driven**: Works with any Neo4j vector or fulltext index
106+
- **Graph traversal**: Custom Cypher queries enrich search results with related entities
107+
- **Search modes**: Vector (semantic similarity), fulltext (keyword/BM25), or hybrid (both combined)
108+
109+
## Resources
110+
111+
- [Neo4j Context Provider repository](https://github.com/neo4j-labs/neo4j-maf-provider)
112+
- [NuGet package page](https://www.nuget.org/packages/Neo4j.AgentFramework.GraphRAG)
113+
- [Workshop: Neo4j Context Providers for Agent Framework](https://github.com/neo4j-partners/maf-context-providers-lab)
114+
115+
::: zone-end
116+
117+
::: zone pivot="programming-language-python"
118+
119+
## Prerequisites
120+
121+
- A Neo4j instance (self-hosted or [Neo4j AuraDB](https://neo4j.com/cloud/aura/)) with a vector or fulltext index configured
122+
- An Azure AI Foundry project with a deployed chat model and an embedding model (e.g. `text-embedding-ada-002`)
123+
- Environment variables set: `NEO4J_URI`, `NEO4J_USERNAME`, `NEO4J_PASSWORD`, `AZURE_AI_PROJECT_ENDPOINT`, `AZURE_AI_EMBEDDING_NAME`
124+
- Azure CLI credentials configured (`az login`)
125+
- Python 3.10 or later
126+
127+
## Installation
128+
129+
```bash
130+
pip install agent-framework-neo4j
131+
```
132+
133+
## Usage
134+
135+
```python
136+
from agent_framework import Agent
137+
from agent_framework.azure import AzureAIClient
138+
from agent_framework_neo4j import Neo4jContextProvider, Neo4jSettings, AzureAISettings, AzureAIEmbedder
139+
from azure.identity import DefaultAzureCredential
140+
from azure.identity.aio import AzureCliCredential
141+
142+
# Reads NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD from environment variables
143+
neo4j_settings = Neo4jSettings()
144+
145+
# Reads AZURE_AI_PROJECT_ENDPOINT, AZURE_AI_EMBEDDING_NAME from environment variables
146+
azure_settings = AzureAISettings()
147+
148+
sync_credential = DefaultAzureCredential()
149+
embedder = AzureAIEmbedder(
150+
endpoint=azure_settings.inference_endpoint,
151+
credential=sync_credential,
152+
model=azure_settings.embedding_model,
153+
)
154+
155+
neo4j_provider = Neo4jContextProvider(
156+
uri=neo4j_settings.uri,
157+
username=neo4j_settings.username,
158+
password=neo4j_settings.get_password(),
159+
index_name=neo4j_settings.vector_index_name,
160+
index_type="vector",
161+
embedder=embedder,
162+
top_k=5,
163+
retrieval_query="""
164+
MATCH (node)-[:FROM_DOCUMENT]->(doc:Document)
165+
OPTIONAL MATCH (doc)<-[:FILED]-(company:Company)
166+
RETURN node.text AS text, score, doc.title AS title, company.name AS company
167+
ORDER BY score DESC
168+
""",
169+
)
170+
171+
async with (
172+
neo4j_provider,
173+
AzureCliCredential() as credential,
174+
AzureAIClient(credential=credential, project_endpoint=azure_settings.project_endpoint) as client,
175+
Agent(
176+
client=client,
177+
instructions="You are a financial analyst assistant.",
178+
context_providers=[neo4j_provider],
179+
) as agent,
180+
):
181+
session = agent.create_session()
182+
response = await agent.run("What risks does Acme Corp face?", session=session)
183+
```
184+
185+
## Key features
186+
187+
- **Index-driven**: Works with any Neo4j vector or fulltext index
188+
- **Graph traversal**: Custom Cypher queries enrich search results with related entities
189+
- **Search modes**: Vector (semantic similarity), fulltext (keyword/BM25), or hybrid (both combined)
190+
191+
## Resources
192+
193+
- [Neo4j Context Provider repository](https://github.com/neo4j-labs/neo4j-maf-provider)
194+
- [PyPI package page](https://pypi.org/project/agent-framework-neo4j/)
195+
- [Workshop: Neo4j Context Providers for Agent Framework](https://github.com/neo4j-partners/maf-context-providers-lab)
196+
197+
::: zone-end
198+
199+
## Next steps
200+
201+
> [!div class="nextstepaction"]
202+
> [Neo4j Memory Provider](./neo4j-memory.md)

‎agent-framework/integrations/neo4j-memory.md‎

Lines changed: 128 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
---
2+
title: Neo4j Memory Provider for Agent Framework
3+
description: Learn how to use the Neo4j Memory Provider to add persistent knowledge graph memory to your Agent Framework agents
4+
zone_pivot_groups: programming-languages
5+
author: retroryan
6+
ms.topic: article
7+
ms.author: westey
8+
ms.date: 03/29/2026
9+
ms.service: agent-framework
10+
---
11+
12+
# Neo4j Memory Provider
13+
14+
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.
15+
16+
The provider manages three types of memory:
17+
18+
- **Short-term memory**: Conversation history and recent context
19+
- **Long-term memory**: Entities, preferences, and facts extracted from interactions
20+
- **Reasoning memory**: Past reasoning traces and tool usage patterns
21+
22+
## Why use Neo4j for agent memory?
23+
24+
- **Knowledge graph persistence**: Memories are stored as connected entities, not flat records, so the agent can reason about relationships between things it remembers.
25+
- **Automatic entity extraction**: Conversations are parsed into structured entities and relationships without manual schema design.
26+
- **Cross-session recall**: Preferences, facts, and reasoning traces persist across sessions and surface automatically via context providers.
27+
28+
> [!NOTE]
29+
> 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).
30+
31+
::: zone pivot="programming-language-csharp"
32+
33+
This provider is not yet available for C#. See the Python tab for usage examples.
34+
35+
::: zone-end
36+
37+
::: zone pivot="programming-language-python"
38+
39+
## Prerequisites
40+
41+
- A Neo4j instance (self-hosted or [Neo4j AuraDB](https://neo4j.com/cloud/aura/))
42+
- An Azure AI Foundry project with a deployed chat model
43+
- An OpenAI API key or Azure OpenAI deployment (for embeddings and entity extraction)
44+
- Environment variables set: `NEO4J_URI`, `NEO4J_PASSWORD`, `AZURE_AI_PROJECT_ENDPOINT`, `OPENAI_API_KEY`
45+
- Azure CLI credentials configured (`az login`)
46+
- Python 3.10 or later
47+
48+
## Installation
49+
50+
```bash
51+
pip install neo4j-agent-memory[microsoft-agent]
52+
```
53+
54+
## Usage
55+
56+
```python
57+
import os
58+
from pydantic import SecretStr
59+
from agent_framework import Agent
60+
from agent_framework.azure import AzureAIClient
61+
from azure.identity.aio import AzureCliCredential
62+
from neo4j_agent_memory import MemoryClient, MemorySettings
63+
from neo4j_agent_memory.integrations.microsoft_agent import (
64+
Neo4jMicrosoftMemory,
65+
create_memory_tools,
66+
)
67+
68+
# Pass Neo4j and embedding configuration directly via constructor arguments.
69+
# MemorySettings also supports loading from environment variables or .env files
70+
# using the NAM_ prefix (e.g. NAM_NEO4J__URI, NAM_EMBEDDING__MODEL).
71+
settings = MemorySettings(
72+
neo4j={
73+
"uri": os.environ["NEO4J_URI"],
74+
"username": os.environ.get("NEO4J_USERNAME", "neo4j"),
75+
"password": SecretStr(os.environ["NEO4J_PASSWORD"]),
76+
},
77+
embedding={
78+
"provider": "openai",
79+
"model": "text-embedding-3-small",
80+
},
81+
)
82+
83+
memory_client = MemoryClient(settings)
84+
85+
async with memory_client:
86+
memory = Neo4jMicrosoftMemory.from_memory_client(
87+
memory_client=memory_client,
88+
session_id="user-123",
89+
)
90+
tools = create_memory_tools(memory)
91+
92+
async with (
93+
AzureCliCredential() as credential,
94+
AzureAIClient(
95+
credential=credential,
96+
project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
97+
) as client,
98+
Agent(
99+
client=client,
100+
instructions="You are a helpful assistant with persistent memory.",
101+
tools=tools,
102+
context_providers=[memory.context_provider],
103+
) as agent,
104+
):
105+
session = agent.create_session()
106+
response = await agent.run("Remember that I prefer window seats on flights.", session=session)
107+
```
108+
109+
## Key features
110+
111+
- **Bidirectional**: Automatically retrieves relevant context before invocation and saves new memories after responses
112+
- **Entity extraction**: Builds a knowledge graph from conversations using a multi-stage extraction pipeline
113+
- **Preference learning**: Infers and stores user preferences across sessions
114+
- **Memory tools**: Agents can explicitly search memory, remember preferences, and find entity connections
115+
116+
## Resources
117+
118+
- [Neo4j Agent Memory repository](https://github.com/neo4j-labs/agent-memory)
119+
- [PyPI package page](https://pypi.org/project/neo4j-agent-memory/)
120+
- [Sample: Retail Assistant with Neo4j Agent Memory](https://github.com/neo4j-labs/agent-memory/tree/main/examples/microsoft_agent_retail_assistant)
121+
- [Workshop: Neo4j Context Providers for Agent Framework](https://github.com/neo4j-partners/maf-context-providers-lab)
122+
123+
::: zone-end
124+
125+
## Next steps
126+
127+
> [!div class="nextstepaction"]
128+
> [Neo4j GraphRAG Context Provider](./neo4j-graphrag.md)

0 commit comments

Comments
 (0)