AI 智能体外挂记忆系统：Memory Sidecar v3.2 架构解析

#ai #automation #opensource

AI 智能体每次新会话都是白纸一张。这不是缺陷，是架构约束。但生产环境里，这约束不能忍——客户背景、项目上下文、历史决策，每次都得重新喂。

Memory Sidecar 的解法很直接：不碰智能体核心代码，在旁边跑一个独立记忆进程，让智能体「想起来」。最近 v3.2 发布，我拆了一遍它的设计，值得记一笔。

三层记忆，不是四层

v3.0 是四层架构，有个 agentmemory Docker 桥接层挂在中间。v3.1 砍掉了——那层 Docker 存着 13 条过期数据，除了加延迟没别的作用。现在三层：

热层 — memory tool 直接注入，5KB 上限，存当前用户画像和配置，0ms 延迟
温层 — Hindsight (PostgreSQL 16)，存提取的事实和重复模式，~50ms
冷层 — gbrain 知识图谱 + FTS5 全文搜索，永久归档，~500ms–2s

召回时三层并行检索，RRF 融合排序。哪层命中用哪层，不强求冷层。

Focused Dossier：重点档案

v3.1 引入的实用功能。声明一个「重点档案」，包含别名列表、主题标记、保留优先级和时间线追踪。命中关键词就优先走档案检索，不会被清理。

第一个投产实例是关系记忆档案——数百个会话、数千条提取事实的规模下验证了这套模式稳定。加新档案只需要在 memory_family_registry.py 里加一条 profile。

v3.2 更新了什么

两个新增脚本 + 两个改进：

memory_watermark.py — 自动检测记忆体容量，归档过期条目，防止膨胀
memory_snapshot_backup.py — 周期性快照备份，出事能回滚
hindsight-service.py — 简化独立守护进程，使用现有 PG（5432），不再另起端口
hindsight_mcp_bridge.py — 清理行尾格式，改进 MCP stdio 桥接
session_to_gbrain.py — 基于环境变量的 Token 配置，不再硬编码密钥

Embedding 服务：50 行代码

语义搜索是冷层召回的关键。项目不捆绑 embedding 服务，给你一个最小实现自己部署：

from sentence_transformers import SentenceTransformer
from http.server import HTTPServer, BaseHTTPRequestHandler
import json

model = SentenceTransformer("intfloat/multilingual-e5-small")

class Handler(BaseHTTPRequestHandler):
    def do_POST(self):
        length = int(self.headers.get("Content-Length", 0))
        body = json.loads(self.rfile.read(length))
        texts = body.get("input", [])
        emb = model.encode(texts, normalize_embeddings=True).tolist()
        self.send_response(200)
        self.send_header("Content-Type", "application/json")
        self.end_headers()
        self.wfile.write(json.dumps(
            {"data": [{"embedding": e} for e in emb]}
        ).encode())

HTTPServer(("127.0.0.1", 8766), Handler).serve_forever()

支持 6 种模型，从 96MB 的 BGE-small-zh 到 2GB 的 BGE-m3，按资源选。不装也能用——FTS5 全文搜索本身够应付大部分场景。

生产数据

不是玩具。从 2026 年 4 月起连续生产运行至今：

10,885 个 gbrain 页面 — 完整知识图谱
42,481 个 Hindsight 节点 — 提取的事实
105,601 条索引消息 — FTS5 全文覆盖
100% 嵌入覆盖率
脑分 73

适配任意智能体

只读 $AGENT_HOME/state.db 和会话文件，完全在智能体进程外运行。设 AGENT_HOME=~/.claude 就适配 Claude Code，~/.cursor 适配 Cursor。安装器一键部署九个核心脚本，cron 调度日常维护周期。

核心思路就一条：记忆是基础设施，不是功能。 把它从智能体代码中解耦出来，独立演进、独立维护，生产环境才能跑得稳。

项目地址：github.com/mage0535/hermes-memory-installer

DEV Community