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.mdindex 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.mdindex 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 ZCodeare 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 handleshandoff 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.mdindex 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 askingthe 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 thosecompat 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-enddelivery. The OpenCode 2 beta plugin subscribes to the same event name on thediff --git a/docs/support-matrix.md b/docs/support-matrix.mdindex 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.mdindex dd80012d..a87e040c 100644--- a/docs/usage.md+++ b/docs/usage.md@@ -38,9 +38,11 @@ $ codex # in the same directory, laterIf 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 bydefault: the next session for that operator sees their own plus deliberatelydiff --git a/docs/use-cases.md b/docs/use-cases.mdindex 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."** Theclassic. SessionStart hook in the next supported hook client prepends atyped 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` fromthe agent for FTS5 fused with entity matches and linked-page expansion (plusvector similarity when an embedder is configured). For a quick terminal-only