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

SinoVec
0 阅读6分钟

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

一个完全本地、高精度、零 API 成本的记忆层，让 AI Agent 真正"记住"你。

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

引言

官话：在构建 AI Agent 时，"长期记忆"始终是一个棘手的问题。Agent 能否记住用户的偏好、历史对话中的重要事实、项目进度等，直接决定了用户体验的连贯性和智能化程度。 实话：是使用openclaw过程中经常失忆，原生又不好用还收费。所以自己做了个记忆系统。

市场上已有的方案各有局限：

方案缺点
OpenClaw 原生文件记忆透明但检索能力弱，无法语义匹配
第三方记忆服务（Mem0/Zep）便捷但有 API 成本，中文支持一般
自建 RAG技术门槛高，需维护向量数据库和检索链路

为了解决这些问题，我们开发了 SinoVec —— 一个专为中文场景设计的本地化、高精度、零 API 成本的长期记忆系统。

SinoVec 名称含义：Sino = 拉丁语"中国的/东方的" + Vec = Vector（向量），专为中文场景深度优化的向量记忆系统。

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

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

用户查询
    ↓
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 分层存储

层级技术用途
L1pgvector 向量库高效语义检索，所有记忆的向量表示
L2.HOTMarkdown当天日志，>2天自动流转
L2.WARMMarkdown近期待办，项目进度
L2.COLDMarkdown永久事实，只增不删

这符合人类记忆的遗忘曲线——越近的记忆越容易被召回，越久的记忆越不需要高频检索。

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

对比项云端 APISinoVec（本地）
向量生成OpenAI Ada-002（$0.0001/1K tokens）FastEmbed 免费
LLM 重排GPT-3.5/4 付费Ollama 免费
数据隐私数据传输到第三方数据不出内网
检索延迟200-500ms20-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. 移除硬编码数据库密码

# ❌ 修复前：硬编码密码
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 <key>
X-API-Key: <key>
?api_key=<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 具备了生产环境的安全基线。

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

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

任务优化前优化后效果
自动记忆提取每30分钟，去重窗口6h，噪声多每6小时，去重窗口48h，加 _is_noise() 过滤运行次数 -83%，重复记忆 -90%
Session 索引每天2次，运行良好保持现状稳定运行，无需改动
每日记忆整理每天2次，token消耗20k-95k每天1次，修复SQL bugtoken消耗 -50%，bug清零

关键改进

  • 新增 _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 条记忆）下：

指标数值
检索延迟（无重排）20-50ms
检索延迟（含重排）500-2000ms（可关闭）
向量生成速度~250ms/条（FastEmbed）
数据库大小47 MB（含向量索引）
核心记忆召回率> 95%

六、开源与社区

SinoVec 采用 MIT 许可证，代码已完全开源：

项目提供了：

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

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

七、未来规划（v1.1.0）

  • 📊 性能基准测试：提供不同数据量下的官方性能数据（1k / 10k / 100k）
  • 🖥️ Web 管理界面：可视化浏览、编辑、删除记忆，查看统计图表
  • 🖼️ 多模态支持：图片记忆（图文混合检索）

如果你也在为 AI Agent 的记忆问题困扰，欢迎试用 SinoVec。你的 Star 是我们最大的动力。 ⭐

本文同步发布于：掘金 / 知乎 / CSDN / 开源中国 / Medium

avatar
文章
阅读
粉丝