Magasins et schéma

Cette page présente les abstractions de l'emplacement de stockage principal et les contrôles de schéma utilisés par le kit SDK de mémoire d'agent Oracle.

API de stockage

Stocker la sémantique d'écriture

Les écritures de stockage conservent une séparation claire entre le texte stocké par une application et la charge utile utilisée par le stockage pour l'extraction. La plupart des applications peuvent utiliser les API de niveau mémoire et de niveau thread et laisser le magasin préparer les lignes de recherche dont il a besoin pour la récupération de vecteur, de mot-clé ou hybride. Les API de stockage de niveau inférieur affichent index_texts, index_text, embeddings et embedding pour les intégrations avancées qui savent déjà quel texte ou vecteurs doivent être utilisés pour l'extraction.

Considérez chaque écriture comme deux éléments connexes :

• contents dans add() et content dans update() contrôlent le contenu d'enregistrement stocké renvoyé par get(), list() et les résultats de recherche.
• index_texts dans add() et index_text dans update() contrôlent le texte écrit dans les lignes d'extraction de la banque. La recherche utilise ces lignes, puis renvoie les enregistrements logiques d'origine.

update() accepte également text en tant que paramètre de compatibilité obsolète. Utilisez content dans le nouveau code ; le fait de fournir text émet un avertissement d'abandon.

Si aucun remplacement de recherche ou incorporation explicite n'est fourni, le magasin utilise le texte stocké résolu comme texte d'extraction. Le texte non vide est découpé par bloc par le magasin lors de la configuration du découpage par bloc. Le texte vide stocke le texte de l'enregistrement mais ne fournit aucun texte d'extraction.

Le tableau ci-dessous décrit comment le texte d'extraction est choisi avant la prise en compte des charges utiles vectorielles explicites.

Charge utile d'extraction au niveau du magasin

Entrée	add()	update()
index_texts ou index_text omis	Chaque enregistrement utilise sa valeur contents résolue pour l'extraction.	Une valeur content de remplacement est utilisée pour l'extraction. Si content est également omis, les mises à jour d'intégration uniquement réutilisent les lignes de texte d'extraction existantes de l'enregistrement.
Chaîne index_texts entrée ou chaîne index_text	La chaîne remplace le texte d'extraction de cet enregistrement. Le magasin peut le fragmenter avant d'écrire des lignes d'extraction.	La chaîne remplace le texte d'extraction de cet enregistrement. Le magasin peut le fragmenter avant d'écrire des lignes d'extraction.
Entrée list[str] index_texts ou list[str] index_text	La liste est traitée comme des blocs appartenant à l'appelant. Chaque chaîne non vide est écrite sous la forme d'une ligne d'extraction, et le magasin ne la fragmente pas à nouveau.	La liste est traitée comme des blocs appartenant à l'appelant. Chaque chaîne non vide est écrite sous la forme d'une ligne d'extraction, et le magasin ne la fragmente pas à nouveau.
Entrée None index_texts ou index_text=None	None dans la liste externe index_texts signifie "utiliser le contenu stocké pour cet enregistrement".	index_text=None efface les lignes d'extraction tout en laissant le contenu stocké inchangé, sauf si content est également fourni.
Chaîne vide ou liste de blocs vide	Stocke le contenu de l'enregistrement et ne fournit aucun texte d'extraction pour cet enregistrement.	Met à jour le contenu de l'enregistrement lorsque content est fourni et efface le texte d'extraction de cet enregistrement.

Les intégrations explicites sont facultatives. Lorsqu'ils sont omis, le magasin dérive des vecteurs locaux du texte de récupération lorsque le stockage vectoriel local est configuré ; les magasins de mots-clés ou hybrides peuvent également utiliser des lignes de récupération de texte uniquement. Lorsque des valeurs embeddings ou embedding explicites sont fournies, le magasin écrit ces vecteurs directement et n'appelle pas son intégrateur pour ces vecteurs.

Dans add(), embeddings=None se comporte comme l'omission de embeddings. Dans update(), embedding=None est explicite : le magasin conserve ou réécrit le texte d'extraction en fonction de content et index_text, mais stocke ces lignes sans vecteurs locaux. Si content et index_text sont tous deux omis, cela efface les vecteurs des lignes d'extraction existantes.

La forme du vecteur indique au magasin combien de parts de propriété l'appelant prend :

• un vecteur signifie un vecteur pour l'ensemble du texte de récupération. Le magasin ne fractionne pas ce texte pour le vecteur explicite. Si ce texte de récupération est vide, le vecteur peut être stocké sans texte de bloc compagnon.
• plusieurs vecteurs signifient un vecteur par bloc appartenant à l'appelant. Fournissez des listes de blocs index_texts ou index_text correspondantes, ou utilisez un élément update() d'intégration uniquement qui réutilise les lignes de texte d'extraction existantes de l'enregistrement.
• les nombres de vecteurs doivent correspondre aux nombres de blocs, et tous les vecteurs explicites d'un appel add() doivent avoir la même dimension.
• une charge utile de vecteur par enregistrement vide n'est autorisée que lorsqu'il n'existe aucune ligne de texte d'extraction à aligner sur celle-ci.

Certaines combinaisons sont rejetées de sorte que le texte stocké, le texte de récupération et les vecteurs ne s'écartent pas. La transmission de content=None efface le contenu stocké et les lignes d'extraction. Elle ne peut donc pas être combinée avec des valeurs index_text ou embedding non NULL ; les enregistrements de profil d'acteur ne prennent pas en charge content=None. Le paramètre text en phase d'abandon a le même comportement. La transmission de index_text=None dans update() signifie "effacer les lignes d'extraction", de sorte que les incorporations explicites non vides ne sont pas autorisées dans le même appel. Plusieurs vecteurs explicites nécessitent un texte de bloc explicite, sauf si la mise à jour est incorporée uniquement et que les lignes d'extraction existantes fournissent déjà le texte de bloc.

classe oracleagentmemory.core.OracleMemoryStore

Bases : IMemoryStore

Interface de banque commune utilisée par OracleAgentMemory.

Une implémentation de magasin est responsable de la persistance des enregistrements de texte et de l'exécution de recherches de similarité sur ces enregistrements. Les points d'entrée synchrones et asynchrones sont définis de sorte que les API de niveau supérieur peuvent afficher les surfaces synchrones/asynchrones correspondantes sans dupliquer la logique propre au magasin.

méthode add

Ajoutez des enregistrements au magasin.

• Paramètres:
  • contents Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None] – Séquence en lecture seule des charges utiles d'enregistrement. Les entrées de message peuvent contenir des parties MessageContent ordonnées, tandis que les entrées de récapitulatif de thread peuvent être des mappings. Les valeurs de texte sont également utilisées pour l'indexation sémantique, sauf si index_texts ou embeddings sont fournis. Lorsqu'une valeur de texte est None, les implémentations peuvent revenir à metadata["content"]. Les chaînes vides explicites sont conservées.
  • record_type str – Type d'enregistrement logique à créer, par exemple "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" ou "thread_summary".
  • index_texts list[str | list[str] | None] : charge utile alternative facultative utilisée uniquement pour l'indexation sémantique. Lorsqu'elle est fournie, la liste externe doit correspondre aux entrées de texte. Chaque entrée peut être une chaîne, que le magasin peut diviser en interne, ou une liste de chaînes non vides, que le magasin traite comme des morceaux appartenant à l'appelant et ne doit pas diviser à nouveau.
  • embeddings list[list[float] | ndarray | list[list[float] | ndarray]] : vecteurs d'intégration précalculés facultatifs alignés sur les entrées de texte. Chaque entrée d'enregistrement peut être soit un vecteur d'intégration, soit une liste de vecteurs d'intégration de blocs pour cet enregistrement. Lorsqu'il est fourni, le magasin doit utiliser ces vecteurs directement au lieu d'appeler son intégrateur. Plusieurs vecteurs pour un enregistrement nécessitent la mise en correspondance de listes de blocs index_texts afin que les limites de blocs de texte et de vecteurs soient explicites. S'ils ne sont pas fournis, les magasins dérivent généralement l'état sémantique de leur intégrateur configuré, mais les modes d'indexation en mode texte spécifique à l'implémentation peuvent également autoriser les écritures en mode texte uniquement sans un.
  • record_ids str | None | list[str | None] : identificateurs invisibles par l'appelant (facultatif). Une seule chaîne peut être utilisée pour les insertions d'un enregistrement, tandis que les listes doivent s'aligner sur les entrées de texte. Les identificateurs générés sont renvoyés lorsque ce champ est omis.
  • thread_ids str | None | list[str | None] – Identificateurs de thread facultatifs associés aux enregistrements insérés. Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées.
  • user_ids str | None | list[str | None] – Identificateurs utilisateur facultatifs associés aux enregistrements insérés. Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées.
  • agent_ids str | None | list[str | None] : identificateurs d'agent facultatifs associés aux enregistrements insérés. Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées.
  • rôles str | None | list[str | None] : rôles de message facultatifs tels que "user" ou "assistant". Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées. Utilisé uniquement si record_type est "message".
  • timestamps str | None | list[str | None] : horodatages facultatifs à enregistrer avec les enregistrements. Chaque horodatage représente un événement associé à l'enregistrement. Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées. Les entrées omises ou None stockent un horodatage d'événement NULL. Les lectures utilisent l'heure de création de l'enregistrement comme horodatage effectif.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None] – Dictionnaires de métadonnées fournis par l'appelant facultatifs. Les métadonnées peuvent inclure "content" en tant que source de secours lorsqu'une valeur de texte est omise plutôt que définie explicitement sur "". Lorsque record_type="image", chaque écriture d'image requiert "image_mime_type" avec l'une des valeurs suivantes : "image/png", "image/jpeg" ou "image/webp". Le magasin utilise ce champ pour enregistrer l'image, mais ne la renvoie pas dans les métadonnées de l'enregistrement.
  • ttl_days int | None | list[int | None] : durée de vie facultative en jours pour les enregistrements prenant en charge l'expiration. Omettez cet argument pour utiliser la valeur par défaut du magasin. Transmettez None pour les enregistrements qui ne doivent pas expirer. Les valeurs scalaires peuvent être diffusées sur des entrées de texte alignées.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor] : ancre de durée de vie facultative. Utilisez TimeToLiveAnchor.CREATED_AT pour expirer par rapport à l'heure de création stockée ou TimeToLiveAnchor.TIMESTAMP pour expirer par rapport à l'horodatage d'événement de chaque enregistrement. Lorsqu'elles sont omises, les implémentations utilisent TimeToLiveAnchor.CREATED_AT.
  • statuts RecordStatus | list[RecordStatus] – Statuts de cycle de vie facultatifs ou statuts pour les enregistrements. Omettez cette opération pour stocker RecordStatus.VALID.
  • **store_kwargs (N'importe lequel) – Options d'écriture spécifiques à l'implémentation transmises au magasin concret.
• Type de retour : list[str]

Notes

Utilisez add_batches() lorsque l'appelant comporte déjà un ou plusieurs objets PendingRecordBatch.

• Retours : Identificateurs des enregistrements insérés, dans le même ordre logique que l'entrée.
• Type de retour : List[str]
• Paramètres:
  • contenu Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
  • record_type str
  • textes_index list[str | list[str] | None]
  • embarquements 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]
  • rôles str | None | list[str | None]
  • horodatages str | None | list[str | None]
  • métadonnées dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • statuts RecordStatus | list[RecordStatus]
  • store_kwargs Any

method add_agent (résumé)

Ajoutez un enregistrement de profil d'agent.

• Paramètres:
  • agent_id str : identificateur stable du profil d'agent.
  • information str : texte de forme libre décrivant l'agent.
  • metadata dict[str, Any] | None – Mapping de métadonnées facultatif stocké sur la ligne de profil d'agent.
• Retours : Identifiant de l'enregistrement de profil d'agent créé.
• Type de retour : str

method add_agent_async (async)

Ajoutez de manière asynchrone un enregistrement de profil d'agent.

• Paramètres:
  • agent_id str : identificateur stable du profil d'agent.
  • information str : texte de forme libre décrivant l'agent.
  • metadata dict[str, Any] | None – Mapping de métadonnées facultatif stocké sur la ligne de profil d'agent.
• Retours : Identifiant de l'enregistrement de profil d'agent créé.
• Type de retour : str

method add_async (async)

Ajoutez de manière asynchrone des enregistrements orientés ligne au magasin.

accepte les mêmes arguments et renvoie les mêmes identificateurs que add().

• Paramètres:
  • contenu Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
  • record_type str
  • textes_index list[str | list[str] | None]
  • embarquements 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]
  • rôles str | None | list[str | None]
  • horodatages str | None | list[str | None]
  • métadonnées dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • statuts RecordStatus | list[RecordStatus]
  • store_kwargs Any
• Type de retour : list[str]

méthode add_batches

Ajoutez des lots logiques préparés par l'appelant au magasin.

• Paramètres:
  • batches list[PendingRecordBatch] : lots logiques entièrement préparés pour persistance. Chaque lot doit contenir ses propres champs par enregistrement, tels que record_type, les valeurs de portée, les rôles, les horodatages et les métadonnées.
  • **store_kwargs (N'importe lequel) – Options d'écriture spécifiques à l'implémentation transmises au magasin concret.
• Retours : Identifiants pour les enregistrements insérés, dans le même ordre logique que les lots et lignes d'entrée.
• Type de retour : List[str]

Exemples

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

method add_batches_async (async)

Ajoutez de manière asynchrone des lots logiques préparés par l'appelant au magasin.

accepte les mêmes arguments et renvoie les mêmes identificateurs que add_batches().

• Paramètres:
  • batchs list[PendingRecordBatch]
  • store_kwargs Any
• Type de retour : list[str]

method add_relations (résumé)

Stockez une ou plusieurs relations dirigées.

Les valeurs scalaires sont diffusées dans le batch d'enregistrement source. Les valeurs de liste doivent avoir la même longueur. Une seule orientation peut être stockée pour une paire d'adresses. Utilisez opposite_relation_types pour décrire la vue inverse plutôt que d'ajouter une seconde relation inverse. Les implémentations peuvent restreindre les types d'enregistrement d'adresse et les étiquettes de relation qu'elles conservent.

• Paramètres:
  • source_record_ids str | list[str] – Identificateur ou identificateurs d'enregistrements à l'extrémité source de chaque relation dirigée.
  • source_record_types str | list[str] – Type(s) d'enregistrement pour source_record_ids. Indiquez une valeur pour toutes les sources ou une valeur pour chaque relation.
  • target_record_ids str | list[str] – Identificateur ou identificateurs d'enregistrements à l'extrémité cible de chaque relation dirigée.
  • target_record_types str | list[str] – Type(s) d'enregistrement pour target_record_ids. Indiquez une valeur pour toutes les cibles ou une valeur pour chaque relation.
  • relation_types str | list[str] – Libellé(s) de relation dirigée(s). Indiquez une valeur pour toutes les relations ou une valeur pour chaque relation.
  • opposite_relation_types str | list[str] : libellé ou libellés facultatifs pour la vue inversée de chaque relation. Pour les types de relations de mémoire intégrés, l'omission utilise l'étiquette inverse prédéfinie. Pour les types de relation personnalisés, l'omission utilise le même libellé dans les deux sens.
  • relation_ids str | None | list[str | None] : identificateurs stables facultatifs. Omettez ceci pour laisser le magasin générer des identificateurs.
  • timestamps str | None | list[str | None] : horodatage ou horodatage facultatif à stocker sur les relations.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None] – Objets de métadonnées facultatifs à stocker sur les relations.
• Renvoie : identificateurs de relation dans l'ordre d'entrée.
• Type de retour : list[str]

Exemples

store.add_relations(
    "new", "memory", "old", "memory", "supersedes"
)
['relation-id']

method add_relations_async (async)

Stockez de manière asynchrone une ou plusieurs relations dirigées.

Les valeurs scalaires sont diffusées dans le batch d'enregistrement source. Les valeurs de liste doivent avoir la même longueur. Une seule orientation peut être stockée pour une paire d'adresses. Utilisez opposite_relation_types pour décrire la vue inverse plutôt que d'ajouter une seconde relation inverse.

