Skip to content

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

Rust

fix(grok): list before reading the marker on the first turn

Victor Alencar026c6471621e
diff --git a/CHANGELOG.md b/CHANGELOG.md
index db0aca62..1cbe1dd7 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -49,8 +49,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
SessionStart stdout, so that list is the first tool and PostToolUse still
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.
+ because Grok reaches MCP tools only through that meta-tool. The rule puts
+ that call ahead of any file read and corrects `workspace`/`project` from
+ `./.ai-memory.toml` only when the list comes back empty, so scope resolution
+ neither consumes the turn nor leaves the current repository.
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`
diff --git a/crates/ai-memory-core/src/routing_skills.rs b/crates/ai-memory-core/src/routing_skills.rs
index 2ec19f41..80f05d58 100644
--- a/crates/ai-memory-core/src/routing_skills.rs
+++ b/crates/ai-memory-core/src/routing_skills.rs
@@ -358,6 +358,25 @@ mod tests {
);
}
+ #[test]
+ fn grok_handoff_rule_lists_before_it_reads_the_marker() {
+ let list_at = GROK_HANDOFF_RULE_CONTENT
+ .find("ai-memory__memory_handoff_list")
+ .expect("the rule must hand Grok the qualified catalog key");
+ let marker_at = GROK_HANDOFF_RULE_CONTENT
+ .find("./.ai-memory.toml")
+ .expect("scope correction must name the marker it reads");
+ assert!(
+ list_at < marker_at,
+ "the list call must come before the marker read, or the read becomes the first tool \
+ call and PostToolUse claims the baton before the rule's own step 1 runs"
+ );
+ assert!(
+ GROK_HANDOFF_RULE_CONTENT.contains("before reading any file"),
+ "step 1 must say the list precedes any file read"
+ );
+ }
+
#[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 2002ffc5..0fd965c4 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). 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.
+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, before reading any file, so that PostToolUse can claim the baton on that call; 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`. Grok is a static MCP client, so that call carries `workspace` and `project` together, as in Project scope below; for this first call fill them from what the session context already shows — `workspace` `default` and the current directory's basename — rather than spending a tool call on scope. Only when the list comes back empty, resolve the names properly as in Project scope and list once more. Recap from the list payload plus any additionalContext that arrives with the tool result. An empty corrected list means nothing is pending; continue with the user's request.
## 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 3715045d..9e1fab82 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,11 +8,12 @@ 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, 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.
+1. Call `memory_handoff_list` as the first tool, before reading any file, 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, so making this call first costs nothing when the scope turns out to be wrong.
+2. Grok is a static MCP client, so that call carries `workspace` and `project` together in `tool_input`. Both are names, never filesystem paths. Fill them from what the session context already shows, without spending a tool call on it: `workspace` is `default` unless the context names another one, and `project` is the basename of the current working directory.
+3. Only when that list returns an empty `handoffs` array, resolve the real names and list once more: read `./.ai-memory.toml` when it declares them, otherwise take the project from normalized `upstream`, then `origin`, using the full repository path without its host (`github.com/acme/api` → `acme-api`), and keep the basename when no valid remote exists. 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.
+4. Do not call `memory_handoff_accept` as the first tool. Accepting first races the PostToolUse GET `/handoff` claim.
+5. After a list returns, recap from that payload plus any `additionalContext` that arrives with the tool result. Then continue with the user's request.
+6. When the corrected list is empty too, nothing is pending. Continue with the user's request.
When a pending-handoff block or `additionalContext` handoff is already visible, answer from that block. Do not list or accept again.
diff --git a/docs/install.md b/docs/install.md
index 322147f2..53d81b88 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -1737,7 +1737,9 @@ 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`. 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
+`ai-memory__memory_handoff_list` instead of leaving it to `search_tool`. That
+call comes before any file read, and the rule corrects `workspace`/`project`
+from `./.ai-memory.toml` only when the list comes back empty. 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
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index 456a142a..7ae9f615 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -1006,7 +1006,9 @@ 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` 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.
+only through that meta-tool), before any file read, and corrects the scope from
+`./.ai-memory.toml` only when that list is empty; 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 58fc787d..65691eec 100644
--- a/docs/support-matrix.md
+++ b/docs/support-matrix.md
@@ -33,7 +33,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` 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`). |
+| 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) ahead of any file read, correcting `workspace`/`project` from `./.ai-memory.toml` only when that list is empty; 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 80ff0074..e45354a3 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -46,7 +46,9 @@ and `install-skills --scope global --agent grok` write
`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
+that meta-tool, and puts that call ahead of any file read, correcting
+`workspace`/`project` from `./.ai-memory.toml` only when the list is empty.
+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