Speicher und Schema

Auf dieser Seite werden die Core-Speicherabstraktionen und Schemakontrollen angezeigt, die vom Oracle Agent-Speicher-SDK verwendet werden.

Shop-API

Schreibsemantik speichern

Beim Speichern von Schreibvorgängen wird eine klare Trennung zwischen dem Text, den eine Anwendung speichert, und der Payload, die der Speicher zum Abrufen verwendet, beibehalten. Die meisten Anwendungen können die APIs auf Speicherebene und Thread-Ebene verwenden und den Speicher die benötigten Suchzeilen für den Vektor-, Schlüsselwort- oder Hybridabruf vorbereiten lassen. Die Speicher-APIs der unteren Ebene stellen index_texts, index_text, embeddings und embedding für erweiterte Integrationen bereit, die bereits wissen, welcher Text oder welche Vektoren zum Abrufen verwendet werden sollen.

Denken Sie an jedes Schreiben als zwei verwandte Stücke:

• contents in add() und text in update() steuern den gespeicherten Datensatztext, der von get(), list() und Suchergebnissen zurückgegeben wird.
• index_texts in add() und index_text in update() steuern den Text, der in die Abrufzeilen des Speichers geschrieben wird. Die Suche verwendet diese Zeilen und gibt dann die ursprünglichen logischen Datensätze zurück.

Wenn keine Suchüberschreibung oder explizite Einbettung angegeben wird, verwendet der Speicher den aufgelösten gespeicherten Text als Abruftext. Bei der Konfiguration von Chunking wird nicht leerer Text vom Speicher als Chunking-Block verarbeitet. Leerer Text speichert den Datensatztext, liefert jedoch keinen Abruftext.

In der folgenden Tabelle wird beschrieben, wie Abruftext ausgewählt wird, bevor explizite Vektor-Payloads berücksichtigt werden.

Abruf-Payloads auf Filialebene

Eingabe	add()	update()
index_texts oder index_text ausgelassen	Jeder Datensatz verwendet den aufgelösten contents-Wert für den Abruf.	Für den Abruf wird ein Ersatzwert text verwendet. Wenn auch text ausgelassen wird, verwenden Nur-Einbetten-Aktualisierungen die vorhandenen Abruftextzeilen des Datensatzes wieder.
Zeichenfolge index_texts-Eintrag oder Zeichenfolge index_text	Die Zeichenfolge ersetzt den Abruftext für diesen Datensatz. Der Speicher kann einen Chunk-Vorgang ausführen, bevor Abrufzeilen geschrieben werden.	Die Zeichenfolge ersetzt den Abruftext für diesen Datensatz. Der Speicher kann einen Chunk-Vorgang ausführen, bevor Abrufzeilen geschrieben werden.
list[str] index_texts-Eintrag oder list[str] index_text	Die Liste wird als Chunks im Besitz des Anrufers behandelt. Jede nicht leere Zeichenfolge wird als eine Abrufzeile geschrieben, und der Speicher blockiert sie nicht erneut.	Die Liste wird als Chunks im Besitz des Anrufers behandelt. Jede nicht leere Zeichenfolge wird als eine Abrufzeile geschrieben, und der Speicher blockiert sie nicht erneut.
None index_texts-Eintrag oder index_text=None	None in der äußeren Liste index_texts bedeutet "den gespeicherten Inhalt für diesen Datensatz verwenden".	index_text=None löscht die Abrufzeilen, während der gespeicherte Text unverändert bleibt, es sei denn, text wird ebenfalls angegeben.
Leere Zeichenfolge oder leere Chunk-Liste	Speichert den Datensatztext und stellt keinen Abruftext für diesen Datensatz bereit.	Aktualisiert den Datensatztext, wenn text angegeben wird, und löscht den Abruftext für diesen Datensatz.

Explizite Einbettungen sind optional. Wenn sie ausgelassen werden, leitet der Speicher lokale Vektoren aus dem Abruftext ab, wenn der lokale Vektorspeicher konfiguriert ist. Schlüsselwort- oder Hybridspeicher können auch Nur-Text-Abrufzeilen verwenden. Wenn explizite embeddings- oder embedding-Werte angegeben werden, schreibt der Speicher diese Vektoren direkt und ruft den Embedder für diese Vektoren nicht auf.

In add() verhält sich embeddings=None wie das Weglassen von embeddings. In update() ist embedding=None explizit: Der Speicher speichert oder schreibt den Abruftext gemäß text und index_text neu, speichert diese Zeilen jedoch ohne lokale Vektoren. Wenn text und index_text beide ausgelassen werden, werden Vektoren aus den vorhandenen Abrufzeilen gelöscht.

Die Vektorform gibt dem Speicher an, wie viel Chunk-Eigentum der Anrufer nimmt:

• Ein Vektor bedeutet einen Vektor für den gesamten Abruftext. Der Speicher teilt diesen Text nicht für den expliziten Vektor auf. Wenn dieser Abruftext leer ist, kann der Vektor ohne Begleittext gespeichert werden.
• Mehrere Vektoren bedeuten einen Vektor pro aufrufendem Chunk. Geben Sie übereinstimmende index_texts- oder index_text-Chunk-Listen an, oder verwenden Sie eine Nur-Einbettung-update(), mit der die vorhandenen Abruftextzeilen des Datensatzes wiederverwendet werden.
• Die Vektoranzahl muss mit der Chunkanzahl übereinstimmen, und alle expliziten Vektoren in einem add()-Aufruf müssen dieselbe Dimension aufweisen.
• Eine leere Vektor-Payload pro Datensatz ist nur zulässig, wenn keine Abruftextzeilen vorhanden sind, die mit ihr ausgerichtet werden können.

Einige Kombinationen werden abgelehnt, sodass gespeicherter Text, Abruftext und Vektoren nicht auseinanderdriften. Durch die Übergabe von text=None werden gespeicherte Text- und Abrufzeilen gelöscht, sodass sie nicht mit Werten kombiniert werden können, die nicht Null sind: index_text oder embedding; Akteurprofildatensätze unterstützen text=None nicht. Die Übergabe von index_text=None in update() bedeutet "Abrufzeilen löschen", sodass nicht leere explizite Einbettungen im selben Aufruf nicht zulässig sind. Mehrere explizite Vektoren erfordern expliziten Chunk-Text, es sei denn, die Aktualisierung wird nur eingebettet, und die vorhandenen Abrufzeilen stellen bereits den Chunk-Text bereit.

Klasse oracleagentmemory.core.OracleMemoryStore

Basen: IMemoryStore

Gemeinsame Speicherschnittstelle, die von OracleAgentMemory verwendet wird.

Eine Store-Implementierung ist dafür verantwortlich, Text-Records zu persistieren und Ähnlichkeitssuchen durchzuführen. Sowohl synchrone als auch asynchrone Einstiegspunkte werden definiert, sodass APIs auf höherer Ebene übereinstimmende Synchronisierungs-/asynchrone Oberflächen bereitstellen können, ohne dass eine speicherspezifische Logik dupliziert wird.

Methode add

Datensätze zur Filiale hinzufügen

• Parameter:
  • contents list[str | None]: Zeichnet Payloads auf, die dauerhaft gespeichert werden sollen. Textwerte werden auch für die semantische Indexierung verwendet, es sei denn, index_texts oder embeddings sind angegeben. Wenn ein Textwert None ist, können Implementierungen auf metadata["content"] zurückgreifen. Explizite leere Zeichenfolgen werden beibehalten.
  • record_type str: Zu erstellender logischer Datensatztyp, z.B. "message", "memory", "guideline", "fact", "preference", "user_profile" oder "agent_profile".
  • index_texts list[str | list[str] | None] – Optionale alternative Payloads, die nur für die semantische Indexierung verwendet werden. Wenn angegeben, muss die äußere Liste mit den Texteingaben übereinstimmen. Jeder Eintrag kann eine Zeichenfolge sein, die der Speicher intern chunkieren kann, oder eine Liste von nicht leeren Zeichenfolgen, die der Speicher als Chunks behandelt, die sich im Besitz des Aufrufers befinden, und nicht erneut aufteilen darf.
  • Einbettungen list[list[float] | ndarray | list[list[float] | ndarray]] – Optionale vorab berechnete Einbettungsvektoren, die an den Texteingaben ausgerichtet sind. Jeder Datensatzeintrag kann entweder ein Einbettungsvektor oder eine Liste von Chunk-Einbettungsvektoren für diesen Datensatz sein. Wenn angegeben, muss der Speicher diese Vektoren direkt verwenden, anstatt dessen Einbettung aufzurufen. Mehrere Vektoren für einen Datensatz erfordern übereinstimmende index_texts-Chunk-Listen, sodass Text- und Vektor-Chunk-Grenzen explizit sind. Falls nicht angegeben, leiten Speicher in der Regel den semantischen Status von ihrem konfigurierten Einbettungsmodus ab. Implementierungsspezifische textbezogene Indexierungsmodi können jedoch auch Schreibvorgänge ohne Text zulassen.
  • record_ids str | None | list[str | None] – Optionale durch Aufrufer sichtbare IDs. Eine einzelne Zeichenfolge kann für Ein-Datensatz-Einfügungen verwendet werden, während Listen mit den Texteingaben übereinstimmen müssen. Generierte Kennungen werden zurückgegeben, wenn dieses Feld ausgelassen wird.
  • thread_ids str | None | list[str | None] – Optionale Thread-IDs, die den eingefügten Datensätzen zugeordnet sind. Skalare Werte können über ausgerichtete Texteingaben übertragen werden.
  • user_ids str | None | list[str | None] – Optionale Benutzer-IDs, die den eingefügten Datensätzen zugeordnet sind. Skalare Werte können über ausgerichtete Texteingaben übertragen werden.
  • agent_ids str | None | list[str | None] – Optionale Agent-IDs, die den eingefügten Datensätzen zugeordnet sind. Skalare Werte können über ausgerichtete Texteingaben übertragen werden.
  • Rollen str | None | list[str | None] – Optionale Nachrichtenrollen, wie "user" oder "assistant". Skalare Werte können über ausgerichtete Texteingaben übertragen werden. Wird nur verwendet, wenn record_type "message" ist.
  • Zeitstempel str | None | list[str | None] – Optionale Zeitstempel zum Speichern mit den Datensätzen. Jeder Zeitstempel gibt an, wann der Datensatz erstellt wurde. Skalare Werte können über ausgerichtete Texteingaben übertragen werden. Ausgelassene oder None-Einträge verwenden die aktuelle Uhrzeit.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None] – Optionale Metadatenwörterbücher, die vom Aufrufer bereitgestellt werden. Metadaten können "content" als Fallback-Quelle enthalten, wenn ein Textwert ausgelassen und nicht explizit auf "" gesetzt wird.
  • ttl_days int | None | list[int | None]: Optionale Gültigkeitsdauer in Tagen für Datensätze, die den Ablauf unterstützen. Lassen Sie dieses Argument aus, um den Speicherstandard zu verwenden. Übergeben Sie None für Datensätze, die nicht ablaufen dürfen. Skalare Werte können über ausgerichtete Texteingaben übertragen werden.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor] – Optionaler Time-to-Live-Anker. Verwenden Sie TimeToLiveAnchor.CREATED_AT, um relativ zur gespeicherten Erstellungszeit abzulaufen, oder TimeToLiveAnchor.TIMESTAMP, um relativ zum Ereigniszeitstempel jedes Datensatzes abzulaufen. Wenn diese Option ausgelassen wird, verwenden Implementierungen TimeToLiveAnchor.CREATED_AT.
  • **store_kwargs (Beliebig) – Implementierungsspezifische Schreiboptionen, die an den konkreten Speicher weitergeleitet werden.
