Memória do Agente

Esta página apresenta a implementação concreta do Oracle AI Agent Memory.

Memória do Agente Oracle

Observação: OracleAgentMemory.delete_thread() é o caminho suportado para limpeza em cascata com escopo de thread. Ele remove o thread junto com mensagens associadas, memórias duráveis e dados de recuperação gerenciados. Isso é mais amplo que OracleThread.delete_message(), que exclui somente a linha de mensagem bruta. A exclusão no nível do cliente aguarda a extração em segundo plano anterior relevante: a exclusão do thread aguarda esse thread, a exclusão da memória aguarda o thread do destino armazenado quando presente e a exclusão do usuário ou agente aguarda os threads de propriedade conhecidos, quer a limpeza em cascata esteja ativada ou não. Essas esperas abrangem apenas o trabalho aceito pelo mesmo cliente antes do início da espera.

classe oracleagentmemory.core.OracleAgentMemory

Bases: IAgentMemory

Cliente de memória do agente com suporte do Oracle DB ou de um armazenamento fornecido pelo chamador.

Criar um cliente de memória.

Aviso: SchemaPolicy.CREATE_IF_NECESSARY pode ser mais caro do que a inicialização normal do cliente 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. A inicialização do cliente aguarda a conclusão desse DDL, portanto, 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.

Exemplos

Para acessar um esquema criado por outro usuário do banco de dados, configure memory_rw_pool para o usuário do banco de dados do aplicativo e defina memory_schema_owner como o nome do banco de dados sem aspas do usuário proprietário.

from oracleagentmemory.core import (
    MemoryExtractionConfig,
    SearchIndexSyncMode,
    OracleAgentMemory,
    SchemaPolicy,
    SearchStrategy,
)
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
pruned_search_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
    pruner_llm=llm,
)
shared_client = OracleAgentMemory(
    connection=memory_rw_pool,
    embedder=embedder,
    llm=llm,
    schema_owner=memory_schema_owner,
)

Use um modelo de incorporação no BD para explorar a pesquisa de índice híbrido da Oracle:

from oracleagentmemory.core.embedders import OracleDBEmbedder
db_embedder = OracleDBEmbedder(
    connection=db_pool,
    model="DOC_MODEL",
    embedding_dimension=768,
)
hybrid_client = OracleAgentMemory(
    connection=db_pool,
    embedder=db_embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    search_strategy=SearchStrategy.HYBRID,
    search_index_sync=SearchIndexSyncMode.ON_COMMIT,
    memory_store_id=memory_store_id,
)

método add_agent

Adicionar um registro de perfil de agente à loja.

Observações

Os registros de perfil do agente são armazenados no armazenamento no nível do cliente e não têm escopo intencional. O identificador de registro retornado é o mesmo identificador público que o aplicativo usa como agent_id.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent(
    "a1",
    "Support assistant",
    metadata={"source": "catalog"},
)
'a1'

método add_agent_async (assíncrono)

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

Observações

Os registros de perfil do agente são armazenados no armazenamento no nível do cliente e não têm escopo intencional. O identificador de registro retornado é o mesmo identificador público que o aplicativo usa como agent_id.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_agent_async(
    "a1",
    "Support assistant",
    metadata={"source": "catalog"},
))
'a1'

método add_image

Adicione um registro de imagem ao cliente.

Exemplos

image_id = client.add_image(
    b"image-bytes",
    description="Image description",
    mime_type=ImageMimeType.PNG,
    image_id="img-1",
    user_id="user-1",
)
image_id
'img-1'

método add_image_async (assíncrono)

Persistir uma imagem independente por meio do armazenamento configurado.

Quando o description é omitido ou o None, o LLM configurado gera uma legenda.

método add_memory

Adicione uma memória no sistema de memória, atribuída ao usuário, agente e thread indicados.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("User likes pizza", memory_id="mem-1")
memory_id
'mem-1'

método add_memory_async (assíncrono)

Adicione uma memória no sistema de memória de forma assíncrona.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
memory_id = asyncio.run(client.add_memory_async(
    "User likes pizza", memory_id="mem-1"
))
memory_id
'mem-1'

método add_user

Adicionar um registro de perfil de usuário à loja.

Observações

Os registros de perfil do usuário são armazenados no armazenamento no nível do cliente e não têm escopo intencional. O identificador de registro retornado é o mesmo identificador público que o aplicativo usa como user_id.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user(
    "u1",
    "Prefers concise answers.",
    metadata={"source": "crm"},
)
'u1'

