Almacenes y esquema

Esta página presenta las abstracciones del almacén principal y los controles de esquema utilizados por el SDK de memoria del agente de Oracle.

API de tienda

Semántica de escritura de tienda

Las escrituras de almacén mantienen una separación clara entre el texto que almacena una aplicación y la carga útil que utiliza el almacén para la recuperación. La mayoría de las aplicaciones pueden utilizar las API de nivel de memoria y de thread y permitir que el almacén prepare las filas de búsqueda que necesita para la recuperación de vectores, palabras clave o híbridos. Las API de almacén de nivel inferior muestran index_texts, index_text, embeddings y embedding para integraciones avanzadas que ya saben qué texto o vectores se deben utilizar para la recuperación.

Piense en cada escritura como dos piezas relacionadas:

• contents en add() y content en update() controlan el contenido del registro almacenado devuelto por get(), list() y los resultados de búsqueda.
• index_texts en add() y index_text en update() controlan el texto escrito en las filas de recuperación del almacén. La búsqueda utiliza esas filas y, a continuación, devuelve los registros lógicos originales.

update() también acepta text como parámetro de compatibilidad en desuso. Utilice content en el nuevo código; al proporcionar text se emite una advertencia de desuso.

Si no se proporciona ninguna sustitución de búsqueda ni embebido explícito, el almacén utiliza el texto almacenado resuelto como texto de recuperación. El almacén fragmenta el texto no vacío cuando se configura la fragmentación. El texto vacío almacena el texto del registro, pero no proporciona texto de recuperación.

La siguiente tabla describe cómo se selecciona el texto de recuperación antes de considerar las cargas útiles de vectores explícitos.

Cargas útiles de recuperación a nivel de almacén

Entrada	add()	update()
index_texts o index_text omitidos	Cada registro utiliza su valor contents resuelto para la recuperación.	Se utiliza un valor content de sustitución para la recuperación. Si también se omite content, las actualizaciones de solo incrustación reutilizan las filas de texto de recuperación existentes del registro.
Entrada de cadena index_texts o cadena index_text	La cadena sustituye el texto de recuperación de ese registro. El almacén puede fragmentarlo antes de escribir filas de recuperación.	La cadena sustituye el texto de recuperación de ese registro. El almacén puede fragmentarlo antes de escribir filas de recuperación.
Entrada list[str] index_texts o list[str] index_text	La lista se trata como fragmentos propiedad de la persona que llama. Cada cadena que no está vacía se escribe como una fila de recuperación y el almacén no la fragmenta de nuevo.	La lista se trata como fragmentos propiedad de la persona que llama. Cada cadena que no está vacía se escribe como una fila de recuperación y el almacén no la fragmenta de nuevo.
Entrada None index_texts o index_text=None	None en la lista externa index_texts significa "usar el contenido almacenado para este registro".	index_text=None borra las filas de recuperación al dejar el contenido almacenado sin cambios, a menos que también se proporcione content.
Cadena vacía o lista de fragmentos vacía	Almacena el contenido del registro y no proporciona texto de recuperación para ese registro.	Actualiza el contenido del registro cuando se proporciona content y borra el texto de recuperación para ese registro.

Las incrustaciones explícitas son opcionales. Cuando se omiten, el almacén deriva vectores locales del texto de recuperación cuando se configura el almacenamiento de vectores locales; los almacenes de palabras clave o híbridos también pueden utilizar filas de recuperación de solo texto. Cuando se proporcionan valores embeddings o embedding explícitos, el almacén escribe esos vectores directamente y no llama a su embebido para esos vectores.

En add(), embeddings=None se comporta como omitir embeddings. En update(), embedding=None es explícito: el almacén mantiene o reescribe el texto de recuperación según content y index_text, pero almacena esas filas sin vectores locales. Si se omiten content y index_text, se borrarán los vectores de las filas de recuperación existentes.

La forma del vector indica a la tienda cuánta propiedad del fragmento está tomando la persona que llama:

• Un vector significa un vector para todo el texto de recuperación. El almacén no divide ese texto para el vector explícito. Si el texto de recuperación está vacío, el vector se puede almacenar sin texto de fragmento complementario.
• varios vectores significan un vector por fragmento propiedad de la persona que llama. Proporcione listas de fragmentos index_texts o index_text coincidentes, o bien utilice un update() de solo embebido que reutilice las filas de texto de recuperación existentes del registro.
• los recuentos de vectores deben coincidir con los recuentos de fragmentos y todos los vectores explícitos de una llamada add() deben tener la misma dimensión.
• solo se permite una carga útil de vector vacía por registro cuando no hay filas de texto de recuperación que alineen con ella.

Algunas combinaciones se rechazan para que el texto almacenado, el texto de recuperación y los vectores no se desvíen. Al transferir content=None, se borra el contenido almacenado y las filas de recuperación, por lo que no se puede combinar con valores index_text o embedding no nulos; los registros de perfil de actor no soportan content=None. El parámetro text en desuso tiene el mismo comportamiento. La transferencia de index_text=None en update() significa "borrar filas de recuperación", por lo que no se permiten incrustaciones explícitas no vacías en la misma llamada. Varios vectores explícitos necesitan texto de fragmento explícito, a menos que la actualización sea de solo embebido y las filas de recuperación existentes ya proporcionen el texto de fragmento.

clase oracleagentmemory.core.OracleMemoryStore

Bases: IMemoryStore

Interfaz de almacén común utilizada por OracleAgentMemory.

La implantación de un almacén es responsable de mantener los registros de texto y realizar una búsqueda de similitud sobre ellos. Tanto los puntos de entrada síncronos como los asíncronos se definen para que las API de nivel superior puedan exponer las superficies de sincronización/asíncronas coincidentes sin duplicar la lógica específica del almacén.

método add

Agregue registros a la tienda.

• Parámetros:
  • contents Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]: secuencia de solo lectura de cargas útiles de registro. Las entradas de mensajes pueden contener partes MessageContent ordenadas, mientras que las entradas de resumen de thread pueden ser asignaciones. Los valores de texto también se utilizan para la indexación semántica a menos que se proporcionen index_texts o embeddings. Cuando un valor de texto es None, las implantaciones pueden volver a ser metadata["content"]. Las cadenas vacías explícitas se conservan.
  • record_type str: tipo de registro lógico para crear, por ejemplo, "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" o "thread_summary".
  • index_texts list[str | list[str] | None]: cargas útiles alternativas opcionales que se utilizan solo para la indexación semántica. Cuando se proporciona, la lista externa debe alinearse con las entradas de texto. Cada entrada puede ser una cadena, que la tienda puede fragmentar internamente, o una lista de cadenas no vacías, que la tienda trata como fragmentos propiedad de la persona que llama y no debe dividirse de nuevo.
  • embeddings list[list[float] | ndarray | list[list[float] | ndarray]]: vectores de incrustación precalculados opcionales alineados con las entradas de texto. Cada entrada de registro puede ser un vector de incrustación o una lista de vectores de incrustación de fragmentos para ese registro. Cuando se proporciona, la tienda debe utilizar estos vectores directamente en lugar de llamar a su embebedor. Para varios vectores de un registro es necesario que coincidan con las listas de fragmentos index_texts para que los límites de fragmentos de texto y vector sean explícitos. Si no se proporciona, los almacenes suelen derivar el estado semántico de su embebido configurado, pero los modos de indexación adaptados al texto específicos de la implantación también pueden permitir escrituras de solo texto sin uno.
  • record_ids str | None | list[str | None]: identificadores visibles para el emisor de llamada opcionales. Se puede utilizar una sola cadena para inserciones de un solo registro, mientras que las listas deben alinearse con las entradas de texto. Los identificadores generados se devuelven cuando se omite este campo.
  • thread_ids str | None | list[str | None]: identificadores de subprocesos opcionales asociados con los registros insertados. Los valores escalares se pueden difundir entre entradas de texto alineadas.
  • user_ids str | None | list[str | None]: identificadores de usuario opcionales asociados con los registros insertados. Los valores escalares se pueden difundir entre entradas de texto alineadas.
  • agent_ids str | None | list[str | None]: identificadores de agente opcionales asociados con los registros insertados. Los valores escalares se pueden difundir entre entradas de texto alineadas.
  • roles str | None | list[str | None]: roles de mensajes opcionales, como "user" o "assistant". Los valores escalares se pueden difundir entre entradas de texto alineadas. Se utiliza solo si record_type es "message".
  • timestamps str | None | list[str | None]: registros de hora opcionales para guardar con los registros. Cada registro de hora representa un evento asociado con el registro. Los valores escalares se pueden difundir entre entradas de texto alineadas. Las entradas omitidas o None almacenan un registro de hora de evento NULL; las lecturas utilizan la hora de creación del registro como registro de hora efectivo.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: diccionarios de metadatos opcionales proporcionados por el emisor de llamada. Los metadatos pueden incluir "content" como origen de reserva cuando se omite un valor de texto en lugar de definirse explícitamente en "". Cuando es record_type="image", cada escritura de imagen necesita "image_mime_type" con uno de los valores "image/png", "image/jpeg" o "image/webp". El almacén utiliza este campo para guardar la imagen, pero no la devuelve como parte de los metadatos del registro.
  • ttl_days int | None | list[int | None]: duración opcional del tiempo de vida en días para los registros que admiten la caducidad. Omita este argumento para utilizar el valor por defecto del almacén. Transfiera None para los registros que no deben caducar. Los valores escalares se pueden difundir entre entradas de texto alineadas.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]: anclaje de tiempo de vida opcional. Utilice TimeToLiveAnchor.CREATED_AT para que caduque en relación con el tiempo de creación almacenado o TimeToLiveAnchor.TIMESTAMP para que caduque en relación con el registro de hora de evento de cada registro. Cuando se omite, las implantaciones utilizan TimeToLiveAnchor.CREATED_AT.
  • statuses RecordStatus | list[RecordStatus]: estados de ciclo de vida opcionales para los registros. Omita esta opción para almacenar RecordStatus.VALID.
  • **store_kwargs (Cualquiera): opciones de escritura específicas de implantación reenviadas al almacén concreto.
• Tipo de devolución: list[str]

Notas

Utilice add_batches() cuando el emisor de llamada ya tenga uno o más objetos PendingRecordBatch.

• Devoluciones: identificadores para los registros insertados, en el mismo orden lógico que la entrada.
• Tipo de devolución: List[str]
• Parámetros:
  • contenido Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
  • tipo_registro str
  • index_texts list[str | list[str] | None]
  • embeddings 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]
  • roles str | None | list[str | None]
  • timestamps str | None | list[str | None]
  • metadatos dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • statuses RecordStatus | list[RecordStatus]
  • store_kwargs Any

method add_agent (resumen)

Agregue un registro de perfil de agente.

• Parámetros:
  • agent_id str: identificador estable para el perfil de agente.
  • information str: texto de formato libre que describe el agente.
  • metadata dict[str, Any] | None: asignación de metadatos opcional almacenada en la fila del perfil de agente.
• Devoluciones: identificador del registro de perfil de agente creado.
• Tipo de devolución: str

method add_agent_async (async)

Agregue un registro de perfil de agente de forma asíncrona.

• Parámetros:
  • agent_id str: identificador estable para el perfil de agente.
  • information str: texto de formato libre que describe el agente.
  • metadata dict[str, Any] | None: asignación de metadatos opcional almacenada en la fila del perfil de agente.
• Devoluciones: identificador del registro de perfil de agente creado.
• Tipo de devolución: str

method add_async (async)

Agregar de forma asíncrona registros orientados a filas al almacén.

Acepta los mismos argumentos y devuelve los mismos identificadores que add().

• Parámetros:
  • contenido Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
  • tipo_registro str
  • index_texts list[str | list[str] | None]
  • embeddings 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]
  • roles str | None | list[str | None]
  • timestamps str | None | list[str | None]
  • metadatos dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • statuses RecordStatus | list[RecordStatus]
  • store_kwargs Any
• Tipo de devolución: list[str]

método add_batches

Agregue lotes lógicos preparados por el emisor de llamada al almacén.

• Parámetros:
  • lotes list[PendingRecordBatch]: lotes lógicos completamente preparados para que persistan. Cada lote debe incluir sus propios campos por registro, como record_type, valores de ámbito, roles, registros de hora y metadatos.
  • **store_kwargs (Cualquiera): opciones de escritura específicas de implantación reenviadas al almacén concreto.
• Devoluciones: identificadores de los registros insertados, en el mismo orden lógico que los lotes y las filas de entrada.
• Tipo de devolución: List[str]

Ejemplos

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

method add_batches_async (async)

Agregue lotes lógicos preparados por el emisor de llamada de forma asíncrona al almacén.

Acepta los mismos argumentos y devuelve los mismos identificadores que add_batches().

• Parámetros:
  • lotes list[PendingRecordBatch]
  • store_kwargs Any
• Tipo de devolución: list[str]

method add_relations (resumen)

Almacenar una o más relaciones dirigidas.

Los valores escalares se transmiten a través del lote de registro de origen. Los valores de lista deben tener la misma longitud. Solo se puede almacenar una orientación para un par de puntos finales. Utilice opposite_relation_types para describir la vista inversa en lugar de agregar una segunda relación inversa. Las implantaciones pueden restringir qué tipos de registro de punto final y etiquetas de relación persisten.

• Parámetros:
  • source_record_ids str | list[str]: identificador o identificadores de registros en el extremo de origen de cada relación dirigida.
  • source_record_types str | list[str]: tipo o tipos de registro para source_record_ids. Proporcione un valor para todos los orígenes o un valor para cada relación.
  • target_record_ids str | list[str]: identificador o identificadores de registros en el extremo de destino de cada relación dirigida.
  • target_record_types str | list[str]: tipo o tipos de registro para target_record_ids. Proporcione un valor para todos los destinos o un valor para cada relación.
  • relation_types str | list[str]: etiqueta o etiquetas de relación dirigida. Proporcione un valor para todas las relaciones o un valor para cada relación.
  • opposite_relation_types str | list[str]: etiqueta o etiquetas opcionales para la vista inversa de cada relación. Para los tipos de relación de memoria incorporados, la omisión utiliza la etiqueta inversa predefinida. Para los tipos de relación personalizados, la omisión utiliza la misma etiqueta en ambas direcciones.
  • relation_ids str | None | list[str | None]: identificador o identificadores estables opcionales. Omita esta opción para permitir que la tienda genere identificadores.
  • timestamps str | None | list[str | None]: registro de hora o registros de hora opcionales para almacenar en las relaciones.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: objeto u objetos de metadatos opcionales para almacenar en las relaciones.
• Devoluciones: identificadores de relación en orden de entrada.
• Tipo de devolución: list[str]

Ejemplos

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

method add_relations_async (async)

Almacene de forma asíncrona una o más relaciones dirigidas.

Los valores escalares se transmiten a través del lote de registro de origen. Los valores de lista deben tener la misma longitud. Solo se puede almacenar una orientación para un par de puntos finales. Utilice opposite_relation_types para describir la vista inversa en lugar de agregar una segunda relación inversa.

