Lojas e Esquema

Esta página apresenta as abstrações do armazenamento principal e os controles de esquema usados pelo SDK de Memória do Oracle Agent.

API da loja

Semântica de Gravação da Loja

As gravações de armazenamento mantêm uma separação clara entre o texto que um aplicativo armazena e o payload que o armazenamento usa para recuperação. A maioria dos aplicativos pode usar as APIs no nível da memória e do thread e permitir que o armazenamento prepare as linhas de pesquisa necessárias para recuperação de vetores, palavras-chave ou híbrida. As APIs de armazenamento de nível inferior expõem index_texts, index_text, embeddings e embedding para integrações avançadas que já sabem qual texto ou vetores devem ser usados para recuperação.

Pense em cada escrita como duas partes relacionadas:

• contents em add() e content em update() controlam o conteúdo do registro armazenado retornado por get(), list() e os resultados da pesquisa.
• O index_texts em add() e o index_text em update() controlam o texto gravado nas linhas de recuperação do armazenamento. A pesquisa usa essas linhas e retorna os registros lógicos originais.

update() também aceita text como um parâmetro de compatibilidade obsoleto. Use content no novo código; o fornecimento de text emite um aviso de descontinuação.

Se nenhuma substituição de pesquisa ou incorporação explícita for fornecida, o armazenamento usará o texto armazenado resolvido como o texto de recuperação. O texto não vazio é dividido pela loja quando a divisão em blocos é configurada. O texto vazio armazena o texto do registro, mas não fornece texto de recuperação.

A tabela abaixo descreve como o texto de recuperação é escolhido antes que os payloads vetoriais explícitos sejam considerados.

Payloads de recuperação no nível da loja

Entrada	add()	update()
index_texts ou index_text omitido	Cada registro usa seu valor contents resolvido para recuperação.	Um valor content de substituição é usado para recuperação. Se content também for omitido, as atualizações somente incorporação reutilizarão as linhas de texto de recuperação existentes do registro.
String index_texts entrada ou string index_text	A string substitui o texto de recuperação desse registro. O armazenamento pode separá-lo antes de gravar linhas de recuperação.	A string substitui o texto de recuperação desse registro. O armazenamento pode separá-lo antes de gravar linhas de recuperação.
Entrada list[str] index_texts ou list[str] index_text	A lista é tratada como chunks de propriedade do chamador. Cada string não vazia é gravada como uma linha de recuperação e o armazenamento não a divide novamente.	A lista é tratada como chunks de propriedade do chamador. Cada string não vazia é gravada como uma linha de recuperação e o armazenamento não a divide novamente.
Entrada None index_texts ou index_text=None	None na lista externa index_texts significa "usar o conteúdo armazenado para este registro".	index_text=None limpa as linhas de recuperação ao deixar o conteúdo armazenado inalterado, a menos que content também seja fornecido.
String vazia ou lista de partes vazia	Armazena o conteúdo do registro e não fornece texto de recuperação para esse registro.	Atualiza o conteúdo do registro quando o content é fornecido e limpa o texto de recuperação desse registro.

As incorporações explícitas são opcionais. Quando eles são omitidos, o armazenamento deriva vetores locais do texto de recuperação quando o armazenamento vetorial local é configurado; os armazenamentos de palavras-chave ou híbridos também podem usar linhas de recuperação somente texto. Quando valores embeddings ou embedding explícitos são fornecidos, o armazenamento grava esses vetores diretamente e não chama seu incorporador para esses vetores.

No add(), embeddings=None se comporta como omitir embeddings. No update(), embedding=None é explícito: o armazenamento mantém ou reescreve o texto de recuperação de acordo com content e index_text, mas armazena essas linhas sem vetores locais. Se content e index_text forem omitidos, isso limpará os vetores das linhas de recuperação existentes.

A forma do vetor informa à loja a quantidade de propriedade de chunk que o chamador está tomando:

• um vetor significa um vetor para todo o texto de recuperação. A loja não divide esse texto para o vetor explícito. Se esse texto de recuperação estiver vazio, o vetor poderá ser armazenado sem texto de bloco complementar.
• múltiplos vetores significam um vetor por pedaço de propriedade do chamador. Forneça listas de segmentos index_texts ou index_text correspondentes ou use um update() somente incorporação que reutilize as linhas de texto de recuperação existentes do registro.
• as contagens de vetores devem corresponder às contagens de chunk, e todos os vetores explícitos em uma chamada add() devem ter a mesma dimensão.
• um payload de vetor por registro vazio é permitido somente quando não há linhas de texto de recuperação para alinhar com ele.

Algumas combinações são rejeitadas, portanto, o texto armazenado, o texto de recuperação e os vetores não se afastam. A transmissão de content=None limpa o conteúdo armazenado e as linhas de recuperação, de modo que não pode ser combinada com valores index_text ou embedding não nulos; os registros de perfil do ator não suportam content=None. O parâmetro text obsoleto tem o mesmo comportamento. Passar index_text=None em update() significa "limpar linhas de recuperação", portanto, incorporações explícitas não vazias não são permitidas na mesma chamada. Vários vetores explícitos exigem texto em bloco explícito, a menos que a atualização seja somente incorporação e as linhas de recuperação existentes já forneçam o texto em bloco.

classe oracleagentmemory.core.OracleMemoryStore

Bases: IMemoryStore

Interface de armazenamento comum usada pelo OracleAgentMemory.

Uma implementação de loja é responsável por persistir registros de texto e executar uma pesquisa de similaridade sobre eles. Os pontos de entrada síncronos e assíncronos são definidos para que as APIs de nível superior possam expor superfícies síncronas/assíncronas correspondentes sem duplicar a lógica específica da loja.

método add

Adicionar registros à loja.

• Parâmetros:
  • contents Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None] – Sequência somente leitura de payloads de registro. As entradas de mensagem podem conter partes MessageContent solicitadas, enquanto as entradas de resumo de thread podem ser mapeamentos. Os valores de texto também são usados para indexação semântica, a menos que index_texts ou embeddings sejam fornecidos. Quando um valor de texto é None, as implementações podem voltar para metadata["content"]. Strings vazias explícitas são preservadas.
  • record_type str – Tipo de registro lógico a ser criado (por exemplo, "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" ou "thread_summary").
  • index_texts list[str | list[str] | None] – Payloads alternativos opcionais usados somente para indexação semântica. Quando fornecida, a lista externa deve se alinhar às entradas de texto. Cada entrada pode ser uma string, que a loja pode separar internamente, ou uma lista de strings não vazias, que a loja trata como partes de propriedade do chamador e não deve dividir novamente.
  • embeddings list[list[float] | ndarray | list[list[float] | ndarray]] – Vetores de incorporação pré-calculados opcionais alinhados com as entradas de texto. Cada entrada de registro pode ser um vetor de incorporação ou uma lista de vetores de incorporação de bloco para esse registro. Quando fornecido, a loja deve usar esses vetores diretamente em vez de invocar seu embutidor. Vários vetores para um registro exigem listas de segmentos index_texts correspondentes, de modo que os limites de trechos de texto e vetor sejam explícitos. Se não for fornecido, os armazenamentos geralmente derivam o estado semântico do incorporador configurado, mas os modos de indexação com reconhecimento de texto específicos da implementação também podem permitir gravações somente texto sem um.
  • record_ids str | None | list[str | None] – Identificadores opcionais visíveis para chamadores. Uma única string pode ser usada para inserções de um registro, enquanto as listas devem se alinhar às entradas de texto. Os identificadores gerados são retornados quando este campo é omitido.
  • thread_ids str | None | list[str | None] – Identificadores de thread opcionais associados aos registros inseridos. Os valores escalares podem ser transmitidos em entradas de texto alinhadas.
  • user_ids str | None | list[str | None] – Identificadores de usuário opcionais associados aos registros inseridos. Os valores escalares podem ser transmitidos em entradas de texto alinhadas.
  • agent_ids str | None | list[str | None] – Identificadores de agente opcionais associados aos registros inseridos. Os valores escalares podem ser transmitidos em entradas de texto alinhadas.
  • roles str | None | list[str | None] – Funções de mensagem opcionais como "user" ou "assistant". Os valores escalares podem ser transmitidos em entradas de texto alinhadas. Usado somente se record_type for "message".
  • timestamps – str | None | list[str | None] – Carimbos de data/hora opcionais a serem salvos com os registros. Cada timestamp representa um evento associado ao registro. Os valores escalares podem ser transmitidos em entradas de texto alinhadas. As entradas Omitidas ou None armazenam um timestamp de evento NULL; as leituras usam o horário de criação do registro como o timestamp efetivo.
  • metadados dict[str, Any] | None | list[dict[str, Any] | None] – dicionários de metadados opcionais fornecidos pelo chamador. Os metadados podem incluir "content" como origem de fallback quando um valor de texto é omitido em vez de ser definido explicitamente como "". Quando record_type="image", cada gravação de imagem requer "image_mime_type" com um dos seguintes "image/png", "image/jpeg" ou "image/webp". O armazenamento usa esse campo para salvar a imagem, mas não a retorna como parte dos metadados do registro.
  • ttl_days int | None | list[int | None] – Duração opcional do tempo de vida em dias para registros que suportam a expiração. Omita esse argumento para usar o padrão de armazenamento. Informe None para registros que não devem expirar. Os valores escalares podem ser transmitidos em entradas de texto alinhadas.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor] – Âncora de tempo de vida opcional. Use TimeToLiveAnchor.CREATED_AT para expirar em relação ao horário de criação armazenado ou TimeToLiveAnchor.TIMESTAMP para expirar em relação ao timestamp de evento de cada registro. Quando omitidas, as implementações usam TimeToLiveAnchor.CREATED_AT.
  • statuses RecordStatus | list[RecordStatus] – Status de ciclo de vida ou status opcionais para registros. Omita isso para armazenar RecordStatus.VALID.
  • **store_kwargs (Qualquer) – Opções de gravação específicas para implementação encaminhadas para o armazenamento concreto.
• Tipo de retorno: list[str]

Observações

Use add_batches() quando o chamador já tiver um ou mais objetos PendingRecordBatch.

• Retorna: Identificadores para os registros inseridos, na mesma ordem lógica da entrada.
• Tipo de retorno: List[str]
• Parâmetros:
  • conteúdo Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
  • tipo_registro str
  • index_texts list[str | list[str] | None]
  • incorporações 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]
  • funções str | None | list[str | None]
  • timestamps (str | None | list[str | None])
  • metadados dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • status RecordStatus | list[RecordStatus]
  • store_kwargs Any

method add_agent (abstract)

Adicionar um registro de perfil do agente.

• Parâmetros:
  • agent_id str – Identificador estável para o perfil do agente.
  • informação str – Texto de formato livre descrevendo o agente.
  • metadados dict[str, Any] | None – Mapeamento de metadados opcional armazenado na linha de perfil do agente.
• Devoluções: Identificador do registro de perfil do agente criado.
• Tipo de retorno: str

método add_agent_async (assíncrono)

Adicionar de forma assíncrona um registro de perfil de agente.

• Parâmetros:
  • agent_id str – Identificador estável para o perfil do agente.
  • informação str – Texto de formato livre descrevendo o agente.
  • metadados dict[str, Any] | None – Mapeamento de metadados opcional armazenado na linha de perfil do agente.
• Devoluções: Identificador do registro de perfil do agente criado.
• Tipo de retorno: str

método add_async (assíncrono)

Adicione registros orientados por linha de forma assíncrona à loja.

Aceita os mesmos argumentos e retorna os mesmos identificadores que add().

• Parâmetros:
  • conteúdo Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
  • tipo_registro str
  • index_texts list[str | list[str] | None]
  • incorporações 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]
  • funções str | None | list[str | None]
  • timestamps (str | None | list[str | None])
  • metadados dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • status RecordStatus | list[RecordStatus]
  • store_kwargs Any
• Tipo de retorno: list[str]

método add_batches

Adicione lotes lógicos preparados pelo chamador à loja.

• Parâmetros:
  • batches list[PendingRecordBatch] – Lotes lógicos totalmente preparados para persistir. Cada batch deve ter seus próprios campos por registro, como record_type, valores de escopo, atribuições, timestamps e metadados.
  • **store_kwargs (Qualquer) – Opções de gravação específicas para implementação encaminhadas para o armazenamento concreto.
• Retorna: Identificadores para os registros inseridos, na mesma ordem lógica que os lotes e linhas de entrada.
• Tipo de retorno: List[str]

Exemplos

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

método add_batches_async (assíncrono)

Adicione lotes lógicos preparados pelo chamador de forma assíncrona ao armazenamento.

Aceita os mesmos argumentos e retorna os mesmos identificadores que add_batches().

• Parâmetros:
  • lotes list[PendingRecordBatch]
  • store_kwargs Any
• Tipo de retorno: list[str]

method add_relations (abstract)

Armazene uma ou mais relações direcionadas.

Os valores escalares são transmitidos pelo lote de registro de origem. Os valores de lista devem ter o mesmo tamanho. Somente uma orientação pode ser armazenada para um par de pontos finais. Use opposite_relation_types para descrever a view reversa em vez de adicionar uma segunda relação reversa. As implementações podem restringir quais tipos de registro de ponto final e rótulos de relação eles persistem.

• Parâmetros:
  • source_record_ids str | list[str] – Identificador ou identificadores de registros na extremidade de origem de cada relação direcionada.
  • source_record_types str | list[str] – Tipo ou tipos de registro para source_record_ids. Forneça um valor para todas as origens ou um valor para cada relação.
  • target_record_ids str | list[str] – Identificador ou identificadores de registros na extremidade de destino de cada relação direcionada.
  • target_record_types str | list[str] – Tipo ou tipos de registro para target_record_ids. Forneça um valor para todos os alvos ou um valor para cada relação.
  • relation_types str | list[str] – Rótulo ou rótulos de relação direcionados. Forneça um valor para todas as relações ou um valor para cada relação.
  • opposite_relation_types str | list[str] – Label ou labels opcionais para a view reversa de cada relação. Para tipos de relação de memória incorporados, a omissão usa o rótulo reverso predefinido. Para tipos de relação personalizados, a omissão usa o mesmo rótulo em ambas as direções.
  • relation_ids str | None | list[str | None] – Identificador ou identificadores estáveis opcionais. Omita isso para permitir que o armazenamento gere identificadores.
  • timestamps (str | None | list[str | None]) – Timestamp ou timestamps opcionais para armazenar nas relações.
  • metadados dict[str, Any] | None | list[dict[str, Any] | None] – Objetos ou objetos de metadados opcionais a serem armazenados nas relações.
• Retorna: Identificadores de relação na ordem de entrada.
• Tipo de retorno: list[str]

Exemplos

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

método add_relations_async (assíncrono)

Armazenar assincronamente uma ou mais relações direcionadas.

Os valores escalares são transmitidos pelo lote de registro de origem. Os valores de lista devem ter o mesmo tamanho. Somente uma orientação pode ser armazenada para um par de pontos finais. Use opposite_relation_types para descrever a view reversa em vez de adicionar uma segunda relação reversa.

