每日一个开源项目（第136篇）：OpenMemory - 给 AI Agent 真正的认知记忆引擎

引言

"向量数据库记住了'说了什么'。OpenMemory 记住'它意味着什么、发生在什么时候、当时的感受如何、以及为什么重要'。"

这是"每日一个开源项目"系列的第136篇文章。今天的主角是 OpenMemory——一个为 AI Agent 和 LLM 应用构建的自托管认知记忆引擎。

LLM 天生无状态，每次对话结束后什么都不记得。大多数"记忆"方案其实是变相的 RAG：把文本切块、嵌入向量数据库、按相似度检索。这种方案不理解记忆的类型（事件、事实、技能、情感的区别），不理解时间（什么时候是真的），不理解重要程度（某条记忆比另一条更关键），不理解关联（这两件事有联系）。

OpenMemory 的出发点是：给 AI Agent 一个真正类人的记忆系统，而不是一个贴了"记忆"标签的向量数据库。

你将学到什么

• 五扇区记忆模型：情节、语义、程序、情感、反思各自的含义和衰减特性
• HMD v2 架构：分层记忆分解如何工作
• Waypoint 联想图：单一最强路径图和复合评分公式
• 时序知识图谱：valid_from / valid_to 和事实演化
• 与 RAG/向量数据库的本质区别
• 三种运行模式：嵌入式 SDK、独立服务器、MCP 接口

前置知识

• 了解 LLM Agent 的基本概念
• 使用过 LangChain、CrewAI 或类似 Agent 框架
• 了解向量嵌入和余弦相似度的基本概念

---

项目背景

项目简介

OpenMemory 是一个开源的认知记忆引擎，基于 HMD（Hierarchical Memory Decomposition）v2 架构，为 LLM 和 AI Agent 提供持久化的结构化记忆。

它不是向量数据库的包装，也不是云端记忆 API 的替代品。它的设计哲学是：记忆不是一个数据库，而是一个动态系统，有衰减、有强化、有关联、有时间维度。

项目由 CaviraOSS 组织维护，提供 Python SDK、Node.js SDK、REST API 服务、VS Code 扩展和原生 MCP 服务器。

作者/团队介绍

• 组织: CaviraOSS
• 主要语言: TypeScript/Node.js（服务器），Python（SDK）
• License: Apache 2.0
• VS Code 扩展: marketplace.visualstudio.com

项目数据

• 📄 License: Apache 2.0
• 🐍 PyPI: openmemory-py
• 📦 npm: openmemory-js
• 🧩 集成: LangChain、CrewAI、AutoGen、Streamlit、MCP、VS Code

---

主要功能

核心作用

传统 RAG 记忆（向量数据库）：
"用户喜欢在晚上编程，感觉很高效"
    → 一条 embedding 向量
    → 按相似度检索，没有结构，没有时间，没有重要程度

OpenMemory 认知记忆：
"用户喜欢在晚上编程，感觉很高效"
    → semantic 扇区："编程偏好"（慢衰减）
    → emotional 扇区："感觉高效"（较快衰减）
    → episodic 扇区："时间：晚上"（最快衰减）
    → 三个扇区向量 → 生成均值向量 → Waypoint 链接到关联记忆
    → 复合评分 = 0.6×相似度 + 0.2×重要性 + 0.1×时效性 + 0.1×图权重

使用场景

1. 长期对话助手：跨会话记住用户偏好、习惯、历史事件，不需要每次重复上下文
2. Agent 框架记忆层：为 CrewAI、AutoGen、LangGraph 的 Agent 提供共享长期记忆存储
3. 知识工作者工具：把 GitHub、Notion、Google Drive 的内容摄入记忆，Agent 可以问"上周的设计决策是什么"
4. 编程助手：用户的代码偏好、项目背景、技术栈选择持久化跨会话
5. 情感感知应用：情感扇区单独存储情感类信息，避免它污染事实类记忆的检索

快速开始

Python SDK（本地 SQLite，零配置）：

