内容
# 开放记忆
作为MCP服务器暴露的AI记忆引擎。具有服务器端智能的结构化知识 - 领域路由、实体提取、重复数据删除和更新。任何AI工具都可以查询它。你拥有数据。
## 问题
AI代理可以存储知识，但现有方法限制了其有效结构化和检索。像ChatGPT和Claude这样的内置记忆存储的是平文本，没有模式或关系 - 并且在工具之间不可移植。开发库提供了内存原语，但需要大量集成工作。知识图引擎在每次摄入时提供了丰富的实体提取，但代价是多个LLM调用和操作开销。轻量级解决方案实现了跨工具共享，但没有结构、置信度评分或重复数据删除。
共同的差距：结构化、基于模式的知识，具有有效的检索功能，适用于任何AI工具，无需大量基础设施成本。
## 解决方案
一个累积结构化知识的地方 - 验证后，由你拥有 - 并且每个AI工具都可以查询，拥有细粒度权限。适用于个人身份、团队知识、项目上下文或任何AI需要持久记忆的用例。
## 快速入门
将以下内容添加到您的AI工具的MCP配置中：
<!-- x-release-please-start-version -->
```json
{
"mcpServers": {
"openmemory": {
"command": "npx",
"args": ["-y", "@openmem/mcp@0.8.0"]
}
}
}
```
<!-- x-release-please-end -->
与Claude Code、Claude Desktop、Cursor以及任何MCP兼容的工具一起使用。默认情况下，数据存储在`~/.openmemory`中。要更改此设置，请在上面的配置中添加`"env": { "OPENMEMORY_DATA": "/absolute/path" }`。
> **禁用客户端内置记忆。** OpenMemory取代了它 - 同时运行两个系统会分散你的知识。在Claude Desktop中：设置 → 记忆 → 关闭。在ChatGPT中：设置 → 个性化 → 记忆 → 关闭。这确保OpenMemory是唯一的真实来源。
## 工作原理
OpenMemory通过两条互补的路径捕获知识：
1. **快速捕获** — 在对话过程中，AI调用`capture_fact`以捕获有用的信息。事实立即存储在会话暂存缓冲区中。
2. **批量合并** — 定期地，服务器将所有待处理事实作为一批进行处理：分类领域，提取实体（人、地点、组织），检测重复和矛盾，并构建知识图。
可选地，服务器还可以在合并期间扫描原始对话事件，以提取AI错过的事实 - 一个安全网，确保重要的知识不会丢失。
结果是一个结构化的、不断演化的知识图，任何AI工具都可以通过MCP查询。
## 功能
- **混合知识捕获** — AI在对话中明确捕获事实。可选地，服务器还可以在合并期间从原始事件中提取事实作为安全网。
- **批量合并** — 定期处理将待处理捕获项整合到长期知识图中：分类领域，提取实体，解决重复项，检测矛盾。
- **实体图** — 自动提取和链接人员、地点、组织。关系强度跟踪证实。
- **混合搜索** — BM25关键词 + 结构化领域 + 实体图路径，通过互惠排名融合与时间衰减合并。
- **会话内存** — 最近捕获的事实通过`get_session_context`立即访问，即使在合并之前。
- **不可变历史** — 事实从不被删除，只被更新。保留完整历史。
- **源可追溯性** — 每个事实都链接回生成它的对话事件。
- **手动合并** — 在自然断点（主题更改、任务完成、预压缩）调用`consolidate`。无需依赖会话边界。
## MCP 资源
资源是客户端自动加载的上下文 - 无需工具调用，无需AI决策。工具只有在助手记得调用时才有帮助；资源只是存在。
- `memory://briefing` — 当前需要知道的一切：个人资料、最近合并中学习的内容、开放线程和最近的知识。Markdown，保持在屏幕大小左右。
- `memory://profile` — 核心身份事实，最重要的事实优先。
这两个都是只读视图，覆盖相同的数据库，工具查询的数据相同，因此它们不会与其分离。它们在读取时重新生成，订阅的客户端在合并更改它们要说的内容时会收到通知。没有资源支持的客户端不会失去功能 - 下面按需涵盖的读取工具。
## MCP 工具
### 会话
- `log_event` — 记录对话事件（消息、工件）。
- `get_events` — 从当前或之前的会话中检索事件。
- `get_session_context` — 回忆当前会话中捕获的事实（会话工作内存）。
### 读取
- `get_entity` — 关于任何命名主题的全部已知信息 - 人、组织、项目、地点、产品 - 以及它如何连接
- `get_context` — 与主题相关的全部信息（搜索 + 实体遍历）
- `search_knowledge` — 跨渐进知识的混合搜索
### 编写
- `capture_fact` — 存储一个事实。快速追加，会话标签。完整的智能延迟到合并。
- `consolidate` — 将待处理事实整合到长期知识中。提取实体，解决重复项，检测矛盾，构建知识图。在自然断点或上下文压缩前调用。
### 元
- `get_schemas` — 可用的领域和结构
- `get_stats` — 事实计数、实体计数、领域分布
## 会话事件日志
OpenMemory捕获每个交互作为`SessionEvent` - DIKW数据层。这是巩固、搜索和回忆的基础。
### 事件如何被捕获
所有事件都通过`log_event` MCP工具或`openmemory log-event` CLI命令捕获。调用AI记录对话消息；Claude Code钩子可以自动化此过程：
### Claude Code 钩子
对于Claude Code，钩子提供确定性的捕获 - 它们每次都触发，无论AI是否“记住”工具描述。
#### 可用的钩子
| 钩子 | 触发条件 | 捕获内容 |
|------|-----------|-----------------|
| `UserPromptSubmit` | 用户发送消息 | 完整的提示文本 |
| `Stop` | 助手完成响应 | 最后一个助手消息 |
| `PostToolUse` | 工具调用完成 | 工具名称、输入和响应 |
#### 设置
为钩子安装CLI：
```bash
npm install -g @openmem/mcp
```
或者，在下面的钩子命令中将`openmemory`替换为`npx -y @openmem/mcp`（无需安装，但每个钩子增加约2-3秒延迟）。
将以下内容添加到`.claude/settings.json`（项目级）或`~/.claude/settings.json`（全局）：
```json
{
"hooks": {
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "openmemory log-event --role user --event-type message"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "openmemory log-event --role assistant --event-type message"
}
]
}
],
"PostToolUse": [
{
"matcher": "^(?!mcp__openmemory__)",
"hooks": [
{
"type": "command",
"command": "openmemory log-event --role tool --event-type tool_result"
}
]
}
]
}
}
```
CLI从标准输入中读取钩子JSON有效载荷，并提取相关的内容字段（`prompt`用于`UserPromptSubmit`，`last_assistant_message`用于`Stop`，用于`PostToolUse`的完整JSON）。事件被追加到数据库中最近活动的会话中。
`PostToolUse`匹配器排除OpenMemory自己的工具（`^(?!mcp__openmemory__)`），以避免捕获内部操作。
### CLI 参考
#### `openmemory init [dir]`
可选 - 服务器无论如何都会在第一次运行时创建其数据目录和数据库。使用`init`提前设置并编写一个可以调整的`config.json`（默认情况下不可见）：
```bash
# 初始化默认位置（~/.openmemory）：
openmemory init
# 或特定目录：
openmemory init ~/my-memory
# 选项：
# --data 数据目录（替代位置参数）
# --force 用默认配置覆盖现有的config.json
```
它创建数据目录，应用数据库模式，写入带有预设默认值的`config.json`，并打印一个可以直接粘贴的MCP配置块。重新运行是安全的：现有的`config.json`保持不变，除非您传递`--force`，否则您的数据将被保留。
生成的`config.json`是您更改合并行为的地方 - 最值得注意的是`intelligence.provider`，它选择如何提取事实（默认情况下为`cli`，运行`claude` CLI；设置为`heuristic`以获取零依赖的正则表达式回退，或在运行时使用`OPENMEMORY_PROVIDER=heuristic`覆盖）。
#### `openmemory log-event`
`openmemory log-event`命令直接将事件插入数据库（无需运行服务器）：
```bash
# 从钩子（从标准输入读取JSON有效载荷）：
echo '{"hook_event_name":"UserPromptSubmit","prompt":"hello"}' | openmemory log-event --role user
# 使用显式内容：
openmemory log-event --role user --event-type message --content "hello world"
# 选项：
# --role user | assistant | system | tool （默认：user）
# --event-type message | tool_calls | tool_result | artifact （默认：message）
# --content-type text | json | image | audio | binary （默认：text）
# --content 事件内容（或通过标准输入管道）
# --session-id 目标会话（默认：最近的）
# --data 数据目录（默认：~/.openmemory 或 $OPENMEMORY_DATA）
```
#### `openmemory search <query>`
从命令行搜索知识库。此命令运行与`search_knowledge`工具相同的混合搜索，因此它可以回答“它实际上对我了解什么？”和“为什么AI会说这？”等问题，而无需连接客户端：
```bash
openmemory search "coffee"
# 优先考虑一个领域：
openmemory search "coffee" --domain preferences
# 适用于脚本的机器可读输出：
openmemory search "coffee" --json
# 选项：
# --domain 优先考虑一个领域（profile, preferences, medical, people, work,
# 或正在使用的任何其他领域）。偏置排名；不过滤 - 参见下文
# --limit 最大结果数（默认：20）
# --json 发出原始搜索有效载荷而不是格式化文本
# --data 数据目录（默认：~/.openmemory 或 $OPENMEMORY_DATA）
```
结果带有相关性评分和置信度，以及整个结果集的覆盖率和置信度估计 - 因此结果集稀疏时看起来是稀疏的，而不是默默地假装完整。
`--domain` **偏置排名而不是过滤。** 领域由分类器分配并且是近似的，因此您要查找的事实可能被归类为近义词。硬过滤器会隐藏它并显示您空的结果，并且无法区分“什么都不知道”和“它被归类为其他领域”。排名在过滤器绝对失败的地方会退化。
#### `openmemory stats`
显示知识库的内容 - 事实计数、实体、领域以及事实在领域之间的分布：
```bash
openmemory stats
openmemory stats --json
# 选项：
# --json 发出原始统计数据有效载荷而不是格式化文本
# --data 数据目录（默认：~/.openmemory 或 $OPENMEMORY_DATA）
```
事实是不可变的 - 更新的事实被保留，从不删除 - 因此当前计数和总数合法地在发生任何更新后有所不同。两者都已报告。
## 集成模式
OpenMemory的工具描述是主要的集成层 - 它们告诉AI助手何时捕获事实和搜索知识，与每个MCP客户端开箱即用。对于更深层次的集成，客户端可以在对话生命周期中的关键时刻添加**基于规则的钩子**（加载到AI的上下文中的指令）。这些是可选的，但使捕获和检索更加可靠。
### 无需配置
`capture_fact`工具描述告诉AI“主动调用此工具以获取有用的信息。” `search_knowledge`描述表示“在回答可能受益于个人上下文的问题之前调用此工具。” 这些描述与服务器一起提供，并在无需客户端设置的情况下驱动行为。
### 钩子点
| 钩子点 | 何时 | 调用什么 | 为什么重要 |
|---|---|---|---|
| 会话开始 | 对话开始 | `get_profile`, `search_knowledge` | AI从第一条消息就知道你是谁 |
| 主动捕获 | 用户提及偏好、事实或决定 | `capture_fact` | 知识在会话中累积 |
| 预响应搜索 | 在生成回复之前 | `search_knowledge`, `get_context` | 回答以个人知识为依据 |
| 预压缩 | 在上下文窗口压缩之前 | `consolidate` | 在上下文被清除之前处理待处理事实 |
| 自然断点 | 主题更改、任务完成 | `consolidate`（可选） | 保持知识图当前 |
**关于预压缩：** 这是最有价值的钩子点 - 如果没有它，知识会在客户端压缩上下文时默默丢失。在压缩之前调用`consolidate`会将所有待处理事实处理为长期知识。如果启用事件提取，服务器还会扫描原始对话事件以提取AI错过的事实。
### Claude Code
在项目中创建`.claude/rules/openmemory.md`（或全局的`~/.claude/rules/openmemory.md`）。这会自动加载到上下文中：
```markdown
# OpenMemory
- 在每次对话开始时，调用`get_profile`以加载身份上下文
- 在回答有关偏好、人员或历史的问题之前，调用`search_knowledge`
- 当用户提及偏好、个人详细信息、关系或决定时，调用`capture_fact`
- 当对话过长时，调用`consolidate`以处理待处理事实，然后再丢失
- 在自然断点（主题更改、任务完成）处，调用`consolidate`以保持知识图更新
```
要允许OpenMemory工具而无需每次调用的批准提示，请在`.claude/settings.json`的`permissions.allow`数组中添加：
```json
{
"permissions": {
"allow": [
"mcp__openmemory__*"
]
}
}
```
### Cursor / Windsurf
在项目根目录中将以下内容添加到`.cursorrules`（Cursor）或`.windsurfrules`（Windsurf）：
```
当OpenMemory MCP服务器可用时：
- 在对话开始时，调用get_profile加载用户上下文
- 在回答有关偏好或历史的问题之前，调用search_knowledge
- 当用户共享偏好、事实或决定时，调用capture_fact
- 当上下文过长时，调用consolidate以处理待处理事实
```
### Claude Desktop / 其他MCP客户端
无需配置。工具描述自动处理集成 - AI助手读取工具描述并知道何时捕获和搜索。
## 开发
```bash
git clone https://github.com/gordonkjlee/openmemory
cd openmemory
npm install
npm run build
npm test
```
## 许可证
MIT
