内容
# evermemos-mcp
[](https://pypi.org/project/evermemos-mcp/)
[](https://pypi.org/project/evermemos-mcp/)
[](https://github.com/tt-a1i/everos-mcp/actions/workflows/ci.yml)
[](https://opensource.org/licenses/MIT)
[English](README.md) | [简体中文](README.zh-CN.md)
**人工智能编码助手的长期记忆。记忆一次，永久回忆。**
你花了30分钟解释你的架构、命名约定以及为什么放弃MongoDB。下一个会话 — 全部遗忘。你又一次解释了一遍。
evermemos-mcp解决了这个问题。一个`remember`调用存储它。一个`briefing`调用在任何会话、任何客户端之间恢复它。
> **基准测试：60/60回忆 vs 0/60基线。零归因错误。P95 < 2s。** ([证据](artifacts/competition/2026-02-26-formal-real-auto-all-v3/benchmark_summary.json))
> **介绍视频：** [在Bilibili上观看](https://www.bilibili.com/video/BV1jMwhzKEVo)
> **演示视频：** [在Bilibili上观看](https://www.bilibili.com/video/BV13twWzuETU)
---
## 快速开始
从 [EverMemOS Cloud](https://evermind.ai/) 获取您的API密钥，然后添加到您的MCP客户端配置中：
```json
{
"mcpServers": {
"evermemos-mcp": {
"type": "stdio",
"command": "uvx",
"args": ["evermemos-mcp@latest"],
"env": {
"EVERMEMOS_API_KEY": "your-key-here"
}
}
}
}
```
或直接运行：
```bash
uvx evermemos-mcp@latest
```
与 **Claude Code, Cursor, Cline, Cherry Studio, OpenClaw, Gemini CLI, Aider** 等MCP兼容的客户端或代理一起工作。参见 [`docs/05-client-integrations.md`](docs/05-client-integrations.md) 以获取客户端特定的设置。
<details>
<summary>从源代码安装</summary>
```bash
git clone https://github.com/tt-a1i/everos-mcp.git
cd everos-mcp
cp .env.example .env # 设置 EVERMEMOS_API_KEY
uv run evermemos-mcp
```
源代码安装的MCP客户端配置：
```json
{
"mcpServers": {
"evermemos-mcp": {
"type": "stdio",
"command": "uv",
"args": ["run", "--directory", "/path/to/evermemos-mcp", "evermemos-mcp"],
"env": { "EVERMEMOS_API_KEY": "your-key-here" }
}
}
}
```
</details>
---
## 您将获得
### 7种工具
| 工具 | 功能 |
|------|-------------|
| `list_spaces` | 发现可用的记忆空间 |
| `remember` | 将上下文存储到长期记忆中。自动检测敏感内容（API密钥、密码）并检查冲突记忆 |
| `request_status` | 检查队列写入是否已提取 |
| `recall` | 使用6种检索策略（关键词/混合/向量/RRF/智能体/自动）搜索记忆 |
| `briefing` | 一键会话启动上下文恢复：配置文件 + 片段 + 事实 + 前瞻 |
| `forget` | 有验证工作流的目标删除 |
| `fetch_history` | 按类型分页浏览记忆时间线 |
### 关键能力
- **空间隔离** — `coding:my-app`, `chat:preferences`, `study:ml-notes` — 记忆永远不会跨项目泄露
- **多空间搜索** — 在一个`recall`调用中查询最多10个空间，并具有自动来源归因
- **敏感内容保护** — 在存储前阻止API密钥、密码、令牌、私钥。要求用户确认
- **记忆冲突检测** — 在`chat:*`空间中自动检查。显示冲突，以便代理可以决定
- **生命周期跟踪** — 每个结果在所有工具中标记为`queued`、`provisional`、`fallback`或`searchable`
- **可追溯的引用** — 每个结果的`memory_type`、`snippet`、`timestamp`、`score`、`source_message_id`
- **Git自动检测** — 省略`space_id`，它从git远程推断`coding:<repo-name>`
- **强大的错误处理** — 重试带有回退（429/5xx）；遗留v0 GET-body代理/WAF回退（默认v1搜索/获取使用POST正文）；结构化错误代码
---
## 用例
**持久的架构上下文：**
```
你：记住我们选择PostgreSQL因为我们的数据是高度关系的
[space_id: coding:my-saas]
-- 第二天，新会话 --
你：我们选择了哪个数据库，为什么？
→ “选择PostgreSQL — 高度关系数据模型”
```
**持久的个人偏好：**
```
你：记住我更喜欢暗黑模式、vim键绑定和简洁的回复
[space_id: chat:preferences]
-- 任意未来会话 --
你：回忆我的UI偏好
→ “暗黑模式、vim键绑定、简洁的回复”
```
**跨会话学习笔记：**
```
你：记住偏差-方差权衡 — 高偏差 = 欠拟合，高方差 = 过拟合
[space_id: study:ml-notes]
-- 稍后 --
你：study:ml-notes的简介
→ 配置文件 + 最近的片段 + 关键事实 + 前瞻
```
---
## 为什么选择evermemos-mcp
还有其他的记忆MCP服务器。这里有什么让它与众不同：
| | evermemos-mcp | Mem0 MCP | Letta/MemGPT | 官方MCP记忆 |
|---|---|---|---|---|
| **空间隔离** | `domain:slug`每个项目/主题 | 否 | 否 | 否 |
| **生命周期跟踪** | queued → provisional → fallback → searchable | 否 | 否 | 否 |
| **敏感内容保护** | API密钥、密码、令牌被阻止 | 否 | 否 | 否 |
| **冲突检测** | 聊天空间自动检测 | 否 | 否 | 否 |
| **多空间搜索** | 一个调用最多10个空间 | 否 | 否 | 否 |
| **检索策略** | 6种方法 + 自动合并 | 仅语义 | 仅语义 | 无 |
| **基准测试验证** | 60/60回忆，0错误 | — | — | — |
| **设置** | `uvx evermemos-mcp` | 云或自托管 | 需要自托管 | `npx` |
---
## 基准测试
在固定60查询集上进行测试，涵盖编码、聊天和学习空间。
| 指标 | 有记忆 | 无记忆 |
|--------|-------------|----------------|
| 命中率 | 60/60（100%） | 0/60（0%） |
| 归因错误 | 0 | — |
| P95延迟 | 1958毫秒 | — |
证据：
- [`benchmark_summary.json`](artifacts/competition/2026-02-26-formal-real-auto-all-v3/benchmark_summary.json)
- [`benchmark_report.md`](artifacts/competition/2026-02-26-formal-real-auto-all-v3/benchmark_report.md)
- [`runs.jsonl` （发布）](https://github.com/tt-a1i/everos-mcp/releases/tag/competition-evidence-2026-02-26)
---
## 工作原理
```
MCP客户端（Claude Code / Cursor / Cline / Cherry Studio / OpenClaw / 任意代理）
│
│ MCP stdio
▼
┌─────────────────────────────┐
│ evermemos-mcp服务器 │
│ ┌───────────────────────┐ │
│ │ 7种工具处理器 │ │
│ └──────────┬────────────┘ │
│ ┌──────────▼────────────┐ │
│ │ 记忆服务 │ │ 内容保护 → 冲突检查 → 云写入 → 生命周期跟踪
│ └──────────┬────────────┘ │
│ ┌──────────▼────────────┐ │
│ │ 空间目录服务 │ │ 空间注册、元数据同步、跨会话恢复
│ └──────────┬────────────┘ │
│ ┌──────────▼────────────┐ │
│ │ EverMemOS HTTP客户端│ │ 认证、重试、速率限制回退、错误归一化
│ └──────────┬────────────┘ │
└─────────────┼───────────────┘
│ HTTPS
▼
EverMemOS云API
```
- **云优先** — 所有记忆都存储在EverMemOS云中。没有本地状态会丢失。
- **异步提取** — `remember`队列内容进行AI提取。使用`request_status`跟踪进度。
- **不是薄包装** — 2500+行编排：回退层次结构、多方法搜索合并、身份镜像、部分故障恢复。
---
## 空间模板
| 模板 | 用途 |
|----------|------------|
| `chat:preferences` | 持久的个人偏好、名称、语气、UI喜好 |
| `chat:daily` | 持续的聊天上下文，不应泄露到项目中 |
| `coding:<repo>` | 架构决策、约定、错误、项目上下文 |
| `study:<topic>` | 学习笔记、主题进度、复习上下文 |
## 何时使用哪种工具
| 目标 | 工具 | 为什么 |
|------|------|-----|
| 开始新会话 | `briefing` | 快速恢复上下文，一键调用 |
| 查找特定事实 | `recall` | 跨空间的相关性排名搜索 |
| 回顾发生了什么 | `fetch_history` | 按时间顺序的时间线 > 排名搜索用于审计 |
| 验证删除前后 | `fetch_history` | 删除前后的稳定时间线检查 |
---
## 配置
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `EVERMEMOS_API_KEY` | *(必填)* | EverMemOS云API密钥 |
| `EVERMEMOS_USER_ID` | `mcp-user` | 默认用户身份 |
| `EVERMEMOS_DEFAULT_SPACE` | *(自动)* | 默认空间。从git远程自动检测为`coding:<repo>` |
| `EVERMEMOS_BASE_URL` | `https://api.evermind.ai` | API端点 |
| `EVERMEMOS_DEFAULT_TIMEZONE` | `UTC` | 元数据时区 |
| `EVERMEMOS_ENABLE_CONVERSATION_META` | `true` | 同步对话元数据 |
<details>
<summary>高级配置</summary>
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `EVERMEMOS_API_VERSION` | `v1` | API版本（`v0`旧版） |
| `EVERMEMOS_LLM_CUSTOM_SETTING_JSON` | — | 自定义LLM提取设置 |
| `EVERMEMOS_USER_DETAILS_JSON` | — | 会话的用户资料详情 |
</details>
### `flush` 规则
| 场景 | `flush` |
|----------|---------|
| 会话中，更多消息即将到来 | `false` |
| 会话结束/主题切换/摘要 | `true` |
| 不确定 | `true`（更安全） |
---
<details>
<summary><strong>高级：记忆生命周期状态</strong></summary>
| 状态 | 含义 |
|-------|---------|
| `queued` | 写入接受，提取尚未确认 |
| `provisional` | `pending_messages`中的答案，同时提取正在进行 |
| `fallback` | `pending_messages`和/或元数据回退的答案，同时正式记忆尚未可搜索；在云v1上，仅有限的Groups元数据（名称/描述）被持久镜像 |
| `searchable` | 正式提取记忆的答案 |
所有7种工具都公开兼容的`lifecycle`块，以便代理始终了解记忆成熟度。
</details>
<details>
<summary><strong>高级：忘记安全性</strong></summary>
云删除是异步和尽力而为的。evermemos-mcp提供了一个先验证后删除的工作流：
1. 通过`fetch_history`或`recall`确认目标`memory_id`
2. 调用`forget(memory_ids=[...], space_id=...)`
3. 通过`fetch_history`验证
4. 如果目标仍然存在，生命周期模型透明地显示这一点
这是故意的：向代理公开真实状态，而不是假装删除是瞬间的。
</details>
---
## 开发
```bash
uv sync --group dev # 安装开发依赖
uv run ruff check # 校验
uv run pytest # 测试（285通过）
```
## 文档
| 文档 | 描述 |
|----------|-------------|
| [`docs/02-architecture.md`](docs/02-architecture.md) | 技术架构 |
| [`docs/05-client-integrations.md`](docs/05-client-integrations.md) | 客户端设置指南 |
| [`docs/auto-memory-prompt.md`](docs/auto-memory-prompt.md) | 自动记忆提示模板 |
| [`docs/06-benchmark.md`](docs/06-benchmark.md) | 基准测试协议 |
| [`CHANGELOG.md`](CHANGELOG.md) | 版本历史 |
## 另请查看
**[MCO](https://github.com/mco-org/mco)** — 代理编排CLI。让你的主代理（Claude Code, Cursor, Aider）将任务分派给多个编码代理并行执行。与evermemos-mcp搭配使用：MCO处理并行执行，evermemos-mcp处理持久记忆。
## 许可证
[MIT](https://opensource.org/licenses/MIT)
