使用说明

Memory MCP Server

统一的内存管理 MCP 服务器，支持 Mem0 Cloud API，可为多个 AI 客户端提供持久化记忆功能。

功能特性

✅ 添加记忆 - 存储用户信息、偏好和上下文
✅ 搜索记忆 - 语义搜索已有记忆
✅ 列出记忆 - 查看所有存储的记忆
✅ 删除记忆 - 删除指定的记忆
✅ 聊天事件入库 - 对话文本自动提取 episodic + preference 结构化记忆
✅ 情绪识别（中文） - 支持常见情绪/口语词识别与强度评分
✅ 降噪限流 - 默认 30 分钟最多 1 条、每日最多 5 条聊天情绪记忆
✅ 跨平台 - 支持 Claude Code、OpenClaw 等支持 MCP 的客户端
✅ Mem0 Cloud - 使用云端 API，无需本地数据库
✅ 一键安装 - 自动配置依赖和环境

PyPI / 自动发布（新增）

本项目已支持标准 Python 打包：

python -m build
python -m twine check dist/*.tar.gz dist/*.whl

CI：.github/workflows/ci.yml（PR / push 自动构建并校验）
发布：.github/workflows/publish.yml（GitHub Release 发布时自动上传 PyPI）
CLI 入口：memory-mcp-server

发布前请先在 PyPI 项目里配置 Trusted Publishing（GitHub OIDC）。

一键安装

Linux/macOS

# 克隆或下载项目
cd memory-mcp-server

# 运行安装脚本
chmod +x install.sh
./install.sh

安装脚本会自动:

✅ 检查 Python 环境
✅ 创建虚拟环境
✅ 安装依赖
✅ 生成配置文件
✅ 测试服务器
✅ 尝试注册 Codex 用户级 MCP (~/.codex/config.toml)

配置

安装完成后,编辑 .env 文件:

nano .env

填入你的配置:

MEM0_BASE_URL=https://api.mem0.ai
MEM0_API_KEY=m0-your-api-key-here
MEMORY_DEFAULT_USER_ID=your-user-id
MEMORY_DEFAULT_AGENT_ID=trinity-main
LOG_LEVEL=INFO

💡 你可以从 platform.mem0.ai 获取 API Key

Claude Code 集成

编辑 ~/.claude.json,添加以下配置:

{
  "mcpServers": {
    "memory": {
      "type": "stdio",
      "command": "/完整路径/memory-mcp-server/claude-code-launcher.sh",
      "env": {
        "MEM0_API_KEY": "m0-your-api-key-here",
        "MEMORY_DEFAULT_USER_ID": "your-user-id",
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

获取完整路径:

pwd

假设输出是 /home/username/memory-mcp-server,则命令为:

/home/username/memory-mcp-server/claude-code-launcher.sh

重启 Claude Code 即可使用。

📖 详细指南: Claude Code 完整指南

Codex 集成

安装脚本会尝试自动注册 Codex 用户级 MCP。如果你需要手动注册，可执行：

codex mcp add memory \
  --env MEM0_BASE_URL=https://api.mem0.ai \
  --env MEM0_API_KEY=m0-your-api-key-here \
  --env MEMORY_DEFAULT_USER_ID=your-user-id \
  --env LOG_LEVEL=INFO \
  -- /完整路径/memory-mcp-server/codex-launcher.sh

查看注册结果：

codex mcp list

📖 详细指南: Codex 集成指南

📚 文档

Claude Code 指南 - Claude Code 集成详细教程
OpenClaw 集成 - OpenClaw 深度集成指南
Codex 集成 - Codex AI 助手集成（可用，实验性）
API 参考 - 完整 API 文档
故障排查 - 常见问题解决

可用工具

memory_add

添加新记忆。

参数：

text (必需): 要记住的文本内容
user_id (可选): 用户ID，默认从环境变量读取
agent_id (可选): Agent ID，默认从环境变量读取（用于分支隔离统计）
scope (可选): 记忆范围/类别，默认 "general"
source (可选): 来源标识，默认 "mcp-server"

示例：

memory_add(
    text="用户喜欢编程，主要使用 Python 和 TypeScript",
    user_id="your-user-id",
    scope="preferences"
)

memory_search

搜索已存储的记忆。

参数：

query (必需): 搜索查询（自然语言问题）
user_id (可选): 用户ID，默认从环境变量读取
agent_id (可选): Agent ID，默认从环境变量读取（用于分支隔离统计）
top_k (可选): 返回结果数量，默认 5
scope (可选): 可选的范围过滤

示例：

memory_search(
    query="用户喜欢什么编程语言？",
    user_id="your-user-id",
    top_k=3
)

memory_list

列出用户的所有记忆。

参数：

user_id (可选): 用户ID，默认从环境变量读取
agent_id (可选): Agent ID，默认从环境变量读取（用于分支隔离统计）
scope (可选): 可选的范围过滤
limit (可选): 返回结果数量限制，默认 20

memory_ingest_chat_event

将聊天文本转成结构化记忆（episodic + preference），并执行降噪限流。

参数：

text (必需): 聊天文本
user_id (可选): 用户ID，默认从环境变量读取
agent_id (可选): Agent ID，默认从环境变量读取
location (可选): 事件来源位置，默认 chat
source (可选): 来源标识，默认 chat-event-pipeline

行为说明：

情绪命中才入库
默认限流：30 分钟最多 1 条；每天最多 5 条
写入两个 scope：episodic 与 preference

memory_delete

删除指定的记忆。

参数：

memory_ids (必需): 要删除的记忆 ID 列表
user_id (可选): 用户ID，默认从环境变量读取

配置选项

环境变量	说明	默认值
`MEM0_BASE_URL`	Mem0 API 地址	`https://api.mem0.ai`
`MEM0_API_KEY`	Mem0 API Key	-
`MEM0_API_MODE`	API 模式 (cloud/oss/auto)	`auto`
`MEMORY_DEFAULT_USER_ID`	默认用户ID	`default`
`MEMORY_DEFAULT_AGENT_ID`	默认Agent ID（可选）	``
`LOG_LEVEL`	日志级别	`INFO`

项目结构

memory-mcp-server/
├── src/memory_mcp_server/
│   ├── server.py                    # MCP 服务器主文件
│   ├── mem0_wrapper.py              # Mem0 客户端包装器
│   ├── schemas.py                   # 结构化记忆 schema
│   ├── emotion_lexicon_zh.py        # 中文情绪词库
│   ├── emotion_scoring.py           # 情绪/强度/重要度打分
│   ├── rate_limit.py                # 聊天记忆限流器
│   └── pipelines/
│       └── chat_event_pipeline.py   # 对话事件入库管道
├── tests/
│   ├── test_agent_id_filtering.py
│   ├── test_emotion_scoring_zh.py
│   ├── test_rate_limit.py
│   └── test_chat_event_pipeline.py
├── venv/                            # 虚拟环境 (安装后生成)
├── .env                             # 配置文件 (安装后生成)
├── .env.example                     # 配置文件模板
├── requirements.txt                 # Python 依赖
├── install.sh                       # 一键安装脚本
├── claude-code-launcher.sh          # Claude Code 启动脚本
├── codex-launcher.sh                # Codex 启动脚本
└── README.md                        # 本文件

手动安装 (如安装脚本失败)

1. 安装依赖

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. 配置环境变量

cp .env.example .env
nano .env  # 编辑配置

3. 测试运行

source venv/bin/activate
python src/server.py

测试

单元测试

python3 -m unittest discover -s tests -p 'test_*.py'

快速脚本测试

# 添加记忆
./add_memory.sh "我喜欢编程"

# 搜索记忆
./search_memory.sh "编程"

# 列出所有记忆
./list_memory.sh

故障排查

问题 1: Python 版本过低

需要 Python 3.8 或更高版本:

python3 --version

问题 2: 虚拟环境创建失败

安装 python3-venv:

# Ubuntu/Debian
sudo apt install python3-venv

# CentOS/RHEL
sudo yum install python3-venv

# macOS
brew install python3

问题 3: MCP 服务器未启动

检查日志:

# 查看服务器日志
source venv/bin/activate
python src/server.py

检查 Claude Code 配置:

cat ~/.claude.json | grep -A 10 memory

问题 4: 记忆未保存到云端

检查 API Key 是否正确
检查网络连接
查看 .env 中的配置

多设备部署

要在多台电脑上共享记忆:

在每台电脑上安装此服务器
使用相同的 API Key
使用相同的 user_id
所有记忆将自动同步到云端

开发路线图

[ ] 添加 SSE/HTTP 传输模式（支持远程连接）
[ ] 添加记忆统计工具
[ ] 添加记忆导出/导入功能
[ ] Docker 镜像打包
[ ] NPX 包发布

License

MIT

Credits

基于 OpenClaw 的 mem0_client.py 改造

支持

遇到问题? 检查:

Python 版本 >= 3.8
虚拟环境已激活
.env 配置正确
API Key 有效

使用说明

Memory MCP Server

功能特性

PyPI / 自动发布（新增）

一键安装

Linux/macOS

配置

Claude Code 集成

Codex 集成

📚 文档

可用工具

memory_add

memory_search

memory_list

memory_ingest_chat_event

memory_delete

配置选项

项目结构

手动安装 (如安装脚本失败)

1. 安装依赖

2. 配置环境变量

3. 测试运行

测试

单元测试

快速脚本测试

故障排查

问题 1: Python 版本过低

问题 2: 虚拟环境创建失败

问题 3: MCP 服务器未启动

问题 4: 记忆未保存到云端

多设备部署

开发路线图

License

Credits

支持

相关 MCP

知识图谱记忆服务器

AI持久记忆MCP服务

AI智能体记忆服务

LLM记忆服务器

AI共享记忆数据库

AI代理记忆存储服务