代理内存入门

本文将指导您安装代理内存并执行基本的内存操作，包括存储和检索用户上下文。

先决条件

确保您具有：

Oracle AI Database 功能要求

Oracle Agent Memory 的数据库支持存储需要 Oracle AI Database 23ai 或更高版本（数据库版本 23.4 或更高版本）。对于 Oracle AI Vector Search，请将数据库 COMPATIBLE 初始化参数设置为 23.4.0 或更高版本。

所选搜索策略具有以下附加要求：

在托管模式初始化期间，Oracle 代理内存会在运行 DDL 之前验证连接的数据库版本，并在所选搜索策略不可用时报告升级操作。

托管数据库设置

方案所有者创建或重新创建内存存储时，Oracle Agent Memory Python 程序包会准备所需的托管数据库对象。所有者需要 Oracle CREATE TABLE 和 CREATE PROCEDURE 系统权限。

作为方案设置的方案所有者进行连接。使用 schema_owner 的应用程序连接访问现有存储，并且必须使用 SchemaPolicy.REQUIRE_EXISTING；它不会创建或更新所有者的托管数据库对象。

安装 SDK

您可以在软件下载页面中找到 oracleagentmemory 的所有版本和支持平台。

要安装代理内存，请运行：

pip install "oracleagentmemory==26.8.0"

使用 pip 进行安装时，将在支持的平台上提取预构建的二进制轮。

日志记录和故障诊断

Oracle AI Agent Memory 通过以 oracleagentmemory 开头的日志记录程序名称下的标准 Python 日志记录发出诊断消息。SDK 不配置处理程序或日志级别；应用可以将这些日志路由到其现有控制台、文件或观测管道。一些日志记录使用 Python 日志记录的 extra 字段进行安全的结构化诊断，结构化日志处理程序可以捕获这些信息。

import logging

logging.basicConfig(level=logging.INFO)
logging.getLogger("oracleagentmemory").setLevel(logging.INFO)

要在受控环境中进行故障排除，请启用 DEBUG 日志：

logging.getLogger("oracleagentmemory").setLevel(logging.DEBUG)

使生产部署保持在非 DEBUG 级别。DEBUG 日志用于开发和支持诊断，不应将日志消息文本视为稳定的公共 API。

生存时间和到期记录清除

Oracle DB 支持的消息和内存可以通过在写入和更新 API 上组合使用模式级别的保留默认值和每记录 ttl_days/ttl_anchor 值来自动失效。

当 Oracle Agent Memory 创建或升级其托管方案时，它还会创建每日 DBMS_SCHEDULER 清除作业，以物理方式删除已失效的行、其检索块和不再存在其支持的源行的孤立检索块。如果方案设置需要创建该作业，但数据库用户缺少 CREATE JOB，则设置完成时会发出警告：过期的行仍会从读取和搜索中过滤掉，但是在特权用户创建作业之前，过期的和孤立的块不会被物理清除。在 SchemaPolicy.REQUIRE_EXISTING 下，允许在 DEBUG 级别记录缺少的清除作业。

Linked-memory 方案还创建一个触发器，用于在删除链接后重新验证保留的内存，包括清除作业删除过期内存并 Oracle 级联其链接时。方案所有者在创建或升级方案期间需要 CREATE TRIGGER；普通运行时用户不需要该权限。

有关完整保留模型、MemoryRetentionConfig 设置、清除作业验证查询、手动 DBA 作业创建以及使用 TimeToLiveAnchor 的 Python 示例，请参见 Use Time-to-Live for Messages and Memories 。

链接内存模式权限

链接内存方案包括一个 Oracle SQL 属性图和一个数据库触发器，用于在删除链接时使生命周期状态保持正确。

如果设置 memory_store_id，则托管图形名称的前缀与表相同。例如，memory_store_id="SALES" 创建 SALES_MEMORY_GRAPH。

APP_SCHEMA 和 APP_USER 值是占位符。将它们替换为数据库用户名。这些示例使用大写，因为未加引号的 Oracle 标识符以大写形式存储。

  1. 在方案设置期间，请授予方案所有者 CREATE PROPERTY GRAPH 和 CREATE TRIGGER。每当必须创建受管图形或链接删除触发器时，在 SchemaPolicy.CREATE_IF_NECESSARY 或 SchemaPolicy.RECREATE 中都需要这些值。 
    GRANT CREATE PROPERTY GRAPH TO APP_SCHEMA;
