安装指南¶

Grok mem — Grok Mem 是 Grok Bot 记忆的方式。与 Grok 自身的记忆并列。不取代它。包名仍然是 claude-mem。

快速开始¶

选项 1：Grok Bot¶

Grok Bot 没有宿主钩子。可独立于 Cursor 或 Claude Code 安装。默认为 CMEM Pro，即托管记忆：

npx claude-mem install --ide grok-bot

本地宿主登录观察器为可选：--provider host。--ide 是单个字符串——第二个宿主需要第二条安装命令。安装此插件不会安装 Cursor。参见 Grok Bot 集成。

选项 2：npx¶

使用单个命令安装并配置 Claude-Mem：

npx claude-mem install

交互式安装程序分三个阶段运行——先安装运行时，再登录，然后选择你的记忆提供方：

选择智能体并安装运行时。 预选已检测到的智能体，包括 OpenCode、OMP、Cursor 和 Codex CLI。仅当你选择 Claude Code 且系统中未找到时，才会提供安装 Claude Code 的选项。如果宿主下载或安装失败，会返回智能体选择界面，以便你重试或选择其他智能体。然后检查 Bun 和 uv，将插件文件复制到市场目录，注册插件，安装依赖项，并将 claude-mem 钩子启动器放入你的 PATH（参见钩子如何到达 claude-mem）。
登录。 对于 --provider claude 会跳过此步骤（记忆在你的 Anthropic 套餐上运行）。CLI 不会询问邮箱。它会启动 OAuth 配对（POST https://cmem.ai/api/installer/oauth/start），打印设备代码 XXXX-XXXX，在浏览器中打开 authorization_url，并持续轮询直到你完成认证。无需银行卡。
选择你的记忆提供方。 CMEM Pro 为预选。 选择它会打开结账/试用 URL，轮询直到账户变为 ready，写入 ~/.claude-mem/settings.json，然后重启 worker。其他选择：个人 OpenRouter、Gemini、Anthropic 套餐，或 --provider host（本地回环观察器）。

无头环境或已登录？参见 CMEM Pro（手动 / 无头）了解安装程序写入的确切设置。

记忆提供方选项¶

CMEM Pro / claude-mem observer（预选） — 记忆通过 https://cmem.ai/api/inference/v1 在套餐外运行，使用模型 cmem-observer。30 天免费试用，之后可订阅或回退。回退是事件驱动的：当网关停止为该账户服务时（额度用尽、订阅失效或密钥被拒绝），会设置 CLAUDE_MEM_PRO_FALLBACK_AT，而不是在试用到期日设置；此后记忆将使用你的 Anthropic 套餐。参见 CMEM Pro（手动 / 无头）。
你的 OpenRouter 密钥 — 记忆在你的 OpenRouter 额度上于套餐外运行。留空 base URL（或使用 https://openrouter.ai/api/v1）。切勿将个人 sk-or- 密钥发送到 cmem.ai 推理网关。
Gemini API 密钥 — 记忆在你的 Gemini 密钥上于套餐外运行。
Anthropic 套餐（--provider claude）— 记忆共享你的 Claude 套餐用量。跳过登录步骤；本地安装会在注册时联系 cmem.ai 一次，以创建登录链接，仅发送数字形式的用量摘要（观察次数和 Token 总数，不包含提示词、路径或项目名称），除此之外不向 cmem.ai 发送任何内容。会提示选择用于压缩观察结果的 Claude 模型（Haiku / Sonnet / Opus）。
宿主观察器（可选） — --provider host 通过本地回环使用已登录的智能体。无需 API 密钥。参见 Grok Bot 集成。

