Eve MCP 客户端

eve-client 是用于将受支持的 AI 工具连接到托管 Eve 记忆服务的本地安装程序和集成 CLI。

它能够检测本地工具、配置 MCP、在支持的情况下安装由 Eve 管理的提示词和钩子文件、管理身份验证，并可在后续验证、修复或移除集成。它还可以从受支持的客户端导入本地历史记录。

Eve 的工作原理

当你运行 eve install 时，Eve 会配置四个自动运行的生命周期钩子——在会话期间无需任何命令。

生命周期钩子适用于 Claude Code 和 Gemini CLI。Eve 还通过提示词植入连接到 Codex CLI 和其他兼容 MCP 的客户端，因此你可以在所有工具中获得记忆。

Related MCP server: Sovereign Universal Memory MCP

快速入门 — 5 分钟

1. 获取 Eve 工作区

在 evemem.com 申请访问权限。配置完成后，登录并在 evemem.com/app/overview 创建 API 密钥。

2. 安装客户端

uv tool install git+https://github.com/sherifkozman/eve-mcp.git

没有 uv？使用：

pipx install git+https://github.com/sherifkozman/eve-mcp.git

验证：eve version

3. 连接 Claude Code（将 --tool gemini-cli 替换为 Gemini CLI）

eve connect --tool claude-code --api-key <your-eve-api-key>

这结合了身份验证、安装和验证。有关分步说明，请参阅下方的 API 密钥流程。

预期输出：

✓ MCP config written
✓ CLAUDE.md companion updated
✓ Lifecycle hooks configured — Eve auto-injects memory context on every session
✓ Eve memory is connected and responding

刚才发生了什么？ Eve 安装了四个生命周期钩子。从现在开始，每个 Claude Code 会话都将预加载你的记忆上下文，并在结束时捕获新的学习内容。你永远不需要要求 Claude 使用 Eve。

如果 eve connect 失败：运行 eve doctor --tool claude-code 并检查诊断输出。在 github.com/sherifkozman/eve-mcp 提交问题。

4. 测试跨会话记忆

在 Claude Code 中，告诉 Claude：

"记住我使用 PostgreSQL，有一个 users 表——包含 email 和 created_at 列。"

开始一个新的 Claude Code 会话并询问：

"我提到了什么数据库设置？"

Claude 将通过 Eve 回忆起来。✓

请参阅 examples/ 获取手动 MCP 配置片段（无需安装程序）。

安装

在安装客户端之前，请获取一个 Eve 工作区：

• 申请访问权限：https://evemem.com

• 工作区配置完成后，登录 Eve 仪表板：

  • https://evemem.com/app/overview

• 如果你计划使用 API 密钥身份验证，请在连接客户端之前从 Eve 管理员/用户设置流程中创建或轮换租户密钥。

现在从 GitHub 安装

推荐：

uv tool install git+https://github.com/sherifkozman/eve-mcp.git

替代方案：

pipx install git+https://github.com/sherifkozman/eve-mcp.git

或通过独立的 bash 安装程序：

curl -fsSL https://raw.githubusercontent.com/sherifkozman/eve-mcp/main/install.sh | bash

然后确认：

eve version
eve --help

手动配置（无安装程序）

请参阅 examples/ 获取适用于 Claude Code、Gemini CLI 和 Codex CLI 的可直接粘贴的 MCP 配置片段。

稍后从 PyPI 安装

发布后，包安装命令将变为：

uv tool install eve-client

或：

pipx install eve-client

Eve 客户端的功能

• 检测受支持的本地 AI 客户端

• 在更改文件前显示安装计划

• 写入由 Eve 管理的 MCP 配置

• 在支持的情况下安装提示词/配套文件

• 安装四个生命周期钩子，在每个会话中自动注入记忆上下文（SessionStart, UserPromptSubmit, PreCompact, Stop）

• 使用基于文件的凭据存储在本地存储身份验证信息

• 提供 eve memory search 和 eve memory status 命令以直接访问记忆

• 验证、修复、回滚和卸载由 Eve 管理的更改

• 从受支持的客户端将本地对话历史导入 Eve

导入本地历史记录

目前支持的导入源：

• Claude Code

• Codex CLI

• Gemini CLI

核心命令：

eve import scan --source claude-code
eve import preview --source claude-code --path <session_file>
eve import jobs                              # list scan jobs
eve auth login --tool claude-code
eve import upload --job <scan_job_id> --use-auth-from claude-code
eve import runs                              # list upload runs
eve import resume --run <run_id>
eve import cleanup --days 30
eve import cleanup --days 30 --apply

工作原理：

• 解析你机器上的本地历史记录

• 将标准化批次上传到托管的 Eve 服务

• 为扫描作业、上传运行、重放和恢复保留本地 SQLite 分类账

• 默认支持对旧的已完成本地导入运行进行试运行清理

导入器维护：

• eve import cleanup 是一个通用的本地分类账维护命令，不是特定于客户端的导入源功能

身份验证说明：

• 尽可能避免直接在命令行上传递密钥

• 优先使用 eve auth login ...，然后运行导入器命令而无需重复输入 API 密钥

• 在交互式 shell 中，eve auth login --tool claude-code 会安全地提示输入密钥

当前发布说明：