• Parâmetros:
  • source_record_ids str | list[str] – Identificador ou identificadores de registros na extremidade de origem de cada relação direcionada.
  • source_record_types str | list[str] – Tipo ou tipos de registro para source_record_ids. Forneça um valor para todas as origens ou um valor para cada relação.
  • target_record_ids str | list[str] – Identificador ou identificadores de registros na extremidade de destino de cada relação direcionada.
  • target_record_types str | list[str] – Tipo ou tipos de registro para target_record_ids. Forneça um valor para todos os alvos ou um valor para cada relação.
  • relation_types str | list[str] – Rótulo ou rótulos de relação direcionados. Forneça um valor para todas as relações ou um valor para cada relação.
  • opposite_relation_types str | list[str] – Label ou labels opcionais para a view reversa de cada relação. Para tipos de relação de memória incorporados, a omissão usa o rótulo reverso predefinido. Para tipos de relação personalizados, a omissão usa o mesmo rótulo em ambas as direções.
  • relation_ids str | None | list[str | None] – Identificador ou identificadores estáveis opcionais. Omita isso para permitir que o armazenamento gere identificadores.
  • timestamps (str | None | list[str | None]) – Timestamp ou timestamps opcionais para armazenar nas relações.
  • metadados dict[str, Any] | None | list[dict[str, Any] | None] – Objetos ou objetos de metadados opcionais a serem armazenados nas relações.
• Retorna: Identificadores de relação na ordem de entrada.
• Tipo de retorno: list[str]

Exemplos

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

method add_user (abstract)

Adicionar um registro de perfil de usuário.

• Parâmetros:
  • user_id str – Identificador estável para o perfil do usuário. As implementações suportadas pelo BD podem inferir esse valor de um contexto de segurança de usuário final anexado quando ele é omitido.
  • informações str – Texto de formato livre obrigatório que descreve o usuário.
  • metadados dict[str, Any] | None – Mapeamento de metadados opcional armazenado na linha do perfil do usuário.
• Devoluções: Identificador do registro de perfil do usuário criado.
• Tipo de retorno: str

método add_user_async (assíncrono)

Adicionar de forma assíncrona um registro de perfil de usuário.

• Parâmetros:
  • user_id str – Identificador estável para o perfil do usuário.
  • information str – Texto de formato livre descrevendo o usuário.
  • metadados dict[str, Any] | None – Mapeamento de metadados opcional armazenado na linha do perfil do usuário.
• Devoluções: Identificador do registro de perfil do usuário criado.
• Tipo de retorno: str

method delete (abstract)

Excluir um registro armazenado por identificador.

• Parâmetros:
  • record_type str – Tipo lógico do registro a ser removido.
  • record_id str – Identificador do registro a ser removido.
  • cascade bool – Quando True, aplique qualquer comportamento de exclusão em cascata suportado pelo armazenamento para os destinos de nível superior solicitados dentro da mesma operação de exclusão. Isso é usado principalmente para alvos como perfis de ator que possuem registros com escopo adicional. Por exemplo, uma cascata de perfil de usuário ou perfil de agente pode excluir threads próprios, as mensagens de escopo de thread e registros semelhantes a memória removidos com esses threads e quaisquer registros de escopo de ator diretamente restantes, como mensagens, memórias, diretrizes, fatos ou preferências. Para exclusões de ator-perfil, essa limpeza com escopo ainda poderá ser executada quando a linha do perfil correspondente já estiver ausente.
• Retorna: Número de registros de nível superior solicitados excluídos, geralmente 0 ou 1. As linhas filho em cascata não são contadas separadamente, portanto, ainda pode ser 0 quando um perfil de ator ausente aciona a limpeza com escopo.
• Tipo de retorno: int

método delete_async (assíncrono)

Exclua de forma assíncrona um registro armazenado por identificador.

• Parâmetros:
  • record_type str – Tipo lógico do registro a ser removido.
  • record_id str – Identificador do registro a ser removido.
  • cascade bool – Quando True, aplique qualquer comportamento de exclusão em cascata suportado pelo armazenamento para os destinos de nível superior solicitados dentro da mesma operação de exclusão. Isso é usado principalmente para alvos como perfis de ator que possuem registros com escopo adicional. Por exemplo, uma cascata de perfil de usuário ou perfil de agente pode excluir threads próprios, as mensagens de escopo de thread e registros semelhantes a memória removidos com esses threads e quaisquer registros de escopo de ator diretamente restantes, como mensagens, memórias, diretrizes, fatos ou preferências. Para exclusões de ator-perfil, essa limpeza com escopo ainda poderá ser executada quando a linha do perfil correspondente já estiver ausente.
• Retorna: Número de registros de nível superior solicitados excluídos, geralmente 0 ou 1. As linhas filho em cascata não são contadas separadamente, portanto, ainda pode ser 0 quando um perfil de ator ausente aciona a limpeza com escopo.
• Tipo de retorno: int

method delete_relations (abstract)

Exclua relações por identificador.

O estado do ciclo de vida é recalculado a partir das relações que permanecem.

• Parâmetros: relation_ids str | list[str] – Identificador ou identificadores das relações a serem excluídas.
• Retorna: Número de relações excluídas.
• Tipo de retorno: int

Exemplos

store.delete_relations("relation-id")
1

método delete_relations_async (assíncrono)

Exclua relações de forma assíncrona por identificador.

O estado do ciclo de vida é recalculado a partir das relações que permanecem.

• Parâmetros: relation_ids str | list[str] – Identificador ou identificadores das relações a serem excluídas.
• Retorna: Número de relações excluídas.
• Tipo de retorno: int

Exemplos

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

method delete_thread (abstract)

Exclua um thread e seus dados armazenados associados.

• Parâmetros: thread_id str – Identificador do thread a ser removido.
• Retorna: Número de registros de thread excluídos, geralmente 0 ou 1.
• Tipo de retorno: int

Observações

Esta é a operação no nível do armazenamento para remover um thread e os registros no escopo do thread gerenciados pelo armazenamento. Prefira a exclusão de thread quando os requisitos de retenção exigirem a exclusão de mensagens de origem e de dados de memória com escopo de thread derivado, porque as exclusões no nível da mensagem não implicam que registros derivados persistidos separadamente sejam removidos.

método delete_thread_async (assíncrono)

Exclua de forma assíncrona um thread e seus dados armazenados associados.

• Parâmetros: thread_id str – Identificador do thread a ser removido.
• Retorna: Número de registros de thread excluídos, geralmente 0 ou 1.
• Tipo de retorno: int

Observações

Esta é a operação no nível do armazenamento para remover um thread e os registros no escopo do thread gerenciados pelo armazenamento. Prefira a exclusão de thread quando os requisitos de retenção exigirem a exclusão de mensagens de origem e de dados de memória com escopo de thread derivado, porque as exclusões no nível da mensagem não implicam que registros derivados persistidos separadamente sejam removidos.

method get (abstract)

Recuperar um registro armazenado por tipo e identificador.

• Parâmetros:
  • record_type str – Tipo lógico do registro a ser recuperado, como "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" ou "image".
  • record_id str – Identificador do registro a ser recuperado.
  • include_bytes bool – Se deseja carregar bytes de imagem armazenados. Para um registro de mensagem, isso controla se as imagens anexadas incluem seus bytes. Para um registro de imagem, ele controla se os bytes de imagem standalone são carregados. Esta opção não tem efeito em outros tipos de registro.
• Retorna: O registro armazenado quando encontrado, caso contrário, None. Uma pesquisa "thread" retorna um ThreadRecord com metadados de thread, configuração de runtime, estado de runtime e o timestamp de criação preenchido quando o armazenamento suporta threads persistidos.
• Tipo de retorno: Registro | Nenhum

método get_async (assíncrono)

Recuperar assincronicamente um registro armazenado por tipo e identificador.

• Parâmetros:
  • record_type str – Tipo lógico do registro a ser recuperado, como "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" ou "image".
  • record_id str – Identificador do registro a ser recuperado.
  • include_bytes bool – Se deseja carregar bytes de imagem armazenados. Para um registro de mensagem, isso controla se as imagens anexadas incluem seus bytes. Para um registro de imagem, ele controla se os bytes de imagem standalone são carregados. Esta opção não tem efeito em outros tipos de registro.
• Retorna: O registro armazenado quando encontrado, caso contrário, None. Uma pesquisa "thread" retorna um ThreadRecord com metadados de thread, configuração de runtime, estado de runtime e o timestamp de criação preenchido quando o armazenamento suporta threads persistidos.
• Tipo de retorno: Registro | Nenhum

method get_relation (abstract)

Retorna uma relação em sua orientação de origem a destino armazenada.

Forneça apenas relation_id ou uma tupla completa de ponto final de origem para destino.

• Parâmetros:
  • source_record_id str – Identificador do registro de origem. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • source_record_type str – Tipo de registro de origem. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • target_record_id str – Identificador de registro de destino. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • target_record_type str – Tipo de registro de destino. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • relation_type str – Rótulo de relação direcionada. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • relation_id str – O identificador de relação corresponde diretamente. Forneça esse argumento sozinho em vez de combiná-lo com campos de tupla de ponto final.
• Retorna: A relação de correspondência ou None quando ela não existe.
• Tipo de retorno: RecordRelation | Nenhum

Exemplos

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

método get_relation_async (assíncrono)

Recupera assincronicamente uma relação por tupla de ID ou ponto final.

Forneça apenas relation_id ou uma tupla completa de ponto final de origem para destino.

• Parâmetros:
  • source_record_id str – Identificador do registro de origem. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • source_record_type str – Tipo de registro de origem. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • target_record_id str – Identificador de registro de destino. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • target_record_type str – Tipo de registro de destino. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • relation_type str – Rótulo de relação direcionada. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • relation_id str – O identificador de relação corresponde diretamente. Forneça esse argumento sozinho em vez de combiná-lo com campos de tupla de ponto final.
• Retorna: A relação de correspondência ou None quando ela não existe.
• Tipo de retorno: RecordRelation | Nenhum

Exemplos

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

method list (abstract)

Listar registros armazenados para um tipo de registro.

• Parâmetros:
  • record_type str – Tipo de registro lógico a ser enumerado, como "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile", ou "thread_summary" ou "image".
  • limit int | None – Número máximo opcional de registros mais recentes a serem retornados. Quando omitidas, as implementações podem aplicar um limite superior seguro, como MAX_LIST_LIMIT. Passe None para desativar esse limite e retornar todos os registros correspondentes.
  • thread_id str | None – Filtro de escopo de thread exato. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros cujo thread_id é None são retornados. Os tipos de registro sem escopo ignoram este filtro. Quando record_type for "thread", thread_id não deverá ser definido; use record_id para selecionar um thread específico.
  • user_id str | None – Filtro de escopo de usuário exato. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros cujo user_id é None são retornados. Os tipos de registro sem escopo ignoram este filtro.
  • agent_id str | None – Filtro exato de escopo do agente. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros cujo agent_id é None são retornados. Os tipos de registro sem escopo ignoram este filtro.

  • metadata_filter dict[str, Any] | None –

    Filtro de metadados Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros cujos metadados são None são retornados. Quando definidas como um ditado, as entradas em metadata_filter são combinadas com a semântica AND. Entradas cujo valor não é um dicionário de operador de nível de campo usam semântica de correspondência exata: a chave solicitada deve existir nos metadados armazenados. Os dicionários aninhados são correspondidos recursivamente. Os valores escalares e de lista são correspondidos por igualdade exata; a ordem e o comprimento da lista também devem ser correspondentes. Para testar a associação de array, use um dicionário do operador no nível do campo, como {"tags": {"$array_contains": "prod"}}. Um operando de lista para "$array_contains" significa que todos os valores listados devem estar presentes; "$array_contains_any" significa que pelo menos um valor listado deve estar presente. Use "$not" para negar outra expressão no nível do campo no mesmo campo, incluindo um dicionário do operador ou valor de correspondência exata bruta. As expressões negativas correspondem quando a expressão positiva falharia, incluindo campos ausentes; a associação de matriz negada também corresponde a campos que não são de matriz. Os exemplos incluem metadata_filter={"source": "slack"} para um campo escalar, metadata_filter={"review": {"status": "open"}} para um campo aninhado e metadata_filter={"tags": ["prod", "urgent"]} para uma correspondência de lista exata. Combine condições para exigir todas elas:

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

  • include_bytes bool – Se os registros de imagem ou imagens anexados a registros de mensagem incluem bytes armazenados. Quando omitido ou False, as descrições de imagem e os metadados são retornados sem carregar bytes. Para listagens diretas de imagem, defina isso como True somente com um record_id exato e pelo menos um filtro exato de escopo de usuário, agente ou thread. Esta opção não tem efeito em outros tipos de registro.
  • record_id str – Filtro exato de identificador de registro. Quando omitido, os registros com qualquer identificador são retornados. Os filtros de escopo e metadados permanecem restrições adicionais.
• Devoluções: Registros ordenados do mais antigo para o mais recente na janela retornada.
• Tipo de retorno: List[Record]

método list_async (assíncrono)

Listar registros armazenados de forma assíncrona para um tipo de registro.

• Parâmetros:
  • record_type str – Tipo de registro lógico a ser enumerado, como "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" ou "image".
  • limit int | None – Número máximo opcional de registros mais recentes a serem retornados. Quando omitidas, as implementações podem aplicar um limite superior seguro, como MAX_LIST_LIMIT. Passe None para desativar esse limite e retornar todos os registros correspondentes.
  • thread_id str | None – Filtro de escopo de thread exato. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros cujo thread_id é None são retornados. Os tipos de registro sem escopo ignoram este filtro. Quando record_type for "thread", thread_id não deverá ser definido; use record_id para selecionar um thread específico.
  • user_id str | None – Filtro de escopo de usuário exato. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros cujo user_id é None são retornados. Os tipos de registro sem escopo ignoram este filtro.
  • agent_id str | None – Filtro exato de escopo do agente. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros cujo agent_id é None são retornados. Os tipos de registro sem escopo ignoram este filtro.

  • metadata_filter dict[str, Any] | None –

    Filtro de metadados Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros cujos metadados são None são retornados. Quando definidas como um ditado, as entradas em metadata_filter são combinadas com a semântica AND. Entradas cujo valor não é um dicionário de operador de nível de campo usam semântica de correspondência exata: a chave solicitada deve existir nos metadados armazenados. Os dicionários aninhados são correspondidos recursivamente. Os valores escalares e de lista são correspondidos por igualdade exata; a ordem e o comprimento da lista também devem ser correspondentes. Para testar a associação de array, use um dicionário do operador no nível do campo, como {"tags": {"$array_contains": "prod"}}. Um operando de lista para "$array_contains" significa que todos os valores listados devem estar presentes; "$array_contains_any" significa que pelo menos um valor listado deve estar presente. Use "$not" para negar outra expressão no nível do campo no mesmo campo, incluindo um dicionário do operador ou valor de correspondência exata bruta. As expressões negativas correspondem quando a expressão positiva falharia, incluindo campos ausentes; a associação de matriz negada também corresponde a campos que não são de matriz. Os exemplos incluem metadata_filter={"source": "slack"} para um campo escalar, metadata_filter={"review": {"status": "open"}} para um campo aninhado e metadata_filter={"tags": ["prod", "urgent"]} para uma correspondência de lista exata. Combine condições para exigir todas elas:

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

  • include_bytes bool – Se os registros de imagem ou imagens anexados a registros de mensagem incluem bytes armazenados. Quando omitido ou False, as descrições de imagem e os metadados são retornados sem carregar bytes. Para listagens diretas de imagem, defina isso como True somente com um record_id exato e pelo menos um filtro exato de escopo de usuário, agente ou thread. Esta opção não tem efeito em outros tipos de registro.
  • record_id str – Filtro exato de identificador de registro. Quando omitido, os registros com qualquer identificador são retornados. Os filtros de escopo e metadados permanecem restrições adicionais.