交互式 --provider claude 会跳过登录步骤。非交互式运行（没有 TTY，例如由 AI 智能体运行安装程序）在全新安装时若未指定 --provider，默认使用 Anthropic 套餐；否则复用已配置的提供方。每次跳过登录的非交互式安装都会在最后打印一个可选的登录链接；该链接为尽力而为，绝不会阻塞或改变退出状态，并且在设置了 CI 时会被跳过。本地安装会在注册时联系 cmem.ai 一次，以创建登录链接，仅发送数字形式的用量摘要（观察次数和 Token 总数，不包含提示词、路径或项目名称）；除此之外不向 cmem.ai 发送任何内容。你可以随时通过重新运行 npx claude-mem install，或手动编写设置（手动 / 无头）来完成 CMEM Pro 配对。

选项 3：插件市场¶

直接从 Claude Code 内的插件市场安装 Claude-Mem：

/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem

两种方法都会自动配置钩子并启动 Worker Service。启动新的 Claude Code 会话，你会看到来自之前会话的上下文自动加载。

仅通过市场安装没有安装程序步骤，因此插件会在第一次会话启动时自行放置 claude-mem 启动器（见下文）。该第一次会话可以在启动器编译期间在没有记忆上下文的情况下运行；下一个会话则会有。运行一次 npx claude-mem install 可避免该空档。

重要： Claude-Mem 发布在 npm 上，但运行 npm install -g claude-mem 只安装 SDK/库。它不会注册插件钩子或启动 Worker Service。始终通过 npx claude-mem install 或上面的 /plugin 命令安装。如果全局 npm claude-mem 在 PATH 中位于钩子启动器之前，会遮蔽启动器；参见故障排除。

钩子如何到达 claude-mem¶

每个 Claude Code 钩子都是一条不带 shell 的短命令：claude-mem hook claude-code <event>（worker 启动条目是 claude-mem start）。Claude Code 会在 PATH 中查找 claude-mem 并直接运行它，因此运行时钩子无需任何平台上的 bash，Windows 也无需 Git Bash 来运行钩子。唯一的例外是 Setup 钩子，它仍然通过 bash 运行，但只在 claude --init / --maintenance 时触发。

此 exec 形式（"command": "claude-mem", "args": [...]）需要 Claude Code 2.1.139 或更高版本。较旧的 Claude Code 会忽略 args，直接运行不带参数的 claude-mem，它只会打印用法信息，因此不会捕获任何记忆。npx claude-mem install 和 npx claude-mem doctor 在检测到 Claude Code 版本较旧时会发出警告；可使用 claude update 进行更新。

此处的 claude-mem 是一个小型编译启动器（launcher），而非 npm CLI。它会找到已安装的插件，在 Bun 下运行钩子，并在任何失败时以退出码 0 结束，因此绝不会阻塞会话。

	启动器的安装位置	PATH
macOS / Linux	`~/.local/bin/claude-mem`	如果 `~/.local/bin` 尚不在 PATH 中，则会附加到你的 shell rc 文件
Windows	`%LOCALAPPDATA%\claude-mem\bin\claude-mem.exe`	附加到你的用户 Path

npx claude-mem install 和 npx claude-mem update 会编译并放置它。当已放置的启动器已是最新版本时，它们会跳过编译。
仅通过插件市场安装的情况由额外的 SessionStart 条目覆盖：node ${CLAUDE_PLUGIN_ROOT}/scripts/ensure-launcher.cjs。该条目在启动时运行，当启动器缺失或过期时进行放置或刷新。

如果启动器无法生效，会话启动时会显示：

claude-mem: memory hooks are not active: <reason>. Fix: run `npx claude-mem install`, then restart Claude Code.

更改 PATH 后，请重启你的终端或 IDE，以便 Claude Code 继承新的 PATH。
npx claude-mem doctor 会显示 Hook launcher 行，其中包含 claude-mem 在 PATH 上的解析位置以及它是否为启动器。参见 claude-mem：钩子中找不到命令。
npx claude-mem uninstall 会移除启动器二进制文件。它不会改动你的 shell rc 文件和用户 Path，并会打印需要删除的行。

系统要求¶

