Speicher und Schema

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

Shop-API

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 zum Einbetten 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] – Optionale alternative Payloads, die nur zum Einbetten/Indexieren verwendet werden. Wenn angegeben, muss er mit den Texteingaben übereinstimmen.
  • Einbettungen list[list[float]] | list[ndarray] – Optionale vorab berechnete Einbettungsvektoren, die an den Texteingaben ausgerichtet sind. Wenn angegeben, muss der Speicher diese Vektoren direkt verwenden, anstatt dessen Einbettung aufzurufen. Falls nicht angegeben, muss der Speicher einen Einbettungsschalter aufweisen. Andernfalls wird ein Fehler ausgelöst.
  • 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 Ereigniszeitstempel, die mit den Datensätzen dauerhaft gespeichert werden. Skalare Werte können über ausgerichtete Texteingaben übertragen werden.
  • metadata dict[str, Any] | list[dict[str, Any] | None] | 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.
  • **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]
  • Einbettungen list[list[float]] | list[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] | list[dict[str, Any] | None] | None
  • 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.
• 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]
  • Einbettungen list[list[float]] | list[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] | list[dict[str, Any] | None] | None
  • 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.
• 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.
• 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.
  • 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 partielle Metadatenzuordnung. Ein Datensatz stimmt nur überein, wenn seine gespeicherten Metadaten alle angeforderten Schlüssel und Werte enthalten. Verschachtelte Wörterbücher werden rekursiv abgeglichen. Listenwerte werden nach genauer Gleichheit und nicht nach rekursiver Zuordnung der Teilmenge abgeglichen. Daher müssen Listenreihenfolge und -länge ebenfalls übereinstimmen.
• Rückgaben: (record, distance)-Paare nach zunehmender Entfernung sortiert.
• 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

Methode search_async (asynchron)

Suchen Sie Datensätze asynchron nach Vektorä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.
• 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 den gespeicherten Datensatzinhalt, die Einbettung von Daten oder Metadaten.

• 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 | None – Optionale Nur-Einbettung-Payload, mit der der gespeicherte Vektor neu berechnet wird, ohne den persistenten Text zu ändern.
  • einbetten list[float] | ndarray | None – Optionaler vorab berechneter Einbettungsvektor. Wenn angegeben, wird dies direkt verwendet, und es erfolgt kein Einbettungsaufruf. Übergeben Sie None, um die gespeicherte Einbettung explizit zu löschen, wenn der Speicher sie unterstützt.
  • metadata dict[str, Any] | None – Optionale Metadaten-Ersatzzuordnung. Übergeben Sie None, um Metadaten zu löschen, wenn der Speicher sie unterstützt.
• 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 für vektorisierte Datensatztypen. Kann None sein, wenn Aufrufer immer vorab berechnete Vektoren in add, update und search bereitstellen.
  • 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.
  • vector_dim int: Einbettungsdimension für die Schemaerstellung, wenn VECTOR-Spalten erstellt werden.
  • table_name_prefix str – Optionales Präfix, das zu verwalteten Tabellen-/Indexnamen hinzugefügt wurde.

Methode add

Datensätze zur Filiale hinzufügen

• Parameter:
  • contents list[str | None]: Zeichnet Payloads auf, die dauerhaft gespeichert werden sollen. Textwerte werden auch zum Einbetten 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] – Optionale alternative Payloads, die nur zum Einbetten/Indexieren verwendet werden. Wenn angegeben, muss er mit den Texteingaben übereinstimmen.
  • Einbettungen list[list[float]] | list[ndarray] – Optionale vorab berechnete Einbettungsvektoren, die an den Texteingaben ausgerichtet sind. Wenn angegeben, muss der Speicher diese Vektoren direkt verwenden, anstatt dessen Einbettung aufzurufen. Falls nicht angegeben, muss der Speicher einen Einbettungsschalter aufweisen. Andernfalls wird ein Fehler ausgelöst.
  • 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 Ereigniszeitstempel, die mit den Datensätzen dauerhaft gespeichert werden. Skalare Werte können über ausgerichtete Texteingaben übertragen werden.
  • metadata dict[str, Any] | list[dict[str, Any] | None] | 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.
  • **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]
  • Einbettungen list[list[float]] | list[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] | list[dict[str, Any] | None] | None
  • store_kwargs Any

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]
  • Einbettungen list[list[float]] | list[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] | list[dict[str, Any] | None] | None
  • 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_agent