• Rückgabetyp: list[str]

Hinweise

Verwenden Sie add_batches(), wenn der Aufrufer bereits mindestens ein PendingRecordBatch-Objekt enthält.

• Rücksendungen: IDs für die eingefügten Datensätze in derselben logischen Reihenfolge wie die Eingabe.
• Rückgabetyp: Liste[str]
• Parameter:
  • Inhalte list[str | None]
  • record_type str
  • index_texts list[str | list[str] | None]
  • Einbettungen list[list[float] | ndarray | list[list[float] | ndarray]]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • Rollen str | None | list[str | None]
  • Zeitstempel str | None | list[str | None]
  • Metadaten dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • store_kwargs Any

Methode add_agent (Übung)

Agent-Profildatensatz hinzufügen.

• Parameter:
  • agent_id str: Stabile ID für das Agent-Profil.
  • Informationen str – Freiformtext, der den Agent beschreibt.
  • metadata dict[str, Any] | None – Optionale Metadatenzuordnung, die in der Agent-Profilzeile gespeichert ist.
• Retouren: ID des erstellten Agent-Profildatensatzes.
• Rückgabetyp: str

Methode add_async (asynchron)

Fügen Sie dem Speicher asynchron zeilenorientierte Datensätze hinzu.

Akzeptiert dieselben Argumente und gibt dieselben IDs wie add() zurück.

• Parameter:
  • Inhalte list[str | None]
  • record_type str
  • index_texts list[str | list[str] | None]
  • Einbettungen list[list[float] | ndarray | list[list[float] | ndarray]]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • Rollen str | None | list[str | None]
  • Zeitstempel str | None | list[str | None]
  • Metadaten dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • store_kwargs Any
• Rückgabetyp: list[str]

Methode add_batches

Fügen Sie dem Speicher vom Aufrufer vorbereitete logische Batches hinzu.

• Parameter:
  • Batches list[PendingRecordBatch] – Vollständig vorbereitete logische Batches zum Persistieren. Jeder Batch muss eigene Felder pro Datensatz wie record_type, Geltungsbereichswerte, Rollen, Zeitstempel und Metadaten enthalten.
  • **store_kwargs (Beliebig) – Implementierungsspezifische Schreiboptionen, die an den konkreten Speicher weitergeleitet werden.
• Rückgaben: IDs für die eingefügten Datensätze in derselben logischen Reihenfolge wie die Eingabebatches und -zeilen.
• Rückgabetyp: Liste[str]

Beispiele

store.add_batches(
    [
        PendingRecordBatch(
            texts=["pizza batch"],
            record_type="memory",
            record_ids="mem-batch-docs",
        )
    ]
)
['mem-batch-docs']

Methode add_batches_async (asynchron)

Fügen Sie dem Speicher asynchron vom Aufrufer vorbereitete logische Batches hinzu.

Akzeptiert dieselben Argumente und gibt dieselben IDs wie add_batches() zurück.

• Parameter:
  • Batches list[PendingRecordBatch]
  • store_kwargs Any
• Rückgabetyp: list[str]

Methode add_user (Übung)

Benutzerprofildatensatz hinzufügen

• Parameter:
  • user_id str: Stabile ID für das Benutzerprofil.
  • Informationen str – Freiformtext, der den Benutzer beschreibt.
  • metadata dict[str, Any] | None – Optionale Metadatenzuordnung, die in der Benutzerprofilzeile gespeichert ist.
• Rücksendungen: ID des erstellten Benutzerprofildatensatzes.
• Rückgabetyp: str

Methode delete (Übung)

Löschen Sie einen gespeicherten Datensatz nach ID.

• Parameter:
  • record_type str: Logischer Typ des zu entfernenden Datensatzes.
  • record_id str: ID des zu entfernenden Datensatzes.
  • cascade bool – Wenn True, wenden Sie jedes vom Speicher unterstützte kaskadierende Löschverhalten für die angeforderten Ziele der obersten Ebene innerhalb desselben Löschvorgangs an. Dies wird hauptsächlich für Ziele wie Schauspielerprofile verwendet, die über weitere Datensätze mit Geltungsbereich verfügen. Beispiel: Eine Benutzerprofil- oder Agent-Profilkaskade kann eigene Threads selbst löschen, Nachrichten mit Thread-Geltungsbereich und speicherähnliche Datensätze, die mit diesen Threads entfernt wurden, sowie alle verbleibenden direkt Akteur-Geltungsdatensätze, wie Nachrichten, Speicher, Richtlinien, Fakten oder Voreinstellungen. Bei Löschvorgängen mit Akteurprofilen wird diese Bereichsbereinigung möglicherweise noch ausgeführt, wenn die entsprechende Profilzeile bereits fehlt.
• Rücksendungen: Anzahl der angeforderten Datensätze der obersten Ebene, die gelöscht wurden, in der Regel 0 oder 1. Kaskadierte untergeordnete Zeilen werden nicht separat gezählt. Daher kann dies immer noch 0 sein, wenn ein fehlendes Akteurprofil eine bereichsbezogene Bereinigung auslöst.
• Rückgabetyp: int

Methode delete_thread (Übung)

Thread und die zugehörigen gespeicherten Daten löschen

• Parameter: thread_id str – ID des zu entfernenden Threads.
• Rückgaben: Anzahl der gelöschten Threaddatensätze, in der Regel 0 oder 1.
• Rückgabetyp: int

Hinweise

Dies ist der Vorgang auf Speicherebene zum Entfernen eines Threads und der vom Speicher verwalteten Datensätze mit Threadbereich. Threadlöschung bevorzugen, wenn Aufbewahrungsanforderungen das Löschen von Quellnachrichten und abgeleiteten Speicherdaten mit Threadbereich erfordern, da Löschvorgänge auf Nachrichtenebene nicht bedeuten, dass separat persistente abgeleitete Datensätze entfernt werden.

Methode get (Übung)

Rufen Sie einen gespeicherten Datensatz nach Typ und ID ab.

• Parameter:
  • record_type str: Logischer Typ des abzurufenden Datensatzes.
  • record_id str: ID des abzurufenden Datensatzes.
• Rücksendungen: Der gespeicherte Datensatz, wenn er gefunden wird. Andernfalls wird None verwendet.
• Rückgabetyp: Datensatz | Keine

Methode list (Übung)

Listet gespeicherte Datensätze für einen Datensatztyp auf.

• Parameter:
  • record_type str: Logischer Datensatztyp, der aufgezählt werden soll.
  • limit int | None – Optionale maximale Anzahl der zuletzt zurückgegebenen Datensätze. Wenn diese Option ausgelassen wird, können Implementierungen einen sicheren oberen Grenzwert wie MAX_LIST_LIMIT anwenden. Übergeben Sie None, um diese Memory Cap zu deaktivieren und jeden übereinstimmenden Datensatz zurückzugeben.
  • thread_id str | None – Exakter Thread-Geltungsbereichsfilter. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert auf None gesetzt ist, werden nur Datensätze zurückgegeben, deren thread_id None ist. Nicht kopierte Datensatztypen ignorieren diesen Filter.
  • user_id str | None: Exakter Filter für den Benutzerumfang. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert auf None gesetzt ist, werden nur Datensätze zurückgegeben, deren user_id None ist. Nicht kopierte Datensatztypen ignorieren diesen Filter.
  • agent_id str | None: Exakter Agent-Geltungsbereichsfilter. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert auf None gesetzt ist, werden nur Datensätze zurückgegeben, deren agent_id None ist. Nicht kopierte Datensatztypen ignorieren diesen Filter.

  • metadata_filter dict[str, Any] | None –

    Metadatenfilter. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert auf None gesetzt ist, werden nur Datensätze zurückgegeben, deren Metadaten None sind. Wenn dies auf ein Diktat gesetzt ist, werden Einträge in metadata_filter mit AND-Semantik kombiniert. Einträge, deren Wert kein Operatordictionary auf Feldebene ist, verwenden eine genaue Übereinstimmungssemantik: Der angeforderte Schlüssel muss in den gespeicherten Metadaten vorhanden sein. Verschachtelte Wörterbücher werden rekursiv abgeglichen. Skalare und Listenwerte werden durch exakte Gleichheit abgeglichen; Listenreihenfolge und -länge müssen ebenfalls übereinstimmen. Um die Arraymitgliedschaft zu testen, verwenden Sie ein Operatordictionary auf Feldebene, wie {"tags": {"$array_contains": "prod"}}. Ein Listenoperand für "$array_contains" bedeutet, dass alle aufgelisteten Werte vorhanden sein müssen. "$array_contains_any" bedeutet, dass mindestens ein aufgelisteter Wert vorhanden sein muss. Verwenden Sie "$not", um einen anderen Ausdruck auf Feldebene in demselben Feld zu negieren, einschließlich eines Operator-Dictionarys oder eines Raw-Exact-Match-Wertes. Negierte Ausdrücke stimmen überein, wenn der positive Ausdruck fehlschlagen würde, einschließlich fehlender Felder; negierte Array-Mitgliedschaft stimmt auch mit Nicht-Array-Feldern überein. Beispiele: metadata_filter={"source": "slack"} für ein skalares Feld, metadata_filter={"review": {"status": "open"}} für ein verschachteltes Feld und metadata_filter={"tags": ["prod", "urgent"]} für eine genaue Listenübereinstimmung. Kombinieren Sie Bedingungen, um sie alle zu benötigen:

    metadata_filter={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    }

