Skip to content

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

Rust

docs(kiro): align open-ticket blockers with current contracts

AkitaOnRailse75f9b86764b
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 49c56446..bf7720b1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -21,8 +21,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
invalid, infer remote connectivity from the managed Kiro MCP entry, inject
handoffs through `agentSpawn` stdout, enforce capture exclusions for known
v2 tool payloads, and uninstall only exact ai-memory entries. Kiro v3 hook
- capture remains unsupported until its command-input payload is documented
- and can be fixture-tested (#355).
+ capture remains unsupported pending sanitized live lifecycle and built-in
+ tool payload fixtures, despite its now-documented standalone schema (#355).
### Fixed
- Mixed-case and trailing-period usernames now use deterministic hashed
diff --git a/crates/ai-memory-cli/src/cli.rs b/crates/ai-memory-cli/src/cli.rs
index 0b7fed99..ca2b9073 100644
--- a/crates/ai-memory-cli/src/cli.rs
+++ b/crates/ai-memory-cli/src/cli.rs
@@ -1016,7 +1016,8 @@ pub enum AgentChoice {
KimiCode,
/// Kiro CLI (AWS), v2 agent engine — camelCase lifecycle hooks embedded
/// in agent configs under `~/.kiro/agents/*.json`. Kiro v3's standalone
- /// hooks do not yet document a command-input payload contract.
+ /// schema is documented but lacks accepted live lifecycle and built-in
+ /// tool payload fixtures.
#[value(alias = "kiro")]
KiroCli,
}
@@ -2190,7 +2191,7 @@ mod tests {
.unwrap_err();
assert!(
error.to_string().contains("invalid value"),
- "v3 must remain unsupported until its payload contract is verified: {error}"
+ "v3 must remain unsupported until its live payload fixtures are verified: {error}"
);
}
}
diff --git a/crates/ai-memory-cli/src/commands/install_hooks.rs b/crates/ai-memory-cli/src/commands/install_hooks.rs
index d9a112ea..ba625fb3 100644
--- a/crates/ai-memory-cli/src/commands/install_hooks.rs
+++ b/crates/ai-memory-cli/src/commands/install_hooks.rs
@@ -1877,7 +1877,7 @@ fn apply_to_kiro_cli_agent_configs(
p.is_file(),
"{} does not exist. Kiro CLI v2 hooks live inside an existing agent config; \
create one first (`kiro-cli agent create`) and re-run. Kiro v3 hooks remain \
- unsupported until its command-input payload contract is documented.",
+ unsupported pending fixture-verified lifecycle and built-in tool payloads.",
p.display()
);
vec![p.clone()]
@@ -1889,8 +1889,8 @@ fn apply_to_kiro_cli_agent_configs(
"no Kiro CLI agent configs found in {}. The v2 engine only fires hooks defined in an \
agent config and the built-in default agent has no file on disk, so create an agent \
first (`kiro-cli agent create`, then `kiro-cli agent set-default <name>`) and re-run. \
- Kiro v3 hooks remain unsupported until its command-input payload contract is \
- documented.",
+ Kiro v3 hooks remain unsupported pending fixture-verified lifecycle and built-in tool \
+ payloads.",
kiro_cli_agents_dir()?.display()
);
let prepared = preflight_kiro_cli_agent_configs(
@@ -3852,8 +3852,8 @@ fn render_kiro_cli(
println!("// preserving third-party hook entries. The v2 engine fires hooks");
println!("// only for the active agent config; the built-in default agent has");
println!("// no file, so create one first (`kiro-cli agent create`). Kiro v3");
- println!("// hooks remain unsupported because their command-input payload is");
- println!("// not documented; do not reuse this v2 registration there.");
+ println!("// hooks remain unsupported pending fixture-verified lifecycle and");
+ println!("// built-in tool payloads; do not reuse this v2 registration there.");
println!("// Hook scripts: {}", hooks_dir.display());
println!("// AI-memory server URL: {server_url}");
if auth_token.is_some() {
diff --git a/crates/ai-memory-cli/src/commands/install_mcp.rs b/crates/ai-memory-cli/src/commands/install_mcp.rs
index 8add847c..063c9af7 100644
--- a/crates/ai-memory-cli/src/commands/install_mcp.rs
+++ b/crates/ai-memory-cli/src/commands/install_mcp.rs
@@ -1147,8 +1147,8 @@ fn render_kiro_cli(args: &InstallMcpArgs) -> Result<String> {
# schema combinators while handler validation remains unchanged.\n\
# Lifecycle capture for the documented v2 engine is installed\n\
# separately with `install-hooks --agent kiro-cli`. Kiro v3 hook\n\
- # capture remains unsupported until its command-input contract is\n\
- # documented.\n\
+ # capture remains unsupported pending fixture-verified lifecycle\n\
+ # and built-in tool payloads for its standalone schema.\n\
# Managed workstreams are not installed by this command.\n\
{snippet}\n",
snippet = render_json_mcp_fragment(args)?,
diff --git a/crates/ai-memory-cli/src/commands/render_shared.rs b/crates/ai-memory-cli/src/commands/render_shared.rs
index 7ac46f3b..8b609a63 100644
--- a/crates/ai-memory-cli/src/commands/render_shared.rs
+++ b/crates/ai-memory-cli/src/commands/render_shared.rs
@@ -81,7 +81,7 @@ pub(crate) const KIMI_CODE_EVENTS: [(&str, &str); 10] = [
/// `(trigger-name-in-agent-config, POSIX hook-script-filename)`.
///
/// The v2 engine embeds hooks in agent configs (`~/.kiro/agents/*.json`)
-/// keyed by camelCase triggers, per kiro.dev/docs/cli/hooks and the
+/// keyed by camelCase triggers, per kiro.dev/docs/hooks and the
/// shipping `HookTrigger` serde in aws/amazon-q-developer-cli
/// (`crates/chat-cli/src/cli/agent/hook.rs`). The vocabulary is exactly
/// these five events — there is no PreCompact/SessionEnd/subagent
@@ -89,9 +89,10 @@ pub(crate) const KIMI_CODE_EVENTS: [(&str, &str); 10] = [
/// the matching `.sh` and `.ps1` files under `hooks/kiro-cli/`; the
/// install-hooks parity test fails if the bundle drifts.
///
-/// Kiro's v3 engine uses a different standalone registration format, but
-/// its command-input payload is not documented. Do not advertise or install
-/// v3 hooks until that input contract can be captured in fixtures and tested.
+/// Kiro's v3 engine uses a documented standalone registration format, but its
+/// live lifecycle and built-in tool payloads have not been accepted as
+/// fixtures. Do not advertise or install v3 hooks until those exact contracts
+/// are captured and tested.
pub(crate) const KIRO_CLI_V2_EVENTS: [(&str, &str); 5] = [
("agentSpawn", "session-start.sh"),
("userPromptSubmit", "user-prompt-submit.sh"),
diff --git a/crates/ai-memory-cli/src/commands/setup_agent.rs b/crates/ai-memory-cli/src/commands/setup_agent.rs
index 11533505..50524071 100644
--- a/crates/ai-memory-cli/src/commands/setup_agent.rs
+++ b/crates/ai-memory-cli/src/commands/setup_agent.rs
@@ -150,7 +150,8 @@ pub fn run(config: &Config, args: SetupAgentArgs) -> Result<()> {
// `[[hooks]]` TOML merge into the user's config.toml.
AgentChoice::KimiCode => emit_other(&emit_root, agent_sub, &args, &[&KIMI_CODE_EVENTS]),
// Kiro v2 embeds its lifecycle hooks in agent configs. Kiro v3 is
- // withheld until its command-input payload contract is documented.
+ // withheld until its live lifecycle and built-in tool payloads are
+ // captured in fixtures.
AgentChoice::KiroCli => {
emit_other(&emit_root, agent_sub, &args, &[&KIRO_CLI_V2_EVENTS]);
}
diff --git a/crates/ai-memory-cli/tests/removal.rs b/crates/ai-memory-cli/tests/removal.rs
index 675ff924..e1e8aace 100644
--- a/crates/ai-memory-cli/tests/removal.rs
+++ b/crates/ai-memory-cli/tests/removal.rs
@@ -1123,7 +1123,7 @@ fn uninstall_kiro_cli_hooks_preserves_user_and_v3_entries() {
r#"{"name":"local","hooks":{"stop":[{"command":"/x/hooks/kiro-cli/stop.sh"}]}}"#,
);
- // v3 is unsupported because its command-input contract is undocumented.
+ // v3 remains unsupported without accepted live payload fixtures.
// Uninstall must leave even an ai-memory-looking standalone file untouched.
let hooks_dir = kiro.join("hooks");
std::fs::create_dir_all(&hooks_dir).unwrap();
diff --git a/docs/install.md b/docs/install.md
index 035f52e3..cd98a3c7 100644
--- a/docs/install.md
+++ b/docs/install.md
@@ -738,9 +738,10 @@ Kimi Code hook entries accept only `event`, `matcher`, `command`, and
### Kiro CLI
Kiro CLI has one MCP surface. ai-memory supports the documented v2 lifecycle
-hook surface; Kiro v3 uses an incompatible standalone registration format and
-does not document the command-input payload yet. The global MCP file is
-`$KIRO_HOME/settings/mcp.json`, defaulting to
+hook surface. Kiro v3 now documents its incompatible standalone registration
+schema and generic command context, but ai-memory does not install it without
+sanitized live lifecycle and built-in tool payload fixtures. The global MCP
+file is `$KIRO_HOME/settings/mcp.json`, defaulting to
`~/.kiro/settings/mcp.json`; pass `--config-file .kiro/settings/mcp.json` for a
project-scoped entry.
diff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.md
index 47ecad33..51767f49 100644
--- a/docs/managed-workstreams.md
+++ b/docs/managed-workstreams.md
@@ -310,20 +310,26 @@ contract was verified against Kimi Code v0.29.0. The managed launcher accepts
`kimi`, `kimi-code`, and `kimi-cli`; all three resolve the installed `kimi`
executable.
-Kiro's explicit adapter covers only the default v2 engine. Official Kiro docs
-define UUID session IDs, checkout scoping, `--resume-id`, `$KIRO_HOME`, and the
-flat `$KIRO_HOME/sessions/cli/<uuid>.json` plus `<uuid>.jsonl` store. The current
-2.16.0 binary also exposes the v1 `Prompt`, `AssistantMessage`, and `ToolResults`
-event variants, but authentication prevented producing a new isolated live
-transcript during this audit. The parser therefore accepts only the known v1
-envelope, records unsupported versions as extraction loss, imports visible text
-and completed tool records only, and stays outside automatic selection until a
-logged-in current-format acceptance run is recorded. Exact lookups require a
-UUID, matching sibling `session_id`, and an exact canonical `cwd`; a linked ID
-cannot select another checkout's flat-store transcript. `--v3`, `--mode`, and a
-non-v2 `--agent-engine` select incompatible engines and pass through unchanged.
-The v2 `--yolo` translation is `--trust-all-tools`; an explicit narrower
-`--trust-tools` choice is never widened.
+Kiro's explicit adapter covers only the default v2 engine. The audited 2.16.0
+binary and v2 fixtures expose UUID session IDs, checkout scoping, `--resume-id`,
+`$KIRO_HOME`, and the flat `$KIRO_HOME/sessions/cli/<uuid>.json` plus
+`<uuid>.jsonl` store with v1 `Prompt`, `AssistantMessage`, and `ToolResults`
+events. Current official Kiro session documentation instead describes
+per-directory database persistence without publishing a filename, schema, or
+read-only transcript contract; its v3 guide confirms that v3 sessions are not
+backward-compatible or resumable in v2. Authentication prevented producing a
+new isolated live transcript during this audit. The parser therefore accepts
+only the known v1 flat-store envelope, records unsupported versions as
+extraction loss, imports visible text and completed tool records only, and stays
+outside automatic selection until a logged-in current-format acceptance run is
+recorded. Exact lookups require a UUID, matching sibling `session_id`, and an
+exact canonical `cwd`; a linked ID cannot select another checkout's flat-store
+transcript. `--v3`, `--mode`, and a non-v2 `--agent-engine` select incompatible
+engines and pass through unchanged. The v2 `--yolo` translation is
+`--trust-all-tools`; an explicit narrower `--trust-tools` choice is never
+widened. See Kiro's current
+[session management](https://kiro.dev/docs/cli/chat/session-management/) and
+[v3 compatibility](https://kiro.dev/docs/cli/v3/) references.
Grok needs no ai-memory hook installation for managed delivery either. Grok
ignores `SessionStart` stdout and its `UserPromptSubmit` hook is passive, so
diff --git a/docs/mcp-install.md b/docs/mcp-install.md
index fd80216c..e596e1f3 100644
--- a/docs/mcp-install.md
+++ b/docs/mcp-install.md
@@ -850,17 +850,19 @@ target before changing any of them. Project-local Kiro agents override global
agents, so `--config-file` is required when the active definition lives under
`.kiro/agents/`. The integration remains fail-open, injects pending handoffs
through `agentSpawn` stdout, and honors `$KIRO_HOME`. Kiro v3 hook capture is
-not installed because its registration migration guide does not document the
-command-input payload needed to validate capture and exclusion behavior. Follow
+not installed: its standalone schema and generic command context are now
+documented, but sanitized live lifecycle and built-in tool payload fixtures are
+still needed to validate capture, exclusions, and fail-open behavior. Follow
[#355](https://github.com/akitaonrails/ai-memory/issues/355) for v3 hook support
and [#356](https://github.com/akitaonrails/ai-memory/issues/356) for automatic
selection and broader version-aware managed support. Explicit
`ai-memory run kiro` (alias `kiro-cli`) manages the default v2 engine;
non-v2 engine selections pass through without session injection or import.
-Sources: <https://kiro.dev/docs/cli/mcp/configuration/>,
-<https://kiro.dev/docs/cli/reference/settings/>,
-<https://kiro.dev/docs/cli/hooks/>, and
+Sources: <https://kiro.dev/docs/mcp/configuration/>,
+<https://kiro.dev/docs/reference/settings/>,
+<https://kiro.dev/docs/hooks/>,
+<https://kiro.dev/docs/hooks/types/>, and
<https://kiro.dev/docs/cli/v3/hooks-migration/>.
## OpenClaw
diff --git a/docs/windows.md b/docs/windows.md
index aca5c7f3..1bbfed36 100644
--- a/docs/windows.md
+++ b/docs/windows.md
@@ -155,9 +155,10 @@ For Kiro CLI, `install-mcp --client kiro-cli --apply` writes
`%USERPROFILE%\.kiro\settings\mcp.json` unless `$env:KIRO_HOME` overrides the
root. `install-hooks --agent kiro-cli --apply` updates existing v2 agent files
under `.kiro\agents`; use `--config-file` for a project-local agent. Kiro v3
-hook capture remains unsupported until its command-input payload is documented.
-Run these commands from the same native Windows environment that launches Kiro
-so generated executable paths remain valid.
+hook capture remains unsupported pending sanitized live lifecycle and built-in
+tool payload fixtures for its documented standalone schema. Run these commands
+from the same native Windows environment that launches Kiro so generated
+executable paths remain valid.
## Scenario C: Prebuilt Release Binary (No Toolchain)