代理内存

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

Oracle 代理内存

class `oracleagentmemory.core.OracleAgentMemory`

基础：IAgentMemory

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

创建内存客户机。

参数：
- store OracleMemoryStore- 可选的预配置存储实例。如果提供，客户机将直接使用此存储，而不是实例化自己的存储。当调用者需要 OracleAgentMemory 公开的构造器选项之外的存储配置时，这非常有用。
- connection object- 可选的 Oracle DB 连接/池。如果提供，则使用数据库存储。通过原始连接可为此客户机实例启用单会话模式，因此并发请求应改用连接池。省略时，调用者必须传递显式 store。
- embedder IEmbedder | str- 嵌入器实现实例或 LiteLLM 嵌入模型标识符。省略时，不会附加任何嵌入器，调用者必须通过较低级别的存储 API 提供预计算的向量。
- LLM ILlm- 线程用于内存提取和/或上下文汇总的可选 LLM 适配器。默认情况下，从此客户机创建或加载的线程需要 LLM，因此可以挖掘最近的消息以获得持久的内存。在此处传递 llm，稍后在 create_thread 中提供，或选择退出 extract_memories=False。
- extract_memories bool- 当 True 时，由此客户机创建或装入的线程需要 LLM，并且自动内存提取仍处于启用状态。设置为 False 可禁用自动内存提取，并允许这些线程在没有 LLM 的情况下运行。默认值为 True，因此缺少提取 LLM 会快速失败。
- schema_policy SchemaPolicy | str- 仅当从 connection 构造数据库存储时才使用的数据库方案设置策略。默认值为 SchemaPolicy.REQUIRE_EXISTING。
- table_name_prefix str- 仅当从 connection 构造数据库存储时才使用的可选数据库表/索引前缀。
引发：ValueError - 如果提供了冲突的存储配置，例如传递 store 和 connection、不带数据库连接的特定于数据库的选项，或者同时忽略 store 和 connection。

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
read_only_client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    extract_memories=False,
)

method `add_agent`

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

参数：
- agent_id str- 代理标识符。
- information str- 关于代理的自由格式信息。
返回：存储的代理配置文件的标识符。
返回类型： str

注

代理概要信息记录存储在客户端级存储中。

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_agent("a1", "Support assistant")
'a1'

method `add_memory`

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

参数：
- content str- 要持久保留的内存内容。
- user_id str- 与存储的内存关联的可选范围标识符。
- agent_id str- 与存储的内存关联的可选作用域标识符。
- thread_id str- 与存储的内存关联的可选作用域标识符。
- memory_id str- 可选的调用方为此内存行提供的稳定标识符。
- **store_kwargs ( Any )- 转发到后备存储的特定于存储的写入选项。
返回：插入的内存记录的标识符。
返回类型： str

示例

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

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

参数：
- user_id str- 用户标识符。
- information str- 关于用户的自由格式信息。
返回：存储的用户配置文件的标识符。
返回类型： str

注

用户配置文件记录存储在客户端级存储中（不与特定线程关联）。

示例

from oracleagentmemory.core import OracleAgentMemory
client = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
)
client.add_user("u1", "Prefers concise answers.")
'u1'

method `create_thread`

创建并注册主题。

参数：
- thread_id str- 线程标识符。如果省略，将生成一个新的。
- user_id str- 附加到此线程记录的用户标识符。如果省略，将生成一个新的。
- agent_id str- 附加到此线程记录的代理标识符。如果省略，将生成一个新的。
- LLM ILlm- 此线程的可选 LLM 覆盖。如果省略，则使用在构建时配置的客户机级 LLM。缺省情况下，客户机或线程必须提供 LLM，以便可以运行自动内存提取。在此处或客户端上设置 extract_memories=False 以选择退出该要求。
- extract_memories bool- 自动内存提取的可选每线程覆盖。当 True 时，此线程需要 LLM，因此可以运行自动提取。设置为 False 可对此线程禁用自动提取并允许在没有 LLM 的情况下执行操作。省略时，将使用客户机级 extract_memories 设置。
- max_message_token_length int- 内存提取和上下文摘要更新期间截断或汇总之前的最大提示时间消息大小。存储的消息内容保持不变。省略时，默认为 15_000 标记。
- message_shortening_input_token_limit int- 缩短超大提示时间消息复制时发送到 LLM 的消息摘录的最大大小（以令牌表示）。省略时，默认为 30_000 标记。
- memory_extraction_window int- 内存提取期间要包含的最近消息数。设置为 -1 可使用新添加的全部消息批对每个 add_messages 调用执行一次提取。如果省略，则默认为 -1。
- context_summary_update_frequency int- 上下文摘要刷新的频率。设置为 -1 可使用新添加的全部消息批对每个 add_messages 调用执行一次摘要更新。对于在 add_messages 期间刷新的线程汇总元数据，会重复使用相同的节奏。如果省略，则默认为 4。
- memory_extraction_frequency int- 内存提取更新的频率。设置为 -1 可使用新添加的全部消息批对每个 add_messages 调用执行一次提取。如果省略，则默认为 -1。
- memory_extraction_token_limit int- 标记中的最大提取提示大小。如果省略，则默认为 100_000。
- enable_context_summary bool- 是否保留此线程的正在运行的上下文摘要。
- **kwargs ( Any )- 其他特定于实现的线程选项。
返回：OracleThread 。
返回类型：OracleThread
引发：ValueError - 如果没有 LLM 可用于自动内存提取，并且线程和客户机未配置 extract_memories=False。

示例

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

按标识符删除内存记录。

参数：memory_id str- 内存标识符。
返回数：已删除的内存行数（0 或 1）。
返回类型： int

示例

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

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

参数：
- thread_id str- 要删除的线程标识符。
- allow_non_existing bool- 当 True 时，删除缺少的线程将被视为 no-op。
返回数：已删除的线程行数（0 或 1）。
返回类型： int

示例

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

检索以前创建的线程。

参数：
- thread_id str- 创建线程时使用的标识符。
- LLM ILlm- 重新打开的线程的可选 LLM 覆盖。省略时，将使用在构建时配置的客户机级 LLM。
- extract_memories bool- 用于在重新打开的线程上自动提取内存的可选覆盖。如果省略，则使用客户机级 extract_memories 设置。
- max_message_token_length int- 内存提取和上下文摘要更新期间截断或汇总之前的最大提示时间消息大小的可选覆盖。存储的消息内容保持不变。
- message_shortening_input_token_limit int- 在缩短超大提示时间消息复制时发送到 LLM 的消息摘录的最大大小（以令牌表示）的可选覆盖。
- memory_extraction_window int- 内存提取期间使用的最近消息数的可选覆盖。
- context_summary_update_frequency int- 上下文摘要刷新频率的可选覆盖。
- memory_extraction_frequency int- 内存提取更新频率的可选覆盖。
- memory_extraction_token_limit int- 标记中最大提取提示大小的可选覆盖。
- enable_context_summary bool- 对于重新打开的线程是否应保留正在运行的上下文摘要的可选覆盖。
返回：从存储元数据重建的线程句柄。
返回类型：OracleThread
增加：
- KeyError - 如果此客户机实例不知道线程 ID。
- ValueError - 如果没有 LLM 可用于自动内存提取，并且客户机未配置 extract_memories=False。

注

显式每次调用覆盖优先。省略运行时覆盖时，重新打开的线程将在可用时使用持久运行时配置，然后再回退到 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'

代理内存

Oracle 代理内存

class oracleagentmemory.core.OracleAgentMemory

method add_agent

method add_memory

method add_user

method create_thread

method delete_memory

method delete_thread

method get_thread