OpenMemory 技术研究报告
- 研究对象：
/Users/daoyu/Documents/agent_memory_repo/OpenMemory - 研究时间： 2026-03-09
- 研究方法： 静态代码审阅（JS/TS + Python 双实现）、配置与文档交叉验证、CI/CD 与部署文件核对
1. 项目概述
1.1 目标与定位
OpenMemory 的核心目标是为 LLM/Agent 提供”长期记忆层”，强调区别于传统 RAG 的”仅向量检索”模式。项目定位为：
- 本地优先、可自托管的记忆引擎
- 同时支持 SDK 嵌入式模式（Python/Node）与服务化模式（HTTP + MCP）
- 面向多 Agent 框架集成（LangChain、MCP、IDE 插件等）
1.2 核心价值
从代码实现看，核心价值主要体现在：
- 记忆语义分层： 以 sector（episodic/semantic/procedural/emotional/reflective）组织记忆
- 多因子检索排序： 相似度 + 词项重叠 + 时间衰减 + waypoint 图关联 + tag 匹配
- 时间维度能力： 独立 temporal graph（事实时效、历史查询）
- 多形态接入： REST API、MCP 工具协议、VSCode 扩展、Python/JS SDK
2. 架构设计
2.1 整体架构
项目是 Monorepo，主要由以下部分构成：
packages/openmemory-js：主后端实现（HTTP 服务、MCP、核心记忆算法、数据层）packages/openmemory-py：Python SDK 与轻量 API（FastAPI）apps/vscode-extension：IDE 侧事件采集与上下文查询- 根目录部署与文档：
docker-compose.yml、render.yaml、railway.json、docs/*
2.2 模块划分
JS 主实现可分为：
- 接口层：
src/server/routes/* - 记忆引擎：
src/memory/hsg.ts - 嵌入层：
src/memory/embed.ts - 数据层：
src/core/db.ts+src/core/vector/* - 时序图：
src/temporal_graph/* - 外部连接器：
src/sources/* - 协议层：
src/ai/mcp.ts
2.3 设计模式与特征
- 策略模式： embedding provider（openai/gemini/aws/ollama/local/synthetic）按配置切换
- 分层抽象：
VectorStore接口 + Postgres/Valkey 实现 - 双轨存储： metadata backend（sqlite/postgres）与 vector backend（pgvector/valkey/兼容模式）
- 后台任务： 衰减、反思、用户摘要定时执行
3. 技术栈分析
3.1 语言与框架
- Node 端： TypeScript + Node.js（自定义轻量 HTTP server，不是 Express）
- Python 端： Python + FastAPI
- IDE 端： TypeScript + VSCode Extension API
3.2 核心依赖
- 向量/数据库：
sqlite3、pg、ioredis - AI 接口：
openai、Gemini API、AWS Bedrock、Ollama - 文档处理：
pdf-parse、mammoth、cheerio、turndown - 协议：
@modelcontextprotocol/sdk（MCP）
3.3 工具链
- JS 构建： TypeScript (
tsc)、tsx - Python 打包：
hatchling - CI： GitHub Actions（Python/Node 测试、Docker build、SDK 发布）
4. 核心功能
4.1 记忆写入与分类
add_hsg_memory() 流程包含：
- simhash 去重 + 汉明距离判重
- sector 分类（正则打分）
- 多 sector embedding
- memory/vector 写入
- 均值向量 + waypoint 建图
4.2 记忆检索
hsg_query() 机制：
- 多 sector 向量召回
- waypoint 扩展召回
- keyword/tag/token overlap 融合打分
- z-score 标准化 + top-k
- 命中后强化（salience/waypoint/feedback）
4.3 衰减与强化
- 定时衰减（sector decay_lambda）
- 查询强化与关联传播
- waypoint 弱边清理
4.4 文档摄取
- text/pdf/docx/url 输入
- 长文 root-child 分段
- root-child waypoint 连接
4.5 时序图能力（Temporal Graph）
- 三元组事实 + valid_from/valid_to
- 支持当前事实、历史时点、时间窗口、对比与波动查询
4.6 协议与生态
- MCP tools：
openmemory_query/store/get/delete/list/... - VSCode 扩展： IDE 事件写入 + context 查询 + AI 工具自动配置
5. 数据模型
5.1 主要表结构（JS）
memories：内容、sector、salience、simhash、meta、mean_vec、versionvectors/openmemory_vectors：(id, sector, user_id, v, dim)waypoints：src_id -> dst_id（单出口）users：用户摘要stats：运行指标temporal_facts、temporal_edges：时序事实图
5.2 存储方案
- metadata： SQLite 或 PostgreSQL
- vector： pgvector 或 Valkey（SQLite 场景为兼容实现）
5.3 评价
- 优点： 生命周期字段完整，支持演化记忆
- 风险： 存在硬编码表名/路径，PG 自定义表名时有兼容隐患
6. API 设计
6.1 接口族
- Memory：
/memory/* - Temporal：
/api/temporal/* - Compression：
/api/compression/* - IDE：
/api/ide/* - Users：
/users/* - Sources：
/sources/* - MCP：
/mcp
6.2 通信协议
- HTTP/JSON
- MCP（streamable HTTP/stdio）
6.3 认证授权
OM_API_KEY（x-api-key/ Bearer / ApiKey）- 公共白名单接口放行
- 进程内限流（Map）
6.4 评价
- 覆盖广、集成深
- 路由前缀不统一，文档与实现存在偏差
7. 代码质量
7.1 组织性
- 模块边界清晰，双语言实现镜像明显
- 但存在历史漂移、无效脚本与重复/残留实现
7.2 测试
- 有 CI，但偏”场景脚本测试”
- 缺少系统化单测、契约测试、并发与事务边界测试
7.3 文档一致性
- 文档数量多，但与代码不同步问题明显（接口、命令、目录结构）
7.4 结论
- 核心能力强，工程一致性不足，长期维护成本偏高
8. 部署方案
8.1 已提供
- JS backend Dockerfile
docker-compose.yml- Render/Railway/Vercel 配置
- GitHub Actions CI/CD
8.2 评价
- 后端镜像方案相对完整（多阶段、非 root、healthcheck）
dashboard/目录仅有 Dockerfile，无前端源码，compose dashboard 服务可构建性存疑- 部分平台 healthcheck 路径与实际健康接口不一致（如
/vs/health）
9. 创新点
- Sector 化记忆 + 衰减/强化 + waypoint 图融合检索
- HSG（上下文记忆）与 Temporal（时序事实）双系统并存
- SDK + REST + MCP + IDE 插件的一体化交付路径
10. 改进建议
P0（优先）
- 对齐文档/脚本/实现，清理过时路径与命令
- 统一 API 前缀与版本策略（建议
/api/v1/*） - 处理 dashboard 交付不完整问题（补齐源码或移除默认 compose 服务）
P1（中期）
- 统一 SQL 适配策略，避免硬编码表名
- 默认安全策略收紧（CORS 白名单、租户边界）
- 补齐单测/契约测试/跨后端一致性测试
P2（演进）
- 标准化观测体系（结构化日志 + 指标导出）
- 优化 N+1 查询与检索阶段批处理
- 建立配置 schema 校验并消除默认值冲突
综合评价
| 维度 | 评分 |
|---|---|
| 技术创新 | 8.5/10 |
| 架构完整度 | 7.5/10 |
| 工程成熟度 | 6.0/10 |
| 生产可维护性 | 6.5/10 |
结论： OpenMemory 在 Agent 长期记忆能力上实现深度较高，产品方向明确；当前最需要的是工程收敛与一致性治理，而非继续扩展功能面。
报告生成工具：Codex (GPT-5.2-codex)
研究耗时：约 15 分钟
代码库规模：~50,000+ 行代码（JS/TS + Python）