• Devoluções: Registros ordenados do mais antigo para o mais recente na janela retornada.
• Tipo de retorno: List[Record]

method list_relations (abstract)

Liste as relações armazenadas em sua orientação de origem para destino.

• Parâmetros:
  • relation_type str – Rótulo de relação direcionada opcional para correspondência, como "supports" ou "supersedes". Omita para incluir todos os tipos de relação.
  • source_record_id str – Identificador de registro fonte opcional a ser correspondente.
  • source_record_type str – Tipo de registro de origem opcional a ser correspondente.
  • target_record_id str – Identificador de registro de destino opcional a ser correspondente.
  • target_record_type str – Tipo de registro de destino opcional a ser correspondente.
  • limit int | None – Número máximo opcional de relações criadas mais recentemente a serem retornadas. Quando omitidas, as implementações podem aplicar um limite superior seguro, como MAX_LIST_LIMIT. Passe None para retornar todas as relações armazenadas correspondentes.
  • metadata_filter dict[str, Any] | None – Filtro de metadados. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente as relações cujos metadados são None são retornadas. Quando definidas como um ditado, as entradas são combinadas com a semântica AND. Os dicionários aninhados usam correspondência exata recursiva. Os valores escalares e de lista exigem igualdade exata; use {"tags": {"$array_contains": "prod"}} para corresponder à associação de array, "$array_contains_any" para corresponder a qualquer valor listado ou "$not" para negar outra expressão de campo.
  • relation_id str – Filtro exato de identificador de relação. Quando omitido, as relações com qualquer identificador são retornadas. Outros filtros permanecem restrições adicionais.
• Retorna: Relações ordenadas por hora de criação e identificador.
• Tipo de retorno: list[RecordRelation]

Exemplos

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

método list_relations_async (assíncrono)

Liste relações de forma assíncrona na orientação de origem para destino.

• Parâmetros:
  • relation_type str – Rótulo de relação direcionada opcional para correspondência, como "supports" ou "supersedes". Omita para incluir todos os tipos de relação.
  • source_record_id str – Identificador de registro fonte opcional a ser correspondente.
  • source_record_type str – Tipo de registro de origem opcional a ser correspondente.
  • target_record_id str – Identificador de registro de destino opcional a ser correspondente.
  • target_record_type str – Tipo de registro de destino opcional a ser correspondente.
  • limit int | None – Número máximo opcional de relações criadas mais recentemente a serem retornadas. Quando omitidas, as implementações podem aplicar um limite superior seguro, como MAX_LIST_LIMIT. Passe None para retornar todas as relações armazenadas correspondentes.
  • metadata_filter dict[str, Any] | None – Filtro de metadados. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente as relações cujos metadados são None são retornadas. Quando definidas como um ditado, as entradas são combinadas com a semântica AND. Os dicionários aninhados usam correspondência exata recursiva. Os valores escalares e de lista exigem igualdade exata; use {"tags": {"$array_contains": "prod"}} para corresponder à associação de array, "$array_contains_any" para corresponder a qualquer valor listado ou "$not" para negar outra expressão de campo.
  • relation_id str – Identificador de relação opcional para coincidir diretamente.
• Retorna: Relações ordenadas por hora de criação e identificador.
• Tipo de retorno: list[RecordRelation]

Exemplos

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

method list_thread_messages (abstract)

Liste o histórico de mensagens armazenado para um tópico.

• Parâmetros:
  • thread_id str – Identificador do thread cujas mensagens devem ser retornadas.
  • last_n int | None – Número opcional de mensagens mais recentes a serem incluídas. Quando omitidas, todas as mensagens armazenadas para o thread são retornadas. Quando combinado com um intervalo de sequência, o limite se aplica dentro desse intervalo.
  • range_start_seq_no int | None – Limite opcional da sequência inferior inclusivo. Somente mensagens cujo seq_no seja pelo menos esse valor serão retornadas.
  • range_end_seq_no int | None – Limite de sequência superior exclusivo opcional. Somente mensagens cujo seq_no seja menor que esse valor serão retornadas.
  • include_bytes bool – Se as partes de imagens anexadas às mensagens retornadas incluem bytes armazenados. Quando omitido ou False, as descrições de imagem e os metadados são retornados sem carregar bytes.
• Devoluções: Registros de mensagens ordenados do mais antigo para o mais recente na janela retornada.
• Tipo de retorno: List[MessageRecord]

método list_thread_messages_async (assíncrono)

Liste de forma assíncrona o histórico de mensagens armazenado para um thread.

• Parâmetros:
  • thread_id str – Identificador do thread cujas mensagens devem ser retornadas.
  • last_n int | None – Número opcional de mensagens mais recentes a serem incluídas. Quando omitidas, todas as mensagens armazenadas para o thread são retornadas. Quando combinado com um intervalo de sequência, o limite se aplica dentro desse intervalo.
  • range_start_seq_no int | None – Limite opcional da sequência inferior inclusivo. Somente mensagens cujo seq_no seja pelo menos esse valor serão retornadas.
  • range_end_seq_no int | None – Limite de sequência superior exclusivo opcional. Somente mensagens cujo seq_no seja menor que esse valor serão retornadas.
  • include_bytes bool – Se as partes de imagens anexadas às mensagens retornadas incluem bytes armazenados. Quando omitido ou False, as descrições de imagem e os metadados são retornados sem carregar bytes.
• Devoluções: Registros de mensagens ordenados do mais antigo para o mais recente na janela retornada.
• Tipo de retorno: List[MessageRecord]

method search (abstract)

Pesquisar registros por similaridade.

• Parâmetros:
  • query str | None – Consulta em linguagem natural. Deve ser fornecido quando query_vector for omitido.
  • query_vector list[float] | None – Incorporação de consulta pré-calculada opcional. Exatamente um dos query e query_vector deve ser fornecido.
  • k int - Número máximo de resultados a ser retornado. Os valores explícitos devem ser pelo menos 1. Este é um limite superior: a chamada pode retornar menos de k resultados quando os filtros são muito restritivos, quando há menos registros correspondentes não expirados ou por causa do comportamento de pesquisa específico da implementação.
  • thread_id str | None – Escopo do thread opcional.
  • user_id str | None – Filtros de escopo de usuário e agente opcionais.
  • agent_id str | None – Filtros de escopo de usuário e agente opcionais.
  • exact_user_match bool – Se cada identificador de escopo fornecido deve ser correspondido exatamente.
  • exact_agent_match bool – Se cada identificador de escopo fornecido deve ser correspondido exatamente.
  • exact_thread_match bool – Se cada identificador de escopo fornecido deve ser correspondido exatamente.
  • record_types set[str] | None – Conjunto opcional de tipos de registro a incluir.
  • metadata_filter dict[str, Any] | None – Mapeamento de filtro de metadados opcional. As entradas no metadata_filter são combinadas com a semântica AND. Entradas cujo valor não é um dicionário de operador de nível de campo usam semântica de correspondência exata: a chave solicitada deve existir nos metadados armazenados. Os dicionários aninhados são correspondidos recursivamente. Os valores escalares e de lista são correspondidos por igualdade exata; a ordem e o comprimento da lista também devem ser correspondentes. Para testar a associação de array, use um dicionário do operador no nível do campo, como {"tags": {"$array_contains": "prod"}}. Um operando de lista para "$array_contains" significa que todos os valores listados devem estar presentes; "$array_contains_any" significa que pelo menos um valor listado deve estar presente. Use "$not" para negar outra expressão no nível do campo no mesmo campo, incluindo um dicionário do operador ou valor de correspondência exata bruta. As expressões negativas correspondem quando a expressão positiva falharia, incluindo campos ausentes; a associação de matriz negada também corresponde a campos que não são de matriz.
  • include_invalid_results bool – Se os resultados incluem registros de memória no status inválido. O padrão é True. Informe False para excluí-los.
  • num_hops int – Número de bordas de link de memória a serem seguidas de cada resultado direto de memória. Há suporte para valores de 0 a 5; 0 desativa a expansão do gráfico.
  • max_linked_results int – Máximo de memórias vinculadas em todos os saltos anexados a cada resultado direto. 0 mantém resultados diretos sem contexto vinculado. O padrão é 100.
• Retorna: pares de (record, distance) classificados por distância crescente. A lista pode conter menos de k entradas.
• Tipo de retorno: list[tuple[Record, float]]
• Eleva: ValueError – Se k for menor que 1.

Exemplos

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 em um valor de metadados 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 em metadados aninhados:

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

Corresponder exatamente um valor de lista, incluindo a ordem:

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

Filtre quando um array de metadados contiver um valor:

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

Combine várias condições de metadados. Um registro deve atender a todas as chaves:

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

método search_async (assíncrono)

Pesquise registros de forma assíncrona por similaridade semântica.

• Parâmetros:
  • query str | None – O mesmo texto de consulta aceito por search.
  • k int – Mesma contagem máxima de resultados aceita por search. Os valores explícitos devem ser pelo menos 1.
  • query_vector list[float] | None – Mesma incorporação de consulta pré-calculada opcional aceita pelo search.
  • thread_id str | None – Os mesmos filtros de escopo opcionais aceitos por search.
  • user_id str | None – Os mesmos filtros de escopo opcionais aceitos por search.
  • agent_id str | None – Os mesmos filtros de escopo opcionais aceitos por search.
  • exact_user_match bool – Os mesmos sinalizadores de correspondência exata aceitos por search.
  • exact_agent_match bool – Os mesmos sinalizadores de correspondência exata aceitos por search.
  • exact_thread_match bool – Os mesmos sinalizadores de correspondência exata aceitos por search.
  • record_types set[str] | None – O mesmo filtro opcional de tipo de registro aceito por search.
  • metadata_filter dict[str, Any] | None – O mesmo filtro de metadados opcional aceito por search, incluindo escalar, aninhado, lista exata, associação de array e condições combinadas, como {"source": "slack"}, {"review": {"status": "open"}}, {"tags": ["prod", "urgent"]} e {"tags": {"$array_contains": "prod"}}.
  • include_invalid_results bool – Opção de resultado de mesmo status de ciclo de vida aceita por search.
  • num_hops int – Mesma profundidade de expansão de gráfico aceita pela search.
  • max_linked_results int – Mesmo limite de memória vinculada por resultado direto aceito por search.
• Retorna: pares (record, distance) retornados pela chamada search subjacente.
• Tipo de retorno: List[tuple[Record, float]]
• Eleva: ValueError – Se k for menor que 1.

method update (abstract)

Atualize o conteúdo do registro armazenado, incorporando dados, metadados, timestamp ou expiração.

• Parâmetros:
  • record_type str – Tipo lógico do registro a ser atualizado.
  • record_id str – Identificador do registro a ser atualizado.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None – Conteúdo de substituição canônica. Para registros message, informe uma string ou uma sequência ordenada de partes de conteúdo de texto e imagem; use "" para substituir a mensagem por texto vazio. Para registros semelhantes à memória, os armazenamentos podem aceitar None para limpar o texto armazenado e o estado semântico associado. Omita o argumento para deixar o conteúdo inalterado. Não forneça isso junto com text.
  • index_text str | list[str] | None – Payload semântico alternativo opcional usado para recomputar ou substituir o estado de pesquisa armazenado sem alterar o texto persistente. Uma string pode ser fragmentada internamente pela loja. Uma lista de strings não vazias é tratada como chunks de propriedade do chamador e não deve ser dividida novamente. Algumas implementações também podem persistir separadamente como texto de pesquisa híbrida. Para um registro image, esse campo substitui a descrição da imagem persistente.
  • embedding list[float] | ndarray | list[list[float] | ndarray] | None – Vetor de incorporação pré-computado opcional ou lista de vetores de incorporação de chunk. Quando fornecido, este é usado diretamente e nenhuma chamada de incorporador é feita. Vários vetores exigem listas de chunk index_text correspondentes ou linhas de chunk text armazenadas existentes. Passe None para limpar explicitamente a incorporação armazenada quando o armazenamento a suportar. Lojas com indexação com reconhecimento de texto também podem permitir atualizações semânticas sem um incorporador ou incorporação explícita.
  • metadata dict[str, Any] | None – Mapeamento de metadados de substituição opcional. Informe None para limpar metadados quando o armazenamento for compatível. A substituição da imagem content requer "image_mime_type" neste mapeamento. O armazenamento usa esse campo para salvar a imagem, mas não a retorna como parte dos metadados do registro.
  • timestamp str | None – Novo timestamp opcional para salvar com o registro. Ele representa quando o registro foi criado. Omita esse argumento para deixar o timestamp armazenado inalterado. Passe None para limpar o timestamp salvo e use o horário em que o registro foi adicionado à loja quando a loja a suporta.
  • ttl_days int | None – Atualização de expiração opcional em dias. Omita esse argumento junto com ttl_anchor para preservar o timestamp de expiração atual. Informe None para limpar a expiração.
  • ttl_anchor TimeToLiveAnchor – Âncora opcional de tempo de vida útil para uma atualização de expiração. Use TimeToLiveAnchor.CREATED_AT para o horário de criação do registro ou TimeToLiveAnchor.TIMESTAMP para o timestamp de substituição fornecido na mesma atualização ou o timestamp de evento armazenado quando timestamp for omitido. O fornecimento de ttl_anchor sem ttl_days usa a duração de tempo de vida padrão do armazenamento ou esquema. Quando o ttl_anchor é omitido durante uma atualização, as implementações usam TimeToLiveAnchor.CREATED_AT.
  • status RecordStatus – Status do ciclo de vida de substituição opcional para registros.

  • texto str | None –

    Alias obsoleto para content. Informe None para limpar explicitamente o texto armazenado quando o armazenamento o suportar. Não forneça isso junto com content.

    Obsoleto

    Obsoleto desde a versão 26.8.0: Este parâmetro foi preterido na versão 26.8.0 e será removido na versão 27.1. Em vez disso, use content.

• Retorna: Número de registros atualizados (0 ou 1). O valor de retorno 0 significa que nenhum registro foi atualizado.
• Tipo de retorno: int
• Eleva: ValueError – Se o payload de atualização for inválido para o armazenamento, como omitir todos os campos opcionais ou fornecer argumentos semânticos conflitantes.

método update_async (assíncrono)

Atualize de forma assíncrona o conteúdo do registro armazenado, incorporando dados, metadados, timestamp ou expiração.