• Parámetros:
  • source_record_ids str | list[str]: identificador o identificadores de registros en el extremo de origen de cada relación dirigida.
  • source_record_types str | list[str]: tipo o tipos de registro para source_record_ids. Proporcione un valor para todos los orígenes o un valor para cada relación.
  • target_record_ids str | list[str]: identificador o identificadores de registros en el extremo de destino de cada relación dirigida.
  • target_record_types str | list[str]: tipo o tipos de registro para target_record_ids. Proporcione un valor para todos los destinos o un valor para cada relación.
  • relation_types str | list[str]: etiqueta o etiquetas de relación dirigida. Proporcione un valor para todas las relaciones o un valor para cada relación.
  • opposite_relation_types str | list[str]: etiqueta o etiquetas opcionales para la vista inversa de cada relación. Para los tipos de relación de memoria incorporados, la omisión utiliza la etiqueta inversa predefinida. Para los tipos de relación personalizados, la omisión utiliza la misma etiqueta en ambas direcciones.
  • relation_ids str | None | list[str | None]: identificador o identificadores estables opcionales. Omita esta opción para permitir que la tienda genere identificadores.
  • timestamps str | None | list[str | None]: registro de hora o registros de hora opcionales para almacenar en las relaciones.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: objeto u objetos de metadatos opcionales para almacenar en las relaciones.
• Devoluciones: identificadores de relación en orden de entrada.
• Tipo de devolución: list[str]

Ejemplos

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

method add_user (resumen)

Agregue un registro de perfil de usuario.

• Parámetros:
  • user_id str: identificador estable para el perfil de usuario. Las implantaciones respaldadas por base de datos pueden inferir este valor a partir de un contexto de seguridad de usuario final asociado cuando se omite.
  • information str: texto de formato libre necesario que describe al usuario.
  • metadata dict[str, Any] | None: asignación de metadatos opcional almacenada en la fila del perfil de usuario.
• Devoluciones: identificador del registro de perfil de usuario creado.
• Tipo de devolución: str

method add_user_async (async)

Agregue un registro de perfil de usuario de forma asíncrona.

• Parámetros:
  • user_id str: identificador estable para el perfil de usuario.
  • information str: texto de formato libre que describe al usuario.
  • metadata dict[str, Any] | None: asignación de metadatos opcional almacenada en la fila del perfil de usuario.
• Devoluciones: identificador del registro de perfil de usuario creado.
• Tipo de devolución: str

method delete (resumen)

Elimine un registro almacenado por identificador.

• Parámetros:
  • record_type str: tipo lógico del registro que se debe eliminar.
  • record_id str: identificador del registro que se debe eliminar.
  • cascade bool: cuando es True, aplique cualquier comportamiento de supresión en cascada admitido por el almacén para los destinos de nivel superior solicitados dentro de la misma operación de supresión. Esto se utiliza principalmente para destinos como los perfiles de actor que poseen registros de ámbito adicionales. Por ejemplo, una cascada de perfil de usuario o perfil de agente puede suprimir los propios threads, los mensajes de ámbito de thread y los registros similares a la memoria eliminados con esos threads, así como cualquier registro de ámbito de actor directo restante, como mensajes, memorias, directrices, hechos o preferencias. Para las supresiones de perfil de actor, esta limpieza de ámbito puede seguir ejecutándose cuando la fila de perfil coincidente ya está ausente.
• Devoluciones: número de registros de nivel superior solicitados suprimidos, normalmente 0 o 1. Las filas secundarias en cascada no se cuentan por separado, por lo que puede seguir siendo 0 cuando falta un perfil de actor que dispara la limpieza en el ámbito.
• Tipo de devolución: int

method delete_async (async)

Elimine de forma asíncrona un registro almacenado por identificador.

• Parámetros:
  • record_type str: tipo lógico del registro que se debe eliminar.
  • record_id str: identificador del registro que se debe eliminar.
  • cascade bool: cuando es True, aplique cualquier comportamiento de supresión en cascada admitido por el almacén para los destinos de nivel superior solicitados dentro de la misma operación de supresión. Esto se utiliza principalmente para destinos como los perfiles de actor que poseen registros de ámbito adicionales. Por ejemplo, una cascada de perfil de usuario o perfil de agente puede suprimir los propios threads, los mensajes de ámbito de thread y los registros similares a la memoria eliminados con esos threads, así como cualquier registro de ámbito de actor directo restante, como mensajes, memorias, directrices, hechos o preferencias. Para las supresiones de perfil de actor, esta limpieza de ámbito puede seguir ejecutándose cuando la fila de perfil coincidente ya está ausente.
• Devoluciones: número de registros de nivel superior solicitados suprimidos, normalmente 0 o 1. Las filas secundarias en cascada no se cuentan por separado, por lo que puede seguir siendo 0 cuando falta un perfil de actor que dispara la limpieza en el ámbito.
• Tipo de devolución: int

method delete_relations (resumen)

Suprimir relaciones por identificador.

El estado del ciclo de vida se vuelve a calcular a partir de las relaciones que quedan.

• Parámetros: relation_ids str | list[str]: identificador o identificadores de las relaciones que se van a suprimir.
• Devoluciones: número de relaciones suprimidas.
• Tipo de devolución: int

Ejemplos

store.delete_relations("relation-id")
1

method delete_relations_async (async)

Suprimir relaciones de forma asíncrona por identificador.

El estado del ciclo de vida se vuelve a calcular a partir de las relaciones que quedan.

• Parámetros: relation_ids str | list[str]: identificador o identificadores de las relaciones que se van a suprimir.
• Devoluciones: número de relaciones suprimidas.
• Tipo de devolución: int

Ejemplos

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

method delete_thread (resumen)

Suprimir un thread y sus datos almacenados asociados.

• Parámetros: thread_id str: identificador del subproceso que se va a eliminar.
• Devoluciones: número de registros de thread suprimidos, normalmente 0 o 1.
• Tipo de devolución: int

Notas

Ésta es la operación de nivel de almacén para eliminar un thread y los registros de ámbito de thread gestionados por el almacén. Prefiere la supresión de threads cuando los requisitos de retención llaman para suprimir tanto los mensajes de origen como los datos de memoria de ámbito de thread derivados, ya que las supresiones de nivel de mensaje no implican que se eliminen registros derivados persistentes por separado.

method delete_thread_async (async)

Suprima de forma asíncrona un thread y sus datos almacenados asociados.

• Parámetros: thread_id str: identificador del subproceso que se va a eliminar.
• Devoluciones: número de registros de thread suprimidos, normalmente 0 o 1.
• Tipo de devolución: int

Notas

Ésta es la operación de nivel de almacén para eliminar un thread y los registros de ámbito de thread gestionados por el almacén. Prefiere la supresión de threads cuando los requisitos de retención llaman para suprimir tanto los mensajes de origen como los datos de memoria de ámbito de thread derivados, ya que las supresiones de nivel de mensaje no implican que se eliminen registros derivados persistentes por separado.

method get (resumen)

Recupere un registro almacenado por tipo e identificador.

• Parámetros:
  • record_type str: tipo lógico del registro que se va a recuperar, como "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" o "image".
  • record_id str: identificador del registro que se recuperará.
  • include_bytes bool: indica si se deben cargar los bytes de imagen almacenados. Para un registro de mensaje, controla si las imágenes adjuntas incluyen sus bytes. Para un registro de imagen, controla si se cargan los bytes de imagen independientes. Esta opción no afecta a otros tipos de registro.
• Devoluciones: el registro almacenado cuando se encuentra; de lo contrario, None. Una consulta "thread" devuelve un valor ThreadRecord con metadatos de thread, configuración de tiempo de ejecución, estado de tiempo de ejecución y el registro de hora de creación rellenado cuando el almacén soporta threads persistentes.
• Tipo de devolución: Registro | Ninguno

method get_async (async)

Recupere de forma asíncrona un registro almacenado por tipo e identificador.

• Parámetros:
  • record_type str: tipo lógico del registro que se va a recuperar, como "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" o "image".
  • record_id str: identificador del registro que se recuperará.
  • include_bytes bool: indica si se deben cargar los bytes de imagen almacenados. Para un registro de mensaje, controla si las imágenes adjuntas incluyen sus bytes. Para un registro de imagen, controla si se cargan los bytes de imagen independientes. Esta opción no afecta a otros tipos de registro.
• Devoluciones: el registro almacenado cuando se encuentra; de lo contrario, None. Una consulta "thread" devuelve un valor ThreadRecord con metadatos de thread, configuración de tiempo de ejecución, estado de tiempo de ejecución y el registro de hora de creación rellenado cuando el almacén soporta threads persistentes.
• Tipo de devolución: Registro | Ninguno

method get_relation (resumen)

Devuelve una relación en su orientación de origen a destino almacenada.

Proporcione relation_id solo o proporcione una tupla completa de punto final de origen a destino.

• Parámetros:
  • source_record_id str: identificador de registro de origen. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • source_record_type str: tipo de registro de origen. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • target_record_id str: identificador de registro de destino. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • target_record_type str: tipo de registro de destino. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • relation_type str: etiqueta de relación dirigida. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • relation_id str: identificador de relación que debe coincidir directamente. Proporcione este argumento solo en lugar de combinarlo con campos de tupla de punto final.
• Devoluciones: relación coincidente o None cuando no existe.
• Tipo de devolución: RecordRelation | Ninguno

Ejemplos

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

method get_relation_async (async)

Recupere de forma asíncrona una relación por ID o tupla de punto final.

Proporcione relation_id solo o proporcione una tupla completa de punto final de origen a destino.

• Parámetros:
  • source_record_id str: identificador de registro de origen. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • source_record_type str: tipo de registro de origen. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • target_record_id str: identificador de registro de destino. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • target_record_type str: tipo de registro de destino. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • relation_type str: etiqueta de relación dirigida. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • relation_id str: identificador de relación que debe coincidir directamente. Proporcione este argumento solo en lugar de combinarlo con campos de tupla de punto final.
• Devoluciones: relación coincidente o None cuando no existe.
• Tipo de devolución: RecordRelation | Ninguno

Ejemplos

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

method list (resumen)

Mostrar registros almacenados para un tipo de registro.

• Parámetros:
  • record_type str: tipo de registro lógico que se debe enumerar, como "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile", "thread_summary" o "image".
  • limit int | None: número máximo opcional de registros más recientes que se deben devolver. Cuando se omite, las implementaciones pueden aplicar un límite superior seguro, como MAX_LIST_LIMIT. Transfiera None para desactivar ese límite y devolver todos los registros coincidentes.
  • thread_id str | None: filtro de ámbito de thread exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyo valor thread_id es None. Los tipos de registro sin ámbito ignoran este filtro. Cuando record_type es "thread", no se debe definir thread_id; utilice record_id para seleccionar un thread específico.
  • user_id str | None: filtro de ámbito de usuario exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyo valor user_id es None. Los tipos de registro sin ámbito ignoran este filtro.
  • agent_id str | None: filtro de ámbito de agente exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyo valor agent_id es None. Los tipos de registro sin ámbito ignoran este filtro.

  • metadata_filter dict[str, Any] | None:

    Filtro de metadatos. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyos metadatos son None. Cuando se define en un dict, las entradas en metadata_filter se combinan con la semántica AND. Las entradas cuyo valor no es un diccionario de operador de nivel de campo utilizan semántica de coincidencia exacta: la clave solicitada debe existir en los metadatos almacenados. Los diccionarios anidados se comparan de forma recursiva. Los valores escalares y de lista coinciden con la igualdad exacta; el orden de lista y la longitud también deben coincidir. Para probar la pertenencia a una matriz, utilice un diccionario de operador de nivel de campo, como {"tags": {"$array_contains": "prod"}}. Un operando de lista para "$array_contains" significa que todos los valores mostrados deben estar presentes; "$array_contains_any" significa que al menos un valor mostrado debe estar presente. Utilice "$not" para negar otra expresión de nivel de campo en el mismo campo, incluido un diccionario de operador o un valor de coincidencia exacta raw. Las expresiones negativas coinciden cuando falla la expresión positiva, incluidos los campos que faltan; la pertenencia a la matriz negada también coincide con los campos que no son de matriz. Entre los ejemplos se incluyen metadata_filter={"source": "slack"} para un campo escalar, metadata_filter={"review": {"status": "open"}} para un campo anidado y metadata_filter={"tags": ["prod", "urgent"]} para una coincidencia de lista exacta. Combinar condiciones para requerir todas ellas:

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

  • include_bytes bool – Whether image records or images attached to message records include their stored bytes. When omitted or False, image descriptions and metadata are returned without loading bytes. For direct image listings, set this to True only with an exact record_id and at least one exact user, agent, or thread scope filter. This option has no effect on other record types.
  • record_id str: filtro de identificador de registro exacto. Cuando se omite, se devuelven los registros con cualquier identificador. Los filtros de ámbito y metadatos siguen siendo restricciones adicionales.
• Devoluciones: registros ordenados de más antiguos a más recientes en la ventana devuelta.
• Tipo de devolución: List[Registro]

method list_async (async)

Mostrar de forma asíncrona los registros almacenados para un tipo de registro.

• Parámetros:
  • record_type str: tipo de registro lógico que se debe enumerar, como "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" o "image".
  • limit int | None: número máximo opcional de registros más recientes que se deben devolver. Cuando se omite, las implementaciones pueden aplicar un límite superior seguro, como MAX_LIST_LIMIT. Transfiera None para desactivar ese límite y devolver todos los registros coincidentes.
  • thread_id str | None: filtro de ámbito de thread exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyo valor thread_id es None. Los tipos de registro sin ámbito ignoran este filtro. Cuando record_type es "thread", no se debe definir thread_id; utilice record_id para seleccionar un thread específico.
  • user_id str | None: filtro de ámbito de usuario exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyo valor user_id es None. Los tipos de registro sin ámbito ignoran este filtro.
  • agent_id str | None: filtro de ámbito de agente exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyo valor agent_id es None. Los tipos de registro sin ámbito ignoran este filtro.

  • metadata_filter dict[str, Any] | None:

    Filtro de metadatos. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyos metadatos son None. Cuando se define en un dict, las entradas en metadata_filter se combinan con la semántica AND. Las entradas cuyo valor no es un diccionario de operador de nivel de campo utilizan semántica de coincidencia exacta: la clave solicitada debe existir en los metadatos almacenados. Los diccionarios anidados se comparan de forma recursiva. Los valores escalares y de lista coinciden con la igualdad exacta; el orden de lista y la longitud también deben coincidir. Para probar la pertenencia a una matriz, utilice un diccionario de operador de nivel de campo, como {"tags": {"$array_contains": "prod"}}. Un operando de lista para "$array_contains" significa que todos los valores mostrados deben estar presentes; "$array_contains_any" significa que al menos un valor mostrado debe estar presente. Utilice "$not" para negar otra expresión de nivel de campo en el mismo campo, incluido un diccionario de operador o un valor de coincidencia exacta raw. Las expresiones negativas coinciden cuando falla la expresión positiva, incluidos los campos que faltan; la pertenencia a la matriz negada también coincide con los campos que no son de matriz. Entre los ejemplos se incluyen metadata_filter={"source": "slack"} para un campo escalar, metadata_filter={"review": {"status": "open"}} para un campo anidado y metadata_filter={"tags": ["prod", "urgent"]} para una coincidencia de lista exacta. Combinar condiciones para requerir todas ellas:

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

  • include_bytes bool – Whether image records or images attached to message records include their stored bytes. When omitted or False, image descriptions and metadata are returned without loading bytes. For direct image listings, set this to True only with an exact record_id and at least one exact user, agent, or thread scope filter. This option has no effect on other record types.
  • record_id str: filtro de identificador de registro exacto. Cuando se omite, se devuelven los registros con cualquier identificador. Los filtros de ámbito y metadatos siguen siendo restricciones adicionales.
• Devoluciones: registros ordenados de más antiguos a más recientes en la ventana devuelta.
• Tipo de devolución: List[Registro]

method list_relations (resumen)

Enumere las relaciones almacenadas en su orientación de origen a destino.

