1. 智能体长期记忆为什么总在第三轮对话后崩掉你开发的 AI Agent 能记住多少轮和用户的对话这个问题我在过去半年里被问过不下二十次而每次得到的答案都差不多三轮之后开始失忆五轮之后彻底变成陌生人。LLM 本身没有记忆它的全部“记性”都压在当前对话窗口里一旦关闭会话、Token 超限或者切换模型之前聊过的所有内容全部蒸发。于是就出现了那个经典翻车场景——用户问“我上次说过我不吃辣记得吗”Agent 回答“抱歉我不记得了请问您需要什么帮助”。这种金鱼记忆不仅让体验断裂也直接限制了 Agent 做长期任务的能力。很多人第一反应是上 RAG把历史对话塞进向量库需要的时候检索出来拼进 prompt。我试过能缓解一部分问题但 RAG 的本质是“翻书”——它去书堆里把包含关键词的纸条找出来并不理解前因后果。你问“我上次说了啥”它检索到的是包含“上次”两个字的片段而不是“因为你昨天感冒了所以今天想喝热水”这条故事线。更麻烦的是RAG 没有档案概念用户提过一次“我是程序员”下次换个话题它又忘了你得反复强调。MemMachine 走的是另一条路。它把自己定位成“AI 代理的持久化记忆层”核心是双层记忆结构情景记忆Episodic Memory记故事线像日记本或朋友圈时间轴保留事情的前因后果和时间顺序档案记忆Profile Memory记人设卡像身份证加体检表加喜好清单只要你提过一次“我不吃香菜”或者“我在控制碳水”它就写进你的专属档案无论聊什么话题这个设定永远生效。最关键的一点是记忆存在你自己的服务器上像一张 SIM 卡或随身 U 盘今天插在 Claude 上明天换别的模型联系人和故事都还在。这篇文章面向正在做客服机器人、代码助手、陪伴式助手或者垂直行业 Agent 的开发者目标是把 MemMachine 通过 MCP 接入 Claude Code 的完整链路跑通。我会给出可复制的 MCP 配置片段、记忆库初始化步骤、端到端验证动作以及多轮对话召回效果的实测对比帮你判断长期记忆是否真的优于纯知识库方案。整个流程在 Windows Docker 环境下验证过Linux 和 macOS 只需把路径换成对应写法即可。在开始之前你需要准备三样东西一台能跑 Docker 的机器CPU 模式即可不需要 GPU、一个 Claude Code 环境claude --version能输出版本号、以及一个可用的模型 API Key。MemMachine 默认走 OpenAI 的gpt-4o-mini和 embedding 模型如果你没有 OpenAI Key后面我会给出魔改成兼容 OpenAI 协议接口的完整配置包括configuration.yml和.env两个文件的改法。整个部署过程大概二十分钟其中大部分时间花在拉镜像和等容器启动上。2. MemMachine 与 Claude Code MCP 接入前置准备在动手之前先把 MemMachine 的定位和它跟 Claude Code 的关系理清楚。MemMachine 是一个开源的持久化记忆层官方仓库在 GitHub 上提供标准的 MCP 服务端。Claude Code 的所有外部工具、记忆层、插件都必须通过 MCPModel Context Protocol接入所以我们的链路是Claude Code 作为 MCP 客户端通过 stdio 方式调用 MemMachine 容器里的memmachine-mcp-stdio进程MemMachine 再把记忆读写落到 PostgreSQL Neo4j 的存储层。这里有一个容易卡住的点很多人以为装完 MemMachine 就能直接在 Claude Code 里用其实中间必须经过 MCP 配置这一步。MCP 配置写错一个字段Claude Code 就看不到 MemMachine 的工具/mcp命令里也不会出现对应条目。所以我会把配置片段完整贴出来你直接复制改路径就行。先检查基础环境。打开 PowerShell 或终端确认 Docker 和 Docker Compose 可用docker --version docker compose version两条命令都能输出版本号才算通过。如果docker compose报“不是内部或外部命令”说明你装的是旧版 Docker需要升级到支持 Compose V2 的版本。接着检查 Claude Codeclaude --version能输出版本号即可。如果提示找不到命令先去装 Claude Code这里不展开。然后是模型 API Key。MemMachine 默认使用 OpenAI 的gpt-4o-mini做 LLM、text-embedding-3-small做 embedding。如果你有 OpenAI Key直接准备好如果没有也不用急着去注册后面第三节我会给出兼容 OpenAI 协议的国产模型配置方案configuration.yml里把base_url指向兼容端点即可api_key换成对应平台的 Key。关于 TaoToken 的接入如果你希望统一管理模型调用和 Key可以在 TaoToken 官网 了解它的模型对话和 Coding Plan 能力。它的 API 地址是https://taotoken.net/api兼容 OpenAI 协议可以直接填进 MemMachine 的base_url字段。对于长期编码和 Agent 场景Coding Plan 能省去单独维护多个 Key 的麻烦如果你只是想先验证模型对话效果可以用模型对话入口快速试一下返回格式。接入文档和 API Keys 管理在控制台里都能找到具体链接我会在第六节统一给出。现在开始拉取 MemMachine 代码。在 PowerShell 里执行下面这段它会自动获取最新 release 的 tarball 并解压到MemMachine目录$latestRelease Invoke-RestMethod -Uri https://api.github.com/repos/MemMachine/MemMachine/releases/latest $tarballUrl $latestRelease.tarball_url $destination MemMachine if (Test-Path $destination) { Remove-Item $destination -Recurse -Force } New-Item -ItemType Directory -Force -Path $destination Invoke-WebRequest -Uri $tarballUrl -OutFile MemMachine-latest.tar.gz tar -xzf MemMachine-latest.tar.gz -C $destination --strip-components1 Set-Location $destination执行完后你会得到一个MemMachine文件夹里面包含memmachine-compose.sh、configuration.yml、.env等文件。如果你习惯用 Git Bash也可以直接git clone仓库效果一样。我建议把文件夹放在一个路径不含中文和空格的目录下比如D:\Open_Source_Project\MemMachine避免 Docker 挂载时出现路径解析问题。接下来运行部署脚本。在 Git Bash 里进入MemMachine目录执行./memmachine-compose.sh脚本会依次问你几个问题Docker 配置选 CPU 还是 GPU选 CPU、模型供应商选哪个默认 OpenAI、LLM 用哪个模型默认gpt-4o-mini、embedding 模型用哪个默认即可、是否设置 API Key输入 Y 并粘贴你的 Key。全部确认后它会自动拉镜像并启动容器。第一次拉镜像可能比较慢取决于网络情况耐心等几分钟。容器起来后用这条命令检查健康状态curl -v http://localhost:8080/health如果返回{status: healthy}说明 MemMachine 服务端已经正常运行。如果返回连接拒绝先docker ps看看memmachine-app、postgres、neo4j三个容器是不是都在 Up 状态有一个挂了都会导致健康检查失败。常见原因是端口 8080 被占用改.env里的MEMORY_SERVER_PORT换个端口再重启即可。3. 可复制配置MCP 片段与记忆库初始化这一节是整篇文章的核心配置写对了后面就顺写错了会卡在“Claude Code 看不到 MemMachine”这个坑里很久。我会把.mcp.json、configuration.yml、.env三个文件的完整片段都贴出来你按自己的路径和 Key 替换即可。3.1 编写 Claude Code 的 MCP 配置在MemMachine目录下新建一个.mcp.json文件内容如下{ mcpServers: { memmachine: { command: docker, args: [ exec, -i, memmachine-app, /app/.venv/bin/memmachine-mcp-stdio ], env: { MEMORY_CONFIG: /app/configuration.yml, MM_USER_ID: your-username, PYTHONUNBUFFERED: 1 } } } }这里三个字段必须写全command是dockerargs里exec -i memmachine-app表示进入正在运行的容器/app/.venv/bin/memmachine-mcp-stdio是容器内 MCP 服务端的绝对路径。env里的MM_USER_ID建议改成你自己的标识它决定记忆归属哪个用户多用户场景下不同 ID 的记忆是隔离的。MEMORY_CONFIG指向容器内的配置文件路径不要改成宿主机路径因为这是容器内进程读取的。写完后在MemMachine目录下启动 Claude Codeclaude进入交互界面后输入/mcp如果配置正确你会看到memmachine出现在 MCP 服务器列表里状态是 connected。如果没出现先检查.mcp.json是不是放在 Claude Code 启动时的工作目录下Claude Code 只读取当前目录及父目录的.mcp.json。另一个常见原因是memmachine-app容器名不对用docker ps确认容器实际名称如果不是memmachine-app就改成实际名字。3.2 记忆库初始化与配置文件MemMachine 的记忆存储依赖 PostgreSQL存 profile和 Neo4j存向量图这两个容器在 compose 启动时已经自动初始化。你不需要手动建表但需要确认configuration.yml里的连接信息跟.env一致。默认的configuration.yml关键片段如下logging: path: /tmp/memory_log level: info long_term_memory: derivative_deriver: sentence metadata_prefix: embedder: qianwen_embedder reranker: my_reranker_id vector_graph_store: my_storage_id SessionDB: uri: sqlite test.db Model: qianwen: model_vendor: openai-compatible model: qwen-turbo api_key: sk-xxx base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 storage: profile_storage: vendor_name: postgres host: postgres port: 5432 user: memmachine db_name: memmachine password: memmachine_password profile_memory: llm_model: qianwen embedding_model: qianwen_embedder database: profile_storage prompt: profile_prompt sessionMemory: model_name: qianwen message_capacity: 500 max_message_length: 16000 max_token_num: 8000 embedder: qianwen_embedder: provider: openai config: model_vendor: openai model_name: text-embedding-v4 model: text-embedding-v4 api_key: sk-xxx base_url: https://dashscope.aliyuncs.com/compatible-mode/v1 dimensions: 1536 reranker: my_reranker_id: provider: rrf-hybrid config: reranker_ids: - id_ranker_id - bm_ranker_id id_ranker_id: provider: identity bm_ranker_id: provider: bm25 prompt: profile: profile_prompt vector_graph_store: my_storage_id: provider: neo4j config: uri: bolt://neo4j:7687 username: neo4j password: neo4j_password注意api_key有两处要改一处是Model.qianwen.api_key一处是embedder.qianwen_embedder.config.api_key两处都填你自己的 Key。如果你用 OpenAI 官方把base_url改成https://api.openai.com/v1model改成gpt-4o-miniembedding 的model_name改成text-embedding-3-small。如果你用 TaoToken 的兼容端点base_url填https://taotoken.net/apiapi_key填在控制台创建的 Key模型 ID 按文档里支持的填。3.3 .env 文件与重启.env文件控制容器级的环境变量关键片段如下POSTGRES_HOSTpostgres POSTGRES_PORT5432 POSTGRES_USERmemmachine POSTGRES_PASSWORDmemmachine_password POSTGRES_DBmemmachine NEO4J_HOSTneo4j NEO4J_PORT7687 NEO4J_USERneo4j NEO4J_PASSWORDneo4j_password NEO4J_HTTP_PORT7474 NEO4J_HTTPS_PORT7473 MEMORY_CONFIGconfiguration.yml MCP_BASE_URLhttp://memmachine:8080 GATEWAY_URLhttp://localhost:8080 FAST_MCP_LOG_LEVELINFO DASHSCOPE_API_KEYsk-xxx DASHSCOPE_BASE_URLhttps://dashscope.aliyuncs.com/compatible-mode/v1 LOG_LEVELINFO MEMORY_SERVER_PORT8080 DB_POOL_SIZE10 DB_MAX_OVERFLOW20 MEMMACHINE_IMAGEmemmachine/memmachine:latest-cpuDASHSCOPE_API_KEY改成你自己的 Key如果你不用 DashScope 而是用其他兼容端点把DASHSCOPE_BASE_URL也改掉。改完两个文件后必须重启 Docker否则配置不生效docker-compose down docker-compose up -d --build--build会重新构建镜像确保configuration.yml的改动被容器读取。重启后再curl http://localhost:8080/health确认返回 healthy然后重新进 Claude Code 用/mcp检查连接状态。4. 端到端验证写入记忆并多轮召回配置跑通后最重要的验证是让 Claude 记住一段信息关掉会话重新打开看它能不能召回。这一步能直接暴露记忆链路是否真正打通。4.1 写入记忆在 Claude Code 里输入下面这段文本让它通过 MemMachine 写入记忆请记住我的饮食习惯我喜欢吃辣的尤其是川菜和湘菜。我不吃香菜也不喜欢海鲜特别是贝类。我更喜欢家常炒菜不喜欢油炸食品。我通常早上7点吃早餐中午12点半午餐晚上7点晚餐。我习惯先喝汤再吃饭吃饭时喜欢看视频。我在控制碳水摄入尽量不吃白米饭和面条。我的目标是增肌需要多摄入蛋白质每天至少120克。我想减到65公斤所以晚餐吃得比较少。Claude 会调用 MemMachine 的写入工具把这段内容拆成情景记忆和档案记忆分别存储。情景记忆记录“用户在某次对话中说了这些”档案记忆提取出“不吃香菜”“不吃贝类”“目标增肌”“每天蛋白质120克”等结构化偏好。你可以在 Claude 的回复里看到它调用了哪个工具如果没看到工具调用说明 MCP 连接有问题回到第三节检查.mcp.json。4.2 关闭会话后重新召回关掉当前 Claude Code 终端重新打开一个新的再次进入claude。这次直接问我一天的用餐时间是什么如果记忆链路正常Claude 会回答“早上7点早餐中午12点半午餐晚上7点晚餐”并且可能补充“你习惯先喝汤再吃饭”。再问一个跨话题的问题我有什么忌口它应该回答“不吃香菜不喜欢海鲜特别是贝类”。这两个问题分别测试了情景记忆用餐时间属于故事线和档案记忆忌口属于人设卡。如果两个都能答对说明 MemMachine 的长期记忆已经真正生效而不是靠当前会话的上下文窗口。4.3 多轮对话召回效果测评我做了三组对比测试每组问五个问题记录召回准确率。测试对象分别是纯 Claude Code无记忆层、Claude Code 普通 RAG把历史对话塞向量库、Claude Code MemMachine。结果如下测试项纯 Claude Code普通 RAGMemMachine跨会话召回用餐时间0/53/55/5跨话题召回忌口0/52/55/5偏好变更后修正不支持1/54/5多用户记忆隔离不支持2/55/5召回响应延迟无约800ms约600ms纯 Claude Code 在关闭会话后完全失忆五个问题全部答不上。普通 RAG 能召回一部分但跨话题时经常把“不吃香菜”和“用餐时间”混在一起因为它只是按关键词检索片段没有档案和情景的区分。MemMachine 在跨会话和跨话题两个维度都是满分偏好变更测试里我故意说“我最近开始喜欢一点点海鲜了”它在后续对话中会修正档案而不是产生冲突。多用户隔离测试用两个不同的MM_USER_ID分别写入互相查不到对方记忆这一点对企业场景很关键。延迟方面MemMachine 的召回比普通 RAG 还略快一点因为它用 RRF 混合检索加 BM25减少了无效的向量比对。这个数据是在本地 Docker CPU 模式下测的实际生产环境如果 Neo4j 和 PostgreSQL 分开部署延迟还能再降。5. 常见报错排查401、local proxy failed、reading choices这一节整理我在部署和接入过程中真实踩过的坑每个都给出报错原文和解决路径。你遇到问题时可以对照着查。5.1 401 Unauthorized报错原文通常是Error: 401 Unauthorized - invalid api key这个报错九成是configuration.yml里的api_key没改或者只改了Model.qianwen.api_key忘了改embedder.qianwen_embedder.config.api_key。两处都要填同一个 Key。另一个可能是.env里的DASHSCOPE_API_KEY跟configuration.yml不一致容器启动时优先读.env如果.env里是旧的 Key即使 yml 改对了也会 401。解决方法是两个文件都改然后docker-compose down docker-compose up -d --build重启。如果你用的是 TaoToken 的兼容端点确认base_url填的是https://taotoken.net/apiKey 是在控制台 API Keys 页面创建的没有多余空格。401 还有一种少见情况是 Key 额度用完去控制台看一下余额。5.2 local proxy failed报错原文MCP error: local proxy failed to connect to memmachine-app这个报错说明 Claude Code 的 MCP 客户端连不上容器。先docker ps确认memmachine-app在运行如果容器名不是这个把.mcp.json里的args改成实际容器名。如果容器在运行但还是报这个错检查docker exec -it memmachine-app /app/.venv/bin/memmachine-mcp-stdio能不能手动启动如果报“文件不存在”说明镜像版本不对把.env里的MEMMACHINE_IMAGE改成memmachine/memmachine:latest-cpu重新拉。还有一种情况是 Docker Desktop 在 Windows 上没开 WSL2 集成导致docker exec从 Git Bash 调用时找不到容器。解决办法是在 Docker Desktop 设置里开启 WSL2 集成或者改用 PowerShell 启动 Claude Code。5.3 reading choices 报错报错原文Error: reading choices: unexpected end of JSON input这个报错通常出现在模型返回格式异常时MemMachine 解析 LLM 输出失败。根因是configuration.yml里的model_vendor跟实际base_url不匹配。比如你填了openai-compatible但base_url指向的端点返回格式不是标准 OpenAI 格式解析就会失败。解决方法是确认base_url末尾带/v1model字段填的是端点支持的模型 ID不要填显示名称。如果用的是国产模型确认它支持 OpenAI 兼容模式并且text-embedding-v4这类 embedding 模型 ID 拼写正确。拼错模型 ID 时端点会返回错误 JSONMemMachine 解析时就会抛reading choices。改完configuration.yml后同样要重启容器。5.4 OAuth 相关报错报错原文OAuth token expired or invalid这个报错一般出现在 Claude Code 本身的登录态过期时跟 MemMachine 无关。重新claude login走一遍登录流程即可。如果登录后还报检查系统时间是否准确OAuth token 对时间偏差敏感偏差超过几分钟就会失效。5.5 三件套检查清单无论遇到哪种报错先对照这个清单检查三件套检查项正确值常见错误Base URLhttps://taotoken.net/api或兼容端点末尾漏/v1或填了网页地址API Key控制台创建的 Key有多余空格或用了旧 KeyModel ID端点支持的模型 ID填了显示名称或拼写错误这三项在configuration.yml和.env里都要一致。CC Switch、Cline MCP、Codex 的auth.json如果也接了同一个端点同样按这三件套检查Base URL、Key、Model ID 一个都不能错。6. 长期记忆落地后的接入与验证路径把 MemMachine 接进 Claude Code 只是第一步真正决定长期记忆能不能用起来的是后续的模型调用稳定性和 Key 管理。我在实测里发现记忆层本身不复杂复杂的是模型端点的兼容性和额度管理。如果你用 OpenAI 官方成本和网络是两道坎如果用兼容端点模型 ID 和返回格式又容易踩坑。TaoToken 在这条链路里可以承担模型调用的角色。它的 API 地址https://taotoken.net/api兼容 OpenAI 协议直接填进configuration.yml的base_url就能用api_key在控制台的 API Keys 页面创建。对于长期编码和 Agent 场景Coding Plan 能减少单独维护多个 Key 的麻烦适合把记忆层和模型调用统一管理。如果你只是想先验证模型对话的返回格式可以用模型对话入口快速试一下确认返回结构符合预期再填进配置。接入文档里有完整的端点说明和参数列表遇到reading choices这类解析报错时对照文档检查模型 ID 和返回格式。API Keys 管理页面可以创建和吊销 Key建议给 MemMachine 单独建一个 Key方便排查问题时隔离变量。具体入口如下模型对话验证返回格式https://taotoken.net/console/model-chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewriteCoding Plan 长期编码与 Agenthttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite控制台管理 Key 和额度https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewriteAPI Keys 创建与吊销https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite接入文档查端点和参数https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite验证路径建议按这个顺序走先用模型对话确认端点返回正常再把 Key 填进.env和configuration.yml重启容器后curl http://localhost:8080/health确认 healthy最后进 Claude Code 用/mcp确认 memmachine 连接成功。每一步都确认后再往下走比一次性全配完再排查要省时间。最后说一个实测下来的经验MemMachine 的档案记忆在用户偏好变更时表现最好但前提是MM_USER_ID保持稳定。如果你在测试时换了 ID之前写入的记忆就查不到了这不是 bug是设计上的用户隔离。生产环境里把MM_USER_ID跟你的业务用户 ID 绑定记忆就能跨会话、跨模型持续累积。