• Parâmetros:
  • record_type str – Tipo lógico do registro a ser atualizado.
  • record_id str – Identificador do registro a ser atualizado.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None – Conteúdo de substituição canônica. Para registros message, informe uma string ou uma sequência ordenada de partes de conteúdo de texto e imagem; use "" para substituir a mensagem por texto vazio. Para registros semelhantes à memória, os armazenamentos podem aceitar None para limpar o texto armazenado e o estado semântico associado. Omita o argumento para deixar o conteúdo inalterado. Não forneça isso junto com text.
  • index_text str | list[str] | None – Payload semântico alternativo opcional usado para recomputar ou substituir o estado de pesquisa armazenado sem alterar o texto persistente. Uma string pode ser fragmentada internamente pela loja. Uma lista de strings não vazias é tratada como chunks de propriedade do chamador e não deve ser dividida novamente. Algumas implementações também podem persistir separadamente como texto de pesquisa híbrida. Para um registro image, esse campo substitui a descrição da imagem persistente.
  • embedding list[float] | ndarray | list[list[float] | ndarray] | None – Vetor de incorporação pré-computado opcional ou lista de vetores de incorporação de chunk. Quando fornecido, este é usado diretamente e nenhuma chamada de incorporador é feita. Vários vetores exigem listas de chunk index_text correspondentes ou linhas de chunk text armazenadas existentes. Passe None para limpar explicitamente a incorporação armazenada quando o armazenamento a suportar. Lojas com indexação com reconhecimento de texto também podem permitir atualizações semânticas sem um incorporador ou incorporação explícita.
  • metadata dict[str, Any] | None – Mapeamento de metadados de substituição opcional. Informe None para limpar metadados quando o armazenamento for compatível. A substituição da imagem content requer "image_mime_type" neste mapeamento. O armazenamento usa esse campo para salvar a imagem, mas não a retorna como parte dos metadados do registro.
  • timestamp str | None – Novo timestamp opcional para salvar com o registro. Ele representa quando o registro foi criado. Omita esse argumento para deixar o timestamp armazenado inalterado. Passe None para limpar o timestamp salvo e use o horário em que o registro foi adicionado à loja quando a loja a suporta.
  • ttl_days int | None – Atualização de expiração opcional em dias. Omita esse argumento junto com ttl_anchor para preservar o timestamp de expiração atual. Informe None para limpar a expiração.
  • ttl_anchor TimeToLiveAnchor – Âncora opcional de tempo de vida útil para uma atualização de expiração. Use TimeToLiveAnchor.CREATED_AT para o horário de criação do registro ou TimeToLiveAnchor.TIMESTAMP para o timestamp de substituição fornecido na mesma atualização ou o timestamp de evento armazenado quando timestamp for omitido. O fornecimento de ttl_anchor sem ttl_days usa a duração de tempo de vida padrão do armazenamento ou esquema. Quando o ttl_anchor é omitido durante uma atualização, as implementações usam TimeToLiveAnchor.CREATED_AT.
  • status RecordStatus – Status do ciclo de vida de substituição opcional para registros. Omita-o para preservar o status atual.

  • texto str | None –

    Alias obsoleto para content. Informe None para limpar explicitamente o texto armazenado quando o armazenamento o suportar. Não forneça isso junto com content.

    Obsoleto

    Obsoleto desde a versão 26.8.0: Este parâmetro foi preterido na versão 26.8.0 e será removido na versão 27.1. Em vez disso, use content.

• Retorna: Número de registros atualizados (0 ou 1). O valor de retorno 0 significa que nenhum registro foi atualizado.
• Tipo de retorno: int
• Eleva: ValueError – Se o payload de atualização for inválido para o armazenamento, como omitir todos os campos opcionais ou fornecer argumentos semânticos conflitantes.

method update_relations (abstract)

Atualizar valores mutáveis nas relações armazenadas.

Os campos omitidos permanecem inalterados, exceto que a alteração para um tipo de relação de memória incorporado substitui seu rótulo reverso pelo inverso fixo. Um armazenamento de memória suportado pelo BD também recalcula os estados do ciclo de vida do ponto final após uma alteração do tipo de relação.

• Parâmetros:
  • relation_ids str | list[str] – Identificador ou identificadores das relações a serem atualizadas.
  • relation_types str | list[str] – Rótulo ou rótulos de relação direcionada de substituição opcional. Omita isso para preservar os rótulos armazenados.
  • opposite_relation_types str | list[str] – Rótulo ou rótulos de relação reversa de substituição opcional. Informe um label para substituí-lo ou omita esse argumento para preservá-lo.
  • timestamps str | None | list[str | None] – Carimbo de data/hora de substituição opcional ou carimbos de data/hora. Informe None para limpar um timestamp armazenado.
  • metadados dict[str, Any] | None | list[dict[str, Any] | None] – Objeto ou objetos de metadados de substituição opcionais. Os metadados fornecidos substituem o objeto armazenado; ele não é mesclado.
• Retorna: Identificadores de relações que foram atualizadas.
• Tipo de retorno: list[str]

Exemplos

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

método update_relations_async (assíncrono)

Atualizar assincronamente valores mutáveis em relações armazenadas.

Os campos omitidos permanecem inalterados, exceto que a alteração para um tipo de relação de memória incorporado substitui seu rótulo reverso pelo inverso fixo. Um armazenamento de memória suportado pelo BD também recalcula os estados do ciclo de vida do ponto final após uma alteração do tipo de relação.

• Parâmetros:
  • relation_ids str | list[str] – Identificador ou identificadores das relações a serem atualizadas.
  • relation_types str | list[str] – Rótulo ou rótulos de relação direcionada de substituição opcional. Omita isso para preservar os rótulos armazenados.
  • opposite_relation_types str | list[str] – Rótulo ou rótulos de relação reversa de substituição opcional. Informe um label para substituí-lo ou omita esse argumento para preservá-lo.
  • timestamps str | None | list[str | None] – Carimbo de data/hora de substituição opcional ou carimbos de data/hora. Informe None para limpar um timestamp armazenado.
  • metadados dict[str, Any] | None | list[dict[str, Any] | None] – Objeto ou objetos de metadados de substituição opcionais. Os metadados fornecidos substituem o objeto armazenado; ele não é mesclado.
• Retorna: Identificadores de relações que foram atualizadas.
• Tipo de retorno: list[str]

Exemplos

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

Armazenamento do Oracle DB

classe oracleagentmemory.core.OracleDBMemoryStore

Bases: OracleMemoryStore

Persistência baseada em banco de dados para mensagens, documentos, memórias e perfis de atores.

Crie um armazenamento do Oracle DB.

• Parâmetros:
  • embedder IEmbedder | None – Embedder usado quando o armazenamento precisa de incorporações vetoriais locais. Pode ser None quando os chamadores sempre fornecem vetores pré-calculados ou quando a pesquisa de palavra-chave é usada com gravações somente texto e consultas de texto. SearchStrategy.HYBRID requer uma OracleDBEmbedder aqui para que o índice híbrido gerenciado possa usar o modelo no banco de dados desse incorporador.
  • pool Any – Conexão ou pool do Oracle DB. A transmissão de uma conexão bruta ativa o modo de sessão única para esta instância de armazenamento: as chamadas de armazenamento simultâneas são serializadas localmente para preservar as suposições de bloqueio de linha e transação usadas pelas operações de gravação. Use um pool de conexões para solicitações simultâneas.
  • schema_policy SchemaPolicy | str – Controla como o esquema gerenciado é aberto ou preparado. O padrão é exigir um esquema existente e atualizado e não faz alterações em DDL. Para um armazenamento identificado por memory_store_id, o SchemaPolicy.CREATE_IF_NECESSARY cria ou repara o esquema quando necessário; o SchemaPolicy.RECREATE o elimina e o recria. Versões de esquema mais antigas exigem um upgrade de esquema de pacote para que possam ser reparadas. Quando schema_owner estiver definido, use SchemaPolicy.REQUIRE_EXISTING para acesso comum entre esquemas ou SchemaPolicy.NO_CHECK para acesso ao runtime do Deep Data Security. Ambos impedem a DDL do esquema gerenciado, incluindo criação, reparo, recriação e primeira criação de índice híbrido; execute essas ações enquanto estiver conectado como o usuário do banco de dados proprietário sem schema_owner. Nenhum dos modos torna o armazenamento somente leitura: leituras e gravações normais de memória usam a autorização efetiva do banco de dados do usuário da conexão. Para acesso ao runtime do Deep Data Security, use SchemaPolicy.NO_CHECK e crie o armazenamento enquanto um OracleMemoryEndUserSecurityContext estiver ativo. O armazenamento resultante requer um contexto de usuário final ativo para cada operação posterior do banco de dados. Políticas de esquema diferentes de NO_CHECK rejeitam contextos de usuário final ativos para que o trabalho do ciclo de vida do esquema não possa ser executado acidentalmente como usuário final.
  • vector_dim int | None – Dimensão de incorporação opcional para armazenamento vetorial local. Informe um número inteiro positivo para criar a coluna de incorporação gerenciada e o índice de vetores e para validar os metadados de esquema existentes em relação a essa dimensão. Informe None ou omita o argumento quando este armazenamento não precisar de armazenamento vetorial local. A palavra-chave e a pesquisa híbrida podem operar a partir do texto de pesquisa armazenado sem a coluna de incorporação local. A pesquisa de vetores requer armazenamento de vetores local. Quando esse argumento é omitido e o backend de pesquisa efetiva é a pesquisa vetorial, o armazenamento usa embedder.embedding_dimension quando um incorporador está disponível.

  • table_name_prefix str –

    Prefixo opcional adicionado aos nomes de tabela/índice gerenciados. Informe este ou memory_store_id, não ambos.

    Obsoleto

    Obsoleto desde a versão 26.6.0: Este parâmetro foi preterido na versão 26.6.0 e será removido na versão 27.1. Em vez disso, use memory_store_id.

  • memory_store_id str – ID estável para o armazenamento de memória do BD gerenciado. Reutilize o mesmo ID para reabrir o mesmo armazenamento gerenciado. O ID é unido aos nomes de objeto do BD gerenciado com um sublinhado, portanto, ele deve começar com uma letra, conter apenas letras, números e sublinhados e ter no máximo 16 caracteres. Informe este ou table_name_prefix, não ambos. Se omitido, o armazenamento usa table_name_prefix ou o padrão não fixo quando table_name_prefix também é omitido. Criar, reparar ou recriar um armazenamento no esquema do usuário de conexão requer um pacote DBMS_AGENT_MEMORY_STORE compatível nesse esquema.
  • schema_owner str – Proprietário do esquema opcional para um armazenamento de memória gerenciado existente. Omita esta opção para usar o esquema do usuário de conexão. O argumento pool pode ser uma conexão de banco de dados bruta ou um pool de conexões; use essa opção quando ela pertencer a um usuário de banco de dados de aplicativo que tenha concessões em tabelas pertencentes a outro usuário. Esta opção é apenas para acesso de runtime a um armazenamento de memória gerenciado já criado. Use SchemaPolicy.REQUIRE_EXISTING para acesso comum entre esquemas ou SchemaPolicy.NO_CHECK com um contexto de segurança de usuário final ativo para um armazenamento protegido pelo Deep Data Security. Crie, faça upgrade ou recrie o armazenamento de memória gerenciado enquanto estiver conectado como proprietário do esquema e omita essa opção. Informe um identificador sem aspas; a entrada em minúsculas é normalizada para maiúsculas e os proprietários de esquema com distinção entre aspas não são suportados. Conceda CREATE SESSION e os privilégios de objeto necessários ao usuário do BD do aplicativo; consulte a seção Database Users and Privileges do guia de diagnóstico e solução de problemas para obter as concessões exatas. Como alternativa, exponha views de objeto gerenciado com o mesmo nome no esquema de runtime e omita schema_owner; isso só é suportado para SchemaPolicy.REQUIRE_EXISTING.
  • search_strategy SearchStrategy – valor SearchStrategy que seleciona o backend para search(). Use SearchStrategy.VECTOR (padrão) para recuperação somente vetorial, SearchStrategy.HYBRID para consultar um índice vetorial híbrido gerenciado da Oracle sobre o texto de pesquisa armazenado, ou SearchStrategy.KEYWORD para classificar por correspondência de palavra-chave/texto sobre o texto de pesquisa armazenado sem fusão vetorial. KEYWORD não requer um incorporador. HYBRID requer que embedder seja um OracleDBEmbedder para que o índice híbrido gerenciado use o mesmo modelo no banco de dados que o incorporador de armazenamento principal. Se um cliente de palavra-chave abrir um esquema híbrido existente, o armazenamento poderá usar a ramificação de texto desse índice híbrido. A inicialização falha quando uma estratégia incompatível é usada com um esquema existente porque esse esquema pode não conter o estado de pesquisa armazenado de que a estratégia precisa. Quando schema_policy=SchemaPolicy.REQUIRE_EXISTING e este argumento são omitidos, o melhor esforço de armazenamento detecta o modo de pesquisa armazenado do esquema a partir de metadados gerenciados e usa esse modo quando disponível.
  • search_index_sync SearchIndexSyncMode – Valor SearchIndexSyncMode que seleciona o comportamento de atualização de índice de pesquisa gerenciado para SearchStrategy.HYBRID e SearchStrategy.KEYWORD. SearchIndexSyncMode.ON_COMMIT é o padrão e torna os registros pesquisáveis assim que a transação de gravação é confirmada. SearchIndexSyncMode.MANUAL deixa a atualização para uma operação de sincronização explícita no banco de dados. O SearchIndexSyncMode.AUTO permite que o sistema Oracle atualize o índice híbrido gerenciado de forma assíncrona e só é suportado com SearchStrategy.HYBRID; a pesquisa por palavra-chave rejeita AUTO.
  • memory_retention_config MemoryRetentionConfig – Configuração de retenção de memória opcional para mensagens e memórias apoiadas por BD. MemoryRetentionConfig.default_ttl_days é usado quando uma nova gravação omite ttl_days. MemoryRetentionConfig.max_ttl_days grampeia durações explícitas por registro acima do máximo configurado com um aviso e, quando definido, faz com que ttl_days=None use esse máximo em vez de criar linhas sem expiração. Com SchemaPolicy.CREATE_IF_NECESSARY, uma configuração explícita atualiza os metadados armazenados em um esquema gerenciado atualizado existente, mas não atualiza as datas de expiração existentes; a omissão mantém a definição existente. Se uma configuração explícita deixar default_ttl_days ou max_ttl_days em NOT_SET_MARKER, o SDK resolverá esse atributo com seu valor padrão (None) antes de comparar ou armazenar metadados de esquema. Escolha essa configuração com base nas informações esperadas armazenadas em registros, por que o aplicativo a retém e quaisquer compromissos de retenção de aplicativos ou regulatórios.
• Gera: RuntimeError – Se um contexto de segurança de usuário final estiver ativo com uma política de esquema diferente de SchemaPolicy.NO_CHECK ou se um armazenamento de runtime NO_CHECK for aberto ou usado sem um contexto de segurança de usuário final ativo.

Aviso: SchemaPolicy.CREATE_IF_NECESSARY pode ser mais caro do que a inicialização normal do armazenamento porque pode reparar objetos de esquema gerenciados antes que a inicialização seja bem-sucedida. Planeje o trabalho de reparo como uma operação de manutenção quando um esquema pode conter muitas linhas. Um armazenamento em uma versão de esquema mais antiga requer um upgrade de esquema de pacote antes da inicialização.

Se a configuração do esquema precisar criar o job de expurgação de registro expirado gerenciado, mas o usuário do banco de dados não tiver o privilégio scheduler-job, a inicialização avisará e continuará. As mensagens e memórias expiradas permanecem ocultas de leituras e pesquisas, mas elas não são expurgadas fisicamente até que o job seja criado por um usuário com o privilégio CREATE JOB ou um scheduler equivalente.

Quando o SchemaPolicy.CREATE_IF_NECESSARY cria pela primeira vez um índice híbrido gerenciado em um esquema existente, o sistema Oracle verifica o texto de pesquisa armazenado e cria o estado de índice híbrido gerenciado com base no modelo configurado no banco de dados. Como a inicialização do armazenamento aguarda a conclusão desse DDL, planeje o primeiro upgrade híbrido como uma operação de migração ou manutenção para grandes esquemas. SearchIndexSyncMode controla a manutenção contínua após a existência do índice; ele não torna a primeira criação de índice assíncrona.