• Parámetros:
  • relation_type str: etiqueta de relación dirigida opcional para que coincida, como "supports" o "supersedes". Omita incluir todos los tipos de relación.
  • source_record_id str: identificador de registro de origen opcional que debe coincidir.
  • source_record_type str: tipo de registro de origen opcional que debe coincidir.
  • target_record_id str: identificador de registro de destino opcional que coincide.
  • target_record_type str: tipo de registro de destino opcional que coincide.
  • limit int | None: número máximo opcional de relaciones creadas más recientemente que se deben devolver. Cuando se omite, las implementaciones pueden aplicar un límite superior seguro, como MAX_LIST_LIMIT. Transfiera None para devolver todas las relaciones almacenadas coincidentes.
  • metadata_filter dict[str, Any] | None: filtro de metadatos. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven las relaciones cuyos metadatos son None. Cuando se define en un dict, las entradas se combinan con la semántica AND. Los diccionarios anidados utilizan la coincidencia exacta recursiva. Los valores escalares y de lista requieren igualdad exacta; utilice {"tags": {"$array_contains": "prod"}} para hacer coincidir la pertenencia a la matriz, "$array_contains_any" para hacer coincidir cualquier valor mostrado o "$not" para negar otra expresión de campo.
  • relation_id str: filtro de identificador de relación exacto. Cuando se omite, se devuelven las relaciones con cualquier identificador. Otros filtros siguen siendo restricciones adicionales.
• Devoluciones: relaciones ordenadas por hora de creación e identificador.
• Tipo de devolución: list[RecordRelation]

Ejemplos

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

method list_relations_async (async)

Mostrar de forma asíncrona las relaciones en la orientación de origen a destino.

• Parámetros:
  • relation_type str: etiqueta de relación dirigida opcional para que coincida, como "supports" o "supersedes". Omita incluir todos los tipos de relación.
  • source_record_id str: identificador de registro de origen opcional que debe coincidir.
  • source_record_type str: tipo de registro de origen opcional que debe coincidir.
  • target_record_id str: identificador de registro de destino opcional que coincide.
  • target_record_type str: tipo de registro de destino opcional que coincide.
  • limit int | None: número máximo opcional de relaciones creadas más recientemente que se deben devolver. Cuando se omite, las implementaciones pueden aplicar un límite superior seguro, como MAX_LIST_LIMIT. Transfiera None para devolver todas las relaciones almacenadas coincidentes.
  • metadata_filter dict[str, Any] | None: filtro de metadatos. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven las relaciones cuyos metadatos son None. Cuando se define en un dict, las entradas se combinan con la semántica AND. Los diccionarios anidados utilizan la coincidencia exacta recursiva. Los valores escalares y de lista requieren igualdad exacta; utilice {"tags": {"$array_contains": "prod"}} para hacer coincidir la pertenencia a la matriz, "$array_contains_any" para hacer coincidir cualquier valor mostrado o "$not" para negar otra expresión de campo.
  • relation_id str: identificador de relación opcional para que coincida directamente.
• Devoluciones: relaciones ordenadas por hora de creación e identificador.
• Tipo de devolución: list[RecordRelation]

Ejemplos

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

method list_thread_messages (resumen)

Mostrar el historial de mensajes almacenado para un thread.

• Parámetros:
  • thread_id str: identificador del thread cuyos mensajes se deben devolver.
  • last_n int | None: número opcional de mensajes más recientes que se deben incluir. Cuando se omite, se devuelven todos los mensajes almacenados para el thread. Cuando se combina con un rango de secuencias, el límite se aplica dentro de ese rango.
  • range_start_seq_no int | None: límite de secuencia inferior inclusivo opcional. Solo se devuelven los mensajes cuyo valor seq_no sea al menos este valor.
  • range_end_seq_no int | None: límite de secuencia superior exclusivo opcional. Solo se devuelven los mensajes cuyo valor seq_no es menor que este valor.
  • include_bytes bool: indica si las partes de la imagen anexadas a los mensajes devueltos incluyen sus bytes almacenados. Cuando se omite o False, se devuelven descripciones de imágenes y metadatos sin cargar bytes.
• Devoluciones: registros de mensajes ordenados de más antiguo a más reciente dentro de la ventana devuelta.
• Tipo de devolución: List[MessageRecord]

method list_thread_messages_async (async)

Mostrar de forma asíncrona el historial de mensajes almacenado para un thread.

• Parámetros:
  • thread_id str: identificador del thread cuyos mensajes se deben devolver.
  • last_n int | None: número opcional de mensajes más recientes que se deben incluir. Cuando se omite, se devuelven todos los mensajes almacenados para el thread. Cuando se combina con un rango de secuencias, el límite se aplica dentro de ese rango.
  • range_start_seq_no int | None: límite de secuencia inferior inclusivo opcional. Solo se devuelven los mensajes cuyo valor seq_no sea al menos este valor.
  • range_end_seq_no int | None: límite de secuencia superior exclusivo opcional. Solo se devuelven los mensajes cuyo valor seq_no es menor que este valor.
  • include_bytes bool: indica si las partes de la imagen anexadas a los mensajes devueltos incluyen sus bytes almacenados. Cuando se omite o False, se devuelven descripciones de imágenes y metadatos sin cargar bytes.
• Devoluciones: registros de mensajes ordenados de más antiguo a más reciente dentro de la ventana devuelta.
• Tipo de devolución: List[MessageRecord]

method search (resumen)

Buscar registros por similitud.

• Parámetros:
  • query str | None: consulta en lenguaje natural. Se debe proporcionar cuando se omite query_vector.
  • query_vector list[float] | None: incrustación opcional de consultas calculadas previamente. Se debe proporcionar exactamente uno de query y query_vector.
  • k int: número máximo de resultados que se deben devolver. Los valores explícitos deben ser al menos 1. Este es un límite superior: la llamada puede devolver menos de k resultados cuando los filtros son demasiado restrictivos, cuando existen menos registros coincidentes no vencidos o debido al comportamiento de búsqueda específico de la implementación.
  • thread_id str | None: ámbito de subproceso opcional.
  • user_id str | None: filtros de ámbito de agente y usuario opcionales.
  • agent_id str | None: filtros de ámbito de agente y usuario opcionales.
  • exact_user_match bool: indica si cada identificador de ámbito proporcionado debe coincidir exactamente.
  • exact_agent_match bool: indica si cada identificador de ámbito proporcionado debe coincidir exactamente.
  • exact_thread_match bool: indica si cada identificador de ámbito proporcionado debe coincidir exactamente.
  • record_types set[str] | None: conjunto opcional de tipos de registro que se deben incluir.
  • metadata_filter dict[str, Any] | None: asignación de filtros de metadatos opcional. Las entradas en metadata_filter se combinan con la semántica AND. Las entradas cuyo valor no es un diccionario de operador de nivel de campo utilizan semántica de coincidencia exacta: la clave solicitada debe existir en los metadatos almacenados. Los diccionarios anidados se comparan de forma recursiva. Los valores escalares y de lista coinciden con la igualdad exacta; el orden de lista y la longitud también deben coincidir. Para probar la pertenencia a una matriz, utilice un diccionario de operador de nivel de campo, como {"tags": {"$array_contains": "prod"}}. Un operando de lista para "$array_contains" significa que todos los valores mostrados deben estar presentes; "$array_contains_any" significa que al menos un valor mostrado debe estar presente. Utilice "$not" para negar otra expresión de nivel de campo en el mismo campo, incluido un diccionario de operador o un valor de coincidencia exacta raw. Las expresiones negativas coinciden cuando falla la expresión positiva, incluidos los campos que faltan; la pertenencia a la matriz negada también coincide con los campos que no son de matriz.
  • include_invalid_results bool: indica si los resultados incluyen registros similares a la memoria en el estado no válido. El valor por defecto es True. Transfiera False para excluirlos.
  • num_hops int: número de bordes de enlace de memoria que se deben seguir de cada resultado de memoria directa. Se admiten los valores de 0 a 5; 0 desactiva la expansión de gráficos.
  • max_linked_results int: máximo de memorias enlazadas en todos los saltos asociados a cada resultado directo. 0 mantiene los resultados directos sin contexto enlazado. El valor por defecto es 100.
• Devoluciones: pares (record, distance) ordenados por distancia creciente. La lista puede contener menos de k entradas.
• Tipo de devolución: list[tuple[Registro, float]]
• Problemas: ValueError: si k es menor que 1.

Ejemplos

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'

Filtrar en un valor de metadatos escalar:

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

Filtrar por metadatos anidados:

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

Hacer coincidir un valor de lista exactamente, incluido el orden:

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

Filtrar cuando una matriz de metadatos contiene un valor:

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

Combinar varias condiciones de metadatos. Un registro debe satisfacer todas las claves:

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)

Busque registros de forma asíncrona por similitud semántica.

• Parámetros:
  • query str | None: el mismo texto de consulta aceptado por search.
  • k int: el mismo recuento máximo de resultados aceptado por search. Los valores explícitos deben ser al menos 1.
  • query_vector list[float] | None: la misma incrustación opcional de consulta calculada previamente aceptada por search.
  • thread_id str | None: los mismos filtros de ámbito opcionales aceptados por search.
  • user_id str | None: los mismos filtros de ámbito opcionales aceptados por search.
  • agent_id str | None: los mismos filtros de ámbito opcionales aceptados por search.
  • exact_user_match bool: los mismos indicadores de coincidencia exacta que acepta search.
  • exact_agent_match bool: los mismos indicadores de coincidencia exacta que acepta search.
  • exact_thread_match bool: los mismos indicadores de coincidencia exacta que acepta search.
  • record_types set[str] | None: el mismo filtro de tipo de registro opcional aceptado por search.
  • metadata_filter dict[str, Any] | None: el mismo filtro de metadatos opcional aceptado por search, incluidos escalar, anidado, lista exacta, pertenencia a una matriz y condiciones combinadas, como {"source": "slack"}, {"review": {"status": "open"}}, {"tags": ["prod", "urgent"]} y {"tags": {"$array_contains": "prod"}}.
  • include_invalid_results bool: la misma opción de resultado de estado de ciclo de vida aceptada por search.
  • num_hops int: la misma profundidad de expansión de gráficos aceptada por search.
  • max_linked_results int: el mismo límite de memoria enlazada por resultado directo aceptado por search.
• Devoluciones: pares (record, distance) devueltos por la llamada search subyacente.
• Tipo de devolución: List[tuple[Registro, float]]
• Problemas: ValueError: si k es menor que 1.

method update (resumen)

Actualizar el contenido del registro almacenado, incrustar datos, metadatos, registro de hora o caducidad.

• Parámetros:
  • record_type str: tipo lógico del registro que se debe actualizar.
  • record_id str: identificador del registro que se debe actualizar.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None: contenido de sustitución canónico. Para los registros message, transfiera una cadena o una secuencia ordenada de partes de contenido de texto e imagen; utilice "" para sustituir el mensaje por texto vacío. Para los registros similares a la memoria, los almacenes pueden aceptar None para borrar el texto almacenado y el estado semántico asociado. Omita el argumento para dejar el contenido sin cambios. No lo proporcione junto con text.
  • index_text str | list[str] | None: carga útil semántica alternativa opcional que se utiliza para volver a calcular o reemplazar el estado de búsqueda almacenado sin cambiar el texto persistente. Una cadena puede ser fragmentada internamente por la tienda. Una lista de cadenas no vacías se trata como fragmentos propiedad del emisor de llamada y no se debe volver a dividir. Algunas implementaciones también pueden persistir esto por separado como texto de búsqueda híbrida. Para un registro image, este campo sustituye la descripción de la imagen guardada.
  • embedding list[float] | ndarray | list[list[float] | ndarray] | None: vector de incrustación precalculado opcional o lista de vectores de incrustación de fragmentos. Cuando se proporciona, se utiliza directamente y no se realiza ninguna llamada de embebido. Varios vectores necesitan listas de fragmentos index_text coincidentes o filas de texto de fragmento almacenadas existentes. Transfiera None para borrar explícitamente la embebida almacenada cuando el almacén la admita. Las tiendas con indexación adaptada al texto también pueden permitir actualizaciones semánticas sin embeber ni embeber explícitamente.
  • metadata dict[str, Any] | None: asignación de metadatos de sustitución opcional. Transfiera None para borrar los metadatos cuando el almacén los soporte. La sustitución de la imagen content necesita "image_mime_type" en esta asignación. El almacén utiliza este campo para guardar la imagen, pero no la devuelve como parte de los metadatos del registro.
  • timestamp str | None: nuevo registro de hora opcional para guardar con el registro. Representa el momento en que se creó el registro. Omita este argumento para dejar el registro de hora almacenado sin cambios. Transfiera None para borrar el registro de hora guardado y utilice el tiempo que el registro se agregó a la tienda cuando la tienda lo admite.
  • ttl_days int | None: refrescamiento de caducidad opcional en días. Omita este argumento junto con ttl_anchor para conservar el registro de hora de caducidad actual. Transfiera None para borrar la caducidad.
  • ttl_anchor TimeToLiveAnchor: anclaje de tiempo de vida opcional para un refrescamiento de caducidad. Utilice TimeToLiveAnchor.CREATED_AT para la hora de creación del registro o TimeToLiveAnchor.TIMESTAMP para la sustitución timestamp proporcionada en la misma actualización, o el registro de hora del evento almacenado cuando se omite timestamp. Si se proporciona ttl_anchor sin ttl_days, se utiliza la duración de tiempo de actividad por defecto del almacén o esquema. Cuando se omite ttl_anchor durante un refrescamiento, las implantaciones utilizan TimeToLiveAnchor.CREATED_AT.
  • status RecordStatus: estado opcional del ciclo de vida de reemplazo para los registros.

  • text str | None:

    Alias en desuso para content. Transfiera None para borrar explícitamente el texto almacenado cuando el almacén lo soporte. No lo proporcione junto con content.

    En desuso

    En desuso desde la versión 26.8.0: este parámetro estaba en desuso en la versión 26.8.0 y se eliminará en la versión 27.1. Utilice content en su lugar.

• Devoluciones: número de registros actualizados (0 o 1). Un valor de retorno de 0 significa que no se ha actualizado ningún registro.
• Tipo de devolución: int
• Incidencias: ValueError: si la carga útil de actualización no es válida para el almacén, como omitir todos los campos opcionales o proporcionar argumentos semánticos en conflicto.

method update_async (async)

Actualice de forma asíncrona el contenido del registro almacenado, incrustando datos, metadatos, registro de hora o caducidad.

