Penyedia Memori Neo4j

Penyedia Memori Neo4j memberikan agen Agent Framework memori persisten yang didukung oleh grafik pengetahuan. Tidak seperti penyedia RAG yang mengambil dari pangkalan pengetahuan statis, penyedia memori menyimpan dan memanggil kembali interaksi agen, secara otomatis mengekstrak entitas dan membangun grafik pengetahuan dari waktu ke waktu.

Penyedia mengelola tiga jenis memori:

• Memori jangka pendek: Riwayat percakapan dan konteks terbaru
• Memori jangka panjang: Entitas, preferensi, dan fakta yang diekstrak dari interaksi
• Memori penalaran: Jejak penalaran sebelumnya dan pola penggunaan alat

Mengapa menggunakan Neo4j untuk memori agen?

• Persistensi grafik pengetahuan: Memori disimpan sebagai entitas yang terhubung, bukan rekaman datar, sehingga agen dapat beralasan tentang hubungan antara hal-hal yang diingatnya.
• Ekstraksi entitas otomatis: Percakapan diurai ke dalam entitas dan hubungan terstruktur tanpa desain skema manual.
• Pengingat lintas sesi: Preferensi, fakta, dan jejak penalaran tetap ada di seluruh sesi dan muncul secara otomatis melalui penyedia konteks.

Nota

Neo4j menawarkan dua integrasi terpisah untuk Agent Framework. Penyedia ini (neo4j-agent-memory) adalah untuk memori persisten - menyimpan dan menarik kembali interaksi agen, mengekstrak entitas, dan membangun grafik pengetahuan dari waktu ke waktu. Untuk GraphRAG dari graf pengetahuan yang sudah ada menggunakan pencarian vektor, teks penuh, atau hibrid, lihat Penyedia Konteks Neo4j GraphRAG.

Nota

Paket .NET (AgentMemory) adalah port .NET independen yang dikelola komunitas dari penyedia memori Neo4j Labs - ini bukan paket Resmi Neo4j Labs. Lihat repositori AgentMemory (.NET) untuk sumber dan detailnya.

Prasyarat

• Instans Neo4j (dihost sendiri atau Neo4j AuraDB)
• Penyebaran Azure OpenAI atau Microsoft Foundry (model obrolan + model penyematan)
• Variabel lingkungan diatur: NEO4J_URI, NEO4J_USERNAME, NEO4J_PASSWORD, AZURE_OPENAI_ENDPOINT
• kredensial Azure CLI yang dikonfigurasi (az login), atau kunci API
• .NET 8.0 atau yang lebih baru

Penginstalan

dotnet add package AgentMemory
dotnet add package AgentMemory.AgentFramework

Penggunaan

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

Fitur utama

• Dua arah: Neo4jMemoryContextProvider mengambil kembali memori yang relevan sebelum setiap eksekusi dan menyimpan memori baru setelahnya — tanpa perlu penyiapan manual
• Ekstraksi entitas: membangun grafik pengetahuan dari percakapan dengan alur ekstraksi yang dapat dikonfigurasi (AutoExtractOnPersist)
• Pembelajaran preferensi: menyimpulkan dan menyimpan preferensi, fakta, dan entitas pengguna, dipanggil kembali secara otomatis oleh pengguna baru AgentSession untuk pengguna yang sama
• Alat memori: MemoryToolFactory menyediakan berbagai AIFunction sehingga model dapat secara eksplisit mencari, mengingat, dan mengambil kembali
• Mengutamakan injeksi dependensi: didaftarkan melalui AddNeo4jAgentMemory (menghubungkan Core + Neo4j secara internal) dan AddAgentMemoryFramework, cocok secara alami untuk Generic Host dan aplikasi ASP.NET Core
• Beyond Agent Framework: pustaka yang sama juga terintegrasi dengan klien Kernel Semantik dan MCP, dan mencakup pengamatan OpenTelemetry bawaan

Sumber Daya

• Repositori AgentMemory (.NET)
• Halaman paket NuGet
• Sampel: Asisten Ritel dengan AgentMemory

Prasyarat

• Instans Neo4j (dihost sendiri atau Neo4j AuraDB)
• Proyek Azure AI Foundry dengan model percakapan yang telah diterapkan
• Kunci API OpenAI atau penyebaran Azure OpenAI (untuk penyematan dan ekstraksi entitas)
• Variabel lingkungan diatur: NEO4J_URI, , NEO4J_PASSWORDFOUNDRY_PROJECT_ENDPOINT, , FOUNDRY_MODELOPENAI_API_KEY
• Kredensial Azure CLI dikonfigurasi (az login)
• Python 3.10 atau yang lebih baru

Penginstalan

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

Penggunaan

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)

Fitur utama

• Dua arah: Secara otomatis mengambil konteks yang relevan sebelum pemanggilan dan menyimpan memori baru setelah respons
• Ekstraksi entitas: Membangun grafik pengetahuan dari percakapan menggunakan alur ekstraksi multi-tahap
• Pembelajaran preferensi: Menyimpulkan dan menyimpan preferensi pengguna di seluruh sesi
• Alat memori: Agen dapat secara eksplisit mencari memori, mengingat preferensi, dan menemukan koneksi entitas

Sumber Daya

• Repositori Memori Agen Neo4j
• Halaman paket PyPI
• Contoh: Asisten Ritel dengan Memori Agen Neo4j
• Lokakarya: Penyedia Konteks Neo4j untuk Kerangka Kerja Agen

Nota

Dukungan Go untuk fitur ini akan segera hadir. Lihat repositori Agent Framework Go untuk status terbaru.

Langkah berikutnya

Penyedia Konteks Neo4j GraphRAG