1. Mem0 团队共享 AI Agent 记忆系统 Wiki

生成日期: 2026-07-08
适用对象: 想把 Mem0 部署在服务端, 给团队成员使用的 AI Agent 提供共享长期记忆能力的团队。

1.1. 项目定位

Mem0 是面向 AI 应用和 AI Agent 的长期记忆层。它负责把用户偏好、项目约定、历史决策、任务经验等信息沉淀为可检索的 memory, 并在后续对话或任务中按语义搜索召回。

它不是传统笔记系统, 也不是文档知识库。更准确的定位是:

AI Agent / Chatbot / Coding Assistant
        |
        | add / search / update / delete memories
        v
Mem0 Memory Service
        |
        | text facts + metadata + embeddings
        v
Postgres + pgvector

如果团队目标是让 Codex、Claude Code、Cursor、OpenCode、内部 Agent 等工具跨会话记住团队约定、项目背景和个人偏好, Mem0 比 Memos 这类人类笔记工具更合适。

1.2. 适合解决的问题

Mem0 适合:

• 给 AI Agent 增加跨会话长期记忆。
• 记住用户偏好, 如代码风格、回答偏好、常用技术栈。
• 记住项目约定, 如目录结构、测试命令、部署方式、禁用方案。
• 记住团队决策, 如某模块采用 PostgreSQL、某 API 不能变更。
• 让多个 AI 工具通过统一后端共享记忆。
• 支持按 user_id、agent_id、app_id、run_id 等维度隔离或共享记忆。
• 通过自托管 MCP、SDK 或 REST API 接入不同类型的 Agent。

不适合:

• 替代 Confluence、Notion 这类人工维护的团队知识库。
• 作为多人实时协同文档系统。
• 直接让所有团队成员手工编辑底层数据库。
• 无设计地把所有团队记忆混进一个全局池。

1.3. 核心功能

1.3.1. 记忆写入

Mem0 可以从文本或对话消息中提取记忆。常见写入内容包括:

• 用户偏好: "Alice prefers concise technical answers."
• 团队规范: "This repo uses pnpm, not npm."
• 项目决策: "Auth service uses RS256 JWT."
• 反模式: "Do not modify generated proto files manually."
• 任务经验: "The test suite requires Docker before integration tests."

写入方式:

• SDK: MemoryClient.add(...)
• MCP tool: add_memories
• 自托管 REST API

1.3.2. 语义搜索

Mem0 会为记忆生成 embedding, 用语义检索召回相关记忆。新版本还强调混合检索能力, 包括语义、关键词、实体和时间相关信号。

常见搜索方式:

• SDK: MemoryClient.search(...)
• MCP tool: search_memory
• 自托管 REST API

1.3.3. 记忆管理

支持:

• 获取单条 memory
• 列出 memories
• 更新 memory 文本
• 删除单条 memory
• 删除某个 scope 下全部 memories
• 删除 user / agent / app / run entity 及其关联 memories
• 查看请求日志和 memory dashboard, 取决于部署形态

1.3.4. 多维度 Scope

推荐使用多层 scope, 不要把所有信息都放在一个 user_id 下。

推荐默认检索策略:

当前用户个人记忆
+ 当前项目记忆
+ 团队共享记忆
+ 当前任务/会话短期记忆

1.4. 存储方式

Mem0 的 memory 不是 Markdown、JSON 或 YAML 文件。它是数据库型记忆服务。

1.4.1. 记忆正文

每条记忆是提取后的文本事实, 通常作为向量数据库 payload / metadata 中的 data 或 memory text 存储。

常见字段:

• memory 文本
• hash
• created_at
• updated_at
• text_lemmatized
• user_id
• agent_id
• app_id
• run_id
• categories
• metadata

1.4.2. Embedding 向量

每条记忆会对应一个 embedding 向量, 用于语义搜索。它通常是 float 数组, 存在向量数据库或 pgvector 中, 不适合人工编辑。

1.4.3. 历史记录

OSS library 默认有 history DB, 用于记录 ADD / UPDATE / DELETE 历史。自托管 server 场景主要使用 Postgres / pgvector。

1.4.4. 自托管 Server 默认栈

本地仓库的 self-hosted server 使用:

• FastAPI API 服务
• Next.js dashboard
• PostgreSQL 17
• pgvector
• API key 鉴权
• JWT dashboard 登录
• 请求日志