• Parámetros:
  • record_type str: tipo lógico del registro que se debe actualizar.
  • record_id str: identificador del registro que se debe actualizar.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None: contenido de sustitución canónico. Para los registros message, transfiera una cadena o una secuencia ordenada de partes de contenido de texto e imagen; utilice "" para sustituir el mensaje por texto vacío. Para los registros similares a la memoria, los almacenes pueden aceptar None para borrar el texto almacenado y el estado semántico asociado. Omita el argumento para dejar el contenido sin cambios. No lo proporcione junto con text.
  • index_text str | list[str] | None: carga útil semántica alternativa opcional que se utiliza para volver a calcular o reemplazar el estado de búsqueda almacenado sin cambiar el texto persistente. Una cadena puede ser fragmentada internamente por la tienda. Una lista de cadenas no vacías se trata como fragmentos propiedad del emisor de llamada y no se debe volver a dividir. Algunas implementaciones también pueden persistir esto por separado como texto de búsqueda híbrida. Para un registro image, este campo sustituye la descripción de la imagen guardada.
  • embedding list[float] | ndarray | list[list[float] | ndarray] | None: vector de incrustación precalculado opcional o lista de vectores de incrustación de fragmentos. Cuando se proporciona, se utiliza directamente y no se realiza ninguna llamada de embebido. Varios vectores necesitan listas de fragmentos index_text coincidentes o filas de texto de fragmento almacenadas existentes. Transfiera None para borrar explícitamente la embebida almacenada cuando el almacén la admita. Las tiendas con indexación adaptada al texto también pueden permitir actualizaciones semánticas sin embeber ni embeber explícitamente.
  • metadata dict[str, Any] | None: asignación de metadatos de sustitución opcional. Transfiera None para borrar los metadatos cuando el almacén los soporte. La sustitución de la imagen content necesita "image_mime_type" en esta asignación. El almacén utiliza este campo para guardar la imagen, pero no la devuelve como parte de los metadatos del registro.
  • timestamp str | None: nuevo registro de hora opcional para guardar con el registro. Representa el momento en que se creó el registro. Omita este argumento para dejar el registro de hora almacenado sin cambios. Transfiera None para borrar el registro de hora guardado y utilice el tiempo que el registro se agregó a la tienda cuando la tienda lo admite.
  • ttl_days int | None: refrescamiento de caducidad opcional en días. Omita este argumento junto con ttl_anchor para conservar el registro de hora de caducidad actual. Transfiera None para borrar la caducidad.
  • ttl_anchor TimeToLiveAnchor: anclaje de tiempo de vida opcional para un refrescamiento de caducidad. Utilice TimeToLiveAnchor.CREATED_AT para la hora de creación del registro o TimeToLiveAnchor.TIMESTAMP para la sustitución timestamp proporcionada en la misma actualización, o el registro de hora del evento almacenado cuando se omite timestamp. Si se proporciona ttl_anchor sin ttl_days, se utiliza la duración de tiempo de actividad por defecto del almacén o esquema. Cuando se omite ttl_anchor durante un refrescamiento, las implantaciones utilizan TimeToLiveAnchor.CREATED_AT.
  • status RecordStatus: estado opcional del ciclo de vida de reemplazo para los registros. Omitirlo para conservar el estado actual.

  • text str | None:

    Alias en desuso para content. Transfiera None para borrar explícitamente el texto almacenado cuando el almacén lo soporte. No lo proporcione junto con content.

    En desuso

    En desuso desde la versión 26.8.0: este parámetro estaba en desuso en la versión 26.8.0 y se eliminará en la versión 27.1. Utilice content en su lugar.

• Devoluciones: número de registros actualizados (0 o 1). Un valor de retorno de 0 significa que no se ha actualizado ningún registro.
• Tipo de devolución: int
• Incidencias: ValueError: si la carga útil de actualización no es válida para el almacén, como omitir todos los campos opcionales o proporcionar argumentos semánticos en conflicto.

method update_relations (resumen)

Actualizar valores modificables en relaciones almacenadas.

Los campos omitidos permanecen sin cambios, excepto que el cambio a un tipo de relación de memoria incorporada reemplaza su etiqueta inversa con la inversa fija. Un almacén de memoria respaldado por base de datos también recalcula los estados del ciclo de vida de los puntos finales después de un cambio de tipo de relación.

• Parámetros:
  • relation_ids str | list[str]: identificador o identificadores de las relaciones que se van a actualizar.
  • relation_types str | list[str]: etiqueta o etiquetas de relación dirigida de reemplazo opcional. Omita esta opción para conservar las etiquetas almacenadas.
  • opposite_relation_types str | list[str]: etiqueta o etiquetas de relación inversa de sustitución opcionales. Transfiera una etiqueta para sustituirla u omita este argumento para conservarla.
  • timestamps str | None | list[str | None]: registro de hora o registros de hora de sustitución opcionales. Transfiera None para borrar un registro de hora almacenado.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: objeto u objetos de metadatos de sustitución opcionales. Los metadatos proporcionados sustituyen al objeto almacenado; no se fusionan.
• Devoluciones: identificadores de las relaciones que se han actualizado.
• Tipo de devolución: list[str]

Ejemplos

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

method update_relations_async (async)

Actualice de forma asíncrona los valores modificables en las relaciones almacenadas.

Los campos omitidos permanecen sin cambios, excepto que el cambio a un tipo de relación de memoria incorporada reemplaza su etiqueta inversa con la inversa fija. Un almacén de memoria respaldado por base de datos también recalcula los estados del ciclo de vida de los puntos finales después de un cambio de tipo de relación.

• Parámetros:
  • relation_ids str | list[str]: identificador o identificadores de las relaciones que se van a actualizar.
  • relation_types str | list[str]: etiqueta o etiquetas de relación dirigida de reemplazo opcional. Omita esta opción para conservar las etiquetas almacenadas.
  • opposite_relation_types str | list[str]: etiqueta o etiquetas de relación inversa de sustitución opcionales. Transfiera una etiqueta para sustituirla u omita este argumento para conservarla.
  • timestamps str | None | list[str | None]: registro de hora o registros de hora de sustitución opcionales. Transfiera None para borrar un registro de hora almacenado.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: objeto u objetos de metadatos de sustitución opcionales. Los metadatos proporcionados sustituyen al objeto almacenado; no se fusionan.
• Devoluciones: identificadores de las relaciones que se han actualizado.
• Tipo de devolución: list[str]

Ejemplos

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

Almacén de Oracle DB

clase oracleagentmemory.core.OracleDBMemoryStore

Bases: OracleMemoryStore

Persistencia respaldada por base de datos para mensajes, documentos, memorias y perfiles de actores.

Cree un almacén de Oracle DB.

• Parámetros:
  • embedder IEmbedder | None: embebido que se utiliza cuando el almacén necesita incrustaciones de vectores locales. Puede ser None cuando los emisores de llamadas siempre proporcionan vectores previamente calculados o cuando se utiliza la búsqueda por palabras clave con escrituras de solo texto y consultas de texto. SearchStrategy.HYBRID necesita OracleDBEmbedder aquí para que el índice híbrido gestionado pueda utilizar el modelo de base de datos de este embebido.
  • pool Any: conexión o pool de Oracle DB. La transferencia de una conexión raw permite el modo de sesión única para esta instancia de almacén: las llamadas de almacén simultáneas se serializan localmente para conservar las suposiciones de bloqueo de filas y transacción utilizadas por las operaciones de escritura. Utilizar un pool de conexiones para solicitudes simultáneas.
  • schema_policy: SchemaPolicy | str controla cómo se abre o se prepara el esquema gestionado. El valor por defecto es que se necesita un esquema existente actualizado y no realiza cambios de DDL. Para un almacén identificado por memory_store_id, SchemaPolicy.CREATE_IF_NECESSARY crea o repara el esquema cuando es necesario; SchemaPolicy.RECREATE lo borra y lo vuelve a crear. Las versiones de esquema anteriores requieren una actualización de esquema de paquete antes de que se puedan reparar. Cuando se define schema_owner, utilice SchemaPolicy.REQUIRE_EXISTING para el acceso ordinario entre esquemas o SchemaPolicy.NO_CHECK para el acceso en tiempo de ejecución de Deep Data Security. Ambos evitan el DDL de esquema gestionado, incluida la creación, reparación, recreación y la creación del primer índice híbrido; realice esas acciones mientras está conectado como usuario de base de datos propietario sin schema_owner. Ninguno de los modos hace que el almacén sea de solo lectura: las lecturas y escrituras de memoria normales utilizan la autorización efectiva de la base de datos del usuario de conexión. Para el acceso en tiempo de ejecución de Deep Data Security, utilice SchemaPolicy.NO_CHECK y cree el almacén mientras OracleMemoryEndUserSecurityContext está activo. El almacén resultante necesita un contexto de usuario final activo para cada operación de base de datos posterior. Las políticas de esquema que no sean NO_CHECK rechazan los contextos de usuario final activos para que el trabajo del ciclo de vida del esquema no se pueda ejecutar accidentalmente como usuario final.
  • vector_dim int | None: dimensión de incrustación opcional para el almacenamiento de vectores local. Transfiera un entero positivo para crear la columna de embebido gestionada y el índice de vector, y para validar los metadatos de esquema existentes con esa dimensión. Transfiera None u omita el argumento cuando este almacén no necesite almacenamiento de vectores local. La búsqueda híbrida y por palabras clave puede funcionar desde el texto de búsqueda almacenado sin la columna de incrustación local. La búsqueda de vectores requiere almacenamiento de vectores local. Cuando se omite este argumento y el backend de búsqueda efectivo es la búsqueda vectorial, el almacén utiliza embedder.embedding_dimension cuando hay un embebido disponible.

  • table_name_prefix str:

    Prefijo opcional agregado a los nombres de tabla/índice gestionados. Pase esto o memory_store_id, no ambos.

    En desuso

    En desuso desde la versión 26.6.0: este parámetro estaba en desuso en la versión 26.6.0 y se eliminará en la versión 27.1. Utilice memory_store_id en su lugar.

  • memory_store_id str: ID estable para el almacén de memoria de base de datos gestionado. Vuelva a utilizar el mismo ID para volver a abrir la misma tienda gestionada. El ID se une a los nombres de objetos de base de datos gestionados con un guion bajo, por lo que debe empezar por una letra, contener solo letras, números y guiones bajos y tener como máximo 16 caracteres. Pase esto o table_name_prefix, no ambos. Si se omite, el almacén utiliza table_name_prefix o el valor por defecto sin fijar cuando también se omite table_name_prefix. Para crear, reparar o volver a crear un almacén en el esquema del usuario de conexión se necesita un paquete DBMS_AGENT_MEMORY_STORE compatible en ese esquema.
  • schema_owner str: propietario de esquema opcional para un almacén de memoria gestionado existente. Omita esta opción para utilizar el esquema del usuario de conexión. El argumento pool puede ser una conexión de base de datos raw o un pool de conexiones; utilice esta opción cuando pertenezca a un usuario de base de datos de aplicación que tenga permisos en tablas propiedad de otro usuario. Esta opción solo es para el acceso en tiempo de ejecución a un almacén de memoria gestionado ya creado. Utilice SchemaPolicy.REQUIRE_EXISTING para el acceso ordinario entre esquemas o SchemaPolicy.NO_CHECK con un contexto de seguridad de usuario final activo para un almacén protegido por Deep Data Security. Cree, actualice o vuelva a crear el almacén de memoria gestionado mientras está conectado como propietario del esquema y omita esta opción. Transfiera un identificador sin comillas; la entrada en minúscula se normaliza a mayúsculas y los propietarios de esquemas entre comillas sensibles a mayúsculas y minúsculas no están soportados. Otorgue CREATE SESSION y los privilegios de objeto necesarios al usuario de la base de datos de la aplicación; consulte la sección Database Users and Privileges de la guía de solución de problemas para obtener los permisos exactos. Como alternativa, exponga las vistas de objeto gestionado con el mismo nombre en el esquema de tiempo de ejecución y omita schema_owner; solo está soportado para SchemaPolicy.REQUIRE_EXISTING.
  • search_strategy SearchStrategy: valor SearchStrategy que selecciona el backend para search(). Utilice SearchStrategy.VECTOR (valor por defecto) para la recuperación sólo vectorial, SearchStrategy.HYBRID para consultar un índice vectorial híbrido de Oracle gestionado a través del texto de búsqueda almacenado, o SearchStrategy.KEYWORD para clasificar por palabra clave/texto que coincida con el texto de búsqueda almacenado sin fusión vectorial. KEYWORD no necesita un embebido. HYBRID necesita que embedder sea OracleDBEmbedder para que el índice híbrido gestionado utilice el mismo modelo en la base de datos que el embebido del almacén principal. Si un cliente de palabras clave abre un esquema híbrido existente, el almacén puede utilizar la rama de texto de ese índice híbrido. El inicio falla cuando se utiliza una estrategia incompatible con un esquema existente porque puede que ese esquema no contenga el estado de búsqueda almacenado que necesita la estrategia. Cuando se omite schema_policy=SchemaPolicy.REQUIRE_EXISTING y este argumento, el mejor esfuerzo del almacén detecta el modo de búsqueda almacenado del esquema a partir de metadatos gestionados y utiliza ese modo cuando está disponible.
  • search_index_sync SearchIndexSyncMode: valor SearchIndexSyncMode que selecciona el comportamiento de refrescamiento del índice de búsqueda gestionado para SearchStrategy.HYBRID y SearchStrategy.KEYWORD. SearchIndexSyncMode.ON_COMMIT es el valor por defecto y permite la búsqueda de registros tan pronto como se confirma la transacción de escritura. SearchIndexSyncMode.MANUAL deja el refrescamiento en una operación de sincronización explícita del lado de la base de datos. SearchIndexSyncMode.AUTO permite a Oracle refrescar el índice híbrido gestionado de forma asíncrona y solo está soportado con SearchStrategy.HYBRID; la búsqueda por palabra clave rechaza AUTO.
  • memory_retention_config MemoryRetentionConfig: configuración opcional de retención de memoria para mensajes y memorias respaldados por base de datos. MemoryRetentionConfig.default_ttl_days se utiliza cuando una nueva escritura omite ttl_days. MemoryRetentionConfig.max_ttl_days sujeta duraciones explícitas por registro por encima del máximo configurado con una advertencia y, cuando se define, hace que ttl_days=None utilice ese máximo en lugar de crear filas que no caducan. Con SchemaPolicy.CREATE_IF_NECESSARY, una configuración explícita refresca los metadatos almacenados en un esquema gestionado actualizado existente, pero no actualiza las fechas de caducidad existentes; omitiendo la configuración existente. Si una configuración explícita deja default_ttl_days o max_ttl_days en NOT_SET_MARKER, el SDK resuelve ese atributo en su valor por defecto (None) antes de comparar o almacenar metadatos de esquema. Elija esta configuración en función de la información esperada que se almacena en los registros, el motivo por el que la aplicación la retiene y cualquier compromiso de conservación de aplicaciones o normativas.
• Incidencias: RuntimeError: si un contexto de seguridad de usuario final está activo con una política de esquema distinta de SchemaPolicy.NO_CHECK, o si se abre o se utiliza un almacén de tiempo de ejecución NO_CHECK sin un contexto de seguridad de usuario final activo.

Advertencia: SchemaPolicy.CREATE_IF_NECESSARY puede ser más caro que el inicio normal del almacén, ya que puede reparar objetos de esquema gestionados antes de que la inicialización se realice correctamente. Planificar el trabajo de reparación como una operación de mantenimiento cuando un esquema puede contener muchas filas. Un almacén en una versión de esquema anterior necesita una actualización de esquema de paquete antes de la inicialización.

Si la configuración del esquema debe crear el trabajo de depuración de registro caducado gestionado, pero el usuario de la base de datos carece del privilegio Scheduler-job, la inicialización advierte y continúa. Los mensajes y las memorias caducados permanecen ocultos para las lecturas y la búsqueda, pero no se depuran físicamente hasta que un usuario con CREATE JOB o un privilegio de programador equivalente crea el trabajo.

Cuando SchemaPolicy.CREATE_IF_NECESSARY crea por primera vez un índice híbrido gestionado a través de un esquema existente, Oracle explora el texto de búsqueda almacenado y crea el estado de índice híbrido gestionado a partir del modelo de base de datos configurado. La inicialización del almacén espera a que termine ese DDL, por lo que debe planificar la primera actualización híbrida como una operación de migración o mantenimiento para esquemas grandes. SearchIndexSyncMode controla el mantenimiento continuo después de que exista el índice; no hace que la primera creación de índice sea asíncrona.