• Rücksendungen: Datensätze, die im zurückgegebenen Fenster von "ältesten" auf "neueste" sortiert wurden.
• Rückgabetyp: Liste[Datensatz]

Methode list_thread_messages (Übung)

Listen Sie die Nachrichtenhistorie auf, die für einen Thread gespeichert ist.

• Parameter:
  • thread_id str: ID des Threads, dessen Nachrichten zurückgegeben werden sollen.
  • last_n int | None – Optionale Anzahl der zuletzt aufzunehmenden Nachrichten. Wenn diese Option ausgelassen wird, werden alle gespeicherten Nachrichten für den Thread zurückgegeben.
• Rücksendungen: Meldungsdatensätze werden im zurückgegebenen Fenster vom ältesten zum neuesten sortiert.
• Rückgabetyp: Liste[MessageRecord]

Methode search (Übung)

Datensätze nach Ähnlichkeit suchen

• Parameter:
  • query str | None – Abfrage in natürlicher Sprache. Muss angegeben werden, wenn query_vector ausgelassen wird.
  • query_vector list[float] | None – Optionale vorberechnete Abfrageeinbettung. Es muss genau einer von query und query_vector angegeben werden.
  • k int – Maximale Anzahl von Ergebnissen, die zurückgegeben werden. Explizite Werte müssen mindestens 1 sein. Dies ist ein oberer Grenzwert: Der Aufruf gibt möglicherweise weniger als k-Ergebnisse zurück, wenn Filter zu restriktiv sind, wenn weniger nicht abgelaufene übereinstimmende Datensätze vorhanden sind oder das implementierungsspezifische Suchverhalten vorliegt.
  • thread_id str | None – Optionaler Threadgeltungsbereich.
  • user_id str | None – Optionale Filter für Benutzer- und Agent-Geltungsbereich.
  • agent_id str | None: Optionale Filter für Benutzer- und Agent-Geltungsbereich.
  • exact_user_match bool: Gibt an, ob jede angegebene Geltungsbereichs-ID genau abgeglichen werden muss.
  • exact_agent_match bool: Gibt an, ob jede angegebene Geltungsbereichs-ID genau abgeglichen werden muss.
  • exact_thread_match bool: Gibt an, ob jede angegebene Geltungsbereichs-ID genau abgeglichen werden muss.
  • record_types set[str] | None – Optionale Datensatztypen, die eingeschlossen werden sollen.
  • metadata_filter dict[str, Any] | None – Optionale Metadatenfilterzuordnung. Einträge in metadata_filter werden mit AND-Semantik kombiniert. Einträge, deren Wert kein Operatordictionary auf Feldebene ist, verwenden eine genaue Übereinstimmungssemantik: Der angeforderte Schlüssel muss in den gespeicherten Metadaten vorhanden sein. Verschachtelte Wörterbücher werden rekursiv abgeglichen. Skalare und Listenwerte werden durch exakte Gleichheit abgeglichen; Listenreihenfolge und -länge müssen ebenfalls übereinstimmen. Um die Arraymitgliedschaft zu testen, verwenden Sie ein Operatordictionary auf Feldebene, wie {"tags": {"$array_contains": "prod"}}. Ein Listenoperand für "$array_contains" bedeutet, dass alle aufgelisteten Werte vorhanden sein müssen. "$array_contains_any" bedeutet, dass mindestens ein aufgelisteter Wert vorhanden sein muss. Verwenden Sie "$not", um einen anderen Ausdruck auf Feldebene in demselben Feld zu negieren, einschließlich eines Operator-Dictionarys oder eines Raw-Exact-Match-Wertes. Negierte Ausdrücke stimmen überein, wenn der positive Ausdruck fehlschlagen würde, einschließlich fehlender Felder; negierte Array-Mitgliedschaft stimmt auch mit Nicht-Array-Feldern überein.
• Rückgaben: (record, distance)-Paare nach zunehmender Entfernung sortiert. Die Liste kann weniger als k-Einträge enthalten.
• Rückgabetyp: list[tuple[Record, float]]
• Gelöst: ValueError – Wenn k kleiner als 1 ist.

Beispiele

store.add(
    ["Searchable abstract memory"],
    record_type="memory",
    record_ids="mem-search-abstract-docs",
)
['mem-search-abstract-docs']
store.search("Searchable", 1, record_types={"memory"})[0][0].id
'mem-search-abstract-docs'

Nach einem skalaren Metadatenwert filtern:

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs']
any(
    record.id == "mem-search-meta-source-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

Nach verschachtelten Metadaten filtern:

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs']
any(
    record.id == "mem-search-meta-review-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

Ordnen Sie einen Listenwert genau zu, einschließlich Reihenfolge:

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs']
any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

Filtern, wenn ein Metadaten-Array einen Wert enthält:

any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": {"$array_contains": "prod"}},
    )
)
True

Mehrere Metadatenbedingungen kombinieren Ein Datensatz muss jeden Schlüssel erfüllen:

store.add(
    ["pizza rollout"],
    record_type="memory",
    record_ids="mem-search-meta-combined-docs",
    metadata={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    },
)
['mem-search-meta-combined-docs']
any(
    record.id == "mem-search-meta-combined-docs"
    for record, _ in store.search(
        "pizza",
        k=5,
        metadata_filter={
            "source": "slack",
            "review": {"status": "open"},
            "tags": ["prod", "urgent"],
        },
    )
)
True

Methode search_async (asynchron)

Suchen Sie Datensätze asynchron nach semantischer Ähnlichkeit.

• Parameter:
  • query str | None – Gleicher Abfragetext, der von search akzeptiert wird.
  • k int – Dieselbe maximale Ergebnisanzahl, die von search akzeptiert wird. Explizite Werte müssen mindestens 1 sein.
  • query_vector list[float] | None – Dieselbe optionale vorberechnete Abfrageeinbettung wurde von search akzeptiert.
  • thread_id str | None – Dieselben optionalen Geltungsbereichsfilter werden von search akzeptiert.
  • user_id str | None – Dieselben optionalen Geltungsbereichsfilter werden von search akzeptiert.
  • agent_id str | None – Dieselben optionalen Geltungsbereichsfilter, die von search akzeptiert werden.
  • exact_user_match bool: Identische Flags mit genauer Übereinstimmung, die von search akzeptiert werden.
  • exact_agent_match bool: Identische Flags mit genauer Übereinstimmung, die von search akzeptiert werden.
  • exact_thread_match bool – Gleiche Flags mit exakter Übereinstimmung werden von search akzeptiert.
  • record_types set[str] | None: Derselbe optionale Datensatztypfilter wurde von search akzeptiert.
  • metadata_filter dict[str, Any] | None – Gleicher optionaler Metadatenfilter, der von search akzeptiert wird, einschließlich skalarer, verschachtelter, exakter Liste, Array-Mitgliedschaft und kombinierter Bedingungen wie {"source": "slack"}, {"review": {"status": "open"}}, {"tags": ["prod", "urgent"]} und {"tags": {"$array_contains": "prod"}}.
• Rückgaben: (record, distance)-Paare, die vom zugrunde liegenden search-Aufruf zurückgegeben werden.
• Rückgabetyp: Liste[tuple[Record, float]]
• Gelöst: ValueError – Wenn k kleiner als 1 ist.

Methode update (Übung)

Aktualisieren Sie gespeicherten Datensatzinhalt, betten Sie Daten, Metadaten, Zeitstempel oder Ablauf ein.

• Parameter:
  • record_type str: Logischer Typ des zu aktualisierenden Datensatzes.
  • record_id str: ID des zu aktualisierenden Datensatzes.
  • text str | None – Optionaler Ersatzinhalt. Übergeben Sie None, um den gespeicherten Text explizit zu löschen, wenn er vom Speicher unterstützt wird. Speicher können auch den zugehörigen semantischen Status löschen und widersprüchliche Aktualisierungen von index_text oder embedding, die nicht Null sind, im selben Aufruf ablehnen. Lassen Sie das Argument weg, um den Inhalt unverändert zu lassen.
  • index_text str | list[str] | None – Optionale alternative semantische Payload, mit der der gespeicherte Suchstatus neu berechnet oder ersetzt wird, ohne den persistenten Text zu ändern. Ein String kann intern vom Store gechunket werden. Eine Liste nicht leerer Zeichenfolgen wird als Chunks behandelt, die Eigentümer des Aufrufers sind, und darf nicht erneut geteilt werden. Einige Implementierungen können dies auch separat als Hybrid-Suchtext beibehalten.
  • einbetten list[float] | ndarray | list[list[float] | ndarray] | None – Optionaler vorab berechneter Einbettungsvektor oder Liste mit Chunk-Einbettungsvektoren. Wenn angegeben, wird dies direkt verwendet, und es erfolgt kein Einbettungsaufruf. Mehrere Vektoren erfordern übereinstimmende index_text-Chunk-Listen oder vorhandene gespeicherte Chunk-Textzeilen. Übergeben Sie None, um die gespeicherte Einbettung explizit zu löschen, wenn der Speicher sie unterstützt. Speicher mit textbezogener Indexierung können auch semantische Aktualisierungen ohne Einbettung oder explizite Einbettung ermöglichen.
  • metadata dict[str, Any] | None – Optionale Metadaten-Ersatzzuordnung. Übergeben Sie None, um Metadaten zu löschen, wenn der Speicher sie unterstützt.
  • timestamp str | None – Optionaler neuer Zeitstempel zum Speichern mit dem Datensatz. Es gibt an, wann der Datensatz erstellt wurde. Lassen Sie dieses Argument weg, um den gespeicherten Zeitstempel unverändert zu lassen. Übergeben Sie None, um den gespeicherten Zeitstempel zu löschen und die Zeit zu verwenden, zu der der Datensatz zum Speicher hinzugefügt wurde, wenn der Speicher ihn unterstützt.
  • ttl_days int | None – Optionale Ablaufaktualisierung in Tagen. Lassen Sie dieses Argument zusammen mit ttl_anchor aus, um den aktuellen Ablaufzeitstempel beizubehalten. Übergeben Sie None, um den Ablauf zu löschen.
  • ttl_anchor TimeToLiveAnchor – Optionaler Time-to-Live-Anker für eine Ablaufaktualisierung. Verwenden Sie TimeToLiveAnchor.CREATED_AT für die Erstellungszeit des Datensatzes oder TimeToLiveAnchor.TIMESTAMP für den Ersatz timestamp, der in derselben Aktualisierung angegeben wird, oder den gespeicherten Ereigniszeitstempel, wenn timestamp ausgelassen wird. Wenn Sie ttl_anchor ohne ttl_days angeben, wird die standardmäßige Gültigkeitsdauer des Speichers oder Schemas verwendet. Wenn ttl_anchor während einer Aktualisierung ausgelassen wird, verwenden Implementierungen TimeToLiveAnchor.CREATED_AT.