• Paramètres:
  • source_record_ids str | list[str] – Identificateur ou identificateurs d'enregistrements à l'extrémité source de chaque relation dirigée.
  • source_record_types str | list[str] – Type(s) d'enregistrement pour source_record_ids. Indiquez une valeur pour toutes les sources ou une valeur pour chaque relation.
  • target_record_ids str | list[str] – Identificateur ou identificateurs d'enregistrements à l'extrémité cible de chaque relation dirigée.
  • target_record_types str | list[str] – Type(s) d'enregistrement pour target_record_ids. Indiquez une valeur pour toutes les cibles ou une valeur pour chaque relation.
  • relation_types str | list[str] – Libellé(s) de relation dirigée(s). Indiquez une valeur pour toutes les relations ou une valeur pour chaque relation.
  • opposite_relation_types str | list[str] : libellé ou libellés facultatifs pour la vue inversée de chaque relation. Pour les types de relations de mémoire intégrés, l'omission utilise l'étiquette inverse prédéfinie. Pour les types de relation personnalisés, l'omission utilise le même libellé dans les deux sens.
  • relation_ids str | None | list[str | None] : identificateurs stables facultatifs. Omettez ceci pour laisser le magasin générer des identificateurs.
  • timestamps str | None | list[str | None] : horodatage ou horodatage facultatif à stocker sur les relations.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None] – Objets de métadonnées facultatifs à stocker sur les relations.
• Renvoie : identificateurs de relation dans l'ordre d'entrée.
• Type de retour : list[str]

Exemples

await store.add_relations_async(
    "new", "memory", "old", "memory", "supersedes"
)
['relation-id']

method add_user (résumé)

Ajouter un enregistrement de profil utilisateur.

• Paramètres:
  • user_id str – Identificateur stable du profil utilisateur. Les implémentations soutenues par la base de données peuvent déduire cette valeur d'un contexte de sécurité d'utilisateur final attaché lorsqu'elle est omise.
  • information str : texte de forme libre requis décrivant l'utilisateur.
  • metadata dict[str, Any] | None – Mapping de métadonnées facultatif stocké sur la ligne du profil utilisateur.
• Retours : Identifiant de l'enregistrement de profil utilisateur créé.
• Type de retour : str

method add_user_async (async)

Ajouter un enregistrement de profil utilisateur de manière asynchrone.

• Paramètres:
  • user_id str – Identificateur stable du profil utilisateur.
  • information str – Texte de forme libre décrivant l'utilisateur.
  • metadata dict[str, Any] | None – Mapping de métadonnées facultatif stocké sur la ligne du profil utilisateur.
• Retours : Identifiant de l'enregistrement de profil utilisateur créé.
• Type de retour : str

method delete (résumé)

Supprimer un enregistrement stocké par identifiant.

• Paramètres:
  • record_type str – Type logique de l'enregistrement à supprimer.
  • record_id str – Identifiant de l'enregistrement à supprimer.
  • cascade bool : lorsque True, appliquez tout comportement de suppression en cascade pris en charge par le magasin pour les cibles de niveau supérieur demandées dans la même opération de suppression. Il est principalement utilisé pour les cibles telles que les profils d'acteur qui possèdent des enregistrements de portée supplémentaires. Par exemple, une cascade de profils utilisateur ou d'agents peut supprimer les threads propriétaires eux-mêmes, les messages de portée thread et les enregistrements de type mémoire supprimés avec ces threads, ainsi que tous les enregistrements de portée acteur directs restants tels que les messages, les mémoires, les directives, les faits ou les préférences. Pour les suppressions de profil d'acteur, ce nettoyage ciblé peut toujours être exécuté lorsque la ligne de profil correspondante est déjà absente.
• Retours : nombre d'enregistrements de niveau supérieur demandés supprimés, généralement 0 ou 1. Les lignes enfant en cascade ne sont pas comptabilisées séparément. Il peut donc s'agir de 0 lorsqu'un profil d'acteur manquant déclenche un nettoyage ciblé.
• Type de retour : int

method delete_async (async)

Supprimer de manière asynchrone un enregistrement stocké par identifiant.

• Paramètres:
  • record_type str – Type logique de l'enregistrement à supprimer.
  • record_id str – Identifiant de l'enregistrement à supprimer.
  • cascade bool : lorsque True, appliquez tout comportement de suppression en cascade pris en charge par le magasin pour les cibles de niveau supérieur demandées dans la même opération de suppression. Il est principalement utilisé pour les cibles telles que les profils d'acteur qui possèdent des enregistrements de portée supplémentaires. Par exemple, une cascade de profils utilisateur ou d'agents peut supprimer les threads propriétaires eux-mêmes, les messages de portée thread et les enregistrements de type mémoire supprimés avec ces threads, ainsi que tous les enregistrements de portée acteur directs restants tels que les messages, les mémoires, les directives, les faits ou les préférences. Pour les suppressions de profil d'acteur, ce nettoyage ciblé peut toujours être exécuté lorsque la ligne de profil correspondante est déjà absente.
• Retours : nombre d'enregistrements de niveau supérieur demandés supprimés, généralement 0 ou 1. Les lignes enfant en cascade ne sont pas comptabilisées séparément. Il peut donc s'agir de 0 lorsqu'un profil d'acteur manquant déclenche un nettoyage ciblé.
• Type de retour : int

method delete_relations (résumé)

Supprimer les relations par identifiant.

L'état de cycle de vie est recalculé à partir des relations restantes.

• Paramètres : relation_ids str | list[str] – Identificateur ou identifiants des relations à supprimer.
• Retours : Nombre de relations supprimées.
• Type de retour : int

Exemples

store.delete_relations("relation-id")
1

method delete_relations_async (async)

Supprimer de manière asynchrone les relations par identificateur.

L'état de cycle de vie est recalculé à partir des relations restantes.

• Paramètres : relation_ids str | list[str] – Identificateur ou identifiants des relations à supprimer.
• Retours : Nombre de relations supprimées.
• Type de retour : int

Exemples

await store.delete_relations_async("relation-id")
1

method delete_thread (résumé)

Supprimer un thread et les données stockées associées.

• Paramètres : thread_id str – Identificateur du thread à enlever.
• Retours : nombre d'enregistrements de thread supprimés, généralement 0 ou 1.
• Type de retour : int

Notes

Il s'agit de l'opération de niveau magasin permettant de supprimer un thread et les enregistrements de niveau thread gérés par le magasin. Préférez la suppression de thread lorsque les exigences de conservation appellent la suppression des messages source et des données de mémoire dérivées de portée thread, car les suppressions au niveau message n'impliquent pas la suppression des enregistrements dérivés conservés séparément.

method delete_thread_async (async)

Supprimer de manière asynchrone un thread et les données stockées associées.

• Paramètres : thread_id str – Identificateur du thread à enlever.
• Retours : nombre d'enregistrements de thread supprimés, généralement 0 ou 1.
• Type de retour : int

Notes

Il s'agit de l'opération de niveau magasin permettant de supprimer un thread et les enregistrements de niveau thread gérés par le magasin. Préférez la suppression de thread lorsque les exigences de conservation appellent la suppression des messages source et des données de mémoire dérivées de portée thread, car les suppressions au niveau message n'impliquent pas la suppression des enregistrements dérivés conservés séparément.

method get (résumé)

Extraire un enregistrement stocké par type et identifiant.

• Paramètres:
  • record_type str – Type logique de l'enregistrement à extraire, tel que "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" ou "image".
  • record_id str – Identificateur de l'enregistrement à extraire.
  • include_bytes bool – Indique si les octets d'image stockés doivent être chargés. Pour un enregistrement de message, cette option détermine si les images jointes incluent leurs octets. Pour un enregistrement d'image, il contrôle si les octets d'image autonomes sont chargés. Cette option n'a aucun effet sur les autres types d'enregistrement.
• Retours : enregistrement stocké trouvé, sinon None. Une recherche "thread" renvoie une valeur ThreadRecord avec les métadonnées de thread, la configuration d'exécution, l'état d'exécution et l'horodatage de création renseignés lorsque la banque prend en charge les threads persistants.
• Type de retour : Enregistrement | Aucun

method get_async (async)

Extraire de manière asynchrone un enregistrement stocké par type et identifiant.

• Paramètres:
  • record_type str – Type logique de l'enregistrement à extraire, tel que "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" ou "image".
  • record_id str – Identificateur de l'enregistrement à extraire.
  • include_bytes bool – Indique si les octets d'image stockés doivent être chargés. Pour un enregistrement de message, cette option détermine si les images jointes incluent leurs octets. Pour un enregistrement d'image, il contrôle si les octets d'image autonomes sont chargés. Cette option n'a aucun effet sur les autres types d'enregistrement.
• Retours : enregistrement stocké trouvé, sinon None. Une recherche "thread" renvoie une valeur ThreadRecord avec les métadonnées de thread, la configuration d'exécution, l'état d'exécution et l'horodatage de création renseignés lorsque la banque prend en charge les threads persistants.
• Type de retour : Enregistrement | Aucun

method get_relation (résumé)

Renvoyer une relation dans son orientation source-cible stockée.

Fournissez relation_id seul ou fournissez un tuple complet d'adresse source à cible.

• Paramètres:
  • source_record_id str – Identifiant de l'enregistrement source. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • source_record_type str – Type d'enregistrement source. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • target_record_id str – Identificateur d'enregistrement cible. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • target_record_type str – Type d'enregistrement cible. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • relation_type str – Libellé de relation dirigée. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • relation_id str : identificateur de relation à mettre en correspondance directement. Fournissez cet argument seul plutôt que de le combiner avec des champs de type endpoint.
• Renvoie : relation correspondante, ou None lorsqu'elle n'existe pas.
• Type de retour : RecordRelation | Aucun

Exemples

store.get_relation(relation_id="relation-id")
RecordRelation(...)
store.get_relation(
    "source-id", "memory", "target-id", "fact", "supports"
)
RecordRelation(...)

method get_relation_async (async)

Extraire de manière asynchrone une relation par ID ou tuple d'adresse.

Fournissez relation_id seul ou fournissez un tuple complet d'adresse source à cible.

• Paramètres:
  • source_record_id str – Identifiant de l'enregistrement source. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • source_record_type str – Type d'enregistrement source. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • target_record_id str – Identificateur d'enregistrement cible. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • target_record_type str – Type d'enregistrement cible. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • relation_type str – Libellé de relation dirigée. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • relation_id str : identificateur de relation à mettre en correspondance directement. Fournissez cet argument seul plutôt que de le combiner avec des champs de type endpoint.
• Renvoie : relation correspondante, ou None lorsqu'elle n'existe pas.
• Type de retour : RecordRelation | Aucun

Exemples

await store.get_relation_async(relation_id="relation-id")
RecordRelation(...)

method list (résumé)

Répertoriez les enregistrements stockés pour un type d'enregistrement.

• Paramètres:
  • record_type str – Type d'enregistrement logique à énumérer, tel que "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile", ou "thread_summary" ou "image".
  • limit int | None : nombre maximal facultatif d'enregistrements les plus récents à renvoyer. Lorsqu'elles sont omises, les implémentations peuvent appliquer une limite supérieure sécurisée telle que MAX_LIST_LIMIT. Transmettez None pour désactiver cette limite et renvoyer tous les enregistrements correspondants.
  • thread_id str | None – Filtre de portée de thread exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements dont thread_id est None sont renvoyés. Les types d'enregistrements non ciblés ignorent ce filtre. Lorsque record_type est défini sur "thread", thread_id ne doit pas être défini. Utilisez record_id pour sélectionner un thread spécifique.
  • user_id str | None – Filtre de portée utilisateur exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements dont user_id est None sont renvoyés. Les types d'enregistrements non ciblés ignorent ce filtre.
  • agent_id str | None : filtre de portée d'agent exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements dont agent_id est None sont renvoyés. Les types d'enregistrements non ciblés ignorent ce filtre.

  • metadata_filter dict[str, Any] | None –

    Filtre de métadonnées. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements dont les métadonnées sont None sont renvoyés. Lorsqu'elle est définie sur une dictée, les entrées de metadata_filter sont combinées à la sémantique AND. Les entrées dont la valeur n'est pas un dictionnaire opérateur de niveau champ utilisent une sémantique de correspondance exacte : la clé demandée doit exister dans les métadonnées stockées. Les dictionnaires imbriqués sont mis en correspondance de manière récursive. Les valeurs scalaires et de liste sont mises en correspondance par égalité exacte ; l'ordre et la longueur de la liste doivent également correspondre. Pour tester l'appartenance à un tableau, utilisez un dictionnaire d'opérateurs de niveau champ tel que {"tags": {"$array_contains": "prod"}}. Un opérande de liste pour "$array_contains" signifie que toutes les valeurs répertoriées doivent être présentes ; "$array_contains_any" signifie qu'au moins une valeur répertoriée doit être présente. Utilisez "$not" pour annuler une autre expression de niveau champ sur le même champ, y compris un dictionnaire d'opérateur ou une valeur de correspondance exacte brute. Les expressions négatives correspondent lorsque l'expression positive échoue, y compris les champs manquants ; l'appartenance au tableau négatif correspond également aux champs non-tableau. Par exemple, metadata_filter={"source": "slack"} pour un champ scalaire, metadata_filter={"review": {"status": "open"}} pour un champ imbriqué et metadata_filter={"tags": ["prod", "urgent"]} pour une correspondance de liste exacte. Combinez les conditions pour les exiger toutes :

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

  • include_bytes bool : indique si les enregistrements d'image ou les images jointes aux enregistrements de message incluent leurs octets stockés. Lorsqu'elle est omise ou False, les descriptions d'image et les métadonnées sont renvoyées sans chargement d'octets. Pour les listes d'images directes, définissez-la sur True uniquement avec une valeur record_id exacte et au moins un filtre d'utilisateur, d'agent ou de portée de thread exact. Cette option n'a aucun effet sur les autres types d'enregistrement.
  • record_id str – Filtre d'identificateur d'enregistrement exact. Lorsqu'il est omis, les enregistrements avec n'importe quel identifiant sont renvoyés. Les filtres de portée et de métadonnées restent des contraintes supplémentaires.
• Retours : Enregistrements classés du plus ancien au plus récent dans la fenêtre renvoyée.
• Type de retour : Liste[Enregistrement]

method list_async (async)

Répertorie de manière asynchrone les enregistrements stockés pour un type d'enregistrement.

• Paramètres:
  • record_type str – Type d'enregistrement logique à énumérer, tel que "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" ou "image".
  • limit int | None : nombre maximal facultatif d'enregistrements les plus récents à renvoyer. Lorsqu'elles sont omises, les implémentations peuvent appliquer une limite supérieure sécurisée telle que MAX_LIST_LIMIT. Transmettez None pour désactiver cette limite et renvoyer tous les enregistrements correspondants.
  • thread_id str | None – Filtre de portée de thread exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements dont thread_id est None sont renvoyés. Les types d'enregistrements non ciblés ignorent ce filtre. Lorsque record_type est défini sur "thread", thread_id ne doit pas être défini. Utilisez record_id pour sélectionner un thread spécifique.
  • user_id str | None – Filtre de portée utilisateur exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements dont user_id est None sont renvoyés. Les types d'enregistrements non ciblés ignorent ce filtre.
  • agent_id str | None : filtre de portée d'agent exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements dont agent_id est None sont renvoyés. Les types d'enregistrements non ciblés ignorent ce filtre.

  • metadata_filter dict[str, Any] | None –

    Filtre de métadonnées. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements dont les métadonnées sont None sont renvoyés. Lorsqu'elle est définie sur une dictée, les entrées de metadata_filter sont combinées à la sémantique AND. Les entrées dont la valeur n'est pas un dictionnaire opérateur de niveau champ utilisent une sémantique de correspondance exacte : la clé demandée doit exister dans les métadonnées stockées. Les dictionnaires imbriqués sont mis en correspondance de manière récursive. Les valeurs scalaires et de liste sont mises en correspondance par égalité exacte ; l'ordre et la longueur de la liste doivent également correspondre. Pour tester l'appartenance à un tableau, utilisez un dictionnaire d'opérateurs de niveau champ tel que {"tags": {"$array_contains": "prod"}}. Un opérande de liste pour "$array_contains" signifie que toutes les valeurs répertoriées doivent être présentes ; "$array_contains_any" signifie qu'au moins une valeur répertoriée doit être présente. Utilisez "$not" pour annuler une autre expression de niveau champ sur le même champ, y compris un dictionnaire d'opérateur ou une valeur de correspondance exacte brute. Les expressions négatives correspondent lorsque l'expression positive échoue, y compris les champs manquants ; l'appartenance au tableau négatif correspond également aux champs non-tableau. Par exemple, metadata_filter={"source": "slack"} pour un champ scalaire, metadata_filter={"review": {"status": "open"}} pour un champ imbriqué et metadata_filter={"tags": ["prod", "urgent"]} pour une correspondance de liste exacte. Combinez les conditions pour les exiger toutes :

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

  • include_bytes bool : indique si les enregistrements d'image ou les images jointes aux enregistrements de message incluent leurs octets stockés. Lorsqu'elle est omise ou False, les descriptions d'image et les métadonnées sont renvoyées sans chargement d'octets. Pour les listes d'images directes, définissez-la sur True uniquement avec une valeur record_id exacte et au moins un filtre d'utilisateur, d'agent ou de portée de thread exact. Cette option n'a aucun effet sur les autres types d'enregistrement.
  • record_id str – Filtre d'identificateur d'enregistrement exact. Lorsqu'il est omis, les enregistrements avec n'importe quel identifiant sont renvoyés. Les filtres de portée et de métadonnées restent des contraintes supplémentaires.