A criação desse índice híbrido gerenciado também cria uma preferência do vetorizador DBMS_VECTOR_CHAIN nomeada pelo esquema gerenciado. A preferência armazena metadados de configuração do vetorizador leves do modelo OracleDBEmbedder configurado. Ele pode ser inspecionado com as exibições de preferência do Oracle Text, como CTX_USER_PREFERENCES e CTX_USER_PREFERENCE_VALUES.

método add

Adicione registros ao armazenamento do Oracle DB.

• Parâmetros:
  • contents Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None] – Sequência somente leitura de payloads de registro. As entradas de mensagem podem conter peças MessageContent solicitadas. As entradas de resumo de thread podem ser mapeamentos, strings que se tornam objetos {"text": value} ou None armazenados como JSON null. Valores de texto também são usados para pesquisa, a menos que index_texts seja fornecido. Para outros tipos de registro, None pode retroceder para metadata["content"]. Strings vazias explícitas são preservadas.
  • record_type str – Tipo de registro lógico a ser criado (como "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" ou "thread_summary").
  • index_texts list[str | list[str] | None] – Cargas úteis alternativas opcionais usadas como texto de pesquisa. Use esta opção para controlar qual palavra-chave ou índices de pesquisa híbridos apoiados pelo BD. Cada entrada da lista externa se alinha a um registro. Uma entrada de string pode ser dividida pela loja. Uma entrada de lista é tratada como partes de propriedade do chamador e gravada como está em RECORD_CHUNKS.chunk_text. Quando embeddings também é fornecido, as entradas de lista exigem exatamente um vetor por bloco; as entradas de string aceitam apenas um único vetor para esse registro.

  • incorporações list[list[float] | ndarray | list[list[float] | ndarray]] –

    Vetores de incorporação pré-computados opcionais alinhados com contents. Cada entrada de registro pode ser um vetor ou uma lista de vetores de chunk. Quando o armazenamento vetorial local é configurado, esses vetores são armazenados diretamente como a representação vetorial do registro, em vez de chamar o incorporador da loja para criar vetores locais para a gravação. Um único vetor representa todo o texto semântico, mesmo quando o chunker configurado o dividiria. Vários vetores de chunk exigem listas de chunk index_texts correspondentes.

    No SearchStrategy.VECTOR, a pesquisa vetorial é classificada em relação aos vetores armazenados. Em SearchStrategy.HYBRID ou SearchStrategy.KEYWORD, a pesquisa suportada pelo BD é classificada por meio do texto de pesquisa armazenado e do texto gerenciado pela Oracle ou do estado do índice híbrido. Portanto, as incorporações de tempo de adição afetam apenas qualquer armazenamento vetorial local configurado, não essa estratégia de pesquisa ativa. Se esse armazenamento tiver sido configurado sem armazenamento vetorial local, forneça index_texts em vez de embeddings para substituir o texto visível para esses índices com reconhecimento de texto.

  • record_ids str | None | list[str | None] – Identificadores opcionais visíveis para chamadores. Uma única string pode ser usada para inserções de um registro, enquanto as listas devem se alinhar a contents. Os identificadores gerados são retornados quando este campo é omitido.
  • thread_ids str | None | list[str | None] – Identificadores de thread opcionais associados aos registros inseridos. Os valores escalares podem ser transmitidos entre entradas alinhadas.
  • user_ids str | None | list[str | None] – Identificadores de usuário opcionais associados aos registros inseridos. Os valores escalares podem ser transmitidos entre entradas alinhadas. Quando omitido em um armazenamento de runtime SchemaPolicy.NO_CHECK, o armazenamento usa o nome de usuário do contexto de segurança do usuário final ativo. Informe None explicitamente para preservar um ID de usuário sem escopo.
  • agent_ids str | None | list[str | None] – Identificadores de agente opcionais associados aos registros inseridos. Os valores escalares podem ser transmitidos entre entradas alinhadas.
  • roles str | None | list[str | None] – Funções de mensagem opcionais como "user" ou "assistant". Usado somente quando record_type é "message".
  • timestamps – str | None | list[str | None] – Carimbos de data/hora opcionais a serem salvos com os registros. Cada timestamp representa quando o registro foi criado. Os valores escalares podem ser transmitidos entre entradas alinhadas. As entradas Omitidas ou None deixam o timestamp do evento sem definição. Quando ttl_anchor é TimeToLiveAnchor.TIMESTAMP, todos os registros afetados devem ter um valor de timestamp ISO-8601 concreto. Os timestamps ISO-8601 sem fuso horário são tratados como UTC.
  • metadados dict[str, Any] | None | list[dict[str, Any] | None] – Dicionários de metadados opcionais. Os metadados podem incluir "content" como origem de fallback quando um valor de texto é omitido em vez de definido como "". As gravações de imagem exigem "image_mime_type" com "image/png", "image/jpeg" ou "image/webp". O armazenamento usa esse campo para salvar a imagem, mas não a retorna como parte dos metadados do registro.
  • ttl_days int | None | list[int | None] – Duração opcional do tempo de vida útil em dias para registros de mensagem e memória. Omita esse argumento para usar MemoryRetentionConfig.default_ttl_days do esquema gerenciado. Informe None para usar MemoryRetentionConfig.max_ttl_days quando a configuração de retenção definir uma, ou para criar um registro que não esteja expirando quando não o fizer. Os valores acima de MemoryRetentionConfig.max_ttl_days são limitados a esse máximo com uma advertência. Os valores escalares podem ser transmitidos entre entradas alinhadas.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor] – Âncora de tempo de vida opcional. Use TimeToLiveAnchor.CREATED_AT para expirar em relação ao horário de criação do banco de dados ou TimeToLiveAnchor.TIMESTAMP para expirar em relação ao timestamp de evento fornecido. Quando omitido, a expiração usa TimeToLiveAnchor.CREATED_AT. A expiração ancorada no timestamp requer um timestamp ISO-8601 concreto para cada registro inserido. Os timestamps ISO-8601 sem fuso horário são tratados como UTC.
  • statuses RecordStatus | list[RecordStatus] – Status de ciclo de vida opcional para registros que o suportam. Forneça um valor RecordStatus para aplicá-lo a cada registro de entrada ou uma lista de status alinhados com contents. Omita este argumento para usar RecordStatus.VALID.
  • **store_kwargs (Qualquer) – Opções de gravação do BD. batch_size controla o tamanho do batch executemany e assume como padrão 256.
• Retorna: Identificadores para registros inseridos, na mesma ordem lógica da entrada.
• Tipo de retorno: list[str]

Exemplos

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

Adicionar um registro de perfil do agente.

• Parâmetros:
  • agent_id str – Identificador do agente.
  • informações str – Informações de formato livre sobre o agente. Esse texto é armazenado como conteúdo do perfil e usado para criar a representação pesquisável do perfil.
  • metadados dict[str, Any] | None – Mapeamento de metadados opcional armazenado na linha de perfil do agente.
• Devoluções: Identificador do registro de perfil do agente inserido.
• Tipo de retorno: str

Observações

Os registros de perfil do agente não têm escopo. O identificador de registro público inserido é o mesmo valor informado como agent_id.

Exemplos

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

método add_agent_async (assíncrono)

Adicionar de forma assíncrona um registro de perfil de agente.

• Parâmetros:
  • agent_id str – Identificador estável para o perfil do agente.
  • informação str – Texto de formato livre descrevendo o agente.
  • metadados dict[str, Any] | None – Mapeamento de metadados opcional armazenado na linha de perfil do agente.
• Devoluções: Identificador do registro de perfil do agente criado.
• Tipo de retorno: str

método add_async (assíncrono)

Adicione registros orientados por linha de forma assíncrona à loja.

Aceita os mesmos argumentos e retorna os mesmos identificadores que add().

• Parâmetros:
  • conteúdo Sequence[str | Mapping[str, object] | Sequence[MessageContent] | bytes | None]
  • tipo_registro str
  • index_texts list[str | list[str] | None]
  • incorporações 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]
  • funções str | None | list[str | None]
  • timestamps (str | None | list[str | None])
  • metadados dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • status RecordStatus | list[RecordStatus]
  • store_kwargs Any
• Tipo de retorno: list[str]

método add_batches

Adicione lotes lógicos preparados pelo chamador à loja.

• Parâmetros:
  • batches list[PendingRecordBatch] – Lotes lógicos totalmente preparados para persistir. Cada batch deve ter seus próprios campos por registro, como record_type, valores de escopo, atribuições, timestamps e metadados.
  • **store_kwargs (Qualquer) – Opções de gravação específicas para implementação encaminhadas para o armazenamento concreto.
• Retorna: Identificadores para os registros inseridos, na mesma ordem lógica que os lotes e linhas de entrada.
• Tipo de retorno: List[str]

Exemplos

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

método add_batches_async (assíncrono)

Adicione lotes lógicos preparados pelo chamador de forma assíncrona ao armazenamento.

Aceita os mesmos argumentos e retorna os mesmos identificadores que add_batches().

• Parâmetros:
  • lotes list[PendingRecordBatch]
  • store_kwargs Any
• Tipo de retorno: list[str]

método add_relations

Armazene uma ou mais relações memória-para-memória atomicamente.

Os valores escalares são transmitidos no batch de ID de origem; as listas devem ser alinhadas. Somente uma orientação de relação pode ser armazenada para um par de pontos finais. Os labels de link de memória incorporados recebem seu label reverso fixo, e os labels de ciclo de vida atualizam o estado do ponto final na mesma transação.

• Parâmetros:
  • source_record_ids str | list[str] – Identificadores de memória de origem, como uma lista escalar ou alinhada.
  • source_record_types str | list[str] – Tipos semelhantes a memória para os registros de origem.
  • target_record_ids str | list[str] – Identificadores de memória de destino, como uma lista escalar ou alinhada.
  • target_record_types str | list[str] – Tipos semelhantes a memória para os registros de destino.
  • relation_types str | list[str] – Rótulos de relação direcionados.
  • opposite_relation_types str | list[str] – Rótulos reversos opcionais para tipos de relação personalizada. Isto descreve a visão inversa da relação armazenada; não cria uma segunda relação na direção inversa.
  • relation_ids str | None | list[str | None] – Identificadores de relação estáveis opcionais. Omita para gerar identificadores.
  • timestamps – str | None | list[str | None] – Carimbos de data/hora opcionais armazenados com as relações.
  • metadados dict[str, Any] | None | list[dict[str, Any] | None] – Metadados opcionais armazenados com as relações.
• Retorna: Identificadores de relação criados na ordem de entrada.
• Tipo de retorno: list[str]

Exemplos

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

método add_relations_async (assíncrono)

Armazenar assincronamente uma ou mais relações direcionadas.

Os valores escalares são transmitidos pelo lote de registro de origem. Os valores de lista devem ter o mesmo tamanho. Somente uma orientação pode ser armazenada para um par de pontos finais. Use opposite_relation_types para descrever a view reversa em vez de adicionar uma segunda relação reversa.

• Parâmetros:
  • source_record_ids str | list[str] – Identificador ou identificadores de registros na extremidade de origem de cada relação direcionada.
  • source_record_types str | list[str] – Tipo ou tipos de registro para source_record_ids. Forneça um valor para todas as origens ou um valor para cada relação.
  • target_record_ids str | list[str] – Identificador ou identificadores de registros na extremidade de destino de cada relação direcionada.
  • target_record_types str | list[str] – Tipo ou tipos de registro para target_record_ids. Forneça um valor para todos os alvos ou um valor para cada relação.
  • relation_types str | list[str] – Rótulo ou rótulos de relação direcionados. Forneça um valor para todas as relações ou um valor para cada relação.
  • opposite_relation_types str | list[str] – Label ou labels opcionais para a view reversa de cada relação. Para tipos de relação de memória incorporados, a omissão usa o rótulo reverso predefinido. Para tipos de relação personalizados, a omissão usa o mesmo rótulo em ambas as direções.
  • relation_ids str | None | list[str | None] – Identificador ou identificadores estáveis opcionais. Omita isso para permitir que o armazenamento gere identificadores.
  • timestamps (str | None | list[str | None]) – Timestamp ou timestamps opcionais para armazenar nas relações.
  • metadados dict[str, Any] | None | list[dict[str, Any] | None] – Objetos ou objetos de metadados opcionais a serem armazenados nas relações.
• Retorna: Identificadores de relação na ordem de entrada.
• Tipo de retorno: list[str]

Exemplos

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

método add_user

Adicionar um registro de perfil de usuário.

• Parâmetros:
  • user_id str – Identificador do usuário. Quando omitido em um armazenamento de runtime SchemaPolicy.NO_CHECK, o armazenamento usa o nome de usuário do contexto de segurança do usuário final ativo. Caso contrário, forneça esse argumento explicitamente.
  • informações str – Informações de formato livre necessárias sobre o usuário. Esse texto é armazenado como conteúdo do perfil e usado para criar a representação pesquisável do perfil.
  • metadados dict[str, Any] | None – Mapeamento de metadados opcional armazenado na linha do perfil do usuário.
• Devoluções: Identificador do registro de perfil de usuário inserido.
• Tipo de retorno: str

Observações

Os registros de perfil do usuário não têm escopo. O identificador de registro público inserido é o user_id explícito ou inferido.

Exemplos

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

método add_user_async (assíncrono)

Adicionar de forma assíncrona um registro de perfil de usuário.

• Parâmetros:
  • user_id str – Identificador estável para o perfil do usuário.
  • information str – Texto de formato livre descrevendo o usuário.
  • metadados dict[str, Any] | None – Mapeamento de metadados opcional armazenado na linha do perfil do usuário.
• Devoluções: Identificador do registro de perfil do usuário criado.
• Tipo de retorno: str

método delete

Excluir uma linha gerenciada e suas linhas de bloco por identificador.

• Parâmetros:
  • record_type str – Rótulo de tipo de registro a ser excluído. Os tipos suportados incluem "thread", "message", "memory", "guideline", "fact", "preference", "user_profile" e "agent_profile", e "thread_summary".
  • record_id str – Identificador a excluir.
  • cascade bool – Quando True, expanda os destinos de nível superior suportados, como perfis de ator, em suas linhas filho com escopo dentro da mesma transação. Para um destino user-profile ou agent-profile, isso exclui primeiro as linhas de thread pertencentes, que removem suas linhas de mensagem com escopo de thread e de tabela de memória e, em seguida, exclui todas as mensagens com escopo de ator diretamente restantes e linhas semelhantes à memória (memory, guideline, fact, preference). Essa limpeza com escopo ainda é executada quando a linha do perfil correspondente já está ausente.
• Retorna: Número de destinos de nível superior solicitados removidos, geralmente 0 ou 1. As linhas filho em cascata não são contadas separadamente, portanto, ainda pode ser 0 quando um perfil de ator ausente aciona a limpeza com escopo.
• Tipo de retorno: int

Observações

A operação é executada dentro de uma transação. Quando cascade está ativado para um destino de nível superior suportado, a exclusão do perfil e todas as exclusões filho com escopo são submetidas a commit ou submetidas a rollback juntas.

Exemplos

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

método delete_async (assíncrono)

Exclua de forma assíncrona um registro armazenado por identificador.

• Parâmetros:
  • record_type str – Tipo lógico do registro a ser removido.
  • record_id str – Identificador do registro a ser removido.
  • cascade bool – Quando True, aplique qualquer comportamento de exclusão em cascata suportado pelo armazenamento para os destinos de nível superior solicitados dentro da mesma operação de exclusão. Isso é usado principalmente para alvos como perfis de ator que possuem registros com escopo adicional. Por exemplo, uma cascata de perfil de usuário ou perfil de agente pode excluir threads próprios, as mensagens de escopo de thread e registros semelhantes a memória removidos com esses threads e quaisquer registros de escopo de ator diretamente restantes, como mensagens, memórias, diretrizes, fatos ou preferências. Para exclusões de ator-perfil, essa limpeza com escopo ainda poderá ser executada quando a linha do perfil correspondente já estiver ausente.
