Agent-Speicher

Auf dieser Seite wird die konkrete Implementierung von Oracle AI Agent Memory vorgestellt.

Oracle Agent-Speicher

Hinweis: OracleAgentMemory.delete_thread() ist der unterstützte Pfad für die Thread-bezogene kaskadierende Bereinigung. Es entfernt den Thread zusammen mit zugehörigen Nachrichten, dauerhaften Speichern und verwalteten Abrufdaten. Dies ist breiter als OracleThread.delete_message(), wodurch nur die Raw-Nachrichtenzeile gelöscht wird. Bevor der Thread gelöscht wird, wartet er auf die frühere akzeptierte Hintergrundextraktion, die diesem Client für diesen Thread bereits bekannt ist. Es wird nicht jeder gleichzeitige Vorgang für denselben Thread serialisiert, während der Löschvorgang ausgeführt wird.

Klasse oracleagentmemory.core.OracleAgentMemory

Basen: IAgentMemory

Agent-Speicherclient, der von Oracle DB oder einem vom Aufrufer bereitgestellten Speicher gesichert wird.

Erstellen Sie einen Speicherclient.

Warnung: SchemaPolicy.CREATE_IF_NECESSARY kann teurer sein als der normale Clientstart, da es DDL des verwalteten Schemas anwenden und Daten mit bestmöglichem Aufwand neu schreiben kann, bevor die Initialisierung erfolgreich verläuft. Planen Sie das erste Öffnen eines älteren verwalteten Schemas als Migrations- oder Wartungsvorgang, wenn dieses Schema viele Zeilen enthalten kann.

Wenn das Schemasetup den Löschjob für verwaltete abgelaufene Datensätze erstellen muss, dem Datenbankbenutzer jedoch die Berechtigung für den Scheduler-Job fehlt, warnt die Initialisierung und wird fortgesetzt. Abgelaufene Nachrichten und Speicher bleiben vor Lese- und Suchvorgängen verborgen, werden jedoch erst physisch gelöscht, wenn der Job von einem Benutzer mit CREATE JOB oder einer entsprechenden Scheduler-Berechtigung erstellt wurde.

Wenn SchemaPolicy.CREATE_IF_NECESSARY zum ersten Mal einen verwalteten Hybridindex über ein vorhandenes Schema erstellt, scannt Oracle den gespeicherten Suchtext und erstellt den verwalteten Hybridindexstatus aus dem konfigurierten datenbankinternen Modell. Der Clientstart wartet, bis diese DDL abgeschlossen ist. Planen Sie daher das erste Hybridupgrade als Migrations- oder Wartungsvorgang für große Schemas. SearchIndexSyncMode steuert die laufende Wartung, nachdem der Index vorhanden ist. Die erste Indexerstellung wird nicht asynchron.

Beispiele

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    SearchIndexSyncMode,
    OracleAgentMemory,
    SchemaPolicy,
    SearchStrategy,
)
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)

Verwenden Sie ein DB-internes Einbettungsmodell, um die Oracle-Hybridindexsuche zu nutzen:

