项目简介

memoraeu-mcp 是一个基于 Model Context Protocol (MCP) 的零知识记忆服务器，用于为 AI 助手（如 Claude）提供持久化、加密的记忆能力。该项目使 AI 能够在多个会话之间记住用户偏好、决策、重要事实和技术配置，同时确保数据在传输和存储过程中的隐私安全。资料来源：README.md

核心设计理念

memoraeu-mcp 遵循零知识（Zero-Knowledge）架构，核心原则包括：

• 客户端加密：所有敏感数据在离开用户设备前完成加密，服务器仅存储密文
• 本地嵌入生成：使用 Mistral API 在本地生成文本向量嵌入，确保明文不出设备
• 自动记忆行为：AI 助手根据工具描述自动执行记忆操作，无需用户手动干预

技术架构

系统组件

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

依赖技术栈

资料来源：requirements.txt

部署模式

memoraeu-mcp 支持两种部署模式，适用于不同的安全需求场景：

本地 Stdio 模式

该模式提供完整的零知识保证，适合处理高度敏感信息。

{
  "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 连接到远程服务，适合无本地安装条件的场景。

{
  "mcpServers": {
    "memoraeu": {
      "type": "sse",
      "url": "https://api.memoraeu.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer meu-sk-..."
      }
    }
  }
}

安全提示：远程 SSE 模式下，内容不以零知识方式处理，服务器会看到明文。资料来源：README.md

核心工具与功能

记忆工具集

资料来源：README.md, memoraeu_mcp/main.py

自动记忆行为

memoraeu-mcp 设计为无需手动干预即可工作，行为逻辑如下：

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

数据安全机制

加密流程

graph LR
    A[明文内容] --> B[Mistral API<br/>生成嵌入]
    B --> C[AES-256-GCM<br/>加密内容]
    C --> D[加密内容 + 嵌入<br/>发送到服务器]
    
    style A fill:#ffebee
    style D fill:#e8f5e9

密钥派生与加密

加密后的密文使用 ENCv1: 前缀标识，格式如下：

ENCv1:<base64编码的密文>

资料来源：CHANGELOG.md, memoraeu_mcp/main.py

去重与压缩

在存储前，系统会执行以下预处理：

1. 本地压缩：使用 Mistral API 对明文进行压缩
2. 本地分类：自动建议或验证分类
3. 向量相似度检测：与现有记忆比较相似度

资料来源：README.md, memoraeu_mcp/main.py

API 交互

内部 API 端点

资源注入

系统通过 MCP 资源机制提供上下文注入：

• 资源 URI：memoraeu://context
• 资源名称：Contexte mémoire MemoraEU
• 用途：会话开始时自动加载最近记忆到上下文

资料来源：memoraeu_mcp/main.py

版本历史

资料来源：CHANGELOG.md

应用场景

适用场景

• 个人 AI 助手：Claude Desktop 与用户跨会话共享上下文
• 开发团队知识库：记住技术栈偏好、项目配置、代码规范
• 客户服务会话：AI 记住用户历史偏好和需求

限制与注意事项

• 远程 SSE 模式不具备零知识保证
• 需要有效的 Mistral API Key 才能启用语义搜索
• 语义搜索降级为关键词搜索时会话上下文仍加密

许可证

本项目采用 AGPL v3 开源许可证。资料来源：CHANGELOG.md

概述

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

系统架构

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

前置条件

在开始之前，请确保满足以下要求：

安装方式

方式一：远程 SSE 模式（即装即用）

适用于不想安装本地服务的用户，通过 SSE 协议直接连接远程服务器。

1. 在客户端配置中添加以下 JSON：

{
  "mcpServers": {
    "memoraeu": {
      "type": "sse",
      "url": "https://api.memoraeu.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer meu-sk-YOUR-API-KEY"
      }
    }
  }
}

1. 支持的客户端：Claude.ai Web、Cursor、Windsurf 等支持 MCP 的应用

资料来源：README.md:45-55

方式二：本地 stdio 模式（完整零知识保证）

适用于需要最高安全级别的用户，所有处理均在本地完成。

#### 步骤 1：获取 API 密钥