Docker Compose 中 Postgres 镜像为:

pgvector/pgvector:pg17

1.5. 部署方式

1.5.1. 推荐部署选型

1.5.2. 操作系统支持

生产环境建议使用 Linux 服务器。

1.6. 自托管 Server 安装部署

以下基于本地仓库 server/README.md 和 server/docker-compose.yaml。

1.6.1. 前置条件

服务器建议:

• Linux
• Docker
• Docker Compose
• 可访问 LLM / embedding provider, 或已配置本地模型
• 至少一个持久化磁盘卷给 Postgres

1.6.2. 最小部署流程

cd server
cp .env.example .env

编辑 .env, 至少设置:

POSTGRES_PASSWORD=<strong-password>
OPENAI_API_KEY=<your-openai-key>
JWT_SECRET=<random-secret>
ADMIN_API_KEY=<optional-admin-bootstrap-key>
AUTH_DISABLED=false
MEM0_TELEMETRY=false

启动:

cd server
make bootstrap

或浏览器初始化:

cd server
make up

默认地址:

Dashboard: http://localhost:3000
API:       http://localhost:8888
OpenAPI:   http://localhost:8888/docs

生产环境一般需要反向代理:

https://mem0.example.com        -> dashboard
https://mem0-api.example.com    -> API

1.6.3. 认证与安全默认值

自托管 server 默认:

• Dashboard 使用 JWT 登录。
• 程序访问使用 X-API-Key。
• Auth 默认启用。
• AUTH_DISABLED=true 只适合本地开发, 不应在生产使用。
• Dashboard 可以创建、标记、撤销 API keys。
• Requests 页面可以查看 API 请求审计日志。

1.6.4. 运维注意事项

需要关注:

• Postgres 数据卷备份。
• API key 管理和撤销。
• 请求日志增长, 建议定期 prune。
• LLM / embedding provider 的密钥和费用。
• 如果完全内网部署, 要替换默认 OpenAI 模型为本地 LLM 和本地 embedding。
• 如果启用 telemetry, 会发送匿名事件。内网或合规环境建议关闭 MEM0_TELEMETRY=false。

1.6.5. 完全离线部署注意事项

完全离线部署不是只启动 Docker Compose 就结束, 还需要:

• 准备内网 Docker 镜像。
• 使用本地 LLM, 如 Ollama、vLLM、私有模型服务。
• 使用本地 embedding 模型。
• 确认 mem0 server 镜像包含对应 provider 依赖。
• 禁止外部 telemetry。
• 禁止依赖外部托管 MCP, 使用自托管 OpenMemory MCP 路径接入。

1.7. 自托管 MCP 访问方式

自托管 OpenMemory MCP 的用户身份不是由 Agent 每次调用 tool 时传入, 而是从 MCP URL path 中解析。

当前本地实现的 Streamable HTTP 路由是:

/mcp/{client_name}/http/{user_id}

示例:

http://mem0-api.example.com/mcp/codex/http/team-default

服务端会解析为:

client_name = codex
user_id     = team-default

后续 MCP tool 内部通过 context variable 读取 user_id 和 client_name, Agent 调用 tool 时不需要再传 user_id。

SSE 路由也支持同样的路径语义:

/mcp/{client_name}/sse/{user_id}

团队共享场景建议固定使用团队级 user_id, 例如:

/mcp/codex/http/team-default
/mcp/claude-code/http/team-default

个人隔离场景可以给每个成员配置独立 URL:

/mcp/codex/http/alice
/mcp/codex/http/bob

安全建议:

• 自托管 MCP 不应裸露在公网。
• 建议放在 VPN、内网网关、反向代理鉴权或零信任访问之后。
• 团队共享 URL 中的 user_id 相当于 memory scope, 需要统一命名和管理。
• 不建议默认使用 run_id, 否则记忆会被切到更细的会话分区, 后续检索容易漏掉。

1.8. 团队共享架构建议

1.8.1. 推荐架构

团队成员
  |
  | Codex / Claude Code / Cursor / 内部 Agent
  v
自托管 MCP URL
  |
  | /mcp/{client_name}/http/{user_id}
  |
  v
Self-hosted Mem0 Server
  |
  v
Postgres + pgvector

1.8.2. 不推荐的架构