La creación de ese índice híbrido gestionado también crea una preferencia de vectorizador DBMS_VECTOR_CHAIN denominada por el esquema gestionado. La preferencia almacena metadatos de configuración del vectorizador ligeros del modelo OracleDBEmbedder configurado. Se puede inspeccionar con vistas de preferencias de Oracle Text, como CTX_USER_PREFERENCES y CTX_USER_PREFERENCE_VALUES.

método add

Agregue registros al almacén de Oracle DB.

• Parámetros:
  • contents Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]: secuencia de solo lectura de cargas útiles de registro. Las entradas de mensajes pueden contener piezas solicitadas de MessageContent. Las entradas de resumen de thread pueden ser asignaciones, cadenas que se convierten en objetos {"text": value} o None almacenados como JSON null. Los valores de texto también se utilizan para la búsqueda, a menos que se proporcione index_texts. Para otros tipos de registro, None puede volver a metadata["content"]. Las cadenas vacías explícitas se conservan.
  • record_type str: tipo de registro lógico que se debe crear, como "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" o "thread_summary".
  • index_texts list[str | list[str] | None]: cargas útiles alternativas opcionales utilizadas como texto de búsqueda. Utilice esta opción para controlar qué palabras clave respaldadas por base de datos o índices de búsqueda híbridos. Cada entrada de la lista externa se alinea con un registro. La tienda puede fragmentar una entrada de cadena. Una entrada de lista se trata como fragmentos propiedad del emisor de llamada y se escribe como está en RECORD_CHUNKS.chunk_text. Cuando también se proporciona embeddings, las entradas de lista requieren exactamente un vector por fragmento; las entradas de cadena solo aceptan un único vector para ese registro.

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

    Vectores de incrustación precalculados opcionales alineados con contents. Cada entrada de registro puede ser un vector o una lista de vectores de fragmentos. Cuando se configura el almacenamiento vectorial local, estos vectores se almacenan directamente como representación vectorial del registro en lugar de llamar al incrustador de la tienda para crear vectores locales para la escritura. Un solo vector representa todo el texto semántico, incluso cuando el fragmentador configurado lo dividiría. Varios vectores de fragmentos necesitan que coincidan con las listas de fragmentos index_texts.

    En SearchStrategy.VECTOR, la búsqueda vectorial se clasifica en función de los vectores almacenados. En SearchStrategy.HYBRID o SearchStrategy.KEYWORD, la búsqueda respaldada por base de datos clasifica en el texto de búsqueda almacenado y el estado de índice híbrido o texto gestionado por Oracle, por lo que las incrustaciones de tiempo de adición solo afectan a cualquier almacenamiento vectorial local configurado, no a esa estrategia de búsqueda activa. Si este almacén se ha configurado sin almacenamiento de vectores local, proporcione index_texts en lugar de embeddings para sustituir el texto visible para esos índices conscientes del texto.

  • record_ids str | None | list[str | None]: identificadores visibles para el emisor de llamada opcionales. Se puede utilizar una sola cadena para inserciones de un solo registro, mientras que las listas deben estar alineadas con contents. Los identificadores generados se devuelven cuando se omite este campo.
  • thread_ids str | None | list[str | None]: identificadores de subprocesos opcionales asociados con los registros insertados. Los valores escalares se pueden difundir entre entradas alineadas.
  • user_ids str | None | list[str | None]: identificadores de usuario opcionales asociados con los registros insertados. Los valores escalares se pueden difundir entre entradas alineadas. Cuando se omite en un almacén de tiempo de ejecución SchemaPolicy.NO_CHECK, el almacén utiliza el nombre de usuario del contexto de seguridad de usuario final activo. Transfiera None explícitamente para conservar un ID de usuario sin ámbito.
  • agent_ids str | None | list[str | None]: identificadores de agente opcionales asociados con los registros insertados. Los valores escalares se pueden difundir entre entradas alineadas.
  • roles str | None | list[str | None]: roles de mensajes opcionales, como "user" o "assistant". Se utiliza solo cuando record_type es "message".
  • timestamps str | None | list[str | None]: registros de hora opcionales para guardar con los registros. Cada registro de hora representa el momento en que se creó el registro. Los valores escalares se pueden difundir entre entradas alineadas. Las entradas omitidas o None dejan el registro de hora del evento sin definir. Cuando ttl_anchor es TimeToLiveAnchor.TIMESTAMP, todos los registros afectados deben tener un valor de registro de hora ISO-8601 concreto. Los registros de hora ISO-8601 sin zona horaria se tratan como UTC.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: diccionarios de metadatos opcionales. Los metadatos pueden incluir "content" como origen de reserva cuando se omite un valor de texto en lugar de definirlo en "". Las escrituras de imagen requieren "image_mime_type" con "image/png", "image/jpeg" o "image/webp". El almacén utiliza este campo para guardar la imagen, pero no la devuelve como parte de los metadatos del registro.
  • ttl_days int | None | list[int | None]: duración opcional del tiempo de vida en días para registros similares a los de la memoria y los mensajes. Omita este argumento para utilizar MemoryRetentionConfig.default_ttl_days desde el esquema gestionado. Transfiera None para utilizar MemoryRetentionConfig.max_ttl_days cuando la configuración de retención defina uno o para crear un registro que no caduque cuando no lo haga. Los valores por encima de MemoryRetentionConfig.max_ttl_days se sujetan a ese máximo con una advertencia. Los valores escalares se pueden difundir entre entradas alineadas.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]: anclaje de tiempo de vida opcional. Utilice TimeToLiveAnchor.CREATED_AT para que caduque en relación con el tiempo de creación de la base de datos o TimeToLiveAnchor.TIMESTAMP para que caduque en relación con el registro de hora del evento proporcionado. Cuando se omite, la caducidad utiliza TimeToLiveAnchor.CREATED_AT. La caducidad anclada en el registro de hora requiere un registro de hora ISO-8601 concreto para cada registro insertado. Los registros de hora ISO-8601 sin zona horaria se tratan como UTC.
  • statuses RecordStatus | list[RecordStatus]: estado opcional del ciclo de vida de los registros que lo admiten. Proporcione un valor RecordStatus para aplicarlo a cada registro de entrada o una lista de estados alineados con contents. Omita este argumento para utilizar RecordStatus.VALID.
  • **store_kwargs (Cualquiera): opciones de escritura de base de datos. batch_size controla el tamaño de lote de ejecución y el valor por defecto es 256.
• Devoluciones: identificadores para los registros insertados, en el mismo orden lógico que la entrada.
• Tipo de devolución: list[str]

Ejemplos

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étodo add_agent

Agregue un registro de perfil de agente.

• Parámetros:
  • agent_id str: identificador de agente.
  • information str: información de formato libre sobre el agente. Este texto se almacena como contenido del perfil y se utiliza para crear la representación que permite la búsqueda del perfil.
  • metadata dict[str, Any] | None: asignación de metadatos opcional almacenada en la fila del perfil de agente.
• Devoluciones: identificador del registro de perfil de agente insertado.
• Tipo de devolución: str

Notas

Los registros de perfil de agente no tienen ámbito. El identificador de registro público insertado es el mismo valor transferido que agent_id.

Ejemplos

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

method add_agent_async (async)

Agregue un registro de perfil de agente de forma asíncrona.

• Parámetros:
  • agent_id str: identificador estable para el perfil de agente.
  • information str: texto de formato libre que describe el agente.
  • metadata dict[str, Any] | None: asignación de metadatos opcional almacenada en la fila del perfil de agente.
• Devoluciones: identificador del registro de perfil de agente creado.
• Tipo de devolución: str

method add_async (async)

Agregar de forma asíncrona registros orientados a filas al almacén.

Acepta los mismos argumentos y devuelve los mismos identificadores que add().

• Parámetros:
  • contenido Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
  • tipo_registro str
  • index_texts list[str | list[str] | None]
  • embeddings 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]
  • roles str | None | list[str | None]
  • timestamps str | None | list[str | None]
  • metadatos dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • statuses RecordStatus | list[RecordStatus]
  • store_kwargs Any
• Tipo de devolución: list[str]

método add_batches

Agregue lotes lógicos preparados por el emisor de llamada al almacén.

• Parámetros:
  • lotes list[PendingRecordBatch]: lotes lógicos completamente preparados para que persistan. Cada lote debe incluir sus propios campos por registro, como record_type, valores de ámbito, roles, registros de hora y metadatos.
  • **store_kwargs (Cualquiera): opciones de escritura específicas de implantación reenviadas al almacén concreto.
• Devoluciones: identificadores de los registros insertados, en el mismo orden lógico que los lotes y las filas de entrada.
• Tipo de devolución: List[str]

Ejemplos

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

method add_batches_async (async)

Agregue lotes lógicos preparados por el emisor de llamada de forma asíncrona al almacén.

Acepta los mismos argumentos y devuelve los mismos identificadores que add_batches().

• Parámetros:
  • lotes list[PendingRecordBatch]
  • store_kwargs Any
• Tipo de devolución: list[str]

método add_relations

Almacene una o más relaciones de memoria a memoria atómicamente.

Los valores escalares se difunden en el lote de ID de origen; las listas deben estar alineadas. Solo se puede almacenar una orientación de relación para un par de puntos finales. Las etiquetas de enlace de memoria incorporadas reciben su etiqueta inversa fija y las etiquetas de ciclo de vida actualizan el estado del punto final en la misma transacción.

• Parámetros:
  • source_record_ids str | list[str]: identificadores de memoria de origen, como una lista escalar o alineada.
  • source_record_types str | list[str]: tipos similares a la memoria para los registros de origen.
  • target_record_ids str | list[str]: identificadores de memoria de destino, como una lista escalar o alineada.
  • target_record_types str | list[str]: tipos similares a memoria para los registros de destino.
  • relation_types str | list[str]: etiquetas de relación dirigidas.
  • opposite_relation_types str | list[str]: etiquetas inversas opcionales para tipos de relación personalizados. Esto describe la vista inversa de la relación almacenada; no crea una segunda relación en la dirección inversa.
  • relation_ids str | None | list[str | None]: identificadores de relación estables opcionales. Omitir para generar identificadores.
  • timestamps str | None | list[str | None]: registros de hora opcionales almacenados con las relaciones.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: metadatos opcionales almacenados con las relaciones.
• Devoluciones: se han creado identificadores de relación en orden de entrada.
• Tipo de devolución: list[str]

Ejemplos

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

method add_relations_async (async)

Almacene de forma asíncrona una o más relaciones dirigidas.

Los valores escalares se transmiten a través del lote de registro de origen. Los valores de lista deben tener la misma longitud. Solo se puede almacenar una orientación para un par de puntos finales. Utilice opposite_relation_types para describir la vista inversa en lugar de agregar una segunda relación inversa.

• Parámetros:
  • source_record_ids str | list[str]: identificador o identificadores de registros en el extremo de origen de cada relación dirigida.
  • source_record_types str | list[str]: tipo o tipos de registro para source_record_ids. Proporcione un valor para todos los orígenes o un valor para cada relación.
  • target_record_ids str | list[str]: identificador o identificadores de registros en el extremo de destino de cada relación dirigida.
  • target_record_types str | list[str]: tipo o tipos de registro para target_record_ids. Proporcione un valor para todos los destinos o un valor para cada relación.
  • relation_types str | list[str]: etiqueta o etiquetas de relación dirigida. Proporcione un valor para todas las relaciones o un valor para cada relación.
  • opposite_relation_types str | list[str]: etiqueta o etiquetas opcionales para la vista inversa de cada relación. Para los tipos de relación de memoria incorporados, la omisión utiliza la etiqueta inversa predefinida. Para los tipos de relación personalizados, la omisión utiliza la misma etiqueta en ambas direcciones.
  • relation_ids str | None | list[str | None]: identificador o identificadores estables opcionales. Omita esta opción para permitir que la tienda genere identificadores.
  • timestamps str | None | list[str | None]: registro de hora o registros de hora opcionales para almacenar en las relaciones.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: objeto u objetos de metadatos opcionales para almacenar en las relaciones.
• Devoluciones: identificadores de relación en orden de entrada.
• Tipo de devolución: list[str]

Ejemplos

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

método add_user

Agregue un registro de perfil de usuario.

• Parámetros:
  • user_id str: identificador de usuario. Cuando se omite en un almacén de tiempo de ejecución SchemaPolicy.NO_CHECK, el almacén utiliza el nombre de usuario del contexto de seguridad de usuario final activo. De lo contrario, proporcione este argumento explícitamente.
  • information str: información de formato libre necesaria sobre el usuario. Este texto se almacena como contenido del perfil y se utiliza para crear la representación que permite la búsqueda del perfil.
  • metadata dict[str, Any] | None: asignación de metadatos opcional almacenada en la fila del perfil de usuario.
• Devoluciones: identificador del registro de perfil de usuario insertado.
• Tipo de devolución: str

Notas

Los registros de perfil de usuario no tienen ámbito. El identificador de registro público insertado es el user_id explícito o inferido.

Ejemplos

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

method add_user_async (async)

Agregue un registro de perfil de usuario de forma asíncrona.

• Parámetros:
  • user_id str: identificador estable para el perfil de usuario.
  • information str: texto de formato libre que describe al usuario.
  • metadata dict[str, Any] | None: asignación de metadatos opcional almacenada en la fila del perfil de usuario.
• Devoluciones: identificador del registro de perfil de usuario creado.
• Tipo de devolución: str

método delete

Suprima una fila gestionada y sus filas de fragmentos por identificador.

• Parámetros:
  • record_type str: etiqueta de tipo de registro para eliminar. Los tipos soportados son "thread", "message", "memory", "guideline", "fact", "preference", "user_profile" y "agent_profile", y "thread_summary".
  • record_id str: identificador para suprimir.
  • cascade bool: cuando es True, amplíe los destinos de nivel superior soportados, como los perfiles de actor, a sus filas secundarias de ámbito dentro de la misma transacción. Para un destino de perfil de usuario o de perfil de agente, primero se suprimen las filas de thread en propiedad, lo que elimina su mensaje de ámbito de thread y las filas de la tabla de memoria y, a continuación, se suprimen los mensajes de ámbito de actor y las filas similares a la memoria restantes directamente (memory, guideline, fact, preference). Esta limpieza de ámbito se sigue ejecutando cuando la fila de perfil coincidente ya está ausente.
• Devoluciones: número de destinos de nivel superior solicitados eliminados, normalmente 0 o 1. Las filas secundarias en cascada no se cuentan por separado, por lo que puede seguir siendo 0 cuando falta un perfil de actor que dispara la limpieza en el ámbito.
• Tipo de devolución: int

Notas

La operación se ejecuta dentro de una transacción. Cuando cascade está activado para un destino de nivel superior soportado, la supresión de perfil y todas las supresiones secundarias de ámbito se confirman o se realiza un rollback juntos.

Ejemplos

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)

Elimine de forma asíncrona un registro almacenado por identificador.

• Parámetros:
  • record_type str: tipo lógico del registro que se debe eliminar.
  • record_id str: identificador del registro que se debe eliminar.
  • cascade bool: cuando es True, aplique cualquier comportamiento de supresión en cascada admitido por el almacén para los destinos de nivel superior solicitados dentro de la misma operación de supresión. Esto se utiliza principalmente para destinos como los perfiles de actor que poseen registros de ámbito adicionales. Por ejemplo, una cascada de perfil de usuario o perfil de agente puede suprimir los propios threads, los mensajes de ámbito de thread y los registros similares a la memoria eliminados con esos threads, así como cualquier registro de ámbito de actor directo restante, como mensajes, memorias, directrices, hechos o preferencias. Para las supresiones de perfil de actor, esta limpieza de ámbito puede seguir ejecutándose cuando la fila de perfil coincidente ya está ausente.
