P2: v0.5 "Agent memory layer" 缺乏设计文档 + `acceleration.py` 与 README 叙事脱节

[dengluozhang-png]

汇总 2 个 roadmap/架构层面的问题，需要更长时间讨论。

问题 1: v0.5 "Agent memory layer" 缺设计文档

Roadmap 原文 (README):

v0.5: Agent memory layer (embedding-backed episodic memory)

现状:

• memory_safety 提供了底层原语（add_with_source / search_with_confidence / decay_low_confidence）
• 但没定义"什么是 episodic memory"
• 没有会话/时间维度的 schema 规范
• 没有"LLM 怎么读、怎么写"的高层 prompt template
• 与现有 memory_safety 的关系没说清（替代 / 扩展 / 并行？）

建议: 在 v0.5 开干前，先在 docs/ 下出一份 design doc，定义：

1. Schema 规范：必填字段（session_id/created_at/kind/source/confidence/archive_id），metadata 约定
2. 分层设计：工作记忆（短时高密度）vs 长期记忆（持久低密度）的边界
3. 写入工作流：LLM 在什么时机触发提炼？提炼出来的格式是什么？
4. 读取工作流：召回后的 ranking、冲突解决、置信度加权
5. 与现有 memory_safety 的关系：扩展而非替代，明确升级路径

参考实现: 我基于 hippo embedding 模块写了一个 ZCode skill（memory-recall），实现了 skill-orchestrated 模式：LLM 做提炼和召回后推理，Python 只做存/取/衰减。可以作为 v0.5 设计参考 —— 它已经验证了"统一库索引记忆 + 会话级 archive 关联 + 来源信任加权"这套架构能跑通。

问题 2: acceleration.py 与 README 叙事脱节

证据:

• 顶层 acceleration.py 是 15KB 精心设计的加速抽象层：AccelerationStrategy 抽象基类 + 4 种策略（DFlash/MTP/Pipeline/None）+ AccelerationOrchestrator 自动选择
• 设计文档注释非常详尽（"DFlash for Mac / MTP for NVIDIA / Pipeline 双机分片"）
• 但 README 主线一直是 embedding-first，最近 10 次 commit 也都是 embedding/ 改动
• acceleration.py 似乎被边缘化了 —— 是设计太超前？还是缺使用场景？

建议:

• 要么把它整合进 README，讲清"Apple Silicon → DFlash, NVIDIA → MTP, 双机 → Pipeline, 无匹配 → None"
• 要么把它挪到 pipeline/ 子包作为内部实现，README 不提
• 如果保留为顶层模块，至少加一段 docstring 解释"为什么独立于 pipeline/"和"现在的使用场景是什么"

优先级

这两个都是设计层面的讨论项，不像 P0/P1 那样阻塞用户。可以在 0.4 收尾后、0.5 开干前讨论清楚。

环境

• 来源：lawcontinue/hippo @ commit e64c375

[lawcontinue]

Addressed in ab7a740.

• Created docs/V05_AGENT_MEMORY_DESIGN.md covering: schema spec, layered design (working/long-term), read/write workflows, and relationship to memory_safety
• README: added Acceleration Strategies section documenting DFlash/MTP/Pipeline/None options

The v0.5 design doc is a draft — feedback welcome.