搜索

本页介绍了面向开发人员的范围限定帮助程序以及具体的 Oracle 搜索结果类型。

范围解析

对于每个作用域字段，可以执行以下三项操作之一：

• 省略它以使用该 API 层的默认值。在 Python 签名和 SearchScope 中，此省略状态由 NOT_SET_MARKER 表示。
• 指定具体 ID 以使用该值；
• 指定 None 表示在维上取消记录范围。例如，agent_id=None 表示记录未与一个代理关联。

每个存储记录都有三个独立的范围字段：user_id、agent_id 和 thread_id。每个字段可以包含一个具体 ID 或 None。

示例：

• thread_id=None 表示记录未绑定到一个线程。
• agent_id=None 表示记录未与一个代理关联。
• user_id="u1", agent_id=None, thread_id=None 表示将记录范围限定于用户 u1，但不限定于任何特定的代理或线程。

相同的范围规则同时适用于同步和异步搜索 API。

在下表中，ID 表示 user_id、agent_id 或 thread_id 中的任何值及其对应的精确匹配标志。

按 API 层搜索范围解析

案例	thread.search()	OracleAgentMemory.search()	store.search()
省略 ID	使用线程默认值：精确的 user_id 和 agent_id，加上当前带有 exact_thread_match=False 的 thread_id。	使用客户机默认值。忽略的 user_id 被拒绝。省略 agent_id 和 thread_id 保持宽泛。	使用存储默认值：ID=None 和 exact_*_match=False，以便不过滤维。
显式值，包括 None + exact_*_match=False	未筛选该维。值与指定记录匹配的记录可能排名高于其他记录。	对于 user_id，由于客户机搜索需要明确明确的用户范围，因此被拒绝。对于 agent_id 和 thread_id，不会过滤该维。值与指定记录匹配的记录可能排名高于其他记录。	未筛选该维。值与指定记录匹配的记录可能排名高于其他记录。
显式 ID + exact_*_match=True	完全匹配该 ID。	完全匹配该 ID。	完全匹配该 ID。
显式 None + exact_*_match=True	仅匹配该维上未界定的记录。	仅匹配该维上未界定的记录。	仅匹配该维上未界定的记录。

如果只希望在该维上取消记录范围且 API 允许，请将显式 None 与 exact_*_match=True 一起使用。如果希望默认操作，请忽略该字段。

生命周期状态筛选

所有保留的记录都具有生命周期状态。搜索在存储、客户端和线程 API 上接受 include_invalid_results。在客户端和线程 API 上，它默认为 NOT_SET_MARKER，它解析为在搜索结果中包括有效和无效记录。低级存储 API 将其布尔默认值解析为相同行为。通过 False 忽略状态为 RecordStatus.INVALID 的记录。

图形扩展

将 num_hops 从 0 到 5 传递到存储、客户端或线程搜索 API，以便将链接的内存上下文附加到每个直接内存结果。遍历遵循任一方向的关系，保留存储的关系方向，并通过每条记录的 linked_results 序列返回一条最短路径树。直接消息、文档和 actor-profile 匹配仍保留在排名结果集中，但不会展开图形。特别是，可搜索的图像描述可以返回图像记录，而不会使 DOCUMENT 成为内存链接顶点。范围、元数据、记录类型和到期筛选器应用于每个链接的内存。include_invalid_results 继续仅控制顶层搜索匹配；它不会更改包含哪些链接的内存。max_linked_results 将所有跃点中附加到每个直接结果的链接内存总数上限。它默认为 100；将 0 传递给忽略链接的上下文。

范围

class oracleagentmemory.apis.scope.Scope

基准：object

表示信息插入或搜索的范围。

• 参数：
  • user_id str | None
  • agent_id str | None
  • thread_id str | None

user_id

最终用户的 ID。NOT_SET_MARKER 表示字段已省略，应使用特定于操作的默认值进行解析。显式 None 由特定于操作的规则保留和解释。诸如 OracleAgentMemory.search() 之类的高级客户端 API 可能需要用户范围显式。在这些 API 中，None 只能用于定位未作用域的记录。

• 类型： str | None

座席标识

