SinoVec：打造生产级中文长期记忆系统的技术实践
一个完全本地、高精度、零 API 成本的记忆层，让 AI Agent 真正"记住"你。
题图由 AI 生成 | SinoVec 核心架构概念图
引言
官话：在构建 AI Agent 时，"长期记忆"始终是一个棘手的问题。Agent 能否记住用户的偏好、历史对话中的重要事实、项目进度等，直接决定了用户体验的连贯性和智能化程度。 实话：是使用openclaw过程中经常失忆，原生又不好用还收费。所以自己做了个记忆系统。
市场上已有的方案各有局限：
| 方案 | 缺点 |
|---|---|
| OpenClaw 原生文件记忆 | 透明但检索能力弱，无法语义匹配 |
| 第三方记忆服务（Mem0/Zep） | 便捷但有 API 成本，中文支持一般 |
| 自建 RAG | 技术门槛高，需维护向量数据库和检索链路 |
为了解决这些问题，我们开发了 SinoVec ------ 一个专为中文场景设计的本地化、高精度、零 API 成本的长期记忆系统。
SinoVec 名称含义：Sino = 拉丁语"中国的/东方的" + Vec = Vector（向量），专为中文场景深度优化的向量记忆系统。
一、核心架构：六层检索漏斗 + 混合存储
SinoVec 的核心是一个渐进式检索漏斗，从粗到精筛选最相关的记忆：
markdown
用户查询
↓
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 分层存储
| 层级 | 技术 | 用途 |
|---|---|---|
| L1 | pgvector 向量库 | 高效语义检索，所有记忆的向量表示 |
| L2.HOT | Markdown | 当天日志，>2天自动流转 |
| L2.WARM | Markdown | 近期待办，项目进度 |
| L2.COLD | Markdown | 永久事实，只增不删 |
这符合人类记忆的遗忘曲线------越近的记忆越容易被召回，越久的记忆越不需要高频检索。
二、为什么选择完全本地化？
| 对比项 | 云端 API | SinoVec（本地） |
|---|---|---|
| 向量生成 | OpenAI Ada-002（$0.0001/1K tokens） | FastEmbed 免费 |
| LLM 重排 | GPT-3.5/4 付费 | Ollama 免费 |
| 数据隐私 | 数据传输到第三方 | 数据不出内网 |
| 检索延迟 | 200-500ms | 20-50ms（不含重排） |
| 中文支持 | 一般 | 深度优化（jieba 分词） |
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. 移除硬编码数据库密码
python
# ❌ 修复前：硬编码密码
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 认证中间件
支持三种认证方式，按需选用：
vbnet
Authorization: Bearer <key>
X-API-Key: <key>
?api_key=<key>通过环境变量 MEMORY_API_KEY 控制，未配置时仅开发模式跳过认证。
3. 防时序攻击
python
# ❌ 修复前
if api_key == expected_key: # 时序攻击漏洞
# ✅ 修复后
import hmac
if hmac.compare_digest(api_key, expected_key): # 防时序攻击4. 向量缓存 TTL 限制
python
# ❌ 修复前：无界字典，可能 OOM
_cache = {}
# ✅ 修复后：限制 1000 条、TTL 1 小时
from cachetools import TTLCache
_cache = TTLCache(maxsize=1000, ttl=3600)5. 连接池线程安全
使用 double-checked locking 确保多线程下只创建一次连接池。
这些加固措施使 SinoVec 具备了生产环境的安全基线。
四、定时任务优化：从失控到高效
在生产运行中，我们对三个定时任务做了全面审查和优化，效果显著：
| 任务 | 优化前 | 优化后 | 效果 |
|---|---|---|---|
| 自动记忆提取 | 每30分钟，去重窗口6h，噪声多 | 每6小时，去重窗口48h，加 _is_noise() 过滤 |
运行次数 -83% ，重复记忆 -90% |
| Session 索引 | 每天2次，运行良好 | 保持现状 | 稳定运行，无需改动 |
| 每日记忆整理 | 每天2次，token消耗20k-95k | 每天1次，修复SQL bug | token消耗 -50%，bug清零 |
关键改进
- 新增
_is_noise()过滤：自动跳过路径、UUID、JSON 结构、GitHub 仓库名单独出现等噪声 - 修复 organize SQL 参数化 Bug ：
COSINE_DIST_MERGE常量误写为 SQL 文本，导致自动流转失败 - 三脚本增加环境变量自动加载 ：解决 cron 任务缺失
MEMORY_DB_PASS的问题
最终调度时间线
makefile
00:05 Session 索引
00:15 自动记忆提取
01:00 每日记忆整理
...
12:05 Session 索引
12:15 自动记忆提取
12:25 每日记忆整理
（午饭期间完成，回来时系统已就绪）
...
18:05 Session 索引
18:15 自动记忆提取
19:00 每日记忆整理五、性能与数据
在真实生产环境（约 3000 条记忆）下：
| 指标 | 数值 |
|---|---|
| 检索延迟（无重排） | 20-50ms |
| 检索延迟（含重排） | 500-2000ms（可关闭） |
| 向量生成速度 | ~250ms/条（FastEmbed） |
| 数据库大小 | 47 MB（含向量索引） |
| 核心记忆召回率 | > 95% |
六、开源与社区
SinoVec 采用 MIT 许可证，代码已完全开源：
- 🐙 GitHub ：github.com/shandongkm/...
- 🐔 Gitee ：gitee.com/confucius-a...
项目提供了：
✅ 一键安装脚本：自动配置 PostgreSQL、创建数据库、安装依赖、注册 systemd 服务
✅ Docker 部署：docker-compose up -d 即可启动
✅ 详细文档：API 参考、OpenClaw 集成指南、开发路线图我们欢迎任何形式的贡献------报告问题、提交代码、撰写文档、分享使用经验。
七、未来规划（v1.1.0）
- 📊 性能基准测试：提供不同数据量下的官方性能数据（1k / 10k / 100k）
- 🖥️ Web 管理界面：可视化浏览、编辑、删除记忆，查看统计图表
- 🖼️ 多模态支持：图片记忆（图文混合检索）
如果你也在为 AI Agent 的记忆问题困扰，欢迎试用 SinoVec。你的 Star 是我们最大的动力。 ⭐
本文同步发布于：掘金 / 知乎 / CSDN / 开源中国 / Medium