agent-mem0

English

为 Claude Code 提供跨 Session 记忆能力。

Claude Code 每次对话都是全新的 — 它不记得你的偏好、技术决策、项目上下文。agent-mem0 通过 MCP Server 为 Claude 注入持久记忆，让它在新 Session 中也能延续之前的对话上下文。

架构

graph LR
    CC[Claude Code] <-->|MCP / stdio| MCP[MCP Server]
    MCP --> mem0[mem0]
    mem0 --> LLM[LLM<br/>记忆提取 & 冲突检测]
    mem0 --> EMB[Embedder<br/>文本向量化]
    mem0 --> QD[Qdrant<br/>向量存储]

工作原理：

• mem0 负责记忆的语义理解 — 提取关键信息、检测新旧记忆冲突、自动合并更新

• LLM 为 mem0 提供语义能力（判断"用户喜欢用 pytest"和"用户偏好 pytest 框架"是同一条记忆）

• Embedder 将文本转为向量，供 Qdrant 进行相似度搜索

• Qdrant 存储和检索记忆向量，支持 Docker、纯本地和外部连接三种模式

Related MCP server: evermemos-mcp-server

快速开始

前置条件

• Python 3.10+

• Docker（推荐，用于运行 Qdrant）或使用纯本地模式

• Claude Code

1. 安装

pip install mcp-mem0

或从源码安装：

git clone https://github.com/ccperdst-lab/agent-mem0.git
cd agent-mem0
pip install -e .

2. 全局配置（一次性）

交互式向导：

agent-mem0 install

向导会引导你完成：

• 选择 LLM Provider（Ollama / OpenAI / Anthropic / LiteLLM）

• 选择 Embedding Provider（Ollama / OpenAI / LiteLLM）

• 配置 Qdrant 存储模式（Docker / Local / External）

• 自动检测并安装 Ollama、Docker（如需要）

• 自动拉取所需模型和镜像

• 写入配置文件和 CLAUDE.md 记忆规则

非交互模式（CI/自动化）：

# 使用推荐预设（自动检测硬件选择模型）
agent-mem0 install --default

# 指定预设
agent-mem0 install --default --preset cloud --api-key "sk-..."

可用预设：recommended（自动选择）、light（轻量本地）、cloud（云端 API）。

3. 项目配置（每个项目一次）

cd your-project
agent-mem0 setup

这一步会在项目目录下创建：

• .mcp.json — Claude Code 的 MCP Server 配置

• .claude/skills/agent-memory/ — /agent-memory:init Skill

4. 开始使用

启动 Claude Code，记忆系统自动生效。首次可运行：

/agent-memory:init

生成项目级上下文（CLAUDE.md），帮助 Claude 更好地理解你的项目。

功能特性

跨 Session 记忆

Claude 自动记住你的偏好、技术决策、项目上下文。新 Session 开启时自动检索相关记忆，无需重复交代背景。

项目级隔离 + 全局共享

每个项目的记忆互相隔离，同时支持全局记忆（如个人偏好、通用规则）。搜索时项目记忆和全局记忆按相关性统一排序，公平竞争。

智能记忆管理

• 场景驱动的工具选择：5 条强制规则确保 Claude 在正确的时机使用正确的记忆工具

• 冲突检测：修改已有架构/决策时自动检索并更新相关记忆，而不是创建重复记忆

• 搜索管线：宽取候选 → 相关性阈值过滤 → TTL 时间过滤 → score 排序 → 截断返回

• 可选精排：支持 Reranker（sentence-transformer / LLM / Cohere），在向量检索后二次精排提升结果质量

多 Provider 支持

异步写入 & 自动 GC

记忆写入通过后台队列异步执行，不阻塞 Claude 的响应。过期记忆（超过 TTL）在搜索时自动标记，累积到阈值后批量清理。

记忆规则注入

安装时自动向 ~/.claude/CLAUDE.md 写入 5 条强制记忆规则，覆盖 search / add / update / delete / list / history 全部 6 个工具的使用时机，确保 Claude 在每个 Session 中主动管理记忆。

MCP 工具

安装后，Claude Code 可通过以下 MCP 工具操作记忆：

这些工具由 Claude 根据记忆规则自动调用，通常不需要你手动操作。

配置

配置文件路径因平台而异：

采用 shadow config 机制：代码内置完整默认值，用户配置文件只需写你想覆盖的字段。

常见配置场景

使用 OpenAI：

llm:
  provider: openai
  model: gpt-4o-mini
  api_key: "sk-..."

embedder:
  provider: openai
  model: text-embedding-3-small
  api_key: "sk-..."

使用 Ollama（本地部署，无需 API Key）：

llm:
  provider: ollama
  model: qwen2.5:7b
  base_url: http://localhost:11434

embedder:
  provider: ollama
  model: nomic-embed-text
  base_url: http://localhost:11434

使用 LiteLLM 代理（如 Azure OpenAI）：

llm:
  provider: litellm
  model: azure_openai/gpt-4o
  base_url: https://your-litellm-proxy.com
  api_key: "your-key"

调节搜索参数：

memory:
  search_top_k: 20        # 每路搜索候选数量
  search_threshold: 0.3   # 相关性阈值（0 = 不过滤）
  search_max_results: 10  # 最终返回最大条数
  default_ttl_days: 30    # 记忆保留天数

启用 Reranker（可选）：

reranker:
  provider: sentence_transformer
  config:
    model: cross-encoder/ms-marco-MiniLM-L-6-v2
    top_k: 10

需要额外安装：pip install mcp-mem0[reranker]

CLI 命令

常见问题

Q: Qdrant 连接失败

检查 Docker 是否运行：

docker ps | grep qdrant
# 如果没有运行：
docker start agent-mem0-qdrant

或切换到 Local 模式（无需 Docker）：

vector_store:
  mode: local

Q: Ollama 模型拉取失败

确认 Ollama 服务已启动：

ollama list
# 如果未启动：
ollama serve

Q: 代理环境下连接失败

agent-mem0 会自动将本地服务地址（localhost 等）加入 NO_PROXY。如果仍有问题，手动设置：

export NO_PROXY=localhost,127.0.0.1

Q: 如何查看当前状态？

agent-mem0 status

会显示 Qdrant 连接状态、Provider 配置、已注册项目和记忆统计。

License

Apache-2.0