不建议每个团队成员或每个 Agent 各自绕过服务端 MCP, 直接散乱调用不同的 memory scope:

每个 Agent 自己随意传 user_id/app_id
  |
  | 无统一 scope 命名
  v
共享 memory 混乱、难审计、难删除

生产环境建议由管理员在 MCP URL 中固定 client_name 和 user_id, 让 Agent 只调用工具本身。

1.8.3. 推荐 Scope 设计

示例:

user_id = 成员 ID, 如 alice
app_id  = 项目 ID, 如 billing-service
agent_id = 工具 ID, 如 codex
run_id = 单次任务 ID, 如 task-20260708-001

团队公共记忆可以使用:

user_id = team-default
app_id = <project>

或业务后端自定义:

metadata.scope = "team"
metadata.team_id = "platform"
metadata.project_id = "billing-service"

关键原则:

• 个人偏好和团队事实分开。
• 项目记忆和全局团队规范分开。
• 写入团队共享记忆需要规则, 例如明确命令、审批或特定 metadata。
• 删除操作必须谨慎, 团队共享 scope 不应允许普通 Agent 批量删除。

1.9. SDK 能力

1.9.1. Python

安装:

pip install mem0ai

OSS self-hosted library:

from mem0 import Memory

memory = Memory()
memory.add("We use pnpm in this repo.", user_id="team-default")
memory.search("package manager", user_id="team-default")

1.9.2. TypeScript / JavaScript

安装:

npm install mem0ai

常见用途:

• Node.js Agent 后端。
• Next.js API routes。
• 服务端任务调度。

注意: API key 不应放在浏览器端。

1.10. 自托管 MCP 能力

本方案使用自托管 OpenMemory MCP, 不依赖外部托管 MCP, 也不要求 Agent 每次调用 tool 时传 user_id。

1.10.1. MCP URL 约定

Streamable HTTP 路由:

/mcp/{client_name}/http/{user_id}

SSE 路由:

/mcp/{client_name}/sse/{user_id}

client_name 表示调用来源或应用名, 例如:

codex
claude-code
cursor
team-agent

user_id 表示记忆归属 scope, 例如:

team-default
alice
bob
platform-team

团队共享推荐:

http://mem0-api.example.com/mcp/codex/http/team-default
http://mem0-api.example.com/mcp/claude-code/http/team-default

个人隔离推荐:

http://mem0-api.example.com/mcp/codex/http/alice
http://mem0-api.example.com/mcp/codex/http/bob

1.10.2. user_id 如何生效

自托管 MCP server 从 URL path 中取值:

/mcp/{client_name}/http/{user_id}

例如:

/mcp/codex/http/team-default

服务端解析为:

client_name = codex
user_id     = team-default

后续所有 MCP tool 内部会从 context 中读取这两个值:

user_id_var    -> team-default
client_name_var -> codex

Agent 调用工具时只需要传业务参数, 不需要再传 user_id。

1.10.3. 自托管 MCP 工具清单

本地 openmemory/api/app/mcp_server.py 实现的 MCP tools:

这些工具都会使用 URL 中的 user_id 和 client_name 做隔离、权限判断和访问日志记录。

1.10.4. Claude Code 配置示例

如果 Claude Code 使用自定义 MCP 配置, 指向自托管 URL:

{
  "mcpServers": {
    "mem0-team": {
      "type": "http",
      "url": "http://mem0-api.example.com/mcp/claude-code/http/team-default"
    }
  }
}

个人记忆隔离:

{
  "mcpServers": {
    "mem0-alice": {
      "type": "http",
      "url": "http://mem0-api.example.com/mcp/claude-code/http/alice"
    }
  }
}

1.10.5. Codex 配置示例

编辑:

~/.codex/config.toml

团队共享记忆:

[mcp_servers.mem0_team]
url = "http://mem0-api.example.com/mcp/codex/http/team-default"

个人记忆隔离:

[mcp_servers.mem0_alice]
url = "http://mem0-api.example.com/mcp/codex/http/alice"

如果你的反向代理需要鉴权, 可以在网关层配置 token、basic auth、mTLS 或 VPN。MCP URL path 本身只负责传递 client_name 和 user_id, 不应承担安全边界。

1.10.6. 项目共享 + 个人隔离

如果希望同时实现:

