Grok Bot integration
The Grok Bot integration gives Grok Bot access to claude-mem through MCP and transcript capture. It adapts to Grok Bot's lack of native hooks by watching agent transcript files, sending them through the claude-mem memory flow, and exposing search and recall through a packaged plugin.
This page is a child of Agent integrations and distribution. For the shared plugin contract, see Plugin hooks and agent modes. The Cursor integration, Cowork integration, and Installation and NPX CLI pages describe related products and shared install paths.
Integration boundary
The Grok Bot package sits between Grok Bot's agent data and claude-mem's worker or remote service. It does not change Grok Bot itself. Instead, it uses the interfaces that Grok Bot already provides: transcript files for capture and MCP for memory search.
The boundary has three main paths:
| Path | Purpose | Direction |
|---|---|---|
| Transcript watcher | Turns Grok Bot conversations and tool activity into claude-mem observations | Grok Bot to claude-mem |
| MCP server | Lets Grok Bot search and fetch retained memory | Grok Bot to claude-mem |
| Optional host bridge | Places a compact context index into Grok Bot's memory files during a task | claude-mem to Grok Bot |
The package remains independent of Cursor. Installing it does not install or configure Cursor.
Integration flow
This diagram shows how a Grok Bot session becomes searchable memory and how Grok Bot can read that memory later.
flowchart LR
A[Grok Bot session] --> B[Agent transcript files]
B --> C[Transcript watcher]
C --> D[claude-mem worker or service]
D --> E[Stored observations]
F[Grok Bot MCP client] --> G[MCP local or remote endpoint]
G --> D
E --> G
D --> H[Optional host memory bridge]
H --> A
References: claude-mem-grok-bot/README.md• L1-5 claude-mem-grok-bot/…/plugin.json• L1-21 src/…/GrokBotInstaller.ts• L258-285 claude-mem-grok-bot/…/SKILL.md• L7-18
Plugin package
The package is distributed as claude-mem-grok-bot through the Grok Bot or Cursor plugin store. Its manifest points the host to the package's skills and MCP manifest while declaring the small set of values needed for remote MCP access.
The package provides these user-facing capabilities:
- Persistent memory for Grok Bot sessions.
- A layered memory search workflow that starts with IDs and fetches detail only when needed.
- Local MCP through the claude-mem command.
- Remote MCP through
https://cmem.ai/api/mcpwith a bearer token. - Setup guidance for local, host-login, and remote observer choices.
The MCP manifest offers local and remote entries rather than selecting one transport in code. The user or host chooses the entry that matches the selected runtime.
MCP boundary
MCP is the read boundary for Grok Bot. The local entry starts the claude-mem MCP command over the host's process transport. The remote entry calls the cloud MCP endpoint and reads CLAUDE_MEM_MCP_TOKEN for authorization.
The mem-search skill keeps this boundary efficient. It guides Grok Bot from indexed search results to nearby timeline context, then to selected observations, and only then to raw tool calls. This prevents a normal memory question from loading large unsummarized tool data.
References: claude-mem-grok-bot/mcp.json• L1-17 claude-mem-grok-bot/…/plugin.json• L19-35 claude-mem-grok-bot/…/SKILL.md• L7-18
Transcript capture
Transcript capture replaces the hook-based capture used by products that expose session and tool hooks. The installer discovers Grok Bot's agent-data root, adds the Grok Bot transcript schema to the shared watcher configuration, and creates one watch for each usable agent.
The schema gives the memory pipeline enough meaning to relate a user message, an assistant response, a tool call, and its result. Agent names map to stable cmem_work_* project names so each Grok Bot agent has a distinct memory workspace.
When agent profiles are available, the integration watches each agent's transcript directory. If no profiles are present, it uses a catch-all watch. Existing watches for other products remain in the shared configuration, and repeated installation replaces only the Grok Bot watches.
Agent data discovery
The installer first accepts GROK_BOT_AGENT_DATA when the user needs an explicit root. Without it, it checks known Grok Bot data locations and then falls back to the current workspace. This keeps a no-argument install tied to Grok Bot's data rather than accidentally using an unrelated working directory.
The installer also creates missing transcript and project directories. This allows the watcher to start before Grok Bot has produced its first transcript.
References: src/…/GrokBotInstaller.ts• L52-76 src/…/GrokBotInstaller.ts• L82-153 src/…/GrokBotInstaller.ts• L178-235 tests/…/grok-bot-config.test.ts• L23-57 tests/…/grok-bot-config.test.ts• L62-113
Observer modes
The observer turns captured transcript units into searchable observations. Grok Bot supports a hosted observer as the default local setup, an explicit host-login observer, and a remote runtime.
| Mode | Main role | User choice |
|---|---|---|
| CMEM Pro observer | Uses the local worker with the CMEM observer service | Default for grok-bot installs |
| Host-login observer | Uses a local loopback shim and Grok Bot to fulfill observer jobs | Explicit --provider host opt-in |
| Remote worker and observer | Uses the remote claude-mem service and remote MCP | Server runtime with a remote URL |
The default is deliberate. A non-interactive Grok Bot install selects CMEM Pro when no provider is given. The host-login path remains available but is not silently selected.
Host observer contract
The host-observer skill is the response contract for the host-login path. It tells Grok Bot to return either a skip marker for idle work or one complete observation in XML for a finished searchable unit. Prose is not a valid observer result because the local observer loop discards it.
This contract keeps observer output separate from ordinary chat. The worker can then classify the result as a memory observation or as intentional noise without treating user-facing prose as stored memory.
References: claude-mem-grok-bot/…/SKILL.md• L1-17 claude-mem-grok-bot/…/SKILL.md• L8-44 src/…/installer-provider-choice.ts• L4-21 src/…/install.ts• L1084-1169
Setup skill
The claude-mem-install skill is the human-facing setup guide for the Grok Bot boundary. It explains that Grok Bot has no session-start, file-read, or tool-use hooks, then directs the user to the NPX installer and the matching runtime choice.
The default setup starts a local worker, installs the transcript watcher, and configures the CMEM Pro observer. The same skill documents the host-login observer as an explicit alternative and the remote MCP path for users who do not want a local worker.
The NPX CLI applies the Grok Bot provider default at the command boundary. This keeps the plugin's documented default and the non-interactive installer behavior aligned.
References: claude-mem-grok-bot/…/SKILL.md• L1-44 src/…/index.ts• L66-113 src/…/install.ts• L347-359 tests/…/grok-bot-install-default.test.ts• L8-53
Host memory bridge
The optional session-injection bridge delivers a compact, task-time memory index into Grok Bot's own memory files. It uses claude-mem's context-inject response as its source and leaves the host chat path unchanged.
The bridge treats a seat timeline as an editable source and a generated memory log as a cache. When the timeline changes, claude-mem recompiles the newest observation rows and keeps each observation ID so Grok Bot can fetch full details through MCP. It writes only the integration-owned memory file and the seat timeline; protected profile and private files remain outside its write boundary.
The bridge is optional and narrow. Its default agent list is an explicit pilot allowlist. An all-agent mode exists for infrastructure use, but it is not the product default.
Awareness facts
The awareness pusher is a separate, narrow feedback path for selected pilot agents. When enabled, it appends matching observation facts to the agent's dated memory log and deduplicates repeated facts. A failed write is logged and does not fail the main observation flow.
The pusher does not replace MCP recall or the session-injection index. It gives selected agents a small set of timely facts while the normal search path remains the source for complete memory.
References: scripts/grok-bot-session-inject.mjs• L1-50 scripts/grok-bot-session-inject.mjs• L511-575 scripts/grok-bot-session-inject.mjs• L598-685 tests/grok-bot-session-inject.test.ts• L97-175 src/…/GrokBotAwarenessPusher.ts• L142-197
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the plugin manifest, mcp.json, and the install skill aligned on local versus remote MCP selection.
- Keep the Grok Bot transcript schema and the transcript fixture aligned with the fields used to join tool calls to tool results.
- Keep project-name rules identical in the transcript installer and the optional session-injection bridge so one agent does not split its memory across workspaces.
- Keep the documented CMEM Pro default aligned with the NPX provider-resolution boundary and the persisted provider settings.
- Keep host-observer output rules aligned with the observer loop's accepted skip and observation results.
- Treat changes to the session-injection file grammar as a host contract change. Verify that Grok Bot still reads the generated facts and that protected memory paths remain untouched.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Grok Bot has no transcript watch | New sessions do not enter claude-mem | The installer writes a Grok Bot schema and per-agent watches into the shared watcher config |
| A tool result loses its tool-use ID | Tool activity cannot be joined to the call that produced it | The schema accepts the supported ID field forms for both tool-use and tool-result events |
--provider host is treated as the default | The install uses a local host-login observer when CMEM Pro was intended | The CLI defaults Grok Bot to CMEM Pro and keeps host as an explicit choice |
| Observer returns prose instead of the contract result | The observer output is dropped and no observation is saved | The host-observer skill requires one skip marker or one observation XML result |
| Remote MCP token is missing or invalid | Grok Bot cannot authenticate to the remote MCP endpoint | Configure CLAUDE_MEM_MCP_TOKEN when using the remote entry |
| Session injection writes outside its owned paths | Host memory or user-authored files can be overwritten | The bridge restricts writes to the seat timeline and its integration-owned memory log |
| A timeline is edited by a user | A refresh can erase the user's timeline changes if it treats the bucket as generated data | The bridge detects user-owned row content and compiles the existing bucket instead of replacing it |
Key files
| File | Why to read it |
|---|---|
| claude-mem-grok-bot/…/plugin.json | Defines the distributed package, skills, MCP manifest, and remote MCP variables. |
| claude-mem-grok-bot/mcp.json | Shows the local and remote MCP connection choices. |
| claude-mem-grok-bot/README.md | Gives the short product and install boundary for the package. |
| claude-mem-grok-bot/…/SKILL.md | Explains the supported setup modes and the Grok Bot default. |
| claude-mem-grok-bot/…/SKILL.md | Defines the host-login observer output contract. |
| claude-mem-grok-bot/…/SKILL.md | Defines the layered memory recall flow. |
| src/…/GrokBotInstaller.ts | Connects Grok Bot agent data and transcript schemas to the shared watcher. |
| src/…/index.ts | Applies the Grok Bot provider default for non-interactive installs. |
| src/…/install.ts | Runs the Grok Bot transcript setup and maps provider choices to observer settings. |
| scripts/grok-bot-session-inject.mjs | Describes the optional editable timeline and host-memory bridge. |
| src/…/GrokBotAwarenessPusher.ts | Shows the narrow pilot-only awareness feedback path. |