// 目录 CONTENTS
一、引言：从"记住"到"真正记住"
所有AI助手都面临一个根本矛盾：模型有上下文窗口限制，但用户的需求是持续累积的。Hermes Agent通过会话持久化让AI"记住"了历史对话，但这份记忆只有在你能准确回忆起当初的表述时才能被利用。
换句话说：系统确实存了，但你不一定找得到。这是一个关于检索的问题，而不是存储的问题。
Hermes Agent存了三个月的对话，但当你问"上次那个连远程主机的问题怎么解决来着"，系统返回"未找到相关结果"——不是没存，是搜索方式太笨。
二、痛点：FTS5关键词搜索的死穴
Hermes Agent原来的搜索基于SQLite的FTS5全文索引。FTS5工作原理是建立倒排索引，记录每个词出现在哪些文档里。搜索时，把查询分词，与索引匹配，返回包含相同词的结果。
这个机制有一个致命弱点：严格词面匹配。用户用不同的词描述同一件事，搜索就会失败。
上个月你说"磁盘满了要清理"，现在问"空间不够"，两个意思完全一样，但FTS5认为这是两个毫无关系的内容。三个月的记录，换一种问法就全丢了。
三、解决思路：给AI装上"语义雷达"
解决方案是在FTS5旁边增加一层：向量语义搜索。
向量搜索的核心思想是：把"语义相近的内容"映射到"向量空间里相近的位置"。当两个文本意思接近时，它们转换后的向量也接近，体现在数学上就是余弦相似度高。
这样一来，用户不需要用同样的词，只需要描述同样的意思，系统就能找到相关记录。
四、技术架构：双路召回与RRF融合
系统采用双路召回、RRF融合的混合架构。两路搜索并行进行，各自找到最匹配的结果，再通过RRF（倒数排名融合）算法合并出一个最终排序列表。
4.1 Embedding 模型选择
使用火山引擎 doubao-embedding-vision 模型，支持2048维中英文文本向量，API兼容OpenAI Embeddings格式，可直接接入。
4.2 RRF 融合公式
RRF（Reciprocal Rank Fusion）是一种简单但有效的多路搜索结果融合算法：
五、效果对比：换了说法照样能找到
关键洞察：当FTS5返回零结果时，向量搜索往往能给出高置信度的答案。两者结合后，系统的有效召回率大幅提升。
六、落地细节：纯Python实现，无重型依赖
6.1 存储格式：BLOB二进制
每条2048维float32向量占用8KB存储空间（2048 x 4字节），1000条会话记录约8MB。向量以二进制BLOB格式直接存入SQLite，配合text_hash去重，文本不变则不重复调用Embedding API。
6.2 余弦相似度：纯Python实现
不依赖numpy，不依赖faiss，不依赖任何外部计算库。在Hermes自带的Python虚拟环境里直接运行。
6.3 增量回填机制
新增消息自动触发Embedding存储，同时提供独立回填脚本，对历史未向量化的消息批量处理，零漏记录。
七、性能实测：100毫秒内完成千条检索
在生产环境中，对1000条2048维向量做全扫描计算余弦相似度，纯Python耗时低于100毫秒，可满足实时检索的响应要求。
八、总结与价值
向量记忆系统的核心价值，是把Hermes Agent从"你说什么我找什么"升级为"你想要什么我理解什么"。这不是一个锦上添花的功能，而是AI助手从玩具走向实用工具的关键一步。
关键词+语义双路召回：FTS5保证精确匹配兜底，向量搜索突破词面限制。纯Python零依赖：不动Hermes现有虚拟环境，直接部署。RRF融合：两路结果取长补短，兼顾召回率与精确度。7倍速度提升：相比传统方案，检索效率大幅改善。
历史会话终于能被真正用起来了。