Proveedor de memoria Neo4j

El proveedor de memoria Neo4j proporciona a los agentes de Agent Framework memoria persistente respaldada por un gráfico de conocimiento. A diferencia de los proveedores RAG que recuperan de bases de conocimiento estáticas, el proveedor de memoria almacena y recupera interacciones del agente, extrayendo automáticamente entidades y creando un grafo de conocimiento a lo largo del tiempo.

El proveedor administra tres tipos de memoria:

• Memoria a corto plazo: historial de conversaciones y contexto reciente
• Memoria a largo plazo: Entidades, preferencias y hechos extraídos de interacciones
• Memoria de razonamiento: seguimientos de razonamiento anteriores y patrones de uso de herramientas

¿Por qué usar Neo4j para la memoria del agente?

• Persistencia del gráfico de conocimiento: los recuerdos se almacenan como entidades conectadas, no registros planos, por lo que el agente puede razonar sobre las relaciones entre las cosas que recuerda.
• Extracción automática de entidades: las conversaciones se analizan en entidades estructuradas y relaciones sin diseño de esquema manual.
• Recuperación entre sesiones: las preferencias, los hechos y los rastros de razonamiento se conservan automáticamente entre sesiones y se muestran automáticamente a través de proveedores de contexto.

Nota:

Neo4j ofrece dos integraciones independientes para Agent Framework. Este proveedor (neo4j-agent-memory) es para memoria persistente : almacenamiento y recuperación de interacciones del agente, extracción de entidades y creación de un gráfico de conocimiento a lo largo del tiempo. Para el uso de GraphRAG desde un grafo del conocimiento existente mediante búsqueda vectorial, de texto completo o híbrida, consulte el Proveedor de Contextos de GraphRAG Neo4j.

Nota:

El paquete de .NET (AgentMemory) es un puerto .NET independiente y mantenido por la comunidad del proveedor de memoria neo4j Labs, no es un paquete oficial de Neo4j Labs. Consulte el repositorio AgentMemory (.NET) para obtener información sobre el origen y los detalles.

Prerrequisitos

• Una instancia de Neo4j (autogestionado o Neo4j AuraDB)
• Una implementación Azure OpenAI o Microsoft Foundry (un modelo de chat + un modelo de inserción)
• Conjunto de variables de entorno: NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, , AZURE_OPENAI_ENDPOINT
• credenciales de CLI de Azure configuradas (az login) o una clave de API
• .NET 8.0 o posterior

Instalación

dotnet add package AgentMemory
dotnet add package AgentMemory.AgentFramework

Uso

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

Características clave

• Bidireccional: Neo4jMemoryContextProvider recupera la memoria pertinente antes de cada ejecución y conserva la nueva memoria después de : no se necesita cableado manual.
• Extracción de entidades: crea un gráfico de conocimiento a partir de conversaciones con una canalización de extracción configurable (AutoExtractOnPersist)
• Aprendizaje de preferencias: infiere y almacena las preferencias del usuario, datos y entidades, que un AgentSession completamente nuevo recupera automáticamente para el mismo usuario
• Herramientas de memoria: MemoryToolFactory expone AIFunctionpara que el modelo pueda buscar, recordar y recuperar explícitamente.
• Prioriza la inyección de dependencias: registra mediante AddNeo4jAgentMemory (integra internamente Core + Neo4j) y AddAgentMemoryFramework, encajando de forma natural en aplicaciones de Generic Host y ASP.NET Core
• Beyond Agent Framework: la misma biblioteca también se integra con clientes de Kernel semántico y MCP, e incluye observabilidad de OpenTelemetry integrada.

Recursos

• Repositorio AgentMemory (.NET)
• Página del paquete NuGet
• Ejemplo: Asistente para minoristas con AgentMemory

Prerrequisitos

• Una instancia de Neo4j (autogestionado o Neo4j AuraDB)
• Un proyecto de Fundición de IA de Azure con un modelo de chat implementado
• Una clave de API de OpenAI o una implementación de Azure OpenAI (para incrustaciones y extracción de entidades)
• Conjunto de variables de entorno: NEO4J_URI, NEO4J_PASSWORD, FOUNDRY_PROJECT_ENDPOINT, , FOUNDRY_MODEL, OPENAI_API_KEY
• Credenciales de la CLI de Azure configuradas (az login)
• Python 3.10 o posterior

Instalación

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

Uso

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)

Características clave

• Bidireccional: recupera automáticamente el contexto pertinente antes de la invocación y guarda nuevos recuerdos después de las respuestas.
• Extracción de entidades: crea un grafo de conocimiento a partir de conversaciones mediante una canalización de extracción en varias fases
• Aprendizaje de preferencias: infiere y almacena preferencias de usuario a través de sesiones
• Herramientas de memoria: los agentes pueden buscar explícitamente en la memoria, recordar preferencias y hallar conexiones de entidad

Recursos

• Repositorio de memoria del agente Neo4j
• Página del paquete pyPI
• Ejemplo: Asistente de Ventas con Memoria del Agente Neo4j
• Taller: Proveedores de contexto Neo4j para el Marco del Agente

Nota:

La compatibilidad con go para esta característica estará disponible próximamente. Consulte el repositorio de Agent Framework Go para obtener el estado más reciente.

Pasos siguientes

Proveedor de contexto de Neo4j GraphRAG