• Rückgaben: Anzahl der aktualisierten Datensätze, in der Regel 0 oder 1. Gibt 0 zurück, wenn kein gespeicherter Datensatz mit der angeforderten logischen ID übereinstimmt.
• Rückgabetyp: int
• Gelöst: ValueError – Wenn die Update-Payload für den Speicher ungültig ist, z.B. das Weglassen jedes optionalen Feldes oder das Bereitstellen widersprüchlicher semantischer Argumente.

Oracle DB-Speicher

Klasse oracleagentmemory.core.OracleDBMemoryStore

Basis: OracleMemoryStore

Datenbankgestützte Persistenz für Nachrichten, Speicher und Akteurprofile.

Oracle DB-Speicher erstellen

• Parameter:
  • embedder IEmbedder | None: Einbettung, die verwendet wird, wenn der Speicher lokale Vektoreinbettungen benötigt. Kann None sein, wenn Aufrufer immer vorab berechnete Vektoren bereitstellen oder wenn die Stichwortsuche mit Nur-Text-Schreib- und Textabfragen verwendet wird. SearchStrategy.HYBRID erfordert hier eine OracleDBEmbedder, damit der verwaltete Hybridindex das datenbankinterne Modell dieses Einbetters verwenden kann.
  • pool Any: Oracle DB-Verbindung oder -Pool. Das Übergeben einer Raw-Verbindung ermöglicht den Single-Session-Modus für diese Speicherinstanz: gleichzeitige Speicheraufrufe werden lokal serialisiert, um die von Schreibvorgängen verwendeten Zeilensperren und Transaktionsannahmen beizubehalten. Verwenden Sie einen Connection Pool für gleichzeitige Anforderungen.
  • schema_policy SchemaPolicy | str – Schemasetupmodus. Standardmäßig ist ein vorhandenes, aktuelles verwaltetes Schema erforderlich, und es werden keine DDL-Änderungen vorgenommen. Verwenden Sie SchemaPolicy.CREATE_IF_NECESSARY, um fehlende Objekte auszufüllen, oder SchemaPolicy.RECREATE, um verwaltete Objekte zu löschen und neu zu erstellen. SchemaPolicy.CREATE_IF_NECESSARY kann unterstützte Upgrades der verwalteten Schemaversion anwenden, ein Vektorschema für die Stichwortsuche aktualisieren, indem ein Textindex hinzugefügt wird, oder für eine hybride Suche, indem die verwalteten Suchstrukturen und der Hybridindex hinzugefügt werden.
  • vector_dim int | None – Optionale Einbettungsdimension für lokalen Vektorspeicher. Übergeben Sie eine positive Ganzzahl, um die verwaltete Einbettungsspalte und den Vektorindex zu erstellen und vorhandene Schemametadaten mit dieser Dimension zu validieren. Übergeben Sie None, oder lassen Sie das Argument weg, wenn dieser Speicher keinen lokalen Vektorspeicher benötigt. Stichwort- und Hybridsuche können aus gespeichertem Suchtext ohne lokale Einbettungsspalte ausgeführt werden. Die Vektorsuche erfordert einen lokalen Vektorspeicher.

  • table_name_prefix str –

    Optionales Präfix zu verwalteten Tabellen-/Indexnamen hinzugefügt. Übergeben Sie entweder diesen oder memory_store_id, nicht beides.

    Hinweis: Veraltet seit Version 26.6.0: Dieser Parameter sollte in 26.6.0 nicht mehr verwendet werden und wird in 27.1 entfernt. Verwenden Sie stattdessen memory_store_id.

  • memory_store_id str: Stabile ID für den verwalteten DB-Speicherspeicher. Verwenden Sie dieselbe ID erneut, um denselben verwalteten Speicher erneut zu öffnen. Die ID wird mit verwalteten DB-Objektnamen mit einem Unterstrich verknüpft. Daher muss sie mit einem Buchstaben beginnen, nur Buchstaben, Zahlen und Unterstriche enthalten und darf maximal 16 Zeichen enthalten. Übergeben Sie entweder diesen oder table_name_prefix, nicht beides. Wenn diese Option ausgelassen wird, verwendet der Speicher table_name_prefix oder den Standard ohne Präfix, wenn auch table_name_prefix ausgelassen wird.
  • search_strategy SearchStrategy: Wert SearchStrategy, der das Backend für search() auswählt. Verwenden Sie SearchStrategy.VECTOR (Standard) für den reinen Vektorabruf, SearchStrategy.HYBRID, um einen verwalteten Oracle-Hybridvektorindex über den gespeicherten Suchtext abzufragen, oder SearchStrategy.KEYWORD, um nach Stichwort/Textabgleich über den gespeicherten Suchtext ohne Vektorfusion zu ordnen. Für KEYWORD ist kein Embedder erforderlich. Für HYBRID muss embedder ein OracleDBEmbedder sein. Daher verwendet der verwaltete Hybridindex dasselbe datenbankinterne Modell wie der Hauptspeichereinbettungsmodus. Wenn ein Keyword-Client ein vorhandenes Hybrid-Schema öffnet, kann der Speicher die Textverzweigung dieses Hybrid-Index verwenden. Das Hochfahren verläuft nicht erfolgreich, wenn eine inkompatible Strategie mit einem vorhandenen Schema verwendet wird, weil dieses Schema möglicherweise nicht den gespeicherten Suchstatus enthält, den die Strategie benötigt.
  • search_index_sync SearchIndexSyncMode – Wert SearchIndexSyncMode, der das Verhalten der Aktualisierung des verwalteten Suchindex für SearchStrategy.HYBRID und SearchStrategy.KEYWORD auswählt. SearchIndexSyncMode.ON_COMMIT ist der Standardwert und macht Datensätze durchsuchbar, sobald die Schreibtransaktion festgeschrieben wird. SearchIndexSyncMode.MANUAL lässt die Aktualisierung eines expliziten datenbankseitigen Synchronisierungsvorgangs zu. Mit SearchIndexSyncMode.AUTO kann Oracle den verwalteten Hybridindex asynchron aktualisieren. Er wird nur mit SearchStrategy.HYBRID unterstützt. Die Schlüsselwortsuche lehnt AUTO ab.
  • memory_retention_config MemoryRetentionConfig – Optionale Speicheraufbewahrungskonfiguration für DB-gesicherte Nachrichten und Speicher. MemoryRetentionConfig.default_ttl_days wird verwendet, wenn ein neuer Schreibvorgang ttl_days auslässt. MemoryRetentionConfig.max_ttl_days klemmt explizite Dauer pro Datensatz über dem konfigurierten Maximum mit einer Warnung. Wenn diese Option festgelegt ist, verwendet ttl_days=None dieses Maximum, anstatt nicht ablaufende Zeilen zu erstellen. Mit SchemaPolicy.CREATE_IF_NECESSARY aktualisiert eine explizite Konfiguration die gespeicherten Metadaten in einem vorhandenen aktuellen verwalteten Schema. Die vorhandenen Ablaufdaten werden jedoch nicht aktualisiert. Wenn Sie diese Option auslassen, wird die vorhandene Einstellung beibehalten. Wenn eine explizite Konfiguration default_ttl_days oder max_ttl_days unter NOT_SET_MARKER verlässt, löst das SDK dieses Attribut auf seinen Standardwert (None) auf, bevor Schemametadaten verglichen oder gespeichert werden. Wählen Sie diese Konfiguration basierend auf den erwarteten Informationen, die in Datensätzen gespeichert sind, dem Grund, warum die Anwendung sie aufrechterhält, und allen Verpflichtungen zur Beibehaltung von Anwendungen oder Vorschriften.

Warnung: SchemaPolicy.CREATE_IF_NECESSARY kann teurer sein als der normale Speicherstart, da verwaltete Schema-DDL und Best-Effort-Datenrewrites angewendet werden können, 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. Die Speicherinitialisierung 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.

Wenn Sie diesen verwalteten Hybridindex erstellen, wird auch eine DBMS_VECTOR_CHAIN-Vektorisatorvoreinstellung erstellt, die vom verwalteten Schema benannt wird. Die Voreinstellung speichert Lightweight Vectorizer-Konfigurationsmetadaten aus dem konfigurierten OracleDBEmbedder-Modell. Er kann mit Oracle Text-Voreinstellungsansichten wie CTX_USER_PREFERENCES und CTX_USER_PREFERENCE_VALUES geprüft werden.

Methode add

Fügen Sie dem Oracle DB-Speicher Datensätze hinzu.