代理 ID。NOT_SET_MARKER 表示字段已省略，应使用特定于操作的默认值进行解析。显式 None 由特定于操作的规则保留和解释。

• 类型： str | None

thread_id

线程 ID。NOT_SET_MARKER 表示字段已省略，应使用特定于操作的默认值进行解析。显式 None 由特定于操作的规则保留和解释。

• 类型： str | None

class oracleagentmemory.apis.searchscope.SearchScope

基础：Scope

表示搜索查询的范围，因此约束可以返回的内容。

• 参数：
  • user_id str | None
  • agent_id str | None
  • thread_id str | None
  • exact_user_match bool
  • exact_agent_match bool
  • exact_thread_match bool

user_id

最终用户的 ID。当解析的 exact_user_match 值为 True 时，此 ID 将完全匹配，包括 None。如果为 False，则用户维不受约束。NOT_SET_MARKER 将替换为特定于操作的缺省值。诸如 OracleAgentMemory.search() 之类的高级客户端 API 可能需要用户范围显式。在这些 API 中，None 在 exact_user_match 解析为 True 时仅针对未作用域的记录。

• 类型： str | None

座席标识

代理 ID。当解析的 exact_agent_match 值为 True 时，此 ID 将完全匹配，包括 None。如果为 False，则代理维不受约束。NOT_SET_MARKER 将替换为默认值，具体取决于使用作用域的操作。

• 类型： str | None

thread_id

线程 ID。当解析的 exact_thread_match 值为 True 时，此 ID 将完全匹配，包括 None。当它是 False 时，线程维不受约束。NOT_SET_MARKER 将替换为默认值，具体取决于使用作用域的操作。

• 类型： str | None

exact_user_ 匹配

是否与解析的 user_id 完全匹配。True 完全匹配，包括 None。False 会使用户维不受约束。NOT_SET_MARKER 将替换为缺省值，具体取决于操作。诸如 OracleAgentMemory.search() 之类的较高级别的客户端 API 可能需要保留 True。

• 类型： bool

精确代理匹配

是否与解析的 agent_id 完全匹配。True 完全匹配，包括 None。False 使代理维不受约束。NOT_SET_MARKER 将替换为缺省值，具体取决于操作。

• 类型： bool

精确线程匹配

是否与解析的 thread_id 完全匹配。True 完全匹配，包括 None。False 使线程维不受约束。NOT_SET_MARKER 将替换为缺省值，具体取决于操作。

• 类型： bool

搜索配置

class oracleagentmemory.core.MemorySearchConfig

基础：ISearchConfig

内存搜索后行为的基本配置。

• 参数：
  • token_budget(token_budget)int | None
  • soft_token_budget int | None

格式化搜索输出的可选目标大小。

通过达到或超过此预算的第一个结果按排名顺序保留完整结果。因此，当没有硬 token_budget 阻止其返回时，将保留第一个结果。

格式化搜索输出的估计大小的可选硬限制。

完成结果按排名顺序保留，而其累计估计值符合预算。如果第一个结果不合适，则不返回任何结果。

class oracleagentmemory.core.TopKMemorySearchConfig

基础：_RerankingMemorySearchConfig

具有固定最大直接结果数的搜索配置。

• 参数：
  • token_budget(token_budget)int | None
  • soft_token_budget int | None
  • reranker IReranker | None
  • reranker_max_candidates int
  • max_results int

重新排序之前检索的最大直接结果数。

class oracleagentmemory.core.PruningEvaluationMode

基础：str、Enum

控制在删改期间对搜索结果的评估范围。

排斥性 = 'EXHAUSTIVE'

单独评估每个候选人结果。这提供了最完整的评估，但具有最高的延迟和 LLM 使用量。

EXTENDED = ‘ EXTENDED ’

在决定保留哪些结果之前，先评估较大的一部分结果，但代价是额外的延迟和 LLM 使用。

快速 = ‘ FAST ’

当进一步检查不太可能更改保留哪些结果时，通过提前停止评估来确定低延迟的优先级。

class oracleagentmemory.core.PruningMemorySearchConfig

基础：_RerankingMemorySearchConfig

用于删除相关性较低的直接结果的搜索配置。

直接结果限制在每次搜索或上下文卡调用中提供，并在重新排序和修剪之前应用。

