MemMachine/MemMachine · 上手攻略

  • 仓库：MemMachine/MemMachine
  • 链接：https://github.com/MemMachine/MemMachine
  • 分类：AI 基础设施 · Agent 记忆层
  • 作者：Tom
  • 更新：2026-09-22

一、是什么

MemMachine 是一个面向 AI Agent 和 LLM 应用的开源长期记忆层（Apache 2.0），核心解决"LLM 天生无状态"问题——让 AI 能够在多次对话、不同 session、甚至切换模型后，依然记住用户偏好、对话历史和关键事实。

架构上采用客户端-服务器模式：Server 端管理存储和检索（Neo4j 图数据库存情景记忆，SQL 存用户画像），Client 端通过 Python SDK / REST API / MCP Server 与应用对接。支持 OpenAI、Anthropic、Bedrock、Ollama 等任意 LLM provider。

⚠️ 注意：MemMachine 同时是一个开源项目名，也有一个同名的商业化平台（memmachine.ai），两者相关联但有区别——本攻略覆盖开源仓库本身。

二、解决什么问题

场景痛点：当前所有主流 LLM 都是无状态的——每次对话结束后，AI 就"失忆"了。对于需要跨 session 持续运行的 AI 助手、CRM Agent、个人理财顾问等场景，这严重限制了实用性。

MemMachine 通过三层记忆架构解决这个问题：

记忆类型 描述 存储
Working Memory 当前 session 的短期上下文 内存
Episodic Memory 跨 session 的对话情景记忆（图结构） Neo4j 图数据库
Profile Memory 长期用户事实与偏好 SQL 数据库

结果是：AI 可以在新的 session 中说"您上次提到喜欢靠窗座位，我已记住"——而不需要用户重复。

三、快速安装

3.1 前提条件

  • Docker & Docker Compose
  • OpenAI API Key（用于语言模型和 embeddings，⚠️ 存储在服务器端配置文件）

3.2 安装 Server（Docker 一键启动）

# Linux/macOS
TARBALL_URL=$(curl -s https://api.github.com/repos/MemMachine/MemMachine/releases/latest \
  | grep '"tarball_url"' \
  | head -n 1 \
  | sed -E 's/.*"tarball_url": "(.*)",/\1/')

curl -L "$TARBALL_URL" -o MemMachine-latest.tar.gz
tar -xzf MemMachine-latest.tar.gz
cd MemMachine-MemMachine-*/
./memmachine-compose.sh

# Windows (PowerShell)
$latestRelease = Invoke-RestMethod -Uri "https://api.github.com/repos/MemMachine/MemMachine/releases/latest"
$tarballUrl = $latestRelease.tarball_url
Invoke-WebRequest -Uri $tarballUrl -OutFile "MemMachine-latest.tar.gz"
tar -xzf "MemMachine-latest.tar.gz" -C MemMachine --strip-components=1
cd MemMachine
./memmachine-compose.sh

安装脚本会引导配置 OpenAI API key，完成后服务自动启动。

3.3 验证安装

curl http://localhost:8080/health
# 应返回 healthy 状态

3.4 管理命令

./memmachine-compose.sh start    # 启动
./memmachine-compose.sh stop     # 停止
./memmachine-compose.sh restart  # 重启
./memmachine-compose.sh logs     # 查看日志
./memmachine-compose.sh clean    # 清除所有数据

3.5 安装 Python Client SDK

pip install memmachine-client

四、核心用法

4.1 Python SDK 基本用法

from memmachine_client import MemMachineClient

# 初始化客户端（连接本地服务器）
client = MemMachineClient(base_url="http://localhost:8080")

# 获取或创建项目
project = client.get_or_create_project(org_id="my_org", project_id="my_project")

# 为用户 session 创建记忆实例
memory = project.memory(
    group_id="default",
    agent_id="travel_agent",
    user_id="alice",
    session_id="session_001"
)

# 添加记忆
result = memory.add("I prefer aisle seats on flights", metadata={"category": "travel"})
# 返回: [AddMemoryResult(uid='...')]

# 搜索记忆
results = memory.search("What are my flight preferences?")
print(results.content.episodic_memory.long_term_memory.episodes[0].content)
# => "I prefer aisle seats on flights"

4.2 MCP Server 接入

MemMachine 提供原生 MCP server，支持两种模式：