• Retorna: Número de registros de nível superior solicitados excluídos, geralmente 0 ou 1. As linhas filho em cascata não são contadas separadamente, portanto, ainda pode ser 0 quando um perfil de ator ausente aciona a limpeza com escopo.
• Tipo de retorno: int

método delete_relations

Exclua relações por identificador e recalcule o estado do ciclo de vida.

• Parâmetros: relation_ids str | list[str] – Identificador ou identificadores das relações a serem excluídas.
• Retorna: Número de relações excluídas.
• Tipo de retorno: int

Exemplos

store.delete_relations("relation-id")
1

método delete_relations_async (assíncrono)

Exclua relações de forma assíncrona por identificador.

O estado do ciclo de vida é recalculado a partir das relações que permanecem.

• Parâmetros: relation_ids str | list[str] – Identificador ou identificadores das relações a serem excluídas.
• Retorna: Número de relações excluídas.
• Tipo de retorno: int

Exemplos

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

método delete_thread

Excluir um thread e suas linhas armazenadas associadas.

• Parâmetros: thread_id str – Identificador do thread cujas linhas devem ser removidas, incluindo a linha do thread, as linhas filho dependentes e a limpeza explícita da linha de bloco.
• Retorna: Número de linhas de thread excluídas (0 ou 1).
• Tipo de retorno: int

Observações

Use esta operação quando precisar de limpeza em cascata com escopo de thread. No armazenamento suportado pelo BD, a exclusão do thread remove a linha do thread gerenciado juntamente com as linhas de mensagem e memória associadas, além dos dados de pesquisa mantidos para recuperação. Isso é mais amplo do que uma exclusão no nível da mensagem, o que remove apenas a linha da mensagem bruta. A exclusão do thread remove as linhas dependentes de mensagem e memória junto com seus dados de recuperação associados na mesma transação.

Exemplos

store.delete_thread("c1")
0

método delete_thread_async (assíncrono)

Exclua de forma assíncrona um thread e seus dados armazenados associados.

• Parâmetros: thread_id str – Identificador do thread a ser removido.
• Retorna: Número de registros de thread excluídos, geralmente 0 ou 1.
• Tipo de retorno: int

Observações

Esta é a operação no nível do armazenamento para remover um thread e os registros no escopo do thread gerenciados pelo armazenamento. Prefira a exclusão de thread quando os requisitos de retenção exigirem a exclusão de mensagens de origem e de dados de memória com escopo de thread derivado, porque as exclusões no nível da mensagem não implicam que registros derivados persistidos separadamente sejam removidos.

método get

Recuperar um registro armazenado por identificador.

• Parâmetros:
  • record_type str – Rótulo de tipo de registro resolvendo para uma linha gerenciada, como "message", "memory", "guideline", "fact", "preference", "thread", "user_profile", "agent_profile" ou "thread_summary".
  • record_id str – Identificador a ser pesquisado.
  • include_bytes bool – Se deseja carregar bytes de imagem para registros de imagem ou imagens anexadas em registros de mensagens. O padrão é False.
• Retorna: Registro preenchido com metadados decodificados quando encontrado; caso contrário, None.
• Tipo de retorno: Registro | Nenhum

Exemplos

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'

método get_async (assíncrono)

Recuperar assincronicamente um registro armazenado por tipo e identificador.

• Parâmetros:
  • record_type str – Tipo lógico do registro a ser recuperado, como "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" ou "image".
  • record_id str – Identificador do registro a ser recuperado.
  • include_bytes bool – Se deseja carregar bytes de imagem armazenados. Para um registro de mensagem, isso controla se as imagens anexadas incluem seus bytes. Para um registro de imagem, ele controla se os bytes de imagem standalone são carregados. Esta opção não tem efeito em outros tipos de registro.
• Retorna: O registro armazenado quando encontrado, caso contrário, None. Uma pesquisa "thread" retorna um ThreadRecord com metadados de thread, configuração de runtime, estado de runtime e o timestamp de criação preenchido quando o armazenamento suporta threads persistidos.
• Tipo de retorno: Registro | Nenhum

método get_relation

Retorna uma relação identificada por ID ou tupla de ponto final completa.

Forneça apenas relation_id ou uma tupla completa de ponto final de origem para destino.

• Parâmetros:
  • source_record_id str – Identificador do registro de origem. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • source_record_type str – Tipo de registro de origem. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • target_record_id str – Identificador de registro de destino. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • target_record_type str – Tipo de registro de destino. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • relation_type str – Rótulo de relação direcionada. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • relation_id str – O identificador de relação corresponde diretamente. Forneça esse argumento sozinho em vez de combiná-lo com campos de tupla de ponto final.
• Retorna: A relação armazenada correspondente, ou None quando ela não existe.
• Tipo de retorno: RecordRelation | Nenhum

Exemplos

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

método get_relation_async (assíncrono)

Recupera assincronicamente uma relação por tupla de ID ou ponto final.

Forneça apenas relation_id ou uma tupla completa de ponto final de origem para destino.

• Parâmetros:
  • source_record_id str – Identificador do registro de origem. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • source_record_type str – Tipo de registro de origem. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • target_record_id str – Identificador de registro de destino. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • target_record_type str – Tipo de registro de destino. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • relation_type str – Rótulo de relação direcionada. Obrigatório com os outros campos de tupla de ponto final quando relation_id é omitido.
  • relation_id str – O identificador de relação corresponde diretamente. Forneça esse argumento sozinho em vez de combiná-lo com campos de tupla de ponto final.
• Retorna: A relação de correspondência ou None quando ela não existe.
• Tipo de retorno: RecordRelation | Nenhum

Exemplos

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

método list

Enumerar registros persistidos para um tipo de registro.

• Parâmetros:
  • record_type str – Rótulo de tipo de registro (por exemplo, "thread", "message", "memory", "guideline", "fact", "preference", "thread", "user_profile" ou "agent_profile").
  • limit int | None – Número máximo opcional de registros a serem retornados. Quando omitido, o armazenamento usa seu limite de listagem padrão. Passe None para desativar esse limite e retornar todos os registros correspondentes.
  • thread_id str | None – Filtro de escopo de thread exato. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente as linhas cujo thread_id é SQL NULL são retornadas. Os tipos de registro sem escopo ignoram este filtro. Quando record_type for "thread", thread_id não deverá ser definido; use record_id para selecionar um thread específico.
  • user_id str | None – Filtro de escopo de usuário exato. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente as linhas cujo user_id é SQL NULL são retornadas. Os tipos de registro sem escopo ignoram este filtro.
  • agent_id str | None – Filtro exato de escopo do agente. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente as linhas cujo agent_id é SQL NULL são retornadas. Os tipos de registro sem escopo ignoram este filtro.

  • metadata_filter dict[str, Any] | None –

    Filtro de metadados Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros sem metadados armazenados são retornados. Quando definidas como um ditado, as entradas em metadata_filter são combinadas com a semântica AND. Entradas cujo valor não é um dicionário de operador de nível de campo usam semântica de correspondência exata: a chave solicitada deve existir nos metadados armazenados. Os dicionários aninhados são correspondidos recursivamente. Os valores escalares e de lista são correspondidos por igualdade exata; a ordem e o comprimento da lista também devem ser correspondentes. Para testar a associação de array, use um dicionário do operador no nível do campo, como {"tags": {"$array_contains": "prod"}}. Um operando de lista para "$array_contains" significa que todos os valores listados devem estar presentes; "$array_contains_any" significa que pelo menos um valor listado deve estar presente. Use "$not" para negar outra expressão no nível do campo no mesmo campo, incluindo um dicionário do operador ou valor de correspondência exata bruta. As expressões negativas correspondem quando a expressão positiva falharia, incluindo campos ausentes; a associação de matriz negada também corresponde a campos que não são de matriz. Os exemplos incluem metadata_filter={"source": "slack"} para um campo escalar, metadata_filter={"review": {"status": "open"}} para um campo aninhado e metadata_filter={"tags": ["prod", "urgent"]} para uma correspondência de lista exata. Combine condições para exigir todas elas:

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

  • include_bytes bool – Se os registros de imagem ou imagens anexados a registros de mensagem incluem bytes armazenados. O padrão é False. As listagens diretas de imagem exigem um record_id e pelo menos um filtro exato de escopo de usuário, agente ou thread quando esse for True.
  • record_id str – Filtro exato de identificador de registro. Quando omitido, os registros com qualquer identificador são retornados. Os filtros de escopo e metadados permanecem restrições adicionais.
• Devoluções: Registros ordenados por ordem de inserção.
• Tipo de retorno: list[Registro]

Observações

"user_profile" e "agent_profile" são tipos de registro sem escopo. Para esses tipos de registro, thread_id, user_id e agent_id são ignorados e a identidade do ator permanece em record.id. Os registros "thread" expõem o identificador de thread como record.id e record.thread_id.

Exemplos

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

método list_async (assíncrono)

Listar registros armazenados de forma assíncrona para um tipo de registro.

• Parâmetros:
  • record_type str – Tipo de registro lógico a ser enumerado, como "thread", "message", "memory", "guideline", "fact", "preference", "user_profile", "agent_profile" ou "image".
  • limit int | None – Número máximo opcional de registros mais recentes a serem retornados. Quando omitidas, as implementações podem aplicar um limite superior seguro, como MAX_LIST_LIMIT. Passe None para desativar esse limite e retornar todos os registros correspondentes.
  • thread_id str | None – Filtro de escopo de thread exato. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros cujo thread_id é None são retornados. Os tipos de registro sem escopo ignoram este filtro. Quando record_type for "thread", thread_id não deverá ser definido; use record_id para selecionar um thread específico.
  • user_id str | None – Filtro de escopo de usuário exato. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros cujo user_id é None são retornados. Os tipos de registro sem escopo ignoram este filtro.
  • agent_id str | None – Filtro exato de escopo do agente. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros cujo agent_id é None são retornados. Os tipos de registro sem escopo ignoram este filtro.

  • metadata_filter dict[str, Any] | None –

    Filtro de metadados Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros cujos metadados são None são retornados. Quando definidas como um ditado, as entradas em metadata_filter são combinadas com a semântica AND. Entradas cujo valor não é um dicionário de operador de nível de campo usam semântica de correspondência exata: a chave solicitada deve existir nos metadados armazenados. Os dicionários aninhados são correspondidos recursivamente. Os valores escalares e de lista são correspondidos por igualdade exata; a ordem e o comprimento da lista também devem ser correspondentes. Para testar a associação de array, use um dicionário do operador no nível do campo, como {"tags": {"$array_contains": "prod"}}. Um operando de lista para "$array_contains" significa que todos os valores listados devem estar presentes; "$array_contains_any" significa que pelo menos um valor listado deve estar presente. Use "$not" para negar outra expressão no nível do campo no mesmo campo, incluindo um dicionário do operador ou valor de correspondência exata bruta. As expressões negativas correspondem quando a expressão positiva falharia, incluindo campos ausentes; a associação de matriz negada também corresponde a campos que não são de matriz. Os exemplos incluem metadata_filter={"source": "slack"} para um campo escalar, metadata_filter={"review": {"status": "open"}} para um campo aninhado e metadata_filter={"tags": ["prod", "urgent"]} para uma correspondência de lista exata. Combine condições para exigir todas elas:

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

  • include_bytes bool – Se os registros de imagem ou imagens anexados a registros de mensagem incluem bytes armazenados. Quando omitido ou False, as descrições de imagem e os metadados são retornados sem carregar bytes. Para listagens diretas de imagem, defina isso como True somente com um record_id exato e pelo menos um filtro exato de escopo de usuário, agente ou thread. Esta opção não tem efeito em outros tipos de registro.
  • record_id str – Filtro exato de identificador de registro. Quando omitido, os registros com qualquer identificador são retornados. Os filtros de escopo e metadados permanecem restrições adicionais.
• Devoluções: Registros ordenados do mais antigo para o mais recente na janela retornada.
• Tipo de retorno: List[Record]

método list_relations

Liste as relações em sua orientação de origem para destino.

• Parâmetros:
  • relation_type str – Rótulo de relação direcionada opcional para correspondência, como "supports" ou "supersedes". Omita para incluir todos os tipos de relação.
  • source_record_id str – Identificador de registro fonte opcional a ser correspondente.
  • source_record_type str – Tipo de registro de origem opcional a ser correspondente.
  • target_record_id str – Identificador de registro de destino opcional a ser correspondente.
  • target_record_type str – Tipo de registro de destino opcional a ser correspondente.
  • limit int | None – Número máximo opcional de relações criadas mais recentemente a serem retornadas. Quando omitido, o armazenamento usa MAX_LIST_LIMIT. Passe None para retornar todas as relações armazenadas correspondentes.
  • metadata_filter dict[str, Any] | None – Filtro de metadados. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente as relações cujos metadados são None são retornadas. Quando definidas como um ditado, as entradas são combinadas com a semântica AND. Os dicionários aninhados usam correspondência exata recursiva. Os valores escalares e de lista exigem igualdade exata; use {"tags": {"$array_contains": "prod"}} para corresponder à associação de array, "$array_contains_any" para corresponder a qualquer valor listado ou "$not" para negar outra expressão de campo.
  • relation_id str – Filtro exato de identificador de relação. Quando omitido, as relações com qualquer identificador são retornadas. Outros filtros permanecem restrições adicionais.
• Retorna: Relações ordenadas por hora de criação e identificador.
• Tipo de retorno: list[RecordRelation]

Exemplos

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

método list_relations_async (assíncrono)

Liste relações de forma assíncrona na orientação de origem para destino.

• Parâmetros:
  • relation_type str – Rótulo de relação direcionada opcional para correspondência, como "supports" ou "supersedes". Omita para incluir todos os tipos de relação.
  • source_record_id str – Identificador de registro fonte opcional a ser correspondente.
  • source_record_type str – Tipo de registro de origem opcional a ser correspondente.
  • target_record_id str – Identificador de registro de destino opcional a ser correspondente.
  • target_record_type str – Tipo de registro de destino opcional a ser correspondente.
  • limit int | None – Número máximo opcional de relações criadas mais recentemente a serem retornadas. Quando omitidas, as implementações podem aplicar um limite superior seguro, como MAX_LIST_LIMIT. Passe None para retornar todas as relações armazenadas correspondentes.
  • metadata_filter dict[str, Any] | None – Filtro de metadados. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente as relações cujos metadados são None são retornadas. Quando definidas como um ditado, as entradas são combinadas com a semântica AND. Os dicionários aninhados usam correspondência exata recursiva. Os valores escalares e de lista exigem igualdade exata; use {"tags": {"$array_contains": "prod"}} para corresponder à associação de array, "$array_contains_any" para corresponder a qualquer valor listado ou "$not" para negar outra expressão de campo.
  • relation_id str – Identificador de relação opcional para coincidir diretamente.
• Retorna: Relações ordenadas por hora de criação e identificador.
• Tipo de retorno: list[RecordRelation]

Exemplos

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

método list_thread_messages

Retornar mensagens persistidas para um tópico.

