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 text em update() controlam o texto 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.

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 text de substituição é usado para recuperação. Se text 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 texto armazenado inalterado, a menos que text também seja fornecido.
String vazia ou lista de partes vazia	Armazena o texto do registro e não fornece nenhum texto de recuperação para esse registro.	Atualiza o texto do registro quando o text é 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 text e index_text, mas armazena essas linhas sem vetores locais. Se text 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 aprovação de text=None limpa linhas de texto e recuperação armazenadas, 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 text=None. 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:
  • conteúdo list[str | None] – Registre payloads para persistir. 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" ou "agent_profile").
  • 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 quando o registro foi criado. Os valores escalares podem ser transmitidos em entradas de texto alinhadas. As entradas Omitidas ou None usam o horário atual.
  • 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 "".
  • 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.
  • **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 | 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]
  • 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_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 | 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]
  • 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.
  • 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

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.

  • 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"],
    }

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

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"}}.
• 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.
  • 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 | 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.
  • 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.
  • 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.
• 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 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 – 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. SchemaPolicy.CREATE_IF_NECESSARY pode aplicar upgrades de versão de esquema gerenciado suportados, pode fazer upgrade de um esquema vetorial para pesquisa de palavra-chave adicionando um índice de texto ou para pesquisa híbrida adicionando as estruturas de pesquisa gerenciada e o índice híbrido.
  • 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.

  • table_name_prefix str –

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

    Observação: 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.
  • 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.
  • 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.

Advertência: SchemaPolicy.CREATE_IF_NECESSARY pode ser mais caro do que a inicialização normal do armazenamento porque pode aplicar DDL de esquema gerenciado e regravações de dados de melhor esforço antes que a inicialização seja bem-sucedida. Planeje a primeira abertura de um esquema gerenciado mais antigo como uma operação de migração ou manutenção quando esse esquema pode conter muitas linhas.

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:
  • conteúdo list[str | None] – Registre payloads para persistir. Os valores de texto também são usados para pesquisar texto, a menos que index_texts seja fornecido. Quando um valor de texto é None, o armazenamento pode voltar a ser 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" ou "agent_profile").
  • 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.
  • 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 "".
  • 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.
  • **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 de

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 de

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

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 | 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]
  • 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_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 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 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 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 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 este 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 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"],
    }

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

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

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

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"}}.
• 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.
  • 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 representação vetorial armazenada para esse registro. Quando omitido, o conteúdo existente é deixado inalterado.
  • index_text str | list[str] | None – Payload opcional somente semântico. Quando omitido, text é 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 text é 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.
  • 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.
• 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'

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.