MCP Memory Server

Long-term memory for AI coding agents — works with Claude Code, ChatGPT, Cursor, Gemini CLI, VS Code Copilot, Windsurf, Claude Desktop, Codex CLI. Deploy once to Cloudflare Workers (free tier), use everywhere.

讓你的 AI coding agent 擁有跨 session 的長期記憶。一次部署，所有 MCP 平台通用。

解決什麼問題

AI coding agent（Claude Code、ChatGPT、Cursor 等）每次對話都從零開始。你上次的架構決策、踩過的坑、偏好的工作方式 — 全部忘光。

這個 server 讓你的 AI agent 可以：

• 記住 — AI 主動判斷並儲存對話中的重要發現、決策、偏好

• 回想 — 用自然語言搜尋，不是關鍵字比對

• 整理 — 自動歸檔過期記憶、去重、合併相似內容

• 保護 — 重要知識標記為「絕對真理」，永遠不被自動清理

使用前 vs 使用後

Related MCP server: ContextFS

為什麼用 Cloudflare

部署（三步）

前置條件： Cloudflare 帳號（免費）+ Node.js 18+ + Wrangler CLI（npm install -g wrangler）

# 1. 登入 Cloudflare（只需做一次）
wrangler login

# 2. Clone
git clone https://github.com/beach55607-max/mcp-memory-server.git
cd mcp-memory-server

# 3. 自動設定 + 部署
bash setup.sh

setup.sh 會自動完成：安裝依賴 → 建立 D1/Vectorize/KV → 產生 wrangler.toml → 設定 API 密鑰 → 執行 migration → 部署。

部署完成後你會看到：

你的 server 已上線：https://mcp-memory-server.你的子網域.workers.dev
MCP 端點：https://mcp-memory-server.你的子網域.workers.dev/mcp

部署後必做

設定 ALLOWED_ORIGINS，指定哪些網站可以連你的 server：

# 在 Cloudflare Dashboard → Workers → 你的 Worker → Settings → Variables
# 或直接改 wrangler.toml 後重新部署
ALLOWED_ORIGINS = "https://claude.ai,https://chatgpt.com"

記憶怎麼存入

主要機制是 AI 主動存（需在 system prompt 設定觸發條件）。不是「裝好就自動存」— AI 需要被告知什麼時候該存。

詳細四層架構：

Supersede 保護：source=auto-extract 的記憶不可取代其他來源的記憶，確保弱 AI 判斷不會覆蓋強 AI 或人類的決定。

連接你的 AI 客戶端

以下範例中，請把 你的子網域 替換成你的 Cloudflare Workers 子網域，你的密碼 替換成你在 setup.sh 設定的 API_SECRET。

Claude.ai（Web + 手機）

重要： 先在網頁版設定 → 手機自動可用。

1. claude.ai → Settings → Integrations

2. 新增 remote MCP server

3. 貼上 https://mcp-memory-server.你的子網域.workers.dev/mcp

4. 打開手機 Claude — memory tools 已可使用

ChatGPT（Web + 手機）

重要： 先在網頁版開啟 Developer Mode → 手機自動可用。

1. chatgpt.com → Settings → Connectors → Advanced

2. 開啟 Developer Mode

3. Connectors → 新增 MCP server → 貼上 https://mcp-memory-server.你的子網域.workers.dev/mcp

4. 打開手機 ChatGPT — memory tools 已可使用

需要 Pro / Plus / Business / Enterprise / Education 方案。

Claude Code（CLI）

方式 A：遠端連接（Streamable HTTP） — 直接連你的 Worker：

// ~/.claude.json 或 .claude/settings.json
{
  "mcpServers": {
    "memory": {
      "type": "url",
      "url": "https://mcp-memory-server.你的子網域.workers.dev/mcp"
    }
  }
}

方式 B：stdio proxy — 透過本地 proxy 轉發到 REST API：

CLI 一行加入（注意 -e 和 -s 要在 name 之前，command 用 -- 隔開）：

claude mcp add \
  -e MCP_MEMORY_API=https://mcp-memory-server.你的子網域.workers.dev \
  -e MCP_MEMORY_API_KEY=你的密碼 \
  -s user \
  memory -- node /path/to/mcp-memory-server/src/mcp-stdio-proxy.mjs