• Devoluciones: número de registros de nivel superior solicitados suprimidos, normalmente 0 o 1. Las filas secundarias en cascada no se cuentan por separado, por lo que puede seguir siendo 0 cuando falta un perfil de actor que dispara la limpieza en el ámbito.
• Tipo de devolución: int

método delete_relations

Suprimir relaciones por identificador y volver a calcular el estado del ciclo de vida.

• Parámetros: relation_ids str | list[str]: identificador o identificadores de las relaciones que se van a suprimir.
• Devoluciones: número de relaciones suprimidas.
• Tipo de devolución: int

Ejemplos

store.delete_relations("relation-id")
1

method delete_relations_async (async)

Suprimir relaciones de forma asíncrona por identificador.

El estado del ciclo de vida se vuelve a calcular a partir de las relaciones que quedan.

• Parámetros: relation_ids str | list[str]: identificador o identificadores de las relaciones que se van a suprimir.
• Devoluciones: número de relaciones suprimidas.
• Tipo de devolución: int

Ejemplos

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

método delete_thread

Suprimir un thread y sus filas almacenadas asociadas.

• Parámetros: thread_id str: identificador de thread cuyas filas se deben eliminar, incluida la fila de thread, las filas secundarias dependientes y la limpieza explícita de la fila de fragmento.
• Devoluciones: número de filas de thread suprimidas (0 o 1).
• Tipo de devolución: int

Notas

Utilice esta operación cuando necesite una limpieza en cascada con ámbito de thread. En el almacén con copia de seguridad de base de datos, al suprimir el thread, se elimina la fila del thread gestionado junto con las filas de memoria y mensajes asociadas, además de los datos de búsqueda mantenidos para su recuperación. Esto es más amplio que una supresión de nivel de mensaje, que elimina sólo la fila de mensaje sin formato. La supresión de threads elimina las filas de memoria y mensajes dependientes junto con sus datos de recuperación asociados en la misma transacción.

Ejemplos

store.delete_thread("c1")
0

method delete_thread_async (async)

Suprima de forma asíncrona un thread y sus datos almacenados asociados.

• Parámetros: thread_id str: identificador del subproceso que se va a eliminar.
• Devoluciones: número de registros de thread suprimidos, normalmente 0 o 1.
• Tipo de devolución: int

Notas

Ésta es la operación de nivel de almacén para eliminar un thread y los registros de ámbito de thread gestionados por el almacén. Prefiere la supresión de threads cuando los requisitos de retención llaman para suprimir tanto los mensajes de origen como los datos de memoria de ámbito de thread derivados, ya que las supresiones de nivel de mensaje no implican que se eliminen registros derivados persistentes por separado.

método get

Recuperar un registro almacenado por identificador.

• Parámetros:
  • record_type str: etiqueta de tipo de registro que se resuelve en una fila gestionada, como "message", "memory", "guideline", "fact", "preference", "thread", "user_profile" o "agent_profile", o "thread_summary".
  • record_id str: identificador que se debe buscar.
  • include_bytes bool: indica si se deben cargar bytes de imágenes para registros de imágenes o imágenes anexadas para registros de mensajes. El valor por defecto es False.
• Devoluciones: registro rellenado con metadatos descodificados cuando se encuentra, de lo contrario, None.
• Tipo de devolución: Registro | Ninguno

Ejemplos

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)

Recupere de forma asíncrona un registro almacenado por tipo e identificador.

• Parámetros:
  • record_type str: tipo lógico del registro que se va a recuperar, como "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" o "image".
  • record_id str: identificador del registro que se recuperará.
  • include_bytes bool: indica si se deben cargar los bytes de imagen almacenados. Para un registro de mensaje, controla si las imágenes adjuntas incluyen sus bytes. Para un registro de imagen, controla si se cargan los bytes de imagen independientes. Esta opción no afecta a otros tipos de registro.
• Devoluciones: el registro almacenado cuando se encuentra; de lo contrario, None. Una consulta "thread" devuelve un valor ThreadRecord con metadatos de thread, configuración de tiempo de ejecución, estado de tiempo de ejecución y el registro de hora de creación rellenado cuando el almacén soporta threads persistentes.
• Tipo de devolución: Registro | Ninguno

método get_relation

Devolver una relación identificada por ID o tupla de punto final completa.

Proporcione relation_id solo o proporcione una tupla completa de punto final de origen a destino.

• Parámetros:
  • source_record_id str: identificador de registro de origen. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • source_record_type str: tipo de registro de origen. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • target_record_id str: identificador de registro de destino. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • target_record_type str: tipo de registro de destino. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • relation_type str: etiqueta de relación dirigida. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • relation_id str: identificador de relación que debe coincidir directamente. Proporcione este argumento solo en lugar de combinarlo con campos de tupla de punto final.
• Devoluciones: relación almacenada coincidente o None cuando no existe.
• Tipo de devolución: RecordRelation | Ninguno

Ejemplos

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

method get_relation_async (async)

Recupere de forma asíncrona una relación por ID o tupla de punto final.

Proporcione relation_id solo o proporcione una tupla completa de punto final de origen a destino.

• Parámetros:
  • source_record_id str: identificador de registro de origen. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • source_record_type str: tipo de registro de origen. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • target_record_id str: identificador de registro de destino. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • target_record_type str: tipo de registro de destino. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • relation_type str: etiqueta de relación dirigida. Se necesita con los otros campos de tupla de punto final cuando se omite relation_id.
  • relation_id str: identificador de relación que debe coincidir directamente. Proporcione este argumento solo en lugar de combinarlo con campos de tupla de punto final.
• Devoluciones: relación coincidente o None cuando no existe.
• Tipo de devolución: RecordRelation | Ninguno

Ejemplos

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

method list

Enumerar registros persistentes para un tipo de registro.

• Parámetros:
  • record_type str: etiqueta de tipo de registro (por ejemplo, "thread", "message", "memory", "guideline", "fact", "preference", "thread", "user_profile" o "agent_profile").
  • limit int | None: número máximo opcional de registros que se deben devolver. Cuando se omite, el almacén utiliza su límite de lista por defecto. Transfiera None para desactivar ese límite y devolver todos los registros coincidentes.
  • thread_id str | None: filtro de ámbito de thread exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven las filas cuyo valor thread_id es SQL NULL. Los tipos de registro sin ámbito ignoran este filtro. Cuando record_type es "thread", no se debe definir thread_id; utilice record_id para seleccionar un thread específico.
  • user_id str | None: filtro de ámbito de usuario exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven las filas cuyo valor user_id es SQL NULL. Los tipos de registro sin ámbito ignoran este filtro.
  • agent_id str | None: filtro de ámbito de agente exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven las filas cuyo valor agent_id es SQL NULL. Los tipos de registro sin ámbito ignoran este filtro.

  • metadata_filter dict[str, Any] | None:

    Filtro de metadatos. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros sin metadatos almacenados. Cuando se define en un dict, las entradas en metadata_filter se combinan con la semántica AND. Las entradas cuyo valor no es un diccionario de operador de nivel de campo utilizan semántica de coincidencia exacta: la clave solicitada debe existir en los metadatos almacenados. Los diccionarios anidados se comparan de forma recursiva. Los valores escalares y de lista coinciden con la igualdad exacta; el orden de lista y la longitud también deben coincidir. Para probar la pertenencia a una matriz, utilice un diccionario de operador de nivel de campo, como {"tags": {"$array_contains": "prod"}}. Un operando de lista para "$array_contains" significa que todos los valores mostrados deben estar presentes; "$array_contains_any" significa que al menos un valor mostrado debe estar presente. Utilice "$not" para negar otra expresión de nivel de campo en el mismo campo, incluido un diccionario de operador o un valor de coincidencia exacta raw. Las expresiones negativas coinciden cuando falla la expresión positiva, incluidos los campos que faltan; la pertenencia a la matriz negada también coincide con los campos que no son de matriz. Entre los ejemplos se incluyen metadata_filter={"source": "slack"} para un campo escalar, metadata_filter={"review": {"status": "open"}} para un campo anidado y metadata_filter={"tags": ["prod", "urgent"]} para una coincidencia de lista exacta. Combinar condiciones para requerir todas ellas:

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

  • include_bytes bool: indica si los registros de imágenes o las imágenes adjuntas a los registros de mensajes incluyen sus bytes almacenados. El valor por defecto es False. Las listas de imágenes directas necesitan un filtro record_id y al menos un filtro de ámbito de usuario, agente o thread exacto cuando se trata de True.
  • record_id str: filtro de identificador de registro exacto. Cuando se omite, se devuelven los registros con cualquier identificador. Los filtros de ámbito y metadatos siguen siendo restricciones adicionales.
• Devoluciones: registros ordenados por orden de inserción.
• Tipo de devolución: list[Registro]

Notas

"user_profile" y "agent_profile" son tipos de registro sin ámbito. Para esos tipos de registro, thread_id, user_id y agent_id se ignoran y la identidad del actor permanece en record.id. Los registros "thread" exponen el identificador de thread como record.id y record.thread_id.

Ejemplos

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)

Mostrar de forma asíncrona los registros almacenados para un tipo de registro.

• Parámetros:
  • record_type str: tipo de registro lógico que se debe enumerar, como "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" o "image".
  • limit int | None: número máximo opcional de registros más recientes que se deben devolver. Cuando se omite, las implementaciones pueden aplicar un límite superior seguro, como MAX_LIST_LIMIT. Transfiera None para desactivar ese límite y devolver todos los registros coincidentes.
  • thread_id str | None: filtro de ámbito de thread exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyo valor thread_id es None. Los tipos de registro sin ámbito ignoran este filtro. Cuando record_type es "thread", no se debe definir thread_id; utilice record_id para seleccionar un thread específico.
  • user_id str | None: filtro de ámbito de usuario exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyo valor user_id es None. Los tipos de registro sin ámbito ignoran este filtro.
  • agent_id str | None: filtro de ámbito de agente exacto. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyo valor agent_id es None. Los tipos de registro sin ámbito ignoran este filtro.

  • metadata_filter dict[str, Any] | None:

    Filtro de metadatos. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven los registros cuyos metadatos son None. Cuando se define en un dict, las entradas en metadata_filter se combinan con la semántica AND. Las entradas cuyo valor no es un diccionario de operador de nivel de campo utilizan semántica de coincidencia exacta: la clave solicitada debe existir en los metadatos almacenados. Los diccionarios anidados se comparan de forma recursiva. Los valores escalares y de lista coinciden con la igualdad exacta; el orden de lista y la longitud también deben coincidir. Para probar la pertenencia a una matriz, utilice un diccionario de operador de nivel de campo, como {"tags": {"$array_contains": "prod"}}. Un operando de lista para "$array_contains" significa que todos los valores mostrados deben estar presentes; "$array_contains_any" significa que al menos un valor mostrado debe estar presente. Utilice "$not" para negar otra expresión de nivel de campo en el mismo campo, incluido un diccionario de operador o un valor de coincidencia exacta raw. Las expresiones negativas coinciden cuando falla la expresión positiva, incluidos los campos que faltan; la pertenencia a la matriz negada también coincide con los campos que no son de matriz. Entre los ejemplos se incluyen metadata_filter={"source": "slack"} para un campo escalar, metadata_filter={"review": {"status": "open"}} para un campo anidado y metadata_filter={"tags": ["prod", "urgent"]} para una coincidencia de lista exacta. Combinar condiciones para requerir todas ellas:

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

  • include_bytes bool – Whether image records or images attached to message records include their stored bytes. When omitted or False, image descriptions and metadata are returned without loading bytes. For direct image listings, set this to True only with an exact record_id and at least one exact user, agent, or thread scope filter. This option has no effect on other record types.
  • record_id str: filtro de identificador de registro exacto. Cuando se omite, se devuelven los registros con cualquier identificador. Los filtros de ámbito y metadatos siguen siendo restricciones adicionales.
• Devoluciones: registros ordenados de más antiguos a más recientes en la ventana devuelta.
• Tipo de devolución: List[Registro]

método list_relations

Enumere las relaciones en su orientación de origen a destino.

• Parámetros:
  • relation_type str: etiqueta de relación dirigida opcional para que coincida, como "supports" o "supersedes". Omita incluir todos los tipos de relación.
  • source_record_id str: identificador de registro de origen opcional que debe coincidir.
  • source_record_type str: tipo de registro de origen opcional que debe coincidir.
  • target_record_id str: identificador de registro de destino opcional que coincide.
  • target_record_type str: tipo de registro de destino opcional que coincide.
  • limit int | None: número máximo opcional de relaciones creadas más recientemente que se deben devolver. Cuando se omite, el almacén utiliza MAX_LIST_LIMIT. Transfiera None para devolver todas las relaciones almacenadas coincidentes.
  • metadata_filter dict[str, Any] | None: filtro de metadatos. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven las relaciones cuyos metadatos son None. Cuando se define en un dict, las entradas se combinan con la semántica AND. Los diccionarios anidados utilizan la coincidencia exacta recursiva. Los valores escalares y de lista requieren igualdad exacta; utilice {"tags": {"$array_contains": "prod"}} para hacer coincidir la pertenencia a la matriz, "$array_contains_any" para hacer coincidir cualquier valor mostrado o "$not" para negar otra expresión de campo.
  • relation_id str: filtro de identificador de relación exacto. Cuando se omite, se devuelven las relaciones con cualquier identificador. Otros filtros siguen siendo restricciones adicionales.
• Devoluciones: relaciones ordenadas por hora de creación e identificador.
• Tipo de devolución: list[RecordRelation]

Ejemplos

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

method list_relations_async (async)

Mostrar de forma asíncrona las relaciones en la orientación de origen a destino.

• Parámetros:
  • relation_type str: etiqueta de relación dirigida opcional para que coincida, como "supports" o "supersedes". Omita incluir todos los tipos de relación.
  • source_record_id str: identificador de registro de origen opcional que debe coincidir.
  • source_record_type str: tipo de registro de origen opcional que debe coincidir.
  • target_record_id str: identificador de registro de destino opcional que coincide.
  • target_record_type str: tipo de registro de destino opcional que coincide.
  • limit int | None: número máximo opcional de relaciones creadas más recientemente que se deben devolver. Cuando se omite, las implementaciones pueden aplicar un límite superior seguro, como MAX_LIST_LIMIT. Transfiera None para devolver todas las relaciones almacenadas coincidentes.
  • metadata_filter dict[str, Any] | None: filtro de metadatos. Cuando se omite, no se aplica ningún filtro. Cuando se define en None, solo se devuelven las relaciones cuyos metadatos son None. Cuando se define en un dict, las entradas se combinan con la semántica AND. Los diccionarios anidados utilizan la coincidencia exacta recursiva. Los valores escalares y de lista requieren igualdad exacta; utilice {"tags": {"$array_contains": "prod"}} para hacer coincidir la pertenencia a la matriz, "$array_contains_any" para hacer coincidir cualquier valor mostrado o "$not" para negar otra expresión de campo.
  • relation_id str: identificador de relación opcional para que coincida directamente.
• Devoluciones: relaciones ordenadas por hora de creación e identificador.
• Tipo de devolución: list[RecordRelation]

Ejemplos

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

método list_thread_messages

Devolver mensajes persistentes para un hilo.

• Parámetros:
  • thread_id str: identificador de thread cuyos mensajes se deben devolver.
  • last_n int | None: número opcional de mensajes más recientes que se deben devolver.
  • range_start_seq_no int | None: límite de secuencia inferior inclusivo opcional.
  • range_end_seq_no int | None: límite de secuencia superior exclusivo opcional.
  • include_bytes bool: indica si las partes de la imagen anexadas a los mensajes devueltos incluyen sus bytes almacenados. El valor por defecto es False.