• Parameter:
  • contents list[str | None]: Zeichnet Payloads auf, die dauerhaft gespeichert werden sollen. Textwerte werden auch für Suchtext verwendet, es sei denn, index_texts ist angegeben. Wenn ein Textwert None ist, kann der Speicher auf metadata["content"] zurückgreifen. Explizite leere Zeichenfolgen werden beibehalten.
  • record_type str: Zu erstellender logischer Datensatztyp, wie "message", "memory", "guideline", "fact", "preference", "user_profile" oder "agent_profile".
  • index_texts list[str | list[str] | None]: Optionale alternative Payloads, die als Suchtext verwendet werden. Mit dieser Option können Sie steuern, welche DB-gesicherten Schlüsselwörter oder hybriden Suchindizes verwendet werden. Jeder äußere Listeneintrag wird an einem Datensatz ausgerichtet. Ein String-Eintrag kann vom Store geblockt werden. Ein Listeneintrag wird als Chunks im Besitz des Aufrufers behandelt und unverändert an RECORD_CHUNKS.chunk_text geschrieben. Wenn auch embeddings angegeben wird, erfordern Listeneinträge genau einen Vektor pro Chunk. Zeichenfolgeneinträge akzeptieren nur einen einzelnen Vektor für diesen Datensatz.

  • Einbettungen list[list[float] | ndarray | list[list[float] | ndarray]] –

    Optionale vorab berechnete Einbettungsvektoren, die auf contents ausgerichtet sind. Jeder Datensatzeintrag kann entweder ein Vektor oder eine Liste von Chunk-Vektoren sein. Wenn ein lokaler Vektorspeicher konfiguriert ist, werden diese Vektoren direkt als Vektordarstellung des Datensatzes gespeichert, anstatt den Einbettungsordner des Speichers aufzurufen, um lokale Vektoren für den Schreibvorgang zu erstellen. Ein einzelner Vektor stellt den gesamten semantischen Text dar, auch wenn der konfigurierte Chunker ihn sonst teilen würde. Mehrere Chunk-Vektoren erfordern übereinstimmende index_texts-Chunk-Listen.

    In SearchStrategy.VECTOR wird die Vektorsuche anhand dieser gespeicherten Vektoren eingestuft. In SearchStrategy.HYBRID oder SearchStrategy.KEYWORD stuft die DB-gestützte Suche den gespeicherten Suchtext und den von Oracle verwalteten Text- oder Hybridindexstatus ein. Daher wirken sich Einbettungen von Add-Time nur auf konfigurierten lokalen Vektorspeicher aus, nicht auf diese aktive Suchstrategie. Wenn dieser Speicher ohne lokalen Vektorspeicher konfiguriert wurde, geben Sie index_texts anstelle von embeddings an, um den Text zu überschreiben, der für diese textbezogenen Indizes sichtbar ist.

  • record_ids str | None | list[str | None] – Optionale durch Aufrufer sichtbare IDs. Für Einfügungen aus einem Datensatz kann eine einzelne Zeichenfolge verwendet werden, während Listen mit contents übereinstimmen müssen. Generierte Kennungen werden zurückgegeben, wenn dieses Feld ausgelassen wird.
  • thread_ids str | None | list[str | None] – Optionale Thread-IDs, die den eingefügten Datensätzen zugeordnet sind. Skalare Werte können über ausgerichtete Eingaben übertragen werden.
  • user_ids str | None | list[str | None] – Optionale Benutzer-IDs, die den eingefügten Datensätzen zugeordnet sind. Skalare Werte können über ausgerichtete Eingaben übertragen werden.
  • agent_ids str | None | list[str | None] – Optionale Agent-IDs, die den eingefügten Datensätzen zugeordnet sind. Skalare Werte können über ausgerichtete Eingaben übertragen werden.
  • Rollen str | None | list[str | None] – Optionale Nachrichtenrollen, wie "user" oder "assistant". Wird nur verwendet, wenn record_type "message" ist.
  • Zeitstempel str | None | list[str | None] – Optionale Zeitstempel zum Speichern mit den Datensätzen. Jeder Zeitstempel gibt an, wann der Datensatz erstellt wurde. Skalare Werte können über ausgerichtete Eingaben übertragen werden. Ohne Einträge oder None wird der Ereigniszeitstempel nicht gesetzt. Wenn ttl_anchor TimeToLiveAnchor.TIMESTAMP ist, muss jeder betroffene Datensatz einen konkreten ISO-8601-Zeitstempelwert aufweisen. ISO-8601-Zeitstempel ohne Zeitzone werden als UTC behandelt.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None] – Optionale Metadatenwörterbücher. Metadaten können "content" als Fallback-Quelle enthalten, wenn ein Textwert ausgelassen und nicht auf "" gesetzt wird.
  • ttl_days int | None | list[int | None] – Optionale Gültigkeitsdauer in Tagen für nachrichten- und speicherähnliche Datensätze. Lassen Sie dieses Argument weg, um MemoryRetentionConfig.default_ttl_days aus dem verwalteten Schema zu verwenden. Übergeben Sie None, um MemoryRetentionConfig.max_ttl_days zu verwenden, wenn die Aufbewahrungskonfiguration eine festlegt, oder um einen nicht ablaufenden Datensatz zu erstellen, wenn dies nicht der Fall ist. Werte über MemoryRetentionConfig.max_ttl_days werden mit einer Warnung auf dieses Maximum geklemmt. Skalare Werte können über ausgerichtete Eingaben übertragen werden.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor] – Optionaler Time-to-Live-Anker. Verwenden Sie TimeToLiveAnchor.CREATED_AT, um relativ zur Datenbankerstellungszeit abzulaufen, oder TimeToLiveAnchor.TIMESTAMP, um relativ zum angegebenen Ereigniszeitstempel abzulaufen. Wenn keine Angabe gemacht wird, verwendet der Ablauf TimeToLiveAnchor.CREATED_AT. Zeitstempelverankertes Ablaufdatum erfordert einen konkreten ISO-8601-Zeitstempel für jeden eingefügten Datensatz. ISO-8601-Zeitstempel ohne Zeitzone werden als UTC behandelt.
  • **store_kwargs (Beliebig): DB-Schreiboptionen. batch_size steuert die executemany-Batchgröße und ist standardmäßig auf 256 gesetzt.
• Rückgaben: IDs für eingefügte Datensätze in derselben logischen Reihenfolge wie die Eingabe.
• Rückgabetyp: list[str]

Beispiele

store.add(
    ["Index this stored text"],
    record_type="memory",
    record_ids="mem-db-add-docs",
)
['mem-db-add-docs']
store.add(
    ["Stored text"],
    record_type="memory",
    index_texts=["Search this text"],
    record_ids="mem-db-index-text-docs",
)
['mem-db-index-text-docs']
store.add(
    ["Short-lived event"],
    record_type="memory",
    record_ids="mem-db-ttl-docs",
    timestamps="2026-01-01T12:00:00+00:00",
    ttl_days=7,
    ttl_anchor=TimeToLiveAnchor.TIMESTAMP,
)
['mem-db-ttl-docs']

Methode add_agent

Agent-Profildatensatz hinzufügen.

• Parameter:
  • agent_id str: Agent-ID.
  • Informationen str – Freiforminformationen zum Agent. Dieser Text wird als Profilinhalt gespeichert und zur Erstellung der durchsuchbaren Darstellung des Profils verwendet.
  • metadata dict[str, Any] | None – Optionale Metadatenzuordnung, die in der Agent-Profilzeile gespeichert ist.
• Rücksendungen: ID des eingefügten Agent-Profildatensatzes.
• Rückgabetyp: str

Hinweise

Agent-Profildatensätze werden nicht kopiert. Die eingefügte öffentliche Datensatz-ID ist derselbe Wert, der als agent_id übergeben wird.

Beispiele

store.add_agent("a-docs-agent", "Support assistant")
'a-docs-agent'

Methode add_async (asynchron)

Fügen Sie dem Speicher asynchron zeilenorientierte Datensätze hinzu.

Akzeptiert dieselben Argumente und gibt dieselben IDs wie add() zurück.

• Parameter:
  • Inhalte list[str | None]
  • record_type str
  • index_texts list[str | list[str] | None]
  • Einbettungen list[list[float] | ndarray | list[list[float] | ndarray]]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • Rollen str | None | list[str | None]
  • Zeitstempel str | None | list[str | None]
  • Metadaten dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • store_kwargs Any
• Rückgabetyp: list[str]

Methode add_batches

Fügen Sie dem Speicher vom Aufrufer vorbereitete logische Batches hinzu.

• Parameter:
  • Batches list[PendingRecordBatch] – Vollständig vorbereitete logische Batches zum Persistieren. Jeder Batch muss eigene Felder pro Datensatz wie record_type, Geltungsbereichswerte, Rollen, Zeitstempel und Metadaten enthalten.
  • **store_kwargs (Beliebig) – Implementierungsspezifische Schreiboptionen, die an den konkreten Speicher weitergeleitet werden.
• Rückgaben: IDs für die eingefügten Datensätze in derselben logischen Reihenfolge wie die Eingabebatches und -zeilen.
• Rückgabetyp: Liste[str]

Beispiele

store.add_batches(
    [
        PendingRecordBatch(
            texts=["pizza batch"],
            record_type="memory",
            record_ids="mem-batch-docs",
        )
    ]
)
['mem-batch-docs']

Methode add_batches_async (asynchron)

Fügen Sie dem Speicher asynchron vom Aufrufer vorbereitete logische Batches hinzu.

Akzeptiert dieselben Argumente und gibt dieselben IDs wie add_batches() zurück.

• Parameter:
  • Batches list[PendingRecordBatch]
  • store_kwargs Any
• Rückgabetyp: list[str]

Methode add_user

Benutzerprofildatensatz hinzufügen

• Parameter:
  • user_id str: Benutzer-ID.
  • Informationen str – Freiforminformationen zum Benutzer. Dieser Text wird als Profilinhalt gespeichert und zur Erstellung der durchsuchbaren Darstellung des Profils verwendet.
  • metadata dict[str, Any] | None – Optionale Metadatenzuordnung, die in der Benutzerprofilzeile gespeichert ist.
• Rücksendungen: ID des eingefügten Benutzerprofildatensatzes.
• Rückgabetyp: str

Hinweise

Benutzerprofildatensätze werden nicht kopiert. Die eingefügte öffentliche Datensatz-ID ist derselbe Wert, der als user_id übergeben wird.

Beispiele

store.add_user("u-docs-profile", "Prefers concise answers.")
'u-docs-profile'

Methode delete

Löschen Sie einen verwalteten Datensatz und die zugehörigen Blockzeilen nach ID.

• Parameter:
  • record_type str: Zu löschendes Label für Datensatztyp. Unterstützte Typen sind "thread", "message", "memory", "guideline", "fact", "preference", "user_profile" und "agent_profile".
  • record_id str: Zu löschende ID.
  • kaskadieren bool: Wenn Sie True verwenden, blenden Sie unterstützte Ziele der obersten Ebene, wie z.B. Akteurprofile, in die untergeordneten Zeilen des Geltungsbereichs innerhalb derselben Transaktion ein. Bei einem Benutzerprofil- oder Agent-Profilziel werden zuerst die eigenen Threadzeilen gelöscht. Dadurch werden die Threadzeilen mit Threadgeltungsbereich und die Zeilen der Speichertabellen entfernt. Anschließend werden alle verbleibenden direkt auf Akteur ausgerichteten Nachrichten und speicherähnlichen Zeilen gelöscht (memory, guideline, fact, preference). Diese Bereichsbereinigung wird noch ausgeführt, wenn die entsprechende Profilzeile bereits fehlt.
• Rückgaben: Anzahl der angeforderten Ziele der obersten Ebene, die entfernt wurden, in der Regel 0 oder 1. Kaskadierte untergeordnete Zeilen werden nicht separat gezählt. Daher kann dies immer noch 0 sein, wenn ein fehlendes Akteurprofil eine bereichsbezogene Bereinigung auslöst.
• Rückgabetyp: int

Hinweise

Der Vorgang wird innerhalb einer Transaktion ausgeführt. Wenn cascade für ein unterstütztes Ziel der obersten Ebene aktiviert ist, werden das Löschen des Profils und alle untergeordneten Löschvorgänge mit Geltungsbereich festgeschrieben oder zusammen zurückgesetzt.

Beispiele

store.add(["Delete me"], record_type="memory", record_ids="mem-delete-docs")
['mem-delete-docs']
store.delete("memory", "mem-delete-docs")
1

Methode delete_thread

