AI Agent 持久记忆实战：Claude Code 接入 MemMachine 全流程

在做 AI Agent 的过程中，模型越强、工具链越完善，但 Agent 却依旧像个"七秒记忆"的金鱼。只要你关闭对话框、上下文 token 一溢出，它立刻忘记你是谁、你喜欢什么、你昨天让它做了哪件事。对于任何需要长期跟踪、持续协作的场景而言，这几乎就是致命缺陷。

文章配图

直到最近，在 GitHub 上看到一个开源项目 —— MemMachine。

项目开源地址：https://github.com/MemMachine/MemMachine

把 MemMachine 接入 Claude Code 的那一刻，才第一次觉得 AI 助手真的'活'了。MemMachine 给 Agent 装上了一层独立于模型之外的"持久化大脑"，不仅能跨会话记忆用户偏好，还能自动结构化信息、持续进化，而且可以本地部署、完全私有，不会随着模型切换而丢失。更惊喜的是，通过 MCP 协议，它能在 Claude Code 中做到即插即用，让你的 Agent 从第一天起就具备'越聊越懂你'的能力。

文章配图

下面记录整套流程：从零部署 MemMachine，到通过 MCP 接入 Claude Code，再到实际写入用户偏好、跨会话成功调用记忆。整个过程顺滑得多，最终效果也远超预期。

1️⃣ 为什么开始研究 AI 长期记忆？

为了验证 MemMachine 是否真的能改变 AI 的交互方式，准备了一个非常现实、但同时又极度考验记忆系统的测试场景——让 Agent 记住用户的完整饮食偏好。

从喜好口味、忌口食材，到三餐作息、营养目标、减脂计划，把一整段像现实生活中'第一次自我介绍'那样的信息交给了 Claude Code，让它通过 MemMachine 自动解析、提取并写入档案记忆。在传统的 LLM 中，这些内容通常会随着窗口关闭而消失，但这一次结果完全不同：隔天再次打开对话、随口问一句'今晚吃什么比较好？'它不仅记得我喜欢辣、不吃香菜、控制碳水，还能根据增肌目标反推蛋白质摄入建议——而这些信息，是在昨天的另一场会话里告诉它的。

文章配图

正因为这个体验如此震撼，意识到：MemMachine 并不是 RAG 的替代品，而是 Agent 能否进入'长期协作'时代的真正分水岭。它让 AI 不再是即时回答工具，而是一个可以理解你、陪伴你、根据你持续变化的喜好主动调整行为的数字伙伴。而且，这一切都可以通过本地部署完成，隐私可控、架构简单，也不依赖任何特定模型。

接下来，把整个过程拆解成一套可完全复现的实战教程：从 MemMachine 的部署、到 MCP 接入、到 Claude Code 内的真实记忆写入，再到最终的跨会话查询，全部一步步带你搭建起来。

2️⃣ 什么是 MemMachine？

MemMachine 可以简单理解为：一个独立于模型之外的'长期记忆服务'。它不负责生成内容，也不和你的 LLM 混在一起，它只做一件事——把用户的重要信息存下来、管起来、长期提供给 Agent 调用。

不同于传统把聊天记录塞进向量库的做法，MemMachine 会自动把信息拆成'事实''偏好''习惯''事件'等结构化内容，并存到自己的数据库里。这样，不论你换模型、换会话、甚至隔一天再来，它都能让 Agent 恢复到正确的'理解用户的状态'。

文章配图

MemMachine 并不是一个'概念'，而是一个真正能 本地部署、直接运行、开箱即用 的开源服务。只要把它跑起来，再通过 MCP 接进 Claude Code，你的 Agent 就立刻拥有跨会话、不丢失、不遗忘、可更新的长期大脑。

接下来，直接动手，从部署开始，把这个 '长期大脑' 装到你的 AI Agent 身上。

3️⃣ 部署安装 MemMachine（Docker 版）

MemMachine 是一个独立服务，需要先把它在本地或服务器跑起来。部署非常简单，只要会用 Docker 就能在 3 分钟内启动。

步骤 1：准备 Docker

在部署 MemMachine 之前，确保环境中已经安装：

Docker Engine
Docker Compose（v2 版本，已集成在 Docker Desktop 中）

这两个工具是整个服务运行的基础。

docker --version
docker compose version

文章配图

步骤 2：准备 Claude Code

在将 MemMachine 与 Claude Code 集成之前，需要先在本机正确安装并配置 Claude Code 环境。Claude Code 并不是 VSCode 默认提供的功能，它依赖 Node.js 18+ 和 Git。

检查本机 Node 版本：

node -v

文章配图

Claude Code 部分功能需要依赖 Git，例如代码模板初始化、版本控制等。

检查本机 Git 版本：

git --version

文章配图

Claude Code 提供命令行工具，必须提前安装，若已经安装好可验证安装：