• Parâmetros:
  • thread_id str – Identificador do thread cujas mensagens devem ser retornadas.
  • last_n int | None – Número opcional de mensagens mais recentes a serem retornadas.
  • range_start_seq_no int | None – Limite opcional da sequência inferior inclusivo.
  • range_end_seq_no int | None – Limite de sequência superior exclusivo opcional.
  • include_bytes bool – Se as partes de imagens anexadas às mensagens retornadas incluem bytes armazenados. O padrão é False.
• Devoluções: Registros de mensagem ordenados por ordem de inserção.
• Tipo de retorno: list[MessageRecord]

Exemplos

store.list_thread_messages("c1")
[]

método list_thread_messages_async (assíncrono)

Liste de forma assíncrona o histórico de mensagens armazenado para um thread.

• Parâmetros:
  • thread_id str – Identificador do thread cujas mensagens devem ser retornadas.
  • last_n int | None – Número opcional de mensagens mais recentes a serem incluídas. Quando omitidas, todas as mensagens armazenadas para o thread são retornadas. Quando combinado com um intervalo de sequência, o limite se aplica dentro desse intervalo.
  • range_start_seq_no int | None – Limite opcional da sequência inferior inclusivo. Somente mensagens cujo seq_no seja pelo menos esse valor serão retornadas.
  • range_end_seq_no int | None – Limite de sequência superior exclusivo opcional. Somente mensagens cujo seq_no seja menor que esse valor serão retornadas.
  • include_bytes bool – Se as partes de imagens anexadas às mensagens retornadas incluem bytes armazenados. Quando omitido ou False, as descrições de imagem e os metadados são retornados sem carregar bytes.
• Devoluções: Registros de mensagens ordenados do mais antigo para o mais recente na janela retornada.
• Tipo de retorno: List[MessageRecord]

método search

Pesquisar registros por similaridade.

O backend de pesquisa ativo depende do SearchStrategy configurado do armazenamento. SearchStrategy.VECTOR classifica o vetor de consulta em relação aos vetores de registro armazenados. SearchStrategy.HYBRID consulta o índice híbrido gerenciado da Oracle pelo texto de pesquisa armazenado e seu estado de índice gerenciado. SearchStrategy.KEYWORD classifica apenas por texto correspondente ao texto de pesquisa armazenado.

• Parâmetros:
  • query str | None – Texto em idioma natural opcional usado para encontrar registros correspondentes ou similares. Forneça pelo menos um caractere que não seja de espaço em branco quando query_vector for omitido. A pesquisa vetorial incorpora esse texto; a pesquisa por palavra-chave o compara com o texto de pesquisa armazenado; a pesquisa híbrida o usa para recuperação de texto e vetor. Quando o texto excede o tamanho do bloco configurado, a loja pesquisa cada bloco de consulta separadamente e mescla os resultados classificados com a fusão de classificação recíproca.
  • query_vector list[float] | None – Incorporação de consulta pré-calculada opcional. Exatamente um dos query e query_vector deve ser fornecido. Na pesquisa de vetores, isso é comparado com vetores de registro armazenados. Na pesquisa híbrida, ela é enviada para o índice híbrido gerenciado da Oracle como entrada de vetor do lado da consulta e não faz com que o armazenamento de banco de dados seja comparado diretamente com vetores armazenados de tempo de adição ou atualização. A pesquisa por palavra-chave não aceita query_vector. O vetor deve ser não vazio, unidimensional e conter apenas valores numéricos finitos. Na pesquisa híbrida, sua dimensão deve corresponder ao modelo OracleDBEmbedder configurado.
  • k int – Número máximo de resultados a ser retornado. Os valores explícitos devem ser pelo menos 1. Este é um limite superior: a chamada pode retornar menos de k resultados quando os filtros são muito restritivos, quando há menos registros correspondentes não expirados ou por causa do comportamento de pesquisa específico da implementação.
  • thread_id str | None – Identificador de escopo de thread opcional. exact_thread_match=False deixa a dimensão de thread sem restrições. exact_thread_match=True corresponde exatamente ao thread_id fornecido. Se thread_id=None, ele corresponderá apenas aos registros sem escopo na dimensão de thread.
  • user_id str | None – Identificadores de escopo de usuário e agente opcionais O flag exact_*_match=False correspondente deixa essa dimensão sem restrições. exact_*_match=True corresponde exatamente ao ID fornecido. Se o ID for None, ele corresponderá apenas a registros sem escopo nessa dimensão.
  • agent_id str | None – Identificadores de escopo de usuário e agente opcionais. O flag exact_*_match=False correspondente deixa essa dimensão sem restrições. exact_*_match=True corresponde exatamente ao ID fornecido. Se o ID for None, ele corresponderá apenas a registros sem escopo nessa dimensão.
  • exact_user_match bool – Se cada identificador de escopo deve ser correspondido exatamente. False deixa essa dimensão sem restrições. True corresponde exatamente ao valor fornecido. Se esse valor for None, ele corresponderá apenas a registros sem escopo nessa dimensão.
  • exact_agent_match bool – Se cada identificador de escopo deve ser correspondido exatamente. False deixa essa dimensão sem restrições. True corresponde exatamente ao valor fornecido. Se esse valor for None, ele corresponderá apenas a registros sem escopo nessa dimensão.
  • exact_thread_match bool – Se cada identificador de escopo deve ser correspondido exatamente. False deixa essa dimensão sem restrições. True corresponde exatamente ao valor fornecido. Se esse valor for None, ele corresponderá apenas a registros sem escopo nessa dimensão.
  • record_types set[str] | None – Conjunto opcional de tipos de registro pesquisáveis a serem incluídos. Quando omitida, a pesquisa do BD abrange mensagens, documentos como imagens, linhas da tabela de memória e perfis de ator. Os registros de imagem contribuem com sua descrição, os perfis de ator contribuem com sua carga útil information e as linhas de mensagem e memória contribuem com sua carga útil content. Durante a pesquisa, os tipos de registro de perfil usam seu identificador de ator para a dimensão de escopo aplicável, enquanto as dimensões de escopo restantes se comportam como None.
  • metadata_filter dict[str, Any] | None – Mapeamento de filtro de metadados opcional. As entradas no metadata_filter são combinadas com a semântica AND. Entradas cujo valor não é um dicionário de operador de nível de campo usam semântica de correspondência exata: a chave solicitada deve existir nos metadados armazenados. Os dicionários aninhados são correspondidos recursivamente. Os valores escalares e de lista são correspondidos por igualdade exata; a ordem e o comprimento da lista também devem ser correspondentes. Para testar a associação de array, use um dicionário do operador no nível do campo, como {"tags": {"$array_contains": "prod"}}. Um operando de lista para "$array_contains" significa que todos os valores listados devem estar presentes; "$array_contains_any" significa que pelo menos um valor listado deve estar presente. Use "$not" para negar outra expressão no nível do campo no mesmo campo, incluindo um dicionário do operador ou valor de correspondência exata bruta. As expressões negativas correspondem quando a expressão positiva falharia, incluindo campos ausentes; a associação de matriz negada também corresponde a campos que não são de matriz.
  • include_invalid_results bool – Se os resultados incluem registros de memória no status inválido. O padrão é True. Informe False para excluí-los.
  • num_hops int – Número de bordas de link de memória a serem seguidas de cada resultado direto de memória. Há suporte para valores de 0 a 5; 0 desativa a expansão do gráfico. A expansão segue os links em ambas as direções. Os registros vinculados continuam a obedecer aos filtros de escopo, metadados, tipo de registro e expiração solicitados. Os resultados de mensagem direta, documento e perfil permanecem no conjunto de resultados, mas não são expandidos por gráfico.
  • max_linked_results int – Máximo de memórias vinculadas em todos os saltos anexados a cada resultado direto. 0 mantém resultados diretos sem contexto vinculado. O padrão é 100.
• Retorna: pares de (record, distance) classificados por distância crescente. A lista pode conter menos de k entradas. Para uma consulta em blocos, a distância é derivada da pontuação de fusão de classificação recíproca.
• Tipo de retorno: list[tuple[Record, float]]
• Aumenta:
  • ValueError – Se k for menor que 1, se ambos ou nenhum dos query e query_vector forem fornecidos, se query estiver em branco, se o modo vetorial não puder resolver uma incorporação de consulta, se query_vector for inválido ou se metadata_filter for inválido.
  • TimeoutError – Se a expansão do gráfico levar mais do que o tempo máximo permitido.

Exemplos

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 em um valor de metadados 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 em metadados aninhados:

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

Corresponder exatamente um valor de lista, incluindo a ordem:

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

Filtre quando um array de metadados contiver um valor:

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

Combine várias condições de metadados. Um registro deve atender a todas as chaves:

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

método search_async (assíncrono)

Pesquise registros de forma assíncrona por similaridade semântica.

• Parâmetros:
  • query str | None – O mesmo texto de consulta aceito por search.
  • k int – Mesma contagem máxima de resultados aceita por search. Os valores explícitos devem ser pelo menos 1.
  • query_vector list[float] | None – Mesma incorporação de consulta pré-calculada opcional aceita pelo search.
  • thread_id str | None – Os mesmos filtros de escopo opcionais aceitos por search.
  • user_id str | None – Os mesmos filtros de escopo opcionais aceitos por search.
  • agent_id str | None – Os mesmos filtros de escopo opcionais aceitos por search.
  • exact_user_match bool – Os mesmos sinalizadores de correspondência exata aceitos por search.
  • exact_agent_match bool – Os mesmos sinalizadores de correspondência exata aceitos por search.
  • exact_thread_match bool – Os mesmos sinalizadores de correspondência exata aceitos por search.
  • record_types set[str] | None – O mesmo filtro opcional de tipo de registro aceito por search.
  • metadata_filter dict[str, Any] | None – O mesmo filtro de metadados opcional aceito por search, incluindo escalar, aninhado, lista exata, associação de array e condições combinadas, como {"source": "slack"}, {"review": {"status": "open"}}, {"tags": ["prod", "urgent"]} e {"tags": {"$array_contains": "prod"}}.
  • include_invalid_results bool – Opção de resultado de mesmo status de ciclo de vida aceita por search.
  • num_hops int – Mesma profundidade de expansão de gráfico aceita pela search.
  • max_linked_results int – Mesmo limite de memória vinculada por resultado direto aceito por search.
• Retorna: pares (record, distance) retornados pela chamada search subjacente.
• Tipo de retorno: List[tuple[Record, float]]
• Eleva: ValueError – Se k for menor que 1.

método update

Atualize o conteúdo do registro armazenado, o estado da pesquisa, os metadados e os valores de timestamp.

• Parâmetros:
  • record_type str – Rótulo do tipo de registro da linha que está sendo modificada (por exemplo, "message", "memory", "guideline", "fact", "preference", "user_profile" ou "agent_profile")
  • record_id str – Identificador da linha armazenada a ser atualizada.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None – Conteúdo de substituição canônica persistido na coluna content. Para registros de mensagem, passe "" para limpar o conteúdo enquanto limpa qualquer representação vetorial armazenada; o None explícito é rejeitado. Para registros semelhantes à memória, passe None para limpar o texto armazenado e a incorporação e passe somente None ou argumentos semânticos omitidos na mesma chamada. Quando omitido, o conteúdo existente é deixado inalterado. Não forneça isso junto com text.
  • index_text str | list[str] | None – Payload opcional somente semântico. Quando omitido, content é usado para indexação semântica. Em esquemas com capacidade híbrida, isso também se torna o texto de pesquisa armazenado usado pelo componente de texto da Oracle. Um valor de string pode ser dividido pelo armazenamento; um valor de lista é tratado como chunks de propriedade do chamador e gravado como está em RECORD_CHUNKS. Quando apenas embedding é fornecido, o texto de pesquisa existente é reutilizado.

  • incorporação list[float] | ndarray | list[list[float] | ndarray] | None –

    Vetor de incorporação pré-computado opcional ou lista de vetores de incorporação de chunk. Quando o armazenamento vetorial local é configurado, isso é usado diretamente e nenhuma chamada de incorporador é feita. Passe None para limpar a incorporação armazenada. Um único vetor representa todo o texto de substituição quando content é fornecido, mesmo quando o chunker configurado dividiria esse texto. Vários vetores de chunk são rejeitados ao substituir o texto, a menos que index_text seja uma lista de chunk. Quando apenas embedding é fornecido, a contagem de incorporação deve corresponder às linhas de bloco existentes do registro.

    Em SearchStrategy.VECTOR, a pesquisa vetorial é classificada em relação à incorporação armazenada. Em SearchStrategy.HYBRID ou SearchStrategy.KEYWORD, a pesquisa suportada pelo BD é classificada por meio do texto de pesquisa armazenado e do texto gerenciado pela Oracle ou do estado do índice híbrido. Portanto, as incorporações de tempo de atualização afetam apenas qualquer armazenamento de vetores local configurado, não essa estratégia de pesquisa ativa. Se esse armazenamento tiver sido configurado sem armazenamento vetorial local, forneça index_text em vez de embedding para atualizar o texto visível para esses índices com reconhecimento de texto. Atualizações semânticas somente de texto podem omitir embedding inteiramente nesses modos.

  • metadata dict[str, Any] | None – Mapeamento de metadados opcional serializado para JSON e armazenado em metadata. A substituição da imagem content requer "image_mime_type" por "image/png", "image/jpeg" ou "image/webp". O armazenamento usa esse campo para salvar a imagem, mas não a retorna como parte dos metadados do registro.
  • timestamp str | None – Novo timestamp opcional para salvar com o registro. Ele representa quando o registro foi criado. Quando omitido, o timestamp existente é preservado. Informe None para limpar o timestamp salvo e use o horário de criação do banco de dados para futuras atualizações de expiração do TimeToLiveAnchor.CREATED_AT. Quando ttl_anchor é TimeToLiveAnchor.TIMESTAMP, os timestamps ISO-8601 sem um fuso horário são tratados como UTC.
  • ttl_days int | None – Atualização de expiração opcional em dias. Omita esse argumento junto com ttl_anchor para preservar o timestamp de expiração atual. Informe None para usar MemoryRetentionConfig.max_ttl_days quando a configuração de retenção definir uma, ou para limpar a expiração quando não o fizer. Os valores acima de MemoryRetentionConfig.max_ttl_days são limitados a esse máximo com uma advertência. Atualizar a expiração pode tornar um registro expirado visível novamente se ainda não tiver sido expurgado.
  • ttl_anchor TimeToLiveAnchor – Âncora opcional de tempo de vida útil para uma atualização de expiração. Use TimeToLiveAnchor.CREATED_AT para contar a partir do horário de criação armazenado, ou TimeToLiveAnchor.TIMESTAMP para contar a partir do timestamp de substituição fornecido na mesma atualização, ou o timestamp do evento armazenado quando timestamp for omitido. O fornecimento de ttl_anchor sem ttl_days atualiza a expiração usando o MemoryRetentionConfig.default_ttl_days do esquema. Quando o ttl_anchor é omitido durante uma atualização, o armazenamento usa TimeToLiveAnchor.CREATED_AT. As atualizações com data/hora ancoradas exigem um timestamp ISO-8601 de substituição na mesma chamada ou um timestamp de evento armazenado existente nesse formato. Os timestamps ISO-8601 sem fuso horário são tratados como UTC.
  • status RecordStatus – Status do ciclo de vida de substituição opcional para registros. Omita-o para preservar o status atual.

  • texto str | None –

    Alias obsoleto para content. Passe None para limpar o texto armazenado e limpar a incorporação armazenada. Não forneça isso junto com content.

    Obsoleto

    Obsoleto desde a versão 26.8.0: Este parâmetro foi preterido na versão 26.8.0 e será removido na versão 27.1. Em vez disso, use content.

