Zep Cloud

Zep Cloud的MCP服务器

通过以下方式给克劳德和Codex留下长期记忆 Zep云 --存储对话、搜索知识图以及跨会话回忆上下文。

先决条件

在获取免费Zep Cloud API密钥 App.etzep.com.

快速开始

克劳德代码（CLI）

claude mcp add zep-cloud \
  -e ZEP_API_KEY=your-key \
  -e ZEP_DEFAULT_USER_ID=your-user-id \
  -- uvx --from git+https://github.com/fshamim/mcp-server-zep-cloud mcp-server-zep-cloud

Codex（命令行界面+桌面）

Codex用途 ~/.codex/config.toml 适用于CLI和桌面。

codex mcp add zep-cloud \
  --env ZEP_API_KEY=your-key \
  --env ZEP_DEFAULT_USER_ID=your-user-id \
  -- /opt/homebrew/bin/uvx --from git+https://github.com/fshamim/mcp-server-zep-cloud mcp-server-zep-cloud

如果客户端仍然显示旧的启动命令，请重新启动Codex，以便重新加载MCP配置。

如果 uvx 已经在你的 PATH，您可以替换 /opt/homebrew/bin/uvx 随着 uvx.

克劳德桌面

添加到您的Claude Desktop配置文件中：

• macOS克劳德桌面: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows克劳德桌面: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "zep-cloud": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/fshamim/mcp-server-zep-cloud",
        "mcp-server-zep-cloud"
      ],
      "env": {
        "ZEP_API_KEY": "your-key",
        "ZEP_DEFAULT_USER_ID": "your-user-id"
      }
    }
  }
}

ZEP_DEFAULT_USER_ID 为所有未显式传递a的工具调用设置用户 user_id.忽略它以回退到 "default_user"桌面应用程序没有技能系统，因此建议使用此环境变量来设置您的身份。

Codex手动配置（可选）

如果您更喜欢直接编辑Codex配置：

[mcp_servers.zep-cloud]
command = "/opt/homebrew/bin/uvx"
args = ["--from", "git+https://github.com/fshamim/mcp-server-zep-cloud", "mcp-server-zep-cloud"]

[mcp_servers.zep-cloud.env]
ZEP_API_KEY = "your-key"
ZEP_DEFAULT_USER_ID = "your-user-id"

安装脚本（克隆+安装）

git clone https://github.com/fshamim/mcp-server-zep-cloud.git
cd mcp-server-zep-cloud
python scripts/install.py

该脚本安装程序包，提示您输入API密钥，并自动配置Claude Desktop。

概念

了解Zep的数据模型可以帮助您正确使用这些工具。

• 用户 (user_id)：存储记忆的身份——人、人工智能代理或任何实体。每个用户都有自己独立的知识图谱。
• 线程 (session_id)：对话或工作会议 *在...之内* 用户的记忆。每个用户有多个线程是正常的；Zep通过知识图自动链接它们之间的事实。
• 图：从用户的所有线程中自动提取实体和关系。可通过以下方式搜索 zep_search_memory，可通过浏览 zep_get_graph_nodes / zep_get_graph_edges.

设置用户标识

每个接触用户数据的工具都接受一个可选 user_id 争论。有三种方法可以设置它，按此优先级顺序应用（最高获胜）：

1.每次工具调用（任何客户）

通过 user_id 直接在工具调用中。这将覆盖该单个调用的所有其他内容：

zep_store_memory(session_id="s1", content="...", user_id="alice")

2.每次会话--仅限Claude Code CLI

跑吧 /zep-context 会话开始时的技能。克劳德会通过的 user_id 在接下来的对话中，对每个Zep工具调用：

/zep-context fshamim

这将覆盖 ZEP_DEFAULT_USER_ID 对于会话，但单个工具调用仍可以进一步覆盖它。

3.服务器默认值——所有客户端

集 ZEP_DEFAULT_USER_ID 作为启动服务器时的环境变量。每个没有显式传递a的工具调用 user_id 将使用此值。回落到 "default_user" 如果没有设置。

克劳德桌面 --在配置JSON中设置它（桌面应用程序没有技能系统，因此建议使用env变量作为默认值）：