1. 访问 app.memoraeu.com 创建账户
2. 进入 设置 → API 密钥 → 创建新密钥 → 复制 MEMORAEU_API_KEY
3. 进入 设置 → 加密密钥 → 复制 MEMORAEU_SALT
4. 在 console.mistral.ai 获取 MISTRAL_API_KEY

资料来源：README.md:35-43

#### 步骤 2：配置环境变量

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 客户端

{
  "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_SECRET 和 MEMORAEU_SALT 的组合用于本地生成加密密钥。服务器仅存储密文，无法解密内容。

资料来源：README.md:35-43

可用工具

资料来源：README.md:56-68

remember_fact 工具参数

{
  "subject": "string",      // 实体名称
  "predicate": "string",    // 属性名称
  "object": "string",       // 属性值
  "scope": "private|org",   // 作用域，默认 private
  "valid_from": "YYYY-MM-DD" // 生效日期
}

资料来源：server.py:1-50

recall 工具参数

{
  "query": "string",        // 语义搜索查询
  "limit": 3,               // 结果数量限制，默认 3
  "category": "string"       // 可选，按分类筛选
}

资料来源：memoraeu_mcp/main.py:1-30

自动行为

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

去重与压缩

在存储记忆前，系统会执行以下处理流程：

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[上传密文 + 向量]

资料来源：README.md:70-80

安全模型

零知识保证

┌─────────────────────────────────────────────────────────────┐
│                        数据流加密                            │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  明文内容                                                    │
│     ↓                                                        │
│  Mistral Embed (本地计算向量)                                │
│     ↓                                                        │
│  AES-256-GCM 加密 (PBKDF2-HMAC-SHA256 派生密钥)             │
│     ↓                                                        │
│  [ENCv1:盐值:IV:密文:Tag] 格式                               │
│     ↓                                                        │
│  发送给 MemoraEU API                                         │
│                                                             │
│  服务器存储：密文 + 向量（两者均无法单独解密原始内容）          │
│                                                             │
└─────────────────────────────────────────────────────────────┘

两种模式的区别

警告：远程 SSE 模式下，传输内容未经端到端加密。建议仅在 stdio 本地模式下使用完整零知识保证。

资料来源：README.md:10-15

依赖项

资料来源：requirements.txt:1-6

版本历史

资料来源：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 了解更多高级配置
• 查看 CHANGELOG 了解版本更新
• 配置您的 AI 客户端以开始使用自动记忆功能

概述

MemoraEU MCP 是一个基于 Model Context Protocol (MCP) 的零知识记忆服务架构。该系统作为 MCP 服务器运行，为 AI 助手（如 Claude）提供持久化记忆功能，同时保证用户数据的隐私性和零知识加密特性。 资料来源：README.md:1

系统采用客户端-服务端架构，支持本地安装（stdio 模式）和远程连接（SSE 模式）两种部署方式。核心设计理念是：在数据离开用户设备之前完成所有可能的处理和加密操作，确保服务端永远无法访问明文内容。 资料来源：README.md:40

概述

MemoraEU-MCP 的加密系统是一个本地优先的零知识加密实现，确保用户数据在传输和存储的整个过程中始终处于加密状态。服务器仅存储加密后的数据密文和向量嵌入，无法还原原始明文内容。

核心加密流程遵循以下原则：

• 端到端加密：内容在本地设备加密后发送，服务器永远不接触明文
• 前向安全：使用 PBKDF2 从用户密码派生出加密密钥
• 语义可搜索：在加密前通过 Mistral Embed 生成向量嵌入，实现零知识语义搜索

资料来源：README.md

架构设计

高层数据流

graph TD
    subgraph 本地客户端
        A[用户输入] --> B[内容压缩]
        B --> C[Mistral Embed<br/>生成向量]
        C --> D[AES-256-GCM<br/>加密]
        D --> E[密文 + Embedding]
    end
    
    subgraph 传输层
        E --> F[HTTPS/TLS]
    end
    
    subgraph 服务器端
        F --> G[(Opaque Blob<br/>存储)]
        G --> H[语义搜索<br/>向量匹配]
    end
    
    subgraph 检索解密
        G --> I[密文获取]
        I --> J[AES-256-GCM<br/>解密]
        J --> K[明文输出]
    end

密钥派生流程

graph LR
    A[MEMORAEU_SECRET<br/>用户密码] --> D[PBKDF2-HMAC-SHA256]
    B[MEMORAEU_SALT<br/>服务端盐值] --> D
    C[210,000<br/>迭代次数] --> D
    D --> E[加密密钥<br/>Derived Key]
    E --> F[AES-256-GCM<br/>加解密]

加密算法详情

算法参数

资料来源：CHANGELOG.md

密文格式

加密后的数据包含以下结构：

ENCv1:<base64(nonce || ciphertext || tag)>

• nonce：随机生成的初始化向量（12字节）
• ciphertext：AES-256-GCM 加密后的密文
• tag：GCM 认证标签（16字节）

资料来源：memoraeu_mcp/main.py

核心模块

crypto.py 模块

该模块负责所有加密/解密操作的实现：

资料来源：memoraeu_mcp/crypto.py

环境变量配置

资料来源：README.md

工作流程

存储记忆流程

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<br/>{content: ENCv1:..., embedding: [...]}
    S-->>MCP: memory_id
    MCP-->>U: ✅ 已记住

检索记忆流程

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<br/>{query: xxx}
    S-->>MCP: [{content: ENCv1:..., score: 0.95}]
    MCP->>C: decrypt_content(ENCv1:...)
    C-->>MCP: 明文内容
    MCP-->>U: 记忆列表

零知识保证

服务器可见内容

语义搜索原理

1. 本地 Embedding 生成：使用 MISTRAL_API_KEY 在本地调用 Mistral Embed API，生成明文内容的向量表示
2. 加密存储：将 Embedding 与加密后的内容一起发送到服务器
3. 向量匹配：服务器基于 Embedding 进行语义相似度计算
4. 本地解密：匹配结果返回后，在本地使用 decrypt_content() 解密

资料来源：README.md

安全特性

认证加密（AES-GCM）

使用 Galois/Counter Mode (GCM) 模式提供：

• 机密性：使用 AES-256 位密钥加密
• 完整性：GCM 标签检测密文篡改
• 认证：防止选择密文攻击

密钥派生加固

PBKDF2 参数配置：

盐值管理

• 每个用户分配唯一的 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

版本演进

资料来源：CHANGELOG.md

最佳实践

1. 使用强密码：MEMORAEU_SECRET 应使用高熵密码
2. 保护盐值：虽然盐值可公开，但应与密码分开存储
3. 定期轮换：未来版本应支持密钥轮换机制
4. 本地 Mistral 密钥：确保 MISTRAL_API_KEY 不泄露，确保端到端零知识

概述

MemoraEU MCP 是一个基于 Model Context Protocol (MCP) 的记忆服务器实现，旨在为 AI 助手提供持久化的上下文记忆能力。该项目允许 Claude 等大语言模型自动记忆用户偏好、决策和重要信息，并在后续对话中自动检索相关内容。

核心功能包括：

• 自动记忆：AI 自动检测并存储重要信息，无需用户手动触发
• 零知识加密：所有数据在本地加密后再发送至服务器
• 语义搜索：支持基于向量相似度的语义检索
• 结构化事实：存储带有时间有效性的三元组事实
• 自动去重：防止存储重复或相似的记忆

资料来源：README.md

架构概览

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["向量数据库<br/>存储 embedding"]
        H --> J["加密Blob存储<br/>存储密文"]
    end
    
    D --> K["压缩模块"]
    D --> L["分类模块"]
    D --> M["去重检测模块"]

资料来源：memoraeu_mcp/main.py

工具分类

MCP 服务器提供 8 个核心工具，分为三大类别：

资料来源：memoraeu_mcp/main.py:70-170

记忆工具详解

remember

remember 是核心的记忆存储工具，设计为 AI 自动调用，无需用户请求。

#### 功能描述

自动检测并存储用户表达的重要信息，包括偏好、决策、传记事实和技术配置。

#### 参数定义

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "要记忆的内容"
    },
    "category": {
      "type": "string",
      "description": "分类名称（可选，自动推断）"
    },
    "tags": {
      "type": "array",
      "items": {"type": "string"},
      "description": "标签数组（可选）"
    }
  },
  "required": ["content"]
}

