1. memory-mcp 是什么给 AI 代理装上可搜索的长期记忆如果你用 Cline、Windsurf 或者 Claude Code 写代码大概率遇到过这种尴尬昨天刚跟 AI 敲定的技术方案今天开个新会话它全忘了你得把背景重新讲一遍。memory-mcp 就是来解决这个问题的——它是一个基于 MCPModel Context Protocol协议的记忆服务把 AI 代理的记忆落到 Valkey 或 Redis 这类 Redis 兼容后端里再通过 HTTP 端点暴露给各种客户端调用。说白了它干的事就是让 AI 代理能记住项目决策、代码模式、用户反馈、事故记录这些东西而且这些记忆是持久化的、可搜索的、带版本历史的。你换会话、换工具、甚至换机器只要连的是同一个后端记忆就还在。它适合谁我梳理了三类人第一类是重度使用 Cline MCP 或 Windsurf BYOK 的开发者需要跨会话保持上下文第二类是想给自建 Agent 加记忆层的人memory-mcp 提供了 8 个标准 MCP 工具接入成本低第三类是团队里想搞项目知识库的把决策和模式沉淀下来新人接手时直接搜。核心能力我列一下方便你判断要不要上持久化存储每条记忆带标签、类型、项目范围存在 Redis 哈希里高级搜索标签交集、类型过滤、项目过滤、子字符串匹配命中跟踪被检索次数越多排名越靠前相当于自带热度排序版本控制每次写入都版本化支持回滚默认每个条目保留 20 个快照8 个 MCP 工具search、get、set、list、delete、history、rollback、prune_candidatesPrometheus 指标/metrics端点暴露监控数据可选认证Bearer 令牌绑定 127.0.0.1 时默认无认证多后端Redis、Valkey、KeyDB、Upstash 都能用记忆类型有 8 种pattern模式、decision决策、reference参考、feedback反馈、incident事故、project项目、entity实体、state状态。这个分类挺实用比如你存用 Valkey 而不是 Redis 做缓存就归到 decision存这个项目的 API 鉴权走 JWT就归到 project。传输方式走的是 HTTPMCP 端点在http://127.0.0.1:3106/mcp健康检查GET /health指标GET /metrics。注意 health 和 metrics 这两个端点始终不需要认证方便你监控。2. 前置准备Valkey/Redis 后端与 TaoToken 接入配置在动手之前得先把两件事理清楚一是记忆后端Valkey 或 Redis怎么起二是 AI 工具链的模型接入怎么配。memory-mcp 本身只负责记忆存储和检索它不提供模型能力所以你的 Cline、Windsurf 这些客户端还得单独配模型接入。先说记忆后端。最省事的方式是用 Docker Composememory-mcp 仓库里一般会带一个 compose 文件把 Valkey 和 memory-mcp 一起拉起来。如果你想用已有的 Redis 或 Valkey就在.env里把VALKEY_URL指过去比如redis://your-host:6379然后只启动 memory-mcp 服务。环境变量这块有几个关键项我整理成表格方便对照变量默认值说明MEMORY_MCP_BIND127.0.0.1绑定接口用 0.0.0.0 时必须设 AUTH_TOKENMEMORY_MCP_HOST_PORT3106主机暴露端口MEMORY_MCP_AUTH_TOKEN空/mcp 的 Bearer 令牌空无认证MEMORY_MCP_MAX_ENTRIES_WARN300软上限超过时警告MEMORY_MCP_MAX_VERSIONS_PER_ENTRY20每个条目最大版本快照数MEMORY_MCP_MEM_LIMIT256m容器内存上限生成令牌用openssl rand -hex 32把结果填到MEMORY_MCP_AUTH_TOKEN里。这里有个坑要注意如果你把MEMORY_MCP_BIND改成0.0.0.0让局域网其他机器访问必须设置 AUTH_TOKEN否则等于把记忆库裸奔在网络上。再说模型接入。memory-mcp 解决的是记忆但你的 AI 工具还得有大脑。如果你用 Cline、Windsurf 这类支持 BYOKBring Your Own Key的客户端可以走 TaoToken 的 API 接入。TaoToken 提供兼容 OpenAI 风格的接口Base URL 填https://taotoken.net/apiKey 在控制台的 API Keys 页面生成。具体操作路径先到 TaoToken 控制台 注册登录然后在 API Keys 页面 创建一个 Key。创建时注意复制保存页面刷新后就不再完整显示了。拿到 Key 之后在 Cline 或 Windsurf 的模型配置里填三件套Base URLhttps://taotoken.net/apiAPI Key你刚生成的那串Model ID按你需要的模型填比如claude-sonnet-4-5这类如果你用的是 Claude Code它有自己的接入方式可以参考 Claude Code 接入文档。想先试试模型对话效果可以直接用 模型对话页面 快速验证。这里要强调一下memory-mcp 和 TaoToken 是两个独立的东西前者管记忆后者管模型调用。你完全可以只用 memory-mcp 配本地模型也可以只用 TaoToken 不配记忆。但如果你想让 AI 代理既有长期记忆又有稳定的模型能力两个都配上体验最完整。长期做编码或 Agent 开发的话可以考虑 Coding Plan按套餐走比单次调用划算。3. 可复制配置服务端 .env 与客户端 mcpServers JSON这一节直接给可复制的配置片段你照着改改就能用。先看服务端的.env# memory-mcp 服务端配置 MEMORY_MCP_BIND127.0.0.1 MEMORY_MCP_HOST_PORT3106 MEMORY_MCP_AUTH_TOKENyour-generated-token-here MEMORY_MCP_MAX_ENTRIES_WARN300 MEMORY_MCP_MAX_VERSIONS_PER_ENTRY20 MEMORY_MCP_MEM_LIMIT256m # Valkey/Redis 后端连接 VALKEY_URLredis://127.0.0.1:6379如果你用 Docker Compose 一起起 ValkeyVALKEY_URL里的 host 要改成 compose 服务名比如redis://valkey:6379。这个坑我踩过本地跑没问题一进容器就连不上就是因为 host 写成了 127.0.0.1。启动命令cp .env.example .env # 编辑 .env填入 AUTH_TOKEN 和 VALKEY_URL docker compose up -d如果只用已有的 Redis/Valkey只起 memory-mcpdocker compose up -d memory-mcp本地构建的话docker compose build docker compose up -d接下来是客户端配置。Cline MCP 和 Windsurf BYOK 都认mcpServers这个结构。以 Cline 为例在 MCP 配置里加{ mcpServers: { memory: { type: http, url: http://127.0.0.1:3106/mcp, headers: { Authorization: Bearer your-generated-token-here } } } }Cursor 的话写到~/.cursor/mcp.json全局或项目里的.cursor/mcp.json{ mcpServers: { memory: { url: http://127.0.0.1:3106/mcp, headers: { Authorization: Bearer your-generated-token-here } } } }注意 Cursor 的配置里没有type: http这个字段它默认按 URL 推断。如果你从 Cline 的配置直接复制过去多这个字段一般也不报错但保险起见按各客户端文档来。Claude Code 用命令行注册# 无认证 claude mcp add memory --transport http http://127.0.0.1:3106/mcp # 有认证 claude mcp add memory --transport http http://127.0.0.1:3106/mcp \ --header Authorization: Bearer your-generated-token-here这里的三件套对应关系要清楚Base URL 是http://127.0.0.1:3106/mcpKey 是MEMORY_MCP_AUTH_TOKEN的值Model ID 这块 memory-mcp 本身不涉及但你的客户端模型配置里要填 TaoToken 的 Model ID。别把两个 Key 搞混了——一个是记忆服务的 Bearer 令牌一个是模型 API 的 Key。如果你用 Codex它的auth.json配置方式不太一样但思路一致把 Base URL、Key、Model ID 三样填对。Codex 的auth.json一般长这样{ openai: { apiKey: your-taotoken-api-key, baseURL: https://taotoken.net/api } }具体路径和字段名以你用的 Codex 版本为准核心就是 Base URL 指向https://taotoken.net/apiKey 用 TaoToken 生成的。4. 验证请求用 curl 跑通记忆读写链路配置填完别急着开客户端先用 curl 把链路跑通这样出问题好定位。memory-mcp 走的是 MCP over HTTP请求体是 JSON-RPC 格式。先测健康检查这个不需要认证curl -s http://127.0.0.1:3106/health正常返回类似{status:ok}。如果连不上先看容器起没起docker compose ps。再测指标端点curl -s http://127.0.0.1:3106/metrics | head -20能看到 Prometheus 格式的指标就说明服务活着。接下来测 MCP 端点。先列一下可用工具curl -s -X POST http://127.0.0.1:3106/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer your-generated-token-here \ -d { jsonrpc: 2.0, id: 1, method: tools/list, params: {} }返回里应该能看到 8 个工具memory_search、memory_get、memory_set、memory_list、memory_delete、memory_history、memory_rollback、memory_prune_candidates。然后写一条记忆进去curl -s -X POST http://127.0.0.1:3106/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer your-generated-token-here \ -d { jsonrpc: 2.0, id: 2, method: tools/call, params: { name: memory_set, arguments: { title: 使用 Valkey 作为缓存, body: 决定使用 Valkey 而不是 Redis因为许可证更友好且兼容 Redis 协议。, type: decision, tags: caching,valkey,redis, project: my-project } } }返回里会带一个 ID类似mem:abc123记下来。搜一下刚写的记忆curl -s -X POST http://127.0.0.1:3106/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer your-generated-token-here \ -d { jsonrpc: 2.0, id: 3, method: tools/call, params: { name: memory_search, arguments: { tags: caching,valkey, type: decision } } }能搜到刚才那条就说明读写链路通了。再测一下 get 和 history# 获取单条会增加 hits 计数 curl -s -X POST http://127.0.0.1:3106/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer your-generated-token-here \ -d { jsonrpc: 2.0, id: 4, method: tools/call, params: { name: memory_get, arguments: {id: mem:abc123} } } # 查看版本历史 curl -s -X POST http://127.0.0.1:3106/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer your-generated-token-here \ -d { jsonrpc: 2.0, id: 5, method: tools/call, params: { name: memory_history, arguments: {id: mem:abc123} } }回滚测试curl -s -X POST http://127.0.0.1:3106/mcp \ -H Content-Type: application/json \ -H Authorization: Bearer your-generated-token-here \ -d { jsonrpc: 2.0, id: 6, method: tools/call, params: { name: memory_rollback, arguments: {id: mem:abc123, version: 1} } }这一套跑下来记忆的增删改查和版本控制就都验证过了。实测下来curl 验证这一步能省掉后面在客户端里瞎猜的时间。5. 常见报错排查401、local proxy failed 与 reading choices这一节按真实报错来对你遇到哪个直接查。401 Unauthorized最常见。原因就两个——要么请求头没带Authorization: Bearer token要么 token 跟服务端.env里的MEMORY_MCP_AUTH_TOKEN不一致。排查步骤先确认.env里设了 token再确认客户端配置里的 token 一字不差。注意 token 前后别带空格复制的时候容易多带。如果你改过.env记得重启容器docker compose restart memory-mcp。local proxy failed / connection refused客户端连不上127.0.0.1:3106。先curl http://127.0.0.1:3106/health看服务活没活。如果服务在容器里而客户端在宿主机端口映射要确认docker compose ps看 3106 有没有映射出来。如果客户端在另一台机器MEMORY_MCP_BIND得改成0.0.0.0同时必须设 AUTH_TOKEN。还有一种情况是端口被占换个MEMORY_MCP_HOST_PORT再试。reading choices / 解析错误这个报错通常出现在客户端解析 MCP 响应时。原因可能是服务端返回了非 JSON 内容比如 404 页面或者 HTML 错误页。排查用 curl 直接打/mcp看返回是不是合法 JSON-RPC。如果返回 404检查 URL 是不是写成了http://127.0.0.1:3106/而不是/mcp。如果返回 HTML可能是反向代理插了一脚把代理配置去掉直连试试。OAuth 相关报错memory-mcp 用的是 Bearer 令牌不是 OAuth。如果你在客户端里看到 OAuth 报错多半是客户端把 MCP 服务当成了需要 OAuth 的远程服务。检查配置里type是不是httpURL 是不是本地地址。有些客户端对http和sse的推断逻辑不一样显式写type: http能避免歧义。连接超时但 health 正常/health通但/mcp超时一般是认证中间件卡住了。检查 token 格式Bearer 后面有个空格别漏了。另外确认请求方法是 POST/mcp不接受 GET。记忆写不进去memory_set返回错误先看 Valkey/Redis 连没连上。VALKEY_URL写错是高频问题尤其是容器里用127.0.0.1连宿主机的情况。进容器测一下docker compose exec memory-mcp sh然后redis-cli -u $VALKEY_URL ping返回 PONG 就说明后端通。条目数量警告默认软上限 300 条超了会警告但不阻止写入。如果你记忆量大调MEMORY_MCP_MAX_ENTRIES_WARN。版本快照默认 20 个写频繁的条目可以调小省内存。排查时记住一个原则先 curl 通服务端再查客户端配置。服务端没问题的话九成是客户端配置里的 URL、token 或 type 写错了。6. 把记忆接进你的 AI 工具链配置跑通之后日常使用其实很简单。你在 Cline 里跟 AI 讨论出一个方案让它调memory_set存下来下次新会话先让它memory_search一下相关标签上下文就回来了。Windsurf BYOK 同理只要 MCP 配置里挂上了 memory 服务工具调用是自动的。几个实用技巧。第一标签别乱打按项目或主题建一套命名规范比如project:my-app、topic:auth搜索时交集匹配才准。第二decision 和 pattern 这两类最值得存前者记录为什么这么选后者记录代码怎么写新人接手时搜这两个类型效率最高。第三定期跑memory_prune_candidates看看零命中的陈旧条目该删就删别让记忆库变成垃圾场。如果你还没配模型接入可以到 TaoToken 模型对话 先试试效果确认模型能力符合预期再往工具链里接。API Key 在 控制台 生成接入细节看 接入文档。长期编码场景建议直接上 Coding Plan省得每次单独配。最后提醒一句memory-mcp 的数据全在 Valkey/Redis 里后端持久化配置一定要做对。容器重启数据丢不丢取决于你的 Redis 有没有开 AOF 或 RDB。生产环境别用默认配置裸跑挂个 volume 把数据目录映射出来这是底线。