claude --version

文章配图

步骤 3：本地部署 MemMachine

官方提供了多种方式的部署方法，这里推荐使用 Docker 来部署。

首先得准备好一个 OpenAI 的 API Key（当然也可以魔改成国内 api_key，后面会讲到，提供必要的源码），我们可以来到 OpenAI 的 API 平台上 https://platform.openai.com/api-keys，点击创建 API Key，就可以得到一个 sk 开头的 API 了，不过记得查看有没有额度哟~

文章配图

如果 API 也有了，就可以正式开始部署了。接着我们需要创建一个文件夹，比如我的路径如下：<project_path>/MemMachine

文章配图

打开 PowerShell，输入以下命令：

$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-components=1
Set-Location $destination

文章配图

进入到这个目录下，打开 Git Bash，运行以下命令：

./memmachine-compose.sh

第一步：选择 Docker 是哪种配置的（CPU/GPU），使用默认的 CPU 就行。

文章配图

第二步：使用哪个模型供应商，默认使用 OpenAI 就行。

文章配图

第三步，使用 OpenAI 的什么模型，默认 [gpt-4o-mini] 的就行了。

文章配图

第四步，embedding 模型也同样，默认即可。

文章配图

第五步，设置 API Key，输入 Y 并填写好刚刚创建好的 API Key 就可以了。

文章配图

最后一步呢，只需要等待它自行安装完成。

文章配图

在命令行中输入这个命令，检查一下是否安装成功。

curl -v http://localhost:8080/health

文章配图

如果返回：{"status": "healthy"}，说明 MemMachine 安装成功！

步骤 4：接入 Claude Code

这是关键步骤，也是很多人卡住的地方。

Claude Code 的所有插件、记忆层、外部工具都必须通过 MCP（Model Context Protocol） 接入。MemMachine 官方提供了标准的 MCP 服务端。

在原本的文件夹目录下创建一个 .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"
      }
    }
  }
}

然后进入到命令行中进行测试。

claude

进入到 Claude 界面中，输入'/mcp'，可以看到，MemMachine 已经记录到了 Claude 里面了。

文章配图

步骤 5：将'饮食习惯'写入记忆并读取

接下来，要进行整个流程中最关键的实战演示：**让 Claude 将一段真实的用户信息写入 MemMachine，并在下一次会话中成功取回这些长期记忆。**这将直接验证 MemMachine 是否真正具备跨会话记忆能力，也验证 Claude Code 是否能通过 MCP 正确读写长期档案。

为了测试，会让 Claude 记住一段典型的'用户档案信息'，包含饮食偏好、忌口、三餐作息、生活习惯以及健康目标等内容——这些信息非常适合用来展示 MemMachine 的结构化记忆能力。下面这段话，就是我们将发送给 Claude，让它写入长期记忆的示例文本：

'您好，请记住我的饮食习惯，其中，我喜欢吃辣的，尤其是川菜和湘菜。我不吃香菜，也不喜欢海鲜，特别是贝类。我更喜欢家常炒菜，不喜欢油炸食品。我通常早上 7 点吃早餐，中午 12 点半午餐，晚上 7 点晚餐。我习惯先喝汤再吃饭，吃饭时喜欢看视频。我在控制碳水摄入，尽量不吃白米饭和面条。我的目标是增肌，需要多摄入蛋白质，每天至少 120 克。我想减到 65 公斤，所以晚餐吃得比较少。就这些了，记住一下。'

发送后，Claude 会自动调用 MemMachine，将这些内容拆解成'偏好''禁忌''作息''营养目标'等结构化字段，并写入 Profile Memory。稍后会关闭会话，再通过一个新的对话验证，这些信息是否真的被长期记住并能被智能调用。

文章配图

关掉这个终端命令，重新打开一个，又进行提问。比如：我一天的用餐时间

文章配图

4️⃣ 配置中转 API

有些同学可能会遇到一个常见问题：'我没有 OpenAI 的 API Key，那还能用 MemMachine 吗？'

当然可以。我们完全可以把模型调用切换为其他兼容 OpenAI 协议的 API，只需要对 MemMachine 的代码和配置做一点修改，就能顺利跑起来。接下来会一步步带你完成这项修改。

第一步，需要进入 MemMachine 项目目录，找到 configuration.yml 文件，并对其中的模型配置进行调整。参考示例如下：

logging:
  path: /tmp/memory_log
  level: info
long_term_memory:
  derivative_deriver: sentence
  metadata_prefix: ""
  embedder: openai_embedder
  reranker: my_reranker_id
  vector_graph_store: my_storage_id
  SessionDB:
    uri: sqlitetest.db
  Model:
    gpt:
      model_vendor: openai-compatible
      model: "gpt-5.1"
      api_key: "sk-xxx"
      base_url: "https://your-api-provider.com/v1"
  storage:
    profile_storage:
      vendor_name: postgres
      host: postgres
      port: 5432
      user: memmachine
      db_name: memmachine
      password: memmachine_password
  profile_memory:
    llm_model: gpt
    embedding_model: openai_embedder
    database: profile_storage
    prompt: profile_prompt
  sessionMemory:

