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.mdindex 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 discardsSessionStart 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 arerefused 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.rsindex 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.mdindex 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 thIf 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 handoffdiff --git a/crates/ai-memory-core/src/routing_skills/grok-handoff-rule.md b/crates/ai-memory-core/src/routing_skills/grok-handoff-rule.mdindex 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, soWhen 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.mdindex 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 notool call and without that rule leaves the handoff fordiff --git a/docs/mcp-install.md b/docs/mcp-install.mdindex 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-hookstdout (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). Grokignores `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 ordiff --git a/docs/support-matrix.md b/docs/support-matrix.mdindex 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.mdindex 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 thattool 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