método add_user_async (assíncrono)

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

Observações

Os registros de perfil do usuário são armazenados no armazenamento no nível do cliente e não têm escopo intencional. O identificador de registro retornado é o mesmo identificador público que o aplicativo usa como user_id.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_user_async(
    "u1",
    "Prefers concise answers.",
    metadata={"source": "crm"},
))
'u1'

método close

Feche o componente de memória do agente.

O fechamento para de aceitar novos trabalhos em segundo plano, incluindo extração de memória e geração de descrição de imagem, e aguarda que o trabalho pendente seja concluído até o tempo limite configurado. Se esse timeout expirar, close() retornará mesmo que algum trabalho ainda esteja inacabado. O método é idempotente.

Exemplos

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.close()

método close_async (assíncrono)

Feche assincronamente o componente de memória do agente.

Este método segue o mesmo comportamento de shutdown que close(). Se o tempo limite expirar, ele poderá retornar enquanto o trabalho em segundo plano ainda estiver em execução.

Exemplos

import asyncio
asyncio.run(client.close_async())

método create_thread

Crie e registre um thread.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
thread.thread_id
'c1'

método create_thread_async (assíncrono)

Crie e registre um thread de forma assíncrona.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
thread = asyncio.run(client.create_thread_async(
    thread_id="c1", user_id="u1"
))
thread.thread_id
'c1'

método delete_agent

Excluir um registro de perfil do agente por identificador.

Observações

Antes de excluir o perfil, esse método aguarda até 300 segundos para a extração em segundo plano anterior já aceita para threads próprios conhecidos por meio desse componente de memória do agente. Esta espera se aplica se a limpeza em cascata está ou não ativada. A limpeza em cascata é planejada e executada dentro do armazenamento de apoio como uma operação. O método não aguarda o trabalho aceito após o início da espera ou o trabalho iniciado por outro componente ou processo de memória do agente. Não há suporte para o uso simultâneo no escopo do ator enquanto a exclusão está em andamento.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a-delete", "Support assistant")
'a-delete'
client.delete_agent("a-delete")
1

método delete_agent_async (assíncrono)

Excluir um registro de perfil do agente por identificador de forma assíncrona.

Observações

Este método segue o comportamento de espera e simultaneidade de extração em segundo plano documentado por delete_agent().

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_agent_async("a-delete", "Support assistant"))
'a-delete'
asyncio.run(client.delete_agent_async("a-delete"))
1

método delete_image

Excluir um registro de imagem por identificador.

método delete_image_async (assíncrono)

Exclua uma imagem independente por meio do armazenamento configurado.

método delete_memory

Excluir um registro semelhante à memória (por exemplo, uma memória, um fato, uma preferência ou uma diretriz) por identificador.

Observações

Antes de excluir um registro com escopo de thread, esse método resolve seu thread armazenado e aguarda a extração em segundo plano anterior aceita por meio desse componente de memória do agente. Ele não aguarda threads não relacionados, trabalho aceito após o início da espera ou trabalho iniciado por outro componente ou processo de memória do agente. Registros sem um escopo de thread e identificadores desconhecidos não causam uma espera de extração.

Exemplos

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
memory_id = client.add_memory("Temporary memory", memory_id="mem-delete")
client.delete_memory(memory_id)
1

método delete_memory_async (assíncrono)

Excluir um registro semelhante a memória de forma assíncrona.

Observações

Este método segue a espera de extração em segundo plano e o comportamento de simultaneidade documentados pelo delete_memory().

Exemplos

import asyncio
memory_id = asyncio.run(client.add_memory_async(
    "Temporary memory", memory_id="mem-delete"
))
asyncio.run(client.delete_memory_async(memory_id))
1

Exclua uma relação por identificador ou complete a tupla do ponto final.

Quando nenhum relation_id for fornecido, forneça todos os argumentos de origem, destino, tipo e rótulo de relação na orientação de origem para destino armazenada.

Exemplos

client.delete_record_link(relation_id="relation-id")
1

Exclua de forma assíncrona uma relação por ID ou complete a tupla do ponto final.

método delete_thread

Exclua todos os registros associados a um identificador de thread.

Observações