• Devoluciones: registros de mensajes ordenados por orden de inserción.
• Tipo de devolución: list[MessageRecord]

Ejemplos

store.list_thread_messages("c1")
[]

method list_thread_messages_async (async)

Mostrar de forma asíncrona el historial de mensajes almacenado para un thread.

• Parámetros:
  • thread_id str: identificador del thread cuyos mensajes se deben devolver.
  • last_n int | None: número opcional de mensajes más recientes que se deben incluir. Cuando se omite, se devuelven todos los mensajes almacenados para el thread. Cuando se combina con un rango de secuencias, el límite se aplica dentro de ese rango.
  • range_start_seq_no int | None: límite de secuencia inferior inclusivo opcional. Solo se devuelven los mensajes cuyo valor seq_no sea al menos este valor.
  • range_end_seq_no int | None: límite de secuencia superior exclusivo opcional. Solo se devuelven los mensajes cuyo valor seq_no es menor que este valor.
  • include_bytes bool: indica si las partes de la imagen anexadas a los mensajes devueltos incluyen sus bytes almacenados. Cuando se omite o False, se devuelven descripciones de imágenes y metadatos sin cargar bytes.
• Devoluciones: registros de mensajes ordenados de más antiguo a más reciente dentro de la ventana devuelta.
• Tipo de devolución: List[MessageRecord]

método search

Buscar registros por similitud.

El backend de búsqueda activo depende del SearchStrategy configurado en el almacén. SearchStrategy.VECTOR clasifica el vector de consulta en vectores de registro almacenados. SearchStrategy.HYBRID consulta el índice híbrido gestionado de Oracle a través del texto de búsqueda almacenado y su estado de índice gestionado. SearchStrategy.KEYWORD solo se clasifica por texto que coincida con el texto de búsqueda almacenado.

• Parámetros:
  • query str | None: texto opcional en lenguaje natural que se utiliza para buscar registros coincidentes o similares. Proporcione al menos un carácter no de espacio en blanco cuando se omite query_vector. La búsqueda vectorial incrusta este texto; la búsqueda por palabras clave lo compara con el texto de búsqueda almacenado; la búsqueda híbrida lo utiliza tanto para la recuperación de texto como de vector. Cuando el texto supera el tamaño de fragmento configurado, el almacén busca cada fragmento de consulta por separado y fusiona los resultados clasificados con la fusión de clasificación recíproca.
  • query_vector list[float] | None: incrustación opcional de consultas calculadas previamente. Se debe proporcionar exactamente uno de query y query_vector. En la búsqueda vectorial, esto se compara con los vectores de registro almacenados. En la búsqueda híbrida, se envía al índice híbrido gestionado de Oracle como entrada de vector del lado de consulta y no hace que el almacén de base de datos se compare con vectores almacenados de tiempo adicional o de tiempo de actualización directamente. La búsqueda por palabra clave no acepta query_vector. El vector debe ser no vacío, unidimensional y contener solo valores numéricos finitos. En la búsqueda híbrida, su dimensión debe coincidir con el modelo OracleDBEmbedder configurado.
  • k int: cantidad máxima de resultados que se devolverán. Los valores explícitos deben ser al menos 1. Este es un límite superior: la llamada puede devolver menos de k resultados cuando los filtros son demasiado restrictivos, cuando existen menos registros coincidentes no vencidos o debido al comportamiento de búsqueda específico de la implementación.
  • thread_id str | None: identificador de ámbito de thread opcional. exact_thread_match=False deja la dimensión de thread sin restricciones. exact_thread_match=True coincide exactamente con el thread_id proporcionado. Si thread_id=None, solo coincide con los registros sin ámbito en la dimensión de thread.
  • user_id str | None: identificadores opcionales de ámbito de agente y usuario. El indicador exact_*_match=False correspondiente deja esa dimensión sin restricciones. exact_*_match=True coincide exactamente con el ID proporcionado. Si el ID es None, solo coincide con los registros sin ámbito en esa dimensión.
  • agent_id str | None: identificadores de ámbito de agente y usuario opcionales. El indicador exact_*_match=False correspondiente deja esa dimensión sin restricciones. exact_*_match=True coincide exactamente con el ID proporcionado. Si el ID es None, solo coincide con los registros sin ámbito en esa dimensión.
  • exact_user_match bool: indica si cada identificador de ámbito debe coincidir exactamente. False deja esa dimensión sin restricciones. True coincide exactamente con el valor proporcionado. Si ese valor es None, solo coincide con los registros sin ámbito de esa dimensión.
  • exact_agent_match bool: indica si cada identificador de ámbito debe coincidir exactamente. False deja esa dimensión sin restricciones. True coincide exactamente con el valor proporcionado. Si ese valor es None, solo coincide con los registros sin ámbito de esa dimensión.
  • exact_thread_match bool: indica si cada identificador de ámbito debe coincidir exactamente. False deja esa dimensión sin restricciones. True coincide exactamente con el valor proporcionado. Si ese valor es None, solo coincide con los registros sin ámbito de esa dimensión.
  • record_types set[str] | None: conjunto opcional de tipos de registro que se pueden buscar para incluir. Cuando se omite, la búsqueda de base de datos abarca mensajes, documentos como imágenes, filas de la tabla de memoria y perfiles de actor. Los registros de imágenes aportan su descripción, los perfiles de actor contribuyen con su carga útil information y las filas de mensaje y memoria contribuyen con su carga útil content. Durante la búsqueda, los tipos de registro de perfil utilizan su identificador de actor para la dimensión de ámbito aplicable mientras que las dimensiones de ámbito restantes se comportan como None.
  • metadata_filter dict[str, Any] | None: asignación de filtros de metadatos opcional. Las entradas en metadata_filter se combinan con la semántica AND. Las entradas cuyo valor no es un diccionario de operador de nivel de campo utilizan semántica de coincidencia exacta: la clave solicitada debe existir en los metadatos almacenados. Los diccionarios anidados se comparan de forma recursiva. Los valores escalares y de lista coinciden con la igualdad exacta; el orden de lista y la longitud también deben coincidir. Para probar la pertenencia a una matriz, utilice un diccionario de operador de nivel de campo, como {"tags": {"$array_contains": "prod"}}. Un operando de lista para "$array_contains" significa que todos los valores mostrados deben estar presentes; "$array_contains_any" significa que al menos un valor mostrado debe estar presente. Utilice "$not" para negar otra expresión de nivel de campo en el mismo campo, incluido un diccionario de operador o un valor de coincidencia exacta raw. Las expresiones negativas coinciden cuando falla la expresión positiva, incluidos los campos que faltan; la pertenencia a la matriz negada también coincide con los campos que no son de matriz.
  • include_invalid_results bool: indica si los resultados incluyen registros similares a la memoria en el estado no válido. El valor por defecto es True. Transfiera False para excluirlos.
  • num_hops int: número de bordes de enlace de memoria que se deben seguir de cada resultado de memoria directa. Se admiten los valores de 0 a 5; 0 desactiva la expansión de gráficos. La expansión sigue los enlaces en ambas direcciones. Los registros enlazados siguen obedeciendo los filtros de ámbito, metadatos, tipo de registro y caducidad solicitados. Los resultados de mensaje directo, documento y perfil permanecen en el conjunto de resultados, pero no se expanden en gráficos.
  • max_linked_results int: máximo de memorias enlazadas en todos los saltos asociados a cada resultado directo. 0 mantiene los resultados directos sin contexto enlazado. El valor por defecto es 100.
• Devoluciones: pares (record, distance) ordenados por distancia creciente. La lista puede contener menos de k entradas. Para una consulta fragmentada, la distancia se deriva de la puntuación recíproco-ranco-fusión.
• Tipo de devolución: list[tuple[Registro, float]]
• Incrementos:
  • ValueError: si k es menor que 1, si se proporcionan ambos o ninguno de los valores query y query_vector, si query está en blanco, si el modo vectorial no puede resolver una incrustación de consulta, si query_vector no es válido o si metadata_filter no es válido.
  • TimeoutError: si la expansión del gráfico tarda más del tiempo máximo permitido.

Ejemplos

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'

Filtrar en un valor de metadatos escalar:

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

Filtrar por metadatos anidados:

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

Hacer coincidir un valor de lista exactamente, incluido el orden:

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

Filtrar cuando una matriz de metadatos contiene un valor:

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

Combinar varias condiciones de metadatos. Un registro debe satisfacer todas las claves:

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)

Busque registros de forma asíncrona por similitud semántica.

• Parámetros:
  • query str | None: el mismo texto de consulta aceptado por search.
  • k int: el mismo recuento máximo de resultados aceptado por search. Los valores explícitos deben ser al menos 1.
  • query_vector list[float] | None: la misma incrustación opcional de consulta calculada previamente aceptada por search.
  • thread_id str | None: los mismos filtros de ámbito opcionales aceptados por search.
  • user_id str | None: los mismos filtros de ámbito opcionales aceptados por search.
  • agent_id str | None: los mismos filtros de ámbito opcionales aceptados por search.
  • exact_user_match bool: los mismos indicadores de coincidencia exacta que acepta search.
  • exact_agent_match bool: los mismos indicadores de coincidencia exacta que acepta search.
  • exact_thread_match bool: los mismos indicadores de coincidencia exacta que acepta search.
  • record_types set[str] | None: el mismo filtro de tipo de registro opcional aceptado por search.
  • metadata_filter dict[str, Any] | None: el mismo filtro de metadatos opcional aceptado por search, incluidos escalar, anidado, lista exacta, pertenencia a una matriz y condiciones combinadas, como {"source": "slack"}, {"review": {"status": "open"}}, {"tags": ["prod", "urgent"]} y {"tags": {"$array_contains": "prod"}}.
  • include_invalid_results bool: la misma opción de resultado de estado de ciclo de vida aceptada por search.
  • num_hops int: la misma profundidad de expansión de gráficos aceptada por search.
  • max_linked_results int: el mismo límite de memoria enlazada por resultado directo aceptado por search.
• Devoluciones: pares (record, distance) devueltos por la llamada search subyacente.
• Tipo de devolución: List[tuple[Registro, float]]
• Problemas: ValueError: si k es menor que 1.

método update

Actualizar contenido de registro almacenado, estado de búsqueda, metadatos y valores de registro de hora.

• Parámetros:
  • record_type str: etiqueta de tipo de registro de la fila que se está modificando (por ejemplo, "message", "memory", "guideline", "fact", "preference", "user_profile" o "agent_profile")
  • record_id str: identificador de la fila almacenada que se actualizará.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None: el contenido de sustitución canónico se mantiene en la columna content. Para los registros de mensajes, transfiera "" para borrar el contenido mientras borra cualquier representación vectorial almacenada; se rechaza None explícito. Para registros similares a la memoria, transfiera None para borrar el texto almacenado y embeber, y transfiera solo None o argumentos semánticos omitidos en la misma llamada. Cuando se omite, el contenido existente no se modifica. No lo proporcione junto con text.
  • index_text str | list[str] | None: carga útil solo semántica opcional. Cuando se omite, content se utiliza para la indexación semántica. En los esquemas con capacidad híbrida, también se convierte en el texto de búsqueda almacenado que utiliza el componente de texto de Oracle. El almacén puede fragmentar un valor de cadena; un valor de lista se trata como fragmentos propiedad del emisor de llamada y se escribe como está en RECORD_CHUNKS. Cuando solo se proporciona embedding, el texto de búsqueda existente se vuelve a utilizar.

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

    Vector de incrustación precalculado opcional o lista de vectores de incrustación de fragmentos. Cuando se configura el almacenamiento vectorial local, se utiliza directamente y no se realiza ninguna llamada de incrustación. Transfiera None para borrar la embebida almacenada. Un único vector representa todo el texto de sustitución cuando se proporciona content, incluso cuando el fragmentador configurado dividiría ese texto. Se rechazan varios vectores de fragmentos al sustituir texto, a menos que index_text sea una lista de fragmentos. Cuando solo se proporciona embedding, el recuento de incrustaciones debe coincidir con las filas de fragmentos existentes del registro.

    En SearchStrategy.VECTOR, la búsqueda vectorial se clasifica en función de la incrustación almacenada. En SearchStrategy.HYBRID o SearchStrategy.KEYWORD, la búsqueda respaldada por la base de datos clasifica en el texto de búsqueda almacenado y el estado de índice híbrido o texto gestionado por Oracle, por lo que las incrustaciones de tiempo de actualización solo afectan a cualquier almacenamiento vectorial local configurado, no a esa estrategia de búsqueda activa. Si este almacén se ha configurado sin almacenamiento vectorial local, proporcione index_text en lugar de embedding para actualizar el texto visible para esos índices conscientes del texto. Las actualizaciones semánticas de solo texto pueden omitir embedding por completo en esos modos.

  • metadata dict[str, Any] | None: asignación de metadatos opcional serializada a JSON y almacenada en metadata. Para sustituir la imagen content se necesita "image_mime_type" con "image/png", "image/jpeg" o "image/webp". El almacén utiliza este campo para guardar la imagen, pero no la devuelve como parte de los metadatos del registro.
  • timestamp str | None: nuevo registro de hora opcional para guardar con el registro. Representa el momento en que se creó el registro. Cuando se omite, se conserva el registro de hora existente. Transfiera None para borrar el registro de hora guardado y utilice el tiempo de creación de la base de datos para futuros refrescamientos de caducidad de TimeToLiveAnchor.CREATED_AT. Cuando ttl_anchor es TimeToLiveAnchor.TIMESTAMP, los registros de hora ISO-8601 sin zona horaria se tratan como UTC.
  • ttl_days int | None: refrescamiento de caducidad opcional en días. Omita este argumento junto con ttl_anchor para conservar el registro de hora de caducidad actual. Transfiera None para utilizar MemoryRetentionConfig.max_ttl_days cuando la configuración de retención defina uno o para borrar la caducidad cuando no lo haga. Los valores por encima de MemoryRetentionConfig.max_ttl_days se sujetan a ese máximo con una advertencia. La actualización de la caducidad puede hacer que un registro caducado vuelva a estar visible si aún no se ha depurado.
  • ttl_anchor TimeToLiveAnchor: anclaje de tiempo de vida opcional para un refrescamiento de caducidad. Utilice TimeToLiveAnchor.CREATED_AT para realizar un recuento a partir de la hora de creación almacenada, o TimeToLiveAnchor.TIMESTAMP para realizar un recuento a partir de la sustitución timestamp proporcionada en la misma actualización, o el registro de hora del evento almacenado cuando se omite timestamp. Al proporcionar ttl_anchor sin ttl_days, se refresca la caducidad mediante MemoryRetentionConfig.default_ttl_days del esquema. Cuando se omite ttl_anchor durante un refrescamiento, el almacén utiliza TimeToLiveAnchor.CREATED_AT. Los refrescamientos con registro de hora anclados requieren un registro de hora ISO-8601 de sustitución en la misma llamada o un registro de hora de evento almacenado existente en ese formato. Los registros de hora ISO-8601 sin zona horaria se tratan como UTC.
  • status RecordStatus: estado opcional del ciclo de vida de reemplazo para los registros. Omitirlo para conservar el estado actual.

  • text str | None:

    Alias en desuso para content. Transfiera None para borrar el texto almacenado y borrar la incrustación almacenada. No lo proporcione junto con content.

    En desuso

    En desuso desde la versión 26.8.0: este parámetro estaba en desuso en la versión 26.8.0 y se eliminará en la versión 27.1. Utilice content en su lugar.