• 项目记忆团队共享。
• 项目无关记忆按用户隔离。

可以给同一个 Agent 配两个 MCP server:

[mcp_servers.project_shared_memory]
url = "http://mem0-api.example.com/mcp/codex/http/project-billing"

[mcp_servers.alice_private_memory]
url = "http://mem0-api.example.com/mcp/codex/http/alice"

含义:

Claude Code 也可以用同样思路:

{
  "mcpServers": {
    "project_shared_memory": {
      "type": "http",
      "url": "http://mem0-api.example.com/mcp/claude-code/http/project-billing"
    },
    "alice_private_memory": {
      "type": "http",
      "url": "http://mem0-api.example.com/mcp/claude-code/http/alice"
    }
  }
}

关键点: Agent 不会天然知道该用哪个 MCP server, 必须在 AGENTS.md、system prompt 或团队规范里写清楚路由规则。

推荐写入 AGENTS.md:

## Memory Routing

Use `project_shared_memory` for project-shared memory:
- architecture decisions
- coding conventions
- test and deploy commands
- API contracts
- bug fixes and debugging learnings
- repo-specific constraints

Use `alice_private_memory` for user-private memory:
- user's communication preferences
- personal coding style preferences
- preferred tools or workflow
- non-project personal facts

When searching context:
- For repo/task questions, search `project_shared_memory` first.
- For user preference or response style, search `alice_private_memory`.
- For ambiguous requests, search both.
- Never store secrets, tokens, passwords, or private credentials.
- Before writing to project-shared memory, only store durable facts useful to teammates.

示例路由:

如果后续希望完全自动判断写入位置, 可以二开一个 memory-router MCP, 由服务端根据内容分类把 memory 写到项目 scope 或个人 scope。当前不二开的方案, 用清晰的 MCP server 名称 + AGENTS.md 路由规则即可。

1.10.7. 调用示例

添加记忆时, Agent 只需要调用:

{
  "text": "团队默认使用 pnpm",
  "infer": false
}

搜索时:

{
  "query": "项目使用什么包管理器"
}

服务端会自动把这些调用落到 URL 对应的 scope:

client_name = codex
user_id = team-default

1.10.8. 验证方式

验证步骤:

1. 配置 Agent 的 MCP URL 为 /mcp/{client_name}/http/{user_id}。
2. 重启 Agent 客户端。
3. 查看 MCP tools 是否出现 add_memories、search_memory、list_memories。
4. 调用 add_memories 保存一条测试记忆。
5. 调用 search_memory 搜索刚才的内容。
6. 登录 dashboard, 查看 memory、request log 和 access log。

如果返回:

Error: user_id not provided

说明 MCP URL 没有按 /mcp/{client_name}/http/{user_id} 配置。

如果返回:

Error: client_name not provided

说明 URL 中缺少 {client_name}。

1.11. 管理与运维建议

1.11.1. Scope 命名

推荐固定命名:

client_name 推荐使用 Agent 或调用方名称:

1.11.2. 安全边界

自托管 MCP URL 中包含 user_id, 但这不是认证手段。生产环境必须额外配置:

• VPN 或内网访问。
• 反向代理鉴权。
• mTLS 或网关 token。
• 访问日志和异常告警。
• 对 delete_all_memories 这类破坏性工具做网关级限制或审计。

1.11.3. 备份与清理

需要定期处理:

• Postgres 数据备份。
• request logs 清理。
• memory 质量审查。
• 误写入 memory 的删除流程。
• 团队共享 scope 的变更记录。

1.12. Skills 清单和使用场景

Mem0 仓库里的 skills/ 是给 AI 编程助手使用的说明包, 不是 Mem0 服务端的 runtime 功能。本自托管 MCP 方案主要关注 SDK、集成和验证相关 skill。

1.12.1. 主 skills

1.12.2. 什么时候用哪个 skill

1.12.3. Plugin skills

integrations/mem0-plugin/skills/ 下还有面向插件 slash command 的 skills。它们主要服务于 AI 编程工具中的 /mem0:* 命令。

1.13. Vercel AI SDK 集成

如果团队 Agent 使用 Vercel AI SDK, 可使用:

npm install @mem0/vercel-ai-provider ai

示例:

import { generateText } from "ai";
import { createMem0 } from "@mem0/vercel-ai-provider";

