安全注意事项

范围：本文档介绍了与 Oracle AI Agent Memory Python SDK 相关的安全注意事项。它适用于使用 SDK 的活动内存功能或仅使用存储层的应用程序。

重要性：Oracle AI Agent Memory 可以在 Oracle Database 中持久保存线程内容和内存记录，并且在启用 LLM 支持的功能时，将内容发送到配置的模型端点以进行汇总、内存提取或嵌入。因此，安全部署取决于对应用数据、检索范围、数据库访问、外部模型端点和保留策略的仔细处理。

有关 LLM 支持的内存处理的注意事项

Oracle AI Agent Memory 支持主动内存功能，例如线程汇总和自动内存提取。启用这些功能后，SDK 可能会向配置的 LLM 或嵌入端点发送最近的消息、线程摘要、检索的内存或搜索文本。

重要提示：仅将适合已配置模型端点和部署策略的内容发送到 Oracle AI 代理内存。如果为显示包含密钥、凭证或不必要的敏感数据的数据启用了活动内存，则在消息进入内存管道之前，应尽量减少或编写该内容。将提取的记忆、摘要、上下文卡和其他模型推导的文本视为不可信的输出，必须通过集成应用程序安全地进行审查和处理。

警告：模型派生的文本可以变为持久内存状态。启用自动提取、汇总或上下文卡功能后，SDK 可以将汇总、提取的内存或检索的记录插入到以后的提示中，例如内存提取、汇总、上下文卡或代理提示，然后应用程序才能查看该特定中间值。将此视为正常的不可信 LLM 数据流：检查并验证应用程序使用的输出，不要让内存派生的内容授权特权操作或绕过策略。

使用活动内存功能时，请遵循以下建议：

• 验证和最小化应用数据：查看应用向 SDK 发送的消息、元数据和 ID。避免传递比内存工作流所需的更多数据。
• 使用可信模型端点：配置 LLM 并嵌入满足传输安全、数据驻留、保留和操作监视要求的端点。
• 将生成的内存作为应用程序数据和不可信输出进行处理：提取的内存、摘要和上下文卡是派生的输出。查看应用如何使用它们，尤其是在它们影响特权操作、外部工具调用或客户可见决策之前。
• 仅在可接受延迟派生写入时选择异步提取：在后台模式下，原始消息写入可以在写入派生内存、摘要或相关运行时状态之前完成。如果工作流在模型派生状态成为持久状态之前需要复查或更严格的提交边界，请对该工作流使用内嵌提取或禁用自动提取。
• 持久提示注入帐户：内存中存储的呼叫者提供的、检索的或模型推导的文本可以重放到以后的汇总、提取、上下文卡或代理提示中。提示分隔符、转义和提取指令可以帮助构建模型输入，但它们不是安全边界。在依赖提取的记忆、摘要、上下文卡和其他持久性或提示性中间文本之前，先查看它们。如果在模型推导的文本影响将来的提取或上下文构造之前，您的工作流需要复查，请禁用自动提取并使用显式内存写入或其他应用程序控制的复查门。
• 清理或转义其目的地的派生文本：如果提取的内存、摘要、上下文卡或其他模型派生文本呈现为 HTML、Markdown、模板、日志或其他输出表面，则应用与上下文相关的转义或清理。在下游提示、工具输入、命令或其他类似解释器的上下文中重复使用派生文本之前，请使用相同的注意事项。
• 选择正确的操作模式：如果您的应用需要在模型派生文本影响以后提取或上下文构造之前进行审核，请考虑使用显式内存写入、仅存储集成，或者对不应执行自动提取的工作流使用 memory_extraction_config=MemoryExtractionConfig(extract_memories=False)。

关于持久性和数据最小化的注意事项

Oracle AI Agent Memory 设计用于在使用数据库支持的存储时在 Oracle Database 中持久保存消息、内存、元数据和嵌入。这允许持久的检索和跨会话内存，但也意味着应用程序应该计划哪些数据适合保留。

以下指南可帮助部署与安全的数据处理实践保持一致：