• Retours : Enregistrements classés du plus ancien au plus récent dans la fenêtre renvoyée.
• Type de retour : Liste[Enregistrement]

method list_relations (résumé)

Répertoriez les relations stockées dans leur orientation source-cible.

• Paramètres:
  • relation_type str – Libellé de relation dirigée facultatif à mettre en correspondance, tel que "supports" ou "supersedes". Omettez d'inclure tous les types de relation.
  • source_record_id str : identificateur d'enregistrement source facultatif à mettre en correspondance.
  • source_record_type str – Type d'enregistrement source à mettre en correspondance (facultatif).
  • target_record_id str – Identificateur d'enregistrement cible facultatif à mettre en correspondance.
  • target_record_type str – Type d'enregistrement cible facultatif à mettre en correspondance.
  • limit int | None – Nombre maximum facultatif de relations créées au plus tôt à renvoyer. Lorsqu'elles sont omises, les implémentations peuvent appliquer une limite supérieure sécurisée telle que MAX_LIST_LIMIT. Transmettez None pour renvoyer toutes les relations stockées correspondantes.
  • metadata_filter dict[str, Any] | None – Filtre de métadonnées. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seules les relations dont les métadonnées sont None sont renvoyées. Lorsqu'elle est définie sur un dict, les entrées sont combinées à la sémantique AND. Les dictionnaires imbriqués utilisent une correspondance exacte récursive. Les valeurs scalaires et de liste nécessitent une égalité exacte ; utilisez {"tags": {"$array_contains": "prod"}} pour mettre en correspondance l'appartenance au tableau, "$array_contains_any" pour mettre en correspondance toute valeur répertoriée ou "$not" pour annuler une autre expression de champ.
  • relation_id str – Filtre d'identificateur de relation exact. Lorsqu'elle est omise, les relations avec n'importe quel identificateur sont renvoyées. D'autres filtres restent des contraintes supplémentaires.
• Retours : Relations triées par heure de création et identifiant.
• Type de retour : list[RecordRelation]

Exemples

store.list_relations(
    source_record_id="current-memory",
    relation_type="supports",
    metadata_filter={"source": "manual"},
)
[RecordRelation(...)]

method list_relations_async (async)

Répertorie de manière asynchrone les relations dans l'orientation source-cible.

• Paramètres:
  • relation_type str – Libellé de relation dirigée facultatif à mettre en correspondance, tel que "supports" ou "supersedes". Omettez d'inclure tous les types de relation.
  • source_record_id str : identificateur d'enregistrement source facultatif à mettre en correspondance.
  • source_record_type str – Type d'enregistrement source à mettre en correspondance (facultatif).
  • target_record_id str – Identificateur d'enregistrement cible facultatif à mettre en correspondance.
  • target_record_type str – Type d'enregistrement cible facultatif à mettre en correspondance.
  • limit int | None – Nombre maximum facultatif de relations créées au plus tôt à renvoyer. Lorsqu'elles sont omises, les implémentations peuvent appliquer une limite supérieure sécurisée telle que MAX_LIST_LIMIT. Transmettez None pour renvoyer toutes les relations stockées correspondantes.
  • metadata_filter dict[str, Any] | None – Filtre de métadonnées. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seules les relations dont les métadonnées sont None sont renvoyées. Lorsqu'elle est définie sur un dict, les entrées sont combinées à la sémantique AND. Les dictionnaires imbriqués utilisent une correspondance exacte récursive. Les valeurs scalaires et de liste nécessitent une égalité exacte ; utilisez {"tags": {"$array_contains": "prod"}} pour mettre en correspondance l'appartenance au tableau, "$array_contains_any" pour mettre en correspondance toute valeur répertoriée ou "$not" pour annuler une autre expression de champ.
  • relation_id str : identificateur de relation facultatif à mettre en correspondance directement.
• Retours : Relations triées par heure de création et identifiant.
• Type de retour : list[RecordRelation]

Exemples

await store.list_relations_async(
    source_record_id="current-memory", relation_type="supports"
)
[RecordRelation(...)]

method list_thread_messages (résumé)

Répertoriez l'historique des messages stockés pour un thread.

• Paramètres:
  • thread_id str – Identificateur du thread dont les messages doivent être renvoyés.
  • last_n int | None : nombre facultatif de messages les plus récents à inclure. Lorsqu'il est omis, tous les messages stockés pour le thread sont renvoyés. Lorsqu'elle est combinée à une plage de séquences, la limite s'applique à l'intérieur de cette plage.
  • range_start_seq_no int | None : limite de séquence inférieure inclusive facultative. Seuls les messages dont seq_no est au moins cette valeur sont renvoyés.
  • range_end_seq_no int | None : limite de séquence supérieure exclusive facultative. Seuls les messages dont la valeur seq_no est inférieure à cette valeur sont renvoyés.
  • include_bytes bool : indique si les parties d'image attachées aux messages renvoyés incluent leurs octets stockés. Lorsqu'elle est omise ou False, les descriptions d'image et les métadonnées sont renvoyées sans chargement d'octets.
• Retours : Enregistrements de message classés du plus ancien au plus récent dans la fenêtre renvoyée.
• Type de retour : List[MessageRecord]

method list_thread_messages_async (async)

Répertoriez de manière asynchrone l'historique des messages stockés pour un thread.

• Paramètres:
  • thread_id str – Identificateur du thread dont les messages doivent être renvoyés.
  • last_n int | None : nombre facultatif de messages les plus récents à inclure. Lorsqu'il est omis, tous les messages stockés pour le thread sont renvoyés. Lorsqu'elle est combinée à une plage de séquences, la limite s'applique à l'intérieur de cette plage.
  • range_start_seq_no int | None : limite de séquence inférieure inclusive facultative. Seuls les messages dont seq_no est au moins cette valeur sont renvoyés.
  • range_end_seq_no int | None : limite de séquence supérieure exclusive facultative. Seuls les messages dont la valeur seq_no est inférieure à cette valeur sont renvoyés.
  • include_bytes bool : indique si les parties d'image attachées aux messages renvoyés incluent leurs octets stockés. Lorsqu'elle est omise ou False, les descriptions d'image et les métadonnées sont renvoyées sans chargement d'octets.
• Retours : Enregistrements de message classés du plus ancien au plus récent dans la fenêtre renvoyée.
• Type de retour : List[MessageRecord]

method search (résumé)

Rechercher des enregistrements par similarité.

• Paramètres:
  • query str | None : requête en langage naturel. Doit être fourni lorsque query_vector est omis.
  • query_vector list[float] | None : intégration de requête précalculée facultative. Vous devez fournir exactement l'une des options query et query_vector.
  • k int – Nombre maximum de résultats à renvoyer. Les valeurs explicites doivent être au moins 1. Limite supérieure : l'appel peut renvoyer moins de résultats k lorsque les filtres sont trop restrictifs, lorsqu'il existe moins d'enregistrements correspondants non expirés ou en raison d'un comportement de recherche propre à l'implémentation.
  • thread_id str | None – Portée de thread facultative.
  • user_id str | None : filtres de portée utilisateur et agent facultatifs.
  • agent_id str | None : filtres de portée utilisateur et agent facultatifs.
  • exact_user_match bool : indique si chaque identificateur de portée fourni doit correspondre exactement.
  • exact_agent_match bool : indique si chaque identificateur de portée fourni doit correspondre exactement.
  • exact_thread_match bool : indique si chaque identificateur de portée fourni doit correspondre exactement.
  • record_types set[str] | None – Ensemble facultatif de types d'enregistrement à inclure.
  • metadata_filter dict[str, Any] | None – Mappage de filtre de métadonnées facultatif. Les entrées dans metadata_filter sont combinées avec la sémantique AND. Les entrées dont la valeur n'est pas un dictionnaire opérateur de niveau champ utilisent une sémantique de correspondance exacte : la clé demandée doit exister dans les métadonnées stockées. Les dictionnaires imbriqués sont mis en correspondance de manière récursive. Les valeurs scalaires et de liste sont mises en correspondance par égalité exacte ; l'ordre et la longueur de la liste doivent également correspondre. Pour tester l'appartenance à un tableau, utilisez un dictionnaire d'opérateurs de niveau champ tel que {"tags": {"$array_contains": "prod"}}. Un opérande de liste pour "$array_contains" signifie que toutes les valeurs répertoriées doivent être présentes ; "$array_contains_any" signifie qu'au moins une valeur répertoriée doit être présente. Utilisez "$not" pour annuler une autre expression de niveau champ sur le même champ, y compris un dictionnaire d'opérateur ou une valeur de correspondance exacte brute. Les expressions négatives correspondent lorsque l'expression positive échoue, y compris les champs manquants ; l'appartenance au tableau négatif correspond également aux champs non-tableau.
  • include_invalid_results bool : indique si les résultats incluent des enregistrements de type mémoire dont le statut n'est pas valide. La valeur par défaut est True. Transmettez False pour les exclure.
  • num_hops int – Nombre d'arêtes de liaison mémoire à suivre à partir de chaque résultat de mémoire directe. Les valeurs comprises entre 0 et 5 sont prises en charge ; 0 désactive l'extension de graphique.
  • max_linked_results int – Nombre maximal de mémoires liées dans tous les sauts attachés à chaque résultat direct. 0 conserve les résultats directs sans contexte lié. Par défaut, 100 est utilisé.
• Renvoie : paires (record, distance) triées par distance croissante. La liste peut contenir moins de k entrées.
• Type de retour : list[tuple[Record, float]]
• Elèves : ValueError – Si k est inférieur à 1.

Exemples

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'

Filtrer sur une valeur de métadonnées scalaire :

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

Filtrer sur les métadonnées imbriquées :

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

Faites correspondre exactement une valeur de liste, y compris l'ordre :

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

Filtrer lorsqu'un tableau de métadonnées contient une valeur :

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

Combinez plusieurs conditions de métadonnées. Un enregistrement doit satisfaire toutes les clés :

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

method search_async (async)

Rechercher des enregistrements de manière asynchrone par similarité sémantique.

• Paramètres:
  • query str | None : même texte de requête accepté par search.
  • k int : nombre de résultats maximal identique accepté par search. Les valeurs explicites doivent être au moins 1.
  • query_vector list[float] | None – Même intégration de requête précalculée facultative acceptée par search.
  • thread_id str | None – Les mêmes filtres de portée facultatifs acceptés par search.
  • user_id str | None – Les mêmes filtres de portée facultatifs acceptés par search.
  • agent_id str | None – Les mêmes filtres de portée facultatifs acceptés par search.
  • exact_user_match bool – Les mêmes indicateurs de correspondance exacte acceptés par search.
  • exact_agent_match bool : indicateurs de correspondance exacte acceptés par search.
  • exact_thread_match bool : indicateurs de correspondance exacte acceptés par search.
  • record_types set[str] | None – Même filtre facultatif de type d'enregistrement accepté par search.
  • metadata_filter dict[str, Any] | None – Même filtre de métadonnées facultatif accepté par search, y compris scalaire, imbriqué, liste exacte, appartenance à un tableau et conditions combinées telles que {"source": "slack"}, {"review": {"status": "open"}}, {"tags": ["prod", "urgent"]} et {"tags": {"$array_contains": "prod"}}.
  • include_invalid_results bool – Option de résultat avec le même statut de cycle de vie acceptée par search.
  • num_hops int – Profondeur d'extension de graphique identique acceptée par search.
  • max_linked_results int – Même limite de mémoire liée par résultat direct acceptée par search.
• Renvoie : paires (record, distance) renvoyées par l'appel search sous-jacent.
• Type de retour : List[tuple[Record, float]]
• Elèves : ValueError – Si k est inférieur à 1.

method update (résumé)

Mettre à jour le contenu des enregistrements stockés, l'intégration des données, les métadonnées, l'horodatage ou l'expiration.

• Paramètres:
  • record_type str – Type logique de l'enregistrement à mettre à jour.
  • record_id str – Identifiant de l'enregistrement à mettre à jour.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None – Contenu de remplacement canonique. Pour les enregistrements message, transmettez une chaîne ou une séquence ordonnée de parties de contenu de texte et d'image. Utilisez "" pour remplacer le message par du texte vide. Pour les enregistrements de type mémoire, les magasins peuvent accepter None pour effacer le texte stocké et l'état sémantique associé. Omettez l'argument pour laisser le contenu inchangé. N'indiquez pas ceci avec text.
  • index_text str | list[str] | None : charge utile sémantique alternative facultative utilisée pour recalculer ou remplacer l'état de recherche stocké sans modifier le texte persistant. Une chaîne peut être découpée en interne par le magasin. Une liste de chaînes non vides est traitée comme des blocs appartenant à l'appelant et ne doit pas être divisée à nouveau. Certaines implémentations peuvent également persister séparément en tant que texte de recherche hybride. Pour un enregistrement image, ce champ remplace la description de l'image persistante.
  • embedding list[float] | ndarray | list[list[float] | ndarray] | None : vecteur d'intégration précalculé facultatif ou liste de vecteurs d'intégration de blocs. Lorsqu'elle est fournie, elle est utilisée directement et aucun appel d'intégration n'est effectué. Plusieurs vecteurs nécessitent la mise en correspondance de listes de blocs index_text ou de lignes de texte de bloc stockées existantes. Transmettez None pour effacer explicitement l'intégration stockée lorsque l'emplacement de stockage la prend en charge. Les magasins avec indexation prenant en charge le texte peuvent également permettre des mises à jour sémantiques sans incorporation ou intégration explicite.
  • metadata dict[str, Any] | None – Mappage de métadonnées de remplacement facultatif. Transmettez None pour effacer les métadonnées lorsque la banque les prend en charge. Le remplacement de l'image content requiert "image_mime_type" dans ce mapping. Le magasin utilise ce champ pour enregistrer l'image, mais ne la renvoie pas dans les métadonnées de l'enregistrement.
  • timestamp str | None : nouvel horodatage facultatif à enregistrer avec l'enregistrement. Il indique la date de création de l'enregistrement. Omettez cet argument pour laisser l'horodatage stocké inchangé. Transmettez None pour effacer l'horodatage enregistré et utiliser l'heure à laquelle l'enregistrement a été ajouté au magasin lorsque celui-ci est pris en charge par le magasin.
  • ttl_days int | None : actualisation facultative de l'expiration en jours. Omettez cet argument avec ttl_anchor pour conserver l'horodatage d'expiration en cours. Transmettez None pour effacer l'expiration.
  • ttl_anchor TimeToLiveAnchor : ancre de durée de vie facultative pour une actualisation d'expiration. Utilisez TimeToLiveAnchor.CREATED_AT pour l'heure de création de l'enregistrement ou TimeToLiveAnchor.TIMESTAMP pour le remplacement timestamp fourni dans la même mise à jour, ou l'horodatage de l'événement stocké lorsque timestamp est omis. Si vous indiquez ttl_anchor sans ttl_days, la durée de vie par défaut du stockage ou du schéma est utilisée. Lorsque ttl_anchor est omis lors d'une actualisation, les implémentations utilisent TimeToLiveAnchor.CREATED_AT.
  • status RecordStatus : statut du cycle de vie de remplacement facultatif pour les enregistrements.

  • text str | None –

    Alias obsolète pour content. Transmettez None pour effacer explicitement le texte stocké lorsque le magasin le prend en charge. N'indiquez pas ceci avec content.

    Obsolète

    Obsolète depuis la version 26.8.0 : Ce paramètre est obsolète dans la version 26.8.0 et sera supprimé dans la version 27.1. Utilisez plutôt content.

• Retours : Nombre d'enregistrements mis à jour (0 ou 1). Une valeur renvoyée de 0 signifie qu'aucun enregistrement n'a été mis à jour.
• Type de retour : int
• Elèves : ValueError – Si la charge utile de mise à jour n'est pas valide pour le magasin, par exemple en omettant tous les champs facultatifs ou en fournissant des arguments sémantiques contradictoires.

method update_async (async)

Mettre à jour de manière asynchrone le contenu des enregistrements stockés, l'intégration des données, les métadonnées, l'horodatage ou l'expiration.

