P0: `hippo-llm` 0.3.1 wheel 漏装 `memory_safety.py` + sparse 模式下 `filter` 参数静默失效

[dengluozhang-png]

背景

我在外部构建基于 hippo 的工具时踩了两个坑，都属于"代码里有、wheel 用户拿不到"的 P0 级别：

Bug 1: wheel 漏装 memory_safety.py

• pyproject.toml L59: include = ["pipeline*", "embedding*"]
• 实际安装后 %APPDATA%\Python\Python314\site-packages\embedding\ 目录下没有 memory_safety.py
• from embedding.memory_safety import add_with_source → ModuleNotFoundError
• 这个模块是 v0.3.1 的新增功能（commit b63b313 feat(memory_safety): add M0 source tagging + confidence-weighted search），是 v0.5 "Agent memory layer" 的基础原语
• 用户照 README 走流程会发现这个核心 API 不可用

Bug 2: VectorStore.search() 在 sparse 模式下完全忽略 filter 参数

• embedding/store.py _search_sparse 方法只读 _bm25_scores，没读 filter 字段
• 文档（README sparse 模式示例）暗示支持 metadata 过滤，实际静默忽略
• 影响所有用 sparse（默认）模式做 session/kind/source 过滤的用户

复现

Bug 1:

pip install hippo-llm
python -c "from embedding.memory_safety import add_with_source"
# ModuleNotFoundError: No module named 'embedding.memory_safety'

Bug 2:

from embedding.store import VectorStore
s = VectorStore("/tmp/x.db", mode="sparse")
s.add("hello world", metadata={"kind": "fact"})
s.add("foo bar", metadata={"kind": "decision"})
docs = s.search("hello", top_k=5, filter={"kind": "fact"})  # 实际返回两条，不应用过滤

建议

Bug 1:

1. 检查 setuptools.packages.find 是否真的扫到了 embedding/memory_safety.py（可能因 embedding/ 下缺 __init__.py 或被 .gitignore 排除）
2. 加 CI smoke test：pip install dist/*.whl && python -c "from embedding.memory_safety import add_with_source"，失败即红线
3. 修复后发 0.3.2 patch

Bug 2:

• 选项 A（最小）：在 _search_sparse 末尾应用 filter 参数，剔除显式不匹配的 doc_id
• 选项 B（推荐）：与 hybrid 行为对齐 —— BM25 计算后、截断前做内存过滤
• 在 docstring 显式说明或文档标注"sparse 模式下过滤在客户端完成"

影响

• 所有 wheel 用户都受影响
• 0.3.1 release notes 提到的核心功能（来源标签、置信度衰减）在生产环境不可用
• 与 v0.5 roadmap（Agent memory layer）方向冲突 —— 这层是基于 memory_safety 构建的

环境

• hippo-llm 0.3.1 (PyPI)
• Python 3.14.0 (Windows)
• 来源：lawcontinue/hippo @ commit e64c375