#### 处理流程

graph TD
    A["remember 调用"] --> B["本地压缩内容"]
    B --> C["自动分类（如未指定）"]
    C --> D["生成/获取 Embedding"]
    D --> E{"去重检测"}
    E -."≥94% 相似<br/>跳过存储"--> F["返回去重警告"]
    E -."<94% 相似<br/>继续存储"--> G["本地加密"]
    G --> H["POST /memories"]
    H --> I["返回记忆ID"]

#### 关键特性

资料来源：memoraeu_mcp/main.py:120-160

recall

recall 是语义搜索工具，用于检索已存储的记忆。

#### 功能描述

在首次用户消息时自动调用，使用语义理解而非关键词匹配进行搜索。

#### 参数定义

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "搜索查询（使用消息主题）"
    },
    "limit": {
      "type": "integer",
      "default": 3,
      "description": "返回结果数量上限"
    },
    "category": {
      "type": "string",
      "description": "按分类过滤（可选）"
    }
  },
  "required": ["query"]
}

#### 特殊行为

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

forget

删除指定 ID 的记忆。

#### 参数定义

#### 返回值

资料来源：memoraeu_mcp/main.py:200-210

list_memories

列出最近的记忆列表。

#### 参数定义

#### 返回格式

📋 N mémoire(s) :