• Paramètres:
  • record_type str – Type logique de l'enregistrement à mettre à jour.
  • record_id str – Identifiant de l'enregistrement à mettre à jour.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None – Contenu de remplacement canonique. Pour les enregistrements message, transmettez une chaîne ou une séquence ordonnée de parties de contenu de texte et d'image. Utilisez "" pour remplacer le message par du texte vide. Pour les enregistrements de type mémoire, les magasins peuvent accepter None pour effacer le texte stocké et l'état sémantique associé. Omettez l'argument pour laisser le contenu inchangé. N'indiquez pas ceci avec text.
  • index_text str | list[str] | None : charge utile sémantique alternative facultative utilisée pour recalculer ou remplacer l'état de recherche stocké sans modifier le texte persistant. Une chaîne peut être découpée en interne par le magasin. Une liste de chaînes non vides est traitée comme des blocs appartenant à l'appelant et ne doit pas être divisée à nouveau. Certaines implémentations peuvent également persister séparément en tant que texte de recherche hybride. Pour un enregistrement image, ce champ remplace la description de l'image persistante.
  • embedding list[float] | ndarray | list[list[float] | ndarray] | None : vecteur d'intégration précalculé facultatif ou liste de vecteurs d'intégration de blocs. Lorsqu'elle est fournie, elle est utilisée directement et aucun appel d'intégration n'est effectué. Plusieurs vecteurs nécessitent la mise en correspondance de listes de blocs index_text ou de lignes de texte de bloc stockées existantes. Transmettez None pour effacer explicitement l'intégration stockée lorsque l'emplacement de stockage la prend en charge. Les magasins avec indexation prenant en charge le texte peuvent également permettre des mises à jour sémantiques sans incorporation ou intégration explicite.
  • metadata dict[str, Any] | None – Mappage de métadonnées de remplacement facultatif. Transmettez None pour effacer les métadonnées lorsque la banque les prend en charge. Le remplacement de l'image content requiert "image_mime_type" dans ce mapping. Le magasin utilise ce champ pour enregistrer l'image, mais ne la renvoie pas dans les métadonnées de l'enregistrement.
  • timestamp str | None : nouvel horodatage facultatif à enregistrer avec l'enregistrement. Il indique la date de création de l'enregistrement. Omettez cet argument pour laisser l'horodatage stocké inchangé. Transmettez None pour effacer l'horodatage enregistré et utiliser l'heure à laquelle l'enregistrement a été ajouté au magasin lorsque celui-ci est pris en charge par le magasin.
  • ttl_days int | None : actualisation facultative de l'expiration en jours. Omettez cet argument avec ttl_anchor pour conserver l'horodatage d'expiration en cours. Transmettez None pour effacer l'expiration.
  • ttl_anchor TimeToLiveAnchor : ancre de durée de vie facultative pour une actualisation d'expiration. Utilisez TimeToLiveAnchor.CREATED_AT pour l'heure de création de l'enregistrement ou TimeToLiveAnchor.TIMESTAMP pour le remplacement timestamp fourni dans la même mise à jour, ou l'horodatage de l'événement stocké lorsque timestamp est omis. Si vous indiquez ttl_anchor sans ttl_days, la durée de vie par défaut du stockage ou du schéma est utilisée. Lorsque ttl_anchor est omis lors d'une actualisation, les implémentations utilisent TimeToLiveAnchor.CREATED_AT.
  • status RecordStatus : statut du cycle de vie de remplacement facultatif pour les enregistrements. Omettez-le pour conserver le statut actuel.

  • text str | None –

    Alias obsolète pour content. Transmettez None pour effacer explicitement le texte stocké lorsque le magasin le prend en charge. N'indiquez pas ceci avec content.

    Obsolète

    Obsolète depuis la version 26.8.0 : Ce paramètre est obsolète dans la version 26.8.0 et sera supprimé dans la version 27.1. Utilisez plutôt content.

• Retours : Nombre d'enregistrements mis à jour (0 ou 1). Une valeur renvoyée de 0 signifie qu'aucun enregistrement n'a été mis à jour.
• Type de retour : int
• Elèves : ValueError – Si la charge utile de mise à jour n'est pas valide pour le magasin, par exemple en omettant tous les champs facultatifs ou en fournissant des arguments sémantiques contradictoires.

method update_relations (résumé)

Mettez à jour les valeurs mutables sur les relations stockées.

Les champs omis restent inchangés, sauf que le passage à un type de relation mémoire intégré remplace son libellé inverse par l'inverse fixe. Une banque de mémoire soutenue par une base de données recalcule également les états de cycle de vie des adresses après une modification de type de relation.

• Paramètres:
  • relation_ids str | list[str] – Identificateur ou identificateurs des relations à mettre à jour.
  • relation_types str | list[str] : libellé ou libellé de relation dirigée de remplacement facultatif. Omettez-la pour conserver les étiquettes stockées.
  • opposite_relation_types str | list[str] : libellé ou libellé de relation inverse de remplacement facultatif. Transmettez une étiquette pour la remplacer ou omettez cet argument pour la conserver.
  • timestamps str | None | list[str | None] : horodatage ou horodatage de remplacement facultatif. Transmettez None pour effacer un horodatage stocké.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None] – Objets de métadonnées de remplacement facultatifs. Les métadonnées fournies remplacent l'objet stocké ; il n'est pas fusionné.
• Retours : Identifiants des relations qui ont été mises à jour.
• Type de retour : list[str]

Exemples

store.update_relations(
    "relation-id", relation_types="supports"
)
['relation-id']

method update_relations_async (async)

Mettre à jour de manière asynchrone les valeurs mutables sur les relations stockées.

Les champs omis restent inchangés, sauf que le passage à un type de relation mémoire intégré remplace son libellé inverse par l'inverse fixe. Une banque de mémoire soutenue par une base de données recalcule également les états de cycle de vie des adresses après une modification de type de relation.

• Paramètres:
  • relation_ids str | list[str] – Identificateur ou identificateurs des relations à mettre à jour.
  • relation_types str | list[str] : libellé ou libellé de relation dirigée de remplacement facultatif. Omettez-la pour conserver les étiquettes stockées.
  • opposite_relation_types str | list[str] : libellé ou libellé de relation inverse de remplacement facultatif. Transmettez une étiquette pour la remplacer ou omettez cet argument pour la conserver.
  • timestamps str | None | list[str | None] : horodatage ou horodatage de remplacement facultatif. Transmettez None pour effacer un horodatage stocké.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None] – Objets de métadonnées de remplacement facultatifs. Les métadonnées fournies remplacent l'objet stocké ; il n'est pas fusionné.
• Retours : Identifiants des relations qui ont été mises à jour.
• Type de retour : list[str]

Exemples

await store.update_relations_async(
    "relation-id", relation_types="supports"
)
['relation-id']

Banque Oracle DB

classe oracleagentmemory.core.OracleDBMemoryStore

Bases : OracleMemoryStore

Persistance basée sur la base de données pour les messages, documents, mémoires et profils d'acteur.

Créez une banque Oracle DB.

• Paramètres:
  • embedder IEmbedder | None – Embedder utilisé lorsque le magasin a besoin d'intégrer des vecteurs locaux. Peut être None lorsque les appelants fournissent toujours des vecteurs précalculés ou lorsque la recherche par mot-clé est utilisée avec des écritures de texte uniquement et des requêtes de texte. SearchStrategy.HYBRID requiert OracleDBEmbedder ici afin que l'index hybride géré puisse utiliser le modèle dans la base de données de cette intégration.
  • pool Any : connexion ou pool Oracle DB. La transmission d'une connexion brute active le mode de session unique pour cette instance de stockage : les appels de stockage simultanés sont sérialisés localement afin de préserver les hypothèses de verrouillage de ligne et de transaction utilisées par les opérations d'écriture. Utilisez un pool de connexions pour les demandes simultanées.
  • schema_policy SchemaPolicy | str : contrôle la façon dont le schéma géré est ouvert ou préparé. Exige par défaut un schéma existant à jour et n'apporte aucune modification LDD. Pour un emplacement de stockage identifié par memory_store_id, SchemaPolicy.CREATE_IF_NECESSARY crée ou répare le schéma en cas de besoin. SchemaPolicy.RECREATE le supprime et le recrée. Les anciennes versions de schéma nécessitent une mise à niveau de schéma de package avant de pouvoir être réparées. Lorsque schema_owner est défini, utilisez SchemaPolicy.REQUIRE_EXISTING pour l'accès inter-schéma ordinaire ou SchemaPolicy.NO_CHECK pour l'accès d'exécution Deep Data Security. Les deux empêchent les instructions LDD de schéma gérées, notamment la création, la réparation, la recréation et la première création d'index hybride. Effectuez ces actions lorsque vous êtes connecté en tant qu'utilisateur de base de données propriétaire sans schema_owner. Aucun des deux modes ne rend le magasin en lecture seule : les lectures et écritures de mémoire normales utilisent l'autorisation de base de données effective de l'utilisateur de connexion. Pour accéder à l'exécution Deep Data Security, utilisez SchemaPolicy.NO_CHECK et créez l'emplacement de stockage tant qu'un élément OracleMemoryEndUserSecurityContext est actif. L'emplacement de stockage résultant nécessite un contexte utilisateur actif pour chaque opération de base de données ultérieure. Les stratégies de schéma autres que NO_CHECK rejettent les contextes d'utilisateur final actifs, de sorte que le travail du cycle de vie du schéma ne peut pas être exécuté accidentellement en tant qu'utilisateur final.
  • vector_dim int | None : dimension d'intégration facultative pour le stockage vectoriel local. Transmettez un entier positif pour créer la colonne d'intégration gérée et l'index vectoriel, et pour valider les métadonnées de schéma existantes par rapport à cette dimension. Transmettez None ou omettez l'argument lorsque cette banque n'a pas besoin de stockage vectoriel local. La recherche par mot-clé et hybride peut fonctionner à partir de texte de recherche stocké sans la colonne d'intégration locale. La recherche vectorielle nécessite un stockage vectoriel local. Lorsque cet argument est omis et que le back-end de recherche effectif est la recherche vectorielle, la banque utilise embedder.embedding_dimension lorsqu'un intégrateur est disponible.

  • table_name_prefix str –

    Préfixe facultatif ajouté aux noms de table/index gérés. Transmettez ceci ou memory_store_id, pas les deux.

    Obsolète

    Obsolète depuis la version 26.6.0 : Ce paramètre est obsolète depuis la version 26.6.0 et sera supprimé depuis la version 27.1. Utilisez plutôt memory_store_id.

  • memory_store_id str – ID stable de la banque de mémoire de base de données gérée. Réutilisez le même ID pour rouvrir le même magasin géré. L'ID est joint aux noms d'objet de base de données gérée avec un trait de soulignement. Il doit donc commencer par une lettre, ne contenir que des lettres, des chiffres et des traits de soulignement et ne pas dépasser 16 caractères. Transmettez ceci ou table_name_prefix, pas les deux. Si cette option est omise, le magasin utilise table_name_prefix ou la valeur par défaut sans préfixe lorsque table_name_prefix est également omis. La création, la réparation ou la recréation d'un magasin dans le schéma de l'utilisateur de connexion requiert un package DBMS_AGENT_MEMORY_STORE compatible dans ce schéma.
  • schema_owner str : propriétaire de schéma facultatif pour une banque de mémoire gérée existante. Omettez cette option pour utiliser le schéma de l'utilisateur de connexion. L'argument pool peut être une connexion de base de données brute ou un pool de connexions. Utilisez cette option lorsqu'il appartient à un utilisateur de base de données d'application disposant d'autorisations sur des tables appartenant à un autre utilisateur. Cette option est uniquement destinée à l'exécution d'un accès à une banque de mémoire gérée déjà créée. Utilisez SchemaPolicy.REQUIRE_EXISTING pour un accès inter-schéma ordinaire ou SchemaPolicy.NO_CHECK avec un contexte de sécurité utilisateur actif pour une banque protégée par la sécurité des données en profondeur. Créez, mettez à niveau ou recréez la banque de mémoire gérée lorsque vous êtes connecté en tant que propriétaire du schéma et omettez cette option. Transmettez un identificateur sans guillemets ; les entrées en minuscules sont normalisées en majuscules et les propriétaires de schéma entre guillemets ne sont pas pris en charge. Accordez CREATE SESSION et les privilèges objet requis à l'utilisateur de base de données d'application. Reportez-vous à la section Database Users and Privileges du guide de dépannage pour connaître les autorisations exactes. Vous pouvez également afficher les vues d'objet géré portant le même nom dans le schéma d'exécution et omettre schema_owner. Cette option est prise en charge uniquement pour SchemaPolicy.REQUIRE_EXISTING.
  • search_strategy SearchStrategy – Valeur SearchStrategy qui sélectionne le back-end pour search(). Utilisez SearchStrategy.VECTOR (valeur par défaut) pour l'extraction vectorielle uniquement, SearchStrategy.HYBRID pour interroger un index vectoriel hybride Oracle géré sur le texte de recherche stocké ou SearchStrategy.KEYWORD pour effectuer un classement par correspondance mot-clé/texte sur le texte de recherche stocké sans fusion vectorielle. KEYWORD ne nécessite pas d'intégrateur. HYBRID requiert que embedder soit une valeur OracleDBEmbedder afin que l'index hybride géré utilise le même modèle dans la base de données que l'intégrateur de banque principale. Si un client de mot-clé ouvre un schéma hybride existant, le magasin peut utiliser la branche de texte de cet index hybride. Le démarrage échoue lorsqu'une stratégie incompatible est utilisée avec un schéma existant car ce schéma peut ne pas contenir l'état de recherche stocké dont la stratégie a besoin. Lorsque schema_policy=SchemaPolicy.REQUIRE_EXISTING et cet argument sont omis, le stockage au mieux détecte le mode de recherche stocké du schéma à partir des métadonnées gérées et utilise ce mode lorsqu'il est disponible.
  • search_index_sync SearchIndexSyncMode – Valeur SearchIndexSyncMode qui sélectionne le comportement d'actualisation de l'index de recherche géré pour SearchStrategy.HYBRID et SearchStrategy.KEYWORD. SearchIndexSyncMode.ON_COMMIT est la valeur par défaut et permet de rechercher des enregistrements dès que la transaction d'écriture est validée. SearchIndexSyncMode.MANUAL laisse l'actualisation à une opération de synchronisation explicite côté base de données. SearchIndexSyncMode.AUTO permet à Oracle d'actualiser l'index hybride géré de manière asynchrone et n'est pris en charge qu'avec SearchStrategy.HYBRID ; la recherche par mot-clé rejette AUTO.
  • memory_retention_config MemoryRetentionConfig : configuration facultative de la conservation de la mémoire pour les messages et les mémoires sauvegardés par la base de données. MemoryRetentionConfig.default_ttl_days est utilisé lorsqu'une nouvelle écriture omet ttl_days. MemoryRetentionConfig.max_ttl_days fixe les durées explicites par enregistrement au-dessus de la valeur maximale configurée avec un avertissement et, lorsqu'il est défini, ttl_days=None utilise cette valeur maximale au lieu de créer des lignes qui n'expirent pas. Avec SchemaPolicy.CREATE_IF_NECESSARY, une configuration explicite actualise les métadonnées stockées sur un schéma géré à jour existant, mais elle ne met pas à jour les dates d'expiration existantes. Si vous omettez cette opération, le paramètre existant est conservé. Si une configuration explicite laisse default_ttl_days ou max_ttl_days dans NOT_SET_MARKER, le kit SDK résout cet attribut à sa valeur par défaut (None) avant de comparer ou de stocker les métadonnées de schéma. Choisissez cette configuration en fonction des informations attendues stockées dans les enregistrements, des raisons pour lesquelles l'application la conserve et des engagements de conservation des applications ou des réglementations.
• Elèves : RuntimeError – Si un contexte de sécurité de l'utilisateur final est actif avec une stratégie de schéma autre que SchemaPolicy.NO_CHECK, ou si une banque d'exécution NO_CHECK est ouverte ou utilisée sans contexte de sécurité de l'utilisateur final actif.

Avertissement : SchemaPolicy.CREATE_IF_NECESSARY peut être plus coûteux que le démarrage normal de l'emplacement de stockage car il peut réparer des objets de schéma gérés avant la réussite de l'initialisation. Planifier le travail de réparation en tant qu'opération de maintenance lorsqu'un schéma peut contenir de nombreuses lignes. Une banque sur une ancienne version de schéma nécessite une mise à niveau de schéma de package avant l'initialisation.

Si la configuration du schéma doit créer le travail de purge géré des enregistrements expirés mais que l'utilisateur de base de données ne dispose pas du privilège Scheduler-job, l'initialisation avertit et continue. Les messages et les mémoires expirés restent masqués lors des lectures et des recherches, mais ils ne sont pas purgés physiquement tant que le travail n'est pas créé par un utilisateur disposant du privilège CREATE JOB ou d'un planificateur équivalent.

Lorsque SchemaPolicy.CREATE_IF_NECESSARY crée pour la première fois un index hybride géré sur un schéma existant, Oracle analyse le texte de recherche stocké et crée l'état de l'index hybride géré à partir du modèle dans la base de données configuré. L'initialisation du stockage attend la fin de ce script LDD. Planifiez donc la première mise à niveau hybride en tant qu'opération de migration ou de maintenance pour les schémas volumineux. SearchIndexSyncMode contrôle la maintenance en cours après l'existence de l'index. Il ne rend pas le premier build d'index asynchrone.

