Skip to content

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

Rust

fix(grok): hand the first-turn rule Grok's use_tool invocation

Victor Alencard9ac6840e8f6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 549b0125..a118c345 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -13,7 +13,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
`$GROK_HOME/rules/ai-memory-handoff.md` (default `~/.grok/rules/ai-memory-handoff.md`)
so the model calls `memory_handoff_list` on the first turn. Grok discards
SessionStart stdout, so that list is the first tool and PostToolUse still
- claims the baton through GET `/handoff`. Project-scope Grok skills and
+ claims the baton through GET `/handoff`. The rule names Grok's invocation —
+ `use_tool` with the qualified catalog key `ai-memory__memory_handoff_list` —
+ because Grok reaches MCP tools only through that meta-tool, and keeps scope
+ resolution inside the current repository so it cannot consume the turn. Project-scope Grok skills and
`--target-dir` leave the user rule alone. Unmanaged same-name files are
refused without `--force`; `install-hooks` warns and keeps the hook file.
`uninstall --only skills` and `--only hooks` remove the markered rule.
diff --git a/crates/ai-memory-core/src/routing_skills.rs b/crates/ai-memory-core/src/routing_skills.rs
index 5ac9303c..d04b12f5 100644
--- a/crates/ai-memory-core/src/routing_skills.rs
+++ b/crates/ai-memory-core/src/routing_skills.rs
@@ -340,6 +340,24 @@ mod tests {
assert!(GROK_HANDOFF_RULE_CONTENT.contains("empty `handoffs` array"));
}
+ #[test]
+ fn grok_handoff_rule_names_the_use_tool_invocation_before_search_tool() {
+ assert!(GROK_HANDOFF_RULE_CONTENT.contains("use_tool"));
+ let qualified_at = GROK_HANDOFF_RULE_CONTENT
+ .find("ai-memory__memory_handoff_list")
+ .expect("the rule must hand Grok the qualified catalog key, not the bare tool name");
+ if let Some(search_at) = GROK_HANDOFF_RULE_CONTENT.find("search_tool") {
+ assert!(
+ qualified_at < search_at,
+ "the key must precede search_tool so the rule never reads as a discovery roundtrip"
+ );
+ }
+ assert!(
+ GROK_HANDOFF_RULE_CONTENT.contains("do not search the filesystem"),
+ "scope resolution must stay inside the current repository"
+ );
+ }
+
#[test]
fn grok_handoff_rule_does_not_embed_a_handoff_peek() {
for leak in [
diff --git a/crates/ai-memory-core/src/routing_skills/ai-memory-handoff/SKILL.md b/crates/ai-memory-core/src/routing_skills/ai-memory-handoff/SKILL.md
index ff3f7c9b..2002ffc5 100644
--- a/crates/ai-memory-core/src/routing_skills/ai-memory-handoff/SKILL.md
+++ b/crates/ai-memory-core/src/routing_skills/ai-memory-handoff/SKILL.md
@@ -21,7 +21,7 @@ The SessionStart hook usually fetches and consumes any pending handoff before th
If no pending handoff block is visible, inspect with `memory_handoff_list` first. Listing does not claim or expire anything. When the user asks where we left off, claim one listed row with `memory_handoff_accept` and that `handoff_id`, using the client-aware project scope below. Do not treat list as a second accept path.
-On Grok Build CLI, SessionStart and UserPromptSubmit never inject a handoff (Grok discards that stdout). The first PostToolUse claims the pending row through GET `/handoff` and injects `additionalContext`. On the first turn, when no handoff block or additionalContext is visible, call `memory_handoff_list` as the first tool so that PostToolUse can claim it; do not call `memory_handoff_accept` first (that races the hook). Recap from the list payload plus any additionalContext that arrives with the tool result. An empty list means nothing is pending; continue with the user's request. Grok is a static MCP client, so pass `workspace` and `project` together as in Project scope below.
+On Grok Build CLI, SessionStart and UserPromptSubmit never inject a handoff (Grok discards that stdout). The first PostToolUse claims the pending row through GET `/handoff` and injects `additionalContext`. On the first turn, when no handoff block or additionalContext is visible, call `memory_handoff_list` as the first tool so that PostToolUse can claim it; do not call `memory_handoff_accept` first (that races the hook). Grok reaches MCP tools only through its `use_tool` meta-tool, so invoke it with `tool_name` set to the qualified catalog key `ai-memory__memory_handoff_list` (or `<server>__memory_handoff_list` when the server was registered under another name) instead of spending the turn on `search_tool`. Recap from the list payload plus any additionalContext that arrives with the tool result. An empty list means nothing is pending; continue with the user's request. Grok is a static MCP client, so pass `workspace` and `project` together as in Project scope below.
## Creating a handoff
diff --git a/crates/ai-memory-core/src/routing_skills/grok-handoff-rule.md b/crates/ai-memory-core/src/routing_skills/grok-handoff-rule.md
index 7c952746..3715045d 100644
--- a/crates/ai-memory-core/src/routing_skills/grok-handoff-rule.md
+++ b/crates/ai-memory-core/src/routing_skills/grok-handoff-rule.md
@@ -8,8 +8,8 @@ Grok Build CLI discards SessionStart stdout and an allowing UserPromptSubmit, so
When this is the first model turn of the session and no pending-handoff block or `additionalContext` handoff is already visible:
-1. Call `memory_handoff_list` as the first tool. Listing is read-only and does not claim or expire anything.
-2. Grok is a static MCP client: pass `workspace` and `project` together on that call. Read both from the nearest `.ai-memory.toml` when it declares them. Without a marker override, derive the project from normalized `upstream`, then `origin`, using the full repository path without its host (`github.com/acme/api` → `acme-api`); use the folder basename only when no valid remote exists. Never rely on the server's last active project.
+1. Call `memory_handoff_list` as the first tool, through `use_tool` with `tool_name` set to the qualified catalog key `ai-memory__memory_handoff_list` and the arguments in `tool_input`. Grok reaches MCP tools only through that meta-tool, so the bare name is not callable. The key is given here: do not spend the turn on `search_tool`. When this server was registered in `config.toml` under another name, the key is `<server>__memory_handoff_list`. Listing is read-only and does not claim or expire anything.
+2. Grok is a static MCP client: pass `workspace` and `project` together in `tool_input`. Both are names, never filesystem paths. Read them from `./.ai-memory.toml` before that call — one read of that single file in the current directory, which is cheap and is not a search. When it declares neither, `workspace` is `default` and the project comes from normalized `upstream`, then `origin`, using the full repository path without its host (`github.com/acme/api` → `acme-api`); with no valid remote, use the current directory's basename. Resolve this from the current repository alone — do not search the filesystem for another project's marker, and never rely on the server's last active project.
3. Do not call `memory_handoff_accept` as the first tool. Accepting first races the PostToolUse GET `/handoff` claim.
4. After the list returns, recap from that payload plus any `additionalContext` that arrives with the tool result. Then continue with the user's request.
5. An empty `handoffs` array means nothing is pending. Continue with the user's request.
diff --git a/docs/install.md b/docs/install.md
index 6d2bc01a..ea666f06 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1735,7 +1735,10 @@ captures lifecycle events.
Grok ignores `SessionStart` stdout and discards an allowing `UserPromptSubmit`,
so those hooks do not accept the handoff. `install-hooks --agent grok --apply`
also writes `$GROK_HOME/rules/ai-memory-handoff.md` so the first turn calls
-`memory_handoff_list`. The first `PostToolUse` prints
+`memory_handoff_list`. Grok reaches MCP tools only through its `use_tool`
+meta-tool, so the rule hands the model the qualified catalog key
+`ai-memory__memory_handoff_list` instead of leaving it to `search_tool`. The
+first `PostToolUse` prints
`hookSpecificOutput.additionalContext` (pending handoff, plus an opted-in
`[briefing]`). The model sees it after that tool result. A session with no
tool call and without that rule leaves the handoff for
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index 85fec15b..e06a266f 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -44,8 +44,10 @@ SessionStart stdout, so ai-memory does not auto-inject handoffs for them.
SessionStart handoff injection works only for clients that consume startup-hook
stdout (or their equivalent context-injection result). Grok's first-turn rule
(`$GROK_HOME/rules/ai-memory-handoff.md`, installed with the Grok hooks and
-with global Grok skills) has the model call `memory_handoff_list` so the first
-`PostToolUse` can claim the baton; Zero must call `memory_handoff_list` then
+with global Grok skills) has the model call `memory_handoff_list` through
+`use_tool` with the qualified catalog key `ai-memory__memory_handoff_list`, so
+the first `PostToolUse` can claim the baton; Zero must call
+`memory_handoff_list` then
`memory_handoff_accept` when resuming.
Capture exclusions are separate from MCP registration. Native hook commands and
@@ -998,7 +1000,9 @@ first `PostToolUse` (`additionalContext` after the tool result). Grok
ignores `SessionStart` stdout and discards an allowing `UserPromptSubmit`,
so those events do not accept the handoff. `--apply` also writes
`$GROK_HOME/rules/ai-memory-handoff.md` (default `~/.grok/rules/ai-memory-handoff.md`)
-so the first turn calls `memory_handoff_list`; PostToolUse then claims the row.
+so the first turn calls `memory_handoff_list` through `use_tool` with the
+qualified catalog key `ai-memory__memory_handoff_list` (Grok exposes MCP tools
+only through that meta-tool); PostToolUse then claims the row.
**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
diff --git a/docs/support-matrix.md b/docs/support-matrix.md
index bad85e2a..2d88819b 100644
--- a/docs/support-matrix.md
+++ b/docs/support-matrix.md
@@ -28,7 +28,7 @@
| Claude Desktop (Code tab) | Supported | Local Code-tab sessions run Claude Code with the user's `~/.claude/settings.json`, so the Claude Code hooks capture them as `claude-code`; a session without a project folder lands in its own scratch-directory project. |
| 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; an interactive session launched with `ai-memory run antigravity` is finalized automatically when it exits if the run can tie the session to itself (see [`docs/managed-workstreams.md`](managed-workstreams.md)). `ai-memory run antigravity` (aliases `antigravity-cli`, `agy`) adds managed workstream resume via `--conversation`; its conversation store is not decoded, so the ledger takes user prompts from `agy`'s `history.jsonl` (only this conversation's lines typed in this checkout) and assistant and tool steps from hook capture. Tool outputs (`run_command`, `view_file`, `list_dir`, etc.) are resolved directly from `.system_generated/steps/<stepIdx>/output.txt` during `post-tool-use` while mutation tools preserve code from arguments (#966). |
-| 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). `install-hooks --agent grok --apply` and `install-skills --scope global --agent grok` also write `$GROK_HOME/rules/ai-memory-handoff.md` so the first turn calls `memory_handoff_list`; the first `PostToolUse` then prints `hookSpecificOutput.additionalContext` with the pending handoff and an opted-in `[briefing]`. If that rule is absent and 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`). |
+| 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). `install-hooks --agent grok --apply` and `install-skills --scope global --agent grok` also write `$GROK_HOME/rules/ai-memory-handoff.md` so the first turn calls `memory_handoff_list` through `use_tool` with the qualified catalog key `ai-memory__memory_handoff_list` (Grok reaches MCP tools only through that meta-tool); the first `PostToolUse` then prints `hookSpecificOutput.additionalContext` with the pending handoff and an opted-in `[briefing]`. If that rule is absent and 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`. Zero runs hooks in its sandbox, which by default denies network (loopback too) and writes outside the workspace, so events stay in the hook spool: allow `sandbox.network` and add the ai-memory data dir to `sandbox.additionalWriteRoots` in the global `~/.config/zero/config.json` (network allow covers every Zero shell command; `sessionEnd` then delivers in-process within a fixed 10-second budget, since the sandbox kills detached drainers), or run `ai-memory hook-drain` from a normal shell (see [`mcp-install.md`](mcp-install.md#zero-gitlawbzero)). |
| 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 12cc3657..ca93991a 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -43,7 +43,10 @@ consume that handoff automatically. Grok shows it as `PostToolUse`
`additionalContext` after the first tool. `install-hooks --agent grok --apply`
and `install-skills --scope global --agent grok` write
`$GROK_HOME/rules/ai-memory-handoff.md` so the first turn calls
-`memory_handoff_list` (read-only; PostToolUse then claims the row). Until that
+`memory_handoff_list` (read-only; PostToolUse then claims the row). The rule
+spells out Grok's invocation — `use_tool` with the qualified catalog key
+`ai-memory__memory_handoff_list` — because Grok reaches MCP tools only through
+that meta-tool. Until that
tool runs, or if the rule is absent and the session never calls a tool, call
`memory_handoff_list` then `memory_handoff_accept` with the listed
`handoff_id`. Zero should list then accept on resume. Listing does not claim