或手動編輯 ~/.claude.json：

{
  "mcpServers": {
    "memory": {
      "command": "node",
      "args": ["/path/to/mcp-memory-server/src/mcp-stdio-proxy.mjs"],
      "env": {
        "MCP_MEMORY_API": "https://mcp-memory-server.你的子網域.workers.dev",
        "MCP_MEMORY_API_KEY": "你的密碼"
      }
    }
  }
}

Codex CLI

codex mcp add memory \
  --env MCP_MEMORY_API=https://mcp-memory-server.你的子網域.workers.dev \
  --env MCP_MEMORY_API_KEY=你的密碼 \
  -- node /path/to/mcp-memory-server/src/mcp-stdio-proxy.mjs

Gemini CLI

~/.gemini/settings.json：

{
  "mcpServers": {
    "memory": {
      "uri": "https://mcp-memory-server.你的子網域.workers.dev/mcp"
    }
  }
}

Cursor

Settings → MCP → Transport: streamable-http → URL: https://mcp-memory-server.你的子網域.workers.dev/mcp

或 .cursor/mcp.json：

{
  "mcpServers": {
    "memory": {
      "transport": "streamable-http",
      "url": "https://mcp-memory-server.你的子網域.workers.dev/mcp"
    }
  }
}

VS Code + GitHub Copilot

.vscode/mcp.json：

{
  "servers": {
    "memory": {
      "type": "http",
      "url": "https://mcp-memory-server.你的子網域.workers.dev/mcp"
    }
  }
}

需要 VS Code 1.99+ 搭配 GitHub Copilot extension。

Windsurf / JetBrains

Settings → MCP → 加入 https://mcp-memory-server.你的子網域.workers.dev/mcp。

其他 stdio-only 客戶端

MCP_MEMORY_API=https://mcp-memory-server.你的子網域.workers.dev \
MCP_MEMORY_API_KEY=你的密碼 \
  node src/mcp-stdio-proxy.mjs

使用指南

日常使用

連上之後，你的 AI agent 會多出 7 個工具。你不需要手動呼叫 — 大多數場景 AI 會自己判斷何時使用。

對話開始時（自動）： Agent 呼叫 memory_auto_inject 載入相關記憶。「絕對真理」一定會被載入。

對話中（按需）：

• 你告訴 agent「記住這個」→ agent 呼叫 memory_save

• 你問「上次那個問題怎麼解的」→ agent 呼叫 memory_search

• 你覺得某條記憶很重要永遠不能忘 → 告訴 agent「promote 這條」→ memory_promote

對話結束時（最佳做法）： Agent 主動呼叫 memory_save 存入本次重要發現。memory_extract 仍可手動使用，但主要機制是 AI 主動存，不依賴 session 結束時的自動萃取。

背景自動（每日 UTC 03:00）： Cron 自動整理：90 天沒確認的歸檔、重複的去除、AI 判斷不相關的清掉、相似的合併。

記憶類型怎麼選

絕對真理

memory_promote 可以把一條記憶升級為「絕對真理」（confidence=1.0）。效果：

• 每次對話開始一定會被載入（不受數量限制）

• 不會被自動清理（cron 衰減、去重、合併全跳過）

• 衝突時永遠贏

• 只有 active 狀態的記憶才能被 promote

適合用在：公司規定、團隊約定、永遠不能搞錯的事實。

7 個 MCP 工具詳細

* = 必填，? = 選填

架構

