# https://github.com/pquattro/memoraeu-mcp 项目说明书
生成时间：2026-05-14 10:05:53 UTC
## 目录
- [项目概述](#page-overview)
- [快速开始](#page-quickstart)
- [系统架构](#page-architecture)
- [加密系统](#page-encryption)
- [MCP 工具详解](#page-mcp-tools)
- [自动记忆机制](#page-auto-memory)
- [去重与压缩](#page-dedup-compression)
- [配置与密钥管理](#page-configuration)
- [自托管部署](#page-selfhosting)
## 项目概述
### 相关页面
相关主题：[快速开始](#page-quickstart), [系统架构](#page-architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)
- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)
- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)
- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)
# 项目概述
## 项目简介
**memoraeu-mcp** 是一个基于 Model Context Protocol (MCP) 的零知识记忆服务器，用于为 AI 助手（如 Claude）提供持久化、加密的记忆能力。该项目使 AI 能够在多个会话之间记住用户偏好、决策、重要事实和技术配置，同时确保数据在传输和存储过程中的隐私安全。资料来源：[README.md]()
## 核心设计理念
memoraeu-mcp 遵循**零知识（Zero-Knowledge）架构**，核心原则包括：
- **客户端加密**：所有敏感数据在离开用户设备前完成加密，服务器仅存储密文
- **本地嵌入生成**：使用 Mistral API 在本地生成文本向量嵌入，确保明文不出设备
- **自动记忆行为**：AI 助手根据工具描述自动执行记忆操作，无需用户手动干预
## 技术架构
### 系统组件
```mermaid
graph TD
subgraph 客户端本地
A[Claude Desktop] --> B[memoraeu-mcp MCP Server]
B --> C[加密模块]
C --> D[压缩模块]
D --> E[嵌入生成 Mistral API]
end
subgraph 远程服务
E --> F[MemoraEU API]
F --> G[(加密存储)]
end
style A fill:#e1f5fe
style F fill:#fff3e0
style G fill:#ffebee
```
### 依赖技术栈
| 组件 | 技术选型 | 版本要求 | 用途 |
|------|----------|----------|------|
| MCP SDK | `mcp` | ≥1.1.0, <1.2.0 | MCP 协议实现 |
| HTTP 客户端 | `httpx` | 0.28.1 | API 通信 |
| Web 框架 | `starlette` | ≥0.40.0, <0.42.0 | SSE 支持 |
| 加密库 | `cryptography` | ≥42.0.0 | AES-256-GCM 加密 |
| 配置管理 | `python-dotenv` | 1.0.1 | 环境变量加载 |
资料来源：[requirements.txt]()
## 部署模式
memoraeu-mcp 支持两种部署模式，适用于不同的安全需求场景：
### 本地 Stdio 模式
该模式提供完整的零知识保证，适合处理高度敏感信息。
```json
{
"mcpServers": {
"memoraeu": {
"command": "uvx",
"args": ["memoraeu-mcp"],
"env": {
"MEMORAEU_API_URL": "https://api.memoraeu.com",
"MEMORAEU_API_KEY": "meu-sk-...",
"MEMORAEU_SECRET": "your-memoraeu-password",
"MEMORAEU_SALT": "your-kdf-salt",
"MISTRAL_API_KEY": "your-mistral-key"
}
}
}
}
```
资料来源：[README.md]()
### 远程 SSE 模式
该模式通过 Server-Sent Events 连接到远程服务，适合无本地安装条件的场景。
```json
{
"mcpServers": {
"memoraeu": {
"type": "sse",
"url": "https://api.memoraeu.com/mcp/sse",
"headers": {
"Authorization": "Bearer meu-sk-..."
}
}
}
}
```
> **安全提示**：远程 SSE 模式下，内容不以零知识方式处理，服务器会看到明文。资料来源：[README.md]()
## 核心工具与功能
### 记忆工具集
| 工具名称 | 功能描述 | 自动执行 |
|----------|----------|----------|
| `remember` | 自动记忆重要信息 | ✅ 会话中检测到关键信息时 |
| `recall` | 语义搜索记忆库 | ✅ 首条用户消息时 |
| `forget` | 按 ID 删除记忆 | ❌ 需手动调用 |
| `list_memories` | 列出最近记忆 | ❌ 需手动调用 |
| `list_categories` | 返回分类统计 | ❌ 需手动调用 |
| `remember_fact` | 存储结构化事实 | ❌ 需手动调用 |
| `recall_facts` | 检索主题相关事实 | ❌ 需手动调用 |
| `invalidate_fact` | 标记事实过期 | ❌ 需手动调用 |
资料来源：[README.md](), [memoraeu_mcp/main.py]()
### 自动记忆行为
memoraeu-mcp 设计为无需手动干预即可工作，行为逻辑如下：
```mermaid
sequenceDiagram
participant U as 用户
participant M as MemoraEU MCP
participant API as MemoraEU API
Note over U,M: 会话开始
U->>M: 首条消息
M->>M: recall 自动执行
M->>API: 搜索相关记忆
API-->>M: 返回结果
M-->>U: 注入上下文
Note over U,M: 交互过程中
U->>M: 表达偏好/决策
M->>M: 检测到持久信息
M->>M: remember 自动执行
M->>API: 存储加密记忆
M-->>U: 确认（单行）
```
**自动执行规则**：
- `recall` 在每个会话首条消息时自动调用，查询与主题相关的记忆
- `remember` 在检测到偏好、决策、传记事实或技术配置时自动执行
- 首次 recall 时自动注入完整系统提示，强化自动记忆规则
资料来源：[README.md]()
## 数据安全机制
### 加密流程
```mermaid
graph LR
A[明文内容] --> B[Mistral API
生成嵌入]
B --> C[AES-256-GCM
加密内容]
C --> D[加密内容 + 嵌入
发送到服务器]
style A fill:#ffebee
style D fill:#e8f5e9
```
### 密钥派生与加密
| 参数 | 来源 | 用途 |
|------|------|------|
| `MEMORAEU_SECRET` | 用户登录密码 | PBKDF2 输入 |
| `MEMORAEU_SALT` | 服务器生成 | KDF 盐值 |
| PBKDF2 迭代次数 | 210,000 | OWASP 2024 推荐值 |
加密后的密文使用 `ENCv1:` 前缀标识，格式如下：
```
ENCv1:
```
资料来源：[CHANGELOG.md](), [memoraeu_mcp/main.py]()
### 去重与压缩
在存储前，系统会执行以下预处理：
1. **本地压缩**：使用 Mistral API 对明文进行压缩
2. **本地分类**：自动建议或验证分类
3. **向量相似度检测**：与现有记忆比较相似度
| 相似度阈值 | 处理动作 |
|------------|----------|
| ≥ 94% | 跳过存储，提示重复 |
| < 94% | 正常存储，输出警告 |
资料来源：[README.md](), [memoraeu_mcp/main.py]()
## API 交互
### 内部 API 端点
| 端点 | 方法 | 用途 |
|------|------|------|
| `/memories` | GET/POST | 列表/创建记忆 |
| `/memories/search` | POST | 语义搜索 |
| `/memories/{id}` | DELETE | 删除记忆 |
| `/memories/categories` | GET | 获取分类统计 |
| `/facts` | GET/POST | 结构化事实管理 |
### 资源注入
系统通过 MCP 资源机制提供上下文注入：
- **资源 URI**：`memoraeu://context`
- **资源名称**：Contexte mémoire MemoraEU
- **用途**：会话开始时自动加载最近记忆到上下文
资料来源：[memoraeu_mcp/main.py]()
## 版本历史
| 版本 | 日期 | 主要变更 |
|------|------|----------|
| 0.1.9 | 2026-05-12 | 新增结构化事实工具、PBKDF2 迭代增至 210k |
| 0.1.5 | 2026-04-28 | PBKDF2 增强、密文前缀 ENCv1: |
资料来源：[CHANGELOG.md]()
## 应用场景
### 适用场景
- **个人 AI 助手**：Claude Desktop 与用户跨会话共享上下文
- **开发团队知识库**：记住技术栈偏好、项目配置、代码规范
- **客户服务会话**：AI 记住用户历史偏好和需求
### 限制与注意事项
- 远程 SSE 模式不具备零知识保证
- 需要有效的 Mistral API Key 才能启用语义搜索
- 语义搜索降级为关键词搜索时会话上下文仍加密
## 许可证
本项目采用 **AGPL v3** 开源许可证。资料来源：[CHANGELOG.md]()
---
## 快速开始
### 相关页面
相关主题：[项目概述](#page-overview), [配置与密钥管理](#page-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)
- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)
- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)
- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)
# 快速开始
本页面提供 MemoraEU MCP 服务器的完整快速入门指南，帮助用户在最短时间内完成安装、配置并开始使用零知识记忆系统。
## 概述
**MemoraEU MCP** 是一个基于 Model Context Protocol (MCP) 的零知识记忆服务器。它允许 AI 助手（如 Claude）在会话中自动存储和检索用户的重要信息，同时确保数据在传输和存储过程中始终保持加密状态。
核心特性包括：
- **零知识加密**：使用 AES-256-GCM 和 PBKDF2-HMAC-SHA256（210,000 次迭代）确保服务端无法访问明文内容
- **本地 Embedding**：使用 Mistral Embed 在本地计算向量嵌入后再加密上传
- **自动记忆行为**：AI 自动调用 `remember` 和 `recall`，无需用户手动触发
- **去重压缩**：存储前通过向量相似度检测近重复内容，避免冗余存储
资料来源：[README.md:1-20]()
## 系统架构
```mermaid
graph TD
subgraph "客户端 (本地)"
A[Claude / AI Assistant] --> B[MCP Client]
B --> C[MemoraEU MCP Server]
C --> D[加密模块]
D --> E[Mistral Embed]
C --> F[压缩模块]
C --> G[分类模块]
end
subgraph "服务端 (远程)"
H[MemoraEU API] --> I[(加密存储)]
I --> J[向量索引]
end
C -->|加密内容 + Embedding| H
E -->|向量| C
F -->|压缩后明文| D
G -->|分类结果| D
style H fill:#ff6b6b,color:#fff
style D fill:#4ecdc4,color:#fff
style I fill:#ffe66d
```
## 前置条件
在开始之前，请确保满足以下要求：
| 要求 | 说明 |
|------|------|
| Python 版本 | Python 3.10+ |
| 网络连接 | 需要访问 `api.memoraeu.com` 和 `console.mistral.ai`（可选） |
| MemoraEU 账户 | 需在 [app.memoraeu.com](https://app.memoraeu.com) 注册 |
| Mistral API Key | 用于本地 Embedding 生成（可选，但推荐） |
## 安装方式
### 方式一：远程 SSE 模式（即装即用）
适用于不想安装本地服务的用户，通过 SSE 协议直接连接远程服务器。
1. 在客户端配置中添加以下 JSON：
```json
{
"mcpServers": {
"memoraeu": {
"type": "sse",
"url": "https://api.memoraeu.com/mcp/sse",
"headers": {
"Authorization": "Bearer meu-sk-YOUR-API-KEY"
}
}
}
}
```
2. 支持的客户端：Claude.ai Web、Cursor、Windsurf 等支持 MCP 的应用
资料来源：[README.md:45-55]()
### 方式二：本地 stdio 模式（完整零知识保证）
适用于需要最高安全级别的用户，所有处理均在本地完成。
#### 步骤 1：获取 API 密钥
1. 访问 [app.memoraeu.com](https://app.memoraeu.com) 创建账户
2. 进入 **设置 → API 密钥** → 创建新密钥 → 复制 `MEMORAEU_API_KEY`
3. 进入 **设置 → 加密密钥** → 复制 `MEMORAEU_SALT`
4. 在 [console.mistral.ai](https://console.mistral.ai) 获取 `MISTRAL_API_KEY`
资料来源：[README.md:35-43]()
#### 步骤 2：配置环境变量
```bash
export MEMORAEU_API_URL="https://api.memoraeu.com"
export MEMORAEU_API_KEY="meu-sk-YOUR-API-KEY"
export MEMORAEU_SECRET="your-memoraeu-password"
export MEMORAEU_SALT="your-kdf-salt"
export MISTRAL_API_KEY="your-mistral-key"
```
#### 步骤 3：配置 MCP 客户端
```json
{
"mcpServers": {
"memoraeu": {
"command": "uvx",
"args": ["memoraeu-mcp"],
"env": {
"MEMORAEU_API_URL": "https://api.memoraeu.com",
"MEMORAEU_API_KEY": "meu-sk-YOUR-API-KEY",
"MEMORAEU_SECRET": "your-memoraeu-password",
"MEMORAEU_SALT": "your-kdf-salt",
"MISTRAL_API_KEY": "your-mistral-key"
}
}
}
}
```
资料来源：[README.md:20-34]()
## 环境变量详解
| 变量 | 用途 | 获取位置 | 必需 |
|------|------|----------|------|
| `MEMORAEU_API_KEY` | HTTP 认证的 Bearer Token | 设置 → API 密钥 | 是 |
| `MEMORAEU_SECRET` | 账户登录密码，用于 PBKDF2 派生加密密钥 | 您的账户密码 | 是 |
| `MEMORAEU_SALT` | 服务器为账户生成的唯一 KDF 盐值 | 设置 → 加密密钥 | 是 |
| `MEMORAEU_API_URL` | API 端点地址 | — | 是 |
| `MISTRAL_API_KEY` | 本地计算 Embedding（加密前） | console.mistral.ai | 推荐 |
> **注意**：`MEMORAEU_SECRET` 和 `MEMORAEU_SALT` 的组合用于本地生成加密密钥。服务器仅存储密文，无法解密内容。
资料来源：[README.md:35-43]()
## 可用工具
| 工具 | 功能 |
|------|------|
| `remember` | 自动记忆用户表达的重要信息（偏好、决策、传记事实、技术配置等） |
| `recall` | 在会话开始时自动调用，基于语义搜索检索相关记忆 |
| `forget` | 根据 ID 删除指定记忆 |
| `list_memories` | 列出最近的记忆，支持按分类筛选 |
| `list_categories` | 返回按使用频率排序的分类列表 |
| `remember_fact` | 存储结构化事实（主体/谓词/对象），支持时间有效性 |
| `recall_facts` | 检索指定主体的当前有效事实 |
| `invalidate_fact` | 将指定事实标记为过期 |
资料来源：[README.md:56-68]()
### remember_fact 工具参数
```json
{
"subject": "string", // 实体名称
"predicate": "string", // 属性名称
"object": "string", // 属性值
"scope": "private|org", // 作用域，默认 private
"valid_from": "YYYY-MM-DD" // 生效日期
}
```
资料来源：[server.py:1-50]()
### recall 工具参数
```json
{
"query": "string", // 语义搜索查询
"limit": 3, // 结果数量限制，默认 3
"category": "string" // 可选，按分类筛选
}
```
资料来源：[memoraeu_mcp/main.py:1-30]()
## 自动行为
```mermaid
sequenceDiagram
participant U as 用户
participant M as MemoraEU MCP
participant A as MemoraEU API
rect rgb(240, 248, 255)
Note over M: 会话开始
U->>M: 第一条消息
M->>M: 自动 recall(话题)
M->>A: 检索记忆
A-->>M: 返回结果
M->>U: 展示上下文
end
rect rgb(255, 250, 240)
Note over M,U: 交互过程中
U->>M: 表达重要信息
M->>M: 检测到持久性信息
M->>M: 自动 remember()
M->>M: 本地压缩 + 分类
M->>M: 本地 Mistral Embed
M->>M: AES-256-GCM 加密
M->>A: 上传密文 + 向量
M->>U: 确认保存（单行）
end
```
### 自动记忆触发条件
以下类型的信息会被自动记忆：
- 用户偏好和习惯
- 重要决策和结论
- 个人事实（工作、位置、联系方式等）
- 技术配置和约束（非敏感信息）
- 重复出现的模式或约束
以下信息**不会**被记忆：
- 临时信息（当日天气、玩笑、临时计算）
- 用户明确要求忽略的内容
资料来源：[memoraeu_mcp/main.py:1-50]()
## 去重与压缩
在存储记忆前，系统会执行以下处理流程：
```mermaid
graph TD
A[新记忆内容] --> B[本地压缩]
B --> C[本地分类]
C --> D[Mistral Embed]
D --> E[向量相似度检测]
E --> F{相似度 >= 94%}
F -->|是| G[跳过存储]
F -->|否| H{94% > 相似度 >= 85%}
H -->|是| I[警告并询问]
H -->|否| J[AES-256-GCM 加密]
J --> K[上传密文 + 向量]
```
| 相似度 | 处理动作 |
|--------|----------|
| ≥ 94% | 完全跳过，视为精确重复 |
| 85% - 93% | 返回警告，询问用户是否仍要存储 |
| < 85% | 正常存储 |
资料来源：[README.md:70-80]()
## 安全模型
### 零知识保证
```
┌─────────────────────────────────────────────────────────────┐
│ 数据流加密 │
├─────────────────────────────────────────────────────────────┤
│ │
│ 明文内容 │
│ ↓ │
│ Mistral Embed (本地计算向量) │
│ ↓ │
│ AES-256-GCM 加密 (PBKDF2-HMAC-SHA256 派生密钥) │
│ ↓ │
│ [ENCv1:盐值:IV:密文:Tag] 格式 │
│ ↓ │
│ 发送给 MemoraEU API │
│ │
│ 服务器存储：密文 + 向量（两者均无法单独解密原始内容） │
│ │
└─────────────────────────────────────────────────────────────┘
```
### 两种模式的区别
| 特性 | stdio 本地模式 | SSE 远程模式 |
|------|----------------|--------------|
| 零知识保证 | 完整 | 部分（SSE 传输非端到端加密） |
| 配置复杂度 | 较高 | 低 |
| 密钥管理 | 本地 | 部分在远程 |
| 适用场景 | 高安全需求 | 快速试用 |
> **警告**：远程 SSE 模式下，传输内容未经端到端加密。建议仅在 stdio 本地模式下使用完整零知识保证。
资料来源：[README.md:10-15]()
## 依赖项
| 依赖 | 版本 | 用途 |
|------|------|------|
| `mcp` | ≥1.1.0, <1.2.0 | Model Context Protocol 框架 |
| `httpx` | 0.28.1 | HTTP 客户端 |
| `python-dotenv` | 1.0.1 | 环境变量加载 |
| `starlette` | ≥0.40.0, <0.42.0 | Web 框架（用于 SSE） |
| `cryptography` | ≥42.0.0 | 加密实现 |
资料来源：[requirements.txt:1-6]()
## 版本历史
| 版本 | 日期 | 主要变更 |
|------|------|----------|
| 0.1.9 | 2026-05-12 | 新增 `remember_fact` 系列工具；PBKDF2 升级至 210,000 次迭代 |
| 0.1.5 | 2026-04-28 | PBKDF2 迭代次数调整；添加 `ENCv1:` 密文前缀 |
资料来源：[CHANGELOG.md:1-50]()
## 故障排除
### 常见问题
**Q: `MISTRAL_API_KEY` 缺失会怎样？**
A: MCP 服务器仍可正常运行，但语义搜索会降级为服务器端关键词搜索。零知识加密不受影响。
**Q: 如何删除已存储的记忆？**
A: 使用 `forget` 工具并提供记忆 ID，或通过 `list_memories` 查看所有记忆后选择删除。
**Q: 为什么提示"无法连接"？**
A: 检查 `MEMORAEU_API_URL` 是否设置为 `https://api.memoraeu.com`，以及网络连接是否正常。
## 下一步
- 阅读 [完整 README](README.md) 了解更多高级配置
- 查看 [CHANGELOG](CHANGELOG.md) 了解版本更新
- 配置您的 AI 客户端以开始使用自动记忆功能
---
## 系统架构
### 相关页面
相关主题：[项目概述](#page-overview), [加密系统](#page-encryption)
相关源码文件
以下源码文件用于生成本页说明：
- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
- [memoraeu_mcp/server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/server.py)
- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)
- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)
- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)
# 系统架构
## 概述
MemoraEU MCP 是一个基于 Model Context Protocol (MCP) 的零知识记忆服务架构。该系统作为 MCP 服务器运行，为 AI 助手（如 Claude）提供持久化记忆功能，同时保证用户数据的隐私性和零知识加密特性。 资料来源：[README.md:1]()
系统采用客户端-服务端架构，支持本地安装（stdio 模式）和远程连接（SSE 模式）两种部署方式。核心设计理念是：**在数据离开用户设备之前完成所有可能的处理和加密操作**，确保服务端永远无法访问明文内容。 资料来源：[README.md:40]()
---
## 整体架构图
```mermaid
graph TB
subgraph 客户端本地["客户端本地环境"]
A[Claude / AI 助手] -->|MCP 协议| B[MCP Server]
B -->|stdio / SSE| A
subgraph 本地处理模块["本地处理模块"]
C[内容压缩]
D[分类建议]
E[Embedding 生成]
F[加密处理]
G[解压缩/解密]
end
B --> C
B --> D
B --> E
B --> F
B --> G
end
subgraph 外部服务["外部服务"]
H[(Mistral API
Embedding 生成)]
I[(MemoraEU Cloud
加密存储)]
end
F -->|加密内容 + Embedding| I
E -->|明文| H
H -->|Embedding 向量| B
I -->|加密数据| B
B -->|解密密文| G
style 客户端本地 fill:#e1f5fe
style 本地处理模块 fill:#fff3e0
style 外部服务 fill:#f3e5f5
```
---
## 核心组件
### MCP 服务器层
MCP 服务器层是整个架构的核心入口，基于 `mcp>=1.1.0,<1.2.0` SDK 实现。该层负责注册和管理所有工具、资源以及提示模板，并通过 `@app` 装饰器与 MCP 协议进行交互。 资料来源：[requirements.txt:1]()
| 组件 | 功能 | 对应装饰器 |
|------|------|-----------|
| 工具注册 | 注册和管理所有 MCP 工具 | `@app.list_tools()` |
| 资源管理 | 提供 `memoraeu://context` 资源 | `@app.list_resources()` |
| 提示模板 | 提供系统行为提示 | `@app.list_prompts()` |
| 工具调用 | 分发和处理工具调用请求 | `@app.call_tool()` |
服务器入口点支持两种启动方式：
```python
# 方式1: 通过 server.py 模块入口
# 资料来源: memoraeu_mcp/server.py:1-8
from memoraeu_mcp.main import main
asyncio.run(main())
# 方式2: 通过 uvx / pip 直接运行
# uvx memoraeu-mcp
```
---
### 工具体系
系统定义了 9 个核心工具，分为通用记忆工具和结构化事实工具两类。 资料来源：[memoraeu_mcp/main.py:45-130]()
#### 通用记忆工具
| 工具名称 | 功能描述 | 核心参数 |
|----------|----------|----------|
| `remember` | 自动记忆重要信息 | `content`, `category?`, `tags?` |
| `recall` | 语义搜索记忆 | `query`, `limit?`, `category?` |
| `forget` | 删除指定记忆 | `memory_id` |
| `list_memories` | 列出最近记忆 | `category?`, `limit?` |
| `list_categories` | 获取分类列表 | 无 |
#### 结构化事实工具
| 工具名称 | 功能描述 | 核心参数 |
|----------|----------|----------|
| `remember_fact` | 存储结构化事实 | `subject`, `predicate`, `object`, `scope?`, `valid_from?` |
| `recall_facts` | 检索活跃事实 | `subject`, `predicate?`, `scope?`, `history?` |
| `invalidate_fact` | 标记事实过期 | `fact_id`, `valid_to?` |
---
## 数据处理流程
### remember 工具执行流程
```mermaid
graph TD
A[remember 调用] --> B{是否提供 category?}
B -->|否| C[获取现有分类]
B -->|是| D[使用提供的分类]
C --> E[本地压缩内容]
D --> E
E --> F[本地生成 Embedding
via Mistral]
F --> G{检查重复?}
G -->|是| H[相似度 >= 94%?]
H -->|是| I[跳过存储]
H -->|否| J[允许存储]
G -->|否| J
I --> K[返回提示]
J --> L[加密内容]
L --> M[发送到 MemoraEU API]
M --> N[存储成功]
style I fill:#ffcdd2
style J fill:#c8e6c9
```
详细处理步骤： 资料来源：[memoraeu_mcp/main.py:140-175]()
1. **内容压缩**：在加密前对明文进行本地压缩，减少存储和传输大小
2. **分类建议**：如未指定分类，通过 Mistral API 建议合适分类
3. **Embedding 生成**：在明文状态下调用 Mistral Embed API 生成向量 资料来源：[README.md:35]()
4. **重复检测**：使用向量相似度检查（阈值 94%）避免存储重复记忆
5. **加密处理**：使用 AES-256-GCM + PBKDF2-HMAC-SHA256 (100k 迭代) 加密内容
6. **API 上传**：将加密内容和 Embedding 向量发送至 MemoraEU 云端
### recall 工具执行流程
```mermaid
graph TD
A[recall 调用] --> B[构建查询参数]
B --> C{本地有 Embedding?}
C -->|有 Mistral Key| D[本地生成 query Embedding]
C -->|无 Mistral Key| E[使用关键词搜索]
D --> F[发送到 MemoraEU API]
E --> F
F --> G[返回加密结果]
G --> H[本地解密内容]
H --> I[返回给 Claude]
style D fill:#c8e6c9
style E fill:#fff3e0
```
---
## 安全架构
### 零知识加密设计
系统采用多层加密策略，确保服务端永远无法访问用户明文数据。 资料来源：[CHANGELOG.md:2]()
```mermaid
graph LR
subgraph 密钥派生["密钥派生流程"]
A[MEMORAEU_SECRET
用户密码] --> B[PBKDF2-HMAC-SHA256]
C[MEMORAEU_SALT
服务器盐值] --> B
B --> D[100,000 次迭代]
D --> E[加密密钥]
end
subgraph 加密过程["加密过程"]
F[明文内容] --> G[AES-256-GCM]
E --> G
G --> H[密文 + IV]
end
style 密钥派生 fill:#e3f2fd
style 加密过程 fill:#e8f5e9
```
### 环境变量与安全配置
| 变量名 | 用途 | 安全性要求 |
|--------|------|------------|
| `MEMORAEU_API_KEY` | HTTP Bearer 认证 | 可共享 |
| `MEMORAEU_SECRET` | PBKDF2 输入，用于派生加密密钥 | **高度敏感** |
| `MEMORAEU_SALT` | KDF 盐值，唯一对应用户账户 | 可共享 |
| `MEMORAEU_API_URL` | API 端点 | 配置项 |
| `MISTRAL_API_KEY` | 本地生成 Embedding | 可共享 |
> **重要**：`MEMORAEU_SECRET` 是用户的 MemoraEU 登录密码，绝对不能泄露或共享。 资料来源：[README.md:25]()
### Mistral Embedding 的零知识保证
系统设计确保 Embedding 生成在本地完成： 资料来源：[README.md:35-40]()
1. 用户提供 `MISTRAL_API_KEY`
2. MCP 服务器在本地使用明文内容调用 Mistral Embed API
3. 获取 Embedding 向量后，立即对内容进行加密
4. 加密后的内容（密文）和 Embedding 向量一起发送到服务端
5. 服务端存储密文和向量，但**无法反向解密或理解内容含义**
---
## 部署架构
### 本地模式 (stdio)
适用于需要完整零知识保证的场景。配置于 `claude_desktop_config.json`： 资料来源：[README.md:15-30]()
```json
{
"mcpServers": {
"memoraeu": {
"command": "uvx",
"args": ["memoraeu-mcp"],
"env": {
"MEMORAEU_API_URL": "https://api.memoraeu.com",
"MEMORAEU_API_KEY": "meu-sk-...",
"MEMORAEU_SECRET": "your-memoraeu-password",
"MEMORAEU_SALT": "your-kdf-salt",
"MISTRAL_API_KEY": "your-mistral-key"
}
}
}
}
```
### 远程模式 (SSE)
适用于快速连接场景，但**不具备零知识保证**： 资料来源：[README.md:40-50]()
```json
{
"mcpServers": {
"memoraeu": {
"type": "sse",
"url": "https://api.memoraeu.com/mcp/sse",
"headers": {
"Authorization": "Bearer meu-sk-..."
}
}
}
}
```
> **警告**：SSE 远程模式下，内容不以零知识方式处理，服务端会看到明文。 资料来源：[README.md:40]()
### 部署模式对比
| 特性 | stdio 本地模式 | SSE 远程模式 |
|------|----------------|--------------|
| 零知识加密 | ✅ 完整支持 | ❌ 不支持 |
| Embedding 本地生成 | ✅ 是 | ❌ 否 |
| 内容加密 | ✅ AES-256-GCM | ❌ 明文传输 |
| 配置复杂度 | 较高（需多环境变量） | 低（仅需 URL + Key） |
| 适用场景 | 高隐私需求 | 快速试用 |
---
## 自动行为机制
### 自动记忆工作流
```mermaid
graph TD
A[用户首次发送消息] --> B[检测消息主题]
B --> C[自动调用 recall 工具]
C --> D[加载最近记忆
memoraeu://context]
D --> E[注入系统提示]
E --> F[用户继续对话]
G[Claude 检测到重要信息] --> H[自动调用 remember 工具]
H --> I[本地处理并加密]
I --> J[存储到 MemoraEU]
J --> K[发送单行确认]
style C fill:#bbdefb
style H fill:#c8e6c9
```
### 重复检测机制
系统在存储前进行向量相似度检查： 资料来源：[memoraeu_mcp/main.py:165-175]()
| 相似度阈值 | 处理动作 |
|------------|----------|
| ≥ 94% | 跳过存储，提示用户存在相似记忆 |
| 70% - 94% | 建议用户是否仍要存储 |
| < 70% | 正常存储 |
---
## 资源与提示注入
### memoraeu://context 资源
该资源用于在会话开始时自动加载最近记忆： 资料来源：[memoraeu_mcp/main.py:30-40]()
```python
@app.list_resources()
async def list_resources() -> list[Resource]:
return [
Resource(
uri="memoraeu://context",
name="Contexte mémoire MemoraEU",
description="Mémoires récentes injectées automatiquement en début de session",
mimeType="text/plain"
)
]
```
### 系统提示模板
`memoraeu_system` 提示模板定义了自动记忆行为规则： 资料来源：[memoraeu_mcp/main.py:95-115]()
- 检测并记忆用户偏好、决策、传记事实、技术配置
- 自动调用 `recall` 获取上下文
- 仅确认存储，不额外说明
- 限制 token 消耗（默认 3 条结果）
---
## 技术依赖
| 依赖包 | 版本范围 | 用途 |
|--------|----------|------|
| `mcp` | ≥1.1.0, <1.2.0 | MCP 协议实现 |
| `httpx` | 0.28.1 | HTTP 客户端，与 MemoraEU API 通信 |
| `python-dotenv` | 1.0.1 | 环境变量加载 |
| `starlette` | ≥0.40.0, <0.42.0 | ASGI 框架（用于 SSE） |
| `cryptography` | ≥42.0.0 | AES-256-GCM 加密实现 |
资料来源：[requirements.txt:1-5]()
---
## 总结
MemoraEU MCP 的系统架构围绕**零知识保证**和**自动化记忆**两大核心目标设计：
1. **客户端优先处理**：所有敏感操作（压缩、分类、Embedding、加密）均在本地完成
2. **分层工具设计**：通用记忆和结构化事实工具满足不同场景需求
3. **灵活的部署模式**：stdio 本地模式提供最高安全级别，SSE 远程模式便于快速接入
4. **智能化自动化**：系统提示和工具描述驱动 AI 自动执行记忆操作
该架构确保用户数据在整个生命周期中都处于加密状态，同时为 AI 助手提供无缝的记忆增强能力。
---
## 加密系统
### 相关页面
相关主题：[系统架构](#page-architecture), [配置与密钥管理](#page-configuration)
相关源码文件
以下源码文件用于生成本页说明：
- [memoraeu_mcp/crypto.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/crypto.py)
- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)
- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)
- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)
# 加密系统
## 概述
MemoraEU-MCP 的加密系统是一个**本地优先的零知识加密实现**，确保用户数据在传输和存储的整个过程中始终处于加密状态。服务器仅存储加密后的数据密文和向量嵌入，无法还原原始明文内容。
核心加密流程遵循以下原则：
- **端到端加密**：内容在本地设备加密后发送，服务器永远不接触明文
- **前向安全**：使用 PBKDF2 从用户密码派生出加密密钥
- **语义可搜索**：在加密前通过 Mistral Embed 生成向量嵌入，实现零知识语义搜索
资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)
## 架构设计
### 高层数据流
```mermaid
graph TD
subgraph 本地客户端
A[用户输入] --> B[内容压缩]
B --> C[Mistral Embed
生成向量]
C --> D[AES-256-GCM
加密]
D --> E[密文 + Embedding]
end
subgraph 传输层
E --> F[HTTPS/TLS]
end
subgraph 服务器端
F --> G[(Opaque Blob
存储)]
G --> H[语义搜索
向量匹配]
end
subgraph 检索解密
G --> I[密文获取]
I --> J[AES-256-GCM
解密]
J --> K[明文输出]
end
```
### 密钥派生流程
```mermaid
graph LR
A[MEMORAEU_SECRET
用户密码] --> D[PBKDF2-HMAC-SHA256]
B[MEMORAEU_SALT
服务端盐值] --> D
C[210,000
迭代次数] --> D
D --> E[加密密钥
Derived Key]
E --> F[AES-256-GCM
加解密]
```
## 加密算法详情
### 算法参数
| 参数 | 值 | 说明 |
|------|-----|------|
| 对称加密算法 | AES-256-GCM | 认证加密，抵抗篡改攻击 |
| 密钥派生函数 | PBKDF2-HMAC-SHA256 | OWASP 2024 推荐配置 |
| 迭代次数 | 210,000 | OWASP 2024 最低建议值 |
| 密文前缀 | `ENCv1:` | 版本标识，便于未来算法升级 |
| 盐值来源 | 服务端分配 | 每个用户唯一，`MEMORAEU_SALT` |
资料来源：[CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)
### 密文格式
加密后的数据包含以下结构：
```
ENCv1:
```
- `nonce`：随机生成的初始化向量（12字节）
- `ciphertext`：AES-256-GCM 加密后的密文
- `tag`：GCM 认证标签（16字节）
资料来源：[memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
## 核心模块
### crypto.py 模块
该模块负责所有加密/解密操作的实现：
| 函数 | 职责 |
|------|------|
| `get_key()` | 获取当前派生的加密密钥 |
| `derive_key(secret, salt)` | 使用 PBKDF2 从密码和盐值派生密钥 |
| `encrypt_content(plaintext)` | 对传入的明文进行 AES-256-GCM 加密 |
| `decrypt_content(ciphertext)` | 对密文进行解密并返回明文 |
| `is_encrypted(text)` | 检查文本是否已加密（检测 `ENCv1:` 前缀） |
资料来源：[memoraeu_mcp/crypto.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/crypto.py)
### 环境变量配置
| 变量名 | 用途 | 必需性 |
|--------|------|--------|
| `MEMORAEU_SECRET` | 用户登录密码，用于 PBKDF2 密钥派生 | **必需** |
| `MEMORAEU_SALT` | 服务端分配的 KDF 盐值 | **必需** |
| `MEMORAEU_API_KEY` | HTTP 认证 Bearer Token | 必需 |
| `MEMORAEU_API_URL` | API 端点地址 | 必需 |
| `MISTRAL_API_KEY` | 本地生成 Embedding | 可选（影响搜索能力） |
资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)
## 工作流程
### 存储记忆流程
```mermaid
sequenceDiagram
participant U as 用户
participant MCP as MCP Client
participant M as Mistral API
participant C as Crypto Module
participant S as MemoraEU Server
U->>MCP: remember(content)
MCP->>M: 生成 Embedding
M-->>MCP: embedding_vector
MCP->>C: encrypt_content(content)
C-->>MCP: ENCv1:xxxx
MCP->>S: POST /memories
{content: ENCv1:..., embedding: [...]}
S-->>MCP: memory_id
MCP-->>U: ✅ 已记住
```
### 检索记忆流程
```mermaid
sequenceDiagram
participant U as 用户
participant MCP as MCP Client
participant C as Crypto Module
participant S as MemoraEU Server
U->>MCP: recall(query)
MCP->>S: POST /memories/search
{query: xxx}
S-->>MCP: [{content: ENCv1:..., score: 0.95}]
MCP->>C: decrypt_content(ENCv1:...)
C-->>MCP: 明文内容
MCP-->>U: 记忆列表
```
## 零知识保证
### 服务器可见内容
| 数据项 | 服务器可见性 | 说明 |
|--------|-------------|------|
| 用户输入明文 | ❌ 不可见 | 始终在本地处理 |
| 加密后的内容 | ✅ 可见 | 仅存储密文 |
| 向量嵌入 | ✅ 可见 | 加密前在本地生成 |
| 类别/标签 | ⚠️ 部分可见 | 由 MCP 客户端添加后加密 |
| 加密密钥 | ❌ 不可见 | 密钥从不传输 |
### 语义搜索原理
1. **本地 Embedding 生成**：使用 `MISTRAL_API_KEY` 在本地调用 Mistral Embed API，生成明文内容的向量表示
2. **加密存储**：将 Embedding 与加密后的内容一起发送到服务器
3. **向量匹配**：服务器基于 Embedding 进行语义相似度计算
4. **本地解密**：匹配结果返回后，在本地使用 `decrypt_content()` 解密
资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)
## 安全特性
### 认证加密（AES-GCM）
使用 Galois/Counter Mode (GCM) 模式提供：
- **机密性**：使用 AES-256 位密钥加密
- **完整性**：GCM 标签检测密文篡改
- **认证**：防止选择密文攻击
### 密钥派生加固
PBKDF2 参数配置：
| 参数 | 值 | 安全性说明 |
|------|-----|----------|
| 迭代次数 | 210,000 | OWASP 2024 建议的最低值 |
| 输出长度 | 256 位 | 匹配 AES-256 密钥长度 |
| 伪随机函数 | HMAC-SHA256 | 行业标准 |
### 盐值管理
- 每个用户分配唯一的 `MEMORAEU_SALT`
- 盐值由服务端生成，确保不可预测性
- 防止彩虹表攻击和预计算攻击
## 依赖项
核心加密库依赖：
```
cryptography>=42.0.0
```
该库提供：
- `cryptography.hazmat.primitives.ciphers.aead.AESGCM`
- `cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`
- `cryptography.hazmat.backends.default_backend()`
资料来源：[requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)
## 版本演进
| 版本 | 更新内容 |
|------|----------|
| 0.1.5 | PBKDF2 升级至 210,000 次迭代 |
| 0.1.5 | 引入 `ENCv1:` 密文前缀 |
| 0.1.0 | 初始 AES-256-GCM 实现 |
资料来源：[CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)
## 最佳实践
1. **使用强密码**：`MEMORAEU_SECRET` 应使用高熵密码
2. **保护盐值**：虽然盐值可公开，但应与密码分开存储
3. **定期轮换**：未来版本应支持密钥轮换机制
4. **本地 Mistral 密钥**：确保 `MISTRAL_API_KEY` 不泄露，确保端到端零知识
---
## MCP 工具详解
### 相关页面
相关主题：[自动记忆机制](#page-auto-memory), [项目概述](#page-overview)
相关源码文件
以下源码文件用于生成本页说明：
- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)
- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)
- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)
- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)
# MCP 工具详解
## 概述
MemoraEU MCP 是一个基于 Model Context Protocol (MCP) 的记忆服务器实现，旨在为 AI 助手提供持久化的上下文记忆能力。该项目允许 Claude 等大语言模型自动记忆用户偏好、决策和重要信息，并在后续对话中自动检索相关内容。
核心功能包括：
- **自动记忆**：AI 自动检测并存储重要信息，无需用户手动触发
- **零知识加密**：所有数据在本地加密后再发送至服务器
- **语义搜索**：支持基于向量相似度的语义检索
- **结构化事实**：存储带有时间有效性的三元组事实
- **自动去重**：防止存储重复或相似的记忆
资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)
## 架构概览
```mermaid
graph TD
subgraph "客户端本地"
A["用户输入"] --> B["Claude / AI 模型"]
B --> C["MCP Client"]
C --> D["记忆处理模块"]
D --> E["本地加密模块"]
E --> F["Mistral Embedding"]
end
subgraph "数据传输"
F --> G["加密内容 + Embedding"]
G --> H["MemoraEU API"]
end
subgraph "服务端存储"
H --> I["向量数据库
存储 embedding"]
H --> J["加密Blob存储
存储密文"]
end
D --> K["压缩模块"]
D --> L["分类模块"]
D --> M["去重检测模块"]
```
资料来源：[memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
## 工具分类
MCP 服务器提供 8 个核心工具，分为三大类别：
| 类别 | 工具 | 功能描述 |
|------|------|----------|
| **记忆工具** | `remember` | 自动记忆重要信息 |
| | `recall` | 语义搜索记忆 |
| | `forget` | 删除指定记忆 |
| | `list_memories` | 列出最近的记忆 |
| | `list_categories` | 列出分类统计 |
| **事实工具** | `remember_fact` | 存储结构化事实 |
| | `recall_facts` | 检索结构化事实 |
| | `invalidate_fact` | 标记事实过期 |
资料来源：[memoraeu_mcp/main.py:70-170](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
## 记忆工具详解
### remember
`remember` 是核心的记忆存储工具，设计为 AI 自动调用，无需用户请求。
#### 功能描述
自动检测并存储用户表达的重要信息，包括偏好、决策、传记事实和技术配置。
#### 参数定义
```json
{
"type": "object",
"properties": {
"content": {
"type": "string",
"description": "要记忆的内容"
},
"category": {
"type": "string",
"description": "分类名称（可选，自动推断）"
},
"tags": {
"type": "array",
"items": {"type": "string"},
"description": "标签数组（可选）"
}
},
"required": ["content"]
}
```
#### 处理流程
```mermaid
graph TD
A["remember 调用"] --> B["本地压缩内容"]
B --> C["自动分类（如未指定）"]
C --> D["生成/获取 Embedding"]
D --> E{"去重检测"}
E -."≥94% 相似
跳过存储"--> F["返回去重警告"]
E -."<94% 相似
继续存储"--> G["本地加密"]
G --> H["POST /memories"]
H --> I["返回记忆ID"]
```
#### 关键特性
| 特性 | 说明 |
|------|------|
| 自动压缩 | 使用 `compress_locally()` 在加密前压缩内容 |
| 自动分类 | 未指定分类时调用 `suggest_category_locally()` |
| 去重检测 | 与现有记忆比较向量相似度 |
| 零知识加密 | 加密后发送至服务器 |
资料来源：[memoraeu_mcp/main.py:120-160](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
### recall
`recall` 是语义搜索工具，用于检索已存储的记忆。
#### 功能描述
在首次用户消息时自动调用，使用语义理解而非关键词匹配进行搜索。
#### 参数定义
```json
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "搜索查询（使用消息主题）"
},
"limit": {
"type": "integer",
"default": 3,
"description": "返回结果数量上限"
},
"category": {
"type": "string",
"description": "按分类过滤（可选）"
}
},
"required": ["query"]
}
```
#### 特殊行为
```mermaid
graph TD
A["首次 recall"] --> B{"_first_recall 标志?"}
B -.->|"是"| C["注入系统提示词"]
B -.->|"是"| D["加载会话上下文"]
C --> E["POST /memories/search"]
D --> E
E --> F["解密结果内容"]
F --> G["返回格式化结果"]
H["非首次 recall"] --> E
```
#### 返回格式
```
🔍 N mémoire(s) :
• [分类] 记忆内容预览... (ID: xxxxxxxx)
标签: tag1, tag2 | 相关度: 0.95
```
资料来源：[memoraeu_mcp/main.py:160-200](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
### forget
删除指定 ID 的记忆。
#### 参数定义
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `memory_id` | string | 是 | 要删除的记忆 ID |
#### 返回值
| 结果 | 返回内容 |
|------|----------|
| 成功 | `🗑️ Supprimée.` |
| 未找到 | `Introuvable.` |
| 错误 | `❌ Erreur : {错误信息}` |
资料来源：[memoraeu_mcp/main.py:200-210](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
### list_memories
列出最近的记忆列表。
#### 参数定义
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `category` | string | — | 按分类过滤（可选） |
| `limit` | integer | 20 | 返回数量上限 |
#### 返回格式
```
📋 N mémoire(s) :
• [分类名称] 内容预览... (ID: xxxxxxxx)
• [分类名称] 内容预览... (ID: xxxxxxxx)
```
资料来源：[memoraeu_mcp/main.py:210-230](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
### list_categories
返回所有已存在的分类，按使用频率排序。
#### 参数定义
无参数。
#### 返回格式
```
📂 Catégories :
• 工作偏好 (15)
• 技术配置 (8)
• 个人信息 (3)
```
资料来源：[memoraeu_mcp/main.py:230-245](https://github.com/pquattro/memoraeu-mcp/blob/main/moraeu_mcp/main.py)
## 事实工具详解
结构化事实存储采用主语-谓语-宾语（SPO）三元组模型，支持时间有效性。
### remember_fact
存储结构化事实，支持时间范围定义。
#### 数据模型
```mermaid
graph LR
S["subject
主语"] --> P["predicate
谓语"]
P --> O["object
宾语"]
S -.->|"valid_from
开始时间"| T["时间范围"]
P -.->|"valid_to
结束时间"| T
```
#### 参数定义
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `subject` | string | 是 | 实体/主语 |
| `predicate` | string | 是 | 属性/谓语 |
| `object` | string | 是 | 值/宾语（加密存储） |
| `scope` | string | 否 | `private` 或 `org`（默认 `private`） |
| `valid_from` | string | 否 | 开始日期 YYYY-MM-DD |
| `valid_to` | string | 否 | 结束日期 YYYY-MM-DD |
#### 返回格式
```
✅ Fait mémorisé 🔒 (remplace xxxxxxxx)
主语 → 谓语
Depuis: 2024-01-01 | ID: xxxxxxxx
```
#### 过期替换机制
当存储与已有事实相同主语和谓语的新事实时，系统自动：
1. 将旧事实标记为 `superseded`
2. 新事实的 `supersedes` 字段记录旧事实 ID
资料来源：[server.py:150-180](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)
### recall_facts
检索指定主语的结构化事实。
#### 参数定义
| 参数 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| `subject` | string | 是 | 要查询的实体 |
| `predicate` | string | 否 | 过滤特定谓语 |
| `scope` | string | `private` | 范围：`private` 或 `org` |
| `history` | boolean | `false` | 是否包含过期事实 |
#### 返回格式
```
📊 N fait(s) pour '主语' :
• 谓语: 宾语值
[2024-01-01 → 2024-06-15 (expiré)] | ID: xxxxxxxx
• 谓语: 宾语值
[2024-06-15 → aujourd'hui] | ID: xxxxxxxx
```
资料来源：[server.py:180-210](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)
### invalidate_fact
标记事实为过期（不再真实）。
#### 参数定义
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `fact_id` | string | 是 | 要过期的事实 ID |
| `valid_to` | string | 否 | 结束日期 YYYY-MM-DD（默认今天） |
#### 使用场景
- 用户更正之前提供的信息
- 临时状态变更（如 "出差中" → 恢复）
- 计划性失效（如活动结束）
资料来源：[server.py:210-220](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)
## 自动记忆行为
系统设计了完整的自动记忆工作流，AI 模型根据工具描述自动执行。
### 工作流程图
```mermaid
sequenceDiagram
participant U as 用户
participant C as Claude
participant MCP as MCP Server
participant API as MemoraEU API
U->>C: 第一条消息
C->>C: 检测话题
C->>MCP: recall(query=话题)
MCP->>API: POST /memories/search
API-->>MCP: 记忆结果
MCP-->>C: 格式化结果 + 系统提示词
C->>C: 处理用户请求
Note over C: 用户表达重要信息
C->>MCP: remember(content=...)
MCP->>MCP: 压缩 → 分类 → 去重检测
MCP->>MCP: 加密内容
MCP->>API: POST /memories
API-->>MCP: 记忆ID
MCP-->>C: ✅ 已记忆
C->>U: 简洁确认
```
### 自动触发规则
| 场景 | 触发条件 | 示例 |
|------|----------|------|
| 偏好表达 | 用户说 "我喜欢..."、"我通常..." | "我更喜欢在上午工作" |
| 决策声明 | 用户做出明确选择 | "我们决定用 React" |
| 传记事实 | 用户介绍自己 | "我是后端工程师" |
| 技术配置 | 用户指定环境或工具 | "我的项目用 Poetry" |
| 约束条件 | 用户说明限制 | "不能超过 2 周" |
### 不应记忆的内容
- 日常闲聊（天气、问候）
- 临时性信息（今日菜单）
- 一次性计算结果
- 用户明确要求遗忘的内容
### 系统提示词注入
首次调用 `recall` 时，系统自动注入完整的行为规范：
```markdown
## 记忆范围
- 用户偏好和习惯
- 重要决策和结论
- 反复出现的信息或约束
## 自动记忆原则
当用户表达以下内容时，立即调用 remember 工具：
- 偏好、决策、传记事实、技术配置
- 或持久性约束
## 规则
- 不记忆一般信息或临时性内容
- 用户要求"遗忘"时使用 forget
- 记忆确认仅需一行
- 优化 tokens：recall 默认限制 3 条结果
```
资料来源：[memoraeu_mcp/main.py:30-60](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
## 去重与压缩机制
### 去重检测流程
```mermaid
graph TD
A["新记忆内容"] --> B["计算向量 Embedding"]
B --> C["与所有现有记忆比较"]
C --> D{"相似度阈值"}
D -.->|">94%"| E["跳过存储
返回去重警告"]
D -.->|"75%-94%"| F["存储但打印警告"]
D -.->|"<75%"| G["正常存储"]
E --> H["⚠️ Doublon détecté (N% similaire)"]
H --> I["显示相似记忆预览"]
```
### 相似度阈值表
| 相似度 | 行为 |
|--------|------|
| ≥ 94% | 完全跳过，不创建新记忆 |
| 75% - 94% | 存储新记忆，打印警告日志 |
| < 75% | 正常存储流程 |
### 本地压缩
在加密前，内容会经过本地压缩处理：
```python
content = await compress_locally(raw_content)
```
压缩目的：
1. 减少加密和传输的数据量
2. 降低 Mistral API 调用成本
3. 保持记忆简洁
资料来源：[memoraeu_mcp/main.py:130-140](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
## 配置与部署
### stdio 模式（推荐）
适用于需要完整零知识保证的场景。
#### 配置示例
```json
{
"mcpServers": {
"memoraeu": {
"command": "uvx",
"args": ["memoraeu-mcp"],
"env": {
"MEMORAEU_API_URL": "https://api.memoraeu.com",
"MEMORAEU_API_KEY": "meu-sk-...",
"MEMORAEU_SECRET": "your-memoraeu-password",
"MEMORAEU_SALT": "your-kdf-salt",
"MISTRAL_API_KEY": "your-mistral-key"
}
}
}
}
```
### SSE 远程模式
适用于快速连接，但不具备零知识保证。
```json
{
"mcpServers": {
"memoraeu": {
"type": "sse",
"url": "https://api.memoraeu.com/mcp/sse",
"headers": {
"Authorization": "Bearer meu-sk-..."
}
}
}
}
```
### 环境变量说明
| 变量 | 用途 | 获取方式 |
|------|------|----------|
| `MEMORAEU_API_KEY` | HTTP 认证 Bearer Token | 设置 → API Keys |
| `MEMORAEU_SECRET` | 账户密码（PBKDF2 输入） | 账户密码 |
| `MEMORAEU_SALT` | KDF 盐值 | 设置 → 加密 Keys |
| `MEMORAEU_API_URL` | API 端点 | 默认 `https://api.memoraeu.com` |
| `MISTRAL_API_KEY` | 本地生成 embedding | Mistral Console |
资料来源：[README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)
## 安全模型
### 零知识加密架构
```mermaid
graph LR
subgraph "本地客户端"
A["明文内容"] --> B["PBKDF2 密钥派生"]
C["SECRET + SALT"] --> B
B --> D["AES-256-GCM 加密"]
A --> D
D --> E["加密 Blob"]
end
subgraph "传输 & 存储"
E --> F["HTTPS 传输"]
F --> G["服务器存储
（无法解密）"]
end
subgraph "搜索"
H["明文"] --> I["Mistral Embedding"]
I --> J["向量搜索"]
G --> J
end
```
### 密钥派生参数
| 参数 | 值 |
|------|------|
| 算法 | PBKDF2-HMAC-SHA256 |
| 迭代次数 | 100,000 |
| 输出密钥长度 | 256 位 |
### Mistral Embedding 的必要性
由于向量搜索需要比较语义相似度，embedding 必须从明文生成：
1. 客户端调用 Mistral API 获取明文 embedding
2. 内容加密后与 embedding 一起发送
3. 服务器仅存储加密 blob 和向量
4. 服务器无法反推明文内容
**无 MISTRAL_API_KEY 时**：搜索降级为服务器端关键词匹配，不影响加密功能。
资料来源：[CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)
## 依赖项
| 依赖 | 版本 | 用途 |
|------|------|------|
| `mcp` | ≥1.1.0, <1.2.0 | MCP 协议实现 |
| `httpx` | 0.28.1 | HTTP 客户端 |
| `python-dotenv` | 1.0.1 | 环境变量加载 |
| `starlette` | ≥0.40.0, <0.42.0 | ASGI 框架 |
| `cryptography` | ≥42.0.0 | 加密实现 |
资料来源：[requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)
## 资源与提示词
### 资源
| URI | 名称 | 说明 |
|-----|------|------|
| `memoraeu://context` | 会话上下文 | 自动加载最近记忆 |
### 提示词
| 名称 | 用途 |
|------|------|
| `memoraeu_system` | 完整的自动记忆行为规范 |
调用方式：
```python
@app.list_prompts()
async def list_prompts() -> list[Prompt]:
return [
Prompt(
name="memoraeu_system",
description="系统记忆行为规范",
arguments=[]
)
]
```
资料来源：[memoraeu_mcp/main.py:60-80](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
---
## 自动记忆机制
### 相关页面
相关主题：[MCP 工具详解](#page-mcp-tools), [去重与压缩](#page-dedup-compression)
相关源码文件
以下源码文件用于生成本页说明：
- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)
- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)
- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)
- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)
# 自动记忆机制
MemoraEU MCP 服务器的核心功能是一套**自动记忆机制**（Auto-memory），它使 AI 能够主动学习、存储和检索用户信息，无需用户手动干预。该机制通过 MCP 工具定义、系统提示注入和上下文资源加载三种方式协同工作。
---
## 概述
自动记忆机制的设计目标是让 AI 在对话过程中自动识别并记住重要的用户信息，包括：
| 信息类型 | 示例 |
|---------|------|
| 用户偏好 | "我更喜欢 TypeScript" |
| 决策记录 | "我们决定用 PostgreSQL" |
| 传记事实 | "我住在上海" |
| 技术约束 | "项目要求 Python 3.10+" |
资料来源：[README.md:1-30]()
### 核心工作流
```mermaid
graph TD
A[用户发送消息] --> B{首次会话?}
B -->|是| C[自动调用 recall]
B -->|否| D[检测记忆内容]
C --> E[加载 memoraeu://context]
E --> F[注入系统提示]
F --> G[返回记忆结果]
D --> H{检测到重要信息?}
H -->|是| I[自动调用 remember]
H -->|否| J[正常处理消息]
I --> K[去重检查]
K --> L{相似度 ≥94%?}
L -->|是| M[跳过存储]
L -->|否| N[本地处理]
N --> O[加密并发送]
M --> P[返回警告]
O --> Q[返回确认]
```
---
## 三大自动行为
### 1. 自动召回（Automatic Recall）
**触发时机**：每个会话的第一条用户消息
**执行流程**：
1. 检测用户消息的主题
2. 使用该主题作为查询词调用 `recall` 工具
3. 通过 `memoraeu://context` 资源加载最近的记忆
4. 将记忆内容注入到会话上下文
```mermaid
graph LR
A[第一条用户消息] --> B[提取主题]
B --> C[recall 工具]
C --> D[memoraeu://context]
D --> E[上下文注入]
```
资料来源：[README.md:45-50]()
### 2. 自动记忆（Automatic Remember）
**触发时机**：当 AI 检测到以下类型的信息时
| 类型 | 判断标准 |
|------|----------|
| 偏好 | 用户表达的个人喜好或选择倾向 |
| 决策 | 涉及项目、方案或技术选型的决定 |
| 传记事实 | 关于用户身份、背景的信息 |
| 技术约束 | 配置、凭证（非敏感）、技术栈信息 |
**执行特点**：
- 无需用户请求，AI 主动调用 `remember` 工具
- 记忆后仅返回一行简短确认
- 不会频繁确认打扰用户
资料来源：[README.md:51-55]()
### 3. 系统提示注入（System Prompt Injection）
**触发时机**：首次调用 `recall` 工具时
**注入内容**：完整的自动记忆行为规范，定义于 `SYSTEM_PROMPT_TEXT` 常量中
**注入方式**：作为用户角色消息注入到 Claude 上下文，强化后续会话中的自动记忆规则
```python
SYSTEM_PROMPT_TEXT = """
## Objectif
Mémoriser automatiquement les informations importantes de l'utilisateur...
## Rappel automatique
Dès le premier message de l'utilisateur, utilise recall avec le sujet détecté comme query...
## Règles
- Ne mémorise pas les informations générales ou éphémères
- Si l'utilisateur dit "oublie ça", utilise forget
- Confirme discrètement les mémorisations
- Optimisation tokens : limite recall à 3 résultats
"""
```
资料来源：[memoraeu_mcp/main.py:1-50]()
---
## 本地预处理流程
自动记忆机制在数据发送到服务器之前执行完整的本地处理，确保**零知识（Zero-Knowledge）**保障：
```mermaid
graph TD
A[原始内容] --> B[本地压缩]
A --> C[本地分类]
A --> D[本地嵌入]
B --> E{去重检查}
D --> E
E -->|≥94%相似| F[跳过存储]
E -->|<94%相似| G[加密内容]
G --> H[发送到API]
H --> I[返回确认]
```
### 处理步骤详解
| 步骤 | 操作 | 说明 |
|------|------|------|
| 1 | 压缩 | 使用 Mistral API 在明文状态下压缩内容，减少 token 消耗 |
| 2 | 分类 | 如果未指定类别，自动建议合适的分类 |
| 3 | 嵌入 | 使用 Mistral Embed 从明文生成向量，用于语义搜索 |
| 4 | 去重 | 使用向量相似度检查（阈值 94%），避免重复存储 |
| 5 | 加密 | 使用 AES-256-GCM 加密内容后发送 |
| 6 | 存储 | API 存储加密内容和向量，但不包含明文 |
资料来源：[memoraeu_mcp/main.py:200-260]()
### 零知识保障
**关键设计**：嵌入向量在加密之前生成
```
用户明文 → Mistral Embed API → 向量 → 加密 → 发送到服务器
↑
本地执行，保证服务器无法看到明文
```
资料来源：[README.md:75-85]()
---
## 工具定义
### 核心记忆工具
| 工具名 | 功能 | 关键参数 |
|--------|------|----------|
| `remember` | 自动记忆重要信息 | `content`（必需）、`category`、`tags` |
| `recall` | 语义搜索记忆 | `query`（必需）、`limit`（默认3）、`category` |
| `forget` | 删除指定记忆 | `memory_id`（必需） |
| `list_memories` | 列出最近记忆 | `limit`（默认20）、`category` |
| `list_categories` | 获取分类列表 | 无 |
### 结构化事实工具
| 工具名 | 功能 | 关键参数 |
|--------|------|----------|
| `remember_fact` | 存储结构化事实 | `subject`（必需）、`predicate`（必需）、`object`（必需） |
| `recall_facts` | 检索活动事实 | `subject`（必需）、`predicate`、`history` |
| `invalidate_fact` | 标记事实过期 | `fact_id`（必需）、`valid_to` |
资料来源：[server.py:50-150]()
---
## 去重与压缩机制
### 向量相似度阈值
| 相似度 | 处理动作 |
|--------|----------|
| ≥ 94% | 记忆被忽略，提示用户为重复内容 |
| < 94% | 正常存储（可能打印警告日志） |
```python
DEDUP_SKIP_THRESHOLD = 0.94 # 94% 相似度阈值
```
资料来源：[memoraeu_mcp/main.py:230-245]()
### 去重检查流程
```mermaid
graph TD
A[新内容] --> B[生成本地嵌入]
B --> C[API 搜索相似向量]
C --> D{最高相似度?}
D -->|≥94%| E[返回重复警告]
D -->|<94%| F{≥70%|
F -->|否| G[存储新记忆]
F -->|是| H[存储并记录警告]
```
---
## 配置要求
### 环境变量
| 变量名 | 用途 | 获取方式 |
|--------|------|----------|
| `MEMORAEU_API_KEY` | HTTP 认证令牌 | Dashboard → Settings → API Keys |
| `MEMORAEU_SECRET` | 登录密码，用于派生加密密钥 | 用户账户密码 |
| `MEMORAEU_SALT` | KDF 盐值，服务器生成 | Dashboard → Settings → Encryption Keys |
| `MEMORAEU_API_URL` | API 端点 | 托管服务使用 `https://api.memoraeu.com` |
| `MISTRAL_API_KEY` | 本地嵌入生成（可选但推荐） | console.mistral.ai |
### Mistral API Key 的必要性
```
┌─────────────────────────────────────────────────────────────┐
│ 为什么需要 Mistral API Key？ │
├─────────────────────────────────────────────────────────────┤
│ 零知识搜索 = 服务器无法看到你的明文 │
│ │
│ 语义搜索需要向量 → 向量必须在本地生成 → 需要 Mistral Embed │
└─────────────────────────────────────────────────────────────┘
```
**无 Mistral Key 时**：搜索降级为服务器端关键词搜索，加密不受影响。
资料来源：[README.md:70-85]()
---
## 安全特性
### 加密方案
| 参数 | 值 |
|------|-----|
| 算法 | AES-256-GCM |
| 密钥派生 | PBKDF2-HMAC-SHA256 |
| 迭代次数 | 210,000（OWASP 2024 推荐） |
| 密文前缀 | `ENCv1:` |
资料来源：[CHANGELOG.md:15-20]()
### 密钥管理
```python
def get_key() -> bytes | None:
"""从环境变量派生加密密钥"""
secret = os.environ.get("MEMORAEU_SECRET")
salt = os.environ.get("MEMORAEU_SALT")
if not secret or not salt:
return None
return PBKDF2(secret, salt, iterations=210000)
```
---
## 会话上下文资源
MCP 服务器通过 `memoraeu://context` 资源提供会话上下文：
```python
@app.list_resources()
async def list_resources() -> list[Resource]:
return [
Resource(
uri="memoraeu://context",
name="Contexte mémoire MemoraEU",
description="Mémoires récentes injectées automatiquement...",
mimeType="text/plain"
)
]
@app.read_resource()
async def read_resource(uri: str) -> list[ResourceContents]:
if uri == "memoraeu://context":
context = await load_session_context()
return [TextResourceContents(uri=uri, text=context)]
```
资料来源：[memoraeu_mcp/main.py:80-100]()
---
## 行为规则总结
| 规则 | 说明 |
|------|------|
| 不记忆 | 通用信息、临时信息（天气、笑话、一次性计算） |
| 响应确认 | 仅一行，简洁低调 |
| Token 优化 | 默认限制 3 条记忆结果 |
| 遗忘请求 | 用户说"忘记"时立即调用 `forget` |
```mermaid
graph TD
A[用户消息] --> B{信息类型?}
B -->|偏好/决策/传记/技术约束| C[自动 remember]
B -->|通用/临时| D[正常处理]
C --> E{重复检查}
E -->|≥94%| F[返回警告]
E -->|<94%| G[存储]
D --> H[无记忆]
```
资料来源：[memoraeu_mcp/main.py:30-45]()
---
## 版本变更记录
| 版本 | 变更内容 |
|------|----------|
| 0.1.9 | 新增 `remember_fact`、`recall_facts`、`invalidate_fact` 结构化事实工具；PBKDF2 迭代次数提升至 210,000 |
| 0.1.5 | 初始版本，包含基础 `remember`、`recall`、`forget` 工具和自动行为 |
资料来源：[CHANGELOG.md:1-35]()
---
## 去重与压缩
### 相关页面
相关主题：[自动记忆机制](#page-auto-memory), [加密系统](#page-encryption)
相关源码文件
以下源码文件用于生成本页说明：
- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)
- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)
- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)
- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)
# 去重与压缩
## 概述
memoraeu-mcp 实现了客户端去重与压缩机制，在数据加密前对内容进行处理。这一设计确保了：
1. **存储效率** — 避免存储重复或冗余的记忆
2. **零知识保证** — 所有处理均在加密前本地完成，服务器无法访问明文
资料来源：[README.md:1-50]()
## 工作流程
### 整体数据流
```mermaid
graph TD
A[用户输入内容] --> B[本地压缩]
B --> C[本地分类建议]
C --> D[生成 Embedding]
D --> E[重复检测]
E --> F{是否重复?}
F -->|是| G[跳过存储]
F -->|否| H[加密内容]
H --> I[发送到 API]
G --> J[返回警告]
I --> K[存储成功]
L[Mistral API] -.->|压缩/分类| B
L -.->|Embedding| D
```
### 记忆存储流程
在 `remember` 工具调用时，系统按以下顺序执行：
| 步骤 | 操作 | 执行位置 | 依赖 |
|------|------|----------|------|
| 1 | 内容压缩 | 本地 | Mistral Chat |
| 2 | 分类建议 | 本地 | Mistral Chat |
| 3 | 生成 Embedding | 本地 | Mistral Embed |
| 4 | 重复检测 | 本地 | 向量相似度 |
| 5 | 内容加密 | 本地 | PBKDF2 + AES-256-GCM |
| 6 | 发送存储 | 远程 | MemoraEU API |
资料来源：[memoraeu_mcp/main.py:150-200]()
## 压缩机制
### 压缩阈值
系统使用 `COMPRESSION_THRESHOLD` 变量控制压缩触发条件。当内容长度超过此阈值时才进行压缩处理。
```python
if len(content) <= COMPRESSION_THRESHOLD:
return content
```
资料来源：[memoraeu_mcp/main.py:1-50]()
### 压缩实现
压缩功能由 `compress_locally()` 函数实现：
```python
async def compress_locally(content: str) -> str:
"""
Résume ce texte en 1-3 phrases concises, en français,
en gardant l'essentiel. Réponds uniquement avec le résumé.
"""
prompt = (
"Résume ce texte en 1-3 phrases concises, en français, "
"en gardant l'essentiel. Réponds uniquement avec le résumé, "
"sans introduction ni conclusion.\n\n"
f"{content}"
)
compressed = await _mistral_chat(prompt)
if compressed and len(compressed) < len(content):
print(f"[mcp] Compression: {len(content)} → {len(compressed)} chars")
return compressed
return content
```
资料来源：[memoraeu_mcp/main.py:50-80]()
### 压缩特点
| 特性 | 说明 |
|------|------|
| 触发条件 | 内容长度 > `COMPRESSION_THRESHOLD` |
| 压缩方式 | Mistral Chat API 生成 1-3 句法式摘要 |
| 语言 | 使用法语（与系统语言一致） |
| 降级策略 | 若压缩后更长，保留原内容 |
| 加密时机 | 压缩后立即加密，服务器不可见 |
## 分类建议机制
### 本地分类函数
```python
async def suggest_category_locally(content: str, existing: list[str]) -> str:
"""Suggère une catégorie pour le contenu en clair."""
existing_str = ", ".join(existing) if existing else "aucune"
prompt = (
f"Catégories existantes : {existing_str}\n\n"
f"Texte : {content[:500]}\n\n"
"Quelle catégorie courte (1-2 mots, en français, minuscules) "
"correspond le mieux ? Utilise une existante si pertinent, "
"sinon crée-en une. Réponds uniquement avec la catégorie."
)
cat = await _mistral_chat(prompt)
if cat:
return cat.lower().strip().strip('"').strip("'")[:30]
return "personnel"
```
资料来源：[memoraeu_mcp/main.py:80-110]()
### 分类处理流程
```mermaid
graph TD
A[新内容] --> B[获取已有分类列表]
B --> C[调用 Mistral Chat]
C --> D{返回有效分类?}
D -->|是| E[规范化分类名]
D -->|否| F[返回默认分类: personnel]
E --> G[限制长度 30 字符]
G --> H[返回分类]
```
### 分类默认值
| 情况 | 行为 |
|------|------|
| 用户指定分类 | 使用用户提供的分类 |
| 未指定且有现有分类 | 调用 Mistral 建议分类 |
| 未指定且无现有分类 | 返回默认分类 `personnel` |
## 去重检测机制
### 重复检测阈值
| 相似度 | 处理行为 |
|--------|----------|
| ≥ 94% | **跳过存储** — 视为完全重复 |
| < 94% | 仍存储，但记录相似度日志 |
资料来源：[README.md:60-80]()
### 去重实现
```python
async def check_duplicate(embedding: list[float]) -> dict | None:
"""
Recherche une mémoire similaire via le vecteur pré-calculé (zero-knowledge).
Retourne la mémoire duplicata si trouvé, None sinon.
"""
# ... API 调用获取相似记忆
score_pct = round(dup["score"] * 100)
if dup["score"] >= DEDUP_SKIP_THRESHOLD:
return [TextContent(type="text", text=(
f"⚠️ Doublon détecté ({score_pct}% similaire) — mémoire non créée.\n"
f"→ Existante : {dup['preview']} (ID: {dup['id'][:8]}…)"
))]
else:
print(f"[mcp] Mémoire similaire à {score_pct}% — stockage quand même")
return None
```
资料来源：[memoraeu_mcp/main.py:110-140]()
### 零知识去重原理
```mermaid
graph LR
A[明文内容] --> B[Mistral Embed]
B --> C[Embedding 向量]
C --> D[本地存储加密]
C --> E[发送给服务器]
F[服务器] --> G[无法解密内容]
G --> H[但可比较向量相似度]
E --> H
```
去重机制利用了预计算的 Embedding 向量进行相似度计算，这些向量在本地生成后立即用于重复检测，服务器仅存储加密后的向量数据。
## 加密集成
### 加密流程
在去重和压缩完成后，系统对内容进行加密：
```python
# 1. 检查重复
if dup_result:
return dup_result
# 2. 加密处理后的内容
encrypted = encrypt_content(content)
# 3. 发送到 API
payload = {
"content": encrypted,
"category": category,
"tags": arguments.get("tags", []),
"source": "claude_desktop",
"scope": "private",
"pre_processed": True,
}
if embedding:
payload["embedding"] = embedding
memory = await api_post("/memories", payload)
```
资料来源：[memoraeu_mcp/main.py:180-220]()
### 加密参数
| 参数 | 说明 | 来源 |
|------|------|------|
| 算法 | AES-256-GCM | 客户端加密 |
| 密钥派生 | PBKDF2-HMAC-SHA256 | 本地派生 |
| 迭代次数 | 210,000 次 | OWASP 2024 推荐 |
| 盐值 | `MEMORAEU_SALT` | 服务器生成 |
| 密文前缀 | `ENCv1:` | 版本标识 |
## 环境配置
### 必需环境变量
| 变量 | 用途 | 获取方式 |
|------|------|----------|
| `MEMORAEU_API_KEY` | API 认证 | 仪表板 → 设置 → API 密钥 |
| `MEMORAEU_SECRET` | 密码 → 加密密钥派生 | 用户账户密码 |
| `MEMORAEU_SALT` | KDF 盐值 | 仪表板 → 设置 → 加密密钥 |
| `MEMORAEU_API_URL` | API 端点 | 默认: `https://api.memoraeu.com` |
| `MISTRAL_API_KEY` | Embedding 和压缩 | [console.mistral.ai](https://console.mistral.ai) |
### Mistral API 作用
> **为什么 MCP 需要 Mistral 密钥？**
>
> 零知识意味着服务器永远看不到明文。为了支持语义搜索，Embedding 必须在**加密前**计算——在你的机器上。MCP 直接用明文调用 Mistral，获取向量后加密内容，然后发送两者到服务器。
资料来源：[README.md:40-50]()
## 完整存储决策流程
```mermaid
graph TD
A[remember 调用] --> B{内容 > 阈值?}
B -->|是| C[压缩内容]
B -->|否| D[保持原样]
C --> E{指定分类?}
D --> E
E -->|否| F[建议分类]
E -->|是| G[使用指定分类]
F --> H[生成 Embedding]
G --> H
H --> I[检查重复]
I --> J{相似度 ≥ 94%?}
J -->|是| K[返回警告]
J -->|否| L[加密内容]
L --> M[发送 API]
M --> N[返回成功]
K --> O[结束]
N --> O
```
## 版本变更
### v0.1.9 (2026-05-12)
- PBKDF2 迭代次数提升至 210,000 次（OWASP 2024 推荐）
- 引入密文前缀 `ENCv1:` 版本标识
资料来源：[CHANGELOG.md:20-30]()
### v0.1.5 (2026-04-28)
- 初始去重机制实现
- 向量相似度阈值 0.94 (94%) 正式启用
- 本地压缩和分类功能上线
## 相关依赖
| 依赖 | 版本 | 用途 |
|------|------|------|
| httpx | 0.28.1 | 异步 HTTP 客户端 |
| starlette | ≥0.40.0,<0.42.0 | Web 框架 |
| cryptography | ≥42.0.0 | 加密实现 |
| python-dotenv | 1.0.1 | 环境变量管理 |
资料来源：[requirements.txt:1-10]()
---
## 配置与密钥管理
### 相关页面
相关主题：[快速开始](#page-quickstart), [自托管部署](#page-selfhosting)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)
- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)
- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)
- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)
# 配置与密钥管理
## 概述
MemoraEU MCP 是一个零知识（Zero-Knowledge）记忆系统，其核心安全机制建立在密钥管理与加密架构之上。本页详细说明 MCP 服务器的配置方式、环境变量的作用、密钥派生流程，以及不同部署模式下的安全考量。
资料来源：[README.md]()
---
## 环境变量总览
MCP 服务器依赖五个核心环境变量，分为三类用途：
| 变量名 | 用途分类 | 说明 |
|--------|----------|------|
| `MEMORAEU_API_KEY` | HTTP 认证 | Bearer Token，随每个请求发送 |
| `MEMORAEU_SECRET` | 密钥派生 | 用户登录密码，用于本地派生加密密钥 |
| `MEMORAEU_SALT` | 密钥派生 | 服务器生成的 KDF 盐值，账户唯一 |
| `MEMORAEU_API_URL` | 端点配置 | API 服务器地址 |
| `MISTRAL_API_KEY` | 嵌入生成 | 本地生成向量嵌入（加密前） |
资料来源：[README.md]()
---
## 密钥派生与加密架构
### 加密流程
```mermaid
graph TD
A[用户密码 MEMORAEU_SECRET] --> B[PBKDF2-HMAC-SHA256]
C[服务器盐值 MEMORAEU_SALT] --> B
B --> D[派生密钥 Key]
E[明文内容] --> F[本地压缩]
F --> G[本地嵌入生成 Mistral]
G --> H[AES-256-GCM 加密]
D --> H
H --> I[ENCv1: 前缀密文]
I --> J[上传至服务器]
```
### 加密参数
根据 CHANGELOG.md v0.1.9 版本更新：
| 参数 | 值 | 说明 |
|------|-----|------|
| 算法 | AES-256-GCM | 对称加密，认证加密 |
| KDF | PBKDF2-HMAC-SHA256 | 密码学密钥派生函数 |
| 迭代次数 | 210,000 | OWASP 2024 推荐值 |
| 密文前缀 | `ENCv1:` | 版本标识，便于密钥轮换 |
| 盐值长度 | 账户唯一 | 服务器生成，Base64 编码 |
资料来源：[CHANGELOG.md]()
资料来源：[memoraeu_mcp/main.py]()
### 本地处理阶段
在加密发生前，MCP 客户端执行以下明文处理：
1. **内容压缩** — 调用 `compress_locally()` 函数减小体积
2. **分类建议** — 调用 `suggest_category_locally()` 自动分类
3. **嵌入生成** — 调用 Mistral Embed API 生成向量
这三个步骤均在加密前执行，确保服务器永远无法访问明文内容。
资料来源：[memoraeu_mcp/main.py:150-180]()
---
## stdio 本地安装配置
本地安装提供完整的零知识保障。所有处理在本地完成。
### 安装命令
```bash
uvx memoraeu-mcp
```
### claude_desktop_config.json 配置示例
```json
{
"mcpServers": {
"memoraeu": {
"command": "uvx",
"args": ["memoraeu-mcp"],
"env": {
"MEMORAEU_API_URL": "https://api.memoraeu.com",
"MEMORAEU_API_KEY": "meu-sk-...",
"MEMORAEU_SECRET": "your-memoraeu-password",
"MEMORAEU_SALT": "your-kdf-salt",
"MISTRAL_API_KEY": "your-mistral-key"
}
}
}
}
```
### 环境变量获取指南
| 变量 | 获取方式 |
|------|----------|
| `MEMORAEU_API_KEY` | 仪表盘 → 设置 → API 密钥 → 创建新密钥 |
| `MEMORAEU_SECRET` | MemoraEU 账户登录密码 |
| `MEMORAEU_SALT` | 仪表盘 → 设置 → 加密密钥 → 复制盐值 |
| `MEMORAEU_API_URL` | 使用 `https://api.memoraeu.com`（托管服务） |
| `MISTRAL_API_KEY` | [console.mistral.ai](https://console.mistral.ai) 获取 |
资料来源：[README.md]()
---
## SSE 远程模式配置
远程模式下，MCP 通过 Server-Sent Events 连接到 MemoraEU API，无需本地安装。
### 安全说明
> **注意：** 在 SSE 远程模式下，内容**不提供**零知识加密（服务器以明文处理文本）。如需完整的零知识保障，请使用本地 `stdio` 安装模式。
资料来源：[README.md]()
### 配置文件示例
```json
{
"mcpServers": {
"memoraeu": {
"type": "sse",
"url": "https://api.memoraeu.com/mcp/sse",
"headers": {
"Authorization": "Bearer meu-sk-..."
}
}
}
}
```
### 部署模式对比
| 特性 | stdio 本地模式 | SSE 远程模式 |
|------|----------------|--------------|
| 零知识加密 | ✅ 完整保障 | ❌ 明文处理 |
| 嵌入本地生成 | ✅ | ❌ |
| 无需安装 | ❌ | ✅ |
| 适用场景 | 高安全需求 | 快速接入 |
资料来源：[README.md]()
---
## Mistral API Key 的必要性
### 为什么需要 Mistral Key？
零知识搜索的核心在于：**嵌入必须在加密前生成**。
```mermaid
graph LR
A[明文内容] --> B[Mistral API
生成嵌入向量]
B --> C[本地加密内容]
B --> D[加密后嵌入]
C --> E[上传密文 + 嵌入]
D --> E
E --> F[服务器存储
但无法解密]
```
1. MCP 直接使用明文调用 Mistral Embed API
2. 获取向量嵌入后，在本地同时加密内容和嵌入
3. 服务器存储密文 blob 和加密向量
4. 服务器无法反向解析原始文本
资料来源：[README.md]()
### 无 Mistral Key 时的行为
```mermaid
graph TD
A[MISTRAL_API_KEY 未配置] --> B{检测到缺失}
B --> C[remember/recall 仍可用]
B --> D[语义搜索降级]
D --> E[服务端关键词搜索替代]
C --> F[零知识加密不受影响]
E --> G[搜索精度降低]
```
- `remember` 和 `recall` 工具保持可用
- 语义搜索切换为服务端关键词匹配
- AES-256-GCM 加密不受影响
资料来源：[README.md]()
---
## 依赖配置
项目依赖声明于 `requirements.txt`：
```
mcp>=1.1.0,<1.2.0
httpx==0.28.1
python-dotenv==1.0.1
starlette>=0.40.0,<0.42.0
cryptography>=42.0.0
```
### 核心依赖说明
| 包名 | 版本约束 | 用途 |
|------|----------|------|
| `mcp` | ≥1.1.0, <1.2.0 | MCP 协议实现 |
| `httpx` | 0.28.1 | 异步 HTTP 客户端 |
| `python-dotenv` | 1.0.1 | 环境变量加载 |
| `starlette` | ≥0.40.0, <0.42.0 | ASGI 框架（用于 SSE） |
| `cryptography` | ≥42.0.0 | AES-256-GCM 加密实现 |
资料来源：[requirements.txt]()
---
## 应用程序内部加密实现
### 加密函数位置
核心加密逻辑位于 `memoraeu_mcp/main.py`，包含以下关键函数：
| 函数名 | 功能 |
|--------|------|
| `encrypt_content()` | 使用 AES-256-GCM 加密内容，添加 `ENCv1:` 前缀 |
| `decrypt_content()` | 解密内容，验证前缀版本 |
| `get_key()` | 从环境变量派生密钥并缓存 |
### 密钥派生流程
```python
# PBKDF2 参数（v0.1.9 更新）
PBKDF2_ITERATIONS = 210000 # OWASP 2024 推荐
PBKDF2_ALGORITHM = "sha256"
KEY_LENGTH = 32 # AES-256
```
### 去重与加密流程
```mermaid
graph TD
A[原始内容] --> B[本地压缩]
B --> C[分类处理]
C --> D[嵌入生成
Mistral]
D --> E{去重检查
相似度 ≥ 0.94?}
E -->|是| F[跳过存储
返回警告]
E -->|否| G[继续处理]
G --> H{相似度 ≥ 0.85?}
H -->|是| I[警告但仍存储]
H -->|否| J[正常存储]
J --> K[本地加密]
G --> K
K --> L[上传 API
pre_processed=True]
```
资料来源：[memoraeu_mcp/main.py:180-220]()
---
## API 端点配置
### 服务端点
| 环境 | URL |
|------|-----|
| 生产环境 | `https://api.memoraeu.com` |
| SSE 端点 | `https://api.memoraeu.com/mcp/sse` |
| 记忆搜索 | `/memories/search` |
| 记忆创建 | `/memories` |
| 事实存储 | `/facts` |
| 分类列表 | `/memories/categories` |
### API 认证头
```json
{
"Authorization": "Bearer {MEMORAEU_API_KEY}"
}
```
支持新版 `meu-sk-xxx` 格式的 API Key。
资料来源：[CHANGELOG.md]()
资料来源：[README.md]()
---
## 安全最佳实践
### 生产环境建议
| 建议 | 说明 |
|------|------|
| 使用 stdio 本地模式 | 确保零知识加密完整 |
| 定期轮换 `MEMORAEU_SALT` | 通过仪表盘重新生成 |
| 保护 `MEMORAEU_SECRET` | 不要明文存储在代码库 |
| 使用环境变量文件 | `.env` 文件配合 `python-dotenv` |
### 敏感信息处理
```bash
# 推荐的 .env 文件结构
MEMORAEU_API_URL=https://api.memoraeu.com
MEMORAEU_API_KEY=meu-sk-xxx
MEMORAEU_SECRET=your-strong-password
MEMORAEU_SALT=base64-encoded-salt
MISTRAL_API_KEY=mistral-api-key
```
> **警告：** 确保 `.env` 文件加入 `.gitignore`，永不提交到版本控制系统。
---
## 故障排查
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 语义搜索不工作 | 缺少 `MISTRAL_API_KEY` | 添加 Mistral API Key |
| 加密失败 | `MEMORAEU_SECRET` 或 `MEMORAEU_SALT` 错误 | 检查环境变量配置 |
| 连接超时 | `MEMORAEU_API_URL` 错误 | 确认使用正确端点 |
| 认证失败 | `MEMORAEU_API_KEY` 过期或格式错误 | 重新生成 API Key |
---
## 版本历史
| 版本 | 日期 | 密钥相关变更 |
|------|------|--------------|
| 0.1.9 | 2026-05-12 | PBKDF2 升级至 210,000 次迭代，添加 `ENCv1:` 前缀 |
| 0.1.5 | 2026-04-28 | 初始加密实现版本 |
资料来源：[CHANGELOG.md]()
---
## 自托管部署
### 相关页面
相关主题：[配置与密钥管理](#page-configuration), [项目概述](#page-overview)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/pquattro/memoraeu-mcp/blob/main/README.md)
- [memoraeu_mcp/main.py](https://github.com/pquattro/memoraeu-mcp/blob/main/memoraeu_mcp/main.py)
- [server.py](https://github.com/pquattro/memoraeu-mcp/blob/main/server.py)
- [requirements.txt](https://github.com/pquattro/memoraeu-mcp/blob/main/requirements.txt)
- [CHANGELOG.md](https://github.com/pquattro/memoraeu-mcp/blob/main/CHANGELOG.md)
# 自托管部署
## 概述
memoraeu-mcp 支持两种部署模式：远程 SSE（Server-Sent Events）模式和本地 stdio 模式。这两种模式在安全性和功能上存在显著差异，开发者可根据实际需求选择合适的部署方式。
**核心区别**：远程 SSE 模式下，服务器会处理明文数据，无法提供零知识加密保证；本地 stdio 模式则能在用户本地机器上完成所有加密操作，实现完整的零知识保护。
资料来源：[README.md:1-10]()
## 部署模式对比
| 特性 | 远程 SSE 模式 | 本地 stdio 模式 |
|------|-------------|----------------|
| 零知识加密 | ❌ 不支持（服务器处理明文） | ✅ 完全支持 |
| 数据传输 | 通过 HTTPS 传输明文 | 进程间通信（本地） |
| 加密时机 | 服务器端加密 | 客户端本地加密 |
| 配置复杂度 | 较低 | 较高（需配置密钥） |
| 适用场景 | 快速测试、信任服务器 | 生产环境、高隐私需求 |
资料来源：[README.md:11-15]()
## 环境变量配置
memoraeu-mcp 使用五个关键环境变量，这些变量服务于三个不同的用途，彼此不可互换：
| 变量名 | 用途 | 获取方式 |
|--------|------|----------|
| `MEMORAEU_API_KEY` | HTTP 认证（Bearer token，随每个请求发送） | 仪表板 → 设置 → API 密钥 |
| `MEMORAEU_SECRET` | 用户 MemoraEU 登录密码，用于本地 PBKDF2 派生加密密钥 | 用户账户密码 |
| `MEMORAEU_SALT` | 服务器生成的 KDF 盐值，唯一对应用户账户，与 `MEMORAEU_SECRET` 组合生成加密密钥 | 仪表板 → 设置 → 加密密钥 |
| `MEMORAEU_API_URL` | API 端点地址 | 使用 `https://api.memoraeu.com`（托管服务） |
| `MISTRAL_API_KEY` | 本地生成嵌入向量（在加密前），用于零知识语义搜索 | [console.mistral.ai](https://console.mistral.ai) |
资料来源：[README.md:32-45]()
## 本地 stdio 模式部署
本地 stdio 模式是实现零知识加密的关键部署方式，所有敏感操作都在本地完成。
### 工作原理
```mermaid
graph TD
A[用户输入] --> B[本地 MCP 服务器]
B --> C{MISTRAL_API_KEY}
C -->|生成嵌入| D[加密内容]
D --> E[加密的嵌入向量]
B --> F[AES-256-GCM 加密]
F --> G[发送加密数据到服务器]
E --> G
G --> H[远程服务器存储]
style A fill:#e1f5fe
style H fill:#ffebee
style D fill:#c8e6c9
```
### 配置步骤
1. **获取 API 密钥**：登录 MemoraEU 仪表板，获取 `MEMORAEU_API_KEY`
2. **获取加密密钥**：在仪表板的"加密密钥"页面获取唯一的 `MEMORAEU_SALT`
3. **设置用户密码**：使用您的 MemoraEU 账户密码作为 `MEMORAEU_SECRET`
4. **获取 Mistral API 密钥**：访问 [console.mistral.ai](https://console.mistral.ai) 获取 `MISTRAL_API_KEY`
5. **编辑 Claude Desktop 配置**：在 `claude_desktop_config.json` 中添加以下配置：
```json
{
"mcpServers": {
"memoraeu": {
"command": "uvx",
"args": ["memoraeu-mcp"],
"env": {
"MEMORAEU_API_URL": "https://api.memoraeu.com",
"MEMORAEU_API_KEY": "meu-sk-...",
"MEMORAEU_SECRET": "your-memoraeu-password",
"MEMORAEU_SALT": "your-kdf-salt",
"MISTRAL_API_KEY": "your-mistral-key"
}
}
}
}
```
资料来源：[README.md:22-30]()
### 使用 uvx 快速启动
memoraeu-mcp 支持通过 `uvx`（UV 包管理器）直接运行，无需手动安装：
```bash
uvx memoraeu-mcp
```
所有环境变量需要在启动前设置好，或者通过 `.env` 文件管理。
资料来源：[README.md:22-25]()
## 零知识加密机制
memoraeu-mcp 采用多层加密策略确保数据安全：
### 加密流程
```mermaid
sequenceDiagram
participant 用户 as 用户应用
participant MCP as MCP 服务器
participant Mistral as Mistral API
participant Server as 远程服务器
用户->>MCP: 输入明文内容
MCP->>Mistral: 发送明文获取嵌入
Mistral-->>MCP: 返回嵌入向量
MCP->>MCP: PBKDF2-HMAC-SHA256 派生密钥
(100k 迭代)
MCP->>MCP: AES-256-GCM 加密内容
MCP->>Server: 发送加密内容 + 加密嵌入
Server-->>用户: 存储不透明的加密 blob
```
### 密钥派生参数
| 参数 | 值 |
|------|-----|
| 算法 | PBKDF2-HMAC-SHA256 |
| 迭代次数 | 100,000 次 |
| 盐值 | 服务器提供的唯一盐（`MEMORAEU_SALT`） |
| 密文前缀 | `ENCv1:` |
| 加密算法 | AES-256-GCM |
资料来源：[CHANGELOG.md:15-20]()
## Mistral API 密钥的作用
### 为什么需要 Mistral API 密钥？
零知识意味着服务器永远不会看到用户的明文数据。为了实现语义搜索功能，嵌入向量必须在加密之前计算——即在用户本地机器上完成。
**工作流程**：
1. MCP 使用明文内容直接调用 Mistral API
2. 获取嵌入向量
3. 在本地加密内容
4. 将加密内容和加密嵌入同时发送到服务器
5. 服务器存储加密 blob 和嵌入向量，但无法还原原始文本
资料来源：[README.md:48-55]()
### 无 Mistral API 密钥时的行为
如果未配置 `MISTRAL_API_KEY`，MCP 仍可继续运行：
- `remember` 和 `recall` 工具保持可用
- 语义搜索将降级为基于关键词的服务器端搜索
- 零知识加密不受影响
资料来源：[README.md:57-59]()
## 系统要求与依赖
memoraeu-mcp 的部署需要以下依赖环境：
### Python 依赖
| 依赖包 | 版本要求 | 用途 |
|--------|----------|------|
| `mcp` | ≥1.1.0, <1.2.0 | MCP 协议实现 |
| `httpx` | 0.28.1 | HTTP 客户端 |
| `python-dotenv` | 1.0.1 | 环境变量管理 |
| `starlette` | ≥0.40.0, <0.42.0 | ASGI 框架 |
| `cryptography` | ≥42.0.0 | 加密功能 |
资料来源：[requirements.txt:1-5]()
### 运行时环境
- **Python**: 3.9+
- **包管理器**: UV（推荐）或 pip
- **网络**: 需要访问 `api.memoraeu.com` 和 `api.mistral.ai`
## 部署检查清单
| 检查项 | 说明 | 优先级 |
|--------|------|--------|
| ✅ 创建 MemoraEU 账户 | 注册并获取 API 访问权限 | 必须 |
| ✅ 获取 API 密钥 | 在仪表板获取 `MEMORAEU_API_KEY` | 必须 |
| ✅ 获取加密盐值 | 获取唯一的 `MEMORAEU_SALT` | 必须 |
| ✅ 配置账户密码 | 设置 `MEMORAEU_SECRET` | 必须 |
| ✅ 获取 Mistral API 密钥 | 用于零知识语义搜索 | 推荐 |
| ✅ 配置 `claude_desktop_config.json` | 添加 MCP 服务器配置 | 必须 |
| ✅ 验证加密连接 | 确认锁图标显示 🔒 | 推荐 |
## 安全建议
1. **使用强密码**：作为 `MEMORAEU_SECRET`，使用高强度密码以增强密钥派生质量
2. **保护盐值**：`MEMORAEU_SALT` 与账户绑定，不应共享
3. **Mistral API 密钥安全**：该密钥仅在本地使用，应妥善保管
4. **定期轮换**：定期更新 API 密钥和加密盐值
5. **网络传输**：即使使用 HTTPS，远程 SSE 模式下的数据传输仍为明文，仅加密存储
资料来源：[README.md:11-15]()
## 故障排除
### 常见问题
| 问题 | 可能原因 | 解决方案 |
|------|----------|----------|
| 语义搜索不工作 | 缺少 `MISTRAL_API_KEY` | 配置 Mistral API 密钥 |
| 加密失败 | `MEMORAEU_SECRET` 或 `MEMORAEU_SALT` 错误 | 检查环境变量配置 |
| 连接超时 | 网络问题或 API 端点错误 | 确认 `MEMORAEU_API_URL` 正确 |
| 无法启动 | uvx 未安装 | 安装 UV：`pip install uv` |
### 验证部署
启动后，可通过以下方式验证零知识加密是否生效：
1. 检查 `recall` 工具返回的记忆内容是否显示 🔒 图标
2. 确认 `forget` 工具能正常删除记忆
3. 验证在未提供 `MEMORAEU_SECRET` 的情况下无法解密数据
资料来源：[memoraeu_mcp/main.py:120-130]()
---
---
## Doramagic 踩坑日志
项目：pquattro/memoraeu-mcp
摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。
## 1. 配置坑 · 可能修改宿主 AI 配置
- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
- 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- 证据：capability.host_targets | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | host_targets=mcp_host, claude
## 2. 能力坑 · 能力判断依赖假设
- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 建议检查：将假设转成下游验证清单。
- 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
- 证据：capability.assumptions | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | README/documentation is current enough for a first validation pass.
## 3. 维护坑 · 维护活跃度未知
- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
- 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
- 证据：evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | last_activity_observed missing
## 4. 安全/权限坑 · 下游验证发现风险项
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：下游已经要求复核，不能在页面中弱化。
- 建议检查：进入安全/权限治理复核队列。
- 防护动作：下游风险存在时必须保持 review/recommendation 降级。
- 证据：downstream_validation.risk_items | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | no_demo; severity=medium
## 5. 安全/权限坑 · 存在评分风险
- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 建议检查：把风险写入边界卡，并确认是否需要人工复核。
- 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
- 证据：risks.scoring_risks | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | no_demo; severity=medium
## 6. 维护坑 · issue/PR 响应质量未知
- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
- 防护动作：issue/PR 响应未知时，必须提示维护风险。
- 证据：evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | issue_or_pr_quality=unknown
## 7. 维护坑 · 发布节奏不明确
- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
- 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
- 证据：evidence.maintainer_signals | github_repo:1215050856 | https://github.com/pquattro/memoraeu-mcp | release_recency=unknown