pip install openmemory-py

from openmemory.client import Memory

mem = Memory()

# 添加记忆
await mem.add("用户对花生过敏", user_id="user123")
await mem.add("用户喜欢在晚上编程", user_id="user123")

# 查询记忆（复合评分排序）
results = await mem.search("用户有什么饮食限制？", user_id="user123")

# 强化某条记忆（提升 salience）
await mem.reinforce("memory_id")

# 删除记忆
await mem.delete("memory_id")

Node.js SDK：

npm install openmemory-js

import { Memory } from "openmemory-js"

const mem = new Memory()
await mem.add("用户偏好 TypeScript 而非 Python", { user_id: "u1" })
const results = await mem.search("语言偏好", { user_id: "u1" })

与 LangChain 集成：

from openmemory.integrations.langchain import OpenMemoryChatMessageHistory

history = OpenMemoryChatMessageHistory(memory=mem, user_id="u1")
# 直接替换 LangChain 的 ConversationBufferMemory

与 OpenAI 集成（拦截器模式）：

mem = Memory()
client = mem.openai.register(OpenAI(), user_id="u1")
# 之后的所有 chat.completions.create 调用自动存入/检索记忆
resp = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "我应该用什么语言？"}]
)

摄入外部数据源：

# 摄入 GitHub 仓库
github = mem.source("github")
await github.connect(token="ghp_...")
await github.ingest_all(repo="owner/repo")

# 摄入 Notion 页面
notion = mem.source("notion")
await notion.connect(token="secret_...")
await notion.ingest_all(database_id="xxx")

支持的连接器：github、notion、google_drive、google_sheets、google_slides、onedrive、web_crawler

MCP 接入（Claude Code / Cursor）：

# Claude Code
claude mcp add --transport http openmemory http://localhost:8080/mcp

