Neo4j-geheugenprovider

De Neo4j-geheugenprovider biedt Agent Framework-agents permanent geheugen dat wordt ondersteund door een kennisgrafiek. In tegenstelling tot RAG-providers die worden opgehaald uit statische knowledge bases, slaat de geheugenprovider agentinteracties op en roept deze op, waarbij entiteiten automatisch worden geëxtraheerd en een kennisgrafiek in de loop van de tijd wordt gebouwd.

De provider beheert drie soorten geheugen:

• Kortlopend geheugen: Gespreksgeschiedenis en recente context
• Langetermijngeheugen: Entiteiten, voorkeuren en feiten die zijn geëxtraheerd uit interacties
• Redeneringsgeheugen: Verleden redeneringssporen en gebruikspatronen van hulpprogramma's

Waarom Neo4j gebruiken voor agentgeheugen?

• Persistentie van knowledge graph: herinneringen worden opgeslagen als verbonden entiteiten, niet platte records, zodat de agent kan reden hebben voor relaties tussen dingen die worden onthouden.
• Automatische entiteitextractie: gesprekken worden geparseerd in gestructureerde entiteiten en relaties zonder handmatig schemaontwerp.
• Cross-sessie herinnering: Voorkeuren, feiten en redeneringssporen blijven behouden tussen sessies en worden automatisch weergegeven via contextproviders.

Opmerking

Neo4j biedt twee afzonderlijke integraties voor Agent Framework. Deze provider (neo4j-agent-memory) is bedoeld voor permanent geheugen : het opslaan en intrekken van agentinteracties, het extraheren van entiteiten en het bouwen van een kennisgrafiek in de loop van de tijd. Zie de Neo4j GraphRAG Context Provider voor GraphRAG vanuit een bestaande kennisgrafiek met behulp van vector-, fulltekst- of hybride zoekopdrachten.

Opmerking

Het .NET-pakket (AgentMemory) is een onafhankelijke, door de community onderhouden .NET poort van de Neo4j Labs-geheugenprovider. Het is geen officieel Neo4j Labs-pakket. Zie de opslagplaats agentMemory (.NET) voor bron en details.

Vereiste voorwaarden

• Een Neo4j-exemplaar (zelf-hostend of Neo4j AuraDB)
• Een Azure OpenAI of Microsoft Foundry-implementatie (een chatmodel + een insluitmodel)
• Omgevingsvariabelen ingesteld: NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORDAZURE_OPENAI_ENDPOINT
• Azure CLI-inloggegevens geconfigureerd (az login), of een API-sleutel
• .NET 8.0 of hoger

Installation

dotnet add package AgentMemory
dotnet add package AgentMemory.AgentFramework

Gebruik

using Azure.AI.OpenAI;
using Azure.Identity;
using Microsoft.Agents.AI;
using Microsoft.Extensions.AI;
using Microsoft.Extensions.DependencyInjection;
using Microsoft.Extensions.Hosting;
using AgentMemory;
using AgentMemory.Abstractions.Services;
using AgentMemory.AgentFramework;
using AgentMemory.AgentFramework.Tools;

var builder = Host.CreateApplicationBuilder(args);

// Registers Core + Neo4j infrastructure in one call (reads NEO4J_URI / NEO4J_USERNAME /
// NEO4J_PASSWORD, falling back to local-dev defaults). Passing configureLlm opts in to
// LLM-backed entity/fact/preference extraction, using the IChatClient registered below.
builder.Services.AddNeo4jAgentMemory(
    configureMemory: _ => { },
    configureNeo4j: neo4j =>
    {
        neo4j.Uri = Environment.GetEnvironmentVariable("NEO4J_URI") ?? "bolt://localhost:7687";
        neo4j.Username = Environment.GetEnvironmentVariable("NEO4J_USERNAME") ?? "neo4j";
        neo4j.Password = Environment.GetEnvironmentVariable("NEO4J_PASSWORD") ?? "password";
    },
    configureLlm: _ => { });

// Any Microsoft.Extensions.AI-compatible chat + embedding client works
var azureClient = new AzureOpenAIClient(
    new Uri(Environment.GetEnvironmentVariable("AZURE_OPENAI_ENDPOINT")!), new DefaultAzureCredential());
builder.Services.AddSingleton(azureClient.GetChatClient("gpt-4o-mini").AsIChatClient());
builder.Services.AddSingleton(azureClient.GetEmbeddingClient("text-embedding-3-small").AsIEmbeddingGenerator());

// AutoExtractOnPersist builds the knowledge graph from every conversation turn
builder.Services.AddAgentMemoryFramework(options =>
{
    options.AutoExtractOnPersist = true;
    options.ContextFormat.IncludeEntities = true;
    options.ContextFormat.IncludeFacts = true;
    options.ContextFormat.IncludePreferences = true;
});