Thread und die zugehörigen gespeicherten Zeilen löschen

• Parameter: thread_id str: Thread-ID, deren Zeilen entfernt werden sollen, einschließlich Threadzeile, abhängigen untergeordneten Zeilen und expliziter Bereinigung der Chunk-Zeile.
• Rückgaben: Anzahl der gelöschten Threadzeilen (0 oder 1).
• Rückgabetyp: int

Hinweise

Verwenden Sie diesen Vorgang, wenn Sie eine Thread-bezogene kaskadierende Bereinigung benötigen. Wenn Sie den Thread im DB-Backed-Speicher löschen, wird die Zeile mit dem verwalteten Thread zusammen mit den zugehörigen Nachrichten- und Speicherzeilen sowie den für den Abruf verwalteten Suchdaten entfernt. Dies ist breiter als ein Löschvorgang auf Nachrichtenebene, bei dem nur die Zeile mit Raw-Nachrichten entfernt wird. Beim Löschen von Threads werden abhängige Nachrichten- und Speicherzeilen zusammen mit den zugehörigen Abrufdaten in derselben Transaktion entfernt.

Beispiele

store.delete_thread("c1")
0

Method get

Gespeicherten Datensatz nach Kennung abrufen

• Parameter:
  • record_type str: Das Label des Datensatztyps wird in eine verwaltete Zeile aufgelöst, wie "message", "memory", "guideline", "fact", "preference", "user_profile" oder "agent_profile".
  • record_id str: ID für die Suche.
• Rückgaben: Der Datensatz wird mit entschlüsselten Metadaten aufgefüllt, wenn er gefunden wird, andernfalls None.
• Rückgabetyp: Datensatz | Keine

Beispiele

store.add(["Remember this"], record_type="memory", record_ids="mem-get-docs")
['mem-get-docs']
store.get("memory", "mem-get-docs").id
'mem-get-docs'

Methode list

Permanente Datensätze für einen Datensatztyp auflisten.

• Parameter:
  • record_type str: Label des Datensatztyps (z.B. "message", "memory", "guideline", "fact", "preference", "user_profile" oder "agent_profile").
  • limit int | None – Optionale maximale Anzahl zurückzugebender Datensätze. Wenn dieser Wert ausgelassen wird, verwendet der Store seine Standard-Auflistungs-Cap. Übergeben Sie None, um diese Memory Cap zu deaktivieren und jeden übereinstimmenden Datensatz zurückzugeben.
  • thread_id str | None – Exakter Thread-Geltungsbereichsfilter. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert auf None gesetzt ist, werden nur Zeilen zurückgegeben, deren thread_id SQL NULL ist. Nicht kopierte Datensatztypen ignorieren diesen Filter.
  • user_id str | None: Exakter Filter für den Benutzerumfang. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert auf None gesetzt ist, werden nur Zeilen zurückgegeben, deren user_id SQL NULL ist. Nicht kopierte Datensatztypen ignorieren diesen Filter.
  • agent_id str | None: Exakter Agent-Geltungsbereichsfilter. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert auf None gesetzt ist, werden nur Zeilen zurückgegeben, deren agent_id SQL NULL ist. Nicht kopierte Datensatztypen ignorieren diesen Filter.

  • metadata_filter dict[str, Any] | None –

    Metadatenfilter. Wenn keine Filter angewendet werden, wird keine Filterung angewendet. Wenn dieser Wert auf None gesetzt ist, werden nur Datensätze ohne gespeicherte Metadaten zurückgegeben. Wenn dies auf ein Diktat gesetzt ist, werden Einträge in metadata_filter mit AND-Semantik kombiniert. Einträge, deren Wert kein Operatordictionary auf Feldebene ist, verwenden eine genaue Übereinstimmungssemantik: Der angeforderte Schlüssel muss in den gespeicherten Metadaten vorhanden sein. Verschachtelte Wörterbücher werden rekursiv abgeglichen. Skalare und Listenwerte werden durch exakte Gleichheit abgeglichen; Listenreihenfolge und -länge müssen ebenfalls übereinstimmen. Um die Arraymitgliedschaft zu testen, verwenden Sie ein Operatordictionary auf Feldebene, wie {"tags": {"$array_contains": "prod"}}. Ein Listenoperand für "$array_contains" bedeutet, dass alle aufgelisteten Werte vorhanden sein müssen. "$array_contains_any" bedeutet, dass mindestens ein aufgelisteter Wert vorhanden sein muss. Verwenden Sie "$not", um einen anderen Ausdruck auf Feldebene in demselben Feld zu negieren, einschließlich eines Operator-Dictionarys oder eines Raw-Exact-Match-Wertes. Negierte Ausdrücke stimmen überein, wenn der positive Ausdruck fehlschlagen würde, einschließlich fehlender Felder; negierte Array-Mitgliedschaft stimmt auch mit Nicht-Array-Feldern überein. Beispiele: metadata_filter={"source": "slack"} für ein skalares Feld, metadata_filter={"review": {"status": "open"}} für ein verschachteltes Feld und metadata_filter={"tags": ["prod", "urgent"]} für eine genaue Listenübereinstimmung. Kombinieren Sie Bedingungen, um sie alle zu benötigen:

    metadata_filter={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    }

• Retouren: Datensätze nach Einfügereihenfolge sortiert.
• Liste Rückgabetyp:[Datensatz]

Hinweise

"user_profile" und "agent_profile" sind nicht kopierte Datensatztypen. Für diese Datensatztypen werden thread_id, user_id und agent_id ignoriert, und die Akteuridentität bleibt in record.id.

Beispiele

store.add(
    ["First listed", "Second listed"],
    record_type="memory",
    record_ids=["mem-list-docs-1", "mem-list-docs-2"],
)
['mem-list-docs-1', 'mem-list-docs-2']
[record.id for record in store.list("memory", limit=2)]
['mem-list-docs-1', 'mem-list-docs-2']
store.add_user("u-list-docs", "Prefers concise answers.")
'u-list-docs'
any(
    record.id == "u-list-docs"
    for record in store.list("user_profile", user_id=None, limit=10)
)
True

Methode list_thread_messages

Permanente Nachrichten für einen Thread zurückgeben.

• Parameter:
  • thread_id str: Thread-ID, deren Nachrichten zurückgegeben werden sollen.
  • last_n int | None – Optionale Anzahl der zuletzt zurückgegebenen Nachrichten.
• Rücksendungen: Nach Einfügereihenfolge sortierte Meldungsdatensätze.
• Liste Rückgabetyp:[MessageRecord]

Beispiele

store.list_thread_messages("c1")
[]

Methode search

Datensätze nach Ähnlichkeit suchen

Das aktive Such-Backend hängt vom konfigurierten SearchStrategy des Speichers ab. SearchStrategy.VECTOR ordnet den Abfragevektor den gespeicherten Datensatzvektoren zu. SearchStrategy.HYBRID fragt den verwalteten Hybridindex von Oracle über den gespeicherten Suchtext und den Status des verwalteten Index ab. SearchStrategy.KEYWORD wird nur nach übereinstimmendem Text über dem gespeicherten Suchtext sortiert.

• Parameter:
  • query str | None – Optionaler Text in natürlicher Sprache, mit dem übereinstimmende oder ähnliche Datensätze gesucht werden. Geben Sie mindestens ein Nicht-Leerzeichen an, wenn query_vector ausgelassen wird. Die Vektorsuche bettet diesen Text ein; die Stichwortsuche gleicht ihn mit dem gespeicherten Suchtext ab; die hybride Suche verwendet ihn sowohl für den Text- als auch für den Vektorabruf.
  • query_vector list[float] | None – Optionale vorberechnete Abfrageeinbettung. Es muss genau einer von query und query_vector angegeben werden. Bei der Vektorsuche wird dies mit gespeicherten Datensatzvektoren verglichen. Bei der hybriden Suche wird sie als abfrageseitige Vektoreingabe an den verwalteten Hybridindex von Oracle gesendet und führt nicht dazu, dass der DB-Speicher direkt mit gespeicherten Vektoren für Add-Time- oder Update-Time-Vorgänge verglichen wird. Die Stichwortsuche akzeptiert query_vector nicht. Der Vektor darf nicht leer, eindimensional sein und nur endliche numerische Werte enthalten. Bei der hybriden Suche muss die zugehörige Dimension mit dem konfigurierten OracleDBEmbedder-Modell übereinstimmen.
  • k int – Maximale Anzahl von Ergebnissen, die zurückgegeben werden können. Explizite Werte müssen mindestens 1 sein. Dies ist ein oberer Grenzwert: Der Aufruf gibt möglicherweise weniger als k-Ergebnisse zurück, wenn Filter zu restriktiv sind, wenn weniger nicht abgelaufene übereinstimmende Datensätze vorhanden sind oder das implementierungsspezifische Suchverhalten vorliegt.
  • thread_id str | None – Optionale Thread-Geltungsbereichs-ID. exact_thread_match=False lässt die Threaddimension uneingeschränkt bestehen. exact_thread_match=True entspricht genau dem angegebenen thread_id. Wenn thread_id=None verwendet wird, werden nur Datensätze abgeglichen, die in der Threaddimension nicht kopiert wurden.
  • user_id str | None – Optionale Geltungsbereichs-IDs für Benutzer und Agents. Das entsprechende Kennzeichen exact_*_match=False lässt diese Dimension uneingeschränkt bestehen. exact_*_match=True stimmt genau mit der angegebenen ID überein. Wenn die ID None lautet, entspricht sie nur Datensätzen, die in dieser Dimension nicht kopiert wurden.
  • agent_id str | None – Optionale Geltungsbereichs-IDs von Benutzern und Agents. Das entsprechende Kennzeichen exact_*_match=False lässt diese Dimension uneingeschränkt bestehen. exact_*_match=True stimmt genau mit der angegebenen ID überein. Wenn die ID None lautet, entspricht sie nur Datensätzen, die in dieser Dimension nicht kopiert wurden.
  • exact_user_match bool: Gibt an, ob jede Geltungsbereichs-ID genau abgeglichen werden muss. Bei False ist diese Dimension uneingeschränkt. True stimmt genau mit dem angegebenen Wert überein. Wenn dieser Wert None lautet, werden nur nicht kopierte Datensätze in dieser Dimension abgeglichen.
  • exact_agent_match bool: Gibt an, ob jede Geltungsbereichs-ID genau abgeglichen werden muss. Bei False ist diese Dimension uneingeschränkt. True stimmt genau mit dem angegebenen Wert überein. Wenn dieser Wert None lautet, werden nur nicht kopierte Datensätze in dieser Dimension abgeglichen.
  • exact_thread_match bool – Gibt an, ob jede Geltungsbereichs-ID genau abgeglichen werden muss. Bei False ist diese Dimension uneingeschränkt. True stimmt genau mit dem angegebenen Wert überein. Wenn dieser Wert None lautet, werden nur nicht kopierte Datensätze in dieser Dimension abgeglichen.
  • record_types set[str] | None: Optionale Gruppe durchsuchbarer Datensatztypen, die eingeschlossen werden sollen. Wenn sie ausgelassen wird, deckt die DB-Suche Nachrichten, Speichertabellenzeilen und Akteurprofile ab. Actor-Profile tragen ihre information-Payload bei, während Nachrichten- und Speicherzeilen ihre content-Payload beitragen. Während der Suche verwenden Profildatensatztypen ihre Darsteller-ID für die anwendbare Umfangsdimension, während sich die verbleibenden Umfangsdimensionen wie None verhalten.
  • metadata_filter dict[str, Any] | None – Optionale Metadatenfilterzuordnung. Einträge in metadata_filter werden mit AND-Semantik kombiniert. Einträge, deren Wert kein Operatordictionary auf Feldebene ist, verwenden eine genaue Übereinstimmungssemantik: Der angeforderte Schlüssel muss in den gespeicherten Metadaten vorhanden sein. Verschachtelte Wörterbücher werden rekursiv abgeglichen. Skalare und Listenwerte werden durch exakte Gleichheit abgeglichen; Listenreihenfolge und -länge müssen ebenfalls übereinstimmen. Um die Arraymitgliedschaft zu testen, verwenden Sie ein Operatordictionary auf Feldebene, wie {"tags": {"$array_contains": "prod"}}. Ein Listenoperand für "$array_contains" bedeutet, dass alle aufgelisteten Werte vorhanden sein müssen. "$array_contains_any" bedeutet, dass mindestens ein aufgelisteter Wert vorhanden sein muss. Verwenden Sie "$not", um einen anderen Ausdruck auf Feldebene in demselben Feld zu negieren, einschließlich eines Operator-Dictionarys oder eines Raw-Exact-Match-Wertes. Negierte Ausdrücke stimmen überein, wenn der positive Ausdruck fehlschlagen würde, einschließlich fehlender Felder; negierte Array-Mitgliedschaft stimmt auch mit Nicht-Array-Feldern überein.