# Stdio 模式（适合 Claude Desktop）
memmachine-mcp-stdio

# HTTP 模式（适合 Web 客户端）
memmachine-mcp-http

接入后，Claude Desktop 等 MCP 兼容客户端可以直接调用 MemMachine 的记忆能力。

4.3 框架集成

框架 集成方式 说明
LangChain Memory Provider 作为 LangChain Agent 的记忆组件
LangGraph Stateful Memory 为 LangGraph 工作流提供跨节点状态持久化
CrewAI Persistent Memory 为 CrewAI 多 Agent 系统提供记忆持久化
LlamaIndex Memory Integration 集成到 LlamaIndex 应用
AWS Strands Agent SDK Memory AWS Strands Agent SDK 的记忆后端
n8n No-code Workflow 工作流自动化平台集成
Dify Memory Backend Dify AI 应用的记忆后端
FastGPT Platform Integration FastGPT 平台集成

五、典型适用场景

  1. 个人 AI 助手：记住用户偏好（语言风格、专业术语、常用上下文），跨 session 持续进化
  2. CRM Sales Agent：记住客户历史、跟进记录、偏好沟通方式，每次对话无缝衔接
  3. Healthcare Navigator：记住患者病史、用药记录、治疗进展，支持长期跟踪
  4. Personal Finance Advisor：记住用户风险偏好、投资目标、资产配置习惯，提供个性化建议
  5. Writing Assistant：学习用户写作风格、常用词汇、一贯格式，保持输出风格一致

六、坑与注意

⚠️ Neo4j + SQL 双依赖

  • Episodic Memory 用 Neo4j 图数据库（需要额外运维）；Profile Memory 用 SQL（PostgreSQL/MySQL）
  • ⚠️ 没有 Docker Compose 管理能力的话，运维复杂度显著上升
  • 本地开发需要同时运行 Neo4j + SQL + MemMachine Server 三个服务

⚠️ OpenAI API Key 必填

  • Server 端配置需要 OpenAI API Key（用于 embeddings 生成和 LLM 调用）
  • ⚠️ Key 以明文/配置文件方式存储，需要确保服务器安全
  • 离线部署需要自建 embedding 服务（当前版本未内置本地 embedding 选项）

⚠️ LangChain/LangGraph 集成成熟度待验证

  • 仓库 README 列出了集成路径，但实际集成代码质量、版本兼容性需要自行测试
  • ⚠️ 如遇到 LangChain 版本不兼容，可能需要降级或等官方修复

⚠️ 存储可扩展性

  • 图数据库存储情景记忆，查询性能依赖 Neo4j 调优；数据量大时需要配置索引
  • 暂无内置的数据导出/迁移工具（⚠️ 如果需要换存储后端，当前没有平滑迁移路径）

⚠️ 与同名商业平台的边界

  • 开源仓库（Apache 2.0）与 memmachine.ai 商业平台是不同的产品
  • 商业平台有额外的托管服务、UI 界面和支持；开源版本需要自行运维

⚠️ 中文文档有限

  • 主要文档和社区讨论为英文；中文资料较少，调试和问题解决需要依赖英文社区

七、与同类对比

工具 存储 开源 多模态记忆 框架集成 部署方式
MemMachine Neo4j + SQL ✅ Apache 2.0 Working + Episodic + Profile LangChain/LangGraph/CrewAI 等 自托管 / Docker
mem0 多种 部分开源 语义 + 关系记忆 LlamaIndex/LangChain 云 / 自托管
letta-ai PostgreSQL ✅ 状态 + 记忆 原生 API 自托管 / 云
Cognee 多种 ✅ 记忆 + 知识图谱 LlamaIndex 自托管
nvidia/ai-memory PostgreSQL ✅ 简单记忆 有限 自托管

MemMachine 的差异化在于三层记忆架构（Working/Episodic/Profile 分层清晰）+ 图数据库做情景记忆（适合复杂关联查询）+ 多框架集成路径完整。劣势在于运维复杂度较高（Neo4j 强依赖）。

八、一句话推荐结论

如果你需要为 AI Agent 构建真正的长期记忆能力，且对图结构的情景记忆（"上次发生了什么"）和 SQL 结构的事实记忆（"用户喜欢什么"）有明确区分需求，MemMachine 是目前集成度最高、框架支持最全的开源方案——代价是运维复杂度（Neo4j + SQL 双依赖）和较高的接入门槛。