using var host = builder.Build();
await using var scope = host.Services.CreateAsyncScope();
var services = scope.ServiceProvider;

// Bootstraps Neo4j schema/indexes on first run (idempotent)
await services.GetRequiredService<ISchemaBootstrapper>().BootstrapAsync();

var memoryProvider = services.GetRequiredService<Neo4jMemoryContextProvider>();
var memoryTools = services.GetRequiredService<MemoryToolFactory>().CreateAIFunctions();

// WithMemoryOwnerScoping wraps the whole invocation — recall, the tool-calling loop, and
// persistence — in the owner scope set by WithMemoryIdentity below, so no manual
// BeginOwnerScope call is needed around RunAsync.
AIAgent agent = services.GetRequiredService<IChatClient>().AsAIAgent(new ChatClientAgentOptions
{
    ChatOptions = new ChatOptions
    {
        Instructions = "You are a helpful assistant with persistent memory.",
        Tools = [.. memoryTools],
    },
    AIContextProviders = [memoryProvider],
}).WithMemoryOwnerScoping(services);

var session = (await agent.CreateSessionAsync())
    .WithMemoryIdentity(userId: "user-123", sessionId: "session-1", applicationId: "my-app");

var response = await agent.RunAsync("Remember that I prefer window seats on flights.", session);

Belangrijkste kenmerken

• Bidirectioneel: Neo4jMemoryContextProvider roept relevante geheugen terug voor elke uitvoering en houdt nieuw geheugen na - geen handmatig bedrading nodig
• Entiteitextractie: bouwt een kennisgrafiek op basis van gesprekken met een configureerbare extractiepijplijn (AutoExtractOnPersist)
• Voorkeursleer: gebruikersvoorkeuren, feiten en entiteiten afleiden en opslaan, automatisch teruggehaald door een gloednieuwe AgentSession gebruiker voor dezelfde gebruiker
• Geheugentools: MemoryToolFactory stelt AIFunctions beschikbaar zodat het model expliciet kan zoeken, onthouden en oproepen
• Dependency-injectie als uitgangspunt: wordt geregistreerd via AddNeo4jAgentMemory (verbindt Core + Neo4j intern) en AddAgentMemoryFramework, en past natuurlijk in de Generic Host en ASP.NET Core-apps
• Beyond Agent Framework: dezelfde bibliotheek kan ook worden geïntegreerd met Semantic Kernel- en MCP-clients en bevat ingebouwde OpenTelemetry-waarneembaarheid

Middelen

• Opslagplaats voor AgentMemory (.NET)
• NuGet-pakketpagina
• Voorbeeld: Retail Assistant met AgentMemory

Vereiste voorwaarden

• Een Neo4j-exemplaar (zelf-hostend of Neo4j AuraDB)
• Een Azure AI Foundry-project met een geïmplementeerd chatmodel
• Een OpenAI API-sleutel of Azure OpenAI-implementatie (voor insluitingen en entiteitextractie)
• Omgevingsvariabelen ingesteld: NEO4J_URI, NEO4J_PASSWORD, FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODELOPENAI_API_KEY
• Geconfigureerde Azure CLI-referenties (az login)
• Python 3.10 of hoger

Installation

pip install neo4j-agent-memory[microsoft-agent]

Gebruik

import os
from pydantic import SecretStr
from agent_framework import Agent
from agent_framework.foundry import FoundryChatClient
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, Agent(
            client=FoundryChatClient(
            credential=credential,
            project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
            model=os.environ["FOUNDRY_MODEL"],
        ),
        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)

Belangrijkste kenmerken

• Bidirectioneel: haalt automatisch relevante context op voordat u aanroept en slaat nieuwe herinneringen op na reacties
• Entiteitextractie: bouwt een kennisgrafiek op basis van gesprekken met behulp van een pijplijn voor extractie in meerdere fasen
• Voorkeursleer: gebruikersvoorkeuren afleiden en opslaan in sessies
• Geheugenhulpprogramma's: Agents kunnen expliciet zoeken in geheugen, voorkeuren onthouden en entiteitsverbindingen zoeken

Middelen

• Neo4j Agent Memory Repository
• PyPI-pakketpagina
• Voorbeeld: Retail Assistant met Neo4j Agent Memory
• Workshop: Neo4j-contextproviders voor Agent Framework

Opmerking

Ondersteuning voor deze functie is binnenkort beschikbaar. Zie de opslagplaats Agent Framework Go voor de meest recente status.

Volgende stappen 

Neo4j GraphRAG Context Provider