在修改 configuration.yml 时，请特别注意其中的这一项：api_key: "sk-xxx"，这里的 sk-xxx 必须替换成你自己的真实 API Key，否则 MemMachine 将无法正常调用模型服务。修改完成后记得保存文件，并重新启动服务以使配置生效。

在配置 MemMachine 的模型服务之前，我们需要先在支持 OpenAI 协议的中转 API 平台申请一个可用的 API Key，用于替代 OpenAI 的原生 Key。只需要简单几步，即可完成授权与配置。

创建令牌时，'名称'可以随意填写，例如我填写的是 MemMachine。 '分组'建议选择 优质官转 OpenAI，接着会在 MemMachine 的配置文件中填写模型名称，中转平台会根据模型自动路由到正确的接口。

你还可以为这个令牌设置额度限制，例如设置 50 元 作为上限，确保 MemMachine 的调用不会意外消耗过多费用。如果你希望不限额度，也可以选择无限制。但无论哪种方式，请记得在 「钱包」 中充值，否则 API 将无法调用。

创建完成后，系统会生成一个 API Key。把这个 Key 复制下来，稍后需要把它写入 MemMachine 项目的配置文件中。

在 MemMachine 中使用中转 API 时，一般填写以下两项内容：

Base URL：https://your-api-provider.com/v1
api_key：复制你刚生成的 Key，例如：sk-xxxxxx

修改完成后保存，并重启 MemMachine，即可让其使用中转 API 平台作为模型服务来源。

文章配图

在调整完 configuration.yml 之后，记得同时修改项目根目录下的 .env 环境变量文件。其中最关键的是这一项：OPENAI_API_KEY=sk-xxx，请务必将 sk-xxx 替换成你实际使用的 API Key，否则 MemMachine 在调用模型时会因为认证失败而无法正常运行。修改完成后保存文件，再重新启动服务即可。

# =============================================================================
# PostgreSQL / pgvector Database Configuration
# =============================================================================
POSTGRES_HOST=postgres
POSTGRES_PORT=5432
POSTGRES_USER=memmachine
POSTGRES_PASSWORD=memmachine_password
POSTGRES_DB=memmachine

# =============================================================================
# Neo4j Database Configuration
# =============================================================================
NEO4J_HOST=neo4j
NEO4J_PORT=7687
NEO4J_USER=neo4j
NEO4J_PASSWORD=neo4j_password
NEO4J_HTTP_PORT=7474
NEO4J_HTTPS_PORT=7473

# =============================================================================
# MemMachine Configuration
# =============================================================================
MEMORY_CONFIG=configuration.yml
MCP_BASE_URL=http://memmachine:8080
GATEWAY_URL=http://localhost:8080
FAST_MCP_LOG_LEVEL=INFO

# =============================================================================
# OpenAI / Compatible API Configuration
# =============================================================================
# GPT-5.1 LLM 和 Embedding 模型都使用这一把 key
OPENAI_API_KEY=sk-xxx
# 您的 API 中转平台基础 URL
OPENAI_BASE_URL=https://your-api-provider.com/v1

# =============================================================================
# MemMachine Optional Settings
# =============================================================================
LOG_LEVEL=INFO
MEMORY_SERVER_PORT=8080
# 数据库连接池
DB_POOL_SIZE=10
DB_MAX_OVERFLOW=20
# 镜像版本
MEMMACHINE_IMAGE=memmachine/memmachine:latest-cpu

在修改完配置文件和环境变量后，一定要重新构建并启动 MemMachine 服务，使最新的配置生效。请进入项目目录，然后依次运行以下两条命令：

docker-compose down
docker-compose up -d --build

文章配图

第一条命令会停止并卸载旧的容器，第二条命令会在重新构建镜像后以后台方式启动服务。完成重启后，你的 MemMachine 就已经加载了新的模型配置，这时就可以打开 Claude，开始愉快地体验带'长期记忆'的智能体啦！

5️⃣ 写在最后

至此，已经完整地为 Claude Code 装上了真正意义上的'长期大脑'：MemMachine 不仅让 AI 具备跨会话记忆能力，更让它能够随着你的使用不断学习、更新和完善自己。从部署、配置、接入 MCP，到写入用户的信息并在下一次对话中成功取回，这套流程跑通之后，你会明显感受到——AI 已经从一个'即时回答工具'，升级成了一个真正会'记住你'的智能助手。

AI Agent 持久记忆实战：Claude Code 接入 MemMachine 全流程