🚧 本项目目前正在全面重写中

预计会出现破坏性变更和潜在Bug。
如发现任何问题，请提交GitHub Issue并附上详细信息，以便跟踪和修复。

OpenMemory

为AI代理提供真正的长期记忆。不是RAG，不是向量数据库。支持自托管，基于Python + Node。

OpenMemory是一个面向大型语言模型（LLM）和代理的认知内存引擎。

• 🧠 真正的长期记忆（不只是表中的嵌入向量）
• 💾 自托管，本地优先（支持SQLite/Postgres）
• 🐍 Python + 🟦 Node SDK
• 🧩 集成：LangChain、CrewAI、AutoGen、Streamlit、MCP、VS Code
• 📥 数据源：GitHub、Notion、Google Drive、OneDrive、网络爬虫
• 🔍 可解释的检索轨迹（查看记忆被召回的原因）

你的模型保持无状态。你的应用不再失忆。

---

☁️ 一键部署

快速启动共享的OpenMemory后端（包含HTTP API + MCP + 仪表盘）：

当需要嵌入式本地内存时使用SDK，当需要多用户组织级内存时使用服务器。

---

1. TL;DR – 10秒快速上手

🐍 Python（本地优先）

安装：

pip install openmemory-py

使用：

from openmemory.client import Memory

mem = Memory()
mem.add("用户偏好深色模式", user_id="u1")
results = mem.search("偏好设置", user_id="u1")
await mem.delete("memory_id")

注意：add、search、get、delete 是异步方法。在异步上下文中使用 await。

🔗 OpenAI

mem = Memory()
client = mem.openai.register(OpenAI(), user_id="u1")
resp = client.chat.completions.create(...)

🧱 LangChain

from openmemory.integrations.langchain import OpenMemoryChatMessageHistory

history = OpenMemoryChatMessageHistory(memory=mem, user_id="u1")

🤝 CrewAI / AutoGen / Streamlit

OpenMemory专为代理框架和UI提供底层支持：

• Crew风格代理：使用Memory作为共享长期存储
• AutoGen风格编排：将对话和工具调用存储为情景记忆
• Streamlit应用：通过user_id为每个用户提供持久化内存

具体集成模式请参阅文档中的集成章节。

---

🟦 Node / JavaScript（本地优先）

安装：

npm install openmemory-js

使用：

import { Memory } from "openmemory-js"

const mem = new Memory()
await mem.add("用户喜欢辣食", { user_id: "u1" })
const results = await mem.search("食物偏好", { user_id: "u1" })
await mem.delete("memory_id")

适用于以下场景：

• Node后端
• 命令行工具
• 本地工具
• 需要持久化内存但不想运行独立服务的场景

---

📥 数据连接器

直接从外部数据源导入数据到内存：

# python
github = mem.source("github")
await github.connect(token="ghp_...")
await github.ingest_all(repo="owner/repo")

// javascript
const github = await mem.source("github")
await github.connect({ token: "ghp_..." })
await github.ingest_all({ repo: "owner/repo" })

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

---

2. 运行模式：SDK、服务器、MCP

OpenMemory可以内嵌运行在应用中，也可以作为中心化服务运行。

2.1 Python SDK

• ✅ 默认使用本地SQLite
• ✅ 支持外部数据库（通过配置）
• ✅ 适合LangChain / LangGraph / CrewAI / 笔记本使用

文档：https://openmemory.cavira.app/docs/sdks/python

---

2.2 Node SDK

• 与Python相同认知模型
• 适合JS/TS应用
• 可本地运行或连接中心化后端

文档：https://openmemory.cavira.app/docs/sdks/javascript

---

2.3 后端服务器（多用户 + 仪表盘 + MCP）

适用于需要以下功能的场景：

• 组织级内存
• HTTP API
• 仪表盘
• 支持Claude / Cursor / Windsurf的MCP服务

从源码运行：

git clone https://github.com/CaviraOSS/OpenMemory.git
cd OpenMemory
cp .env.example .env

cd backend
npm install
npm run dev   # 默认监听8080端口

或使用Docker（API + MCP）：

docker compose up --build -d

可选：启用仪表盘服务：

docker compose --profile ui up --build -d

