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. Das Löschen auf Client-Ebene wartet auf die relevante frühere Hintergrundextraktion: Threadlöschung wartet auf diesen Thread, Speicherlöschung wartet auf den Thread des gespeicherten Ziels, wenn er vorhanden ist, und Benutzer- oder Agentlöschung wartet auf bekannte Threads, unabhängig davon, ob die kaskadierende Bereinigung aktiviert ist oder nicht. Diese Waits decken nur Arbeiten ab, die von demselben Client akzeptiert werden, bevor das Warten beginnt.

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

Um auf ein Schema zuzugreifen, das von einem anderen Datenbankbenutzer erstellt wurde, konfigurieren Sie memory_rw_pool für den Anwendungs-DB-Benutzer, und setzen Sie memory_schema_owner auf den Datenbanknamen des Eigentümerbenutzers ohne Anführungszeichen.

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),
)
pruned_search_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    pruner_llm=llm,
)
shared_client = OracleAgentMemory(
    connection=memory_rw_pool,
    embedder=embedder,
    llm=llm,
    schema_owner=memory_schema_owner,
)

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,
    memory_store_id=memory_store_id,
)

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_agent_async (asynchron)

Fügen Sie dem Speicher asynchron 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,
)
import asyncio
asyncio.run(client.add_agent_async(
    "a1",
    "Support assistant",
    metadata={"source": "catalog"},
))
'a1'

Methode add_image

Fügen Sie dem Client einen Bilddatensatz hinzu.

Beispiele

image_id = client.add_image(
    b"image-bytes",
    description="Image description",
    mime_type=ImageMimeType.PNG,
    image_id="img-1",
    user_id="user-1",
)
image_id
'img-1'

Methode add_image_async (asynchron)

Behalten Sie ein Standalone-Abbild über den konfigurierten Speicher bei.

Wenn description weggelassen wird oder None, generiert das konfigurierte LLM einen Titel.

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 asynchron einen Speicher im Speichersystem hinzu.

Beispiele

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

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 add_user_async (asynchron)

Fügen Sie dem Speicher asynchron 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,
)
import asyncio
asyncio.run(client.add_user_async(
    "u1",
    "Prefers concise answers.",
    metadata={"source": "crm"},
))
'u1'

Methode close

Schließen Sie die Agent-Speicherkomponente.

Beim Schließen werden keine neuen Hintergrundarbeiten akzeptiert, einschließlich Speicherextraktion und Generierung von Bildbeschreibungen, und es wird gewartet, bis die ausstehenden Arbeiten bis zum konfigurierten Timeout abgeschlossen sind. Wenn dieser Timeout abläuft, gibt close() auch dann zurück, wenn einige Arbeiten 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 Hintergrundarbeit noch ausgeführt wird.

Beispiele

import asyncio
asyncio.run(client.close_async())

Methode create_thread

Erstellen und Registrieren eines Threads.

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 create_thread_async (asynchron)

Thread asynchron erstellen und registrieren

Beispiele

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

Methode delete_agent

Agent-Profildatensatz nach ID löschen.

Hinweise

Vor dem Löschen des Profils wartet diese Methode bis zu 300 Sekunden auf eine frühere Hintergrundextraktion, die bereits für eigene Threads akzeptiert wurde, die über diese Agent-Speicherkomponente bekannt sind. Dieses Warten gilt, ob die kaskadierende Bereinigung aktiviert ist oder nicht. Kaskadierende Bereinigung wird im Backing Store als ein Vorgang geplant und ausgeführt. Die Methode wartet nicht auf angenommene Arbeit, nachdem die Wartezeit beginnt oder die Arbeit 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_agent_async (asynchron)

Agent-Profildatensatz asynchron nach ID löschen.

Hinweise

Diese Methode folgt dem von delete_agent() dokumentierten Warte- und Nebenläufigkeitsverhalten der Hintergrundextraktion.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_agent_async("a-delete", "Support assistant"))
'a-delete'
asyncio.run(client.delete_agent_async("a-delete"))
1

