Condividi tramite

Provider di memoria Neo4j

Il provider di memoria Neo4j offre agli agenti di Agent Framework la memoria persistente supportata da un grafico delle conoscenze. A differenza dei provider RAG che recuperano da knowledge base statiche, il provider di memoria archivia e richiama le interazioni dell'agente, estraendo automaticamente le entità e creando un grafico delle informazioni nel tempo.

Il provider gestisce tre tipi di memoria:

  • Memoria a breve termine: cronologia delle conversazioni e contesto recente
  • Memoria a lungo termine: entità, preferenze e fatti estratti dalle interazioni
  • Memoria di ragionamento: tracce di ragionamento passate e modelli di utilizzo degli strumenti

Perché usare Neo4j per la memoria dell'agente?

  • Persistenza del grafico delle conoscenze: le memorie vengono archiviate come entità connesse, non come record flat, in modo che l'agente possa ragionare sulle relazioni tra elementi che ricorda.
  • Estrazione automatica di entità: le conversazioni vengono analizzate in entità strutturate e relazioni senza progettazione manuale dello schema.
  • Richiamo cross-sessione: preferenze, fatti e tracce di ragionamento persistono tra sessioni e sono visualizzati automaticamente tramite fornitori di contesto.

Annotazioni

Neo4j offre due integrazioni separate per Agent Framework. Questo provider (neo4j-agent-memory) è per la memoria persistente , ovvero l'archiviazione e il richiamo delle interazioni dell'agente, l'estrazione di entità e la creazione di un grafico delle informazioni nel tempo. Per GraphRAG da un grafo delle conoscenze esistente usando la ricerca vettoriale, fulltext o ibrida, vedere il Provider di contesto GraphRAG di Neo4j.

Questo provider non è ancora disponibile per C#. Per esempi di utilizzo, vedere la scheda Python.

Prerequisiti

  • Istanza Neo4j (autogestito o Neo4j AuraDB)
  • Un progetto Azure AI Foundry con un modello di chat distribuito
  • Una chiave API OpenAI o una distribuzione OpenAI di Azure (per incorporamenti ed estrazione di entità)
  • Set di variabili di ambiente: NEO4J_URI, NEO4J_PASSWORD, FOUNDRY_PROJECT_ENDPOINT, FOUNDRY_MODEL, OPENAI_API_KEY
  • Credenziali di Azure CLI configurate (az login)
  • Python 3.10 o versione successiva

Installazione

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

Utilizzo

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)

Funzionalità principali

  • Bidirezionale: recupera automaticamente il contesto pertinente prima della chiamata e salva nuovi ricordi dopo le risposte
  • Estrazione di entità: crea un grafico delle conoscenze dalle conversazioni usando una pipeline di estrazione a più fasi
  • Apprendimento delle preferenze: deduce e archivia le preferenze utente tra le sessioni
  • Strumenti di memoria: gli agenti possono cercare in modo esplicito la memoria, memorizzare le preferenze e trovare connessioni entità

risorse

Passaggi successivi

Neo4j GraphRAG Context Provider

  • Last updated on