Node.js：20.0.0 或更高版本
Bun ≥ 1.0（如果缺失，npx claude-mem install 会自动安装）
uv（如果缺失会自动安装——为 Chroma 的嵌入服务提供 Python）
Claude Code 2.1.139 或更高版本（首个支持 exec 形式钩子 args 的版本），或其他受支持的主机（Cursor、Grok Bot、Windsurf、OpenCode、Codex CLI、Antigravity CLI、OpenClaw）
SQLite 3：通过 bun:sqlite 内置

高级安装¶

如需开发或测试，你可以从源码克隆并构建：

克隆与构建¶

# Clone the repository
git clone https://github.com/thedotmack/claude-mem.git
cd claude-mem

# Install dependencies
npm install

# Build hooks and worker service
npm run build

# Worker service will auto-start on first Claude Code session
# Or manually start with:
npm run worker:start

# Verify worker is running
npm run worker:status

安装后验证¶

1. 自动依赖安装¶

依赖由 npx claude-mem install 和 npx claude-mem repair 自动安装。繁重的工作（安装 Bun + uv、在插件缓存中执行 bun install、编译钩子启动器）会在可见的安装加载指示器（spinner）背后完成。支持在 Windows、macOS 和 Linux 上跨平台运行。

该插件还附带一个 Setup 钩子（version-check.js）：当插件根目录中声明的依赖缺失时，它会在插件根目录运行 bun install，并在依赖安装完成后记录 .install-version 标记。Claude Code 仅在执行 claude --init、claude --init-only 和 claude -p --maintenance 时触发 Setup，绝不会在插件安装、更新或正常会话启动时触发。因此，对于依赖缺失的市场安装，请运行 npx claude-mem install（或 claude --init-only）。Setup 钩子始终以退出码 0 结束。

2. 验证插件安装¶

检查 Claude Code 中的钩子是否已配置，以及启动器是否在 PATH 上：

cat plugin/hooks/hooks.json
command -v claude-mem && claude-mem --version   # prints the launcher protocol number, e.g. 1
npx claude-mem doctor                            # "Hook launcher" row

3. 数据目录位置¶

数据存储于 ~/.claude-mem/： - 数据库：~/.claude-mem/claude-mem.db - PID 文件：~/.claude-mem/.worker.pid - 端口文件：~/.claude-mem/.worker.port - 日志：~/.claude-mem/logs/worker-YYYY-MM-DD.log - 设置：~/.claude-mem/settings.json

可通过环境变量覆盖：

export CLAUDE_MEM_DATA_DIR=/custom/path

4. 检查 Worker 日志¶

npm run worker:logs

5. 测试上下文检索¶

npm run test:context

6. CMEM Pro / 同步¶

curl -s "http://127.0.0.1:${CLAUDE_MEM_WORKER_PORT}/api/health"
curl -s "http://127.0.0.1:${CLAUDE_MEM_WORKER_PORT}/api/sync/status"

参见 CMEM Pro（手动 / 无头模式）。

升级¶

通过插件市场更新时，升级会自动完成。PATH 上的启动器是版本稳定的：它不包含任何 claude-mem 逻辑，因此市场更新不需要新的启动器。当更新确实需要较新的启动器时，启动时的 SessionStart 自愈机制会编译它，而在此过程中，首次会话可能会缺少记忆上下文。npx claude-mem update 会一步完成插件、其依赖和启动器的刷新。如果更新后仍有依赖缺失，请运行 npx claude-mem@latest install。

完整的版本历史请参见 CHANGELOG。

后续步骤¶

入门指南 - 了解 Claude-Mem 如何自动工作
CMEM Pro（手动 / 无头模式） - 精确的 settings.json 键和无头设置
Grok Bot 集成 - 为 Grok Bot 提供持久记忆（无需钩子）
MCP 搜索工具 - 查询你的项目历史
配置 - 自定义 Claude-Mem 行为

本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/claude-mem