"env": {
  "ZEP_API_KEY": "your-key",
  "ZEP_DEFAULT_USER_ID": "fshamim"
}

Codex命令行界面/Codex桌面 --设置它 ~/.codex/config.toml （或使用 codex mcp add --env ...):

[mcp_servers.zep-cloud.env]
ZEP_API_KEY = "your-key"
ZEP_DEFAULT_USER_ID = "fshamim"

克劳德代码 --添加服务器时传递它：

-e ZEP_DEFAULT_USER_ID=fshamim

Codex CLI --添加服务器时传递它：

--env ZEP_DEFAULT_USER_ID=fshamim

即使有 ZEP_DEFAULT_USER_ID 设置后，您或Claude仍然可以随时通过传递 user_id 明确地在工具调用中。桌面应用程序支持这一点——只需让Claude在存储或检索内存时使用特定用户。

故障排除

食品法典： MCP startup failed: No such file or directory

常见原因：

• -e 旗子不小心插进去了 args 而不是使用Codex --env.
• uvx 在上不可用 PATH 对于宿主应用程序进程。

修复：

codex mcp remove zep-cloud
codex mcp add zep-cloud \
  --env ZEP_API_KEY=your-key \
  --env ZEP_DEFAULT_USER_ID=your-user-id \
  -- /opt/homebrew/bin/uvx --from git+https://github.com/fshamim/mcp-server-zep-cloud mcp-server-zep-cloud

本地开发人员： ImportError: cannot import name 'Zep' from 'zep_cloud'

您的环境可能更旧 zep-cloud 包裹。从重新安装 pyproject.toml 约束：

pip install -e .

快速验证服务器

python tests/test_server_tools.py
# requires ZEP_API_KEY in env
python tests/test_v3_compatibility.py

Claude代码集成

自动记忆→ Zep同步（挂钩）

Claude Code为 memory/*.md 会话期间的文件。所包含的钩子会自动将这些写入同步到Zep，以便它们在知识图中持久存在。

设置：

1. 在中设置环境变量 .claude/settings.local.json （gitignored，保持凭据私有）：

{
  "env": {
    "ZEP_API_KEY": "your-key-here",
    "ZEP_USER_ID": "your-user-id-here"
  }
}

1. 通过复制钩子配置来启用钩子 .claude/settings.json 在您的本地设置中，或在中全局配置 ~/.claude/settings.json.

1. 确保 zep-cloud 在Python环境中是可导入的：

pip install zep-cloud
# or, if the server is already installed:
pip install -e .

它是如何工作的： 每当 Write 或 Edit 工具调用，涉及 memory/*.md 文件， hooks/sync_memory_to_zep.py 异步运行。它读取文件内容并将其作为系统消息存储在线程中 claude_code_memory_{ZEP_USER_ID}。如果发生以下情况，钩子会悄无声息地退出 ZEP_API_KEY 或 ZEP_USER_ID 未设置，因此它永远不会干扰正常的Claude Code操作。

可用工具

所有操作用户特定数据的工具都接受可选 user_id 参数（默认为 "default_user").

码头工人

docker build -t mcp-server-zep-cloud .
docker run -e ZEP_API_KEY="your-key" mcp-server-zep-cloud

发展

项目结构

core/
  run_server.py          — Entry point, runs asyncio event loop
  zep_cloud_server.py    — MCP server with 7 tools, stdio transport
  zep_cloud_client.py    — API client wrapping zep-cloud SDK v3
config/
  requirements.txt       — Dependencies (for manual/Smithery installs)
  .env.example           — Template for environment variables
scripts/
  install.py             — Automated setup script
tests/
  test_server_tools.py   — Unit tests (no API key needed)
  test_v3_compatibility.py — Integration tests (requires ZEP_API_KEY)
pyproject.toml           — Package metadata and build config

安装用于开发

pip install -e .

运行服务器

mcp-server-zep-cloud          # via console entry point
python core/run_server.py     # direct execution

运行测试

python tests/test_server_tools.py        # Unit tests (no API key needed)
python tests/test_v3_compatibility.py    # Integration tests (requires ZEP_API_KEY)

许可证

麻省理工学院——见 许可证.