La création de cet index hybride géré crée également une préférence de vecteur DBMS_VECTOR_CHAIN nommée par le schéma géré. La préférence stocke les métadonnées de configuration du vecteur léger à partir du modèle OracleDBEmbedder configuré. Il peut être inspecté à l'aide des vues de préférences Oracle Text telles que CTX_USER_PREFERENCES et CTX_USER_PREFERENCE_VALUES.

méthode add

Ajoutez des enregistrements à la banque Oracle DB.

• Paramètres:
  • contents Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None] – Séquence en lecture seule des charges utiles d'enregistrement. Les entrées de message peuvent contenir des pièces de MessageContent commandées. Les entrées de récapitulatif de thread peuvent être des correspondances, des chaînes qui deviennent des objets {"text": value} ou None stockées en tant que null JSON. Les valeurs de texte sont également utilisées pour la recherche, sauf si index_texts est fourni. Pour les autres types d'enregistrement, None peut revenir à metadata["content"]. Les chaînes vides explicites sont conservées.
  • record_type str – Type d'enregistrement logique à créer, tel que "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" ou "thread_summary".
  • index_texts list[str | list[str] | None] – Charge utile alternative facultative utilisée comme texte de recherche. Utilisez cette option pour contrôler les index de recherche hybride ou par mot-clé soutenus par la base de données. Chaque entrée de liste externe correspond à un enregistrement. Une entrée de chaîne peut être découpée par bloc par le magasin. Une entrée de liste est traitée comme des blocs appartenant à l'appelant et écrite telle quelle à RECORD_CHUNKS.chunk_text. Lorsque embeddings est également fourni, les entrées de liste nécessitent exactement un vecteur par bloc ; les entrées de chaîne n'acceptent qu'un seul vecteur pour cet enregistrement.

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

    vecteurs d'intégration précalculés facultatifs alignés sur contents. Chaque entrée d'enregistrement peut être un vecteur ou une liste de vecteurs de bloc. Lorsque le stockage vectoriel local est configuré, ces vecteurs sont stockés directement en tant que représentation vectorielle de l'enregistrement au lieu d'appeler l'intégrateur du magasin pour créer des vecteurs locaux pour l'écriture. Un seul vecteur représente l'ensemble du texte sémantique, même lorsque le bloc configuré le diviserait autrement. Plusieurs vecteurs de bloc nécessitent des listes de blocs index_texts correspondantes.

    Dans SearchStrategy.VECTOR, la recherche vectorielle se classe par rapport aux vecteurs stockés. Dans SearchStrategy.HYBRID ou SearchStrategy.KEYWORD, la recherche soutenue par la base de données se classe par le texte de recherche stocké et l'état d'index hybride ou de texte géré par Oracle, de sorte que les incorporations d'ajout/d'ajout affectent uniquement tout stockage vectoriel local configuré, et non cette stratégie de recherche active. Si cette banque a été configurée sans stockage vectoriel local, indiquez index_texts au lieu de embeddings pour remplacer le texte visible par ces index sensibles au texte.

  • record_ids str | None | list[str | None] : identificateurs invisibles par l'appelant (facultatif). Une seule chaîne peut être utilisée pour les insertions d'un enregistrement, tandis que les listes doivent correspondre à contents. Les identificateurs générés sont renvoyés lorsque ce champ est omis.
  • thread_ids str | None | list[str | None] – Identificateurs de thread facultatifs associés aux enregistrements insérés. Les valeurs scalaires peuvent être diffusées sur des entrées alignées.
  • user_ids str | None | list[str | None] – Identificateurs utilisateur facultatifs associés aux enregistrements insérés. Les valeurs scalaires peuvent être diffusées sur des entrées alignées. Lorsqu'il est omis dans une banque d'exécution SchemaPolicy.NO_CHECK, la banque utilise le nom utilisateur du contexte de sécurité de l'utilisateur final actif. Transmettez None explicitement pour conserver un ID utilisateur non ciblé.
  • agent_ids str | None | list[str | None] : identificateurs d'agent facultatifs associés aux enregistrements insérés. Les valeurs scalaires peuvent être diffusées sur des entrées alignées.
  • rôles str | None | list[str | None] : rôles de message facultatifs tels que "user" ou "assistant". Utilisé uniquement lorsque record_type est "message".
  • timestamps str | None | list[str | None] : horodatages facultatifs à enregistrer avec les enregistrements. Chaque horodatage indique la date de création de l'enregistrement. Les valeurs scalaires peuvent être diffusées sur des entrées alignées. Les entrées omises ou None laissent l'horodatage de l'événement non défini. Lorsque ttl_anchor est défini sur TimeToLiveAnchor.TIMESTAMP, chaque enregistrement affecté doit avoir une valeur d'horodatage ISO-8601 concrète. Les horodatages ISO-8601 sans fuseau horaire sont traités comme UTC.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None] – Dictionnaires de métadonnées facultatifs. Les métadonnées peuvent inclure "content" en tant que source de secours lorsqu'une valeur de texte est omise plutôt que définie sur "". Les écritures d'image nécessitent "image_mime_type" avec "image/png", "image/jpeg" ou "image/webp". Le magasin utilise ce champ pour enregistrer l'image, mais ne la renvoie pas dans les métadonnées de l'enregistrement.
  • ttl_days int | None | list[int | None] : durée de vie facultative en jours pour les enregistrements de type message et mémoire. Omettez cet argument pour utiliser MemoryRetentionConfig.default_ttl_days à partir du schéma géré. Transmettez None pour utiliser MemoryRetentionConfig.max_ttl_days lorsque la configuration de conservation en définit un ou pour créer un enregistrement qui n'expire pas lorsqu'il ne l'est pas. Les valeurs au-dessus de MemoryRetentionConfig.max_ttl_days sont bloquées à ce maximum avec un avertissement. Les valeurs scalaires peuvent être diffusées sur des entrées alignées.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor] : ancre de durée de vie facultative. Utilisez TimeToLiveAnchor.CREATED_AT pour expirer par rapport à l'heure de création de la base de données ou TimeToLiveAnchor.TIMESTAMP pour expirer par rapport à l'horodatage d'événement fourni. Lorsqu'elle est omise, l'expiration utilise TimeToLiveAnchor.CREATED_AT. L'expiration ancrée dans l'horodatage nécessite un horodatage ISO-8601 concret pour chaque enregistrement inséré. Les horodatages ISO-8601 sans fuseau horaire sont traités comme UTC.
  • statuses RecordStatus | list[RecordStatus] – Statut de cycle de vie facultatif pour les enregistrements qui le prennent en charge. Fournissez une valeur RecordStatus pour l'appliquer à chaque enregistrement d'entrée ou une liste de statuts alignés sur contents. Omettez cet argument pour utiliser RecordStatus.VALID.
  • **store_kwargs (Any) – Options d'écriture de la base de données. batch_size contrôle la taille de batch executemany et la valeur par défaut est 256.
• Retours : Identifiants pour les enregistrements insérés, dans le même ordre logique que l'entrée.
• Type de retour : list[str]

Exemples

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']

méthode add_agent

Ajoutez un enregistrement de profil d'agent.

• Paramètres:
  • agent_id str : identificateur d'agent.
  • information str : informations de forme libre sur l'agent. Ce texte est stocké en tant que contenu de profil et utilisé pour créer la représentation recherchable du profil.
  • metadata dict[str, Any] | None – Mapping de métadonnées facultatif stocké sur la ligne de profil d'agent.
• Retours : Identificateur de l'enregistrement de profil d'agent inséré.
• Type de retour : str

Notes

La portée des enregistrements de profil d'agent n'est pas définie. L'identificateur d'enregistrement public inséré est la même valeur transmise que agent_id.

Exemples

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

method add_agent_async (async)

Ajoutez de manière asynchrone un enregistrement de profil d'agent.

• Paramètres:
  • agent_id str : identificateur stable du profil d'agent.
  • information str : texte de forme libre décrivant l'agent.
  • metadata dict[str, Any] | None – Mapping de métadonnées facultatif stocké sur la ligne de profil d'agent.
• Retours : Identifiant de l'enregistrement de profil d'agent créé.
• Type de retour : str

method add_async (async)

Ajoutez de manière asynchrone des enregistrements orientés ligne au magasin.

accepte les mêmes arguments et renvoie les mêmes identificateurs que add().

• Paramètres:
  • contenu Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
  • record_type str
  • textes_index list[str | list[str] | None]
  • embarquements 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]
  • rôles str | None | list[str | None]
  • horodatages str | None | list[str | None]
  • métadonnées dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • statuts RecordStatus | list[RecordStatus]
  • store_kwargs Any
• Type de retour : list[str]

méthode add_batches

Ajoutez des lots logiques préparés par l'appelant au magasin.

• Paramètres:
  • batches list[PendingRecordBatch] : lots logiques entièrement préparés pour persistance. Chaque lot doit contenir ses propres champs par enregistrement, tels que record_type, les valeurs de portée, les rôles, les horodatages et les métadonnées.
  • **store_kwargs (N'importe lequel) – Options d'écriture spécifiques à l'implémentation transmises au magasin concret.
• Retours : Identifiants pour les enregistrements insérés, dans le même ordre logique que les lots et lignes d'entrée.
• Type de retour : List[str]

Exemples

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

method add_batches_async (async)

Ajoutez de manière asynchrone des lots logiques préparés par l'appelant au magasin.

accepte les mêmes arguments et renvoie les mêmes identificateurs que add_batches().

• Paramètres:
  • batchs list[PendingRecordBatch]
  • store_kwargs Any
• Type de retour : list[str]

méthode add_relations

Stockez atomiquement une ou plusieurs relations mémoire-mémoire.

Les valeurs scalaires sont diffusées dans le lot d'ID source ; les listes doivent être alignées. Une seule orientation de relation peut être stockée pour une paire d'adresses. Les étiquettes de liaison de mémoire intégrées reçoivent leur étiquette inversée fixe et les étiquettes de cycle de vie mettent à jour l'état de l'adresse dans la même transaction.

• Paramètres:
  • source_record_ids str | list[str] : identificateurs de mémoire source, sous forme de liste scalaire ou alignée.
  • source_record_types str | list[str] – Types de type mémoire pour les enregistrements source.
  • target_record_ids str | list[str] – Identificateurs de mémoire cible, sous forme de liste scalaire ou alignée.
  • target_record_types str | list[str] – Types de type mémoire pour les enregistrements cible.
  • relation_types str | list[str] – Libellés de relation dirigée.
  • opposite_relation_types str | list[str] : libellés inversés facultatifs pour les types de relation personnalisés. Ceci décrit la vue inverse de la relation stockée ; il ne crée pas de seconde relation dans le sens inverse.
  • relation_ids str | None | list[str | None] : identificateurs de relation stables facultatifs. Omettez de générer des identificateurs.
  • timestamps str | None | list[str | None] : horodatages facultatifs stockés avec les relations.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None] : métadonnées facultatives stockées avec les relations.
• Retours : Identifiants de relation créés dans l'ordre d'entrée.
• Type de retour : list[str]

Exemples

store.add_relations(
    "new-memory", "memory", "old-memory", "memory", "supersedes"
)
['relation-id']

method add_relations_async (async)

Stockez de manière asynchrone une ou plusieurs relations dirigées.

Les valeurs scalaires sont diffusées dans le batch d'enregistrement source. Les valeurs de liste doivent avoir la même longueur. Une seule orientation peut être stockée pour une paire d'adresses. Utilisez opposite_relation_types pour décrire la vue inverse plutôt que d'ajouter une seconde relation inverse.

• Paramètres:
  • source_record_ids str | list[str] – Identificateur ou identificateurs d'enregistrements à l'extrémité source de chaque relation dirigée.
  • source_record_types str | list[str] – Type(s) d'enregistrement pour source_record_ids. Indiquez une valeur pour toutes les sources ou une valeur pour chaque relation.
  • target_record_ids str | list[str] – Identificateur ou identificateurs d'enregistrements à l'extrémité cible de chaque relation dirigée.
  • target_record_types str | list[str] – Type(s) d'enregistrement pour target_record_ids. Indiquez une valeur pour toutes les cibles ou une valeur pour chaque relation.
  • relation_types str | list[str] – Libellé(s) de relation dirigée(s). Indiquez une valeur pour toutes les relations ou une valeur pour chaque relation.
  • opposite_relation_types str | list[str] : libellé ou libellés facultatifs pour la vue inversée de chaque relation. Pour les types de relations de mémoire intégrés, l'omission utilise l'étiquette inverse prédéfinie. Pour les types de relation personnalisés, l'omission utilise le même libellé dans les deux sens.
  • relation_ids str | None | list[str | None] : identificateurs stables facultatifs. Omettez ceci pour laisser le magasin générer des identificateurs.
  • timestamps str | None | list[str | None] : horodatage ou horodatage facultatif à stocker sur les relations.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None] – Objets de métadonnées facultatifs à stocker sur les relations.
• Renvoie : identificateurs de relation dans l'ordre d'entrée.
• Type de retour : list[str]

Exemples

await store.add_relations_async(
    "new", "memory", "old", "memory", "supersedes"
)
['relation-id']

méthode add_user

Ajouter un enregistrement de profil utilisateur.

• Paramètres:
  • user_id str : identificateur utilisateur. Lorsqu'il est omis dans une banque d'exécution SchemaPolicy.NO_CHECK, la banque utilise le nom utilisateur du contexte de sécurité de l'utilisateur final actif. Sinon, fournissez cet argument de manière explicite.
  • information str : informations de forme libre requises sur l'utilisateur. Ce texte est stocké en tant que contenu de profil et utilisé pour créer la représentation recherchable du profil.
  • metadata dict[str, Any] | None – Mapping de métadonnées facultatif stocké sur la ligne du profil utilisateur.
• Retours : Identifiant de l'enregistrement de profil utilisateur inséré.
• Type de retour : str

Notes

Les enregistrements de profil utilisateur n'ont pas de portée. L'identificateur d'enregistrement public inséré est le fichier user_id explicite ou inféré.

Exemples

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

method add_user_async (async)

Ajouter un enregistrement de profil utilisateur de manière asynchrone.

• Paramètres:
  • user_id str – Identificateur stable du profil utilisateur.
  • information str – Texte de forme libre décrivant l'utilisateur.
  • metadata dict[str, Any] | None – Mapping de métadonnées facultatif stocké sur la ligne du profil utilisateur.
• Retours : Identifiant de l'enregistrement de profil utilisateur créé.
• Type de retour : str

méthode delete

Supprimez une ligne gérée et ses lignes de bloc par identificateur.

• Paramètres:
  • record_type str – Libellé de type d'enregistrement à supprimer. Les types pris en charge sont "thread", "message", "memory", "guideline", "fact", "preference", "user_profile" et "agent_profile", et "thread_summary".
  • record_id str – Identificateur à supprimer.
  • cascade bool : lorsque True, développez les cibles de niveau supérieur prises en charge, telles que les profils d'acteur, jusqu'à leurs lignes enfant ciblées dans la même transaction. Pour une cible de profil utilisateur ou de profil d'agent, cela supprime d'abord les lignes de thread détenues, ce qui enlève leurs lignes de message de portée thread et de table de mémoire, puis supprime tous les messages de portée acteur directs restants et les lignes de type mémoire (memory, guideline, fact, preference). Ce nettoyage ciblé s'exécute quand la ligne de profil correspondante est déjà absente.
• Retours : nombre de cibles de niveau supérieur demandées enlevées, généralement 0 ou 1. Les lignes enfant en cascade ne sont pas comptabilisées séparément. Il peut donc s'agir de 0 lorsqu'un profil d'acteur manquant déclenche un nettoyage ciblé.
• Type de retour : int

Notes

L'opération s'exécute dans une transaction. Lorsque cascade est activé pour une cible de niveau supérieur prise en charge, la suppression de profil et toutes les suppressions enfant ciblées sont validées ou annulées ensemble.

Exemples

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

method delete_async (async)

Supprimer de manière asynchrone un enregistrement stocké par identifiant.

• Paramètres:
  • record_type str – Type logique de l'enregistrement à supprimer.
  • record_id str – Identifiant de l'enregistrement à supprimer.
  • cascade bool : lorsque True, appliquez tout comportement de suppression en cascade pris en charge par le magasin pour les cibles de niveau supérieur demandées dans la même opération de suppression. Il est principalement utilisé pour les cibles telles que les profils d'acteur qui possèdent des enregistrements de portée supplémentaires. Par exemple, une cascade de profils utilisateur ou d'agents peut supprimer les threads propriétaires eux-mêmes, les messages de portée thread et les enregistrements de type mémoire supprimés avec ces threads, ainsi que tous les enregistrements de portée acteur directs restants tels que les messages, les mémoires, les directives, les faits ou les préférences. Pour les suppressions de profil d'acteur, ce nettoyage ciblé peut toujours être exécuté lorsque la ligne de profil correspondante est déjà absente.