Use esta operação quando precisar de remoção completa de retenção de um thread. O armazenamento de suporte exclui o thread junto com mensagens com escopo de thread associadas, memórias duráveis e dados de recuperação gerenciados. Isso difere de OracleThread.delete_message(), que remove apenas o registro de mensagem bruta e não faz cascata para memórias derivadas criadas a partir dessa mensagem. Antes de excluir o thread, este método aguarda a extração em segundo plano anterior já aceita para esse thread por meio deste componente de memória do agente. Ele não aguarda o trabalho em segundo plano aceito após o início da espera ou o trabalho iniciado por outro componente ou processo de memória do agente. O uso simultâneo do mesmo thread enquanto a exclusão está em andamento não é suportado.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c-delete")
client.delete_thread(thread.thread_id)
1

método delete_thread_async (assíncrono)

Exclua todos os registros associados a um identificador de thread de forma assíncrona.

Observações

Use esta operação quando precisar de remoção completa de retenção de um thread. O armazenamento de suporte exclui o thread junto com mensagens com escopo de thread associadas, memórias duráveis e dados de recuperação gerenciados. Isso difere de OracleThread.delete_message(), que remove apenas o registro de mensagem bruta e não faz cascata para memórias derivadas criadas a partir dessa mensagem. Antes de excluir o thread, este método aguarda a extração em segundo plano anterior já aceita para esse thread por meio deste componente de memória do agente. Ele não aguarda o trabalho em segundo plano aceito após o início da espera ou o trabalho iniciado por outro componente ou processo de memória do agente. O uso simultâneo do mesmo thread enquanto a exclusão está em andamento não é suportado.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
thread = asyncio.run(client.create_thread_async(thread_id="c-delete"))
asyncio.run(client.delete_thread_async(thread.thread_id))
1

método delete_user

Excluir um registro de perfil de usuário por identificador.

Observações

Antes de excluir o perfil, esse método aguarda até 300 segundos para a extração em segundo plano anterior já aceita para threads próprios conhecidos por meio desse componente de memória do agente. Esta espera se aplica se a limpeza em cascata está ou não ativada. A limpeza em cascata é planejada e executada dentro do armazenamento de apoio como uma operação. O método não aguarda o trabalho aceito após o início da espera ou o trabalho iniciado por outro componente ou processo de memória do agente. Não há suporte para o uso simultâneo no escopo do ator enquanto a exclusão está em andamento.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u-delete", "Prefers concise answers.")
'u-delete'
client.delete_user("u-delete")
1

método delete_user_async (assíncrono)

Excluir um registro de perfil de usuário por identificador de forma assíncrona.

Observações

Este método segue o comportamento de espera e simultaneidade de extração em segundo plano documentado por delete_user().

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
asyncio.run(client.add_user_async("u-delete", "Prefers concise answers."))
'u-delete'
asyncio.run(client.delete_user_async("u-delete"))
1

método get_thread

Recupera um thread criado anteriormente.

Observações

As substituições explícitas por chamada têm precedência. Quando as substituições de runtime são omitidas, os threads reabertos usam a configuração de runtime persistente quando disponível antes de voltar aos padrões do SDK.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
created = client.create_thread(thread_id="c2", user_id="u1")
loaded = client.get_thread("c2")
loaded.user_id
'u1'

método get_thread_async (assíncrono)

Recupera um thread criado anteriormente de forma assíncrona.

Observações

As substituições explícitas por chamada têm precedência. Quando as substituições de runtime são omitidas, os threads reabertos usam a configuração de runtime persistente quando disponível antes de voltar aos padrões do SDK.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
import asyncio
created = asyncio.run(client.create_thread_async(
    thread_id="c2", user_id="u1"
))
loaded = asyncio.run(client.get_thread_async("c2"))
loaded.user_id
'u1'

Criar uma relação direcionada entre dois registros armazenados.

No momento, os dois pontos finais devem ser registros semelhantes à memória: "memory", "fact", "guideline" ou "preference". Os tipos de relação incorporados são "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") e "duplicates". "contradicts" e "duplicates" usam o mesmo label invertido.

Somente uma orientação pode ser armazenada para um par de pontos finais. opposite_relation_type nomeia a relação ao percorrer do destino para a origem. Por exemplo, se new "supersedes" old, a reversão será old "is_superseded_by" new.

Exemplos

client.link_records(
    "fact-1", "fact", "memory-1", "memory", "supports"
)
'relation-id'

Crie de forma assíncrona uma relação digitada entre os registros armazenados.

No momento, os dois pontos finais devem ser registros semelhantes à memória: "memory", "fact", "guideline" ou "preference". Os tipos de relação incorporados são "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") e "duplicates". "contradicts" e "duplicates" usam o mesmo label invertido.

método list_agents