Methode delete_image

Bilddatensatz nach Kennung löschen.

Methode delete_image_async (asynchron)

Löschen Sie ein eigenständiges Bild über den konfigurierten Speicher.

Methode delete_memory

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

Hinweise

Vor dem Löschen eines Thread-bezogenen Datensatzes löst diese Methode den gespeicherten Thread auf und wartet auf eine frühere Hintergrundextraktion, die über diese Agent-Speicherkomponente akzeptiert wurde. Es wartet nicht auf nicht verwandte Threads, wird nach Beginn des Wait-Ereignisses angenommen oder wird von einer anderen Agent-Speicherkomponente oder einem anderen Agent-Prozess gestartet. Datensätze ohne Thread-Geltungsbereich und unbekannte IDs verursachen keine Extraktionswartezeit.

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)

Einen speicherähnlichen Datensatz asynchron löschen.

Hinweise

Diese Methode folgt dem gezielten Warte- und Nebenläufigkeitsverhalten der Hintergrundextraktion, das von delete_memory() dokumentiert wurde.

Beispiele

import asyncio
memory_id = asyncio.run(client.add_memory_async(
    "Temporary memory", memory_id="mem-delete"
))
asyncio.run(client.delete_memory_async(memory_id))
1

Relation nach ID oder vollständigem Endpunkttupel löschen.

Wenn kein relation_id angegeben wird, geben Sie jedes Quell-, Ziel-, Typ- und Relation-Label-Argument in der gespeicherten Quell-zu-Ziel-Ausrichtung an.

Beispiele

client.delete_record_link(relation_id="relation-id")
1

Relation nach ID oder vollständigem Endpunkt-Tupel asynchron löschen.

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_thread_async (asynchron)

Löschen Sie alle Datensätze, die einer Thread-ID zugeordnet sind, asynchron.

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,
)
import asyncio
thread = asyncio.run(client.create_thread_async(thread_id="c-delete"))
asyncio.run(client.delete_thread_async(thread.thread_id))
1

Methode delete_user

Benutzerprofildatensatz nach ID löschen.

Hinweise

Vor dem Löschen des Profils wartet diese Methode bis zu 300 Sekunden auf eine frühere Hintergrundextraktion, die bereits für eigene Threads akzeptiert wurde, die über diese Agent-Speicherkomponente bekannt sind. Dieses Warten gilt, ob die kaskadierende Bereinigung aktiviert ist oder nicht. Kaskadierende Bereinigung wird im Backing Store als ein Vorgang geplant und ausgeführt. Die Methode wartet nicht auf angenommene Arbeit, nachdem die Wartezeit beginnt oder die Arbeit 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 delete_user_async (asynchron)

Löschen Sie einen Benutzerprofildatensatz asynchron nach ID.

Hinweise

Diese Methode folgt dem von delete_user() dokumentierten Warte- und Nebenläufigkeitsverhalten der Hintergrundextraktion.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_user_async("u-delete", "Prefers concise answers."))
'u-delete'
asyncio.run(client.delete_user_async("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="c2", user_id="u1")
loaded = client.get_thread("c2")
loaded.user_id
'u1'

Methode get_thread_async (asynchron)

Ruft einen zuvor erstellten Thread asynchron 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,
)
import asyncio
created = asyncio.run(client.create_thread_async(
    thread_id="c2", user_id="u1"
))
loaded = asyncio.run(client.get_thread_async("c2"))
loaded.user_id
'u1'

Erstellen Sie eine gerichtete Beziehung zwischen zwei gespeicherten Datensätzen.

Derzeit müssen beide Endpunkte speicherähnliche Datensätze sein: "memory", "fact", "guideline" oder "preference". Integrierte Relationstypen sind "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") und "duplicates". "contradicts" und "duplicates" verwenden dasselbe Label umgekehrt.

