SinoVec：打造生产级中文长期记忆系统的技术实践

题图由 AI 生成 | SinoVec 核心架构概念图

聊到 AI Agent 的“长期记忆”，这绝对是个让人头大的问题。Agent 要能记住用户偏好、历史对话里的关键事实、项目进度——这些直接决定着体验是否连贯、是否真正“智能”。但现实是，用 OpenClaw 的时候经常失忆，原生方案不好用不说还收费，于是干脆自己动手搭了一套记忆系统。

市面上已有的方案各有短板：原生文件记忆透明但检索弱，没法做语义匹配；第三方记忆服务（像 Mem0、Zep）方便但有 API 成本，中文支持也一般；自建 RAG 技术门槛高，得维护向量数据库和整套检索链路。针对这些，SinoVec 应运而生——一个专为中文场景设计的本地化、高精度、零 API 成本的长期记忆系统。

一、核心架构：六层检索漏斗 + 混合存储

整个系统的核心是一个渐进式检索漏斗，从粗到精逐层筛选最相关的记忆：

用户查询
↓
jieba 分词（中文处理）
↓
LLM 查询扩展（可选，提升召回率）
↓
向量 + BM25 混合检索（动态权重，默认 70:30）
↓
时间衰减（近期记忆权重更高）
↓
LLM 重排（可选，对 Top-15 二次打分）
↓
MMR 多样性去重（避免结果同质化）
↓
返回 Top-K 结果

1. 向量 + BM25 混合检索

• 向量检索：用 BAAI/bge-small-zh-v1.5 将文本映射到 512 维语义空间，计算余弦距离
• BM25 全文检索：基于 PostgreSQL 全文索引，精准匹配关键词
• 动态权重：根据查询长度、专有名词数量、召回重叠度自动调整向量/BM25 比例（默认 70:30）

2. 可选增强模块

LLM 查询扩展
└─ 调用本地 Ollama（qwen2.5:7b）生成同义词，提升召回率
LLM 重排
└─ 对 Top-15 候选结果进行二次打分，优化排序
MMR 多样性去重
└─ Maximal Marginal Relevance，避免结果过于同质化

3. L1 + L2 分层存储

这个分层设计正好贴合人类记忆的遗忘曲线——越近的记忆越容易被召回，越久的记忆越不需要高频检索。

二、为什么选择完全本地化？

具体实现上，SinoVec 用 FastEmbed 做本地向量化（BAAI/bge-small-zh-v1.5，512 维，约 250ms/条），Ollama 跑本地 LLM（qwen2.5:7b），PostgreSQL + pgvector 做向量数据库——整套下来零外部 API 依赖。

三、生产级安全加固：v1.0.2 实践

项目开源后收到一份详细的代码审查报告，指出了多个安全问题。于是 v1.0.2 安全加固版本诞生了：

1. 移除硬编码数据库密码

# ❌ 修复前：硬编码密码
DB_CONFIG = {"password": "admin123"}
# ✅ 修复后：强制环境变量
_db_pass = os.getenv("MEMORY_DB_PASS", "")
if not _db_pass:
    raise RuntimeError("MEMORY_DB_PASS environment variable is not set.")

2. HTTP API 认证中间件

支持三种认证方式，按需选用：

Authorization: Bearer 
X-API-Key: 
?api_key=

通过环境变量 MEMORY_API_KEY 控制，未配置时仅开发模式跳过认证。

3. 防时序攻击

# ❌ 修复前
if api_key == expected_key:  # 时序攻击漏洞
# ✅ 修复后
import hmac
if hmac.compare_digest(api_key, expected_key):  # 防时序攻击

4. 向量缓存 TTL 限制

# ❌ 修复前：无界字典，可能 OOM
_cache = {}
# ✅ 修复后：限制 1000 条、TTL 1 小时
from cachetools import TTLCache
_cache = TTLCache(maxsize=1000, ttl=3600)

5. 连接池线程安全

使用 double-checked locking 确保多线程下只创建一次连接池。

这些加固措施让 SinoVec 具备了生产环境应有的安全基线。

四、定时任务优化：从失控到高效

生产运行中，我们对三个定时任务做了全面审查和优化，效果相当明显：

关键改进

• 新增 _is_noise() 过滤：自动跳过路径、UUID、JSON 结构、GitHub 仓库名单独出现等噪声
• 修复 organize SQL 参数化 Bug：COSINE_DIST_MERGE 常量误写为 SQL 文本，导致自动流转失败
• 三脚本增加环境变量自动加载：解决 cron 任务缺失 MEMORY_DB_PASS 的问题

最终调度时间线

00:05 Session 索引
00:15 自动记忆提取
01:00 每日记忆整理
...
12:05 Session 索引
12:15 自动记忆提取
12:25 每日记忆整理  （午饭期间完成，回来时系统已就绪）
...
18:05 Session 索引
18:15 自动记忆提取
19:00 每日记忆整理

五、性能与数据

在真实生产环境（约 3000 条记忆）下，数据表现如下：

六、开源与社区

SinoVec 采用 MIT 许可证，代码完全开源。项目提供了：

• 一键安装脚本：自动配置 PostgreSQL、创建数据库、安装依赖、注册 systemd 服务
• Docker 部署：docker-compose up -d 即可启动
• 详细文档：API 参考、OpenClaw 集成指南、开发路线图

欢迎任何形式的贡献——报告问题、提交代码、撰写文档、分享使用经验。

七、未来规划（v1.1.0）