• Devoluciones: número de registros actualizados (0 o 1). Un valor de retorno de 0 significa que no se ha actualizado ningún registro.
• Tipo de devolución: int
• Problemas: ValueError: si record_type no está soportado, si no se proporciona ninguna carga útil de actualización o si los argumentos de actualización semántica son incompatibles.

Ejemplos

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)

Actualice de forma asíncrona el contenido del registro almacenado, incrustando datos, metadatos, registro de hora o caducidad.

• Parámetros:
  • record_type str: tipo lógico del registro que se debe actualizar.
  • record_id str: identificador del registro que se debe actualizar.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None: contenido de sustitución canónico. Para los registros message, transfiera una cadena o una secuencia ordenada de partes de contenido de texto e imagen; utilice "" para sustituir el mensaje por texto vacío. Para los registros similares a la memoria, los almacenes pueden aceptar None para borrar el texto almacenado y el estado semántico asociado. Omita el argumento para dejar el contenido sin cambios. No lo proporcione junto con text.
  • index_text str | list[str] | None: carga útil semántica alternativa opcional que se utiliza para volver a calcular o reemplazar el estado de búsqueda almacenado sin cambiar el texto persistente. Una cadena puede ser fragmentada internamente por la tienda. Una lista de cadenas no vacías se trata como fragmentos propiedad del emisor de llamada y no se debe volver a dividir. Algunas implementaciones también pueden persistir esto por separado como texto de búsqueda híbrida. Para un registro image, este campo sustituye la descripción de la imagen guardada.
  • embedding list[float] | ndarray | list[list[float] | ndarray] | None: vector de incrustación precalculado opcional o lista de vectores de incrustación de fragmentos. Cuando se proporciona, se utiliza directamente y no se realiza ninguna llamada de embebido. Varios vectores necesitan listas de fragmentos index_text coincidentes o filas de texto de fragmento almacenadas existentes. Transfiera None para borrar explícitamente la embebida almacenada cuando el almacén la admita. Las tiendas con indexación adaptada al texto también pueden permitir actualizaciones semánticas sin embeber ni embeber explícitamente.
  • metadata dict[str, Any] | None: asignación de metadatos de sustitución opcional. Transfiera None para borrar los metadatos cuando el almacén los soporte. La sustitución de la imagen content necesita "image_mime_type" en esta asignación. El almacén utiliza este campo para guardar la imagen, pero no la devuelve como parte de los metadatos del registro.
  • timestamp str | None: nuevo registro de hora opcional para guardar con el registro. Representa el momento en que se creó el registro. Omita este argumento para dejar el registro de hora almacenado sin cambios. Transfiera None para borrar el registro de hora guardado y utilice el tiempo que el registro se agregó a la tienda cuando la tienda lo admite.
  • ttl_days int | None: refrescamiento de caducidad opcional en días. Omita este argumento junto con ttl_anchor para conservar el registro de hora de caducidad actual. Transfiera None para borrar la caducidad.
  • ttl_anchor TimeToLiveAnchor: anclaje de tiempo de vida opcional para un refrescamiento de caducidad. Utilice TimeToLiveAnchor.CREATED_AT para la hora de creación del registro o TimeToLiveAnchor.TIMESTAMP para la sustitución timestamp proporcionada en la misma actualización, o el registro de hora del evento almacenado cuando se omite timestamp. Si se proporciona ttl_anchor sin ttl_days, se utiliza la duración de tiempo de actividad por defecto del almacén o esquema. Cuando se omite ttl_anchor durante un refrescamiento, las implantaciones utilizan TimeToLiveAnchor.CREATED_AT.
  • status RecordStatus: estado opcional del ciclo de vida de reemplazo para los registros. Omitirlo para conservar el estado actual.

  • text str | None:

    Alias en desuso para content. Transfiera None para borrar explícitamente el texto almacenado cuando el almacén lo soporte. No lo proporcione junto con content.

    En desuso

    En desuso desde la versión 26.8.0: este parámetro estaba en desuso en la versión 26.8.0 y se eliminará en la versión 27.1. Utilice content en su lugar.

• Devoluciones: número de registros actualizados (0 o 1). Un valor de retorno de 0 significa que no se ha actualizado ningún registro.
• Tipo de devolución: int
• Incidencias: ValueError: si la carga útil de actualización no es válida para el almacén, como omitir todos los campos opcionales o proporcionar argumentos semánticos en conflicto.

método update_relations

Actualice los campos de relaciones modificables y vuelva a calcular el estado del ciclo de vida del punto final.

Los campos omitidos permanecen sin cambios. Las etiquetas de enlace de memoria incorporadas siempre conservan su etiqueta inversa derivada.

• Parámetros:
  • relation_ids str | list[str]: identificador o identificadores de las relaciones que se van a actualizar.
  • relation_types str | list[str]: etiqueta o etiquetas de relación dirigida de reemplazo opcional.
  • opposite_relation_types str | list[str]: etiqueta o etiquetas inversas de sustitución opcionales para tipos personalizados.
  • timestamps str | None | list[str | None]: registros de hora de sustitución opcionales. Transfiera None para borrar uno.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: metadatos de sustitución opcionales. Sustituye los metadatos existentes.
• Devoluciones: identificadores de las relaciones que se han actualizado.
• Tipo de devolución: list[str]

Ejemplos

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

method update_relations_async (async)

Actualice de forma asíncrona los valores modificables en las relaciones almacenadas.

Los campos omitidos permanecen sin cambios, excepto que el cambio a un tipo de relación de memoria incorporada reemplaza su etiqueta inversa con la inversa fija. Un almacén de memoria respaldado por base de datos también recalcula los estados del ciclo de vida de los puntos finales después de un cambio de tipo de relación.

• Parámetros:
  • relation_ids str | list[str]: identificador o identificadores de las relaciones que se van a actualizar.
  • relation_types str | list[str]: etiqueta o etiquetas de relación dirigida de reemplazo opcional. Omita esta opción para conservar las etiquetas almacenadas.
  • opposite_relation_types str | list[str]: etiqueta o etiquetas de relación inversa de sustitución opcionales. Transfiera una etiqueta para sustituirla u omita este argumento para conservarla.
  • timestamps str | None | list[str | None]: registro de hora o registros de hora de sustitución opcionales. Transfiera None para borrar un registro de hora almacenado.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None]: objeto u objetos de metadatos de sustitución opcionales. Los metadatos proporcionados sustituyen al objeto almacenado; no se fusionan.
• Devoluciones: identificadores de las relaciones que se han actualizado.
• Tipo de devolución: list[str]

Ejemplos

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

Relaciones

OracleDBMemoryStore puede almacenar relaciones dirigidas entre registros similares a la memoria (memory, fact, guideline y preference). Utilice add_relations(), get_relation(), list_relations(), update_relations() y delete_relations() cuando una integración necesite la API de relación de nivel inferior. Las API de cliente y thread proporcionan link_records(), update_record_link() y delete_record_link() para los tipos de relación de memoria soportados.

Para recuperar una relación, proporcione relation_id por sí mismo o la tupla de punto final almacenada completa: tipo e ID de registro de origen, tipo e ID de registro de destino y tipo y tipo de relación. Una tupla parcial y un ID de relación combinados con cualquier campo de tupla no son válidos porque ninguno de los dos identifica la relación solicitada de forma inequívoca.

Utilice list_relations() para enumerar las relaciones en orden de creación. Filtre por tipo e ID de registro de origen o de destino, o por etiqueta de relación dirigida. Utiliza el límite normal de la lista de seguridad de la tienda a menos que pase limit=None. Su metadata_filter utiliza la misma semántica de coincidencia exacta, objeto anidado, pertenencia a matriz y negación que list(); transfiera metadata_filter=None para devolver solo las relaciones sin metadatos.

Los tipos de relación de ciclo de vida (supersedes, refines y duplicates) marcan su memoria de destino como no válida mientras exista el enlace. Al eliminar o cambiar el último enlace de este tipo, se restaura el destino al estado válido. Las API de búsqueda pueden excluir registros no válidos con include_invalid_results=False.

clase oracleagentmemory.apis.relations.RecordRelation

Bases: object

Describa una relación dirigida y almacenada entre dos registros.

• Parámetros:
  • id str: identificador estable de la relación.
  • source_record_id str: identificador del registro en el origen almacenado de la relación.
  • source_record_type str: tipo lógico del registro de origen.
  • target_record_id str: identificador del registro en el destino almacenado de la relación.
  • target_record_type str: tipo lógico del registro de destino.
  • relation_type str: etiqueta cuyo significado sigue la dirección de origen a destino almacenada.
  • opposite_relation_type str: etiqueta que se utiliza cuando el recorrido se mueve de un destino a otro.
  • timestamp str | None: registro de hora de emisor de llamada opcional asociado con la relación.
  • metadata dict[str, Any] | None: metadatos opcionales similares a JSON almacenados con la relación.
  • created_at str: registro de hora de creación de base de datos para la relación.

Estrategia de búsqueda

clase oracleagentmemory.core.dbsearch.SearchStrategy

Bases: Enum

Comportamiento de búsqueda de almacenes de Oracle DB.

La inicialización del almacén de base de datos utiliza la estrategia seleccionada para seleccionar la capacidad de búsqueda de esquema gestionado. La búsqueda VECTOR almacena incrustaciones locales. La búsqueda KEYWORD almacena texto apto para búsqueda y un índice de texto. La búsqueda HYBRID almacena el texto que se puede buscar más el estado de índice vectorial híbrido gestionado por Oracle. El almacén de base de datos valida esta capacidad de esquema al iniciar para que una estrategia incompatible no devuelva resultados incompletos de forma silenciosa.

VECTOR

Buscar solo por similitud de vectores. La tienda embebebe la consulta con el embebido configurado o utiliza un query_vector proporcionado por el emisor de llamada y clasifica los registros por distancia de los vectores almacenados. Utilícelo con un esquema de base de datos configurado para la búsqueda vectorial.

HYBRID

Busque con el índice híbrido gestionado de Oracle. Oracle combina la coincidencia de texto sobre el texto de búsqueda almacenado con la clasificación vectorial del índice híbrido en la base de datos. Utilice esta opción cuando los usuarios puedan buscar por lenguaje natural, así como por identificadores exactos, alias o nombres de productos. Esta estrategia requiere que el embebido principal del almacén sea OracleDBEmbedder para que el índice gestionado y el almacén compartan un modelo en la base de datos.

KEYWORD

Busque solo por palabra clave/texto que coincida con el texto de búsqueda almacenado. Este modo no crea embebidas de consultas locales y no necesita un embebido de Oracle DB. Cuando se abre en un esquema híbrido existente, puede utilizar la rama de texto de ese índice híbrido sin crear un nuevo índice híbrido. Utilice esta opción cuando los identificadores exactos, los alias, los nombres de productos o las frases cortas deban permitir la recuperación de unidades sin fusión de vectores.

HYBRID = 'híbrido'

Palabra clave = 'palabra clave'

VECTOR = 'VECTOR'

Modo de sincronización de índice de búsqueda

clase oracleagentmemory.core.dbsearch.SearchIndexSyncMode

Bases: Enum

Comportamiento de refrescamiento para índices de búsqueda de base de datos gestionados.

Este valor controla cuándo Oracle hace que el texto de búsqueda nuevo o cambiado sea visible para la búsqueda con reconocimiento de texto respaldada por base de datos. SearchStrategy.HYBRID utiliza el índice vectorial híbrido gestionado de Oracle. SearchStrategy.KEYWORD utiliza un índice de Oracle Text. SearchStrategy.VECTOR no utiliza este valor.

ON_COMMIT

Refresque el índice cuando se confirme la transacción de escritura. Esta es la opción por defecto y la más sencilla para la mayoría de las aplicaciones porque los registros se pueden buscar inmediatamente después de una escritura correcta. Puede agregar trabajo para escribir transacciones porque el índice se mantiene actualizado de inmediato.

MANUAL

No refresque el índice automáticamente. Es posible que los registros nuevos o actualizados no aparezcan en la búsqueda por palabra clave o híbrida hasta que ejecute la operación de sincronización de índice de la base de datos usted mismo. Esto resulta útil para cargas masivas o ventanas de mantenimiento en las que desea controlar cuando se ejecuta el trabajo de refrescamiento.

AUTO

Deje que Oracle refresque el índice híbrido gestionado de forma asíncrona. Las escrituras pueden evitar el costo de refrescamiento inmediato, pero los resultados de la búsqueda pueden retrasarse con respecto a las escrituras recientes hasta que Oracle complete el refrescamiento en segundo plano. Este modo solo está soportado con SearchStrategy.HYBRID.

Advertencia: este valor controla el mantenimiento continuo después de que exista el índice de búsqueda gestionado. No hace que la primera creación de índice sea asíncrona. La creación de un índice híbrido gestionado sobre el texto de búsqueda almacenado existente puede ser de larga ejecución porque Oracle crea el estado de índice híbrido gestionado a partir de ese texto.

AUTO = 'AUTO'

MANUAL = 'MANUAL'

ON_COMMIT = 'ON_COMMIT'

Periodo de vida

clase oracleagentmemory.core.retention.MemoryRetentionConfig

Bases: object

Configuración de retención de nivel de esquema para registros respaldados por Oracle DB.

• Parámetros:
  • default_ttl_days int | None: duración predeterminada del tiempo de vida, en días. Deje NOT_SET_MARKER para utilizar el valor por defecto de None (sin máximo).
  • max_ttl_days int | None: duración máxima opcional del tiempo de vida, en días. Deje NOT_SET_MARKER para utilizar el valor por defecto de None. Transfiera None sin máximo. Cuando se define, se trata de un límite estricto: las escrituras que intentan utilizar un valor ttl_days mayor se sujetan a este máximo con una advertencia y las API de escritura que pasan ttl_days=None utilizan este máximo en lugar de crear registros que no caducan.

clase oracleagentmemory.apis.ttl.TimeToLiveAnchor

Bases: Enum

Anclaje utilizado para calcular un registro de hora de caducidad a partir de una duración de tiempo de vida.

CREATED_AT

Caducidad de cálculo desde el registro de hora de creación de la base de datos del registro. Este es el valor por defecto cuando los emisores de llamadas omiten ttl_anchor.

TIMESTAMP

Calcular caducidad desde el registro de hora de evento almacenado del registro. Utilice esta opción cuando un mensaje o memoria represente un evento anterior y deba caducar en relación con la hora del evento en lugar de la hora de inserción.

CREATED_AT = 'CREATED_AT'

TIMESTAMP = 'TIMESTAMP' (Registro de hora)

Política de esquema

clase oracleagentmemory.core.SchemaPolicy

Bases: str, Enum

Política de creación de esquema para almacenes de Oracle DB.

REQUERIR_EXISTENTE

Valide que el esquema gestionado completo ya existe y que está actualizado. No cree ni modifique objetos de base de datos.

CREAR_IF_EMPTY

Si no existen objetos gestionados, esquema de inicialización de datos. Si ya existen objetos, necesita un esquema gestionado completo y actualizado.

CREAR_SI_NECESARIO

Cree los objetos gestionados que faltan y aplique actualizaciones de esquema gestionado soportadas.

VOLVER A CREAR

Borrar y volver a crear todos los objetos de esquema gestionados. Esto es destructivo.

SIN COMPROBACIÓN

Omita la validación y creación del esquema gestionado. Utilice esta política para un almacén protegido por Deep Data Security existente mientras un contexto de seguridad de usuario final está activo. Un almacén abierto en un contexto de usuario final necesita un contexto activo para cada operación de base de datos posterior. Otras políticas de esquema rechazan los contextos de usuario final porque el trabajo del ciclo de vida del esquema debe ejecutarse a través de una identidad de base de datos administrativa.