Listar registros de perfil de agente persistidos.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a1", "Support assistant", metadata={"source": "catalog"})
'a1'
[record.id for record in client.list_agents(metadata_filter={"source": "catalog"})]
['a1']

método list_agents_async (assíncrono)

Liste registros de perfil de agente persistidos de forma assíncrona.

Exemplos

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_agent_async(
        "a1",
        "Support assistant",
        metadata={"source": "catalog"},
    )
    records = await client.list_agents_async(metadata_filter={"source": "catalog"})
    return [record.id for record in records]
anyio.run(main)
['a1']

método list_images

Liste registros de imagem stand-alone persistidos.

Exemplos

images = client.list_images(user_id="u1", limit=10)
[image.id for image in images]
['img-1']

método list_images_async (assíncrono)

Liste registros de imagem standalone persistidos de forma assíncrona.

Exemplos

images = await client.list_images_async(
    user_id="u1",
    limit=10,
)
[image.id for image in images]
['img-1']

método list_memories

Listar registros semelhantes à memória persistente.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_memory("User likes pizza.", user_id="u1", memory_id="mem-1")
'mem-1'
[record.id for record in client.list_memories(user_id="u1", limit=10)]
['mem-1']

método list_memories_async (assíncrono)

Liste registros semelhantes à memória persistida de forma assíncrona.

Exemplos

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_memory_async("User likes pizza.", user_id="u1", memory_id="mem-1")
    records = await client.list_memories_async(user_id="u1", limit=10)
    return [record.id for record in records]
anyio.run(main)
['mem-1']

método list_messages

Listar registros de mensagens de chat persistidas.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
thread = client.create_thread(thread_id="c1", user_id="u1")
message_id = thread.add_messages([{"role": "user", "content": "Hello"}])[0]
[record.id for record in client.list_messages(thread_id="c1", limit=10)] == [message_id]
True

método list_messages_async (assíncrono)

Listar registros de mensagem de chat persistidos de forma assíncrona.

Exemplos

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    thread = await client.create_thread_async(thread_id="c1", user_id="u1")
    message_ids = await thread.add_messages_async(
        [{"role": "user", "content": "Hello"}]
    )
    records = await client.list_messages_async(thread_id="c1", limit=10)
    return [record.id for record in records] == message_ids
anyio.run(main)
True

método list_threads

Listar tópicos de conversas persistidas.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.create_thread(thread_id="c1", user_id="u1").thread_id
'c1'
[record.thread_id for record in client.list_threads(user_id="u1", limit=10)]
['c1']

método list_threads_async (assíncrono)

Listar tópicos de conversas persistidas de forma assíncrona.

Exemplos

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.create_thread_async(thread_id="c1", user_id="u1")
    records = await client.list_threads_async(user_id="u1", limit=10)
    return [record.thread_id for record in records]
anyio.run(main)
['c1']

método list_users

Listar registros de perfil de usuário persistidos.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u1", "Prefers concise answers.", metadata={"source": "crm"})
'u1'
[record.id for record in client.list_users(metadata_filter={"source": "crm"})]
['u1']

método list_users_async (assíncrono)

Liste registros de perfil de usuário persistidos de forma assíncrona.

Exemplos

import anyio
from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
async def main():
    await client.add_user_async(
        "u1",
        "Prefers concise answers.",
        metadata={"source": "crm"},
    )
    records = await client.list_users_async(metadata_filter={"source": "crm"})
    return [record.id for record in records]
anyio.run(main)
['u1']

Pesquise de forma síncrona registros relevantes para uma consulta.

Observações

Os valores explícitos do escopo None ainda seguem as regras de correspondência exata resolvidas: exact_*_match=False deixa essa dimensão sem restrições, enquanto exact_*_match=True corresponde apenas a registros sem escopo nessa dimensão.

método search_async (assíncrono)

Pesquise registros relevantes para uma consulta de forma assíncrona.

Observações

Os valores explícitos do escopo None ainda seguem as regras de correspondência exata resolvidas: exact_*_match=False deixa essa dimensão sem restrições, enquanto exact_*_match=True corresponde apenas a registros sem escopo nessa dimensão.

método update_image

Atualizar um registro de imagem armazenado por identificador.

Observações

Os campos omitidos permanecem inalterados. As atualizações de escopo não são suportadas por esta API. A substituição de metadados é uma substituição de objeto inteiro, não uma mesclagem JSON recursiva.

método update_image_async (assíncrono)

Atualize uma imagem independente por meio do armazenamento configurado.

