Skip to content

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

Rust

fix(swival): scope integration to supported MCP path (#385)

AkitaOnRails30602aeb52d6
diff --cc CHANGELOG.md
index c99a65b8,78e0e3bb..6d523afe
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@@ -7,34 -7,19 +7,27 @@@ and this project adheres to [Semantic V
## [Unreleased]
+### Added
- - Added first-party Swival CLI support. `AgentKind::Swival` persists sessions
- under the `swival` wire value (new V48 migration) and never claims startup
- handoff injection because Swival captures lifecycle-hook stdout without
- putting it into the model context. `install-hooks --agent swival` renders
- / merges the single `lifecycle_command` (an `env AI_MEMORY_HOOK_URL=…`
- prefix plus the shim path, which survives Swival's no-shell
- `shlex.split` + `subprocess` exec) into `~/.config/swival/config.toml` or a
- project `swival.toml`; the shim maps `startup`/`exit <base_dir>` positional
- args to `session-start`/`session-end` hook events and recovers project
- scope from the cwd marker. `install-mcp --client swival` merges the
- documented `.swival/mcp.json` HTTP entry, `setup-agent --agent swival`
- emits the hook command, and `uninstall` strips both. Handoffs are recovered
- via the MCP `memory_handoff_accept` tool because Swival discards hook
- stdout ([#385]).
- - Added `ai-memory run swival` managed workstream support. The new
- `ManagedHarness::Swival` adapter discovers, lists, and checks native
- sessions against the project-scoped `.swival/HISTORY.md` rollup (or the
- `--cache-dir` store) under the fixed native id `HISTORY`, injects no
- resume selector (Swival has none and resumes implicitly by cwd), maps
- `--yolo` to Swival's own `--files all --commands all`, and passes utility
- subcommands (`--init-config`, `--logout`, `--list-profiles`, `--version`,
- `skills`, `--serve`, `--acp`) through untouched. HISTORY.md is an
- undecodable rolling rollup, so the visible-event ledger comes from
- lifecycle-hook capture and transcript export fails with an explanatory
- message (mirroring Antigravity). The server's managed-run allowlist
- accepts `AgentKind::Swival` explicitly but keeps Swival out of the
- no-argument automatic pool ([#385]).
++- Added MCP-only Swival CLI support. `install-mcp --client swival --apply`
++ merges ai-memory's native HTTP entry into the project-root
++ `.swival/mcp.json`, and `uninstall` removes only the matching ai-memory
++ entry while preserving sibling servers. Lifecycle capture and managed
++ workstreams remain unsupported because Swival's callback contract does not
++ expose a stable session identifier (#385).
++
+ ### Fixed
+ - The `bin/ai-memory` wrapper now detects rootless mode and SELinux under
+ podman, so host-file commands stop failing with `Permission denied (os error
+ 13)` on podman-based distros. Both the `-u 0:0` remap and `--security-opt
+ label=disable` were decided from `docker info --format
+ '{{.SecurityOptions}}'`, a Docker-only field that podman cannot evaluate;
+ the swallowed error left both gates off exactly where they were needed.
+ Podman's `.Host.Security.*` keys are consulted when that probe comes back
+ empty. `bootstrap` is now covered as well: it only reads host files, but an
+ unmapped UID blocks reads just as hard, and it degraded silently to "no
+ `.git` found" before dying. Restore archives, explicit config paths, and
+ commands using a host-backed `AI_MEMORY_DATA_DIR` now receive the same
+ host-file treatment (#388).
## [1.25.0] - 2026-08-07
diff --cc README.md
index 8d5a5b48,d07ab1e0..2f8d4571
--- a/README.md
+++ b/README.md
@@@ -37,7 -37,6 +37,7 @@@
| 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_accept`. `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 | Supported | MCP config (`install-mcp --client swival` → project `.swival/mcp.json`, HTTP entry) + lifecycle hooks (`install-hooks --agent swival` → single `lifecycle_command` in `~/.config/swival/config.toml` or a project `swival.toml`; the shim maps Swival's positional `startup`/`exit <base_dir>` hook args to `session-start`/`session-end` events). Capture works; no handoff injection — Swival captures hook stdout but never puts it in the model context, so recover handoffs via MCP `memory_handoff_accept`. `ai-memory run swival` adds managed workstream resume via `--cache-dir` (default `.swival/`); HISTORY.md is not decoded, so the ledger for this harness comes from hook capture. |
++| 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_accept`. |
| Kimi Code | Supported | MCP config (`url` entry in `~/.kimi-code/mcp.json`) + lifecycle hooks (`[[hooks]]` in `~/.kimi-code/config.toml`, 10 events including subagent start/stop and `PostToolUseFailure` for tool-failure capture); both paths honor `$KIMI_CODE_HOME`. Handoffs inject via `UserPromptSubmit` stdout (Kimi Code discards `SessionStart` hook stdout); `ai-memory run kimi` adds managed workstream resume. |
| Kiro CLI | Supported | MCP config uses `install-mcp --client kiro-cli` (alias `kiro`) and Kiro's Bedrock-compatible schema flavor. `install-hooks --agent kiro-cli` merges v2 hooks into existing agent configs; the explicit `--agent kiro-cli-v3` target writes the incompatible standalone v3 registration. Both preserve unrelated entries, honor `$KIRO_HOME`, enforce capture exclusions, and inject pending handoffs at session start. Kiro has no true SessionEnd hook; use `ai-memory finalize-session --agent kiro-cli`, with `--session-id <uuid>` for concurrent sessions. `ai-memory run kiro` manages v2; add `--v3`, `--mode`, or `--agent-engine v3` for version-safe v3 resume. |
diff --cc crates/ai-memory-cli/src/cli.rs
index e06696d8,e80ce805..dd14741b
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@@ -1184,14 -1171,6 +1171,10 @@@ pub enum McpClient
/// Command Code CLI — `~/.commandcode/mcp.json`.
#[value(alias = "commandcode", alias = "cmdc", alias = "cmd")]
CommandCode,
- /// Swival CLI — `.swival/mcp.json` in the project root (standard
- /// `mcpServers` map) or a `[mcp_servers.<name>]` table in
- /// `swival.toml` / `~/.config/swival/config.toml`. HTTP transport
- /// against ai-memory's `/mcp` endpoint. Pair with
- /// `install-hooks --agent swival` for lifecycle capture; Swival
- /// captures hook stdout but never injects it, so handoffs are
- /// recovered via MCP `memory_handoff_accept`.
++ /// Swival CLI — project-scoped `.swival/mcp.json` using native HTTP.
++ /// This integration is MCP-only; Swival's lifecycle callback does not
++ /// expose a stable session identifier for reliable capture correlation.
+ Swival,
/// VS Code GitHub Copilot (agent mode) — per-workspace
/// `.vscode/mcp.json`. Copilot's agent mode reads MCP servers
/// from VS Code's own MCP framework (top-level `servers` key),
@@@ -2315,48 -2294,6 +2298,23 @@@ mod tests
}
}
+ #[test]
- fn swival_mcp_and_hook_agents_parse() {
- let mcp = Cli::try_parse_from([
++ fn swival_mcp_client_parses() {
++ let cli = Cli::try_parse_from([
+ "ai-memory",
+ "install-mcp",
+ "--client",
+ "swival",
+ "--server-url",
+ "http://memory.example:49374",
+ ])
+ .unwrap_or_else(|error| panic!("failed to parse MCP client swival: {error}"));
- let Command::InstallMcp(args) = mcp.command else {
++ let Command::InstallMcp(args) = cli.command else {
+ panic!("expected install-mcp for swival");
+ };
+ assert_eq!(args.client, McpClient::Swival);
-
- let hooks = Cli::try_parse_from([
- "ai-memory",
- "install-hooks",
- "--agent",
- "swival",
- "--server-url",
- "http://memory.example:49374",
- ])
- .unwrap_or_else(|error| panic!("failed to parse hook agent swival: {error}"));
- let Command::InstallHooks(args) = hooks.command else {
- panic!("expected install-hooks for swival");
- };
- assert_eq!(args.agent, AgentChoice::Swival);
- assert_eq!(args.agent.kind(), ai_memory_core::AgentKind::Swival);
- }
-
- #[test]
- fn run_swival_harness_parses() {
- let cli = Cli::try_parse_from(["ai-memory", "run", "swival", "--yolo", "refactor auth"])
- .unwrap_or_else(|error| panic!("failed to parse run swival: {error}"));
- let Command::Run(args) = cli.command else {
- panic!("expected run for swival");
- };
- assert_eq!(args.harness, Some(RunHarnessChoice::Swival));
+ }
+
#[test]
fn install_hooks_project_strategy_repo_root_parses() {
let cli = Cli::try_parse_from([
diff --cc crates/ai-memory-cli/src/commands/install_hooks.rs
index 445504a5,332d0d0b..1e3a29b7
--- a/crates/ai-memory-cli/src/commands/install_hooks.rs
+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs
@@@ -802,12 -798,7 +798,13 @@@ fn infer_installed_mcp_config(agent: Ag
"url",
)),
McpClient::ClaudeDesktop => Ok(None),
+ // MCP-only client: no AgentChoice counterpart routes here.
+ McpClient::Swival => Ok(infer_json_mcp_config(
+ &content,
+ &["mcpServers", "ai-memory"],
+ "url",
+ )),
+ // MCP-only client: no AgentChoice counterpart routes here.
// Reachable only if a future install_hooks flow targets VS
// Code Copilot directly.
McpClient::VsCodeCopilot => Ok(infer_json_mcp_config(
diff --cc crates/ai-memory-cli/src/commands/install_mcp.rs
index 9bd48d5a,3b139951..5bbd7fe2
--- a/crates/ai-memory-cli/src/commands/install_mcp.rs
+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs
@@@ -213,12 -212,6 +213,11 @@@ pub(crate) fn mcp_config_path(client: c
.join("settings")
.join("mcp.json"),
McpClient::CommandCode => home()?.join(".commandcode").join("mcp.json"),
- // Swival reads the project-scoped `.swival/mcp.json` under the
- // current base dir by default (its own documented default lookup).
- McpClient::Swival => std::env::current_dir()
- .context("could not resolve current dir for .swival/mcp.json default")?
- .join(".swival")
- .join("mcp.json"),
++ McpClient::Swival => {
++ let cwd = std::env::current_dir()
++ .context("could not resolve current dir for .swival/mcp.json default")?;
++ swival_project_root(&cwd).join(".swival").join("mcp.json")
++ }
// VS Code MCP is workspace-scoped by default: `.vscode/mcp.json`
// at the current workspace root. The user-profile alternative
// lives under VS Code's profile-specific data dir; use VS
@@@ -239,6 -232,6 +238,22 @@@
})
}
++/// Match Swival's own base-dir discovery: the nearest ancestor containing
++/// `.git` or `swival.toml`, falling back to the invocation directory.
++fn swival_project_root(start: &Path) -> PathBuf {
++ let resolved = std::fs::canonicalize(start).unwrap_or_else(|_| start.to_path_buf());
++ let mut current = resolved.as_path();
++ loop {
++ if current.join(".git").exists() || current.join("swival.toml").exists() {
++ return current.to_path_buf();
++ }
++ let Some(parent) = current.parent() else {
++ return resolved;
++ };
++ current = parent;
++ }
++}
++
/// Resolve Zed's user settings from the platform config root. The root is
/// injected so path behavior can be tested without consulting the real home.
fn zed_config_path_in(config_dir: &Path, target_os: &str) -> PathBuf {
@@@ -1196,21 -1179,6 +1211,16 @@@ fn render_command_code(args: &InstallMc
))
}
+fn render_swival(args: &InstallMcpArgs) -> Result<String> {
+ Ok(format!(
+ "# Swival CLI — merge into .swival/mcp.json in the project root
+ # (Swival's documented default lookup; project-scoped by design), or
+ # re-run with --apply to merge it in place preserving other servers.
- # A `[mcp_servers.ai-memory]` table in swival.toml is the TOML
- # alternative and wins by name when both exist.
- # Pair with `ai-memory install-hooks --agent swival` for lifecycle
- # capture; Swival captures hook stdout but never injects it, so
- # handoffs are recovered via the MCP `memory_handoff_accept` tool.
+ {snippet}\n",
+ snippet = render_json_mcp_fragment(args)?,
+ ))
+}
+
fn render_vscode_copilot(args: &InstallMcpArgs) -> Result<String> {
Ok(format!(
"# VS Code GitHub Copilot (agent mode) — write to one of:\n\
@@@ -1670,6 -1637,6 +1680,7 @@@ mod tests
McpClient::KimiCode,
McpClient::KiroCli,
McpClient::CommandCode,
++ McpClient::Swival,
McpClient::VsCodeCopilot,
McpClient::Zed,
] {
@@@ -1709,6 -1676,6 +1720,7 @@@
McpClient::KimiCode,
McpClient::KiroCli,
McpClient::CommandCode,
++ McpClient::Swival,
McpClient::VsCodeCopilot,
McpClient::Zed,
] {
@@@ -2337,6 -2303,6 +2349,61 @@@
);
}
++ #[test]
++ fn swival_entry_and_apply_match_upstream_json_schema() {
++ let tmp = tempfile::TempDir::new().unwrap();
++ let config_path = tmp.path().join(".swival").join("mcp.json");
++ fs::create_dir_all(config_path.parent().unwrap()).unwrap();
++ fs::write(
++ &config_path,
++ r#"{"mcpServers":{"other":{"command":"other-mcp"}}}"#,
++ )
++ .unwrap();
++
++ let mut args = args_with_token(McpClient::Swival);
++ args.config_file = Some(config_path.clone());
++ apply_to_config_file(&args).unwrap();
++ let first = fs::read_to_string(&config_path).unwrap();
++ apply_to_config_file(&args).unwrap();
++ let second = fs::read_to_string(&config_path).unwrap();
++
++ assert_eq!(first, second, "Swival MCP apply must be idempotent");
++ let value: serde_json::Value = serde_json::from_str(&second).unwrap();
++ assert_eq!(value["mcpServers"]["ai-memory"]["type"], "http");
++ assert_eq!(
++ value["mcpServers"]["ai-memory"]["url"],
++ "http://127.0.0.1:49374/mcp"
++ );
++ assert_eq!(
++ value["mcpServers"]["ai-memory"]["headers"]["Authorization"],
++ "Bearer test-token-deadbeef"
++ );
++ assert_eq!(
++ value["mcpServers"]["other"]["command"], "other-mcp",
++ "apply must preserve sibling servers"
++ );
++ }
++
++ #[test]
++ fn swival_project_root_matches_git_toml_and_fallback_rules() {
++ let tmp = tempfile::TempDir::new().unwrap();
++ let git_root = tmp.path().join("git-project");
++ let git_nested = git_root.join("a").join("b");
++ fs::create_dir_all(git_root.join(".git")).unwrap();
++ fs::create_dir_all(&git_nested).unwrap();
++ assert_eq!(swival_project_root(&git_nested), git_root);
++
++ let toml_root = tmp.path().join("toml-project");
++ let toml_nested = toml_root.join("src");
++ fs::create_dir_all(&toml_nested).unwrap();
++ fs::write(toml_root.join("swival.toml"), "").unwrap();
++ assert_eq!(swival_project_root(&toml_nested), toml_root);
++
++ let plain = tmp.path().join("plain");
++ fs::create_dir_all(&plain).unwrap();
++ assert_eq!(swival_project_root(&plain), plain);
++ }
++
#[test]
fn grok_print_uses_apply_toml_builder_for_dotted_names_and_quotes() {
let mut args = args_with_token(McpClient::Grok);
diff --cc crates/ai-memory-cli/src/commands/uninstall.rs
index bde0b35d,6b47dc5c..2f215cee
--- a/crates/ai-memory-cli/src/commands/uninstall.rs
+++ b/crates/ai-memory-cli/src/commands/uninstall.rs
@@@ -354,6 -339,6 +339,7 @@@ fn build_plan(args: &UninstallArgs) ->
KimiCode,
KiroCli,
CommandCode,
++ Swival,
] {
let paths = if matches!(client, ClaudeCode) {
claude_config_paths(
@@@ -2182,6 -2136,6 +2138,23 @@@ command = "'/usr/local/bin/ai-memory' h
assert!(v["mcpServers"].get("other").is_some());
}
++ #[test]
++ fn strip_mcp_swival_root_servers_preserves_siblings() {
++ let content = r#"{"mcpServers":{"ai-memory":{"type":"http","url":"http://127.0.0.1:49374/mcp"},"other":{"command":"other-mcp"}}}"#;
++ let (out, removed) = strip_mcp_json_client(
++ content,
++ McpClient::Swival,
++ Some("ai-memory"),
++ "http://127.0.0.1:49374/mcp",
++ )
++ .unwrap();
++
++ assert_eq!(removed, vec!["ai-memory".to_string()]);
++ let value: serde_json::Value = serde_json::from_str(&out).unwrap();
++ assert!(value["mcpServers"].get("ai-memory").is_none());
++ assert_eq!(value["mcpServers"]["other"]["command"], "other-mcp");
++ }
++
#[test]
fn mcp_url_candidates_adds_client_schema_flavors() {
assert_eq!(
diff --cc docs/mcp-install.md
index 3648a91c,c493f264..ed0c54f3
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@@ -120,7 -120,7 +120,7 @@@ metadata
> **One-shot tip:** every snippet below is also reachable from the
> CLI:
> ```bash
--> ai-memory install-mcp --client gemini-cli # or cursor / claude-desktop / openclaw / omp / pi / antigravity-cli / grok / kimi-code / kiro-cli / command-code / devin / zero / vscode-copilot / zed
++> ai-memory install-mcp --client gemini-cli # or cursor / claude-desktop / openclaw / omp / pi / antigravity-cli / grok / kimi-code / kiro-cli / command-code / swival / devin / zero / vscode-copilot / zed
> ```
---
@@@ -601,50 -601,6 +601,41 @@@ capture and session-end handoff *creati
does not — ask Zero to call `memory_handoff_accept` at the start of a
resumed session.
+## Swival CLI
+
- **Status:** ✅ MCP supported. ✅ Lifecycle hooks supported via
- `ai-memory install-hooks --agent swival --apply`. ❌ No automatic handoff
- injection (Swival captures hook stdout but never puts it in the model
- context — same policy as Zero/Grok; recover handoffs through
- `memory_handoff_accept`).
++**Status:** MCP supported. Lifecycle hooks and managed workstreams are not
++supported: Swival invokes one shared startup/exit callback without exposing a
++stable session identifier, so concurrent sessions cannot be correlated safely.
+
+**Config file:** Swival reads the project-scoped `.swival/mcp.json` by
+default (its own documented default lookup), so `install-mcp --client
- swival --apply` merges under that path in the current directory. The TOML
- alternative is a `[mcp_servers.ai-memory]` table in `swival.toml` or
- `~/.config/swival/config.toml`, which wins by name when both exist — pass
- `--config-file` to target it explicitly.
++swival --apply` merges under that path at the nearest `.git` or `swival.toml`
++ancestor, matching Swival's own project-root discovery. Pass `--config-file`
++only to target a different MCP JSON file.
+
+```bash
- ai-memory install-mcp --client swival --apply --server-url "http://homelab:49374/mcp" --auth-token "$TOKEN"
++ai-memory install-mcp --client swival --apply \
++ --server-url "http://homelab:49374/mcp" \
++ --auth-token "$TOKEN"
+```
+
+which merges into `.swival/mcp.json`:
+
+```json
+{
+ "mcpServers": {
+ "ai-memory": {
+ "type": "http",
+ "url": "http://homelab:49374/mcp",
+ "headers": { "Authorization": "Bearer <token>" }
+ }
+ }
+}
+```
+
- Lifecycle capture is a single hook: `ai-memory install-hooks --agent swival
- --apply` merges `lifecycle_command` into `~/.config/swival/config.toml` (or
- a project `swival.toml` via `--config-file`). Swival runs the command as
- `<command> startup <base_dir>` / `<command> exit <base_dir>` with
- `cwd = base_dir` and `SWIVAL_*` env — the installed command prefixes an
- `env AI_MEMORY_HOOK_URL=…` so the shim can post the server without a shell.
- Only `startup`/`exit` events exist (no tool/prompt/compaction hooks), and
- Swival discards hook stdout, so handoffs must be recovered explicitly:
- ask the model to call `memory_handoff_accept` after a resumed session
- starts.
++`uninstall --only mcp --apply --yes` removes the matching ai-memory entry from
++that file and preserves all unrelated MCP servers.
+
## Grok Build CLI
**Status:** ✅ MCP supported. ✅ Lifecycle hooks supported via
@@@ -1135,8 -1091,8 +1126,8 @@@ that *starts* the next one - to play ni
| 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, Devin CLI, Cursor, Gemini CLI, Grok Build CLI, Zero, Kimi Code, OpenClaw, OpenCode, Swival CLI, and OMP. Codex, 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. |
- | **Starting side** | Either (a) the session-start/plugin path injects the handoff via `/handoff`, OR (b) the model proactively calls `memory_handoff_accept` on first turn. | (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 / OMP. It requires a client that consumes startup-hook stdout or an equivalent context-injection result. Grok, Zero, and Swival are explicitly excluded because they discard (or never inject) SessionStart stdout; use (b). (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). |
-| **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, Devin CLI, Cursor, Gemini CLI, Grok Build CLI, Zero, Kimi Code, OpenClaw, OpenCode, and OMP. Codex, 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. |
-| **Starting side** | Either (a) the session-start/plugin path injects the handoff via `/handoff`, OR (b) the model proactively calls `memory_handoff_accept` on first turn. | (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 / OMP. It requires a client that consumes startup-hook stdout or an equivalent context-injection result. Grok and Zero are explicitly excluded because they discard SessionStart stdout; use (b). (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). |
++| **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, Devin CLI, Cursor, Gemini CLI, Grok Build CLI, Zero, Kimi Code, OpenClaw, OpenCode, and OMP. Codex, 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. 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 proactively calls `memory_handoff_accept` on first turn. | (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 / 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). |
OpenCode uses its official `session.deleted` plugin event for true session-end
delivery. Its generated plugin also sends a deduped best-effort close for any