Skip to content

Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors

Rust

docs: Grok handoff is PostToolUse additionalContext

Giovanni Coutinho8a6a137c23ad
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9c59817a..f3418aed 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,14 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
## [Unreleased]
+### Changed
+- Grok Build CLI shows a pending handoff, and an opted-in `[briefing]`,
+ as `PostToolUse` `additionalContext` on the first tool of a session.
+ `SessionStart` and `UserPromptSubmit` still do not accept the handoff:
+ Grok discards that stdout. A session that never calls a tool leaves the
+ handoff open for `memory_handoff_accept`. The note is clipped to 10,000
+ characters, which is Grok's own cap.
+
### Security
- Bumped `rmcp` to 2.x (2.2.0), resolving three MCP transport advisories:
GHSA-9pj6-vhgr-3mwh (unauthenticated Streamable-HTTP session-table leak /
diff --git a/docs/install.md b/docs/install.md
index 1e86f884..02d34d01 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1395,14 +1395,19 @@ Cursor, Gemini CLI, Antigravity CLI, Grok Build CLI, Kiro CLI, Command Code, and
`$GROK_HOME/config.toml` (default `~/.grok/config.toml`); its hooks live under
`$GROK_HOME/hooks` (default `~/.grok/hooks`). `install-hooks --agent grok`
captures lifecycle events.
-Grok ignores `SessionStart` stdout, so handoffs must be accepted through MCP with
-`memory_handoff_accept` when resuming. Claude Desktop, VS Code Copilot, Zed,
+Grok ignores `SessionStart` stdout and discards an allowing `UserPromptSubmit`,
+so those hooks do not accept the handoff. The first `PostToolUse` prints
+`hookSpecificOutput.additionalContext` (pending handoff, plus an opted-in
+`[briefing]`). The model sees it after that tool result, not before the
+first prompt. A session with no tool call leaves the handoff for
+`memory_handoff_accept`. Claude Desktop, VS Code Copilot, Zed,
and ZCode
are MCP-only here, so you'll need to nudge the model to call
`memory_query` / `memory_handoff_accept` itself.
For clients with `install-hooks` support, the capture path handles
handoff injection at session start or the client's closest equivalent, except
-for Grok's (and Zero's) no-stdout SessionStart behavior (Antigravity CLI uses `PreInvocation`).
+for Zero's no-stdout SessionStart behavior. Grok delivers on the first
+`PostToolUse` instead (Antigravity CLI uses `PreInvocation`).
---
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index a1fc114a..6e02247d 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -47,7 +47,7 @@ endpoint. The trade-off:
| | What you get | What you don't get |
|---|---|---|
| **MCP only** | LLM can query the wiki, accept handoffs, run memory_consolidate, and run `memory_auto_improve` learning reviews | No automatic session-end summaries; no auto-handoff at session boundaries |
-| **MCP + hooks** | All of the above *plus* bounded sanitized prompt/tool-lifecycle observations captured automatically; handoffs surface at SessionStart with no human prompting **only when the client consumes startup-hook output or an equivalent context-injection result** | Hook observations are not complete native transcripts. Grok and Zero discard SessionStart stdout; ask them to call `memory_handoff_accept` when resuming. |
+| **MCP + hooks** | All of the above *plus* bounded sanitized prompt/tool-lifecycle observations captured automatically; handoffs surface at SessionStart with no human prompting **only when the client consumes startup-hook output or an equivalent context-injection result** | Hook observations are not complete native transcripts. Grok delivers the handoff on the first `PostToolUse`. Zero discards SessionStart stdout; ask it to call `memory_handoff_accept`. |
For MCP-only use, you can still cover the session-boundary gap by asking
the LLM to call `memory_handoff_begin` manually before quitting.
@@ -748,8 +748,10 @@ that file and preserves all unrelated MCP servers.
## Grok Build CLI
**Status:** ✅ MCP supported. ✅ Lifecycle hooks supported via
-`ai-memory install-hooks --agent grok --apply`. ❌ No automatic handoff
-injection (Grok ignores SessionStart stdout — same policy as Zero).
+`ai-memory install-hooks --agent grok --apply`. Handoff injection is the
+first `PostToolUse` (`additionalContext` after the tool result). Grok
+ignores `SessionStart` stdout and discards an allowing `UserPromptSubmit`,
+so those events do not accept the handoff.
**Config file:** `install-mcp --client grok --apply` writes the user config at
`$GROK_HOME/config.toml` (default `~/.grok/config.toml`). To use a project or
@@ -790,10 +792,11 @@ mirror Claude Code's vocabulary (`SessionStart`, `UserPromptSubmit`,
`PreToolUse`, `PostToolUse`, `PreCompact`, `Stop`, `SessionEnd`,
`SubagentStart`, `SubagentStop`) with a Grok-specific script bundle /
native `ai-memory hook --event … --agent grok` commands. Session-end
-handoff *creation* works; handoff *injection* does not — ask Grok to
-call `memory_handoff_accept` (or install the managed routing skills under
-`.grok/skills` / `$GROK_HOME/skills` (default `~/.grok/skills`)) at the start
-of a resumed session.
+handoff *creation* works. Injection is the first `PostToolUse`: JSON
+`additionalContext` with the pending handoff and an opted-in `[briefing]`.
+`memory_handoff_accept` is still the path when the session has not called
+a tool yet (skills live under `.grok/skills` / `$GROK_HOME/skills`, default
+`~/.grok/skills`).
Grok can also load MCP from Claude Code / Cursor compat sources when those
compat flags are enabled, but first-party `install-mcp --client grok` is
@@ -1363,7 +1366,7 @@ that *starts* the next one - to play nicely with ai-memory:
| Side | What's needed | Covered by |
|---|---|---|
| **Ending side** | The agent must create a handoff through a true session-end hook, the manual finalizer, or `memory_handoff_begin`. | Built-in automatically for Claude Code, Codex (native `SessionEnd`, Codex CLI 0.145.0+), Devin CLI, Cursor, Gemini CLI, Grok Build CLI, Zero, Kimi Code, OpenClaw, OpenCode, OpenCode 2 beta, and OMP. Antigravity CLI, both Kiro CLI engines, and Command Code have no reliable true session-end event; run `ai-memory finalize-session` with the corresponding `--agent` after the final turn (also the fallback on Codex older than 0.145.0). MCP-only clients such as Swival must call `memory_handoff_begin` explicitly. |
-| **Starting side** | Either (a) the session-start/plugin path injects the handoff via `/handoff`, OR (b) the model inspects with `memory_handoff_list` then claims with `memory_handoff_accept` (`handoff_id` from the list). | (a) is built-in for Claude Code / Codex / Devin CLI / Cursor / Gemini CLI / Antigravity CLI / Kimi Code / both Kiro CLI engines / Command Code / OpenClaw / OpenCode / OpenCode 2 beta / OMP. It requires a client that consumes startup-hook stdout or an equivalent context-injection result. Grok and Zero discard SessionStart stdout; Swival is MCP-only. Use (b) for those clients. (b) works for any MCP-capable client if you nudge the model - see [the managed routing package](usage.md#install-the-routing-snippet-and-agent-skills). |
+| **Starting side** | Either (a) the session-start/plugin path injects the handoff via `/handoff`, OR (b) the model inspects with `memory_handoff_list` then claims with `memory_handoff_accept` (`handoff_id` from the list). | (a) is built-in for Claude Code / Codex / Devin CLI / Cursor / Gemini CLI / Antigravity CLI / Kimi Code / Grok Build CLI / both Kiro CLI engines / Command Code / OpenClaw / OpenCode / OpenCode 2 beta / OMP. Grok's (a) is the first `PostToolUse` `additionalContext`, not SessionStart. Zero discards SessionStart stdout; Swival is MCP-only. Use (b) for those. (b) works for any MCP-capable client if you nudge the model - see [the managed routing package](usage.md#install-the-routing-snippet-and-agent-skills). |
OpenCode uses its official `session.deleted` plugin event for true session-end
delivery. The OpenCode 2 beta plugin subscribes to the same event name on the
diff --git a/docs/support-matrix.md b/docs/support-matrix.md
index 91595628..a18c58bf 100644
--- a/docs/support-matrix.md
+++ b/docs/support-matrix.md
@@ -25,7 +25,7 @@
| Claude Desktop | MCP-only | Uses `mcp-remote`; no lifecycle hooks. |
| OpenClaw | Supported | MCP config + native plugin lifecycle hooks; generated plugin enforces capture exclusions. |
| Antigravity CLI | Supported | MCP config (`serverUrl`) + lifecycle hooks (`agy` alias). Only `PreInvocation` with `invocationNum = 0` maps to SessionStart; later model calls cannot consume a next-session handoff. No automatic true session-end hook, so run `ai-memory finalize-session --agent antigravity-cli` after the final turn when you need a summary, handoff, and opt-in SessionEnd consolidation. `ai-memory run antigravity` (aliases `antigravity-cli`, `agy`) adds managed workstream resume via `--conversation`; conversation text is not decoded, so the ledger for this harness comes from hook capture. |
-| Grok Build CLI | Supported | MCP config (`install-mcp --client grok` → `$GROK_HOME/config.toml`, default `~/.grok/config.toml`) + lifecycle hooks (`install-hooks --agent grok` → `$GROK_HOME/hooks/ai-memory.json`, default `~/.grok/hooks/ai-memory.json`, Grok-specific hook bundle). Capture works; no hook handoff injection — Grok ignores `SessionStart` stdout, so recover handoffs via MCP `memory_handoff_list` then `memory_handoff_accept` with that `handoff_id`. `ai-memory run grok` adds managed workstream resume with the context packet delivered natively through `--rules`. Skills root: `.grok/skills` / `$GROK_HOME/skills` (default `~/.grok/skills`). |
+| Grok Build CLI | Supported | MCP config (`install-mcp --client grok` → `$GROK_HOME/config.toml`, default `~/.grok/config.toml`) + lifecycle hooks (`install-hooks --agent grok` → `$GROK_HOME/hooks/ai-memory.json`, default `~/.grok/hooks/ai-memory.json`, Grok-specific hook bundle). Capture works. `SessionStart` and `UserPromptSubmit` do not accept the handoff (Grok discards that stdout). The first `PostToolUse` prints `hookSpecificOutput.additionalContext` with the pending handoff and an opted-in `[briefing]`; the model sees it after that tool result. If no tool runs, recover via MCP `memory_handoff_list` then `memory_handoff_accept` with that `handoff_id`. `ai-memory run grok` adds managed workstream resume with the context packet delivered natively through `--rules`. Skills root: `.grok/skills` / `$GROK_HOME/skills` (default `~/.grok/skills`). |
| Swival CLI | MCP-only | `install-mcp --client swival --apply` merges a native HTTP entry into the project-root `.swival/mcp.json`, preserving sibling servers. Lifecycle and managed-workstream support are not claimed because Swival's callback contract does not expose a stable session identifier. |
| Zero | Supported | `install-mcp --client zero` (native HTTP + bearer in `~/.config/zero/config.json`) + lifecycle hooks via `install-hooks --agent zero --apply` (exec-form native commands in `~/.config/zero/hooks.json`, JSON payload on stdin, no shell). Capture works incl. specialist (subagent) events; no handoff injection — Zero discards `sessionStart` stdout, so recover handoffs via MCP `memory_handoff_list` then `memory_handoff_accept` with that `handoff_id`. |
| ZCode | Supported | `install-mcp --client zcode --apply` merges a native HTTP entry (strict schema: `type`/`url`/`headers` only) into the `mcp.servers` map of `~/.zcode/cli/config.json`, preserving sibling servers. ZCode (z.ai, `zcode`, alias `zai`). Lifecycle-hook capture via `install-hooks --agent zcode --apply`: exec-form native commands (`type: "process"`, no shell) merged into the root `hooks` block of `~/.zcode/cli/config.json` around any third-party hooks; native commands enforce capture exclusions. Six documented triggers (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `Stop`); `PostToolUseFailure` fires instead of `PostToolUse` when a tool throws and lands on the same capture channel with the error preserved. `PermissionRequest` is deliberately not installed — its hook chain races the interactive permission client, so passive capture of that event is unreliable by design. No true session-end — `Stop` is a per-turn boundary, so run `ai-memory finalize-session --agent zcode` after the final turn. Unlike Pool and Zero, `SessionStart` stdout injection works (`hookSpecificOutput.additionalContext`, verified live against the embedded engine v0.16.5), so the prior session's handoff is delivered automatically. No first-party `install-mcp` client and no managed workstream are claimed yet. |
diff --git a/docs/usage.md b/docs/usage.md
index dd80012d..a87e040c 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -38,9 +38,11 @@ $ codex # in the same directory, later
If an agent has MCP but no lifecycle hook surface, ask it to call
`memory_handoff_begin` before quitting. The next hooked agent can still
-consume that handoff automatically. No-stdout clients (Grok, Zero) should
-call `memory_handoff_list` on resume, then `memory_handoff_accept` with
-the listed `handoff_id`; listing does not claim the row.
+consume that handoff automatically. Grok shows it as `PostToolUse`
+`additionalContext` after the first tool. Until that tool runs, or if the
+session never calls one, call `memory_handoff_list` then
+`memory_handoff_accept` with the listed `handoff_id`. Zero should do that
+on resume. Listing does not claim the row.
On a server that distinguishes operators, handoffs belong to their creator by
default: the next session for that operator sees their own plus deliberately
diff --git a/docs/use-cases.md b/docs/use-cases.md
index 1b6d3969..f42987ed 100644
--- a/docs/use-cases.md
+++ b/docs/use-cases.md
@@ -117,9 +117,10 @@
- **"Quit at 4 PM, pick up at 9 AM in a different agent."** The
classic. SessionStart hook in the next supported hook client prepends a
typed handoff with open questions, next steps, and a session summary. Grok
- captures lifecycle events but ignores SessionStart stdout, so ask it to call
- `memory_handoff_accept` when resuming from a handoff. Zero has the same
- no-stdout behavior and also must call `memory_handoff_accept`.
+ cannot show that text before the first prompt. The first tool's
+ `PostToolUse` hook adds it as `additionalContext`. If the session never
+ calls a tool, ask Grok to call `memory_handoff_accept`. Zero still must
+ call `memory_handoff_accept`.
- **"What did we decide about X six weeks ago?"** Use `memory_query X` from
the agent for FTS5 fused with entity matches and linked-page expansion (plus
vector similarity when an embedder is configured). For a quick terminal-only