poolsplit

用途

Pool-split retrieval 用于智能体记忆的检索场景。当使用单一评分函数对混合类型的记忆存储进行排序，并只给一个 token 预算时，高优先级的条目类型会垄断上下文窗口，低优先级类型永远无法出现。在产生该模式的系统中，预留前的测量数据显示：增长类条目在 4 次测试查询中加载了 0 次，技能类在 30 次中仅加载 1 次。

该失败模式还有一个更危险的相反面：大量新的、刚被评分的内容可能把一条长期存在的行为纠正挤出范围，而恰好在智能体即将重犯那条纠正所要防止的错误时。一条纠正如果只在安静的回合才加载，就毫无价值。

主要能力

Pool（预留预算）

每个 pool 为一组类型拥有一个 token 上限和条目上限。Pool 独立填充，因此一个 pool 中的高优先级类型无法消耗另一个 pool 中低优先级类型的预算，低优先级类型获得有保证的空间。

Pool(name, max_tokens, max_entries, types=None) 是一个冻结数据类，描述一个预留预算：

• name：pool 结果返回时使用的唯一键。
• max_tokens：上下文（非 always）条目的 token 上限。
• max_entries：上下文条目的数量上限；always-scope 条目不计入。
• types：该 pool 抽取的条目类型元组；None 表示接受所有类型。

max_tokens 或 max_entries 为负会抛出 ValueError。

Always-scope 无条件加载

带有 scope="always" 的条目（行为纠正）会优先加载，并绕过 token 上限和条目上限。无论有多少新内容到达，它永远不会被挤出去。这是该库存在的核心不变式。

retrieve 函数

retrieve(entries, pool, context=None, *, scorer, token_counter, is_active, now) -> List[dict] 填充一个 pool，语义如下：

• 过滤出活跃条目，再过滤出该 pool 的类型。
• 拆分为 always-scope（scope == "always"）和上下文条目。
• 所有 always-scope 条目优先加载，绕过 max_tokens 和 max_entries。
• 上下文条目按完全确定的键排序：(-score, created-or-"", id-or-"", original-index)。输入顺序除了通过 original-index 打破剩余平局外，永远不会改变结果。
• 贪心填充预算。条目的开销优先使用 entry["token_count"]（当存在且为正整数时），否则使用 token_counter(content)，缺失计数时绝不使用 0。
• 返回的条目是相同的 dict 对象（无副本），顺序为 always-scope（输入顺序）然后上下文（排序顺序）。
• 绝不修改 entries。

retrieve_pools 函数

retrieve_pools(entries, pools, context=None, *, ...) -> Dict[str, List[dict]] 从同一组条目填充多个 pool。Pool 按顺序处理；被前一个 pool 选中的条目会从后续 pool 中排除，因此每个条目最多落在一个 pool 中。去重依据对象标识（id()），因此即使条目缺少 "id" 键也能正确去重。重复的 pool 名称会抛出 ValueError。

默认评分器

default_scorer(entry, context, *, now=None) -> float 的评分公式为：基础优先级 × 最近性衰减（90 天线性，下限 0.3）× 标签重叠 × 项目匹配 × 消息内容词重叠。now 可注入以实现确定性评分。没有访问计数/频率项。评分是词法的且完全可插拔，可以传入自定义 scorer。

默认计数器与活跃判断

default_token_counter(text) -> int 返回 max(1, len(text) // 4)。故意粗略且可插拔，永不返回 0。

default_is_active(entry) -> bool：当 status 为 "active"（缺键时的默认值）且没有 superseded_by 指针时返回 True。

使用方式

这是一个单文件、无依赖的模块。支持通过复制 poolsplit.py 到项目中并导入的方式来内嵌安装。

开发（测试）需要 Python 3.9 或更新版本，无运行时依赖。

适用场景

适合需要为智能体记忆做检索、且希望避免单一预算导致类型饥饿或重要纠正被挤出的系统。尤其适用于包含多种条目类型、需要保证低优先级类型可见性、并需要行为纠正无条件加载的场景。

限制（明确不做什么）

• 持久化：poolsplit 只读写 dict 列表，不负责加载、保存、加锁或迁移存储。
• 语义评分：默认 scorer 是词法的（标签和词重叠），不含嵌入向量。完全可插拔，可自行提供向量相似度等 scorer。
• 访问频率跟踪：读取时不修改任何条目，没有访问计数，评分中也没有频率项。这是有意为之：频率反馈循环（检索提高计数，计数提高评分，评分导致再次被检索）曾使原存储中约 97% 的内容在普通查询下变得不可达。排名与检索历史保持独立。
• 异步：所有内容都是同步、进程内的。

该库是从一个自 2026 年初投入生产的个人 AI 系统的检索层中干净室提取并重新表达的。

采用 MIT 许可证，详见 LICENSE。