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

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:
  • conteúdo list[str | None] – Registre payloads para persistir. Os valores de texto também são usados para incorporação, 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" ou "agent_profile").
  • index_texts list[str] – Cargas úteis alternativas opcionais usadas somente para incorporação/indexação. Quando fornecido, deve estar alinhado com as entradas de texto.
  • embeddings list[list[float]] | list[ndarray] – Vetores de incorporação pré-calculados opcionais alinhados com as entradas de texto. Quando fornecido, a loja deve usar esses vetores diretamente em vez de invocar seu embutidor. Se não for fornecido, a loja deve ter um encaixe anexado, caso contrário, um erro será gerado.
  • 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 de evento opcionais a serem mantidos com os registros. Os valores escalares podem ser transmitidos em entradas de texto alinhadas.
  • metadados dict[str, Any] | list[dict[str, Any] | None] | 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 "".
  • **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 list[str | None]
  • tipo_registro str
  • index_texts list[str]
  • incorporações list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • funções str | None | list[str | None]
  • timestamps (str | None | list[str | None])
  • metadados dict[str, Any] | list[dict[str, Any] | None] | None
  • 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.
• 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 list[str | None]
  • tipo_registro str
  • index_texts list[str]
  • incorporações list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • funções str | None | list[str | None]
  • timestamps (str | None | list[str | None])
  • metadados dict[str, Any] | list[dict[str, Any] | None] | None
  • 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 de