• Rückgaben: (record, distance)-Paare nach zunehmender Entfernung sortiert. Die Liste kann weniger als k-Einträge enthalten.
• Rückgabetyp: list[tuple[Record, float]]
• Raises: ValueError – Wenn k kleiner als 1 ist, wenn sowohl query als auch query_vector angegeben sind, wenn query leer ist, wenn der Vektormodus keine Abfrageeinbettung auflösen kann, wenn query_vector ungültig ist oder wenn metadata_filter ungültig ist.

Beispiele

store.add(
    ["pizza preference"],
    record_type="memory",
    record_ids="mem-search-docs",
    thread_ids="c-search-docs",
)
['mem-search-docs']
results = store.search(
    "pizza",
    1,
    thread_id="c-search-docs",
    exact_thread_match=True,
    record_types={"memory"},
)
results[0][0].id
'mem-search-docs'

Nach einem skalaren Metadatenwert filtern:

store.add(
    ["pizza release"],
    record_type="memory",
    record_ids="mem-search-meta-source-docs",
    metadata={"source": "slack"},
)
['mem-search-meta-source-docs']
any(
    record.id == "mem-search-meta-source-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"source": "slack"},
    )
)
True

Nach verschachtelten Metadaten filtern:

store.add(
    ["pizza review"],
    record_type="memory",
    record_ids="mem-search-meta-review-docs",
    metadata={"review": {"status": "open"}},
)
['mem-search-meta-review-docs']
any(
    record.id == "mem-search-meta-review-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"review": {"status": "open"}},
    )
)
True

Ordnen Sie einen Listenwert genau zu, einschließlich Reihenfolge:

store.add(
    ["pizza tags"],
    record_type="memory",
    record_ids="mem-search-meta-tags-docs",
    metadata={"tags": ["prod", "urgent"]},
)
['mem-search-meta-tags-docs']
any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": ["prod", "urgent"]},
    )
)
True

Filtern, wenn ein Metadaten-Array einen Wert enthält:

any(
    record.id == "mem-search-meta-tags-docs"
    for record, _ in store.search(
        "pizza",
        k=3,
        metadata_filter={"tags": {"$array_contains": "prod"}},
    )
)
True

Mehrere Metadatenbedingungen kombinieren Ein Datensatz muss jeden Schlüssel erfüllen:

store.add(
    ["pizza rollout"],
    record_type="memory",
    record_ids="mem-search-meta-combined-docs",
    metadata={
        "source": "slack",
        "review": {"status": "open"},
        "tags": ["prod", "urgent"],
    },
)
['mem-search-meta-combined-docs']
any(
    record.id == "mem-search-meta-combined-docs"
    for record, _ in store.search(
        "pizza",
        k=5,
        metadata_filter={
            "source": "slack",
            "review": {"status": "open"},
            "tags": ["prod", "urgent"],
        },
    )
)
True

Methode search_async (asynchron)

Suchen Sie Datensätze asynchron nach semantischer Ähnlichkeit.

• Parameter:
  • query str | None – Gleicher Abfragetext, der von search akzeptiert wird.
  • k int – Dieselbe maximale Ergebnisanzahl, die von search akzeptiert wird. Explizite Werte müssen mindestens 1 sein.
  • query_vector list[float] | None – Dieselbe optionale vorberechnete Abfrageeinbettung wurde von search akzeptiert.
  • thread_id str | None – Dieselben optionalen Geltungsbereichsfilter werden von search akzeptiert.
  • user_id str | None – Dieselben optionalen Geltungsbereichsfilter werden von search akzeptiert.
  • agent_id str | None – Dieselben optionalen Geltungsbereichsfilter, die von search akzeptiert werden.
  • exact_user_match bool: Identische Flags mit genauer Übereinstimmung, die von search akzeptiert werden.
  • exact_agent_match bool: Identische Flags mit genauer Übereinstimmung, die von search akzeptiert werden.
  • exact_thread_match bool – Gleiche Flags mit exakter Übereinstimmung werden von search akzeptiert.
  • record_types set[str] | None: Derselbe optionale Datensatztypfilter wurde von search akzeptiert.
  • metadata_filter dict[str, Any] | None – Gleicher optionaler Metadatenfilter, der von search akzeptiert wird, einschließlich skalarer, verschachtelter, exakter Liste, Array-Mitgliedschaft und kombinierter Bedingungen wie {"source": "slack"}, {"review": {"status": "open"}}, {"tags": ["prod", "urgent"]} und {"tags": {"$array_contains": "prod"}}.
• Rückgaben: (record, distance)-Paare, die vom zugrunde liegenden search-Aufruf zurückgegeben werden.
• Rückgabetyp: Liste[tuple[Record, float]]
• Gelöst: ValueError – Wenn k kleiner als 1 ist.

Methode update

Aktualisieren Sie gespeicherten Datensatzinhalt, Suchstatus, Metadaten und Zeitstempelwerte.

• Parameter:
  • record_type str: Label des Datensatztyps der zu ändernden Zeile (Beispiel: "message", "memory", "guideline", "fact", "preference", "user_profile" oder "agent_profile")
  • record_id str: ID der zu aktualisierenden gespeicherten Zeile.
  • text str | None – Optionaler Ersatztext, der in der Spalte content persistiert wird. Übergeben Sie None, um den gespeicherten Text zu löschen und die gespeicherte Einbettung zu löschen. Übergeben Sie nur None oder ausgelassene semantische Argumente im selben Aufruf. Übergeben Sie "", um expliziten leeren Inhalt beizubehalten, während Sie eine gespeicherte Vektordarstellung für diesen Datensatz löschen. Wird der Inhalt ausgelassen, bleibt der vorhandene Inhalt unverändert.
  • index_text str | list[str] | None – Optionale reine Semantik-Payload. Wenn keine Angabe gemacht wird, wird text für die semantische Indexierung verwendet. Bei hybridfähigen Schemas wird dies auch der gespeicherte Suchtext, der von der Textkomponente von Oracle verwendet wird. Ein Zeichenfolgenwert kann vom Speicher als Chunking verarbeitet werden. Ein Listenwert wird als Chunks behandelt, die Eigentümer des Aufrufers sind, und wird unverändert in RECORD_CHUNKS geschrieben. Wenn nur embedding angegeben wird, wird der vorhandene Suchtext wieder verwendet.

  • Einbetten list[float] | ndarray | list[list[float] | ndarray] | None –

    Optionaler vorberechneter Einbettungsvektor oder Liste von Chunk-Einbettungsvektoren. Wenn ein lokaler Vektorspeicher konfiguriert ist, wird dieser direkt verwendet, und es erfolgt kein Einbettungsaufruf. Übergeben Sie None, um die gespeicherte Einbettung zu löschen. Ein einzelner Vektor stellt den gesamten Ersetzungstext dar, wenn text angegeben wird, selbst wenn der konfigurierte Chunker diesen Text teilen würde. Beim Ersetzen von Text werden mehrere Chunk-Vektoren abgelehnt, es sei denn, index_text ist eine Chunk-Liste. Wenn nur embedding angegeben wird, muss die Einbettungsanzahl mit den vorhandenen Chunk-Zeilen des Datensatzes übereinstimmen.

    In SearchStrategy.VECTOR wird die Vektorsuche im Vergleich zur gespeicherten Einbettung eingestuft. In SearchStrategy.HYBRID oder SearchStrategy.KEYWORD stuft die DB-gestützte Suche den gespeicherten Suchtext und den von Oracle verwalteten Text- oder Hybridindexstatus ein. Daher wirken sich Einbettungen zur Aktualisierungszeit nur auf konfigurierten lokalen Vektorspeicher aus, nicht auf diese aktive Suchstrategie. Wenn dieser Speicher ohne lokalen Vektorspeicher konfiguriert wurde, geben Sie index_text anstelle von embedding an, um den Text zu aktualisieren, der für diese textbezogenen Indizes sichtbar ist. Semantische Textaktualisierungen können embedding vollständig in diesen Modi weglassen.

  • metadata dict[str, Any] | None – Optionale Metadatenzuordnung, die in JSON serialisiert und in metadata gespeichert wird.
  • timestamp str | None – Optionaler neuer Zeitstempel zum Speichern mit dem Datensatz. Es gibt an, wann der Datensatz erstellt wurde. Wenn dieser Wert ausgelassen wird, wird der vorhandene Zeitstempel beibehalten. Übergeben Sie None, um den gespeicherten Zeitstempel zu löschen und die Datenbankerstellungszeit für zukünftige TimeToLiveAnchor.CREATED_AT-Ablaufaktualisierungen zu verwenden. Wenn ttl_anchor TimeToLiveAnchor.TIMESTAMP ist, werden ISO-8601-Zeitstempel ohne Zeitzone als UTC behandelt.
  • ttl_days int | None – Optionale Ablaufaktualisierung in Tagen. Lassen Sie dieses Argument zusammen mit ttl_anchor aus, um den aktuellen Ablaufzeitstempel beizubehalten. Übergeben Sie None, um MemoryRetentionConfig.max_ttl_days zu verwenden, wenn die Aufbewahrungskonfiguration eine festlegt, oder um den Ablauf zu löschen, wenn dies nicht der Fall ist. Werte über MemoryRetentionConfig.max_ttl_days werden mit einer Warnung auf dieses Maximum geklemmt. Durch das Aktualisieren des Ablaufs kann ein abgelaufener Datensatz erneut angezeigt werden, wenn er noch nicht gelöscht wurde.
  • ttl_anchor TimeToLiveAnchor – Optionaler Time-to-Live-Anker für eine Ablaufaktualisierung. Verwenden Sie TimeToLiveAnchor.CREATED_AT, um ab der gespeicherten Erstellungszeit zu zählen, oder TimeToLiveAnchor.TIMESTAMP, um aus dem Ersatz timestamp zu zählen, der in derselben Aktualisierung bereitgestellt wird, oder dem gespeicherten Ereigniszeitstempel, wenn timestamp ausgelassen wird. Wenn Sie ttl_anchor ohne ttl_days bereitstellen, wird der Ablauf mit dem Schema MemoryRetentionConfig.default_ttl_days aktualisiert. Wenn ttl_anchor während einer Aktualisierung ausgelassen wird, verwendet der Speicher TimeToLiveAnchor.CREATED_AT. Aktualisierungen mit Zeitstempel erfordern entweder einen Ersatz-ISO-8601-Zeitstempel in demselben Aufruf oder einen vorhandenen gespeicherten Ereigniszeitstempel in diesem Format. ISO-8601-Zeitstempel ohne Zeitzone werden als UTC behandelt.