客戶端（Claude / ChatGPT / Cursor / ...）
  │
  ├── MCP Streamable HTTP ──→ /mcp (OAuth 2.1)
  │
  └── REST API ──────────────→ /api/* (API_SECRET)
                                 │
                    ┌────────────┼────────────┐
                    │            │            │
                ┌───┴───┐  ┌────┴────┐  ┌────┴────┐
                │  D1   │  │Vectorize│  │Workers AI│
                │(SQLite)│  │(向量)   │  │bge-m3   │
                └───────┘  └─────────┘  │llama-3.1│
                                        └─────────┘
                    │
                ┌───┴───┐
                │  KV   │
                │(OAuth)│
                └───────┘

Cron（每日 UTC 03:00）──→ 衰減 → 去重 → AI 判斷 → 自動合併

Cloudflare 資源用量（免費額度）

AI 功能超額時 graceful 降級 — 跳過摘要/判斷，不影響核心 CRUD。

安全性

重要提醒：

• API_SECRET 必須設定（wrangler secret put API_SECRET）

• DEV_MODE 永遠不要在生產環境開啟

• 建議加 Cloudflare Rate Limiting

• 詳見 SECURITY.md

環境變數

核心

AI 功能

Cron 調參（免部署）

密鑰

REST API

工具腳本

# 批次匯入知識庫
MCP_MEMORY_API=https://mcp-memory-server.你的子網域.workers.dev \
MCP_MEMORY_API_KEY=你的密碼 \
  node scripts/batch-import.mjs

# Embedding 品質驗證
CLOUDFLARE_ACCOUNT_ID=xxx CLOUDFLARE_API_TOKEN=xxx \
  node scripts/eval-embedding.mjs

# Structural test（38 項檢查）
npm run test:check

已知限制

Codex CLI exec 模式下 MCP tool call 會失敗

影響版本：codex-cli 0.117.0（2026-04-05 確認）

Codex CLI 的非互動模式（codex exec --full-auto、codex:codex-rescue）對 MCP tool call 強制要求 user approval。非互動模式下無人批准 → 自動 cancel，顯示 user cancelled MCP tool call。

這不是 MCP Memory Server 的問題，是 Codex CLI 的已知限制。

Workaround：

• 互動模式下手動批准 MCP 呼叫

• 在有 workspace instructions（AGENTS.md / CLAUDE.md）的環境中，Codex 互動模式會自己判斷何時存記憶

• codex exec --dangerously-bypass-approvals-and-sandbox 可繞過，但風險高，不建議日常使用

更新紀錄

相關專案

• ai-dev-toolkit — AI 工程治理 skill（boundary-first、spec planning、adversarial review）

English Summary

What Is This

A semantic memory server for AI coding agents. Deploy once to Cloudflare Workers (free tier), use from any MCP-compatible client. Your AI remembers across sessions, platforms, and projects.

The problem: AI agents start fresh every conversation. Architecture decisions, debugging lessons, your preferences — all forgotten.

The solution: This server gives your AI agent persistent semantic memory with automatic governance: decay stale memories, deduplicate, AI-judge relevance, consolidate similar entries.

Why Cloudflare

Deploy (3 steps)

wrangler login                    # one-time Cloudflare auth
git clone https://github.com/beach55607-max/mcp-memory-server.git && cd mcp-memory-server
bash setup.sh                     # auto: install → create resources → config → migrate → deploy

After deploy, set ALLOWED_ORIGINS to specify which websites can access your server:

ALLOWED_ORIGINS = "https://claude.ai,https://chatgpt.com"

7 MCP Tools

* = required, ? = optional

How Memories Are Saved

The primary mechanism is AI proactive save (requires system prompt configuration). It's not "install and it auto-saves" — AI needs to be told when to save.

4-layer architecture:

Supersede protection: memories with source=auto-extract cannot supersede memories from other sources. This ensures weak AI judgments don't overwrite decisions made by strong AI or humans.

Connect Your AI Client

In the examples below, replace YOUR_SUBDOMAIN with your Cloudflare Workers subdomain, and your-secret with the API_SECRET you set during setup.

Claude.ai (Web + Mobile)

Important: Set up on the web version first. Once configured, it automatically works on the iOS / Android app.

1. Go to claude.ai → Settings → Integrations

2. Add a new remote MCP server

3. Enter: https://mcp-memory-server.YOUR_SUBDOMAIN.workers.dev/mcp

4. Open Claude on your phone — memory tools are now available

ChatGPT (Web + Mobile)

Important: Enable Developer Mode on the web version first. Once configured, it works on the mobile app.

1. Go to chatgpt.com → Settings → Connectors → Advanced

2. Toggle on Developer Mode

3. Go to Connectors → Add MCP server → Enter: https://mcp-memory-server.YOUR_SUBDOMAIN.workers.dev/mcp

4. Open ChatGPT on your phone — memory tools are now available

Requires Pro, Plus, Business, Enterprise, or Education plan.

Claude Code (CLI)

Option A: Remote (Streamable HTTP) — connect directly to your Worker:

// ~/.claude.json or .claude/settings.json
{
  "mcpServers": {
    "memory": {
      "type": "url",
      "url": "https://mcp-memory-server.YOUR_SUBDOMAIN.workers.dev/mcp"
    }
  }
}

Option B: stdio proxy — local proxy forwarding to REST API:

claude mcp add \
  -e MCP_MEMORY_API=https://mcp-memory-server.YOUR_SUBDOMAIN.workers.dev \
  -e MCP_MEMORY_API_KEY=your-secret \
  -s user \
  memory -- node /path/to/mcp-memory-server/src/mcp-stdio-proxy.mjs

Note: -e and -s must come before the name, command is after --.

Codex CLI

codex mcp add memory \
  --env MCP_MEMORY_API=https://mcp-memory-server.YOUR_SUBDOMAIN.workers.dev \
  --env MCP_MEMORY_API_KEY=your-secret \
  -- node /path/to/mcp-memory-server/src/mcp-stdio-proxy.mjs

Gemini CLI

~/.gemini/settings.json:

{
  "mcpServers": {
    "memory": {
      "uri": "https://mcp-memory-server.YOUR_SUBDOMAIN.workers.dev/mcp"
    }
  }
}

Cursor

Settings → MCP → Transport: streamable-http → URL: https://mcp-memory-server.YOUR_SUBDOMAIN.workers.dev/mcp

VS Code + GitHub Copilot

.vscode/mcp.json:

{
  "servers": {
    "memory": {
      "type": "http",
      "url": "https://mcp-memory-server.YOUR_SUBDOMAIN.workers.dev/mcp"
    }
  }
}

Requires VS Code 1.99+ with GitHub Copilot extension.

Windsurf / JetBrains

Settings → MCP → Add https://mcp-memory-server.YOUR_SUBDOMAIN.workers.dev/mcp.

Other stdio-only clients

MCP_MEMORY_API=https://mcp-memory-server.YOUR_SUBDOMAIN.workers.dev \
MCP_MEMORY_API_KEY=your-secret \
  node src/mcp-stdio-proxy.mjs

Security

• OAuth 2.1 on MCP endpoint (PKCE S256, scope whitelist: memory:read, memory:write)

• API_SECRET required for REST API in production (wrangler secret put API_SECRET)

• CORS origin allowlist (no wildcard *). Configure ALLOWED_ORIGINS

• Input sanitization: strips script/iframe/object/embed/event handlers/javascript: URI

• DEV_MODE: never enable in production (bypasses API_SECRET, allows localhost CORS)

• Rate limiting: configure Cloudflare Rate Limiting Rules after deployment

• See SECURITY.md

Scripts

# Batch import knowledge files
MCP_MEMORY_API=https://mcp-memory-server.YOUR_SUBDOMAIN.workers.dev \
MCP_MEMORY_API_KEY=your-secret \
  node scripts/batch-import.mjs

# Embedding quality evaluation
CLOUDFLARE_ACCOUNT_ID=xxx CLOUDFLARE_API_TOKEN=xxx \
  node scripts/eval-embedding.mjs

# Structural test (38 checks)
npm run test:check

Related

ai-dev-toolkit — AI engineering governance skills (boundary-first, spec planning, adversarial review)

Known Limitations

Codex CLI exec mode: MCP tool calls fail

Affected version: codex-cli 0.117.0 (confirmed 2026-04-05)

Codex CLI's non-interactive mode (codex exec --full-auto, codex:codex-rescue) requires user approval for MCP tool calls. In non-interactive mode, no one can approve → auto-cancel with user cancelled MCP tool call.

This is a Codex CLI limitation, not a Memory Server issue.

Workarounds:

• Use interactive mode and approve MCP calls manually

• In workspaces with AGENTS.md / CLAUDE.md, Codex interactive mode will proactively save via Layer 1

• codex exec --dangerously-bypass-approvals-and-sandbox bypasses all approval (use with caution)

Version History

License

MIT