• 对于仅存储使用，仅保留所需内容：设计应用程序，以便仅将有用的、适合业务的内容写入内存存储。
• 启用活动内存功能后，规划派生记录：除了调用方提供的内容（例如消息和元数据）外，工作流还可能保留提取的内存、摘要或嵌入。
• 将支持写入的内存路径视为可信路径：可以写入消息、摘要、内存、元数据、嵌入或线程运行时状态的数据库身份证明和后端代码路径可能会影响将来的提示和检索结果。主动内存功能有意保留模型派生状态；如果这不适用于工作流，请禁用自动提取，或使用仅存储/手动写入集成以及更窄的应用控制。
• 为保留工作选择正确的删除范围：delete_message() 仅删除原始消息记录。根据该消息创建的派生存储器或其他下游线程范围 Artifact 可以保持可搜索状态，因为提取的存储器当前不会持久保留每消息来源。当需要线程范围的清除操作来删除关联的内存和托管检索数据时，请使用 OracleAgentMemory.delete_thread()。
• 围绕后台工作的删除和关闭边界进行规划：delete_thread()、delete_user(cascade=True) 和 delete_agent(cascade=True) 仅等待该客户机在等待开始时已知的先前已接受的后台提取。它们不是跨其他句柄、组件或进程的全局并发屏障，在删除期间不支持并发写入。当保留或关闭边界需要从当前客户机已经接受的后台提取才能首先完成时，请在进程关闭或相关管理操作之前调用 wait_for_memory_extraction()。
• 提前定义保留和删除策略：如果您的应用提供了删除或保留承诺，请确保这些承诺涵盖由工作流创建的原始消息、提取的内存、元数据和其他相关记录。根据每条记录中的预期信息类型、应用程序需要保留它的原因以及任何适用的保留承诺，选择每条记录的 ttl_days 值和方案 memory_retention_config。当记录应按时间清除时，使用自动失效，并验证托管 Oracle 清除作业是否存在于数据库支持的部署中，尤其是在方案设置用户没有调度程序任务权限时。
• 清除任务数据库加载的计划：托管 Oracle 清除任务按计划运行，并从 SDK 管理的表中分批删除过期行，而不是作为一个大型删除操作。在具有高写入率或大量到期批的环境中监视其运行时、重做/撤消生成、跳过的运行历史记录和行卷，如果清除活动可能与延迟敏感的数据库工作负载重叠，则调整保留设置或操作部署计划。托管作业设置一天 schedule_limit，因此可以跳过延迟过长的运行，而不是任意延迟启动。
• 避免将内存作为事实来源：存储的内存旨在改善上下文和检索。应用程序应继续依赖权威系统作出重要决定。

关于检索范围和访问控制的注意事项

Oracle AI Agent Memory 使用调用方提供的 user_id、agent_id 和 thread_id 值来进行范围检索。这是一个强大的过滤模型，但它不应该是应用程序在决定如何使用或显示检索内容时所依赖的唯一控制。

缺省情况下，线程范围检索对 user_id 和 agent_id 使用完全匹配，对 thread_id 使用更广泛的匹配，因此相关结果可以跨越相同用户 - 代理对的过去线程。顶级 OracleAgentMemory.search() 和 search_async() 调用也需要显式的用户范围和精确的用户匹配。它们拒绝省略了用户范围和 exact_user_match=False，因此公共客户端 API 不会意外搜索多个用户。仅允许在完全匹配的用户和目标中传递 user_id=None，并且仅允许未定义的记录。

设计检索时，请使用以下练习：

