1. 为什么你的 AI Agent 总是“金鱼记忆”长期记忆系统到底缺了什么先说一个我踩过的坑。去年我给自己写了个代码助手 Agent专门用来记录项目里的技术选型和命名规范。第一次对话我告诉它“这个项目统一用 pydantic v2别给我生成 v1 的写法”它答应得好好的。第二天我重新打开问它“帮我写个配置类”它反手就给我来了一段class Config:的老式写法。那一刻我意识到LLM 本身没有记忆它的“记性”完全依赖当前上下文窗口窗口一关前因后果全部蒸发。这不是模型能力问题而是架构问题。大语言模型的推理是无状态的每次请求都是一次全新的前向计算。你看到的“它记得”其实是把历史对话拼进了 prompt 里。一旦对话轮次变多、token 超限或者你换了会话、重启了进程这些临时拼进去的内容就没了。对于陪伴类助手、客服机器人、长期编码 Agent 来说这种“金鱼记忆”直接让体验断裂。传统做法是用 RAG检索增强生成来补。RAG 的思路是把历史内容切块、向量化、存进向量库需要时按语义相似度召回几段塞进 prompt。它像给 AI 配了一本字典能查资料但它不懂前因后果。你问“我上次说了啥”它只是去书堆里把包含“上次”两个字的纸条翻出来并不理解时间线和人物关系。更麻烦的是RAG 召回的是静态片段用户改口了、偏好变了旧片段还在库里容易和新信息打架。MemMachine 走的是另一条路。它把自己定位成“AI Agent 的持久化记忆层”核心是双层记忆结构一层叫情景记忆Episodic Memory记的是“故事线”比如你昨天感冒了所以今天想喝热水它记的是事件的前后顺序和因果另一层叫档案记忆Profile Memory记的是“人设卡”比如你不吃香菜、你是程序员、你在控制碳水这些一旦写入就长期生效不需要反复强调。检索时它会把这两层记忆融合后注入到当前对话里让模型“想起来”。这套机制适合谁如果你在做多轮对话的个人助手、需要跨会话记住用户偏好的客服系统、或者长期跑任务的编码 Agent那长期记忆系统就是刚需。这篇我会带你从零把 MemMachine 搭起来走通记忆写入、检索、注入的完整链路并且用 TaoToken 统一 Key 和 API 通道来接入模型调用保证整条链路可跑通、可复现。你不需要懂太多底层原理跟着命令走就行。2. 搭建前的环境准备Docker 部署 MemMachine 与 TaoToken 统一接入配置动手之前先把地基打好。MemMachine 官方推荐用 Docker 部署所以你的机器上得有 Docker 和 Docker Compose。Windows 用户装 Docker Desktop 就行Mac 和 Linux 用户装对应版本。装完在终端里验证一下docker --version docker compose version两条命令都能打印出版本号说明环境没问题。接下来是模型 API 通道。MemMachine 默认走 OpenAI 的接口格式但实际调用哪个模型供应商是可以换的。这里我用 TaoToken 来做统一接入原因是它兼容 OpenAI 的接口协议Base URL 和 Key 配一次后面换模型只改 Model ID 就行不用动代码结构。TaoToken 的 API 地址是https://taotoken.net/api注意这个地址不带任何查询参数。你需要先去控制台创建一个 API Key入口在https://taotoken.net/console/api-keys。创建完把 Key 复制下来形如sk-开头的一串字符后面配置里要用。如果你还没决定用哪个模型可以先在模型对话页面试试手感地址是https://taotoken.net/model-chat确认通道通了再往下走。现在拉取 MemMachine 的代码。官方仓库在 GitHub 上我用的是 release 包的方式这样版本可控。在 PowerShell 里执行下面这段它会自动下载最新 release 并解压到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如果你用的是 Git Bash 或者 Linux也可以直接git clone仓库效果一样。解压完进入目录你会看到memmachine-compose.sh这个脚本它是官方给的交互式部署入口。运行它./memmachine-compose.sh脚本会依次问你几个问题用 CPU 还是 GPU 配置、用哪个模型供应商、用哪个对话模型、用哪个 embedding 模型、以及 API Key。这里有个关键点如果你打算用 TaoToken 统一接入模型供应商那一步选 OpenAI 兼容模式然后把 Base URL 指向 TaoToken。不过脚本的交互流程里 Base URL 不一定能直接改所以更稳妥的做法是先用默认流程跑通再手动改配置文件。我实测下来先让它用默认的 OpenAI 配置把容器拉起来然后改configuration.yml和.env两个文件重启容器这样最省事。等脚本跑完容器启动需要一两分钟。验证服务是否健康curl -v http://localhost:8080/health返回{status: healthy}就说明 MemMachine 服务起来了。这一步如果卡住多半是端口占用或者镜像没拉下来先docker ps看看容器状态再docker logs看具体报错。环境准备好之后下一节我们进入真正的配置环节把 TaoToken 的 Key 和 Base URL 写进去让记忆系统用上统一的模型通道。3. 可复制配置configuration.yml 与 .env 接入 TaoToken 的完整片段这一节是整篇的核心配置写对了后面就顺了。MemMachine 的模型调用配置分散在两个文件里configuration.yml管记忆系统的模型绑定.env管环境变量和 API Key。我们要做的是把这两处的模型供应商都指向 TaoToken这样对话模型和 embedding 模型走同一条通道。先看configuration.yml。这个文件在 MemMachine 根目录下用文本编辑器打开。找到model和embedder两段改成下面这样。注意base_url填 TaoToken 的 API 地址api_key填你在控制台创建的那把 Keymodel填你要用的 Model ID。Model ID 的具体取值可以在接入文档里查地址是https://taotoken.net/doc。logging: path: /tmp/memory_log level: info long_term_memory: derivative_deriver: sentence metadata_prefix: embedder: my_embedder reranker: my_reranker vector_graph_store: my_storage SessionDB: uri: sqlite:///test.db Model: taotoken_model: model_vendor: openai-compatible model: gpt-4o-mini api_key: sk-你的TaoToken密钥 base_url: https://taotoken.net/api storage: profile_storage: vendor_name: postgres host: postgres port: 5432 user: memmachine db_name: memmachine password: memmachine_password profile_memory: llm_model: taotoken_model embedding_model: my_embedder database: profile_storage prompt: profile_prompt sessionMemory: model_name: taotoken_model message_capacity: 500 max_message_length: 16000 max_token_num: 8000 embedder: my_embedder: provider: openai config: model_vendor: openai model_name: text-embedding-3-small model: text-embedding-3-small api_key: sk-你的TaoToken密钥 base_url: https://taotoken.net/api dimensions: 1536 reranker: my_reranker: 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: provider: neo4j config: uri: bolt://neo4j:7687 username: neo4j password: neo4j_password这里有三处要替换成你自己的值api_key两处、model和model_name按你实际想用的模型填。如果你用的是别的 embedding 模型把text-embedding-3-small换成对应的 Model IDdimensions也要跟着改否则向量维度对不上会报错。再看.env文件。这个文件管容器启动时的环境变量重点是DASHSCOPE_API_KEY这类变量名可能因版本而异但核心是让容器内的服务能读到 Key。改成下面这样# PostgreSQL / pgvector POSTGRES_HOSTpostgres POSTGRES_PORT5432 POSTGRES_USERmemmachine POSTGRES_PASSWORDmemmachine_password POSTGRES_DBmemmachine # Neo4j NEO4J_HOSTneo4j NEO4J_PORT7687 NEO4J_USERneo4j NEO4J_PASSWORDneo4j_password NEO4J_HTTP_PORT7474 NEO4J_HTTPS_PORT7473 # MemMachine MEMORY_CONFIGconfiguration.yml MCP_BASE_URLhttp://memmachine:8080 GATEWAY_URLhttp://localhost:8080 FAST_MCP_LOG_LEVELINFO # TaoToken 统一通道 TAOTOKEN_API_KEYsk-你的TaoToken密钥 TAOTOKEN_BASE_URLhttps://taotoken.net/api # 可选 LOG_LEVELINFO MEMORY_SERVER_PORT8080 DB_POOL_SIZE10 DB_MAX_OVERFLOW20 MEMMACHINE_IMAGEmemmachine/memmachine:latest-cpu改完两个文件必须重启容器让配置生效。在 MemMachine 目录下执行docker compose down docker compose up -d --build--build会重新构建镜像确保配置被读进去。等容器起来后再跑一次健康检查确认服务正常。这一步如果报401或者invalid api key八成是 Key 没填对或者 Base URL 多了斜杠。TaoToken 的地址是https://taotoken.net/api结尾不要加/v1也不要加多余路径否则会拼出错误的请求地址。配置这块搞定下一节我们做记忆写入和检索的验证。4. 验证记忆链路写入偏好、重启服务、检查召回是否成功配置写完不代表链路通了得用真实数据验证一遍。这一节我们做三件事把一段用户偏好写进记忆、重启服务模拟“关掉对话再打开”、然后提问看它能不能召回。整个过程可复现你跟着做就能确认自己的系统是否正常。先确认 Claude Code 已经装好因为 MemMachine 是通过 MCP 协议接入 Claude Code 的。检查命令claude --version有版本号输出就行。然后在 MemMachine 根目录下创建.mcp.json文件内容如下。这个文件告诉 Claude Code 去哪里找 MemMachine 的 MCP 服务端{ 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 } } } }MM_USER_ID填一个你自己的标识比如test-user它用来区分不同用户的记忆空间。保存后启动 Claude Codeclaude进入交互界面后输入/mcp如果看到memmachine出现在已连接的服务列表里说明 MCP 通道打通了。接下来做记忆写入。在 Claude 对话框里输入下面这段文本让它记住你的饮食习惯请记住我的饮食习惯我喜欢吃辣的尤其是川菜和湘菜。我不吃香菜也不喜欢海鲜特别是贝类。我更喜欢家常炒菜不喜欢油炸食品。我通常早上7点吃早餐中午12点半午餐晚上7点晚餐。我习惯先喝汤再吃饭。我在控制碳水摄入尽量不吃白米饭和面条。我的目标是增肌每天至少摄入120克蛋白质。我想减到65公斤所以晚餐吃得比较少。发送后MemMachine 会把这段内容拆解成情景记忆和档案记忆分别存储。情景记忆记录“用户在某时刻说了这些”档案记忆提取出“不吃香菜”“喜欢川菜”“目标增肌”这些长期偏好。写入过程可能需要几秒取决于模型响应速度。关键验证步骤来了完全退出 Claude Code然后重新启动。这一步模拟“关掉对话再打开”的场景如果记忆只存在上下文里重启后就没了如果 MemMachine 正常工作重启后偏好应该还在。重新进入后直接提问我一天的用餐时间是怎么安排的如果系统返回类似“你早上7点吃早餐中午12点半午餐晚上7点晚餐”的内容说明记忆召回成功。再问一个偏好类问题我不吃什么预期它能答出“不吃香菜不喜欢海鲜特别是贝类”。这两个问题一个考情景记忆的时间线一个考档案记忆的偏好提取都答对才算链路完整。如果你想更直观地看记忆存储情况可以调 MemMachine 的检索接口。不过对大多数场景来说通过 Claude Code 的对话验证已经够了。实测下来第一次写入后召回可能需要一两秒因为要做向量检索和重排后续命中缓存会快一些。如果召回失败先检查MM_USER_ID是否和写入时一致不同用户 ID 的记忆空间是隔离的写进 A 用户的内容 B 用户查不到。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth 问题链路跑通之前报错是常态。这一节我把几个高频错误和对应的排查路径列出来你遇到时可以直接对照。这些报错我在搭建过程中基本都踩过一遍原因和解法都比较明确。401 Unauthorized / invalid api key这是最常见的。表现是容器日志里出现401或者 Claude 对话时提示模型调用失败。根因通常是 Key 没填对、Key 过期、或者 Base URL 拼错。排查顺序先确认.env和configuration.yml里的api_key是同一把 Key且没有多余空格再确认base_url是https://taotoken.net/api结尾没有/v1或斜杠最后去控制台确认这把 Key 还有效、额度没耗尽。如果三处都对还是 401把容器日志打出来看具体请求地址docker logs memmachine-app --tail 100日志里会打印实际请求的 URL如果 URL 里出现了双斜杠或者路径拼接错误就是 Base URL 配置问题。local proxy failed / connection refused这个报错通常出现在容器内服务访问外部 API 时。表现是记忆写入卡住日志提示连接失败。根因可能是容器网络配置问题或者 Base URL 指向了容器内访问不到的地址。检查两点一是base_url必须是公网可访问的地址不能写localhost因为容器内的localhost指向容器自己二是确认宿主机网络正常容器能出网。可以用下面命令进容器测试连通性docker exec -it memmachine-app curl -v https://taotoken.net/api如果这条命令在容器内能通说明网络没问题问题在配置如果不通检查 Docker 的网络模式。reading choices / 响应解析失败这个报错说明请求发出去了但返回的内容格式不符合预期。常见原因是 Model ID 填错了比如填了一个不存在的模型名接口返回了错误结构而客户端按正常响应去解析choices字段就报reading choices。排查方法是把 Model ID 和接入文档里的可用列表对一遍确认拼写完全一致。另外 embedding 模型的dimensions如果和实际模型输出维度不一致也会在写入阶段报解析错误这时候要改dimensions值。OAuth / 认证流程异常如果你在 Claude Code 侧看到 OAuth 相关报错通常是 MCP 配置里的环境变量没传对。检查.mcp.json里的env段MEMORY_CONFIG路径要指向容器内的实际路径/app/configuration.ymlMM_USER_ID不能为空。另外 Claude Code 本身的登录态如果失效也会报认证错误重新登录一次即可。记忆写入成功但召回为空这个不是报错但很常见。表现是写入时没报错提问时却答“不知道”。排查方向确认写入和查询用的是同一个MM_USER_ID确认两次操作之间没有清空数据库确认 embedding 模型在写入和查询时是同一个换了 embedding 模型会导致向量空间不一致检索不到。如果都正常把message_capacity调大一点默认 500 条消息的容量在测试时够用但如果你写入了大量内容可能被截断。排查完这些链路基本就稳了。下一节说下长期用起来的一些实际建议和通道选择。6. 长期编码与 Agent 场景的通道选择把记忆系统跑成日常基础设施记忆系统搭好只是第一步真正让它产生价值的是长期跑起来。我自己的用法是把它挂在日常编码 Agent 上每次开新会话Agent 会自动召回项目规范、命名习惯、技术栈偏好不用我重复交代。这种场景对模型通道的稳定性要求比较高因为记忆检索本身要调 embedding 模型对话又要调对话模型两条链路都得通。如果你的使用频率不高只是偶尔试试那用 API Keys 的方式按量调用就够了去https://taotoken.net/console/api-keys创建 Key配到 MemMachine 里就能跑。但如果你打算把带记忆的 Agent 当成日常工具每天都要跑很多轮对话和检索那 Coding Plan 会更合适它在长期编码和 Agent 场景下有更稳定的通道保障入口在https://taotoken.net/coding-plan。我实测下来高频调用时用 Plan 的通道响应抖动会小一些记忆召回的成功率也更稳。还有一个实际经验记忆系统刚搭好的时候别急着灌大量数据。先写几条关键偏好验证召回正常再逐步增加。因为记忆检索是按相关性排序的如果早期写入了太多噪音反而会干扰召回质量。等链路稳定了再让它自然积累。另外定期检查一下 Neo4j 和 Postgres 的存储占用长期跑下来数据量会增长虽然不大但心里有数比较好。如果你在配置过程中卡在某个报错或者想确认某个 Model ID 是否可用接入文档里有完整的参数说明地址是https://taotoken.net/doc。模型对话页面也可以用来快速验证通道是否正常地址是https://taotoken.net/model-chat。把记忆系统跑成日常基础设施之后你会发现 Agent 的体验完全不一样了它不再是每次从零开始的工具而是一个真正记得你的助手。