记忆服务 MCP 网关（Memory Service MCP Gateway）

# 记忆服务 MCP 网关（Memory Service MCP Gateway）

**状态：** 🟡 临时设计中  
**优先级：** P0（最高）  
**依赖：** Memory Service SDK、Claude Orchestrator  
**负责人：** 待定

---

## 📋 模块概述

记忆服务 MCP 网关面向 Model Context Protocol（MCP）生态，将内部 Memory Service SDK 的能力以标准化方式暴露给 Claude CLI 及其他兼容 MCP 的客户端。作为系统的“对外边界层”，网关负责统一的记忆读写接口、权限裁剪、安全隔离与可观测能力，既保护核心 SDK 免受外部实现细节影响，也为后续独立开源或单独部署奠定基础。

## 🎯 核心职责

1. **协议适配：** 实现 MCP 服务器协议，将外部 JSON-RPC 请求转换为 Memory Service SDK 调用。
2. **权限裁剪：** 针对外部访问配置白名单接口、字段过滤与租户边界校验，确保数据安全。
3. **请求协调：** 统一处理会话上下文、速率控制与重试策略，保障核心 SDK 稳定运行。
4. **审计追踪：** 记录外部调用轨迹，输出结构化审计日志，支撑合规检查和排障分析。
5. **可观测性：** 集成监控指标、链路追踪与健康检查，便于运维与弹性扩缩。
6. **灵活部署：** 同时支持 CLI 内嵌、本地守护进程及容器化三种运行模式。

## 🏗️ 架构设计

```
┌──────────────────────────────────────────────────────────────┐
│            Claude CLI / MCP 客户端（外部访问）                  │
└───────────────▲───────────────────────────────▲──────────────┘
                │                               │
         MCP JSON-RPC                     MCP 文件同步
                │                               │
┌───────────────┴───────────────────────────────┴────────────────┐
│                 记忆服务 MCP 网关                                │
│                                                                │
│  ┌──────────────────────────────────────────────────┐          │
│  │  网关核心层 / Gateway Core                         │          │
│  │  - MCP 服务适配器                                  │          │
│  │  - 会话路由器                                      │          │
│  │  - 请求校验与速率限制                               │          │
│  └──────────────────────────────────────────────────┘          │
│            │                                 │                 │
│  ┌─────────▼────────────────┐   ┌────────────▼─────────────┐   │
│  │ 能力层 / Capability Layer │   │  可观测层（Observability） │   │
│  │ - 消息接口（Messages）     │   │  - 指标导出（Metrics）     │   │
│  │ - 决策接口（Decisions）    │   │  - 审计日志（Audit）       │   │
│  │ - 会话接口（Sessions）     │   │  - 健康探针（Health）      │   │
│  │ - 检索接口（Search）       │   └────────────▲─────────────┘   │
│  └─────────▲────────────────┘                │                 │
│            │                                 │                 │
│  ┌─────────┴──────────┐    ┌─────────────────┴──────────┐      │
│  │ SDK集成层           │    │ 安全边界层                   │      │
│  │ - Memory SDK 外观层 │    │ - 访问策略                   │     │
│  │ - 配置加载器         │    │ - 凭证校验                  │      │
│  │ - 连接池管理         │    │ - 数据脱敏                  │      │
│  └─────────▲──────────┘    └──────────▲─────────────────┘      │
│            │                          │                        │
│  ┌─────────┴──────────┐               │                        │
│  │ Memory Service SDK │◄──────────────┘                        │
│  └────────────────────┘                                        │
└────────────────────────────────────────────────────────────────┘
          │
          ▼
 PostgreSQL / Redis / 向量数据库（由核心 SDK 统一管理）
```

### 核心子系统说明

| 模块 | 职责概览 | 关键组件 | 关联依赖 |
|------|----------|----------|----------|
| **网关核心层** | 统一处理 MCP 会话、通知与请求生命周期 | MCP 服务适配器、会话路由器、校验与限流器 | `@modelcontextprotocol/sdk`、速率限制器 |
| **能力层** | 以业务能力对外暴露 Memory SDK 接口 | 消息、决策、会话、检索等接口适配器 | Memory Service SDK 模块化能力 |
| **安全边界层** | 构建对外安全边界与访问控制 | 访问策略引擎、凭证校验器、数据脱敏器 | 身份验证服务、策略配置中心 |
| **可观测层** | 实现监控、日志与健康探针 | 指标导出器、审计日志器、健康检查器 | OpenTelemetry、日志管道 |
| **SDK 集成层** | 复用核心 SDK 配置与连接，统一异常与脱敏 | Memory SDK 外观层、配置加载器、连接池管理器 | `@kysion/memory-service`、配置中心 |