• Retours : nombre d'enregistrements de niveau supérieur demandés supprimés, généralement 0 ou 1. Les lignes enfant en cascade ne sont pas comptabilisées séparément. Il peut donc s'agir de 0 lorsqu'un profil d'acteur manquant déclenche un nettoyage ciblé.
• Type de retour : int

méthode delete_relations

Supprimer les relations par identifiant et recalculer l'état du cycle de vie.

• Paramètres : relation_ids str | list[str] – Identificateur ou identifiants des relations à supprimer.
• Retours : Nombre de relations supprimées.
• Type de retour : int

Exemples

store.delete_relations("relation-id")
1

method delete_relations_async (async)

Supprimer de manière asynchrone les relations par identificateur.

L'état de cycle de vie est recalculé à partir des relations restantes.

• Paramètres : relation_ids str | list[str] – Identificateur ou identifiants des relations à supprimer.
• Retours : Nombre de relations supprimées.
• Type de retour : int

Exemples

await store.delete_relations_async("relation-id")
1

méthode delete_thread

Supprimer un thread et ses lignes stockées associées.

• Paramètres : thread_id str : identificateur de thread dont les lignes doivent être enlevées, notamment la ligne de thread, les lignes enfant dépendantes et le nettoyage explicite des lignes de segment.
• Renvoie : nombre de lignes de thread supprimées (0 ou 1).
• Type de retour : int

Notes

Utilisez cette opération lorsque vous avez besoin d'un nettoyage en cascade de niveau thread. Dans la banque de données adossée à une base de données, la suppression du thread enlève la ligne de thread géré ainsi que les lignes de message et de mémoire associées, ainsi que les données de recherche gérées pour extraction. Elle est plus large qu'une suppression de niveau message, qui supprime uniquement la ligne de message brut. La suppression de thread enlève les lignes de message et de mémoire dépendantes ainsi que les données d'extraction associées dans la même transaction.

Exemples

store.delete_thread("c1")
0

method delete_thread_async (async)

Supprimer de manière asynchrone un thread et les données stockées associées.

• Paramètres : thread_id str – Identificateur du thread à enlever.
• Retours : nombre d'enregistrements de thread supprimés, généralement 0 ou 1.
• Type de retour : int

Notes

Il s'agit de l'opération de niveau magasin permettant de supprimer un thread et les enregistrements de niveau thread gérés par le magasin. Préférez la suppression de thread lorsque les exigences de conservation appellent la suppression des messages source et des données de mémoire dérivées de portée thread, car les suppressions au niveau message n'impliquent pas la suppression des enregistrements dérivés conservés séparément.

method get

Extraire un enregistrement stocké par identifiant.

• Paramètres:
  • record_type str – Libellé de type d'enregistrement résolu en ligne gérée, telle que "message", "memory", "guideline", "fact", "preference", "thread", "user_profile" ou "agent_profile", ou "thread_summary".
  • record_id str : identificateur à rechercher.
  • include_bytes bool : indique si les octets d'image doivent être chargés pour les enregistrements d'image ou les images jointes pour les enregistrements de message. La valeur par défaut est False.
• Retours : enregistrement rempli avec des métadonnées décodées lorsqu'elles sont trouvées, sinon None.
• Type de retour : Enregistrement | Aucun

Exemples

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'

method get_async (async)

Extraire de manière asynchrone un enregistrement stocké par type et identifiant.

• Paramètres:
  • record_type str – Type logique de l'enregistrement à extraire, tel que "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" ou "image".
  • record_id str – Identificateur de l'enregistrement à extraire.
  • include_bytes bool – Indique si les octets d'image stockés doivent être chargés. Pour un enregistrement de message, cette option détermine si les images jointes incluent leurs octets. Pour un enregistrement d'image, il contrôle si les octets d'image autonomes sont chargés. Cette option n'a aucun effet sur les autres types d'enregistrement.
• Retours : enregistrement stocké trouvé, sinon None. Une recherche "thread" renvoie une valeur ThreadRecord avec les métadonnées de thread, la configuration d'exécution, l'état d'exécution et l'horodatage de création renseignés lorsque la banque prend en charge les threads persistants.
• Type de retour : Enregistrement | Aucun

méthode get_relation

Renvoyer une relation identifiée par un ID ou un tuple d'adresse complet.

Fournissez relation_id seul ou fournissez un tuple complet d'adresse source à cible.

• Paramètres:
  • source_record_id str – Identifiant de l'enregistrement source. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • source_record_type str – Type d'enregistrement source. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • target_record_id str – Identificateur d'enregistrement cible. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • target_record_type str – Type d'enregistrement cible. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • relation_type str – Libellé de relation dirigée. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • relation_id str : identificateur de relation à mettre en correspondance directement. Fournissez cet argument seul plutôt que de le combiner avec des champs de type endpoint.
• Renvoie : relation stockée correspondante, ou None lorsqu'elle n'existe pas.
• Type de retour : RecordRelation | Aucun

Exemples

store.get_relation(relation_id="relation-id")
RecordRelation(...)
store.get_relation(
    "source-id", "memory", "target-id", "fact", "supports"
)
RecordRelation(...)

method get_relation_async (async)

Extraire de manière asynchrone une relation par ID ou tuple d'adresse.

Fournissez relation_id seul ou fournissez un tuple complet d'adresse source à cible.

• Paramètres:
  • source_record_id str – Identifiant de l'enregistrement source. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • source_record_type str – Type d'enregistrement source. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • target_record_id str – Identificateur d'enregistrement cible. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • target_record_type str – Type d'enregistrement cible. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • relation_type str – Libellé de relation dirigée. Obligatoire avec les autres champs de tuple d'adresse lorsque relation_id est omis.
  • relation_id str : identificateur de relation à mettre en correspondance directement. Fournissez cet argument seul plutôt que de le combiner avec des champs de type endpoint.
• Renvoie : relation correspondante, ou None lorsqu'elle n'existe pas.
• Type de retour : RecordRelation | Aucun

Exemples

await store.get_relation_async(relation_id="relation-id")
RecordRelation(...)

méthode list

Enumérer les enregistrements persistants pour un type d'enregistrement.

• Paramètres:
  • record_type str – Libellé du type d'enregistrement (par exemple, "thread", "message", "memory", "guideline", "fact", "preference", "thread", "user_profile" ou "agent_profile").
  • limit int | None – Nombre maximum d'enregistrements à renvoyer (facultatif). Lorsqu'il est omis, le magasin utilise sa limite de liste par défaut. Transmettez None pour désactiver cette limite et renvoyer tous les enregistrements correspondants.
  • thread_id str | None – Filtre de portée de thread exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seules les lignes dont thread_id est SQL NULL sont renvoyées. Les types d'enregistrements non ciblés ignorent ce filtre. Lorsque record_type est défini sur "thread", thread_id ne doit pas être défini. Utilisez record_id pour sélectionner un thread spécifique.
  • user_id str | None – Filtre de portée utilisateur exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seules les lignes dont user_id est SQL NULL sont renvoyées. Les types d'enregistrements non ciblés ignorent ce filtre.
  • agent_id str | None : filtre de portée d'agent exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seules les lignes dont agent_id est SQL NULL sont renvoyées. Les types d'enregistrements non ciblés ignorent ce filtre.

  • metadata_filter dict[str, Any] | None –

    Filtre de métadonnées. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements sans métadonnées stockées sont renvoyés. Lorsqu'elle est définie sur une dictée, les entrées de metadata_filter sont combinées à la sémantique AND. Les entrées dont la valeur n'est pas un dictionnaire opérateur de niveau champ utilisent une sémantique de correspondance exacte : la clé demandée doit exister dans les métadonnées stockées. Les dictionnaires imbriqués sont mis en correspondance de manière récursive. Les valeurs scalaires et de liste sont mises en correspondance par égalité exacte ; l'ordre et la longueur de la liste doivent également correspondre. Pour tester l'appartenance à un tableau, utilisez un dictionnaire d'opérateurs de niveau champ tel que {"tags": {"$array_contains": "prod"}}. Un opérande de liste pour "$array_contains" signifie que toutes les valeurs répertoriées doivent être présentes ; "$array_contains_any" signifie qu'au moins une valeur répertoriée doit être présente. Utilisez "$not" pour annuler une autre expression de niveau champ sur le même champ, y compris un dictionnaire d'opérateur ou une valeur de correspondance exacte brute. Les expressions négatives correspondent lorsque l'expression positive échoue, y compris les champs manquants ; l'appartenance au tableau négatif correspond également aux champs non-tableau. Par exemple, metadata_filter={"source": "slack"} pour un champ scalaire, metadata_filter={"review": {"status": "open"}} pour un champ imbriqué et metadata_filter={"tags": ["prod", "urgent"]} pour une correspondance de liste exacte. Combinez les conditions pour les exiger toutes :

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

  • include_bytes bool : indique si les enregistrements d'image ou les images jointes aux enregistrements de message incluent leurs octets stockés. La valeur par défaut est False. Les listes d'images directes requièrent une valeur record_id et au moins un filtre de portée d'utilisateur, d'agent ou de thread exact lorsqu'il s'agit de True.
  • record_id str – Filtre d'identificateur d'enregistrement exact. Lorsqu'il est omis, les enregistrements avec n'importe quel identifiant sont renvoyés. Les filtres de portée et de métadonnées restent des contraintes supplémentaires.
• Retours : Enregistrements triés par ordre d'insertion.
• Type de retour : list[Enregistrement]

Notes

"user_profile" et "agent_profile" sont des types d'enregistrement non ciblés. Pour ces types d'enregistrement, thread_id, user_id et agent_id sont ignorés et l'identité de l'acteur reste dans record.id. Les enregistrements "thread" affichent l'identificateur de thread en tant que record.id et record.thread_id.

Exemples

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

method list_async (async)

Répertorie de manière asynchrone les enregistrements stockés pour un type d'enregistrement.

• Paramètres:
  • record_type str – Type d'enregistrement logique à énumérer, tel que "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" ou "image".
  • limit int | None : nombre maximal facultatif d'enregistrements les plus récents à renvoyer. Lorsqu'elles sont omises, les implémentations peuvent appliquer une limite supérieure sécurisée telle que MAX_LIST_LIMIT. Transmettez None pour désactiver cette limite et renvoyer tous les enregistrements correspondants.
  • thread_id str | None – Filtre de portée de thread exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements dont thread_id est None sont renvoyés. Les types d'enregistrements non ciblés ignorent ce filtre. Lorsque record_type est défini sur "thread", thread_id ne doit pas être défini. Utilisez record_id pour sélectionner un thread spécifique.
  • user_id str | None – Filtre de portée utilisateur exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements dont user_id est None sont renvoyés. Les types d'enregistrements non ciblés ignorent ce filtre.
  • agent_id str | None : filtre de portée d'agent exact. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements dont agent_id est None sont renvoyés. Les types d'enregistrements non ciblés ignorent ce filtre.

  • metadata_filter dict[str, Any] | None –

    Filtre de métadonnées. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seuls les enregistrements dont les métadonnées sont None sont renvoyés. Lorsqu'elle est définie sur une dictée, les entrées de metadata_filter sont combinées à la sémantique AND. Les entrées dont la valeur n'est pas un dictionnaire opérateur de niveau champ utilisent une sémantique de correspondance exacte : la clé demandée doit exister dans les métadonnées stockées. Les dictionnaires imbriqués sont mis en correspondance de manière récursive. Les valeurs scalaires et de liste sont mises en correspondance par égalité exacte ; l'ordre et la longueur de la liste doivent également correspondre. Pour tester l'appartenance à un tableau, utilisez un dictionnaire d'opérateurs de niveau champ tel que {"tags": {"$array_contains": "prod"}}. Un opérande de liste pour "$array_contains" signifie que toutes les valeurs répertoriées doivent être présentes ; "$array_contains_any" signifie qu'au moins une valeur répertoriée doit être présente. Utilisez "$not" pour annuler une autre expression de niveau champ sur le même champ, y compris un dictionnaire d'opérateur ou une valeur de correspondance exacte brute. Les expressions négatives correspondent lorsque l'expression positive échoue, y compris les champs manquants ; l'appartenance au tableau négatif correspond également aux champs non-tableau. Par exemple, metadata_filter={"source": "slack"} pour un champ scalaire, metadata_filter={"review": {"status": "open"}} pour un champ imbriqué et metadata_filter={"tags": ["prod", "urgent"]} pour une correspondance de liste exacte. Combinez les conditions pour les exiger toutes :

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

  • include_bytes bool : indique si les enregistrements d'image ou les images jointes aux enregistrements de message incluent leurs octets stockés. Lorsqu'elle est omise ou False, les descriptions d'image et les métadonnées sont renvoyées sans chargement d'octets. Pour les listes d'images directes, définissez-la sur True uniquement avec une valeur record_id exacte et au moins un filtre d'utilisateur, d'agent ou de portée de thread exact. Cette option n'a aucun effet sur les autres types d'enregistrement.
  • record_id str – Filtre d'identificateur d'enregistrement exact. Lorsqu'il est omis, les enregistrements avec n'importe quel identifiant sont renvoyés. Les filtres de portée et de métadonnées restent des contraintes supplémentaires.
• Retours : Enregistrements classés du plus ancien au plus récent dans la fenêtre renvoyée.
• Type de retour : Liste[Enregistrement]

méthode list_relations

Répertoriez les relations dans leur orientation source-cible.

• Paramètres:
  • relation_type str – Libellé de relation dirigée facultatif à mettre en correspondance, tel que "supports" ou "supersedes". Omettez d'inclure tous les types de relation.
  • source_record_id str : identificateur d'enregistrement source facultatif à mettre en correspondance.
  • source_record_type str – Type d'enregistrement source à mettre en correspondance (facultatif).
  • target_record_id str – Identificateur d'enregistrement cible facultatif à mettre en correspondance.
  • target_record_type str – Type d'enregistrement cible facultatif à mettre en correspondance.
  • limit int | None – Nombre maximum facultatif de relations créées au plus tôt à renvoyer. Lorsqu'il est omis, le magasin utilise MAX_LIST_LIMIT. Transmettez None pour renvoyer toutes les relations stockées correspondantes.
  • metadata_filter dict[str, Any] | None – Filtre de métadonnées. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seules les relations dont les métadonnées sont None sont renvoyées. Lorsqu'elle est définie sur un dict, les entrées sont combinées à la sémantique AND. Les dictionnaires imbriqués utilisent une correspondance exacte récursive. Les valeurs scalaires et de liste nécessitent une égalité exacte ; utilisez {"tags": {"$array_contains": "prod"}} pour mettre en correspondance l'appartenance au tableau, "$array_contains_any" pour mettre en correspondance toute valeur répertoriée ou "$not" pour annuler une autre expression de champ.
  • relation_id str – Filtre d'identificateur de relation exact. Lorsqu'elle est omise, les relations avec n'importe quel identificateur sont renvoyées. D'autres filtres restent des contraintes supplémentaires.
• Retours : Relations triées par heure de création et identifiant.
• Type de retour : list[RecordRelation]

Exemples

store.list_relations(
    source_record_id="current-memory",
    relation_type="supports",
    metadata_filter={"source": "manual"},
)
[RecordRelation(...)]

method list_relations_async (async)

Répertorie de manière asynchrone les relations dans l'orientation source-cible.

• Paramètres:
  • relation_type str – Libellé de relation dirigée facultatif à mettre en correspondance, tel que "supports" ou "supersedes". Omettez d'inclure tous les types de relation.
  • source_record_id str : identificateur d'enregistrement source facultatif à mettre en correspondance.
  • source_record_type str – Type d'enregistrement source à mettre en correspondance (facultatif).
  • target_record_id str – Identificateur d'enregistrement cible facultatif à mettre en correspondance.
  • target_record_type str – Type d'enregistrement cible facultatif à mettre en correspondance.
  • limit int | None – Nombre maximum facultatif de relations créées au plus tôt à renvoyer. Lorsqu'elles sont omises, les implémentations peuvent appliquer une limite supérieure sécurisée telle que MAX_LIST_LIMIT. Transmettez None pour renvoyer toutes les relations stockées correspondantes.
  • metadata_filter dict[str, Any] | None – Filtre de métadonnées. Lorsqu'il est omis, aucun filtrage n'est appliqué. Lorsqu'elle est définie sur None, seules les relations dont les métadonnées sont None sont renvoyées. Lorsqu'elle est définie sur un dict, les entrées sont combinées à la sémantique AND. Les dictionnaires imbriqués utilisent une correspondance exacte récursive. Les valeurs scalaires et de liste nécessitent une égalité exacte ; utilisez {"tags": {"$array_contains": "prod"}} pour mettre en correspondance l'appartenance au tableau, "$array_contains_any" pour mettre en correspondance toute valeur répertoriée ou "$not" pour annuler une autre expression de champ.
  • relation_id str : identificateur de relation facultatif à mettre en correspondance directement.