Omita image para preservar os bytes existentes. Se image for fornecido, mime_type deverá ser fornecido com ele. Omita description para preservar a descrição existente. Informe None para gerar uma nova descrição com o LLM configurado; uma descrição não nula a substitui diretamente. As definições de metadados, timestamp e expiração são atualizadas quando fornecidas.

método update_memory

Atualizar um registro de memória armazenada por identificador.

Observações

Os campos omitidos são preservados do registro armazenado. O escopo armazenado permanece inalterado. A substituição de metadados é uma substituição de objeto inteiro, não uma mesclagem JSON recursiva.

método update_memory_async (assíncrono)

Atualizar um registro semelhante à memória armazenada por identificador de forma assíncrona.

Observações

Os campos omitidos são preservados do registro armazenado. O escopo armazenado permanece inalterado. A substituição de metadados é uma substituição de objeto inteiro, não uma mesclagem JSON recursiva.

Exemplos

import asyncio
memory_id = asyncio.run(client.add_memory_async("Original memory"))
(
    asyncio.run(client.update_memory_async(
        memory_id, content="Updated memory"
    ))
    == memory_id
)
True

Atualizar campos mutáveis de uma relação armazenada.

Os valores omitidos são preservados. Quando relation_type muda para um tipo de relação de memória incorporado, seu label reverso fixo substitui opposite_relation_type. Informe None para timestamp ou metadata para limpar esse valor.

Exemplos

client.update_record_link("relation-id", relation_type="supports")
1

Atualizar assincronamente uma relação armazenada.

método update_thread

Persistir metadados de thread e atualizações duráveis de configuração de runtime.

Observações

A configuração de runtime é resolvida do thread de conversa armazenado mais as substituições explícitas especificadas para esta chamada, correspondendo à semântica get_thread antes de persistir o resultado. Os metadados omitidos e as atualizações de configuração de runtime são resolvidos com base em dados armazenados, não de qualquer instância OracleThread carregada anteriormente, e somente as atualizações de metadados fornecidas explicitamente ou as substituições duráveis de configuração de runtime são gravadas de volta. A substituição de metadados é uma substituição de objeto inteiro, não uma mesclagem JSON recursiva. A propriedade do thread não pode ser alterada por meio dessa API; portanto, user_id e agent_id permanecem inalterados. O estado de tempo de execução mutável, como contadores de extração, é deixado intocado.

Exemplos

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
updated = client.update_thread(
    "c1",
    metadata={"flags": {"vip": True}},
    message_shortening_input_token_limit=12_000,
)
updated.message_shortening_input_token_limit
12000

método update_thread_async (assíncrono)

Persistir metadados de thread atualizados e configuração de runtime durável de forma assíncrona.

método wait_for_memory_extraction

Aguarde a extração anterior da memória em segundo plano iniciada por este cliente.

Este método aguarda a extração em segundo plano já iniciada por meio desta instância do OracleAgentMemory, em todos os threads pertencentes a este componente de memória do agente. Ele não aguarda o início da extração após o início dessa espera, a extração iniciada por outro componente de memória do agente ou a extração em execução em outro processo. As falhas de extração contam como concluídas para esta espera.

Exemplos

client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    memory_extraction_config=MemoryExtractionConfig(extract_memories=False),
)
client.wait_for_memory_extraction(timeout=10)

método wait_for_memory_extraction_async (assíncrono)

Aguarde assincronamente a extração de memória em segundo plano anterior.

Este método segue o mesmo comportamento de wait_for_memory_extraction().

Exemplos

import asyncio
asyncio.run(client.wait_for_memory_extraction_async(timeout=10))

Limites de Entrada de Imagem

classe oracleagentmemory.core.ImageInputLimitConfig

Bases: object

Configurar limites de solicitação de imagem bruta e LLM.

Os campos omitidos herdam do próximo escopo de configuração mais amplo. Os campos do cliente herdam os padrões do SDK, enquanto os campos por thread herdam a configuração do cliente. A validação não pode ser desativada e os valores resolvidos não podem exceder o máximo absoluto do SDK.

Exemplos

from oracleagentmemory.core import ImageInputLimitConfig
config = ImageInputLimitConfig(
    max_raw_image_bytes=16 * 1024 * 1024,
    max_images_per_llm_request=200,
)

Extração de memória

classe oracleagentmemory.core.MemoryExtractionImageContext

Bases: str, Enum

Selecione como as imagens participam da extração automática de memória.