• [分类名称] 内容预览... (ID: xxxxxxxx)
• [分类名称] 内容预览... (ID: xxxxxxxx)

资料来源：memoraeu_mcp/main.py:210-230

list_categories

返回所有已存在的分类，按使用频率排序。

#### 参数定义

无参数。

#### 返回格式

📂 Catégories :

• 工作偏好 (15)
• 技术配置 (8)
• 个人信息 (3)

资料来源：memoraeu_mcp/main.py:230-245

事实工具详解

结构化事实存储采用主语-谓语-宾语（SPO）三元组模型，支持时间有效性。

remember_fact

存储结构化事实，支持时间范围定义。

#### 数据模型

graph LR
    S["subject<br/>主语"] --> P["predicate<br/>谓语"]
    P --> O["object<br/>宾语"]
    
    S -.->|"valid_from<br/>开始时间"| T["时间范围"]
    P -.->|"valid_to<br/>结束时间"| T

#### 参数定义

#### 返回格式

✅ Fait mémorisé 🔒 (remplace xxxxxxxx)
  主语 → 谓语
  Depuis: 2024-01-01 | ID: xxxxxxxx

#### 过期替换机制

当存储与已有事实相同主语和谓语的新事实时，系统自动：

1. 将旧事实标记为 superseded
2. 新事实的 supersedes 字段记录旧事实 ID

资料来源：server.py:150-180

recall_facts

检索指定主语的结构化事实。

#### 参数定义

#### 返回格式

📊 N fait(s) pour '主语' :

• 谓语: 宾语值
  [2024-01-01 → 2024-06-15 (expiré)] | ID: xxxxxxxx