### 部署模式对比

| 模式 | 典型场景 | 主要特点 |
|------|----------|----------|
| **CLI 内嵌模式** | 单开发者本地调试 | 通过 `claude --plugins-dir ./packages/memory-service-mcp-gateway/dist` 直接加载，复用本地 `.env` 配置。 |
| **守护进程模式** | 团队共享工作站 | 网关以 Node 服务常驻，Claude CLI 通过 `mcpServers` 远程连接，便于共享缓存和连接池。 |
| **容器化模式** | CI/CD 或生产环境 | 提供 Docker 镜像，结合反向代理与观测插件，支持横向扩缩与统一运维。 |

### 关键数据流

```mermaid
sequenceDiagram
    participant Client as MCP 客户端
    participant Gateway as MCP 网关
    participant SDK as Memory Service SDK
    participant Store as 数据存储（PostgreSQL / Redis / 向量库）

Note over Client,Gateway: 写请求需携带 idempotencyKey（Header 或 Payload）
    Note over Client,Gateway: 消息写入
    Client->>Gateway: memory.messages.record
    Gateway->>SDK: recordMessage()
    SDK->>Store: 写入消息
    Store-->>SDK: 写入结果
    SDK-->>Gateway: 成功响应
    Gateway-->>Client: 结果与审计 ID

Note over Client,Gateway: 会话上下文读取
    Client->>Gateway: memory.sessions.context
    Gateway->>SDK: getContext()
    SDK->>Store: 查询上下文
    Store-->>SDK: 会话数据
    SDK-->>Gateway: 原始数据
    Gateway-->>Client: 脱敏后的上下文

Note over Client,Gateway: 语义检索
    Client->>Gateway: memory.search.semantic
    Gateway->>SDK: semanticSearch()
    SDK->>Store: 访问向量索引
    Store-->>SDK: 检索结果
    SDK-->>Gateway: 排序列表
    Gateway-->>Client: Top-K 结果

Note over Gateway,Store: 审计日志
    Gateway->>Store: 写入审计事件 (auditEvent)
```

> 💡 **提示：** 若在部分 Markdown 查看器中无法渲染 Mermaid，可使用支持 GFM 扩展的阅读器或 VS Code + Mermaid 插件浏览。

## 🔑 配置设计

| 配置项 | 用途说明 | 配置来源 |
|--------|----------|----------|
| `MCP_GATEWAY_MODE` | 运行模式（`embedded` / `daemon` / `server`） | 环境变量 |
| `MEMORY_SDK_CONFIG_PATH` | Memory Service SDK 配置路径 | 环境变量 / CLI 参数 |
| `AUTH_TOKEN` | 外部访问凭证 | 环境变量 / 密钥管理系统 |
| `RATE_LIMIT_QPS` | 单租户速率上限（默认 20 次/秒） | 环境变量 |
| `AUDIT_SINK` | 审计日志输出方式（`stdout` / `file` / `http`） | 环境变量 |
| `TRACE_EXPORTER` | 链路追踪导出目标（OTLP / Jaeger / Console） | 配置文件 |
| `RATE_LIMIT_GLOBAL_QPS` | 全局速率上限（默认 200 次/秒） | 环境变量 |
| `MTLS_CERT_PATH` / `MTLS_KEY_PATH` | 双向 TLS 证书与私钥路径 | 环境变量 / Secret 管理 |
| `GATEWAY_API_TOKEN` | Bearer Token（支持热更新） | Secret 管理 |
| `IDEMPOTENCY_TTL_MS` | 幂等键有效期（默认 10 分钟） | 配置文件 |
| `CAPABILITY_VERSION_MAP` | 能力到语义版本映射（如 `memory.messages@v1`） | 配置文件 |

## 🔌 MCP 能力映射

