mem0-memory-setup

name	mem0-memory-setup
description	为 Hermes Agent 配置 Mem0 外部记忆层。涵盖 pip install、npm CLI 安装、 Agent Mode 注册、Hermes 集成、账号认领、验证、和国内网络/特殊 shell 的排错。 使用场景：用户问"怎么给 Hermes 加记忆"、"装一下 mem0"、"配置外部记忆"、 "memory provider"、"让 Hermes 记住我"。

Mem0 记忆层配置指南

Mem0（"mem-zero"）是开源的 AI Agent 记忆层（Apache 2.0）。Hermes 内置 8 种记忆 provider，其中 Mem0 支持服务端自动事实提取 + 语义搜索 + 实体提权，一行命令接入。

官方文档: https://docs.mem0.ai Hermes 集成文档: https://hermes-agent.nousresearch.com/docs/user-guide/features/memory-providers GitHub: https://github.com/mem0ai/mem0

触发条件

• 用户说"配置记忆"、"装 mem0"、"memory provider"、"让 Hermes 记住我"
• hermes memory status 显示 provider 为 built-in only
• 需要跨会话持久记忆的场景

完整配置流程

Step 1: 安装 Python 包

pip install mem0ai

中国用户（镜像加速）：

pip install mem0ai -i https://pypi.tuna.tsinghua.edu.cn/simple

Step 2: 安装 Mem0 CLI（获取 API Key）

Mem0 CLI 是 npm 包，用于注册 Agent Mode 账号和获取 API Key：

# 安装
npm install -g @mem0/cli

如果报 EACCES（权限错误）：

# 检查当前 prefix
npm config get prefix   # 可能返回 /usr

# 设为用户目录
npm config set prefix ~/.npm-global

# 重新安装
npm install -g @mem0/cli

# 恢复原 prefix（可选）
npm config set prefix /usr

安装完后记得恢复 prefix，否则后续 npm install -g 可能不会安装到预期位置。

PATH 问题（fish / zsh 等非 bash shell）

CLI 装在 ~/.npm-global/bin/mem0。如果是 bash，~/.bashrc 通常已有此行：

export PATH="$HOME/.npm-global/bin:$PATH"

fish shell（通过 bashrc 启动 fish）： fish 继承 bash 的 PATH，通常无需额外配置。验证：

type mem0
# → mem0 is /home/po/.npm-global/bin/mem0

如果找不到，在 ~/.config/fish/config.fish 添加：

fish_add_path ~/.npm-global/bin

Step 3: Agent Mode 注册（无邮箱）

AI Agent 可以直接注册，无需人类邮箱：

mem0 init --agent --agent-caller hermes

说明：

• --agent-caller hermes — 告诉 Mem0 这是 Hermes Agent
• 注册后在 ~/.mem0/config.json 保存 API Key
• 此账号未认领，30 天内可认领到人类邮箱

Step 4: 读取 API Key

python3 -c "import json; print(json.load(open('/home/po/.mem0/config.json'))['platform']['api_key'])"

或直接查看：cat ~/.mem0/config.json

Step 5: 配置 Hermes

写入 API Key 到 .env：

MEM0_KEY=$(python3 -c "import json; print(json.load(open('$HOME/.mem0/config.json'))['platform']['api_key'])")
echo "export MEM0_API_KEY=$MEM0_KEY" >> ~/.hermes/.env

设置 provider：

hermes config set memory.provider mem0

Step 6: 验证

hermes memory status
# → Plugin: installed ✓
# → Status: available ✓
# → Provider: mem0 ← active

Step 7: 测试写入和检索

mem0 add "Test memory: user prefers concise responses"
mem0 search "prefers concise"
# → Found 1 memories:
# → User prefers concise responses in conversations
# → Score: 0.34

Step 8: 账号认领（可选但推荐）

让人类用户认领 Agent 账号，获得 Web 面板和管理权限：

mem0 init --email <your-email>
# 输入邮箱验证码即可
# API Key 不变，所有记忆数据保留

认领后可在 app.mem0.ai 查看记忆数据和管理面板。

Hermes 集成后行为

时机	行为
每轮对话前	Mem0 预取相关记忆注入 system prompt（零延迟，后台完成）
每轮回复后	Mem0 自动提取事实并存储（后台线程，不阻塞对话）
会话结束时	服务端处理存储优化和去重
Circuit breaker	连续 5 次失败后暂停 2 分钟，Agent 继续工作不受影响

可用工具

启用 Mem0 后，Hermes 额外获得 3 个工具（自动调用，无需手动触发）：

工具	功能
mem0_profile	获取所有已存储的用户记忆
mem0_search	语义搜索（支持 rerank + top_k 过滤）
mem0_conclude	手动存储一条事实（不走服务端提取）

内置记忆 vs Mem0

内置记忆（memory/user 工具）始终并行运行，不受影响：

内置记忆:   MEMORY.md + USER.md 文件 → 2 个分区，各 2200 字符上限
Mem0:       云端语义向量库 → 无大小限制，支持语义搜索 + 自动提取

两者互补：内置记忆存静态事实（项目路径、设备参数、偏好），Mem0 存动态学习（用户习惯、工作模式、历史偏好变化）。

已知问题与排错

1. 国内网络

• pip install 超时: 用清华镜像 -i https://pypi.tuna.tsinghua.edu.cn/simple
• npm install 正常: npm 镜像通常够快
• Mem0 Cloud API (api.mem0.ai) 延迟: 国内访问约 0.5-1.5s 延迟，Hermes 用后台预取 + 缓存屏蔽了感知延迟
• 自托管选项: Mem0 支持 Docker 自部署，见 Self-hosted docs

2. mem0 命令找不到

# 检查安装位置
ls ~/.npm-global/bin/mem0
ls /usr/lib/node_modules/.bin/mem0

# 加 PATH
export PATH="$HOME/.npm-global/bin:$PATH"

3. Hermes memory status 显示 not available

检查以下 env var 是否已设置：

grep MEM0_API_KEY ~/.hermes/.env

4. npm 全局安装报 EACCES

npm 默认 prefix 为 /usr，普通用户无写入权限。解法：

npm config set prefix ~/.npm-global
# 之后安装无需 sudo

5. fish shell 下 which 找不到

fish 没有 which 命令。用内置的 type 代替：

type mem0
# → mem0 is /home/po/.npm-global/bin/mem0