• Retours : Relations triées par heure de création et identifiant.
• Type de retour : list[RecordRelation]

Exemples

await store.list_relations_async(
    source_record_id="current-memory", relation_type="supports"
)
[RecordRelation(...)]

méthode list_thread_messages

Renvoyer les messages persistants pour un thread.

• Paramètres:
  • thread_id str : identificateur de thread dont les messages doivent être renvoyés.
  • last_n int | None : nombre facultatif de messages les plus récents à renvoyer.
  • range_start_seq_no int | None : limite de séquence inférieure inclusive facultative.
  • range_end_seq_no int | None : limite de séquence supérieure exclusive facultative.
  • include_bytes bool : indique si les parties d'image attachées aux messages renvoyés incluent leurs octets stockés. La valeur par défaut est False.
• Retours : Enregistrements de message triés par ordre d'insertion.
• Type de retour : list[MessageRecord]

Exemples

store.list_thread_messages("c1")
[]

method list_thread_messages_async (async)

Répertoriez de manière asynchrone l'historique des messages stockés pour un thread.

• Paramètres:
  • thread_id str – Identificateur du thread dont les messages doivent être renvoyés.
  • last_n int | None : nombre facultatif de messages les plus récents à inclure. Lorsqu'il est omis, tous les messages stockés pour le thread sont renvoyés. Lorsqu'elle est combinée à une plage de séquences, la limite s'applique à l'intérieur de cette plage.
  • range_start_seq_no int | None : limite de séquence inférieure inclusive facultative. Seuls les messages dont seq_no est au moins cette valeur sont renvoyés.
  • range_end_seq_no int | None : limite de séquence supérieure exclusive facultative. Seuls les messages dont la valeur seq_no est inférieure à cette valeur sont renvoyés.
  • include_bytes bool : indique si les parties d'image attachées aux messages renvoyés incluent leurs octets stockés. Lorsqu'elle est omise ou False, les descriptions d'image et les métadonnées sont renvoyées sans chargement d'octets.
• Retours : Enregistrements de message classés du plus ancien au plus récent dans la fenêtre renvoyée.
• Type de retour : List[MessageRecord]

méthode search

Rechercher des enregistrements par similarité.

Le back-end de recherche actif dépend de l'adresse SearchStrategy configurée de la banque. SearchStrategy.VECTOR classe le vecteur de requête par rapport aux vecteurs d'enregistrement stockés. SearchStrategy.HYBRID interroge l'index hybride géré d'Oracle sur le texte de recherche stocké et son état d'index géré. SearchStrategy.KEYWORD se classe uniquement par le texte correspondant au texte de recherche stocké.

• Paramètres:
  • query str | None : texte en langage naturel facultatif utilisé pour rechercher des enregistrements correspondants ou similaires. Indiquez au moins un caractère autre qu'un espace lorsque query_vector est omis. La recherche vectorielle intègre ce texte ; la recherche par mot clé le compare au texte de recherche stocké ; la recherche hybride l'utilise à la fois pour la récupération de texte et de vecteur. Lorsque le texte dépasse la taille de bloc configurée, le magasin recherche chaque bloc de requête séparément et fusionne les résultats classés avec la fusion de rang réciproque.
  • query_vector list[float] | None : intégration de requête précalculée facultative. Vous devez fournir exactement l'une des options query et query_vector. Dans la recherche vectorielle, cela est comparé aux vecteurs d'enregistrement stockés. Dans la recherche hybride, elle est envoyée à l'index hybride géré d'Oracle en tant qu'entrée vectorielle côté requête et ne permet pas à la banque de base de données de comparer directement les vecteurs stockés d'ajout ou de mise à jour. La recherche par mot-clé n'accepte pas query_vector. Le vecteur doit être non vide, unidimensionnel et ne contenir que des valeurs numériques finies. Dans la recherche hybride, sa dimension doit correspondre au modèle OracleDBEmbedder configuré.
  • k int – Nombre maximum de résultats à renvoyer. Les valeurs explicites doivent être au moins 1. Limite supérieure : l'appel peut renvoyer moins de résultats k lorsque les filtres sont trop restrictifs, lorsqu'il existe moins d'enregistrements correspondants non expirés ou en raison d'un comportement de recherche propre à l'implémentation.
  • thread_id str | None : identificateur de portée de thread facultatif. exact_thread_match=False laisse la dimension de thread sans contrainte. exact_thread_match=True correspond exactement au paramètre thread_id fourni. Si la valeur est thread_id=None, elle correspond uniquement aux enregistrements non ciblés sur la dimension de thread.
  • user_id str | None : identificateurs de portée utilisateur et agent facultatifs. L'indicateur exact_*_match=False correspondant laisse cette dimension sans contrainte. exact_*_match=True correspond exactement à l'ID fourni. Si l'ID est None, il correspond uniquement aux enregistrements non ciblés sur cette dimension.
  • agent_id str | None : identificateurs de portée d'agent et d'utilisateur facultatifs. L'indicateur exact_*_match=False correspondant laisse cette dimension sans contrainte. exact_*_match=True correspond exactement à l'ID fourni. Si l'ID est None, il correspond uniquement aux enregistrements non ciblés sur cette dimension.
  • exact_user_match bool – Indique si chaque identificateur de portée doit correspondre exactement. False laisse cette dimension sans contrainte. True correspond exactement à la valeur fournie. Si cette valeur est None, elle ne correspond qu'aux enregistrements non ciblés de cette dimension.
  • exact_agent_match bool – Indique si chaque identificateur de portée doit être mis en correspondance exactement. False laisse cette dimension sans contrainte. True correspond exactement à la valeur fournie. Si cette valeur est None, elle ne correspond qu'aux enregistrements non ciblés de cette dimension.
  • exact_thread_match bool : indique si chaque identificateur de portée doit être mis en correspondance exactement. False laisse cette dimension sans contrainte. True correspond exactement à la valeur fournie. Si cette valeur est None, elle ne correspond qu'aux enregistrements non ciblés de cette dimension.
  • record_types set[str] | None – Ensemble facultatif de types d'enregistrement recherchables à inclure. Lorsqu'elle est omise, la recherche de base de données couvre les messages, les documents tels que les images, les lignes de table mémoire et les profils d'acteur. Les enregistrements d'image fournissent leur description, les profils d'acteur fournissent leur charge utile information et les lignes de message et de mémoire fournissent leur charge utile content. Au cours de la recherche, les types d'enregistrement de profil utilisent leur identifiant d'acteur pour la dimension de portée applicable, tandis que les dimensions de portée restantes se comportent comme None.
  • metadata_filter dict[str, Any] | None – Mappage de filtre de métadonnées facultatif. Les entrées dans metadata_filter sont combinées avec la sémantique AND. Les entrées dont la valeur n'est pas un dictionnaire opérateur de niveau champ utilisent une sémantique de correspondance exacte : la clé demandée doit exister dans les métadonnées stockées. Les dictionnaires imbriqués sont mis en correspondance de manière récursive. Les valeurs scalaires et de liste sont mises en correspondance par égalité exacte ; l'ordre et la longueur de la liste doivent également correspondre. Pour tester l'appartenance à un tableau, utilisez un dictionnaire d'opérateurs de niveau champ tel que {"tags": {"$array_contains": "prod"}}. Un opérande de liste pour "$array_contains" signifie que toutes les valeurs répertoriées doivent être présentes ; "$array_contains_any" signifie qu'au moins une valeur répertoriée doit être présente. Utilisez "$not" pour annuler une autre expression de niveau champ sur le même champ, y compris un dictionnaire d'opérateur ou une valeur de correspondance exacte brute. Les expressions négatives correspondent lorsque l'expression positive échoue, y compris les champs manquants ; l'appartenance au tableau négatif correspond également aux champs non-tableau.
  • include_invalid_results bool : indique si les résultats incluent des enregistrements de type mémoire dont le statut n'est pas valide. La valeur par défaut est True. Transmettez False pour les exclure.
  • num_hops int – Nombre d'arêtes de liaison mémoire à suivre à partir de chaque résultat de mémoire directe. Les valeurs comprises entre 0 et 5 sont prises en charge ; 0 désactive l'extension de graphique. L'expansion suit les liens dans les deux sens. Les enregistrements liés continuent d'obéir aux filtres de portée, de métadonnées, de type d'enregistrement et d'expiration demandés. Les résultats de message, de document et de profil directs restent dans l'ensemble de résultats mais ne sont pas développés dans le graphique.
  • max_linked_results int – Nombre maximal de mémoires liées dans tous les sauts attachés à chaque résultat direct. 0 conserve les résultats directs sans contexte lié. Par défaut, 100 est utilisé.
• Renvoie : paires (record, distance) triées par distance croissante. La liste peut contenir moins de k entrées. Pour une interrogation fragmentée, la distance est dérivée du score réciproque-rang-fusion.
• Type de retour : list[tuple[Record, float]]
• Elèves :
  • ValueError – Si k est inférieur à 1, si les deux ou aucun des éléments query et query_vector sont fournis, si query est vide, si le mode vectoriel ne peut pas résoudre une intégration de requête, si query_vector n'est pas valide ou si metadata_filter n'est pas valide.
  • TimeoutError – Si l'extension du graphique prend plus de temps que la durée maximale autorisée.

Exemples

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'

Filtrer sur une valeur de métadonnées scalaire :

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

Filtrer sur les métadonnées imbriquées :

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

Faites correspondre exactement une valeur de liste, y compris l'ordre :

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

Filtrer lorsqu'un tableau de métadonnées contient une valeur :

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

Combinez plusieurs conditions de métadonnées. Un enregistrement doit satisfaire toutes les clés :

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

method search_async (async)

Rechercher des enregistrements de manière asynchrone par similarité sémantique.

• Paramètres:
  • query str | None : même texte de requête accepté par search.
  • k int : nombre de résultats maximal identique accepté par search. Les valeurs explicites doivent être au moins 1.
  • query_vector list[float] | None – Même intégration de requête précalculée facultative acceptée par search.
  • thread_id str | None – Les mêmes filtres de portée facultatifs acceptés par search.
  • user_id str | None – Les mêmes filtres de portée facultatifs acceptés par search.
  • agent_id str | None – Les mêmes filtres de portée facultatifs acceptés par search.
  • exact_user_match bool – Les mêmes indicateurs de correspondance exacte acceptés par search.
  • exact_agent_match bool : indicateurs de correspondance exacte acceptés par search.
  • exact_thread_match bool : indicateurs de correspondance exacte acceptés par search.
  • record_types set[str] | None – Même filtre facultatif de type d'enregistrement accepté par search.
  • metadata_filter dict[str, Any] | None – Même filtre de métadonnées facultatif accepté par search, y compris scalaire, imbriqué, liste exacte, appartenance à un tableau et conditions combinées telles que {"source": "slack"}, {"review": {"status": "open"}}, {"tags": ["prod", "urgent"]} et {"tags": {"$array_contains": "prod"}}.
  • include_invalid_results bool – Option de résultat avec le même statut de cycle de vie acceptée par search.
  • num_hops int – Profondeur d'extension de graphique identique acceptée par search.
  • max_linked_results int – Même limite de mémoire liée par résultat direct acceptée par search.
• Renvoie : paires (record, distance) renvoyées par l'appel search sous-jacent.
• Type de retour : List[tuple[Record, float]]
• Elèves : ValueError – Si k est inférieur à 1.

méthode update

Mettre à jour le contenu des enregistrements stockés, l'état de la recherche, les métadonnées et les valeurs d'horodatage.

• Paramètres:
  • record_type str – Libellé de type d'enregistrement de la ligne en cours de modification (par exemple, "message", "memory", "guideline", "fact", "preference", "user_profile" ou "agent_profile")
  • record_id str – Identificateur de la ligne stockée à mettre à jour.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None : le contenu de remplacement canonique est conservé dans la colonne content. Pour les enregistrements de message, transmettez "" pour effacer le contenu tout en effaçant toute représentation de vecteur stockée ; l'expression explicite None est rejetée. Pour les enregistrements de type mémoire, transmettez None pour effacer le texte stocké et l'intégration, et transmettez uniquement None ou les arguments sémantiques omis dans le même appel. Lorsqu'il est omis, le contenu existant reste inchangé. N'indiquez pas ceci avec text.
  • index_text str | list[str] | None : charge utile sémantique uniquement facultative. Lorsqu'elle est omise, content est utilisé pour l'indexation sémantique. Sur les schémas à capacité hybride, cela devient également le texte de recherche stocké utilisé par le composant de texte d'Oracle. Une valeur de chaîne peut être découpée en blocs par le magasin. Une valeur de liste est traitée comme des blocs appartenant à l'appelant et écrite telle quelle dans RECORD_CHUNKS. Lorsque seul embedding est fourni, le texte de recherche existant est réutilisé.

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

    Facultatif vecteur d'intégration précalculé ou liste de vecteurs d'intégration de blocs. Lorsque le stockage vectoriel local est configuré, il est utilisé directement et aucun appel d'intégration n'est effectué. Transmettez None pour effacer l'intégration stockée. Un seul vecteur représente l'ensemble du texte de remplacement lorsque content est fourni, même lorsque le bloc configuré fractionne ce texte. Plusieurs vecteurs de bloc sont rejetés lors du remplacement du texte, sauf si index_text est une liste de blocs. Lorsque seul embedding est fourni, le nombre d'incorporation doit correspondre aux lignes de bloc existantes de l'enregistrement.

    Dans SearchStrategy.VECTOR, la recherche vectorielle se classe par rapport à l'intégration stockée. Dans SearchStrategy.HYBRID ou SearchStrategy.KEYWORD, la recherche soutenue par la base de données se classe par le texte de recherche stocké et l'état d'index hybride ou de texte géré par Oracle, de sorte que les incorporations de mise à jour n'affectent que tout stockage vectoriel local configuré, et non cette stratégie de recherche active. Si cette banque a été configurée sans stockage vectoriel local, indiquez index_text au lieu de embedding pour mettre à jour le texte visible par ces index sensibles au texte. Les mises à jour sémantiques en texte uniquement peuvent omettre embedding entièrement dans ces modes.

  • metadata dict[str, Any] | None – Mise en correspondance de métadonnées facultative sérialisée avec JSON et stockée dans metadata. Le remplacement de l'image content nécessite "image_mime_type" par "image/png", "image/jpeg" ou "image/webp". Le magasin utilise ce champ pour enregistrer l'image, mais ne la renvoie pas dans les métadonnées de l'enregistrement.
  • timestamp str | None : nouvel horodatage facultatif à enregistrer avec l'enregistrement. Il indique la date de création de l'enregistrement. Lorsqu'il est omis, l'horodatage existant est conservé. Transmettez None pour effacer l'horodatage enregistré et utiliser l'heure de création de la base de données pour les futures actualisations d'expiration TimeToLiveAnchor.CREATED_AT. Lorsque ttl_anchor est défini sur TimeToLiveAnchor.TIMESTAMP, les horodatages ISO-8601 sans fuseau horaire sont traités comme UTC.
  • ttl_days int | None : actualisation facultative de l'expiration en jours. Omettez cet argument avec ttl_anchor pour conserver l'horodatage d'expiration en cours. Transmettez None pour utiliser MemoryRetentionConfig.max_ttl_days lorsque la configuration de conservation en définit une ou pour effacer l'expiration lorsqu'elle ne le fait pas. Les valeurs au-dessus de MemoryRetentionConfig.max_ttl_days sont bloquées à ce maximum avec un avertissement. L'actualisation de l'expiration peut rendre un enregistrement expiré visible à nouveau s'il n'a pas encore été purgé.
  • ttl_anchor TimeToLiveAnchor : ancre de durée de vie facultative pour une actualisation d'expiration. Utilisez TimeToLiveAnchor.CREATED_AT pour compter à partir de l'heure de création stockée ou TimeToLiveAnchor.TIMESTAMP pour compter à partir de l'élément timestamp de remplacement fourni dans la même mise à jour ou de l'horodatage de l'événement stocké lorsque timestamp est omis. La fourniture de ttl_anchor sans ttl_days actualise l'expiration à l'aide de MemoryRetentionConfig.default_ttl_days du schéma. Lorsque ttl_anchor est omis lors d'une actualisation, le magasin utilise TimeToLiveAnchor.CREATED_AT. Les actualisations ancrées dans l'horodatage nécessitent un horodatage ISO-8601 de remplacement dans le même appel ou un horodatage d'événement stocké existant dans ce format. Les horodatages ISO-8601 sans fuseau horaire sont traités comme UTC.
  • status RecordStatus : statut du cycle de vie de remplacement facultatif pour les enregistrements. Omettez-le pour conserver le statut actuel.

  • text str | None –

    Alias obsolète pour content. Transmettez None pour effacer le texte stocké et effacer l'intégration stockée. N'indiquez pas ceci avec content.

    Obsolète

    Obsolète depuis la version 26.8.0 : Ce paramètre est obsolète dans la version 26.8.0 et sera supprimé dans la version 27.1. Utilisez plutôt content.