• 正确性和恢复功能很稳健

• 非常大的导入（尤其是 Claude 相关的导入）在批处理默认值持续调整的同时，速度可能仍不如理想

支持的客户端

Claude Code

目前支持：

• MCP 配置

• CLAUDE.md 配套文件

• 包管理的钩子

• 导入器支持：scan, preview, upload, resume

目前主要的身份验证路径：

• Eve API 密钥

Gemini CLI

目前支持：

• MCP 配置

• GEMINI.md 配套文件

• 包管理的钩子

• 导入器支持：scan, preview, upload, resume

目前主要的身份验证路径：

• Eve API 密钥

Codex CLI

目前支持：

• MCP 配置

• Eve 拥有的 OAuth 登录

• 运行时 bearer 令牌注入

• 导入器支持：scan, preview, upload, resume

目前主要的身份验证路径：

• Eve OAuth

重要：

• 原生 Codex MCP 登录不是受支持的 Eve 路径

Claude Desktop

未针对托管的 Eve 在本地自动配置。

身份验证要求

你需要一个 Eve 工作区以及以下任一项：

• Eve API 密钥，或

• 支持流程的 Eve OAuth 访问权限

当前的身份验证预期：

• Claude Code：API 密钥

• Gemini CLI：API 密钥

• Codex CLI：Eve OAuth

OAuth 浏览器流程适用于更多客户端，但它在 Codex 路径之外仍处于实验阶段，不应被视为默认的生产安装流程。

基本用法

首次运行

eve quickstart
eve connect --tool claude-code
eve verify --tool claude-code

API 密钥流程

eve auth login --tool claude-code --api-key <eve-key>
eve install --tool claude-code --apply --yes  # --apply writes config, --yes skips confirmation
eve verify --tool claude-code

Codex OAuth 流程

eve auth login --tool codex-cli --auth-mode oauth
eve install --tool codex-cli --auth-mode oauth --apply --yes
eve verify --tool codex-cli --auth-mode oauth

记忆命令

eve memory search "what database do we use" --context naya
eve memory search "auth patterns" --limit 5 --json
eve memory status
eve memory status --json

常用命令

eve quickstart
eve connect
eve install --dry-run
eve install --apply --yes --tool claude-code
eve status
eve doctor
eve verify
eve repair --tool gemini-cli --apply --yes
eve uninstall --tool claude-code --yes
eve run --tool codex-cli -- exec "Use Eve memory to search for my latest preference."

手动 MCP 配置

如果你不希望安装程序为你编辑客户端配置，请手动添加托管的 Eve MCP 服务器。

共享托管 MCP 端点

https://mcp.evemem.com/mcp

Claude Code / Gemini CLI (API 密钥)

使用 Eve 管理面板中的租户 API 密钥。

{
  "eve-memory": {
    "type": "http",
    "url": "https://mcp.evemem.com/mcp",
    "headers": {
      "X-API-Key": "eve_<tenant>_...",
      "X-Source-Agent": "claude_code"
    }
  }
}

对于 Gemini，保持相同的结构并更改：

X-Source-Agent = gemini_cli

Codex CLI (OAuth)

Codex 应使用 Eve 拥有的 bearer 令牌，而不是原生的 codex mcp login。

[mcp_servers.eve-memory]
url = "https://mcp.evemem.com/mcp"
bearer_token_env_var = "EVE_CODEX_BEARER_TOKEN"
startup_timeout_sec = 60

[mcp_servers.eve-memory.headers]
X-Source-Agent = "codex_cli"

OAuth 资源：

https://mcp.evemem.com/mcp

Codex 提示词植入属于活动项目 AGENTS.md。Eve 在该文件中管理其自己的标记块，而不是创建平行的辅助文件。

其他 MCP 客户端

对于其他远程 MCP 客户端，最小工作配置为：

1. MCP URL：

https://mcp.evemem.com/mcp

2. 一个源代理标头：

X-Source-Agent: your_client_name

3. 选择一种身份验证样式：

• API 密钥：

X-API-Key: eve_<tenant>_...

• OAuth bearer：

Authorization: Bearer <token>

4. 对于支持 OAuth 的客户端，使用此资源标识符：

https://mcp.evemem.com/mcp

5. 所需范围：

memory.read
memory.write

如果客户端支持配套指令文件，请将其指向该工具的活动指令文件，而不是创建第二个平行文件。

使用哪种身份验证路径

• Claude Code：API 密钥

• Gemini CLI：API 密钥

• Codex CLI：Eve OAuth

如果你希望 Eve 为你管理配置、提示词、钩子和验证，请使用 eve connect 而不是手动编辑文件。

安全模型

• 无静默 shell 配置文件变异

• 无未记录的钩子

• 不覆盖用户编写的指令文件

• 变异前进行备份和清单跟踪

• 支持显式回滚和卸载

• 卸载会移除 Eve 管理的凭据和工具条目，并在用户修改的 Eve 拥有的文件需要手动审查时发出警告

开发

运行测试：

uv run pytest --cov=eve_client --cov-report=term-missing -q tests

构建 Python 工件：

uv build .

检查构建工件：

uvx twine check dist/*

构建独立发布工件：

bash scripts/build-eve-client-release.sh

许可证

Apache-2.0。请参阅 LICENSE。