GRANT CREATE TRIGGER TO APP_SCHEMA;
-- Run OracleAgentMemory schema setup as APP_SCHEMA.
REVOKE CREATE PROPERTY GRAPH FROM APP_SCHEMA;
REVOKE CREATE TRIGGER FROM APP_SCHEMA;

    如果此升级需要创建或重新创建托管图形或链接删除触发器，请在以后进行 SDK 升级之前再次授予它们。

  2. 在正常应用程序运行时，确定哪个用户连接到 Oracle：
    • 如果运行时用户为 APP_SCHEMA，则不需要额外的图形授权。图形所有者可以访问自己的图形。
    • 如果运行时用户不同，请在方案设置后以 APP_SCHEMA 身份运行以下命令。默认图形名称为 MEMORY_GRAPH；设置 memory_store_id 时使用前缀名称。 
      GRANT SELECT ON PROPERTY GRAPH APP_SCHEMA.MEMORY_GRAPH TO APP_USER;

      运行时用户还需要 Oracle Agent Memory 部署的其余部分所需的常规数据库访问。

SchemaPolicy.REQUIRE_EXISTING 将跳过第一步，因为它预计图形和触发器已存在。单独的运行时用户仍需要访问托管属性图。

初始化内存实例

通过配置嵌入器、LLM 和数据库连接来创建 OracleAgentMemory 实例。

import oracledb

from oracleagentmemory.core import SchemaPolicy
from oracleagentmemory.core.oracleagentmemory import OracleAgentMemory
from oracleagentmemory.apis.searchscope import SearchScope
from oracleagentmemory.core.embedders.embedder import Embedder
from oracleagentmemory.core.llms.llm import Llm

embedder = Embedder(model="YOUR_EMBEDDING_MODEL")
llm = Llm(model="YOUR_LLM")
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
memory = OracleAgentMemory(
    connection=db_pool,
    embedder=embedder,
    llm=llm,
    schema_policy=SchemaPolicy.CREATE_IF_NECESSARY,
    memory_store_id="T_GET_STARTED",
)

注：默认情况下，托管 Oracle AI Database 方案不会为消息和内存设置保留期。配置 MemoryRetentionConfig 或每条记录的生存时间设置以使用不同的保留期。有关更多信息，请参见 Use Time-to-Live for Messages and Memories 。

存储内存条目

首先为用户创建线程、添加消息和存储内存条目。

messages = [
    {
        "role": "user",
        "content": (
            "Orange juice has become my favorite breakfast drink lately, "
            "what can I pair it with?"
        ),
    },
    {
        "role": "assistant",
        "content": (
            "Nice! Orange juice goes great with something savory. "
            "Try eggs and toast, avocado toast, or a breakfast sandwich."
        ),
    },
]

thread = memory.create_thread(user_id="user_123")
#add_messages will add messages to the DB and extract memories automatically
thread.add_messages(messages)
#add_memory adds memory to the DB
thread.add_memory("The user likes orange juice with breakfast.")

检索内存条目

使用用户范围的查询搜索内存。

results = memory.search(query="orange juice", scope=SearchScope(user_id="user_123"))
for result in results:
    print(f"- [{result.record.record_type}] {result.content}")

输出：

- [memory] The user likes orange juice with breakfast.
- [message] Orange juice has become my favorite breakfast drink lately, what can I pair it with?
- [message] Nice! Orange juice goes great with something savory. Try eggs and toast,
            avocado toast, or a breakfast sandwich.

注：显示的输出具有说明性。将来的版本可能会返回其他结果类型、字段或排序。

模型兼容性

以下大型语言模型 (LLM) 和嵌入模型与 oracleagentmemory 兼容。

LLM

已确认以下大型语言模型 (LLM) 兼容。

OCI 托管的模型

OpenAI

自托管 LLM

人造

双子座

嵌入

已确认以下嵌入模型兼容。

OCI 托管的模型

OpenAI

自主托管 LLM

双子座