• 参数：
  • token_budget(token_budget)int | None
  • soft_token_budget int | None
  • reranker IReranker | None
  • reranker_max_candidates int
  • evaluation_mode PruningEvaluationMode
  • num_probe_points int
  • protected_fraction float
  • pruner ILlm

在修剪期间对搜索结果的评估范围有多广。

如果省略，则使用 PruningEvaluationMode.FAST。

在 FAST 或 EXTENDED 模式下评估的排名结果区域数。

当 evaluation_mode 为 PruningEvaluationMode.EXHAUSTIVE 时，无法设置此参数。

受修剪保护的最高级别直接结果的分数。

例如，0.1 可保护前 10% 的直接结果。

LLM 用于确定要删除的直接结果。

结果

class oracleagentmemory.core.SearchResultFormatConfig

基准：object

控制便携式搜索结果渲染选项。

实现可以为子类提供其他呈现选项。

• 参数：include_invalid_results bool- 无效的链接记录是否包括其内容。当 False 时，将省略仅无效的分支，而有效记录的路径上的无效记录将保留其状态和链接上下文。省略以使用 True。

class oracleagentmemory.core.OracleSearchResultFormatConfig

基础：SearchResultFormatConfig

控制 Oracle 搜索结果呈现选项。

• 参数：
  • show_thread_id bool- 是否包括记录的线程标识符。省略以使用 False。
  • show_distance bool- 是否包括估计的相关性。省略以使用 False。
  • show_timestamp bool- 是否包括记录时间戳。省略以使用 True。
  • show_role bool- 是否包括消息角色。省略以使用 True。
  • show_user_id bool- 是否包括记录用户标识符。省略以使用 False。
  • show_agent_id bool- 是否包括记录代理标识符。省略以使用 False。
  • show_status bool- 是否包括记录生命周期状态。省略以使用 True。
  • show_metadata bool- 是否包括调用方元数据和内存失效原因（如果存在）。每个条目都使用其元数据键作为 XML 标记，并将其值呈现为字符串。省略以使用 False。
  • include_invalid_results bool

class oracleagentmemory.core.OracleSearchResult

基础：SearchResult

Oracle 线程返回的搜索结果。

• 参数：
  • distance float- 与查询向量的距离（较小越好）。
  • record Record- 包含有关持久性条目的元数据信息的记录对象。
  • id str | None- 与存储的记录关联的可选标识符。
  • linked_results list tuple[[RecordRelation, SearchResult]] | None- 可选的图形链接子结果。每对都包含存储的 RecordRelation 和通过它获得的结果。
  • format_config SearchResultFormatConfig- 当未提供任何选项时，由 formatted_content 和 format_content() 使用的缺省呈现选项。

property（属性）content

• 返回类型： str
• 说明：返回匹配记录的主要文本内容。

method format_content

将此结果及其图形上下文呈现为 XML 安全的提示文本。

• 参数：format_config SearchResultFormatConfig- 此调用的呈现选项。省略以使用此结果的默认配置。在提供的配置中，省略的选项会回退到该默认配置中的相应选项。
• 返回：XML 安全结果呈现。
• 返回类型： str

property（属性）formatted_content

• 返回类型： str

• 说明：返回提示中使用的默认 XML 安全呈现。

• 返回：使用此结果的默认配置的 XML 安全呈现。
• 返回类型： str

property（属性）id

• 返回类型： str

  无

• 说明：返回匹配记录的稳定标识符（如果可用）。

property（属性）linked_results

• 返回类型： list[tuple[ RecordRelation ，SearchResult]]
• 说明：在其递归最短路径树中返回链接的结果。

property（属性）metadata

• 返回类型： dict[str，Any]

  无

• 说明：返回记录元数据（如果可用）。

property（属性）record

• 返回类型：记录
• 说明：返回匹配的记录。

返回的值可以是普通 Record 或 ScopedRecord 子类。在读取公共范围标识符之前，请使用 isinstance(result.record, ScopedRecord)。

property（属性）status

• 返回类型：RecordStatus

  无

• 说明：返回匹配记录的生命周期状态。

property（属性）timestamp

• 返回类型： str

  无

• 说明：返回记录时间戳（如果可用）。