• Retours : Nombre d'enregistrements mis à jour (0 ou 1). Une valeur renvoyée de 0 signifie qu'aucun enregistrement n'a été mis à jour.
• Type de retour : int
• Elèves : ValueError – Si record_type n'est pas pris en charge, si aucune charge utile de mise à jour n'est fournie ou si les arguments de mise à jour sémantique sont incompatibles.

Exemples

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

method update_async (async)

Mettre à jour de manière asynchrone le contenu des enregistrements stockés, l'intégration des données, les métadonnées, l'horodatage ou l'expiration.

• Paramètres:
  • record_type str – Type logique de l'enregistrement à mettre à jour.
  • record_id str – Identifiant de l'enregistrement à mettre à jour.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None – Contenu de remplacement canonique. Pour les enregistrements message, transmettez une chaîne ou une séquence ordonnée de parties de contenu de texte et d'image. Utilisez "" pour remplacer le message par du texte vide. Pour les enregistrements de type mémoire, les magasins peuvent accepter None pour effacer le texte stocké et l'état sémantique associé. Omettez l'argument pour laisser le contenu inchangé. N'indiquez pas ceci avec text.
  • index_text str | list[str] | None : charge utile sémantique alternative facultative utilisée pour recalculer ou remplacer l'état de recherche stocké sans modifier le texte persistant. Une chaîne peut être découpée en interne par le magasin. Une liste de chaînes non vides est traitée comme des blocs appartenant à l'appelant et ne doit pas être divisée à nouveau. Certaines implémentations peuvent également persister séparément en tant que texte de recherche hybride. Pour un enregistrement image, ce champ remplace la description de l'image persistante.
  • embedding list[float] | ndarray | list[list[float] | ndarray] | None : vecteur d'intégration précalculé facultatif ou liste de vecteurs d'intégration de blocs. Lorsqu'elle est fournie, elle est utilisée directement et aucun appel d'intégration n'est effectué. Plusieurs vecteurs nécessitent la mise en correspondance de listes de blocs index_text ou de lignes de texte de bloc stockées existantes. Transmettez None pour effacer explicitement l'intégration stockée lorsque l'emplacement de stockage la prend en charge. Les magasins avec indexation prenant en charge le texte peuvent également permettre des mises à jour sémantiques sans incorporation ou intégration explicite.
  • metadata dict[str, Any] | None – Mappage de métadonnées de remplacement facultatif. Transmettez None pour effacer les métadonnées lorsque la banque les prend en charge. Le remplacement de l'image content requiert "image_mime_type" dans ce mapping. Le magasin utilise ce champ pour enregistrer l'image, mais ne la renvoie pas dans les métadonnées de l'enregistrement.
  • timestamp str | None : nouvel horodatage facultatif à enregistrer avec l'enregistrement. Il indique la date de création de l'enregistrement. Omettez cet argument pour laisser l'horodatage stocké inchangé. Transmettez None pour effacer l'horodatage enregistré et utiliser l'heure à laquelle l'enregistrement a été ajouté au magasin lorsque celui-ci est pris en charge par le magasin.
  • ttl_days int | None : actualisation facultative de l'expiration en jours. Omettez cet argument avec ttl_anchor pour conserver l'horodatage d'expiration en cours. Transmettez None pour effacer l'expiration.
  • ttl_anchor TimeToLiveAnchor : ancre de durée de vie facultative pour une actualisation d'expiration. Utilisez TimeToLiveAnchor.CREATED_AT pour l'heure de création de l'enregistrement ou TimeToLiveAnchor.TIMESTAMP pour le remplacement timestamp fourni dans la même mise à jour, ou l'horodatage de l'événement stocké lorsque timestamp est omis. Si vous indiquez ttl_anchor sans ttl_days, la durée de vie par défaut du stockage ou du schéma est utilisée. Lorsque ttl_anchor est omis lors d'une actualisation, les implémentations utilisent TimeToLiveAnchor.CREATED_AT.
  • status RecordStatus : statut du cycle de vie de remplacement facultatif pour les enregistrements. Omettez-le pour conserver le statut actuel.

  • text str | None –

    Alias obsolète pour content. Transmettez None pour effacer explicitement le texte stocké lorsque le magasin le prend en charge. N'indiquez pas ceci avec content.

    Obsolète

    Obsolète depuis la version 26.8.0 : Ce paramètre est obsolète dans la version 26.8.0 et sera supprimé dans la version 27.1. Utilisez plutôt content.

• Retours : Nombre d'enregistrements mis à jour (0 ou 1). Une valeur renvoyée de 0 signifie qu'aucun enregistrement n'a été mis à jour.
• Type de retour : int
• Elèves : ValueError – Si la charge utile de mise à jour n'est pas valide pour le magasin, par exemple en omettant tous les champs facultatifs ou en fournissant des arguments sémantiques contradictoires.

méthode update_relations

Mettez à jour les champs de relation mutables et recalculez l'état de cycle de vie de l'adresse.

Les champs omis restent inchangés. Les étiquettes de liaison de mémoire intégrées conservent toujours leur étiquette inverse dérivée.

• Paramètres:
  • relation_ids str | list[str] – Identificateur ou identificateurs des relations à mettre à jour.
  • relation_types str | list[str] : libellé ou libellé de relation dirigée de remplacement facultatif.
  • opposite_relation_types str | list[str] : libellé inversé ou libellé de remplacement facultatif pour les types personnalisés.
  • timestamps str | None | list[str | None] : horodatages de remplacement facultatifs. Transmettez None pour en effacer un.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None] : métadonnées de remplacement facultatives. Il remplace les métadonnées existantes.
• Retours : Identifiants des relations qui ont été mises à jour.
• Type de retour : list[str]

Exemples

store.update_relations("relation-id", relation_types="supports")
['relation-id']

method update_relations_async (async)

Mettre à jour de manière asynchrone les valeurs mutables sur les relations stockées.

Les champs omis restent inchangés, sauf que le passage à un type de relation mémoire intégré remplace son libellé inverse par l'inverse fixe. Une banque de mémoire soutenue par une base de données recalcule également les états de cycle de vie des adresses après une modification de type de relation.

• Paramètres:
  • relation_ids str | list[str] – Identificateur ou identificateurs des relations à mettre à jour.
  • relation_types str | list[str] : libellé ou libellé de relation dirigée de remplacement facultatif. Omettez-la pour conserver les étiquettes stockées.
  • opposite_relation_types str | list[str] : libellé ou libellé de relation inverse de remplacement facultatif. Transmettez une étiquette pour la remplacer ou omettez cet argument pour la conserver.
  • timestamps str | None | list[str | None] : horodatage ou horodatage de remplacement facultatif. Transmettez None pour effacer un horodatage stocké.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None] – Objets de métadonnées de remplacement facultatifs. Les métadonnées fournies remplacent l'objet stocké ; il n'est pas fusionné.
• Retours : Identifiants des relations qui ont été mises à jour.
• Type de retour : list[str]

Exemples

await store.update_relations_async(
    "relation-id", relation_types="supports"
)
['relation-id']

Relations

OracleDBMemoryStore peut stocker des relations dirigées entre des enregistrements de type mémoire (memory, fact, guideline et preference). Utilisez add_relations(), get_relation(), list_relations(), update_relations() et delete_relations() lorsqu'une intégration a besoin de l'API de relation de niveau inférieur. Les API client et thread fournissent link_records(), update_record_link() et delete_record_link() pour les types de relation de mémoire pris en charge.

Pour extraire une relation, indiquez relation_id seul ou le tuple d'adresse stocké complet : ID et type d'enregistrement source, ID et type d'enregistrement cible, et type de relation. Un tuple partiel et un ID de relation associés à un champ de tuple ne sont pas valides car aucun des deux n'identifie la relation demandée sans ambiguïté.

Utilisez list_relations() pour énumérer les relations dans l'ordre de création. Filtrer par ID et type d'enregistrement source ou cible, ou par libellé de relation dirigée. Il utilise la limite de liste de sécurité normale du magasin, sauf si vous transmettez limit=None. Son élément metadata_filter utilise la même sémantique de correspondance exacte, d'objet imbriqué, d'appartenance à un tableau et de négation que list(). Transmettez metadata_filter=None pour renvoyer uniquement les relations sans métadonnées.

Les types de relation de cycle de vie (supersedes, refines et duplicates) marquent la mémoire cible non valide tant que le lien existe. La suppression ou la modification du dernier lien de ce type rétablit le statut valide de la cible. Les API de recherche peuvent exclure les enregistrements non valides avec include_invalid_results=False.

classe oracleagentmemory.apis.relations.RecordRelation

Bases : object

Décrivez une relation dirigée et stockée entre deux enregistrements.

• Paramètres:
  • id str – Identificateur stable de la relation.
  • source_record_id str – Identificateur de l'enregistrement à la source stockée de la relation.
  • source_record_type str – Type logique de l'enregistrement source.
  • target_record_id str – Identificateur de l'enregistrement sur la cible stockée de la relation.
  • target_record_type str – Type logique de l'enregistrement cible.
  • relation_type str – Libellé dont la signification suit la direction source-cible stockée.
  • opposite_relation_type str – Libellé utilisé lors du déplacement du parcours de la cible vers la source.
  • timestamp str | None : horodatage facultatif de l'appelant associé à la relation.
  • metadata dict[str, Any] | None : métadonnées de type JSON facultatives stockées avec la relation.
  • created_at str : horodatage de création de la base de données pour la relation.

Stratégie de recherche

classe oracleagentmemory.core.dbsearch.SearchStrategy

Bases : Enum

Comportement de recherche pour les banques Oracle DB.

L'initialisation de la banque de données utilise la stratégie sélectionnée pour choisir la fonction de recherche de schéma géré. La recherche VECTOR stocke les incorporations locales. La recherche KEYWORD stocke le texte recherchable et un index de texte. La recherche HYBRID stocke le texte recherchable plus l'état d'index vectoriel hybride géré par Oracle. La banque de base de données valide cette fonctionnalité de schéma au démarrage afin qu'une stratégie incompatible ne renvoie pas de résultats incomplets en mode silencieux.

VECTOR

Recherche par similarité vectorielle uniquement. Le magasin intègre la requête avec l'intégrateur configuré, ou utilise un query_vector fourni par l'appelant, et classe les enregistrements en fonction de la distance par rapport aux vecteurs stockés. Utilisez-le avec un schéma de base de données configuré pour la recherche vectorielle.

HYBRID

Recherchez avec l'index hybride géré d'Oracle. Oracle combine la correspondance de texte sur le texte de recherche stocké avec le classement vectoriel à partir de l'index hybride dans la base de données. Utilisez cette option lorsque les utilisateurs peuvent effectuer une recherche par langage naturel, ainsi que par identifiants, alias ou noms de produit exacts. Cette stratégie exige que l'intégrateur principal du magasin soit un OracleDBEmbedder afin que l'index géré et le magasin partagent un modèle dans la base de données.

KEYWORD

Effectuez une recherche uniquement par mot-clé/texte sur le texte de recherche stocké. Ce mode ne crée pas d'intégrations de requête locale et n'a pas besoin d'un intégrateur Oracle DB. Lorsqu'il est ouvert sur un schéma hybride existant, il peut utiliser la branche de texte de cet index hybride sans créer de nouvel index hybride. Utilisez-le lorsque les identificateurs exacts, les alias, les noms de produit ou les expressions courtes doivent conduire à la récupération sans fusion vectorielle.

HYBRIDE = 'hybride'

MOT-clé = 'mot-clé'

VECTEUR = 'vecteur'

Mode de synchronisation d'index de recherche

classe oracleagentmemory.core.dbsearch.SearchIndexSyncMode

Bases : Enum

Comportement d'actualisation des index de recherche de base de données gérée.

Ce paramètre détermine quand Oracle rend le texte de recherche nouveau ou modifié visible pour la recherche en mode texte adossée à une base de données. SearchStrategy.HYBRID utilise l'index vectoriel hybride géré d'Oracle. SearchStrategy.KEYWORD utilise un index Oracle Text. SearchStrategy.VECTOR n'utilise pas ce paramètre.

ON_COMMIT

Actualisez l'index lors de la validation de la transaction d'écriture. Il s'agit du choix par défaut et du plus simple pour la plupart des applications, car les enregistrements peuvent faire l'objet d'une recherche immédiatement après une écriture réussie. Il peut ajouter du travail pour écrire des transactions car l'index est immédiatement mis à jour.

MANUAL

N'actualisez pas l'index automatiquement. Les enregistrements nouveaux ou mis à jour peuvent ne pas apparaître dans la recherche par mot clé ou hybride tant que vous n'avez pas exécuté vous-même l'opération de synchronisation d'index côté base de données. Cela est utile pour les chargements en masse ou les fenêtres de maintenance dans lesquelles vous souhaitez contrôler l'actualisation des exécutions de travail.

AUTO

Laissez Oracle actualiser l'index hybride géré de manière asynchrone. Les écritures peuvent éviter le coût d'actualisation immédiat, mais les résultats de la recherche peuvent différer des écritures récentes jusqu'à ce qu'Oracle termine l'actualisation en arrière-plan. Ce mode est pris en charge uniquement avec SearchStrategy.HYBRID.

Avertissement : ce paramètre contrôle la maintenance continue après l'existence de l'index de recherche géré. Il ne rend pas le premier build d'index asynchrone. La création d'un index hybride géré sur du texte de recherche stocké existant peut être longue car Oracle construit l'état de l'index hybride géré à partir de ce texte.

AUTO = 'AUTO'

MANUEL = 'manuel'

ON_COMMIT = 'ON_COMMIT'

Durée de vie

classe oracleagentmemory.core.retention.MemoryRetentionConfig

Bases : object

Paramètres de conservation de niveau schéma pour les enregistrements sauvegardés par Oracle DB.

• Paramètres:
  • default_ttl_days int | None : durée de vie par défaut, en jours. Conservez la valeur NOT_SET_MARKER pour utiliser la valeur par défaut None (pas de valeur maximale).
  • max_ttl_days int | None : durée de vie maximale (en jours) facultative. Conservez la valeur NOT_SET_MARKER pour utiliser la valeur par défaut de None. Transmettez None sans limite maximale. Lorsqu'elle est définie, il s'agit d'une limitation stricte : les écritures qui tentent d'utiliser une valeur ttl_days supérieure sont bloquées à cette valeur maximale avec un avertissement, et les API d'écriture qui transmettent ttl_days=None utilisent cette valeur maximale au lieu de créer des enregistrements qui n'expirent pas.

classe oracleagentmemory.apis.ttl.TimeToLiveAnchor

Bases : Enum

Ancrage utilisé pour calculer un horodatage d'expiration à partir d'une durée de vie.

CREATED_AT

Calculer l'expiration à partir de l'horodatage de création de la base de données de l'enregistrement. Il s'agit de la valeur par défaut lorsque les appelants omettent ttl_anchor.

TIMESTAMP

Calculer l'expiration à partir de l'horodatage de l'événement stocké de l'enregistrement. Utilisez cette option lorsqu'un message ou une mémoire représente un événement plus ancien et doit expirer par rapport à l'heure de l'événement au lieu de l'heure d'insertion.

CREATED_AT = 'CREATED_AT'

TIMESTAMP = 'TIMESTAMP'

Stratégie de schéma

classe oracleagentmemory.core.SchemaPolicy

Bases : str, Enum

Stratégie de création de schéma pour les banques Oracle DB.

EXIGER_EXISTANT

Vérifiez que le schéma géré complet existe déjà et qu'il est à jour. Ne créez ni ne modifiez des objets de base de données.

CREATE_IF_EMPTY

S'il n'existe aucun objet géré, initialisez le schéma. Si des objets existent déjà, vous devez disposer d'un schéma géré complet et à jour.

CRÉER_SI_NÉCESSAIRE

Créez les objets gérés manquants et appliquez les mises à niveau de schéma géré prises en charge.

RECRÉER

Supprimez et recréez tous les objets de schéma gérés. C'est destructeur.

NO_CHECK

Ignorer la validation et la création de schéma géré. Utilisez cette stratégie pour un emplacement de stockage protégé par la sécurité des données profondes existant tant qu'un contexte de sécurité de l'utilisateur final est actif. Un emplacement de stockage ouvert sous un contexte d'utilisateur final nécessite un contexte actif pour chaque opération de base de données suivante. D'autres stratégies de schéma rejettent les contextes de l'utilisateur final car le travail du cycle de vie du schéma doit être exécuté via une identité de base de données administrative.