| MCP 能力标识 | 对应 SDK 模块 | 关键操作 |
|---------------|----------------|----------|
| `memory.messages` | `messages` 模块 | `record`、`list`、`search`、`stats` |
| `memory.decisions` | `decisions` 模块 | `record`、`updateOutcome`、`list` |
| `memory.sessions` | `sessions` 模块 | `create`、`close`、`getContext`、`list` |
| `memory.search` | `search` 模块 | `semantic`、`fullText`、`relatedArtifacts` |
| `memory.attachments` | `codeChanges` 模块 | `recordChange`、`diff`、`rollback` |

所有能力默认开放读操作；写操作需在配置中显式启用并绑定访问策略，避免外部滥用。

## 🧾 能力版本与错误模型

- **语义版本约定：** 每个能力需在配置中声明版本标识，如 `memory.messages@v1`、`memory.sessions@v1beta`，并在返回体 `meta.version` 中回传，便于 CLI 与脚本端显式协商。
- **错误分类：**
  - `1xxx`：参数、鉴权、权限问题 —— 不可重试，需立即提示调用方修正。
  - `2xxx`：限流、配额不足 —— 可以按照 `retryAfterMs` 延迟重试。
  - `3xxx`：下游临时故障 —— 支持幂等重试，配合 `idempotencyKey` 使用。
- **错误结构：** 返回体必须携带 `auditId`、`traceId`、`error.code`、`error.reason`、`retryAfterMs`（可选）与 `details`（上下文信息），以满足审计与自动化处理需求。
- **幂等写入：** 所有写接口应支持 `idempotencyKey`，重复提交时返回首次响应并保证无副作用，TTL 默认 10 分钟。

## 🔐 安全与合规

- **身份鉴别：** 支持 CLI 侧 Token、双向 TLS 证书签名及 OAuth 代理对接。
- **租户隔离：** 基于 SDK 的 Enterprise/Solution 维度校验请求上下文，确保多租户安全。
- **字段脱敏：** 对内部备注、标签等敏感字段执行过滤或哈希处理。
- **速率限制：** 以租户/角色维度控制调用频率，防止异常流量冲击。
- **审计追踪：** 每个请求生成唯一 `auditId`，同步写入审计表和观测系统，实现全链路追踪。

## ⏱️ 限流与背压策略

- **分层限流：**
  1. 全局层（`RATE_LIMIT_GLOBAL_QPS`）控制整体吞吐；
  2. 租户层（`tenant.qps` 配置）保障多租户公平；
  3. 方法层（如 `memory.messages.record`）防止热点接口被滥用；
  4. 会话层（按 `sessionId`）控制单会话突发流量。
- **反馈机制：** 触发限流时返回 `RateLimited` 错误，并携带 `retryAfterMs` 与当前/配额信息；指标 `rate_limit_drops_total` 同步累加。
- **背压与熔断：** 写路径支持熔断器策略，检测到 SDK 延迟异常升高时进入“打开”状态，拒绝新写入并定期半开探测；与 Claude Orchestrator 配合时可自动降级为只读模式。

## 📡 审计与可观测性

- **审计事件 Schema：**
  ```json
  {
    "timestamp": "ISO8601",
    "auditId": "uuid",
    "traceId": "traceparent",
    "tenant": "enterprise-id",
    "subject": "调用主体",
    "action": "memory.messages.record",
    "resource": "session/{id}",
    "latencyMs": 42,
    "outcome": "success" | "error",
    "errorCode": "optional"
  }
  ```
- **关键指标：**
  - `rpc_requests_total{method,code}`：按方法与结果码统计请求量。
  - `rpc_latency_ms_bucket`：请求延迟直方图。
  - `sdk_rtt_ms`：SDK 调用往返时间，辅助识别下游瓶颈。
  - `rate_limit_drops_total`：限流丢弃次数。
  - `audit_sink_lag_seconds`：审计落库/落盘滞后。
- **Tracing 要求：** 贯通 MCP 入站、网关核心、SDK 调用与数据存储操作，统一注入 `traceparent` 与 `tracestate`。
- **日志字段：** 强制包含 `method`、`tenant`、`subject`、`idempotencyKey`、`latencyMs`、`auditId`、`traceId`，支持 JSON 格式输出。

## 🚦 依赖与集成

- **Memory Service SDK：** 主要依赖，通过工作区 `workspace:*` 方式引用，保持版本一致。
- **Claude Orchestrator：** 通过 `claude.config.json` 将网关纳入 CLI 工作流，复用 `sessionId` 与 `traceId`。
- **Notification Service（可选）：** 当出现鉴权失败或速率超限时，可触发通知模块进行预警。