MCP Memory Cloudflare

Cloudflare Workers上的MCP内存服务器

部署在Cloudflare Workers上的生产就绪模型上下文协议（MCP）内存管理服务器。该服务器提供具有向量嵌入的持久内存存储，用于智能语义搜索，使AI代理能够跨会话维护上下文信息。

特性

• 持久内存存储：采用Cloudflare D1的两层内存系统（短期和长期）
• 向量搜索：使用Cloudflare Vectorize和嵌入进行语义搜索
• MCP集成：为AI代理和助手提供完整的模型上下文协议支持
• REST API：用于直接内存操作的HTTP端点
• 回滚安全：DB首先在向量索引失败时自动回滚写入
• 速率限制：内置速率限制，可配置阈值
• TypeScript：完全类型化的代码库，运行时配置为零

建筑

┌─────────────────────────────────────────────────────────┐
│           Cloudflare Worker (Hono)                      │
├─────────────────────────────────────────────────────────┤
│  ┌──────────────────┐      ┌──────────────────┐        │
│  │  MCP Server      │      │  REST API        │        │
│  │  (MCP Tools)     │      │  (HTTP Routes)   │        │
│  └────────┬─────────┘      └────────┬─────────┘        │
│           │                         │                  │
│           └────────────┬────────────┘                  │
│                        │                               │
│                  ┌─────▼─────┐                         │
│                  │ Vectorize  │                         │
│                  │ DB Module  │                         │
│                  └─────┬─────┘                         │
└─────────────────────────┼───────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        │                 │                 │
    ┌───▼────┐      ┌────▼────┐      ┌────▼─────┐
    │ D1 DB  │      │Vectorize │      │Rate Limit│
    │(Memory)│      │(Embeddings)│     │Namespace │
    └────────┘      └──────────┘      └──────────┘

项目结构

src/
├── index.ts          # Main Hono application & REST endpoints
├── mcp/
│   └── mcp.ts        # MCP server implementation & tools
└── db/
    ├── db.ts         # D1 database interface
    └── vectorize.ts  # Vector embeddings & semantic search

快速开始

先决条件

• Node.js 18+
• 启用Workers、D1和Vectorize的Cloudflare帐户
• wrangler 已安装CLI

安装

npm install

发展

启动本地开发服务器：

npm run dev

服务器将在以下时间运行 http://localhost:8787

生成Cloudflare绑定

将类型与Cloudflare Worker配置同步：

npm run cf-typegen

这产生了 CloudflareBindings 基于您的类型 wrangler.jsonc 配置。

部署到生产

部署到Cloudflare Workers：

npm run deploy

API终点

写存储器

POST /:userId/memory/write

请求正文：

{
  "content": "User information to remember",
  "tier": "long",
  "importance": 0.8,
  "source": "optional source identifier"
}

答复：

{
  "success": true,
  "memoryId": "uuid",
  "content": "..."
}

搜索记忆

GET /:userId/memory/search?query=search+term&limit=10

答复：

{
  "results": [
    {
      "id": "uuid",
      "content": "...",
      "score": 0.95,
      "tier": "long"
    }
  ]
}

更新存储器

PUT /:userId/memory/:memoryId

请求正文：

{
  "content": "Updated content",
  "importance": 0.9
}

删除内存

DELETE /:userId/memory/:memoryId

MCP工具

MCP服务器公开了以下工具：

• memory_write：使用可选元数据存储信息
• memory_search：跨记忆的语义搜索
• memory_update：修改现有内存条目
• memory_delete：删除内存条目
• memory_batch_write：高效地写入多个内存

每个工具都包括使用Zod模式的输入验证和全面的错误处理。

配置

Cloudflare绑定（wrangler.json）

该项目使用以下Cloudflare服务：

• D1数据库: DB 持久存储绑定
• 向量化: VECTORIZE 语义搜索的绑定
• 耐用物品: MCP_OBJECT 用于有状态操作（如果需要）
• 速率限制: RATE_LIMITER 每60秒有100个请求

更新 wrangler.jsonc 自定义这些绑定或阈值。

部署说明

• 已配置生产D1数据库和Vectorize索引
• 环境： production （在wrangler.json中配置）
• 所有绑定都绑定到远程Cloudflare资源
• 默认情况下启用速率限制以防止滥用

环境设置

确保您的Cloudflare帐户具有：

1. ✅ D1数据库已创建： mcp-memory-db
2. ✅ 已创建矢量化索引： mcp-memory-vectorize
3. ✅ 已启用具有适当权限的工作人员
4. ✅ 牧马人认证： wrangler login

故障排除

端口已在使用中？ 默认情况下，开发服务器使用端口8787。指定其他端口：

wrangler dev --ip 0.0.0.0 --port 8788

TypeScript中的类型错误？ 重新生成绑定：

npm run cf-typegen

矢量化查询不返回结果？ 在搜索之前，确保内存已写入Cloudflare Vectorize。检查Cloudflare仪表板中的数据库日志。

开发技巧

• 使用 wrangler tail 从生产Worker流式传输实时日志
• 监控Workers Analytics下Cloudflare仪表板中的指标
• 使用代理库测试实用程序测试MCP工具
• 保持内存层策略的一致性（短期为短暂，长期为持久）