• Retorna: Número de registros atualizados (0 ou 1). O valor de retorno 0 significa que nenhum registro foi atualizado.
• Tipo de retorno: int
• Gera: ValueError – Se record_type não for suportado, se nenhum payload de atualização for fornecido ou se os argumentos de atualização semântica forem incompatíveis.

Exemplos

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'

método update_async (assíncrono)

Atualize de forma assíncrona o conteúdo do registro armazenado, incorporando dados, metadados, timestamp ou expiração.

• Parâmetros:
  • record_type str – Tipo lógico do registro a ser atualizado.
  • record_id str – Identificador do registro a ser atualizado.
  • content str | Mapping[str, object] | Sequence[MessageContent] | bytes | None – Conteúdo de substituição canônica. Para registros message, informe uma string ou uma sequência ordenada de partes de conteúdo de texto e imagem; use "" para substituir a mensagem por texto vazio. Para registros semelhantes à memória, os armazenamentos podem aceitar None para limpar o texto armazenado e o estado semântico associado. Omita o argumento para deixar o conteúdo inalterado. Não forneça isso junto com text.
  • index_text str | list[str] | None – Payload semântico alternativo opcional usado para recomputar ou substituir o estado de pesquisa armazenado sem alterar o texto persistente. Uma string pode ser fragmentada internamente pela loja. Uma lista de strings não vazias é tratada como chunks de propriedade do chamador e não deve ser dividida novamente. Algumas implementações também podem persistir separadamente como texto de pesquisa híbrida. Para um registro image, esse campo substitui a descrição da imagem persistente.
  • embedding list[float] | ndarray | list[list[float] | ndarray] | None – Vetor de incorporação pré-computado opcional ou lista de vetores de incorporação de chunk. Quando fornecido, este é usado diretamente e nenhuma chamada de incorporador é feita. Vários vetores exigem listas de chunk index_text correspondentes ou linhas de chunk text armazenadas existentes. Passe None para limpar explicitamente a incorporação armazenada quando o armazenamento a suportar. Lojas com indexação com reconhecimento de texto também podem permitir atualizações semânticas sem um incorporador ou incorporação explícita.
  • metadata dict[str, Any] | None – Mapeamento de metadados de substituição opcional. Informe None para limpar metadados quando o armazenamento for compatível. A substituição da imagem content requer "image_mime_type" neste mapeamento. O armazenamento usa esse campo para salvar a imagem, mas não a retorna como parte dos metadados do registro.
  • timestamp str | None – Novo timestamp opcional para salvar com o registro. Ele representa quando o registro foi criado. Omita esse argumento para deixar o timestamp armazenado inalterado. Passe None para limpar o timestamp salvo e use o horário em que o registro foi adicionado à loja quando a loja a suporta.
  • ttl_days int | None – Atualização de expiração opcional em dias. Omita esse argumento junto com ttl_anchor para preservar o timestamp de expiração atual. Informe None para limpar a expiração.
  • ttl_anchor TimeToLiveAnchor – Âncora opcional de tempo de vida útil para uma atualização de expiração. Use TimeToLiveAnchor.CREATED_AT para o horário de criação do registro ou TimeToLiveAnchor.TIMESTAMP para o timestamp de substituição fornecido na mesma atualização ou o timestamp de evento armazenado quando timestamp for omitido. O fornecimento de ttl_anchor sem ttl_days usa a duração de tempo de vida padrão do armazenamento ou esquema. Quando o ttl_anchor é omitido durante uma atualização, as implementações usam TimeToLiveAnchor.CREATED_AT.
  • status RecordStatus – Status do ciclo de vida de substituição opcional para registros. Omita-o para preservar o status atual.

  • texto str | None –

    Alias obsoleto para content. Informe None para limpar explicitamente o texto armazenado quando o armazenamento o suportar. Não forneça isso junto com content.

    Obsoleto

    Obsoleto desde a versão 26.8.0: Este parâmetro foi preterido na versão 26.8.0 e será removido na versão 27.1. Em vez disso, use content.

• Retorna: Número de registros atualizados (0 ou 1). O valor de retorno 0 significa que nenhum registro foi atualizado.
• Tipo de retorno: int
• Eleva: ValueError – Se o payload de atualização for inválido para o armazenamento, como omitir todos os campos opcionais ou fornecer argumentos semânticos conflitantes.

método update_relations

Atualize os campos de relação mutável e recalcule o estado do ciclo de vida do ponto final.

Os campos omitidos permanecem inalterados. Os rótulos de link de memória incorporados sempre mantêm seu rótulo reverso derivado.

• Parâmetros:
  • relation_ids str | list[str] – Identificador ou identificadores das relações a serem atualizadas.
  • relation_types str | list[str] – Rótulo ou rótulos de relação direcionada de substituição opcional.
  • opposite_relation_types str | list[str] – Rótulo(s) reverso(s) de substituição opcional(is) para tipos personalizados.
  • timestamps str | None | list[str | None] – Carimbos de data/hora de substituição opcionais. Passe None para limpar um.
  • metadata dict[str, Any] | None | list[dict[str, Any] | None] – Metadados de substituição opcionais. Ele substitui os metadados existentes.
• Retorna: Identificadores de relações que foram atualizadas.
• Tipo de retorno: list[str]

Exemplos

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

método update_relations_async (assíncrono)

Atualizar assincronamente valores mutáveis em relações armazenadas.

Os campos omitidos permanecem inalterados, exceto que a alteração para um tipo de relação de memória incorporado substitui seu rótulo reverso pelo inverso fixo. Um armazenamento de memória suportado pelo BD também recalcula os estados do ciclo de vida do ponto final após uma alteração do tipo de relação.

• Parâmetros:
  • relation_ids str | list[str] – Identificador ou identificadores das relações a serem atualizadas.
  • relation_types str | list[str] – Rótulo ou rótulos de relação direcionada de substituição opcional. Omita isso para preservar os rótulos armazenados.
  • opposite_relation_types str | list[str] – Rótulo ou rótulos de relação reversa de substituição opcional. Informe um label para substituí-lo ou omita esse argumento para preservá-lo.
  • timestamps str | None | list[str | None] – Carimbo de data/hora de substituição opcional ou carimbos de data/hora. Informe None para limpar um timestamp armazenado.
  • metadados dict[str, Any] | None | list[dict[str, Any] | None] – Objeto ou objetos de metadados de substituição opcionais. Os metadados fornecidos substituem o objeto armazenado; ele não é mesclado.
• Retorna: Identificadores de relações que foram atualizadas.
• Tipo de retorno: list[str]

Exemplos

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

Relacionamentos

O OracleDBMemoryStore pode armazenar relações direcionadas entre registros semelhantes à memória (memory, fact, guideline e preference). Use add_relations(), get_relation(), list_relations(), update_relations() e delete_relations() quando uma integração precisar da API de relação de nível inferior. As APIs de cliente e thread fornecem link_records(), update_record_link() e delete_record_link() para tipos de relação de memória suportados.

Para recuperar uma relação, forneça relation_id sozinha ou a tupla completa do ponto final armazenado: tipo e ID do registro de origem, tipo e ID do registro de destino e tipo de relação. Uma tupla parcial e um ID de relação combinados com qualquer campo de tupla são inválidos porque nenhum identifica a relação solicitada sem ambiguidade.

Use list_relations() para enumerar relações na ordem de criação. Filtre por ID e tipo de registro de origem ou de destino ou por rótulo de relação direcionada. Ele usa o limite de lista de segurança normal da loja, a menos que você passe limit=None. Seu metadata_filter usa a mesma semântica de correspondência exata, objeto aninhado, associação de array e negação que list(); passe metadata_filter=None para retornar somente relações sem metadados.

Os tipos de relação do ciclo de vida — supersedes, refines e duplicates — marcam a memória de destino inválida enquanto o link existe. A remoção ou alteração do último link desse tipo restaura o destino para um status válido. As APIs de pesquisa podem excluir registros inválidos com include_invalid_results=False.

classe oracleagentmemory.apis.relations.RecordRelation

Bases: object

Descrever uma relação armazenada e direcionada entre dois registros.

• Parâmetros:
  • id str – Identificador estável da relação.
  • source_record_id str – Identificador do registro na origem armazenada da relação.
  • source_record_type str – Tipo lógico do registro de origem.
  • target_record_id str – Identificador do registro no destino armazenado da relação.
  • target_record_type str – Tipo lógico do registro de destino.
  • relation_type str – Label cujo significado segue a direção de origem a destino armazenada.
  • opposite_relation_type str – Rótulo usado quando a travessia se move do destino para a origem.
  • timestamp str | None – Timestamp do chamador opcional associado à relação.
  • metadata dict[str, Any] | None – Metadados opcionais semelhantes a JSON armazenados com a relação.
  • created_at str – Timestamp de criação do banco de dados para a relação.

Estratégia de Pesquisa

classe oracleagentmemory.core.dbsearch.SearchStrategy

Bases: Enum

Comportamento de pesquisa para armazenamentos do Oracle DB.

A inicialização do armazenamento do BD usa a estratégia selecionada para escolher o recurso de pesquisa de esquema gerenciado. A pesquisa VECTOR armazena incorporações locais. A pesquisa KEYWORD armazena texto pesquisável e um índice de texto. A pesquisa HYBRID armazena texto pesquisável mais o estado de índice vetorial híbrido gerenciado pela Oracle. O armazenamento do BD valida esse recurso de esquema na inicialização para que uma estratégia incompatível não retorne resultados incompletos silenciosamente.

VECTOR

Pesquisar apenas por similaridade vetorial. O armazenamento incorpora a consulta ao incorporador configurado ou usa um query_vector fornecido pelo chamador e classifica os registros pela distância dos vetores armazenados. Use isso com um esquema de banco de dados configurado para pesquisa de vetor.

HYBRID

Pesquise com o índice híbrido gerenciado da Oracle. A Oracle combina correspondência de texto em relação ao texto de pesquisa armazenado com classificação vetorial do índice híbrido no banco de dados. Use-o quando os usuários puderem pesquisar por linguagem natural, bem como identificadores exatos, aliases ou nomes de produtos. Essa estratégia requer que o principal incorporador da loja seja um OracleDBEmbedder para que o índice gerenciado e o armazenamento compartilhem um modelo no banco de dados.

KEYWORD

Pesquise somente por palavra-chave/texto correspondente ao texto de pesquisa armazenado. Esse modo não cria incorporações de consulta local e não precisa de um incorporador do Oracle DB. Quando aberto em um esquema híbrido existente, ele pode usar a ramificação de texto desse índice híbrido sem criar um novo índice híbrido. Use isso quando identificadores exatos, aliases, nomes de produtos ou frases curtas devem gerar recuperação sem fusão vetorial.

HÍBRIDO = 'híbrido'

KEYWORD = 'palavra-chave'

VECTOR = 'vetor'

Modo de sincronização de índice de pesquisa

classe oracleagentmemory.core.dbsearch.SearchIndexSyncMode

Bases: Enum

Comportamento de atualização para índices de pesquisa do BD gerenciado.

Essa definição controla quando o sistema Oracle torna o texto de pesquisa novo ou alterado visível para pesquisa com reconhecimento de texto suportada pelo BD. O SearchStrategy.HYBRID usa o índice vetorial híbrido gerenciado da Oracle. SearchStrategy.KEYWORD usa um índice do Oracle Text. SearchStrategy.VECTOR não usa essa definição.

ON_COMMIT

Atualize o índice quando a transação de gravação for confirmada. Esta é a opção padrão e mais simples para a maioria dos aplicativos porque os registros são pesquisáveis imediatamente após uma gravação bem-sucedida. Ele pode adicionar trabalho para gravar transações porque o índice é mantido atualizado imediatamente.

MANUAL

Não atualize o índice automaticamente. Registros novos ou atualizados podem não aparecer na pesquisa por palavra-chave ou híbrida até que você mesmo execute a operação de sincronização de índice do banco de dados. Isso é útil para cargas em massa ou janelas de manutenção nas quais você deseja controlar ao atualizar execuções de trabalho.

AUTO

Permitir que a Oracle atualize o índice híbrido gerenciado de forma assíncrona. As gravações podem evitar o custo de atualização imediato, mas os resultados da pesquisa podem ficar atrás das gravações recentes até que a Oracle conclua a atualização em segundo plano. Este modo é suportado somente com SearchStrategy.HYBRID.

Aviso: Esta configuração controla a manutenção contínua após a existência do índice de pesquisa gerenciado. Ele não torna a primeira compilação de índice assíncrona. A criação de um índice híbrido gerenciado sobre o texto de pesquisa armazenado existente pode ser de longa execução porque a Oracle cria o estado de índice híbrido gerenciado com base nesse texto.

AUTO = 'AUTO'

MANUAL = 'MANUAL'

ON_COMMIT = 'ON_COMMIT'

Tempo de Vida Útil

classe oracleagentmemory.core.retention.MemoryRetentionConfig

Bases: object

Definições de retenção no nível do esquema para registros com suporte do Oracle DB.

• Parâmetros:
  • default_ttl_days int | None – Duração padrão da vida útil, em dias. Deixe como NOT_SET_MARKER para usar o padrão de None (sem máximo).
  • max_ttl_days int | None – Duração máxima opcional da vida útil, em dias. Deixe como NOT_SET_MARKER para usar o padrão de None. Informe None para nenhum máximo. Quando definido, esse é um limite rígido: as gravações que tentam usar um valor ttl_days maior são limitadas a esse máximo com um aviso, e as APIs que passam por ttl_days=None usam esse máximo em vez de criar registros sem expiração.

classe oracleagentmemory.apis.ttl.TimeToLiveAnchor

Bases: Enum

Âncora usada para calcular um timestamp de expiração de uma duração de tempo de vida.

CREATED_AT

Expiração de computação do timestamp de criação do banco de dados do registro. Este é o padrão quando os chamadores omitem ttl_anchor.

TIMESTAMP

Calcular expiração do timestamp de evento armazenado do registro. Use esta opção quando uma mensagem ou memória representar um evento mais antigo e deve expirar em relação a esse horário de evento em vez de inserir o tempo.

CREATED_AT = 'criated_at'

TIMESTAMP = 'TIMESTAMP'

Política de Esquema

classe oracleagentmemory.core.SchemaPolicy

Bases: str, Enum

Política de criação de esquema para armazenamentos do Oracle DB.

REQUER_EXISTENTE

Valide se o esquema gerenciado completo já existe e está atualizado. Não crie ou modifique objetos do BD.

CRIAR_SE_VAZIO

Se não houver objetos gerenciados, o esquema de bootstrap. Se já existirem objetos, exija um esquema gerenciado completo e atualizado.

CRIAR_IF_NECESSÁRIO

Crie objetos gerenciados ausentes e aplique upgrades de esquema gerenciado suportados.

RECRIAR

Elimine e recrie todos os objetos de esquema gerenciados. Isso é destrutivo.

SEM_VERIFICAÇÃO

Ignore a validação e a criação do esquema gerenciado. Use esta política para um armazenamento protegido do Deep Data Security existente enquanto um contexto de segurança do usuário final estiver ativo. Um armazenamento aberto em um contexto de usuário final requer um contexto ativo para cada operação subsequente do banco de dados. Outras políticas de esquema rejeitam contextos de usuário final porque o trabalho do ciclo de vida do esquema deve ser executado por meio de uma identidade de banco de dados administrativo.