使用Doppler管理配置（推荐用于托管仪表盘/API的URL）：

cd OpenMemory
tools/ops/compose_with_doppler.sh up -d --build

检查服务状态：

docker compose ps
curl -f http://localhost:8080/health

后端暴露以下接口：

• /api/memory/* – 内存操作接口
• /api/temporal/* – 时序知识图谱
• /mcp – MCP服务
• 仪表盘UI（启用ui配置时）

---

3. 为什么选择OpenMemory（对比RAG，对比"纯向量"方案）

LLM在消息间会遗忘所有状态。
大多数"记忆"方案本质上只是RAG流水线：

• 文本被切分
• 转换为向量存储
• 通过相似度检索

它们无法理解：

• 某条信息是事实、事件、偏好还是情感
• 其时效性/重要性
• 与其他记忆的关联
• 特定时间点的真值状态

云服务记忆API带来：

• 供应商锁定
• 延迟问题
• 不透明的行为
• 隐私风险

OpenMemory为你提供真正的记忆系统：

• 🧠 多区域记忆（情景、语义、程序、情感、反思）
• ⏱ 时序推理（知晓特定时间的真值状态）
• 📉 衰减与强化机制（替代简单的TTL）
• 🕸 路标图（可遍历的关联链接）
• 🔍 可解释的检索轨迹（查看被召回的节点及其原因）
• 🏠 自托管，本地优先，数据完全可控
• 🔌 SDK + 服务器 + VS Code + MCP

它表现得像一个真正的内存模块，而非"加了营销文案的向量数据库"。

4. 传统方式 vs OpenMemory

Vector DB + LangChain（重度云依赖，流程繁琐）：

import os
import time
from langchain.chains import ConversationChain
from langchain.memory import VectorStoreRetrieverMemory
from langchain_community.vectorstores import Pinecone
from langchain_openai import ChatOpenAI, OpenAIEmbeddings

os.environ["PINECONE_API_KEY"] = "sk-..."
os.environ["OPENAI_API_KEY"] = "sk-..."
time.sleep(3)  # 云端预热

embeddings = OpenAIEmbeddings()
pinecone = Pinecone.from_existing_index(embeddings, index_name="my-memory")
retriever = pinecone.as_retriever(search_kwargs={"k": 2})
memory = VectorStoreRetrieverMemory(retriever=retriever)
conversation = ConversationChain(llm=ChatOpenAI(), memory=memory)

conversation.predict(input="I'm allergic to peanuts")

OpenMemory（3行代码，本地文件，无厂商锁定）：

from openmemory.client import Memory

mem = Memory()
mem.add("user allergic to peanuts", user_id="user123")
results = mem.search("allergies", user_id="user123")

✅ 零云配置 • ✅ 本地SQLite • ✅ 支持离线 • ✅ 自主数据库，自主架构

---

5. 核心功能概览

• 多维度内存
  情景记忆（事件）、语义记忆（事实）、程序记忆（技能）、情感记忆（感受）、反思记忆（洞察）。

• 时间知识图谱（Temporal knowledge graph）
  valid_from/valid_to时间窗口，时点真相，随时间演进。

• 复合评分机制
  显著度+时效性+共激活度，不局限于余弦距离。

• 衰减引擎
  按维度自适应遗忘，替代硬性TTL设置。

• 可解释召回
  通过"航路点（waypoint）"追踪显示上下文使用的具体节点。

• 嵌入支持
  兼容OpenAI、Gemini、Ollama、AWS，支持合成回退。

• 集成能力
  支持LangChain、CrewAI、AutoGen、Streamlit、MCP、VS Code等IDE。

• 数据连接器
  支持从GitHub、Notion、Google Drive、Google表格/幻灯片、OneDrive、网络爬虫导入数据。

• 迁移工具
  支持从Mem0、Zep、Supermemory等迁移记忆数据。

若您正在开发智能代理、协作助手、日志系统、知识工作者或编程助手，OpenMemory能让这些系统从"金鱼记忆"升级为真正具备记忆能力的智能体。

---

6. MCP与IDE工作流

OpenMemory内置原生MCP服务器，任何支持MCP的客户端均可将其作为工具使用。

Claude / Claude Code

claude mcp add --transport http openmemory http://localhost:8080/mcp

Cursor / Windsurf

.mcp.json配置：

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

支持的工具包括：

• openmemory_query
• openmemory_store
• openmemory_list
• openmemory_get
• openmemory_reinforce

您的IDE助手可直接查询、存储、列举和强化记忆，无需手动编写每个调用。

---

7. 时间知识图谱

OpenMemory将时间作为核心维度处理。

核心概念

• valid_from/valid_to - 真值时间窗口
• 自动演进 - 新事实自动闭合旧记录
• 置信衰减 - 旧事实渐进式失效
• 时点查询 - "X时间点什么为真？"
• 时间线 - 重建实体历史
• 变更检测 - 识别状态变更时间点

示例

POST /api/temporal/fact
{
  "subject": "CompanyX",
  "predicate": "has_CEO",
  "object": "Alice",
  "valid_from": "2021-01-01"
}

后续更新：

POST /api/temporal/fact
{
  "subject": "CompanyX",
  "predicate": "has_CEO",
  "object": "Bob",
  "valid_from": "2024-04-10"
}

Alice的任期自动闭合，时间线查询保持逻辑完整。

---

8. 命令行工具（opm）

opm命令行工具可直接与引擎/服务器通信。

安装

cd packages/openmemory-js
npm install
npm run build
npm link   # 将`opm`添加到系统路径

使用示例

# 启动API服务器
opm serve

# 新终端中：
opm health
opm add "Recall that I prefer TypeScript over Python" --tags preference
opm query "language preference"

支持命令

opm add "user prefers dark mode" --user u1 --tags prefs
opm query "preferences" --user u1 --limit 5
opm list --user u1
opm delete <id>
opm reinforce <id>
opm stats

适用于脚本编写、调试及非LLM流水线的记忆管理。

---

9. 架构设计（高层视图）

OpenMemory采用**分层内存分解（Hierarchical Memory Decomposition）**架构，叠加时间图谱层。

graph TB
    classDef inputStyle fill:#eceff1,stroke:#546e7a,stroke-width:2px,color:#37474f
    classDef processStyle fill:#e3f2fd,stroke:#1976d2,stroke-width:2px,color:#0d47a1
    classDef sectorStyle fill:#fff3e0,stroke:#f57c00,stroke-width:2px,color:#e65100
    classDef storageStyle fill:#fce4ec,stroke:#c2185b,stroke-width:2px,color:#880e4f
    classDef engineStyle fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px,color:#4a148c
    classDef outputStyle fill:#e8f5e9,stroke:#388e3c,stroke-width:2px,color:#1b5e20
    classDef graphStyle fill:#e1f5fe,stroke:#0277bd,stroke-width:2px,color:#01579b

    INPUT[输入 / 查询]:::inputStyle
    CLASSIFIER[维度分类器]:::processStyle

    EPISODIC[情景记忆]:::sectorStyle
    SEMANTIC[语义记忆]:::sectorStyle
    PROCEDURAL[程序记忆]:::sectorStyle
    EMOTIONAL[情感记忆]:::sectorStyle
    REFLECTIVE[反思记忆]:::sectorStyle

    EMBED[嵌入引擎]:::processStyle

    SQLITE[(SQLite/Postgres<br/>记忆数据 / 向量 / 航路点)]:::storageStyle
    TEMPORAL[(时间图谱)]:::storageStyle

    subgraph RECALL_ENGINE["召回引擎"]
        VECTOR[向量搜索]:::engineStyle
        WAYPOINT[航路点图]:::engineStyle
        SCORING[复合评分]:::engineStyle
        DECAY[衰减引擎]:::engineStyle
    end

    subgraph TKG["时间知识图谱"]
        FACTS[事实存储]:::graphStyle
        TIMELINE[时间线]:::graphStyle
    end

    CONSOLIDATE[整合处理]:::processStyle
    REFLECT[反思处理]:::processStyle
    OUTPUT[召回结果 + 追踪]:::outputStyle

    INPUT --> CLASSIFIER
    CLASSIFIER --> EPISODIC
    CLASSIFIER --> SEMANTIC
    CLASSIFIER --> PROCEDURAL
    CLASSIFIER --> EMOTIONAL
    CLASSIFIER --> REFLECTIVE

    EPISODIC --> EMBED
    SEMANTIC --> EMBED
    PROCEDURAL --> EMBED
    EMOTIONAL --> EMBED
    REFLECTIVE --> EMBED

    EMBED --> SQLITE
    EMBED --> TEMPORAL

    SQLITE --> VECTOR
    SQLITE --> WAYPOINT
    SQLITE --> DECAY

    TEMPORAL --> FACTS
    FACTS --> TIMELINE

    VECTOR --> SCORING
    WAYPOINT --> SCORING
    DECAY --> SCORING
    TIMELINE --> SCORING

    SCORING --> CONSOLIDATE
    CONSOLIDATE --> REFLECT
    REFLECT --> OUTPUT

    OUTPUT -.->|强化| WAYPOINT
    OUTPUT -.->|显著度| DECAY

---

10. 数据迁移

OpenMemory提供迁移工具支持从其他记忆系统导入数据。

支持来源：

• Mem0
• Zep
• Supermemory

示例命令：

cd migrate
python -m migrate --from zep --api-key ZEP_KEY --verify

（详见migrate/目录及文档中各提供商的具体命令）

11. 路线图

• 🧬 可学习的扇区分类器（可在您的数据上训练）
• 🕸 联邦学习/集群内存节点（Federated / clustered memory nodes）
• 🤝 更深入的 LangGraph / CrewAI / AutoGen 集成
• 🔭 内存可视化工具 2.0
• 🔐 可插拔的静态加密（Pluggable encryption at rest）

点击 Star 关注项目进展。

---

12. 贡献指南

欢迎提交问题反馈和 Pull Request。

• Bug 反馈: https://github.com/CaviraOSS/OpenMemory/issues
• 功能请求: 使用 GitHub 问题模板
• 进行重大更改前，请先发起讨论或提交小型设计 PR

---

13. 许可证

OpenMemory 采用 Apache 2.0 许可证。详情请参阅 LICENSE 文件。

OpenMemory 快速上手指南

---

🧰 环境准备

• Python 用户：Python 3.10+（推荐使用 清华源 加速安装）
• Node.js 用户：Node.js 18.x 或更高版本（推荐使用 nvm 管理版本）
• 数据库：默认使用 SQLite（无需额外安装），生产环境可选 PostgreSQL
• 后端部署：Docker 20+ 及 Docker Compose（建议安装 阿里云容器镜像加速器）

---

📦 安装步骤

Python SDK 安装

pip install openmemory-py -i https://pypi.tuna.tsinghua.edu.cn/simple

Node.js SDK 安装

npm install openmemory-js --registry=https://registry.npmmirror.com

后端服务部署（含 Web UI）

# 克隆仓库（国内用户可替换为 GitHub 镜像）
git clone https://github.com/CaviraOSS/OpenMemory.git
cd OpenMemory

# 使用 Docker Compose 启动服务
docker compose up --build -d

# 启动带 Web UI 的完整服务
docker compose --profile ui up --build -d

---

🚀 基本使用

Python 本地记忆操作

from openmemory.client import Memory

# 初始化本地内存引擎
mem = Memory()

# 添加记忆（支持异步）
await mem.add("用户喜欢辣食", user_id="u1")

# 搜索记忆
results = await mem.search("饮食偏好", user_id="u1")

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

Node.js 本地记忆操作

import { Memory } from "openmemory-js"

const mem = new Memory()
await mem.add("用户喜欢夜间工作", { user_id: "u1" })
const results = await mem.search("作息偏好", { user_id: "u1" })
await mem.delete("memory_id")

连接外部数据源（GitHub 示例）

# Python 连接 GitHub 仓库
github = mem.source("github")
await github.connect(token="your_github_token")
await github.ingest_all(repo="owner/repo")

后端服务启动验证

# 检查服务状态
docker compose ps

# 健康检查
curl -f http://localhost:8080/health

---

💡 国内加速建议：

1. Python 包安装时添加 -i https://pypi.tuna.tsinghua.edu.cn/simple
2. Docker 用户配置阿里云容器镜像加速器
3. Node.js 安装时添加 --registry=https://registry.npmmirror.com

---

通过以上步骤即可快速实现本地记忆存储或部署全功能服务，完整功能请参考官方集成文档。