DISABLED omite imagens e descrições de imagens dos prompts de extração. IMAGE envia partes da imagem original. CAPTION envia descrições de imagem como texto e requer que cada imagem selecionada tenha uma descrição em branco.

CAPTION = 'legenda'

Inclua descrições como texto e exija uma para cada imagem selecionada.

DISABLED = 'desativado'

Não inclua imagens ou descrições de imagens em prompts de extração.

IMAGEM = 'imagem'

Incluir partes da imagem original em prompts de extração.

MEMÓRIA = 'memória'

A extração de memória específica da imagem não é suportada no momento.

classe oracleagentmemory.core.MemoryExtractionConfig

Bases: object

Configurações agrupadas para extração automática de memória.

Informe este objeto para OracleAgentMemory, create_thread, get_thread ou update_thread para configurar a extração automática. extraction_mode e as definições da fila de segundo plano também controlam a geração automática de descrição de imagem. Cada campo é calculado de forma independente. Um valor fornecido para uma operação tem precedência, seguido por um valor de thread salvo, o valor do cliente e o padrão do SDK. Threads novos e stand-alone não têm valor de thread salvo.

Exemplos

from oracleagentmemory.core import (
    MemoryExtractionImageContext,
    MemoryExtractionConfig,
    MemoryExtractionMode,
    MemoryLinkExtractionMode,
)
config = MemoryExtractionConfig(
    extract_memories=True,
    memory_extraction_image_context=MemoryExtractionImageContext.CAPTION,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
    memory_link_extraction_mode=MemoryLinkExtractionMode.POST_EXTRACTION,
    memory_link_extraction_token_limit=8_000,
)

O que fazer quando as descrições de extração ou imagem não podem ser enfileiradas imediatamente.

Os valores omitidos são resolvidos para DROP.

O trabalho em segundo plano de segundos máximo aguarda a capacidade da fila nos modos de espera.

Os valores omitidos são resolvidos para 300.0 segundos.

Mensagens após o último resumo válido antes da atualização automática.

Valores menores ou iguais à atualização 0 em cada verificação.

Se o OAM mantém resumos de contexto para leituras de thread e prompts de extração.

Se as descrições de extração e imagem são executadas em linha ou em segundo plano.

Os valores omitidos são resolvidos para BACKGROUND.

Mensagens entre execuções de extração; valores abaixo da extração 0 após cada apêndice.

Representação de imagem; a omissão é resolvida como thread, cliente e depois como DISABLED.

Metadados de mensagem de origem copiados em memórias extraídas.

Orçamento de token de entrada para prompts; valores abaixo de 1 desativam o limite.

Janela de mensagens recentes usada para prompts de extração; -1 usa somente novas mensagens.

Instruções opcionais do chamador anexadas a prompts automáticos de resolução de vínculo.

Como os links automáticos são resolvidos para memórias extraídas.

Os valores omitidos são resolvidos para POST_EXTRACTION.

Orçamento total do token de entrada para resolução do link POST_EXTRACTION.

Os valores abaixo de 1 desativam o limite.

classe oracleagentmemory.core.MemoryExtractionMode

Bases: str, Enum

Controla quando a extração automática e as descrições de imagem são executadas.

INLINE conclui o trabalho derivado antes do retorno do método de gravação. BACKGROUND retorna depois que a gravação bruta é bem-sucedida e tenta enfileirar esse trabalho. O trabalho de fundo é o melhor esforço: descrições geradas e memórias derivadas podem aparecer mais tarde ou nunca podem ser escritas se não puderem ser concluídas.

PLANO DE FUNDO = 'CONTEXTO'

Retorne após a gravação bruta e execute o trabalho derivado em segundo plano.

EM LINHA = 'EM LINHA'

Conclua as descrições de extração e imagem antes que a gravação seja retornada.

classe oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

Bases: str, Enum

Controla o que acontece quando o trabalho em segundo plano configurado não pode ser enfileirado no tempo.

Apesar do nome específico da extração, essa configuração também se aplica à geração automática de descrição de imagem no modo de fundo.

ELIMINAR = 'ELIMINAR'

Registre um aviso e continue imediatamente quando a capacidade da fila estiver indisponível.

WAIT_THEN_DROP = 'WAIT_THEN_DROP'

Aguarde a capacidade da fila até o timeout configurado, registre um aviso e continue.

WAIT_THEN_RAISE = 'WAIT_THEN_RAISE'

Aguarde a capacidade da fila até o timeout configurado e, em seguida, gere TimeoutError.