代理内存

本页介绍具体的 Oracle AI Agent Memory 实施。

Oracle 代理内存

注：OracleAgentMemory.delete_thread() 是线程范围级联清除支持的路径。它将删除线程以及关联的消息、持久存储和托管检索数据。这比 OracleThread.delete_message() 更宽，后者仅删除原始消息行。在删除线程之前，它将等待此客户机已知的该线程的先前接受的后台提取。在删除过程中，它不会序列化同一线程的每个并发操作。

class oracleagentmemory.core.OracleAgentMemory

基础：IAgentMemory

由 Oracle DB 或呼叫方提供的存储支持的代理内存客户机。

创建内存客户机。

警告：SchemaPolicy.CREATE_IF_NECESSARY 可能比普通客户端启动贵，因为它可能会在初始化成功之前应用托管方案 DDL 和尽力重写数据。在旧托管方案包含多个行时，将首次打开的托管方案计划为迁移或维护操作。

如果方案设置必须创建托管的过期记录清除作业，但数据库用户缺少调度程序 - 作业权限，则初始化将警告并继续。过期的消息和记忆不会被读取和搜索隐藏，但是在具有 CREATE JOB 或等效调度程序权限的用户创建作业之前，这些消息和记忆不会被物理清除。

当 SchemaPolicy.CREATE_IF_NECESSARY 首次在现有方案上创建托管混合索引时，Oracle 会扫描存储的搜索文本，并从配置的数据库内模型构建托管混合索引状态。客户机启动将等待该 DDL 完成，因此，请计划第一次将混合升级作为大型方案的迁移或维护操作。SearchIndexSyncMode 控制索引存在后正在进行的维护；它不会使第一个索引构建异步。

示例

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

使用数据库内嵌入模型利用 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,
)

method add_agent

将座席概要信息记录添加到门店。

注

代理概要信息记录存储在客户端级存储中，并有意取消范围。返回的记录标识符与应用程序用作 agent_id 的公共标识符相同。

示例

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

method add_memory

在内存系统中添加内存，该内存归属于指示的用户、代理和线程。

示例

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'

method add_memory_async（异步）

将内存记录异步添加到客户机。

method add_user

将用户概要信息记录添加到门店。

注

用户概要信息记录存储在客户端级存储中，并且有意取消范围。返回的记录标识符与应用程序用作 user_id 的公共标识符相同。

示例

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'

method close

关闭代理内存组件。

关闭将停止接受新的后台提取工作，并等待暂挂的后台内存提取以完成到配置的超时。如果该超时到期，即使某些后台提取工作仍未完成，close() 也会返回。方法是幂等的。

示例

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

method close_async（异步）

异步关闭代理内存组件。

此方法遵循与 close() 相同的关闭行为。如果超时到期，则可以在后台提取工作仍在运行时返回。

示例

await client.close_async()

method create_thread

创建并注册线程。

示例

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'

method delete_agent

按标识符删除代理概要记录。

注

级联删除是在后备存储内计划和执行的，因此概要信息删除和所有范围的子删除都在一个存储操作中发生。在运行级联删除之前，此方法将等待先前已通过此代理内存组件接受的所有线程的后台提取。它不等待等待等待开始后接受的工作，也不等待其他代理内存组件或进程启动的工作。不支持在删除过程中同时使用操作者范围。

示例

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

method delete_memory

按标识符删除类似内存的记录（例如，内存、事实、首选项或准则）。

示例

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

method delete_memory_async（异步）

按标识符异步删除类似内存的记录（例如，内存、事实、首选项或准则）。

method delete_thread

删除与线程标识符关联的所有记录。

注

需要保留完成删除线程时，请使用此操作。后备存储将删除线程以及关联的线程范围消息、持久存储器和托管检索数据。This differs from OracleThread.delete_message(), which removes only the raw message record and does not cascade to derived memories created from that message. 在删除线程之前，此方法将等待已通过此代理内存组件为该线程接受的早期后台提取。它不会等待等待等待开始后接受的后台工作，也不会等待其他代理内存组件或进程启动的工作。不支持在删除过程中同时使用同一线程。

示例

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

method delete_user

按标识符删除用户概要记录。

注