Für ein Endpunktpaar kann nur eine Ausrichtung gespeichert werden. opposite_relation_type benennt die Beziehung beim Durchlaufen von Ziel zu Quelle. Beispiel: Wenn new "supersedes" old, ist der Reverse Traversal old "is_superseded_by" new.

Beispiele

client.link_records(
    "fact-1", "fact", "memory-1", "memory", "supports"
)
'relation-id'

Erstellen Sie asynchron eine typisierte Beziehung zwischen gespeicherten Datensätzen.

Derzeit müssen beide Endpunkte speicherähnliche Datensätze sein: "memory", "fact", "guideline" oder "preference". Integrierte Relationstypen sind "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") und "duplicates". "contradicts" und "duplicates" verwenden dasselbe Label umgekehrt.

Methode list_agents

Persistierte Agent-Profildatensätze auflisten.

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'
[record.id for record in client.list_agents(metadata_filter={"source": "catalog"})]
['a1']

Methode list_agents_async (asynchron)

Persistente Agent-Profildatensätze asynchron auflisten.

Beispiele

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_agent_async(
        "a1",
        "Support assistant",
        metadata={"source": "catalog"},
    )
    records = await client.list_agents_async(metadata_filter={"source": "catalog"})
    return [record.id for record in records]
anyio.run(main)
['a1']

Methode list_images

Permanente Standalone-Bilddatensätze auflisten.

Beispiele

images = client.list_images(user_id="u1", limit=10)
[image.id for image in images]
['img-1']

Methode list_images_async (asynchron)

Permanente Standalone-Imagedatensätze asynchron auflisten.

Beispiele

images = await client.list_images_async(
    user_id="u1",
    limit=10,
)
[image.id for image in images]
['img-1']

Methode list_memories

Permanente speicherähnliche Datensätze auflisten.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_memory("User likes pizza.", user_id="u1", memory_id="mem-1")
'mem-1'
[record.id for record in client.list_memories(user_id="u1", limit=10)]
['mem-1']

Methode list_memories_async (asynchron)

Persistente speicherähnliche Datensätze asynchron auflisten.

Beispiele

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_memory_async("User likes pizza.", user_id="u1", memory_id="mem-1")
    records = await client.list_memories_async(user_id="u1", limit=10)
    return [record.id for record in records]
anyio.run(main)
['mem-1']

Methode list_messages

Datensätze für persistente Chatnachrichten auflisten.

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")
message_id = thread.add_messages([{"role": "user", "content": "Hello"}])[0]
[record.id for record in client.list_messages(thread_id="c1", limit=10)] == [message_id]
True

Methode list_messages_async (asynchron)

Datensätze für persistente Chatnachrichten asynchron auflisten.

Beispiele

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    thread = await client.create_thread_async(thread_id="c1", user_id="u1")
    message_ids = await thread.add_messages_async(
        [{"role": "user", "content": "Hello"}]
    )
    records = await client.list_messages_async(thread_id="c1", limit=10)
    return [record.id for record in records] == message_ids
anyio.run(main)
True

Methode list_threads

Permanente Konversationsthreads auflisten.

Beispiele

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.create_thread(thread_id="c1", user_id="u1").thread_id
'c1'
[record.thread_id for record in client.list_threads(user_id="u1", limit=10)]
['c1']

Methode list_threads_async (asynchron)

Permanente Unterhaltungsthreads asynchron auflisten.

Beispiele

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.create_thread_async(thread_id="c1", user_id="u1")
    records = await client.list_threads_async(user_id="u1", limit=10)
    return [record.thread_id for record in records]
anyio.run(main)
['c1']

Methode list_users

Permanente Benutzerprofildatensätze auflisten.

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'
[record.id for record in client.list_users(metadata_filter={"source": "crm"})]
['u1']

Methode list_users_async (asynchron)

Permanente Benutzerprofildatensätze asynchron auflisten.