// Cursor .mcp.json
{
  "mcpServers": {
    "openmemory": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

MCP 工具：openmemory_query、openmemory_store、openmemory_list、openmemory_get、openmemory_reinforce

五扇区记忆模型

扇区	含义	衰减速率	权重
episodic	事件和经历（发生了什么、什么时候）	0.015（较快）	1.2
semantic	事实和知识（用户偏好、领域知识）	0.005（最慢）	1.0
procedural	技能和流程（怎么做某事）	0.008（中等）	1.1
emotional	情感和态度（感受如何）	0.020（最快）	1.3
reflective	元认知和洞察（意识到了什么）	0.001（极慢）	0.8

衰减公式：salience × e^(-decay_lambda × days_since_last_seen)

衰减每 24 小时运行一次；每 7 天清理权重低于 0.05 的 Waypoint 链接。

---

项目详细剖析

HMD v2 架构

输入内容
    ↓
扇区分类器（Sector Classifier）
    ├── 识别主要扇区 + 次要扇区
    └── 基于关键词模式 + 上下文
    ↓
多扇区嵌入（Multi-Sector Embedding）
    ├── 每个相关扇区独立生成 embedding 向量
    ├── 支持：OpenAI / Gemini / AWS / Ollama / 本地模型 / 合成向量
    └── 计算所有扇区向量的均值向量（mean vector）
    ↓
存储（SQLite / Postgres）
    ├── memories 表：内容 + 元数据 + 重要性分数 + 衰减参数
    ├── vectors 表：每条记忆 × 每个扇区 = 一个向量
    └── waypoints 表：记忆间的单一最强联想链接
    ↓
查询时：复合评分
    score = 0.6×相似度 + 0.2×重要性 + 0.1×时效性 + 0.1×Waypoint权重

Waypoint 联想图

这是 OpenMemory 区别于向量数据库的关键设计之一：

记忆 A ──0.85──▶ 记忆 B
（只保留相似度最高的那条链接）

添加记忆时，自动寻找余弦相似度 ≥ 0.75 的最相似记忆，建立单向 Waypoint 链接（跨扇区时建立双向链接）。

查询时，在 top-K 向量检索结果基础上，做 1-hop 图遍历扩展，把被 Waypoint 指向的关联记忆也纳入评分。每次被召回，Waypoint 权重提升 +0.05（最大 1.0），形成"经常被一起想到 → 链接越来越强"的强化机制。

这个设计的效果是：即使查询语义上与某条记忆不完全匹配，只要查询的记忆和它有强 Waypoint 关联，它也会被召回。

时序知识图谱

OpenMemory 把时间作为一等公民：

# 2021 年添加事实
POST /api/temporal/fact
{
  "subject": "CompanyX",
  "predicate": "has_CEO",
  "object": "Alice",
  "valid_from": "2021-01-01"
}

# 2024 年更新
POST /api/temporal/fact
{
  "subject": "CompanyX",
  "predicate": "has_CEO",
  "object": "Bob",
  "valid_from": "2024-04-10"
}
# Alice 的任期自动关闭（valid_to = 2024-04-09）

支持：

• valid_from / valid_to 真值时间窗口
• 时间点查询（"2022年底 CompanyX 的 CEO 是谁？"）
• 变更检测（某个事实什么时候翻转了）
• 实体时间线重建

性能数据

在 100k 条记忆规模下（SQLite，WAL 模式）：

操作	延迟
添加记忆	80-120 ms（取决于嵌入服务商）
单扇区查询	110-130 ms
多扇区融合查询（2-3个扇区）	150-200 ms
Waypoint 展开（每 hop）	+30-50 ms
衰减计算（后台）	~10 秒（每 24 小时一次）

存储规模：

• 单条记忆：约 4-6 KB（含所有扇区向量）
• 100k 条记忆：约 500 MB
• 100 万条记忆：约 5 GB

与 SaaS 方案对比

维度	OpenMemory	Supermemory	OpenAI Memory
托管方式	自托管	仅云端	仅云端
查询延迟	110-130 ms	350-400 ms	~300 ms
1M token 费用	~$0.30-0.40	~$2.50+	~$3.00+
可解释性	完全透明（可查 Waypoint 路径）	黑盒	黑盒
本地嵌入	支持（Ollama、本地模型）	不支持	不支持
数据所有权	100% 你自己	供应商持有	OpenAI 持有

从其他系统迁移

OpenMemory 支持从现有记忆系统导入数据：

cd migrate
# 从 Mem0 迁移
python -m migrate --from mem0 --api-key MEM0_KEY --verify

# 从 Zep 迁移
python -m migrate --from zep --api-key ZEP_KEY --verify

# 从 Supermemory 迁移
python -m migrate --from supermemory --api-key SM_KEY --verify

---

项目地址与资源

官方资源

• 🌟 GitHub: CaviraOSS/OpenMemory
• 📦 PyPI: openmemory-py
• 📦 npm: openmemory-js
• 🔌 VS Code 扩展: openmemory-vscode
• 📄 架构文档: ARCHITECTURE.md（项目仓库内）

---

总结

OpenMemory 做的事情是：把"记忆"这个概念认真实现一遍。

大多数人谈"AI 记忆"的时候，实际上谈的是检索增强（RAG）——存向量，查相似。OpenMemory 的立场是：这不是记忆，这是搜索引擎。真正的记忆系统需要知道一件事是事实还是情感、是最近发生的还是很久以前的、现在是否还成立、和其他什么记忆有关联。

五扇区模型、Waypoint 联想图、时序知识图谱、复合评分——这些设计不是为了让代码看起来复杂，而是对应了人类记忆的不同维度。

对于正在构建需要跨会话记忆的 Agent 应用的开发者，OpenMemory 是目前开源方案里架构思考最清晰的之一：自托管、本地优先、框架无关、可解释、性能可预测。三行代码接入，按需扩展到完整服务器模式。

---

探索 PrimeSkills —— 精选 AI Agent 与技能的市场，每一个都经过真实企业工作流验证，去掉浮夸，留下真正有用的。

欢迎访问我的个人主页，发现更多有价值的见解和有趣的产品。