• 谓语: 宾语值
  [2024-06-15 → aujourd'hui] | ID: xxxxxxxx

资料来源：server.py:180-210

invalidate_fact

标记事实为过期（不再真实）。

#### 参数定义

#### 使用场景

• 用户更正之前提供的信息
• 临时状态变更（如 "出差中" → 恢复）
• 计划性失效（如活动结束）

资料来源：server.py:210-220

自动记忆行为

系统设计了完整的自动记忆工作流，AI 模型根据工具描述自动执行。

工作流程图

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: 简洁确认

自动触发规则

不应记忆的内容

• 日常闲聊（天气、问候）
• 临时性信息（今日菜单）
• 一次性计算结果
• 用户明确要求遗忘的内容

系统提示词注入

首次调用 recall 时，系统自动注入完整的行为规范：

## 记忆范围
- 用户偏好和习惯
- 重要决策和结论
- 反复出现的信息或约束

## 自动记忆原则
当用户表达以下内容时，立即调用 remember 工具：
- 偏好、决策、传记事实、技术配置
- 或持久性约束

## 规则
- 不记忆一般信息或临时性内容
- 用户要求"遗忘"时使用 forget
- 记忆确认仅需一行
- 优化 tokens：recall 默认限制 3 条结果

资料来源：memoraeu_mcp/main.py:30-60

去重与压缩机制

去重检测流程

graph TD
    A["新记忆内容"] --> B["计算向量 Embedding"]
    B --> C["与所有现有记忆比较"]
    C --> D{"相似度阈值"}
    
    D -.->|">94%"| E["跳过存储<br/>返回去重警告"]
    D -.->|"75%-94%"| F["存储但打印警告"]
    D -.->|"<75%"| G["正常存储"]
    
    E --> H["⚠️ Doublon détecté (N% similaire)"]
    H --> I["显示相似记忆预览"]

相似度阈值表

本地压缩

在加密前，内容会经过本地压缩处理：

content = await compress_locally(raw_content)

压缩目的：

1. 减少加密和传输的数据量
2. 降低 Mistral API 调用成本
3. 保持记忆简洁

资料来源：memoraeu_mcp/main.py:130-140

配置与部署

stdio 模式（推荐）

适用于需要完整零知识保证的场景。

#### 配置示例

{
  "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 远程模式

适用于快速连接，但不具备零知识保证。

{
  "mcpServers": {
    "memoraeu": {
      "type": "sse",
      "url": "https://api.memoraeu.com/mcp/sse",
      "headers": {
        "Authorization": "Bearer meu-sk-..."
      }
    }
  }
}

环境变量说明

资料来源：README.md

安全模型

零知识加密架构

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["服务器存储<br/>（无法解密）"]
    end
    
    subgraph "搜索"
        H["明文"] --> I["Mistral Embedding"]
        I --> J["向量搜索"]
        G --> J
    end

密钥派生参数

Mistral Embedding 的必要性

由于向量搜索需要比较语义相似度，embedding 必须从明文生成：

1. 客户端调用 Mistral API 获取明文 embedding
2. 内容加密后与 embedding 一起发送
3. 服务器仅存储加密 blob 和向量
4. 服务器无法反推明文内容

无 MISTRAL_API_KEY 时：搜索降级为服务器端关键词匹配，不影响加密功能。

资料来源：CHANGELOG.md

依赖项

资料来源：requirements.txt

资源与提示词

资源

提示词

调用方式：

@app.list_prompts()
async def list_prompts() -> list[Prompt]:
    return [
        Prompt(
            name="memoraeu_system",
            description="系统记忆行为规范",
            arguments=[]
        )
    ]

资料来源：memoraeu_mcp/main.py:60-80

概述

memoraeu-mcp 实现了客户端去重与压缩机制，在数据加密前对内容进行处理。这一设计确保了：

1. 存储效率 — 避免存储重复或冗余的记忆
2. 零知识保证 — 所有处理均在加密前本地完成，服务器无法访问明文

资料来源：README.md:1-50

工作流程

整体数据流

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 工具调用时，系统按以下顺序执行：

资料来源：memoraeu_mcp/main.py:150-200

压缩机制

压缩阈值

系统使用 COMPRESSION_THRESHOLD 变量控制压缩触发条件。当内容长度超过此阈值时才进行压缩处理。

if len(content) <= COMPRESSION_THRESHOLD:
    return content

资料来源：memoraeu_mcp/main.py:1-50

压缩实现

压缩功能由 compress_locally() 函数实现：

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

压缩特点

分类建议机制

本地分类函数

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

分类处理流程

graph TD
    A[新内容] --> B[获取已有分类列表]
    B --> C[调用 Mistral Chat]
    C --> D{返回有效分类?}
    D -->|是| E[规范化分类名]
    D -->|否| F[返回默认分类: personnel]
    E --> G[限制长度 30 字符]
    G --> H[返回分类]

分类默认值

去重检测机制

重复检测阈值

资料来源：README.md:60-80

去重实现

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

零知识去重原理

graph LR
    A[明文内容] --> B[Mistral Embed]
    B --> C[Embedding 向量]
    C --> D[本地存储加密]
    C --> E[发送给服务器]
    
    F[服务器] --> G[无法解密内容]
    G --> H[但可比较向量相似度]
    E --> H

去重机制利用了预计算的 Embedding 向量进行相似度计算，这些向量在本地生成后立即用于重复检测，服务器仅存储加密后的向量数据。

加密集成

加密流程

在去重和压缩完成后，系统对内容进行加密：

# 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

加密参数

环境配置

必需环境变量

Mistral API 作用

为什么 MCP 需要 Mistral 密钥？

零知识意味着服务器永远看不到明文。为了支持语义搜索，Embedding 必须在加密前计算——在你的机器上。MCP 直接用明文调用 Mistral，获取向量后加密内容，然后发送两者到服务器。

资料来源：README.md:40-50

完整存储决策流程

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%) 正式启用
• 本地压缩和分类功能上线

相关依赖

资料来源：requirements.txt:1-10

概述

MemoraEU MCP 是一个零知识（Zero-Knowledge）记忆系统，其核心安全机制建立在密钥管理与加密架构之上。本页详细说明 MCP 服务器的配置方式、环境变量的作用、密钥派生流程，以及不同部署模式下的安全考量。

资料来源：README.md

概述

memoraeu-mcp 支持两种部署模式：远程 SSE（Server-Sent Events）模式和本地 stdio 模式。这两种模式在安全性和功能上存在显著差异，开发者可根据实际需求选择合适的部署方式。

核心区别：远程 SSE 模式下，服务器会处理明文数据，无法提供零知识加密保证；本地 stdio 模式则能在用户本地机器上完成所有加密操作，实现完整的零知识保护。

资料来源：README.md:1-10

部署模式对比

资料来源：README.md:11-15

环境变量配置

memoraeu-mcp 使用五个关键环境变量，这些变量服务于三个不同的用途，彼此不可互换：

资料来源：README.md:32-45

本地 stdio 模式部署

本地 stdio 模式是实现零知识加密的关键部署方式，所有敏感操作都在本地完成。

工作原理

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

1. 获取加密密钥：在仪表板的"加密密钥"页面获取唯一的 MEMORAEU_SALT

1. 设置用户密码：使用您的 MemoraEU 账户密码作为 MEMORAEU_SECRET

1. 获取 Mistral API 密钥：访问 console.mistral.ai 获取 MISTRAL_API_KEY

1. 编辑 Claude Desktop 配置：在 claude_desktop_config.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 包管理器）直接运行，无需手动安装：

uvx memoraeu-mcp

所有环境变量需要在启动前设置好，或者通过 .env 文件管理。

资料来源：README.md:22-25

零知识加密机制

memoraeu-mcp 采用多层加密策略确保数据安全：

加密流程

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 派生密钥<br/>(100k 迭代)
    MCP->>MCP: AES-256-GCM 加密内容
    MCP->>Server: 发送加密内容 + 加密嵌入
    Server-->>用户: 存储不透明的加密 blob

密钥派生参数

资料来源：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 依赖

资料来源：requirements.txt:1-5

运行时环境

• Python: 3.9+
• 包管理器: UV（推荐）或 pip
• 网络: 需要访问 api.memoraeu.com 和 api.mistral.ai

部署检查清单

安全建议

1. 使用强密码：作为 MEMORAEU_SECRET，使用高强度密码以增强密钥派生质量

1. 保护盐值：MEMORAEU_SALT 与账户绑定，不应共享

1. Mistral API 密钥安全：该密钥仅在本地使用，应妥善保管

1. 定期轮换：定期更新 API 密钥和加密盐值

1. 网络传输：即使使用 HTTPS，远程 SSE 模式下的数据传输仍为明文，仅加密存储

资料来源：README.md:11-15

故障排除

常见问题

验证部署

启动后，可通过以下方式验证零知识加密是否生效：

1. 检查 recall 工具返回的记忆内容是否显示 🔒 图标
2. 确认 forget 工具能正常删除记忆
3. 验证在未提供 MEMORAEU_SECRET 的情况下无法解密数据

资料来源：memoraeu_mcp/main.py:120-130

Pitfall Log / 踩坑日志

项目：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