Beispiele

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_user_async(
        "u1",
        "Prefers concise answers.",
        metadata={"source": "crm"},
    )
    records = await client.list_users_async(metadata_filter={"source": "crm"})
    return [record.id for record in records]
anyio.run(main)
['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_image

Einen gespeicherten Bilddatensatz nach Kennung aktualisieren.

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_image_async (asynchron)

Aktualisieren Sie ein Standalone-Image über den konfigurierten Speicher.

Lassen Sie image weg, um die vorhandenen Byte beizubehalten. Wenn image angegeben wird, muss mime_type damit angegeben werden. Lassen Sie description weg, um die vorhandene Beschreibung beizubehalten. Übergeben Sie None, um eine neue Beschreibung mit dem konfigurierten LLM zu generieren. Eine Beschreibung, die nicht Null ist, ersetzt sie direkt. Metadaten, Zeitstempel und Ablaufeinstellungen werden aktualisiert, wenn sie angegeben werden.

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 ID.

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.

Beispiele

import asyncio
memory_id = asyncio.run(client.add_memory_async("Original memory"))
(
    asyncio.run(client.update_memory_async(
        memory_id, content="Updated memory"
    ))
    == memory_id
)
True

Veränderbare Felder einer gespeicherten Beziehung aktualisieren

Ausgelassene Werte werden beibehalten. Wenn relation_type zu einem integrierten Speicherbeziehungstyp wechselt, ersetzt das feste Reverse Label opposite_relation_type. Übergeben Sie None für timestamp oder metadata, um diesen Wert zu löschen.

Beispiele

client.update_record_link("relation-id", relation_type="supports")
1

Eine gespeicherte Beziehung asynchron aktualisieren.

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 update_thread_async (asynchron)

Aktualisierte Threadmetadaten und dauerhafte Laufzeitkonfiguration asynchron beibehalten.

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

import asyncio
asyncio.run(client.wait_for_memory_extraction_async(timeout=10))

Grenzwerte für Bildeingabe

Klasse oracleagentmemory.core.ImageInputLimitConfig

Basis: object

Konfigurieren Sie Grenzwerte für Raw-Images und LLM-Imageanforderungen.

Ausgelassene Felder übernehmen den nächsten größeren Konfigurationsbereich. Clientfelder übernehmen SDK-Standardwerte, während Felder pro Thread die Clientkonfiguration erben. Die Validierung kann nicht deaktiviert werden, und die aufgelösten Werte dürfen die absolute Maxima des SDK nicht überschreiten.

Beispiele

from oracleagentmemory.core import ImageInputLimitConfig
config = ImageInputLimitConfig(
    max_raw_image_bytes=16 * 1024 * 1024,
    max_images_per_llm_request=200,
)

Speicherextraktion

Klasse oracleagentmemory.core.MemoryExtractionImageContext

Basis: str, Enum

Wählen Sie aus, wie Bilder an der automatischen Speicherextraktion teilnehmen.

Deaktiviert lässt Bilder und Bildbeschreibungen aus Extraktions-Prompts aus. IMAGE sendet Originalbildteile. CAPTION sendet Bildbeschreibungen als Text und erfordert, dass jedes ausgewählte Bild eine nicht leere Beschreibung enthält.

CAPTION = 'CAPTION'

Fügen Sie Beschreibungen als Text ein, und benötigen Sie für jedes ausgewählte Bild eine Beschreibung.

Deaktiviert = 'DISABLED'

Nehmen Sie keine Bilder oder Bildbeschreibungen in Extraktions-Prompts auf.

BILD = 'IMAGE'

Originalbildteile in Extraktions-Prompts aufnehmen.

MEMORY = "Arbeitsspeicher"

Die bildspezifische Speicherextraktion wird derzeit nicht unterstützt.

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. extraction_mode und die Einstellungen der Hintergrundwarteschlange steuern auch die automatische Generierung von Bildbeschreibungen. Jedes Feld wird unabhängig berechnet. Ein für einen Vorgang angegebener Wert hat Vorrang, gefolgt von einem gespeicherten Threadwert, dem Clientwert und dem SDK-Standardwert. Neue und eigenständige Threads haben keinen gespeicherten Thread-Wert.

Beispiele

from oracleagentmemory.core import (
    MemoryExtractionImageContext,
    MemoryExtractionConfig,
    MemoryExtractionMode,
    MemoryLinkExtractionMode,
)
config = MemoryExtractionConfig(
    extract_memories=True,
    memory_extraction_image_context=MemoryExtractionImageContext.CAPTION,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
    memory_link_extraction_mode=MemoryLinkExtractionMode.POST_EXTRACTION,
    memory_link_extraction_token_limit=8_000,
)

Was zu tun ist, wenn Extraktion oder Bildbeschreibungen nicht sofort in die Warteschlange gestellt werden können.

Ausgelassene Werte werden in DROP aufgelöst.

Maximale Anzahl Sekunden, die Hintergrundarbeit im Wartemodus auf Warteschlangenkapazität wartet.

Ausgelassene Werte werden in 300.0 Sekunden aufgelöst.

Meldungen nach der letzten gültigen Übersicht vor der automatischen Aktualisierung.

Werte kleiner/gleich 0 Refresh bei jeder Prüfung.

Gibt an, ob OAM Kontextübersichten für Thread-Lese- und Extraktions-Prompts verwaltet.

Ob Extraktion und Bildbeschreibungen inline oder im Hintergrund ausgeführt werden.

Ausgelassene Werte werden in BACKGROUND aufgelöst.

Nachrichten zwischen Extraktionsausführungen; Werte unter 0-Extrakt nach jedem Anhängen.

Bilddarstellung; Auslassung wird in Thread, Client und dann DISABLED aufgelöst.

Metadaten der Quellnachricht in extrahierte Speicher kopiert.

Eingabe-Tokenbudget für Prompts; Werte unter 1 deaktivieren das Limit.

Fenster "Letzte Nachricht" für Extraktions-Prompts. -1 verwendet nur neue Nachrichten.

Optionale Anruferanweisungen, die an Prompts zur automatischen Linkauflösung angehängt werden.

Wie automatische Links für extrahierte Speicher aufgelöst werden.

Ausgelassene Werte werden in POST_EXTRACTION aufgelöst.

Gesamtbudget für Eingabe-Token für POST_EXTRACTION-Linkauflösung.

Werte unter 1 deaktivieren den Grenzwert.

Klasse oracleagentmemory.core.MemoryExtractionMode

Basis: str, Enum

Steuert, wann automatische Extraktion und Bildbeschreibungen ausgeführt werden.

INLINE schließt abgeleitete Arbeit ab, bevor die Schreibmethode zurückgegeben wird. BACKGROUND gibt zurück, nachdem der Raw-Schreibvorgang erfolgreich war, und versucht, diese Arbeit in eine Queue zu stellen. Hintergrundarbeit ist der beste Aufwand: Generierte Beschreibungen und abgeleitete Erinnerungen können später erscheinen oder nie geschrieben werden, wenn sie nicht abgeschlossen werden können.

HINTERGRUND = 'HINTERGRUND'

Geben Sie nach dem Raw-Schreibvorgang zurück, und führen Sie abgeleitete Arbeit im Hintergrund aus.

INLINE = 'INLINE'

Komplette Extraktion und Bildbeschreibungen vor der Rückgabe des Schreibvorgangs.

Klasse oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

Basis: str, Enum

Steuert, was geschieht, wenn konfigurierte Hintergrundarbeit nicht rechtzeitig in eine Warteschlange gestellt werden kann.

Trotz des extraktionsspezifischen Namens gilt diese Einstellung auch für die automatische Bildbeschreibungsgenerierung im Hintergrundmodus.

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.