Erste Schritte mit Agent Memory

Dieser Artikel führt Sie durch die Installation von Agent Memory und die Ausführung grundlegender Speichervorgänge, einschließlich Speichern und Abrufen von Benutzerkontext.

Voraussetzungen

Stellen Sie sicher, dass Sie:

Oracle AI Database-Featureanforderungen

Für den DB-Backed-Speicher von Oracle Agent Memory ist Oracle AI Database 23ai oder höher erforderlich (Datenbankversion 23.4 oder höher). Setzen Sie für Oracle AI Vector Search den Initialisierungsparameter COMPATIBLE der Datenbank auf 23.4.0 oder höher.

Die ausgewählte Suchstrategie hat folgende zusätzliche Anforderungen:

Während der Initialisierung des verwalteten Schemas validiert Oracle Agent Memory die Version der verbundenen Datenbank, bevor DDL ausgeführt wird, und meldet eine Upgradeaktion, wenn die ausgewählte Suchstrategie nicht verfügbar ist.

Setup der verwalteten Datenbank

Wenn ein Schemaeigentümer einen Speicherspeicher erstellt oder neu erstellt, bereitet das Python-Package "Oracle Agent Memory" die erforderlichen verwalteten Datenbankobjekte vor. Der Eigentümer benötigt die Systemberechtigungen Oracle CREATE TABLE und CREATE PROCEDURE.

Melden Sie sich als Schemaeigentümer für das Schemasetup an. Eine Anwendungsverbindung, die schema_owner verwendet, greift auf einen vorhandenen Speicher zu und muss SchemaPolicy.REQUIRE_EXISTING verwenden. Die verwalteten Datenbankobjekte des Eigentümers werden nicht erstellt oder aktualisiert.

SDK installieren

Alle Versionen und unterstützten Plattformen von oracleagentmemory finden Sie auf der Seite "Softwaredownload".

Um Agent Memory zu installieren, führen Sie folgenden Befehl aus:

pip install "oracleagentmemory==26.8.0"

Bei der Installation mit pip werden vordefinierte Binärräder auf unterstützten Plattformen abgerufen.

Logging und Diagnostik

Oracle AI Agent Memory gibt Diagnosemeldungen über das standardmäßige Python-Logging unter Loggernamen aus, die mit oracleagentmemory beginnen. Das SDK konfiguriert keine Handler oder Logebenen. Anwendungen können diese Logs an die vorhandene Konsole, Datei oder Beobachtbarkeitspipeline weiterleiten. Einige Logdatensätze verwenden die extra-Felder des Python-Loggings für sichere strukturierte Diagnosen, die von strukturierten Logging-Handlern erfasst werden können.

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("oracleagentmemory").setLevel(logging.INFO)

Um Fehler in kontrollierten Umgebungen zu beheben, aktivieren Sie DEBUG-Logs:

logging.getLogger("oracleagentmemory").setLevel(logging.DEBUG)

Behalten Sie Produktions-Deployments auf einer Nicht-DEBUG-Ebene bei. DEBUG-Logs sind für die Entwicklung und Unterstützung von Diagnosen vorgesehen. Logmeldungstext sollte nicht als stabile öffentliche API behandelt werden.

Gültigkeitsdauer und Abgelaufener Datensatz löschen

Von Oracle DB gesicherte Nachrichten und Speicher können automatisch durch eine Kombination aus Aufbewahrungsstandardwerten auf Schemaebene und Werten für ttl_days/ttl_anchor pro Datensatz bei Schreib- und Aktualisierungs-APIs ablaufen.

Wenn Oracle Agent Memory sein verwaltetes Schema erstellt oder aktualisiert, erstellt es außerdem einen täglichen DBMS_SCHEDULER-Löschjob, der abgelaufene Zeilen, ihre Abruf-Chunks und verwaiste Abruf-Chunks, deren unterstützte Quellzeile nicht mehr vorhanden ist, physisch entfernt. Wenn das Schemasetup diesen Job erstellen muss, dem Datenbankbenutzer jedoch CREATE JOB fehlt, wird das Setup mit einer Warnung abgeschlossen: Abgelaufene Zeilen bleiben aus Lese- und Suchvorgängen herausgefiltert, abgelaufene und verwaiste Chunks werden jedoch erst physisch gelöscht, wenn ein berechtigter Benutzer den Job erstellt. Unter SchemaPolicy.REQUIRE_EXISTING wird ein fehlender Löschjob toleriert und auf der Ebene DEBUG protokolliert.

Linked-Memory-Schemas erstellen auch einen Trigger, der verbleibende Speicher erneut validiert, nachdem ein Link gelöscht wurde. Dies gilt auch, wenn der Löschjob einen abgelaufenen Speicher löscht und Oracle seine Links kaskadiert. Der Schemaeigentümer benötigt CREATE TRIGGER während der Schemaerstellung oder dem Upgrade. Normale Laufzeitbenutzer benötigen diese Berechtigung nicht.

Das vollständige Aufbewahrungsmodell, das Setup von MemoryRetentionConfig, Verifizierungsabfragen für Löschjobs, die manuelle Erstellung von DBA-Jobs und Python-Beispiele mit TimeToLiveAnchor finden Sie unter Live-Zeit für Nachrichten und Erinnerungen verwenden.

Linked-Memory-Schemaberechtigungen

Das Linked-Memory-Schema enthält ein Oracle SQL-Eigenschaftsdiagramm und einen Datenbanktrigger, der den Lebenszyklusstatus beim Löschen von Links korrekt hält.