Agent-Profildatensatz hinzufügen.

• Parameter:
  • agent_id str: Agent-ID.
  • Informationen str – Freiforminformationen zum Agent. Dieser Text wird als Profilinhalt gespeichert und zum Erstellen der Profileinbettungszeile in RECORD_CHUNKS verwendet.
• 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_user

Benutzerprofildatensatz hinzufügen

• Parameter:
  • user_id str: Benutzer-ID.
  • Informationen str – Freiforminformationen zum Benutzer. Dieser Text wird als Profilinhalt gespeichert und zum Erstellen der Profileinbettungszeile in RECORD_CHUNKS verwendet.
• 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 übereinstimmende 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 verwaltete Threadzeile zusammen mit den zugehörigen Nachrichten- und Speicherzeilen sowie den Datensatz-Chunk-Zeilen entfernt, die für den Abruf verwaltet werden. 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 die abhängigen Nachrichten- und Speicherzeilen, die von THREAD referenziert werden, zusammen mit den übereinstimmenden RECORD_CHUNKS-Zeilen 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 wird None verwendet.
• 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 diese Option 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 diese Eigenschaft auf ein Diktat gesetzt ist, müssen gespeicherte Metadaten alle angeforderten Schlüssel und Werte enthalten. Verschachtelte Wörterbücher werden rekursiv abgeglichen. Listenwerte werden nach genauer Gleichheit und nicht nach rekursiver Zuordnung der Teilmenge abgeglichen. Daher müssen Listenreihenfolge und -länge ebenfalls übereinstimmen.
• 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

• 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.
  • 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. Bei thread_id=None 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 diese Option 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. Bei 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 partielle Metadatenzuordnung. Ein Datensatz stimmt nur überein, wenn seine gespeicherten Metadaten alle angeforderten Schlüssel und Werte enthalten. Verschachtelte Wörterbücher werden rekursiv abgeglichen. Listenwerte werden nach genauer Gleichheit und nicht nach rekursiver Zuordnung der Teilmenge abgeglichen. Daher müssen Listenreihenfolge und -länge ebenfalls übereinstimmen.
• Rückgaben: (record, distance)-Paare nach zunehmender Entfernung sortiert.
• Rückgabetyp: list[tuple[Record, float]]
• Gelöst: ValueError – Wenn k kleiner als 1 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

Methode search_async (asynchron)

Suchen Sie Datensätze asynchron nach Vektorä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.
• 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, Chunk-Einbettungen und Metadatenwerte.

• 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 Chunk-Einbettung für diesen Datensatz löschen. Wird der Inhalt ausgelassen, bleibt der vorhandene Inhalt unverändert.
  • index_text str | None – Optionale Payload, die nur zur Einbettung dient. Wenn keine Angabe gemacht wird, wird text eingebettet.
  • einbetten list[float] | ndarray | None – Optionaler vorab berechneter Einbettungsvektor. Wenn angegeben, wird dies direkt verwendet, und es erfolgt kein Einbettungsaufruf. Übergeben Sie None, um die gespeicherte Einbettung zu löschen.
  • metadata dict[str, Any] | None – Optionale Metadatenzuordnung, die in JSON serialisiert und in metadata gespeichert wird.
• 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'

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 nur fehlende verwaltete Objekte, einschließlich Metadaten.

NEU ERSTELLEN

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