from oracleagentmemory.core.embedders import OracleDBEmbedder
db_embedder = OracleDBEmbedder(
    connection=db_pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
hybrid_client = OracleAgentMemory(
    connection=db_pool,
    embedder=db_embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.HYBRID,
    search_index_sync=SearchIndexSyncMode.ON_COMMIT,
)

Methode add_agent

Fügen Sie dem Shop einen Agent-Profildatensatz hinzu.

Hinweise

Agent-Profildatensätze werden im Speicher auf Client-Ebene gespeichert und absichtlich nicht kopiert. Die zurückgegebene Datensatz-ID ist dieselbe öffentliche ID, die von der Anwendung verwendet wird wie agent_id.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent(
    "a1",
    "Support assistant",
    metadata={"source": "catalog"},
)
'a1'

Methode add_memory

Fügen Sie im Speichersystem einen Speicher hinzu, der dem angegebenen Benutzer, Agent und Thread zugewiesen wird.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("User likes pizza", memory_id="mem-1")
memory_id
'mem-1'

Methode add_memory_async (asynchron)

Fügen Sie dem Client asynchron einen Speicherdatensatz hinzu.

Methode add_user

Fügen Sie der Filiale einen Benutzerprofildatensatz hinzu.

Hinweise

Benutzerprofildatensätze werden im Kundenspeicher gespeichert und absichtlich unkopiert. Die zurückgegebene Datensatz-ID ist dieselbe öffentliche ID, die von der Anwendung verwendet wird wie user_id.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user(
    "u1",
    "Prefers concise answers.",
    metadata={"source": "crm"},
)
'u1'

Methode close

Schließen Sie die Agent-Speicherkomponente.

Das Schließen stoppt die Annahme neuer Hintergrundextraktionsarbeiten und wartet, bis die ausstehende Hintergrundspeicherextraktion bis zum konfigurierten Timeout abgeschlossen ist. Wenn dieser Timeout abläuft, gibt close() auch dann zurück, wenn einige Hintergrundextraktionsarbeiten noch nicht abgeschlossen sind. Die Methode ist idempotent.

Beispiele

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.close()

Methode close_async (asynchron)

Schließen Sie die Agent-Speicherkomponente asynchron.

Diese Methode folgt demselben Herunterfahrverhalten wie close(). Wenn der Timeout abläuft, kann er zurückgegeben werden, während die Hintergrundextraktion noch ausgeführt wird.

Beispiele

await client.close_async()

Methode create_thread

Erstellen und registrieren Sie einen Thread.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
thread.thread_id
'c1'

Methode delete_agent

Agent-Profildatensatz nach ID löschen.

Hinweise

Kaskadierende Löschvorgänge werden im zugrunde liegenden Speicher geplant und ausgeführt, sodass das Löschen des Profils und alle untergeordneten Löschvorgänge mit Geltungsbereich in einem Speichervorgang erfolgen. Bevor das kaskadierende Löschen ausgeführt wird, wartet diese Methode auf eine frühere Hintergrundextraktion, die bereits für die zu diesem Zeitpunkt über diese Agent-Speicherkomponente bekannten eigenen Threads akzeptiert wurde. Sie wartet nicht auf die Arbeit, die nach Beginn dieser Wartezeit akzeptiert wird, oder auf die Arbeit, die von einer anderen Agent-Speicherkomponente oder einem anderen Agent-Prozess gestartet wurde. Die gleichzeitige Verwendung mit Akteurbereich während des Löschvorgangs wird nicht unterstützt.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a-delete", "Support assistant")
'a-delete'
client.delete_agent("a-delete")
1

Methode delete_memory

Löschen Sie einen speicherähnlichen Datensatz (z. B. Speicher, Fakt, Voreinstellung oder Richtlinie) nach Kennung.

Beispiele

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("Temporary memory", memory_id="mem-delete")
client.delete_memory(memory_id)
1

Methode delete_memory_async (asynchron)

Löschen Sie asynchron einen speicherähnlichen Datensatz (z. B. Speicher, Fakt, Präferenz oder Richtlinie) durch Kennung.

Methode delete_thread

Löschen Sie alle Datensätze, die mit einer Thread-ID verknüpft sind.

Hinweise

Verwenden Sie diesen Vorgang, wenn ein Thread vollständig entfernt werden muss. Der Sicherungsspeicher löscht den Thread zusammen mit zugehörigen Thread-bezogenen Nachrichten, dauerhaften Speichern und verwalteten Abrufdaten. Dies unterscheidet sich von OracleThread.delete_message(), das nur den Raw-Nachrichtendatensatz entfernt und nicht auf abgeleitete Speicher kaskadiert, die aus dieser Nachricht erstellt wurden. Vor dem Löschen des Threads wartet diese Methode auf eine frühere Hintergrundextraktion, die bereits für diesen Thread über diese Agent-Speicherkomponente akzeptiert wurde. Es wartet nicht auf Hintergrundarbeit, die nach Beginn dieser Wartezeit akzeptiert wird, oder auf Arbeit, die von einer anderen Agent-Speicherkomponente oder einem anderen Agent-Prozess gestartet wurde. Die gleichzeitige Verwendung desselben Threads während des Löschvorgangs wird nicht unterstützt.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c-delete")
client.delete_thread(thread.thread_id)
1

Methode delete_user

Benutzerprofildatensatz nach ID löschen.

Hinweise

Kaskadierende Löschvorgänge werden im zugrunde liegenden Speicher geplant und ausgeführt, sodass das Löschen des Profils und alle untergeordneten Löschvorgänge mit Geltungsbereich in einem Speichervorgang erfolgen. Bevor das kaskadierende Löschen ausgeführt wird, wartet diese Methode auf eine frühere Hintergrundextraktion, die bereits für die zu diesem Zeitpunkt über diese Agent-Speicherkomponente bekannten eigenen Threads akzeptiert wurde. Sie wartet nicht auf die Arbeit, die nach Beginn dieser Wartezeit akzeptiert wird, oder auf die Arbeit, die von einer anderen Agent-Speicherkomponente oder einem anderen Agent-Prozess gestartet wurde. Die gleichzeitige Verwendung mit Akteurbereich während des Löschvorgangs wird nicht unterstützt.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u-delete", "Prefers concise answers.")
'u-delete'
client.delete_user("u-delete")
1

Methode get_thread

Ruft einen zuvor erstellten Thread ab.

Hinweise

Explizite Overrides pro Aufruf haben Vorrang. Wenn Laufzeit-Overrides ausgelassen werden, verwenden erneut geöffnete Threads eine persistente Laufzeitkonfiguration, sofern verfügbar, bevor sie auf SDK-Standardwerte zurückgreifen.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
created = client.create_thread(thread_id="c1", user_id="u1")
loaded = client.get_thread("c1")
loaded.user_id
'u1'

Synchron nach Datensätzen suchen, die für eine Abfrage relevant sind.

Hinweise

Explizite None-Geltungsbereichswerte folgen weiterhin den aufgelösten exakten Übereinstimmungsregeln: exact_*_match=False lässt diese Dimension uneingeschränkt zu, während exact_*_match=True nur mit Datensätzen übereinstimmt, die in dieser Dimension nicht kopiert wurden.

Methode search_async (asynchron)

Suche asynchron nach Datensätzen, die für eine Abfrage relevant sind.

Hinweise

Explizite None-Geltungsbereichswerte folgen weiterhin den aufgelösten exakten Übereinstimmungsregeln: exact_*_match=False lässt diese Dimension uneingeschränkt zu, während exact_*_match=True nur mit Datensätzen übereinstimmt, die in dieser Dimension nicht kopiert wurden.

Methode update_memory

Einen gespeicherten speicherähnlichen Datensatz nach Kennung aktualisieren.

Hinweise

Ausgelassene Felder werden aus dem gespeicherten Datensatz beibehalten. Der gespeicherte Geltungsbereich bleibt unverändert. Metadatenersetzung ist eine vollständige Objektersetzung, keine rekursive JSON-Zusammenführung.

Methode update_memory_async (asynchron)

Aktualisieren Sie einen gespeicherten speicherähnlichen Datensatz asynchron nach Kennung.

Hinweise

Ausgelassene Felder bleiben unverändert. Umfangsaktualisierungen werden von dieser API nicht unterstützt. Metadatenersetzung ist eine vollständige Objektersetzung, keine rekursive JSON-Zusammenführung.

Methode update_thread

Threadmetadaten und dauerhafte Aktualisierungen der Laufzeitkonfiguration beibehalten.

Hinweise

Die Laufzeitkonfiguration wird aus dem gespeicherten Unterhaltungsthread plus den expliziten Overrides aufgelöst, die an diesen Aufruf übergeben werden, und entspricht der get_thread-Semantik, bevor das Ergebnis persistiert wird. Ausgelassene Metadaten- und Laufzeitkonfigurationsupdates werden aus gespeicherten Daten und nicht aus zuvor geladenen OracleThread-Instanzen aufgelöst. Nur explizit bereitgestellte Metadatenupdates oder dauerhafte Laufzeitkonfigurations-Overrides werden zurückgeschrieben. Metadatenersetzung ist eine vollständige Objektersetzung, keine rekursive JSON-Zusammenführung. Thread-Eigentümerschaft kann über diese API nicht geändert werden, sodass user_id und agent_id unverändert bleiben. Veränderbarer Laufzeitzustand, wie Extraktionszähler, bleibt unberührt.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
updated = client.update_thread(
    "c1",
    metadata={"flags": {"vip": True}},
    message_shortening_input_token_limit=12_000,
)
updated.message_shortening_input_token_limit
12000

Methode wait_for_memory_extraction

Warten Sie auf eine frühere Hintergrundspeicherextraktion, die von diesem Client gestartet wurde.

Diese Methode wartet auf die Hintergrundextraktion, die bereits über diese OracleAgentMemory-Instanz gestartet wurde, über alle Threads hinweg, deren Eigentümer diese Agent-Speicherkomponente ist. Es wartet nicht auf den Start der Extraktion nach Beginn dieser Wartezeit, auf die Extraktion, die von einer anderen Agent-Speicherkomponente gestartet wurde, oder auf die Extraktion, die in einem anderen Prozess ausgeführt wird. Extraktionsfehler zählen als beendet für diese Wartezeit.

Beispiele

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.wait_for_memory_extraction(timeout=10)

Methode wait_for_memory_extraction_async (asynchron)

Asynchrones Warten auf frühere Hintergrundspeicherextraktion.

Diese Methode folgt demselben Verhalten wie wait_for_memory_extraction().

Beispiele

await client.wait_for_memory_extraction_async(timeout=10)

Speicherextraktion

Klasse oracleagentmemory.core.MemoryExtractionConfig

Basis: object

Gruppierte Einstellungen für die automatische Speicherextraktion.

Übergeben Sie dieses Objekt an OracleAgentMemory, create_thread, get_thread oder update_thread, um die automatische Extraktion zu konfigurieren. Ausgelassene Felder werden von der nächsten größeren Einstellung übernommen. Beispiel: Ein Thread, der ohne memory_extraction_frequency erstellt wurde, verwendet den Standardwert der Agent-Speicherkomponente, und der Komponentenstandardwert wird auf den SDK-Standardwert zurückgesetzt.

Beispiele

from oracleagentmemory.core import MemoryExtractionConfig, MemoryExtractionMode
config = MemoryExtractionConfig(
    extract_memories=True,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
)

Klasse oracleagentmemory.core.MemoryExtractionMode

Basis: str, Enum

Steuert, wann die automatische Speicherextraktion ausgeführt wird.

INLINE führt die automatische Extraktion aus, bevor die Schreibmethode zurückgegeben wird. BACKGROUND gibt zurück, nachdem der Raw-Schreibvorgang erfolgreich war und die erforderliche Extraktionsarbeit im Hintergrund versucht wurde. Die Hintergrundextraktion ist am besten: abgeleitete Erinnerungen können später erscheinen oder niemals geschrieben werden, wenn die Hintergrundarbeit nicht abgeschlossen werden kann.

HINTERGRUND = 'HINTERGRUND'

Nach Raw-Nachrichtenpersistenz zurückkehren und Best-Effort-Extraktion in Hintergrundarbeit ausführen.

INLINE = 'INLINE'

Führen Sie die Extraktion aus, bevor die Schreibmethode zurückgegeben wird.

Klasse oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

Basis: str, Enum

Steuert, was passiert, wenn die Hintergrundextraktion nicht rechtzeitig in eine Warteschlange gestellt werden kann.

LÖSCHEN = 'DROP'

Melden Sie eine Warnung, und fahren Sie sofort fort, wenn die Warteschlangenkapazität nicht verfügbar ist.

WAIT_THEN_DROP = 'WAIT_THEN_DROP'

Warten Sie bis zum konfigurierten Timeout auf die Queuekapazität, melden Sie eine Warnung an, und fahren Sie fort.

WAIT_THEN_RAISE = 'WAIT_THEN_RAISE'

Warten Sie bis zum konfigurierten Timeout auf die Queuekapazität, und starten Sie dann TimeoutError.