Wenn Sie memory_store_id festlegen, wird der Name des verwalteten Diagramms auf dieselbe Weise wie die Tabellen vorangestellt. Beispiel: memory_store_id="SALES" erstellt SALES_MEMORY_GRAPH.

Die Werte APP_SCHEMA und APP_USER sind Platzhalter. Ersetzen Sie sie durch Ihre Datenbankbenutzernamen. In den Beispielen wird Großbuchstaben verwendet, da Oracle-IDs ohne Anführungszeichen in Großbuchstaben gespeichert werden.

  1. Erteilen Sie während des Schemasetups dem Schemaeigentümer CREATE PROPERTY GRAPH und CREATE TRIGGER. Diese sind mit SchemaPolicy.CREATE_IF_NECESSARY oder SchemaPolicy.RECREATE erforderlich, wenn der Trigger für das verwaltete Diagramm oder das Löschen von Links erstellt werden muss. 
    GRANT CREATE PROPERTY GRAPH TO APP_SCHEMA;
GRANT CREATE TRIGGER TO APP_SCHEMA;
-- Run OracleAgentMemory schema setup as APP_SCHEMA.
REVOKE CREATE PROPERTY GRAPH FROM APP_SCHEMA;
REVOKE CREATE TRIGGER FROM APP_SCHEMA;

    Erteilen Sie sie vor einem späteren SDK-Upgrade erneut, wenn dieses Upgrade den Trigger für das verwaltete Diagramm oder das Löschen von Links erstellen oder neu erstellen muss.

  2. Entscheiden Sie während der normalen Anwendungslaufzeit, welcher Benutzer sich bei Oracle anmeldet:
    • Wenn der Laufzeitbenutzer APP_SCHEMA ist, ist keine zusätzliche Diagrammberechtigung erforderlich. Der Grafikeigentümer kann auf sein eigenes Diagramm zugreifen.
    • Wenn der Laufzeitbenutzer nicht identisch ist, führen Sie nach dem Schemasetup den folgenden Befehl als APP_SCHEMA aus. Der Standarddiagrammname ist MEMORY_GRAPH. Verwenden Sie den Präfixnamen, wenn memory_store_id festgelegt ist. 
      GRANT SELECT ON PROPERTY GRAPH APP_SCHEMA.MEMORY_GRAPH TO APP_USER;

      Der Laufzeitbenutzer benötigt auch den normalen Datenbankzugriff, der für den Rest des Oracle Agent-Speicher-Deployments erforderlich ist.

SchemaPolicy.REQUIRE_EXISTING überspringt den ersten Schritt, da erwartet wird, dass Diagramm und Trigger bereits vorhanden sind. Ein separater Laufzeitbenutzer benötigt weiterhin Zugriff auf das verwaltete Eigenschaftsdiagramm.

Speicherinstanz initialisieren

Erstellen Sie eine OracleAgentMemory-Instanz, indem Sie die Einbettung, das LLM und die Datenbankverbindung konfigurieren.

import oracledb

from oracleagentmemory.core import SchemaPolicy
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory
from oracleagentmemory.apis.searchscope import SearchScope
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="YOUR_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id="T_GET_STARTED",
)

Hinweis: In verwalteten Oracle AI Database-Schemas wird standardmäßig kein Aufbewahrungszeitraum für Nachrichten und Speicher festgelegt. Konfigurieren Sie die Time-to-Live-Einstellungen für MemoryRetentionConfig oder pro Datensatz, um einen anderen Aufbewahrungszeitraum zu verwenden. Weitere Informationen finden Sie unter Live-Zeit für Nachrichten und Erinnerungen verwenden.

Speichereinträge speichern

Erstellen Sie zunächst einen Thread, fügen Sie Nachrichten hinzu, und speichern Sie einen Speichereintrag für den Benutzer.

messages = [
    {
        "role": "user",
        "content": (
            "Orange juice has become my favorite breakfast drink lately, "
            "what can I pair it with?"
        ),
    },
    {
        "role": "assistant",
        "content": (
            "Nice! Orange juice goes great with something savory. "
            "Try eggs and toast, avocado toast, or a breakfast sandwich."
        ),
    },
]

thread = memory.create_thread(user_id="user_123")
#add_messages will add messages to the DB and extract memories automatically
thread.add_messages(messages)
#add_memory adds memory to the DB
thread.add_memory("The user likes orange juice with breakfast.")

Speichereinträge abrufen

Speicher mit einer Abfrage mit Benutzergeltungsbereich suchen

results = memory.search(query="orange juice", scope=SearchScope(user_id="user_123"))
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")

Ausgabe:

- [memory] The user likes orange juice with breakfast.
- [message] Orange juice has become my favorite breakfast drink lately, what can I pair it with?
- [message] Nice! Orange juice goes great with something savory. Try eggs and toast,
            avocado toast, or a breakfast sandwich.

Hinweis: Die angezeigte Ausgabe ist illustrativ. Zukünftige Versionen können zusätzliche Ergebnistypen, Felder oder Anforderungen zurückgeben.

Modellkompatibilität

Die folgenden Large Language Models (LLMs) und Einbettungsmodelle sind mit oracleagentmemory kompatibel.

LLMs

Die folgenden Large Language Models (LLMs) wurden als kompatibel bestätigt.

Von OCI gehostete Modelle

OpenAI

Selbst gehostete LLMs

Anthrop

Zwilling

Einbettungen

Die folgenden Einbettungsmodelle wurden als kompatibel bestätigt.

Von OCI gehostete Modelle

OpenAI

Selbst gehostete LLMs

Zwilling