• Rückgaben: Anzahl der aktualisierten Zeilen (0 oder 1). Gibt 0 zurück, wenn kein logischer Datensatz mit record_type und record_id übereinstimmt.
• Rückgabetyp: int
• Raises: ValueError – Wenn record_type nicht unterstützt wird, keine Update-Payload angegeben wird oder die semantischen Aktualisierungsargumente inkompatibel sind.

Beispiele

store.add(["Original note"], record_type="memory", record_ids="mem-update-docs")
['mem-update-docs']
store.update("memory", "mem-update-docs", text="Updated note")
1
store.get("memory", "mem-update-docs").content
'Updated note'

Suchstrategie

Klasse oracleagentmemory.core.dbsearch.SearchStrategy

Basen: Enum

Suchverhalten für Oracle DB-Speicher.

Bei der Initialisierung des DB-Speichers wird die ausgewählte Strategie verwendet, um die Suchfunktion für das verwaltete Schema auszuwählen. Die VECTOR-Suche speichert lokale Einbettungen. Bei der KEYWORD-Suche werden durchsuchbarer Text und ein Textindex gespeichert. In der HYBRID-Suche werden durchsuchbarer Text und von Oracle verwalteter Hybridvektorindexstatus gespeichert. Der DB-Speicher validiert diese Schemafunktion beim Start, sodass eine inkompatible Strategie keine unvollständigen Ergebnisse zurückgibt.

VECTOR

Nur nach Vektorähnlichkeit suchen. Der Speicher bettet die Abfrage mit der konfigurierten Einbettung ein oder verwendet eine vom Aufrufer bereitgestellte query_vector und ordnet Datensätze nach Entfernung zu den gespeicherten Vektoren ein. Verwenden Sie dies mit einem DB-Schema, das für die Vektorsuche konfiguriert ist.

HYBRID

Mit dem verwalteten Hybridindex von Oracle suchen. Oracle kombiniert Textabgleich über gespeicherten Suchtext mit Vektorrangfolge aus dem datenbankinternen Hybridindex. Verwenden Sie diese Option, wenn Benutzer nach natürlicher Sprache sowie nach genauen Kennungen, Aliasnamen oder Produktnamen suchen können. Für diese Strategie muss der Haupteinbettungsordner des Speichers ein OracleDBEmbedder sein, sodass der verwaltete Index und der verwaltete Speicher ein datenbankinternes Modell gemeinsam verwenden.

KEYWORD

Nur nach Stichwort/Text suchen, der über gespeicherten Suchtext übereinstimmt. In diesem Modus werden keine lokalen Abfrageeinbettungen erstellt, und es ist kein Oracle DB-Einbettung erforderlich. Wenn es für ein vorhandenes Hybridschema geöffnet wird, kann es die Textverzweigung dieses Hybridindex verwenden, ohne einen neuen Hybridindex zu erstellen. Verwenden Sie diese Option, wenn exakte Kennungen, Aliasnamen, Produktnamen oder kurze Phrasen den Abruf ohne Vektorfusion steuern sollen.

HYBRID = "HYBRID"

Schlüsselwort = "Schlüsselwort"

VECTOR = 'VECTOR'

Suchindex-Synchronisierungsmodus

Klasse oracleagentmemory.core.dbsearch.SearchIndexSyncMode

Basen: Enum

Aktualisierungsverhalten für verwaltete DB-Suchindizes.

Diese Einstellung steuert, wann Oracle neuen oder geänderten Suchtext für die DB-gestützte textbezogene Suche sichtbar macht. SearchStrategy.HYBRID verwendet den verwalteten Hybridvektorindex von Oracle. SearchStrategy.KEYWORD verwendet einen Oracle Text-Index. SearchStrategy.VECTOR verwendet diese Einstellung nicht.

ON_COMMIT

Aktualisieren Sie den Index, wenn die Schreibtransaktion festgeschrieben wird. Dies ist die Standardeinstellung und die einfachste Wahl für die meisten Anwendungen, da Datensätze unmittelbar nach einem erfolgreichen Schreibvorgang durchsucht werden können. Es kann Arbeit hinzufügen, um Transaktionen zu schreiben, da der Index sofort auf dem neuesten Stand gehalten wird.

MANUAL

Index nicht automatisch aktualisieren. Neue oder aktualisierte Datensätze werden möglicherweise erst dann in der Stichwort- oder Hybridsuche angezeigt, wenn Sie den datenbankseitigen Indexsynchronisierungsvorgang selbst ausführen. Dies ist nützlich für Bulk Loads oder Wartungsfenster, in denen Sie steuern möchten, wann Aktualisierungsarbeitsläufe ausgeführt werden.

AUTO

Lassen Sie Oracle den verwalteten Hybridindex asynchron aktualisieren. Schreibvorgänge können die unmittelbaren Aktualisierungskosten vermeiden. Die Suchergebnisse können jedoch hinter den letzten Schreibvorgängen zurückbleiben, bis Oracle die Hintergrundaktualisierung abgeschlossen hat. Dieser Modus wird nur mit SearchStrategy.HYBRID unterstützt.

Warnung: Diese Einstellung steuert die fortlaufende Wartung, nachdem der verwaltete Suchindex vorhanden ist. Die erste Indexerstellung wird nicht asynchron erstellt. Das Erstellen eines verwalteten Hybridindexes über vorhandenen gespeicherten Suchtext kann eine lange Ausführungszeit haben, da Oracle den verwalteten Hybridindexstatus aus diesem Text erstellt.

AUTO = 'AUTO'

MANUELL = 'manuell'

ON_COMMIT = 'ON_COMMIT'

Gültigkeitsdauer

Klasse oracleagentmemory.core.retention.MemoryRetentionConfig

Basis: object

Aufbewahrungseinstellungen auf Schemaebene für von Oracle DB unterstützte Datensätze.

• Parameter:
  • default_ttl_days int | None: Standarddauer für die Gültigkeitsdauer in Tagen. Behalten Sie NOT_SET_MARKER bei, um den Standardwert None (kein Maximum) zu verwenden.
  • max_ttl_days int | None – Optionale maximale Gültigkeitsdauer in Tagen. Behalten Sie NOT_SET_MARKER bei, um den Standardwert None zu verwenden. Übergeben Sie None für kein Maximum. Wenn diese Option festgelegt ist, handelt es sich um eine Hard Cap: Schreibvorgänge, die versuchen, einen größeren ttl_days-Wert zu verwenden, werden mit einer Warnung auf dieses Maximum geklemmt, und Schreib-APIs, die ttl_days=None übergeben, verwenden dieses Maximum, anstatt nicht ablaufende Datensätze zu erstellen.

Klasse oracleagentmemory.apis.ttl.TimeToLiveAnchor

Basen: Enum

Anker zur Berechnung eines Ablaufzeitstempels von einer Gültigkeitsdauer.

CREATED_AT

Compute-Ablauf vom Zeitstempel der Datenbankerstellung des Datensatzes. Dies ist der Standardwert, wenn Aufrufer ttl_anchor auslassen.

TIMESTAMP

Berechnung des Ablaufs aus dem gespeicherten Ereigniszeitstempel des Datensatzes. Verwenden Sie diese Option, wenn eine Nachricht oder ein Speicher ein älteres Ereignis darstellt und relativ zu dieser Ereigniszeit anstatt der Einfügezeit ablaufen soll.

CREATED_AT = 'CREATED_AT'

Zeitstempel = 'Zeitstempel'

Schema-Policy

Klasse oracleagentmemory.core.SchemaPolicy

Basis: str, Enum

Schemaerstellungs-Policy für Oracle DB-Speicher.

ERFORDERLICH

Stellen Sie sicher, dass das vollständige verwaltete Schema bereits vorhanden ist und aktuell ist. Erstellen oder ändern Sie keine DB-Objekte.

CREATE_IF_LEER

Wenn keine verwalteten Objekte vorhanden sind, Bootstrap-Schema. Wenn bereits Objekte vorhanden sind, benötigen Sie ein vollständiges und aktuelles verwaltetes Schema.

ERSTELLEN_IF_NOTWENDIG

Erstellen Sie fehlende verwaltete Objekte, und wenden Sie unterstützte Upgrades verwalteter Schemas an.

NEU ERSTELLEN

Alle verwalteten Schemaobjekte löschen und neu erstellen. Das ist destruktiv.