Neo4j-minnesprovider

Neo4j-minnesprovidern ger Agent Framework-agenter beständigt minne som backas upp av ett kunskapsdiagram. Till skillnad från RAG-leverantörer som hämtar från statiska kunskapsbaser lagrar och återkallar minnesprovidern agentinteraktioner, extraherar automatiskt entiteter och skapar ett kunskapsdiagram över tid.

Providern hanterar tre typer av minne:

• Kortsiktigt minne: Konversationshistorik och aktuell kontext
• Långtidsminne: Entiteter, inställningar och fakta som extraherats från interaktioner
• Resonemangsminne: Tidigare resonemangsspårningar och användningsmönster för verktyg

Varför använda Neo4j för agentminne?

• Kunskapsdiagramspersistens: Minnen lagras som anslutna entiteter, inte platta poster, så agenten kan resonera om relationer mellan saker som den kommer ihåg.
• Automatisk entitetsextrahering: Konversationer parsas i strukturerade entiteter och relationer utan manuell schemadesign.
• Tvärsessionsbevarande: Inställningar, fakta och resonemangsspårningar bevaras och visas automatiskt mellan sessioner via kontextprovidrar.

Anmärkning

Neo4j erbjuder två separata integreringar för Agent Framework. Den här providern (neo4j-agent-memory) är avsedd för beständigt minne – lagra och återkalla agentinteraktioner, extrahera entiteter och skapa ett kunskapsdiagram över tid. För GraphRAG från ett befintligt kunskapsdiagram med hjälp av vektor-, fulltext- eller hybridsökning, se Neo4j GraphRAG-kontextprovidern.

Anmärkning

.NET-paketet (AgentMemory) är en oberoende, samhällsunderhållen .NET port för Neo4j Labs-minnesprovidern – det är inte ett officiellt Neo4j Labs-paket. Se AgentMemory-repot (.NET) för källkod och mer information.

Förutsättningar

• En Neo4j-instans (lokalt installerad eller Neo4j AuraDB)
• En Azure OpenAI- eller Microsoft Foundry-distribution (en chattmodell + en inbäddningsmodell)
• Miljövariabler inställda: NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, AZURE_OPENAI_ENDPOINT
• Azure CLI autentiseringsuppgifter som konfigurerats (az login) eller en API-nyckel
• .NET 8.0 eller senare

Installation

dotnet add package AgentMemory
dotnet add package AgentMemory.AgentFramework

Usage

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);

Viktiga funktioner

• Dubbelriktad: Neo4jMemoryContextProvider återkallar relevant minne före varje körning och bevarar nytt minne efter – inga manuella ledningar behövs
• Entitetsextrahering: skapar ett kunskapsdiagram från konversationer med en konfigurerbar extraheringspipeline (AutoExtractOnPersist)
• Inställningsinlärning: härleder och lagrar användarinställningar, fakta och entiteter, som automatiskt återkallas av en helt ny AgentSession för samma användare
• Minnesverktyg: MemoryToolFactory exponerar AIFunctions så att modellen uttryckligen kan söka, komma ihåg och återkalla
• Beroendeinmatning först: registrerar sig via AddNeo4jAgentMemory (binder upp Core + Neo4j internt) och AddAgentMemoryFramework, passar naturligt in i Generic Host- och ASP.NET Core-appar
• Beyond Agent Framework: samma bibliotek integreras också med Semantic Kernel- och MCP-klienter och innehåller inbyggd OpenTelemetry-observerbarhet

Resurser

• AgentMemory-lagringsplats (.NET)
• NuGet-paketsida
• Exempel: Retail Assistant med AgentMemory

Förutsättningar

• En Neo4j-instans (lokalt installerad eller Neo4j AuraDB)
• Ett Azure AI Foundry-projekt med en distribuerad chattmodell
• En OpenAI API-nyckel eller Azure OpenAI-distribution (för inbäddning och entitetsextrahering)
• Miljövariabler ställda: NEO4J_URI, NEO4J_PASSWORD, FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL, OPENAI_API_KEY
• Konfigurerade Azure CLI-autentiseringsuppgifter (az login)
• Python 3.10 eller senare

Installation

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

Usage

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)

Viktiga funktioner

• Dubbelriktad: Hämtar automatiskt relevant kontext före anrop och sparar nya minnen efter svar
• Entitetsextrahering: Skapar ett kunskapsdiagram från konversationer med hjälp av en pipeline för extrahering i flera steg
• Inställningsinlärning: Härleder och lagrar användarinställningar mellan sessioner
• Minnesverktyg: Agenter kan uttryckligen söka efter minne, komma ihåg inställningar och hitta entitetsanslutningar

Resurser

• Lagringsplats för Neo4j-agentminne
• PyPI-paketsida
• Exempel: Retail Assistant med Neo4j:s Agentminne
• Workshop: Neo4j Kontextleverantörer för Agent Framework

Anmärkning

Go-stöd för den här funktionen kommer snart. Se Agent Framework Go-lagringsplatsen för den senaste statusen.

Nästa steg

Neo4j GraphRAG-kontextprovider