const mem0 = createMem0();

const { text } = await generateText({
  model: mem0("gpt-5-mini", { user_id: "alice" }),
  prompt: "Recommend a restaurant",
});

工作流程:

1. 调用 Mem0 search 检索相关 memories。
2. 把 memories 注入 system prompt。
3. 调用底层 LLM 生成回答。
4. 异步把对话写回 Mem0。

1.14. 团队使用规范建议

1.14.1. 写入规则

建议把 memory 分为几类:

1.14.2. 共享记忆写入建议

不要让 Agent 自动把所有内容写入团队共享 scope。推荐:

• 个人记忆可以自动写。
• 项目记忆可以半自动写, 但要标注 source 和 confidence。
• 团队共享记忆应显式触发, 如 /mem0:remember 或专门命令。
• 安全、架构、部署类关键 memory 应 pin。
• 定期运行 memory reviewer / dream。

1.14.3. 删除规则

删除操作建议:

• 普通成员只删除自己的 personal memories。
• 项目 memories 删除需要确认。
• 团队共享 memories 删除应有管理员权限或审计。
• delete_all_memories 只能由管理员使用。

1.15. 与 Memos 的区别

推荐组合:

Mem0 负责 AI Agent 长期记忆
Memos 负责人类可读的团队笔记和轻量知识库

1.16. 上线检查清单

上线前确认:

• 使用 self-hosted Mem0 Server。
• 定义 MCP URL 中的 client_name / user_id 命名规则。
• 设计团队共享 user_id, 例如 team-default。
• 设计个人记忆和团队记忆的隔离策略。
• 如需项目共享 + 个人隔离, 为 Agent 配置两个 MCP server: project_shared_memory 和 <user>_private_memory。
• 在 AGENTS.md 或 system prompt 中写明 memory routing 规则。
• 配置 MCP 访问安全边界, 如 VPN、反向代理鉴权、mTLS 或网关 token。
• 配置 Postgres 数据备份。
• 配置日志保留策略。
• 如果内网部署, 确认本地 LLM 和 embedding 可用。
• 为 Codex/Claude Code 配置 /mcp/{client_name}/http/{user_id} URL。
• 确认 MCP tools 出现 add_memories、search_memory、list_memories。
• 用 add_memories -> search_memory -> list_memories -> delete_memories 做 smoke test。
• 制定 memory 清理和审核周期。

1.17. 推荐落地方案

团队服务端共享使用时, 推荐只采用自托管 Mem0 Server + 自托管 OpenMemory MCP。

Codex / Claude Code / Cursor
        |
        | MCP Streamable HTTP
        v
http://mem0-api.example.com/mcp/{client_name}/http/{user_id}
        |
        v
Self-hosted Mem0 Server
        |
        v
Postgres + pgvector

团队共享示例:

Codex       -> /mcp/codex/http/team-default
Claude Code -> /mcp/claude-code/http/team-default

个人隔离示例:

Alice 的 Codex -> /mcp/codex/http/alice
Bob 的 Codex   -> /mcp/codex/http/bob

建议:

• 团队默认先使用 team-default 作为共享 user_id。
• 如果成员个人偏好会污染团队记忆, 再增加个人 URL。
• 自托管 MCP 前面必须有内网或网关鉴权。
• 不在 Agent prompt 中反复解释 user_id, 因为 URL 已经固定 scope。
• 不默认使用 run_id, 避免记忆被切分到单次会话导致搜索不到。

1.18. 参考来源

本地仓库文件:

• /Users/shinerio/Workspace/code/memory/mem0/README.md
• /Users/shinerio/Workspace/code/memory/mem0/server/README.md
• /Users/shinerio/Workspace/code/memory/mem0/server/docker-compose.yaml
• /Users/shinerio/Workspace/code/memory/mem0/server/.env.example
• /Users/shinerio/Workspace/code/memory/mem0/skills/README.md
• /Users/shinerio/Workspace/code/memory/mem0/integrations/mem0-plugin/README.md

官方文档:

• Mem0 open-source overview: https://docs.mem0.ai/open-source/overview
• Mem0 self-hosted setup: https://docs.mem0.ai/open-source/setup
• Mem0 integrations: https://docs.mem0.ai/integrations
• Mem0 MCP: https://docs.mem0.ai/platform/mem0-mcp