技能介绍

要解决的问题

Agent 的短期上下文窗口有限，跨会话记住用户偏好、项目约定和历史结论，必须落到长期存储。但长期记忆很容易退化：无关条目堆积、重复事实互相覆盖、过期策略把该留的内容一起清掉，检索时又只能靠关键词硬匹配，"它""那个项目"这类指代无法回填。这个技能面向 agent-cognitive-brain 七层架构的 L2/L3 层，把"存得下"和"取得准"拆开治理。

核心模块

TfidfIndex：纯 Python TF-IDF 向量索引，中文分词用字 + bigram，词表懒重建，可选 numpy 加速。
MemoryRetentionPolicy：热度衰减（系数 × 0.95）、TTL 软过期（归档不删除）、按 topic 配额驱逐、带环检测的版本链追踪。
MemoryMergeEngine：语义相似度去重（阈值 > 0.86）、冲突检测（键值重叠 < 30%）、增量 diff 追加合并。
MemoryRecallRouter：混合检索（关键词 × 0.7 + 语义 × 0.3）× decay_score，支持指代消解回填上下文，访问热度自动更新。
MemoryHealthMonitor：碎片化得分（孤儿比例）、冗余得分（已合并 + 已过期占比）、冷记忆比例，并自动产出修复建议。

召回流程

关键词匹配（权重 0.7）：对 query 做精确 key/tag 命中；
语义相似度（权重 0.3）：TF-IDF 余弦；
热度加权：最终得分 = (keyword × 0.7 + semantic × 0.3) × decay_score()；
兜底降级：numpy 缺失时自动切到纯 Python 路径。

适用边界

依赖只有标准库（sqlite3、json、re、math、uuid、dataclasses、collections），numpy 可选。
TF-IDF 是词袋模型，没有真正的语义理解；0.86 这个阈值需要按自己的语料调。
提供 CLI 与编程 API 两种入口，也可先跑内置自测验证行为。
架构细节、TF-IDF 索引设计、健康度打分算法与数据库 schema 见 references/architecture.md。