• 将应用程序规则映射到内存范围：确保应用程序传递到 SDK 的范围与您的租户、用户和数据共享规则匹配。
• 在每次客户机搜索时传递显式用户范围：从已验证的请求上下文（而不是从请求 JSON 或其他调用方控制的输入）派生 user_id，并在每个顶级 OracleAgentMemory.search() 或 search_async() 调用上提供它。仅对有意限制为未定义范围记录的工作流使用 user_id=None。
• 首选满足该用例的最窄范围：对处理更敏感数据的工作流使用精确匹配和更严格的筛选器。
• 有意查看跨线程检索：更广泛的检索可以提高会话的连续性，但应用程序应仅在相应行为时启用它。
• 将搜索结果视为检索的内容，而不是最终决策：返回的记忆可能相关，但应用程序仍有责任决定它们是应该显示还是应该执行。
• 安全地在集成边界处理检索到的文本：检索到的记录可以包括调用方提供的文本或模型派生的文本。如果检索到的记忆或其他返回的文本呈现为 HTML、Markdown、模板、日志或其他输出表面，请在显示、转换或将其传递到下游系统之前应用上下文相关的转义或消毒。

有关应用程序集成和调用方信任的注意事项

Oracle AI Agent Memory 是由集成应用程序或其他可信后端代码调用的，而不是由最终用户直接调用的。它不是面向最终用户的安全边界，它不会自行执行最终用户验证或授权。软件包信任调用方为每个操作提供正确的 user_id、agent_id、thread_id 和检索范围。

重要提示：集成应用负责在调用 Oracle AI Agent Memory API 之前对最终用户进行身份验证、授权访问以及推导正确的 user_id 和范围。调用方提供的 user_id 是作用域值，而不是身份证明。

将 SDK 集成到代理应用时，请使用以下做法：

• 将 user_id 视为安全敏感的应用程序输入：如果集成应用程序从请求 JSON 或其他调用方控制的输入（而不是经过验证的上下文）派生 user_id，则可以允许跨用户内存访问。从经过验证的应用程序上下文中推导 user_id，而不是让最终用户选择任意值。
• 在每次内存调用之前应用应用程序授权：集成应用程序必须确定哪些 user_id、agent_id、thread_id 和搜索范围值对当前请求有效，并在预期租户和用户边界内保留读取和写入。
• 不要向最终用户公开原始内存 API ：应将程序包 API（如 add_memory 或搜索助手）封装在应用程序逻辑中，以验证调用方、强制执行策略并控制可以写入或返回哪些数据。
• 保留 user-ID 搜索和枚举特权：如果软件包添加了用于列出或枚举 user_id 值的帮助器，则仅将其视为管理功能，并且绝不会通过集成应用程序向最终用户公开这些功能。
• 仔细审查范围覆盖：任何扩展线程范围、禁用精确匹配或丢弃到较低级别存储 API 的工作流都应仅限于可信组件，并针对跨用户或跨租户效果进行审查。

有关日志记录和诊断的注意事项

Oracle AI Agent Memory 使用标准 Python 日志记录，不为集成应用程序配置应用程序日志处理程序或日志级别。应用程序可以启用 oracleagentmemory 日志记录程序并通过其现有的日志记录配置路由 SDK 日志。

使用 SDK 日志时，请使用以下做法：

• 将生产部署保留在非 DEBUG 级别：DEBUG 日志记录仅用于受控开发或支持诊断，不适用于生产日志收集。
• 限制对诊断日志的访问：使用适当的访问控制、保留和共享策略将日志存储在受保护的接收器中。在将日志发送到操作环境之外之前，请查看支持包。
• 避免在应用程序日志记录包装中添加敏感上下文：不要使用提示、内存内容、身份证明、原始元数据、数据库行值或调用方控制的标识符来扩充 SDK 日志记录。
• 将日志文本视为诊断输出，而不是审计接口：日志消息可以帮助对 SDK 行为进行故障排除，但应用程序应将自己的显式审计事件用于安全性和合规性工作流。

有关数据库访问、方案管理和密钥的注意事项

Oracle AI Agent Memory 使用呼叫者提供的 Oracle Database 连接或池。该程序包不会自行创建或管理数据库身份证明。它也不会代表调用方创建、协商或升级数据库网络加密。

重要提示：生产代码应将启用 TLS 的 Oracle Database 连接或池传递到 Oracle AI Agent Memory。SDK 按原样使用调用方提供的连接或池，并且不升级纯文本 DSN。不要跨不可信、共享或外部网络使用纯文本数据库连接。使用 python-oracledb 时，请按照 Securely Encrypting Network Traffic to Oracle Database 官方部分进行操作，并在连接或池创建过程中配置 TLS 或其他批准的加密传输。

