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.

method add (abstract)

Incorpore e persista registros de texto.

• Parâmetros:
  • conteúdo list[str | None] – Payloads de texto a serem armazenados. Esses valores também são usados como payloads de incorporação quando o index_texts não é fornecido. Quando um item é omitido (None), os armazenamentos o resolvem da chave de metadados "content" quando disponível; caso contrário, o conteúdo vazio é mantido.
  • record_type str – Rótulo de tipo de registro para registros armazenados (por exemplo, "message" ou "memory").
  • index_texts list[str] – Cargas úteis somente para incorporação opcionais alinhados com contents.
  • embeddings list[list[float]] | list[ndarray] – Vetores de incorporação pré-computados opcionais alinhados com contents. Quando fornecidos, as lojas usam esses vetores diretamente e não chamam o incorporador.
  • record_ids str | None | list[str] | list[None] – IDs de registro opcionais visíveis ao chamador. Deve ser totalmente fornecido (um por texto) ou omitido para todos os textos. Os IDs retornados correspondem a esses valores quando fornecidos.
  • thread_ids str | None | list[str | None] – Identificadores de escopo opcionais armazenados com os registros.
  • user_ids str | None | list[str | None] – Identificadores de escopo opcionais armazenados com os registros.
  • agent_ids str | None | list[str | None] – Identificadores de escopo opcionais armazenados com os registros.
  • funções str | None | list[str | None] – Função de chat opcional para registros de mensagem.
  • timestamps str | None | list[str | None] – Timestamp opcional ou timestamps por registro.
  • metadados dict[str, Any] | list[dict[str, Any] | None] | None – Mapeamento de metadados opcional ou mapeamentos de metadados por registro. Os metadados podem incluir "content" como origem de fallback para valores de texto omitidos.
  • **store_kwargs (Qualquer) – Opções de gravação específicas da loja encaminhadas por APIs de nível superior.
• Retorna: insere identificadores para cada item de conteúdo de entrada. Esses valores correspondem a record_ids quando fornecidos; caso contrário, armazenam identificadores de geração.
• Tipo de retorno: list[str]

Exemplos de

store.add(["Abstract memory"], record_type="memory", record_ids="mem-abstract-docs")
['mem-abstract-docs']

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

Armazenamento do Oracle DB

classe oracleagentmemory.core.OracleDBMemoryStore

Bases: OracleMemoryStore

Persistência suportada pelo banco de dados para mensagens e registros de memória digitados.

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 ao armazenamento de memória.

• Parâmetros:
  • conteúdo list[str | None] – Payloads de texto a serem armazenados. Esses valores também são usados para calcular a incorporação, a menos que index_texts ou embeddings sejam fornecidos. Quando um item é omitido (None), os armazenamentos o resolvem da chave de metadados "content" quando disponível; caso contrário, o conteúdo vazio é mantido.
  • record_type str – Rótulo de tipo de registro para registros armazenados (por exemplo, "message", "memory", guideline, fact ou preference).
  • index_texts list[str] – Cargas úteis alternativas opcionais usadas somente para incorporação/indexação. Quando fornecido, deve ter o mesmo tamanho que contents.
  • embeddings list[list[float]] | list[ndarray] – Vetores de incorporação pré-computados opcionais alinhados com contents. Quando fornecido, as lojas devem usar esses vetores diretamente e não devem invocar o incorporador. Quando omitido, o armazenamento usa o incorporador somente para cargas úteis de indexação não vazias; strings vazias explícitas são armazenadas sem incorporações de bloco.
  • record_ids str | None | list[str] | list[None] – IDs de registro opcionais visíveis ao chamador. Deve ser totalmente fornecido (um por texto) ou omitido para todos os textos. Os IDs retornados correspondem a esses valores quando fornecidos. Quando o armazenamento é omitido, os IDs são gerados pelo lado do cliente.
  • thread_ids str | None | list[str | None] – Identificadores de escopo opcionais armazenados com os registros.
  • user_ids str | None | list[str | None] – Identificadores de escopo opcionais armazenados com os registros.
  • agent_ids str | None | list[str | None] – Identificadores de escopo opcionais armazenados com os registros.
  • funções str | None | list[str | None] – Função de chat opcional para registros de mensagem.
  • timestamps str | None | list[str | None] – Carimbos de data/hora de evento fornecidos pelo chamador opcional.
  • 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 para valores de texto omitidos.
  • **store_kwargs (Qualquer) – Opções de gravação específicas da loja. As chaves suportadas atualmente incluem batch_size para o batch executemany da Oracle.
• Retorna: insere identificadores para cada item de conteúdo de entrada. Eles correspondem a record_ids quando fornecidos; caso contrário, armazenam IDs gerados de retorno.
• Tipo de retorno: list[str]

Exemplos de

store.add(
    ["Hello from docs"],
    record_type="message",
    record_ids="msg-docs-add",
    thread_ids="c-docs-add",
    roles="user",
)
['msg-docs-add']

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.
• Devoluções: Identificador do registro de perfil do agente inserido.
• Tipo de retorno: str

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.
• Devoluções: Identificador do registro de perfil de usuário inserido.
• Tipo de retorno: str

Exemplos de

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

método delete

Excluir uma linha de registro de vetor gerenciado e suas linhas de bloco por identificador.

• Parâmetros:
  • record_type str – Label de tipo de registro cuja tabela gerenciada deve ser direcionada, como "message", "memory", "guideline", "fact" ou "preference"
  • record_id str – Identificador da linha a ser removida.
• Retorna: Número de linhas removidas (0 quando o identificador não foi encontrado).
• Tipo de retorno: int

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 associadas de registro vetorial e bloco.

• Parâmetros: thread_id str – Identificador de thread cujas linhas devem ser removidas (incluindo linhas filho excluídas em cascata).
• Retorna: Número de linhas de thread excluídas (0 ou 1).
• Tipo de retorno: int

Exemplos de

store.delete_thread("c1")
0

método get

Recuperar uma mensagem ou memória armazenada por identificador.

• Parâmetros:
  • record_type str – Label de tipo de registro resolvendo para uma linha de registro vetorial gerenciado, como "message", "memory", "guideline", "fact" ou "preference".
  • 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" ou "preference").
  • limite int – Número máximo de registros a serem retornados.
  • thread_id str | None – Filtro de escopo de thread exato. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros sem escopo na dimensão de thread são retornados.
  • user_id str | None – Filtro de escopo de usuário exato. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros sem escopo na dimensão do usuário são retornados.
  • agent_id str | None – Filtro exato de escopo do agente. Quando omitido, nenhum filtro é aplicado. Quando definido como None, somente os registros sem escopo na dimensão do agente são retornados.
  • 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]

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

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 a incluir. Quando omitida, a pesquisa abrange qualquer tipo de registro.
  • 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 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 ou preference)
  • record_id str – Identificador da mensagem ou linha da memória 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.