store.add_batches(
    [
        PendingRecordBatch(
            texts=["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_user (abstract)

Adicionar 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.
• 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

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.

method get (abstract)

Recuperar um registro armazenado por tipo e identificador.

• Parâmetros:
  • record_type str – Tipo lógico do registro a ser recuperado.
  • record_id str – Identificador do registro a ser recuperado.
• Retorna: O registro armazenado quando encontrado, caso contrário, None.
• Tipo de retorno: Registro | Nenhum

method list (abstract)

Listar registros armazenados para um tipo de registro.

• Parâmetros:
  • record_type str – Tipo de registro lógico a ser enumerado.
  • 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.
  • 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.
• Devoluções: Registros ordenados do mais antigo para o mais recente na janela retornada.
• Tipo de retorno: List[Record]

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.
• 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.
  • 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 metadados parcial opcional. Um registro só corresponde quando seus metadados armazenados contêm todas as chaves e valores solicitados. Os dicionários aninhados são correspondidos recursivamente. Os valores de lista são correspondidos por igualdade exata em vez de correspondência de subconjunto recursivo, portanto, a ordem e o tamanho da lista também devem corresponder.
• Retorna: pares de (record, distance) classificados por distância crescente.
• Tipo de retorno: list[tuple[Record, float]]
• Eleva: ValueError – Se k for menor que 1.

Exemplos de

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

método search_async (assíncrono)

Pesquisa assíncrona de registros por similaridade vetorial.

• 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.
• 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 ou metadados.

• Parâmetros:
  • record_type str – Tipo lógico do registro a ser atualizado.
  • record_id str – Identificador do registro a ser atualizado.
  • text str | None – Conteúdo de substituição opcional. Informe None para limpar explicitamente o texto armazenado quando o armazenamento o suportar. Os armazenamentos também podem limpar o estado semântico associado e rejeitar atualizações index_text ou embedding não nulas em conflito na mesma chamada. Omita o argumento para deixar o conteúdo inalterado.
  • index_text str | None – Payload opcional somente para incorporação usado para recalcular o vetor armazenado sem alterar o texto persistido.
  • embedding list[float] | ndarray | None – Vetor de incorporação pré-computado opcional. Quando fornecido, este é usado diretamente e nenhuma chamada de incorporador é feita. Passe None para limpar explicitamente a incorporação armazenada quando o armazenamento a suportar.
  • metadata dict[str, Any] | None – Mapeamento de metadados de substituição opcional. Informe None para limpar metadados quando o armazenamento for compatível.
• Retorna: Número de registros atualizados, geralmente 0 ou 1. Retorna 0 quando nenhum registro armazenado corresponde ao identificador lógico solicitado.
• 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.

Armazenamento do Oracle DB

classe oracleagentmemory.core.OracleDBMemoryStore

Bases: OracleMemoryStore

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

Crie um armazenamento do Oracle DB.

• Parâmetros:
  • embedder IEmbedder | None – Embedder usado para tipos de registro vetorizados. Pode ser None quando os chamadores sempre fornecem vetores pré-calculados em add, update e search.
  • 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 – Modo de configuração do esquema. O padrão é exigir um esquema gerenciado existente e atualizado e não executar alterações de DDL. Use SchemaPolicy.CREATE_IF_NECESSARY para preencher objetos ausentes ou SchemaPolicy.RECREATE para eliminar e recriar objetos gerenciados.
  • vector_dim int – Dimensão de incorporação para criação de esquema quando colunas VECTOR são criadas.
  • table_name_prefix str – Prefixo opcional adicionado aos nomes de tabelas/índices gerenciados.

método add

Adicionar registros à loja.

• Parâmetros:
  • conteúdo list[str | None] – Registre payloads para persistir. Os valores de texto também são usados para incorporação, 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" ou "agent_profile").
  • index_texts list[str] – Cargas úteis alternativas opcionais usadas somente para incorporação/indexação. Quando fornecido, deve estar alinhado com as entradas de texto.
  • embeddings list[list[float]] | list[ndarray] – Vetores de incorporação pré-calculados opcionais alinhados com as entradas de texto. Quando fornecido, a loja deve usar esses vetores diretamente em vez de invocar seu embutidor. Se não for fornecido, a loja deve ter um encaixe anexado, caso contrário, um erro será gerado.
  • 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 de evento opcionais a serem mantidos com os registros. Os valores escalares podem ser transmitidos em entradas de texto alinhadas.
  • metadados dict[str, Any] | list[dict[str, Any] | None] | 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 "".
  • **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 list[str | None]
  • tipo_registro str
  • index_texts list[str]
  • incorporações list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • funções str | None | list[str | None]
  • timestamps (str | None | list[str | None])
  • metadados dict[str, Any] | list[dict[str, Any] | None] | None
  • store_kwargs Any

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 list[str | None]
  • tipo_registro str
  • index_texts list[str]
  • incorporações list[list[float]] | list[ndarray]
  • record_ids str | None | list[str | None]
  • thread_ids str | None | list[str | None]
  • user_ids str | None | list[str | None]
  • agent_ids str | None | list[str | None]
  • funções str | None | list[str | None]
  • timestamps (str | None | list[str | None])
  • metadados dict[str, Any] | list[dict[str, Any] | None] | None
  • 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 de

store.add_batches(
    [
        PendingRecordBatch(
            texts=["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_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 linha de incorporação de perfil em RECORD_CHUNKS.
• 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 de

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

método add_user

Adicionar um registro de perfil de usuário.

• Parâmetros:
  • user_id str – Identificador do usuário.
  • informações str – Informações de formato livre sobre o usuário. Esse texto é armazenado como conteúdo do perfil e usado para criar a linha de incorporação de perfil em RECORD_CHUNKS.
• 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 mesmo valor informado como user_id.

Exemplos de

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

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 de suporte incluem "thread", "message", "memory", "guideline", "fact", "preference", "user_profile" e "agent_profile".
  • 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 de

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_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 das linhas de bloco de registro mantidas 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 referenciadas de THREAD junto com as linhas RECORD_CHUNKS correspondentes na mesma transação.

Exemplos de

store.delete_thread("c1")
0

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", "user_profile" ou "agent_profile".
  • record_id str – Identificador a ser pesquisado.
• Retorna: Registro preenchido com metadados decodificados quando encontrado; caso contrário, None.
• Tipo de retorno: Registro | Nenhum

Exemplos de

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 list

Enumerar registros persistidos para um tipo de registro.

• Parâmetros:
  • record_type str – Rótulo de tipo de registro (por exemplo, "message", "memory", "guideline", "fact", "preference", "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 esse filtro.
  • 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 esse 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 definidos como um dict, os metadados armazenados devem conter todas as chaves e valores solicitados. Os dicionários aninhados são correspondidos recursivamente. Os valores de lista são correspondidos por igualdade exata em vez de correspondência de subconjunto recursivo, portanto, a ordem e o tamanho da lista também devem corresponder.
• 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 na record.id.

Exemplos de

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_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.
• Devoluções: Registros de mensagem ordenados por ordem de inserção.
• Tipo de retorno: list[MessageRecord]

Exemplos de

store.list_thread_messages("c1")
[]

método search

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.
  • 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, linhas da tabela de memória e perfis de ator. Os perfis de ator contribuem com o payload information, enquanto as linhas de mensagem e memória contribuem com o payload 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 metadados parcial opcional. Um registro só corresponde quando seus metadados armazenados contêm todas as chaves e valores solicitados. Os dicionários aninhados são correspondidos recursivamente. Os valores de lista são correspondidos por igualdade exata em vez de correspondência de subconjunto recursivo, portanto, a ordem e o tamanho da lista também devem corresponder.
• Retorna: pares de (record, distance) classificados por distância crescente.
• Tipo de retorno: list[tuple[Record, float]]
• Eleva: ValueError – Se k for menor que 1.

Exemplos de

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

método search_async (assíncrono)

Pesquisa assíncrona de registros por similaridade vetorial.

• 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.
• 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, as incorporações de chunk e os valores de metadados.

• 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.
  • text str | None – Texto de substituição opcional persistido na coluna content. Passe None para limpar o texto armazenado e limpar a incorporação armazenada. Informe somente None ou argumentos semânticos omitidos na mesma chamada. Informe "" para preservar conteúdo vazio explícito ao limpar qualquer incorporação de chunk para esse registro. Quando omitido, o conteúdo existente é deixado inalterado.
  • index_text str | None – Payload somente de incorporação opcional. Quando omitido, text é incorporado.
  • embedding list[float] | ndarray | None – Vetor de incorporação pré-computado opcional. Quando fornecido, este é usado diretamente e nenhuma chamada de incorporador é feita. Passe None para limpar a incorporação armazenada.
  • metadata dict[str, Any] | None – Mapeamento de metadados opcional serializado para JSON e armazenado em metadata.
• Retorna: Número de linhas atualizadas (0 ou 1). Retorna 0 quando nenhum registro lógico corresponde a record_type e record_id.
• 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 de

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

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_SE_NECESSÁRIO

Crie somente objetos gerenciados ausentes, incluindo metadados.

RECRIAR

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