Grok Bot 集成¶

你的 Grok Bot 会记住。 Claude-mem 捕获 agent 的行为，将其压缩，并注入到后续会话中。

没有任何 host hooks

Ingest 是 agent JSONL 上的 transcript watcher，而非 Cursor 风格的 hooks。

CMEM Pro 为默认选项

npx claude-mem install --ide grok-bot 会预选 CMEM Pro。--provider host 为可选加入。

独立于 Cursor

可以只安装 Grok Bot、只安装 Cursor，或两者都安装。任一 host 都不依赖另一个。

MCP 搜索

使用三层记忆工具搜索过往会话。

工作原理¶

Grok Bot 没有 session-start、file-read 或 tool-use hooks。Claude-mem 改为接入以下组件：

1. Transcript watcher 会 tail agent-transcripts/*/*.jsonl，并打上 platformSource=grok-bot 标记。
2. Local worker 存储会话并提供搜索服务（默认端口为 127.0.0.1 上的 37700 + uid % 100）。
3. Observer（默认 CMEM Pro） — observation 提取通过 https://cmem.ai/api/inference/v1 使用模型 cmem-observer 在计划外运行。可通过 --provider host 选择加入 host observer（此 Grok 登录通过本地 OpenAI 兼容回环，无需 API key）。
4. MCP 向 bot 暴露搜索功能（search → timeline → get_observations）。
5. 实时时间线 INDEX — 当 observations 落地时，worker 会重写 agents/<agent_id>/memory/log/zz-claude-mem-inject.md。host 已经会在会话中途将该文件作为 Memory facts 附加。文件会持续增长（最新的 ID 滑入；最旧的滑出）。数据稀薄的每席位日志会从最新的全局 observations 中填充，因此即使一个席位只有少量自己的行，也仍能获得有用的 INDEX。
6. Awareness 推送（试点） — 在 observation 存储后，needle 类型会作为一行带日期的事实追加到该 bot 的 Grok 记忆日志（YYYY-MM.md）中。这不是 INDEX。

不要为此 host 安装 Claude CLI。不要传入 xAI API key。没有 --provider grok 标志。

Grok Bot 不使用 Claude Code hook stdin，因此 #2188 空 stdin / CAPTURE_BROKEN 路径不适用。捕获由 transcript watcher 完成。现在每个 watch 都会将 agentId 带入 ingest，从而让 observations 始终带有其来源 bot 的标签。

安装¶

CLI（仅限 Grok Bot）¶

npx claude-mem install --ide grok-bot

这会启动一个 local worker，并以 CMEM Pro 作为 observer（预选）。本地 host 登录 observer 为可选加入：

npx claude-mem install --ide grok-bot --provider host

--ide 只接受单个 host。若还要接入 Cursor，请再运行一次安装（不要在一条命令中传两次 --ide — 只会保留最后一个值）：

npx claude-mem install --ide cursor

其他选项：

# Remote worker
npx claude-mem install --ide grok-bot --runtime server --server-url https://YOUR_HOST

# Remote observer (cmem.ai or any OpenAI-compatible URL)
npx claude-mem install --ide grok-bot --provider openrouter

--provider 仍然接受 claude 和 gemini。传入显式的 --provider 会跳过登录步骤。

插件商店¶

Grok Bot 的插件商店就是 Cursor 目录。当列表上线后（13.24 发布后已提交至 cursor.com/marketplace/publish），请从那里安装 claude-mem-grok-bot。该列表项不会安装 Cursor。

安装插件后，仍需运行上述 CLI 以启动 local worker，或设置 CLAUDE_MEM_MCP_TOKEN 以使用远程 MCP。

Observer 与 worker¶

--provider host 是一个 OpenRouter 形态的回环：CLAUDE_MEM_OPENROUTER_BASE_URL=http://127.0.0.1:<shim>/v1 加上一个非空的虚拟 API key。你不需要手动配置它。

端口规则： observer shim 不得绑定 worker 端口。worker 通常是 37700 + (uid % 100)。在 macOS 上通常是 37777 — 如果该端口被占用，shim 会使用 37778（或 CLAUDE_MEM_HOST_OBSERVER_PORT）。

绝不要重启健康的 worker。observation 队列位于 RAM 中，重启会将其丢弃。

Host-observer 的空闲回复必须是 skip_summary XML；一个完成的单元是一个 observation。像 "still observing" 这样的普通文本会丢弃批次（issue #2485）。

XML 约定（host observer）¶

使用 --provider host 时，worker 解析器只接受三种根元素。

空闲 / 初始化 / 尚无工具结果：

<skip_summary reason="noise" />

已完成的可搜索单元： 一个覆盖整批内容的 <observation> — 真实标题、4–10 条带路径的事实、一段简短叙述。绝不要使用工具名称作为标题。不要混用 skip_summary 和 <observation>。超时必须返回 skip_summary XML，而不是 HTTP 504。

实时时间线 INDEX（Memory 中途附加）¶

Grok Bot 没有 SessionStart hook。worker 会将 Claude Code 在会话开始时获得的同样紧凑的 ID INDEX 写入 host 已经在重新读取的文件中：

agents/<uuid>/memory/log/zz-claude-mem-inject.md

写入者：worker，在存储 observations 之后（防抖）以及 worker 启动时写入一次。当最新行发生变化时，文件会被就地覆盖。它不是一次性的转储。

增长方式：最新的 observation ID 位于顶部，最旧的会在 CLAUDE_MEM_GROK_BOT_INJECT_WINDOW（默认 80）处滑出。每行事实都保留 observation ID，因此 get_observations([IDs]) 仍然可用。

薄座位日记：/api/context/inject?projects=<cmem_work_seat> 仍限定在项目范围内（Claude Code / Cursor 钩子保持不变）。Grok Bot 写入器还会从该 worker 上的最新观察中填充剩余槽位（house feed），因此一个有五条自身记录的座位仍能获得有用的 INDEX。

启用 / 禁用（settings.json 或环境变量；环境变量优先）：

不要写入 profile.md。主机拥有 YYYY-MM.md。CCS TIMELINE.md 分桶不是唯一事实来源。

在 Grok Bot 机器上验证：

# After the worker is healthy and a new observation has landed:
seat=YOUR-SEAT-UUID
root="${GROK_BOT_AGENT_DATA:-$HOME/.grok-bot}"
# If the seat lives under /home/box or Application Support, use that root.
wc -l "$root/agents/$seat/memory/log/zz-claude-mem-inject.md"
grep -n '\[claude-mem\]' "$root/agents/$seat/memory/log/zz-claude-mem-inject.md" | head
# Do more work, wait ~2s, confirm a newer ID appeared at the top.

可选的 scripts/grok-bot-session-inject.mjs 守护进程不是必需的。worker 才是实时写入者。

使用记忆¶

在开始实际任务时，为项目调用 MCP session_start_context，并传入 platformSource grok-bot。

然后进行 3 层搜索：

1. search — 包含 ID 的紧凑索引
2. timeline — 某个命中点周围的上下文
3. get_observations — 仅对你将要使用的 ID 获取完整详情

来自此主机的写入会标记 platformSource=grok-bot。读取时，除非你要求 grok-only，否则不要丢弃 Cursor（或其他主机）的记忆。参见 搜索工具。

验证是否成功¶

1. Worker 健康状态：打开 http://127.0.0.1:<worker-port>/api/health（端口在 ~/.claude-mem/.worker.port 或设置中）。
2. 记忆查看器：打开安装时打印的 worker URL。
3. 在 Grok Bot 中做一小块工作，然后搜索。新观察应显示 platformSource=grok-bot。
4. 默认观察器：第一条实际观察通过模型 cmem-observer 存储。主机观察器：如果队列空闲，回复很可能是普通文本而不是 skip_summary。
5. 实时 INDEX：存储一条观察（此 worker 上的任意项目）后，agents/<this-seat-uuid>/memory/log/zz-claude-mem-inject.md 应新增一条最新的行（- (YYYY-MM-DD) [episode] [claude-mem] <id> …），无需任何人手写该文件。单薄座位项目仍会从最新的 house 行填充。使用 CLAUDE_MEM_GROK_BOT_INJECT_ENABLED=false 关闭。
6. 感知推送试点（LFG + Orifice）：关键观察（decision、bugfix、security_alert、sensitive）应追加 - YYYY-MM-DD [awareness] … 到 agents/<agent_id>/memory/log/YYYY-MM.md。不会写入 profile.md。使用 CLAUDE_MEM_GROK_BOT_AWARENESS_ENABLED=false 关闭。

故障排查¶

没有存储任何内容¶

• 确认 worker 已启动，并且你没有重启一个健康的 worker。
• CMEM Pro：检查 /api/health（provider openrouter）和 /api/sync/status。参见 CMEM Pro（手动 / headless）。
• 主机观察器：确认回复是 XML（skip_summary 或 observation），并且 shim 不在 worker 端口上（macOS：worker 37777 → shim 37778）。

npx claude-mem install --ide grok-bot 被拒绝¶

你使用的是 npm 13.23.x 或更早版本。此功能将在 13.24 中随 PR #3842 落地。

我也使用 Cursor¶

--ide 是单个字符串。为 Cursor 运行第二次安装；不要在一个命令中堆叠 --ide 标志：

npx claude-mem install --ide grok-bot
npx claude-mem install --ide cursor

Cursor 使用钩子（npx claude-mem hook cursor …）和 platformSource=cursor。Grok Bot 仍然没有钩子。参见 Cursor 集成。

这不是 Grok Build¶

Grok Build CLI 市场（xai-org/plugin-marketplace）是另一个目录。此页面仅针对 Grok Bot。

后续步骤¶

• CMEM Pro（手动 / headless） — 默认观察器设置
• 搜索工具 — 查询项目历史
• 配置 — 设置和环境变量
• Cursor 集成 — 如果你同时运行 Cursor