级联删除是在后备存储内计划和执行的，因此概要信息删除和所有范围的子删除都在一个存储操作中发生。在运行级联删除之前，此方法将等待先前已通过此代理内存组件接受的所有线程的后台提取。它不等待等待等待开始后接受的工作，也不等待其他代理内存组件或进程启动的工作。不支持在删除过程中同时使用操作者范围。

示例

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

method get_thread

检索以前创建的线程。

注

显式每次调用覆盖优先。省略运行时覆盖时，重新打开的线程将在可用时使用持久运行时配置，然后再回退到 SDK 默认值。

示例

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

同步搜索与查询相关的记录。

注

显式 None 范围值仍遵循已解析的确切匹配规则：exact_*_match=False 保持该维不受约束，而 exact_*_match=True 仅匹配该维上未定义的记录。

method search_async（异步）

异步搜索与查询相关的记录。

注

显式 None 范围值仍遵循已解析的确切匹配规则：exact_*_match=False 保持该维不受约束，而 exact_*_match=True 仅匹配该维上未定义的记录。

method update_memory

按标识符更新存储的类似内存的记录。

注

省略的字段将从存储的记录中保留。存储的范围保持不变。元数据替换是整个对象替换，而不是递归 JSON 合并。

method update_memory_async（异步）

按标识符异步更新存储的类似内存的记录。

注

省略的字段保持不变。此 API 不支持范围更新。元数据替换是整个对象替换，而不是递归 JSON 合并。

method update_thread

持久保存线程元数据和持久的运行时配置更新。

注

运行时配置通过存储的对话线程解析，加上传递给此调用的显式覆盖，匹配 get_thread 语义，然后再保留结果。省略的元数据和运行时配置更新是从存储的数据（而不是从任何以前加载的 OracleThread 实例）解析的，并且仅写入显式提供的元数据更新或持久的运行时配置覆盖。元数据替换是整个对象替换，而不是递归 JSON 合并。线程所有权通过此 API 不可变，因此 user_id 和 agent_id 保持不变。可变运行时状态（例如提取计数器）保持不变。

示例

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

method wait_for_memory_extraction

等待此客户机启动更早的后台内存提取。

此方法等待已通过此 OracleAgentMemory 实例在此代理内存组件拥有的所有线程中启动的后台提取。它不等待此等待开始后启动提取，不等待其他代理内存组件启动提取，也不等待在另一个进程中运行的提取。此等待的提取失败计数为已完成。

示例

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

method wait_for_memory_extraction_async（异步）

异步等待更早的后台内存提取。

此方法遵循与 wait_for_memory_extraction() 相同的行为。

示例

await client.wait_for_memory_extraction_async(timeout=10)

内存提取

class oracleagentmemory.core.MemoryExtractionConfig

基准：object

用于自动内存提取的分组设置。

将此对象传递到 OracleAgentMemory、create_thread、get_thread 或 update_thread 以配置自动提取。省略的字段从下一个更广泛的设置继承。例如，不使用 memory_extraction_frequency 创建的线程使用代理内存组件默认值，组件默认值回退到 SDK 默认值。

示例

from oracleagentmemory.core import MemoryExtractionConfig, MemoryExtractionMode
config = MemoryExtractionConfig(
    extract_memories=True,
    extraction_mode=MemoryExtractionMode.BACKGROUND,
)

class oracleagentmemory.core.MemoryExtractionMode

基础：str、Enum

控制自动内存提取工作何时运行。

INLINE 在写入方法返回之前运行自动提取。原始写入成功后，BACKGROUND 将返回，并尝试在后台执行适当的提取工作。背景提取是最好的努力：派生的记忆可能稍后出现，或者如果背景工作无法完成，可能永远不会写。

后台 = ‘ BACKGROUND ’

原始消息持久化后返回，并在后台工作中运行尽力提取。

内嵌 = ‘ INLINE ’

在 write 方法返回之前运行提取。

class oracleagentmemory.core.BackgroundExtractionQueueFullBehavior

基础：str、Enum

控制在后台提取无法及时排队时发生的情况。

删除 = ‘ DROP ’

记录警告，并在队列容量不可用时立即继续。

WAIT_THEN_DROP = ‘ WAIT_THEN_DROP ’

等待队列容量达到配置的超时，然后记录警告并继续。

WAIT_THEN_RAISE = ‘ WAIT_THEN_RAISE ’

等待队列容量达到配置的超时，然后引发 TimeoutError。