重要提示：切勿将 API 密钥、密码或其他密钥直接嵌入到应用程序代码、签入配置或导出的对象中。始终使用安全注入机制，并遵循最少权限原则进行身份证明访问。

建议采用以下部署实践：

• 仅使用具有所需权限的数据库用户：仅授予所选部署模型和方案策略所需的权限。
• 在可行的情况下，使用单独的数据库用户执行删除工作流：如果您的应用程序需要删除记录，则更喜欢使用这些路径的专用连接或池，并且仅将托管 Oracle AI 代理内存表上的 DELETE 授予该数据库用户。将主运行时连接限制为其正常操作所需的非删除权限，以便意外或不需要的删除具有更窄的闪存半径。如果调用方通过没有 DELETE 权限的连接调用 delete()，则 Oracle Database 会拒绝该语句。
• 创建加密的数据库连接和池：生产代码应将启用 TLS 的 Oracle Database 连接或池传递到 SDK。Oracle AI Agent Memory 使用呼叫者提供的连接或池完全按照提供的方式使用，因此对于 python-oracledb，首选启用了 TLS 的连接（例如 protocol="tcps" 或等效 TCPS DSN），配置所需的 wallet 或 CA 材料，并保持服务器证书验证处于启用状态。
• 除非明确需要 DDL 更改，否则保留默认方案策略：SchemaPolicy.REQUIRE_EXISTING 是默认值，可避免在正常应用程序启动期间创建、修改或删除方案对象。
• 限制破坏性设置模式：SchemaPolicy.RECREATE 用于设置、测试或管理工作流，不应在常规生产路径中使用。
• 依赖于程序包管理的 SQL 路径，而不是应用程序代码中的动态 SQL 组合件：在托管数据库路径中，使用绑定变量发送记录值和搜索筛选器，托管对象名称由验证的前缀派生。
• 保护连接和提供程序身份证明：在 OCI Vault 等密钥管理器中存储数据库、LLM 和嵌入身份证明，并定期轮换。
• 在 Thin 和 Thick 模式下首选验证的 TLS ：官方 python-oracledb 文档指出，Thin 和 Thick 模式都支持 TLS，而 Thick 模式也可以使用 Oracle Native Network Encryption（这是您批准的标准）。
• 使用到数据库的安全传输：数据库网络安全、TLS 配置和验证方法由调用方提供的连接确定，应当遵循组织的标准。

关于网络通信和外部端点的注意事项

当部署配置远程 LLM 或嵌入提供程序时，Oracle AI Agent Memory 可以与外部服务通信。SDK 通过配置的客户端路径转发提示和请求参数，但周围的应用程序和部署仍负责保护这些连接。

我们建议您：

• 将 HTTPS 用于模型端点，并首选专用或受限网络路径（如果可用）。
• 监视出站流量和提供程序使用情况，以了解意外目标、异常请求卷或异常令牌使用情况。
• 在受监管或敏感的工作流上启用主动内存功能之前，选择符合合规性和驻留需求的提供商。

关于资源耗尽向量的注意事项

内存工作流可以随着时间的推移增加数据库使用量、嵌入流量和 LLM 标记消耗。这既适用于恶意过度使用，也适用于无辜的实施错误，例如超大消息或过于广泛的检索模式。

使用这些控件作为生产淬火的一部分：

• 设置实际提示和消息界限：配置 max_message_token_length 和 memory_extraction_token_limit 等值以符合工作量和提供程序限制。max_message_token_length 限制提取工作流使用的提示时副本；存储的消息保持不变。
• 限制检索大小：使用合理的 max_results 值和记录类型筛选器进行应用程序搜索。
• 应用 SDK 之外的基础设施限制：在周边部署中使用数据库配额、连接限制、网络控制、端点超时和速率限制。
• 监视一段时间内的增长：跟踪存储的消息量、持久内存增长、提供商使用情况和查询延迟，以便在影响可靠性之前进行保留或优化更改。