Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
docs: document managed kimi adapter and handoff delivery fix
Lucas Oliveira23e1f9bb016b
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 4c62eab5..41b640d9 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -7,6 +7,28 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]+### Added+- Managed workstreams now support Kimi Code through `ai-memory run kimi`.+ Returning runs resume the linked native session with `--session <id>`;+ fresh sessions are discovered post-exit by exact checkout match through+ `state.json`'s `workDir` (the session bucket name is a one-way hash and is+ never parsed). The adapter reads `$KIMI_CODE_HOME/sessions` (default+ `~/.kimi-code/sessions`) and imports only visible user/assistant/tool+ messages and compaction summaries from `agents/main/wire.jsonl`, excluding+ system prompts, hidden reasoning, hook-injected context (`hook_result` and+ related origins), and subagent transcripts. Wrapper `--yolo` maps to Kimi+ Code's `--yolo`, and kimi joins the automatic bare-run harness pool.++### Fixed+- Kimi Code handoffs are now delivered through the `UserPromptSubmit` hook+ instead of `SessionStart`. Kimi Code fires `SessionStart` but discards the+ hook's stdout/result (verified against kimi-code v0.28.1,+ `packages/agent-core/src/session/index.ts`), so the previous hook consumed+ pending handoffs — legacy and managed — without ever showing them to the+ model. `UserPromptSubmit` stdout is injected as a user message before the+ turn. Re-run `ai-memory install-hooks --agent kimi-code --apply` after+ upgrading.+## [1.17.3] - 2026-07-22### Fixeddiff --git a/README.md b/README.mdindex 7052f400..f6db823b 100644--- a/README.md+++ b/README.md@@ -31,13 +31,13 @@| Oh My Pi / OMP | Supported | Use `--client omp` / `--agent omp` (or `oh-my-pi`) for native `.omp` MCP config + TypeScript extension; generated extension enforces capture exclusions. || Pi | Supported | Generated `~/.pi/agent/extensions/ai-memory.ts` extension provides lifecycle capture and an HTTP MCP bridge; generated extension enforces capture exclusions. || Crush | Managed-only | `ai-memory run crush` resumes its project-local session database and supplies portable context through a temporary supported global-context file; no lifecycle-hook installer is provided. |-| Managed workstreams | Opt-in | `ai-memory run` provides transparent cross-harness continuity for Claude Code, Codex, OpenCode, Pi, Crush, and OMP. Direct launches remain unchanged. See [`docs/managed-workstreams.md`](docs/managed-workstreams.md). |+| Managed workstreams | Opt-in | `ai-memory run` provides transparent cross-harness continuity for Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, and OMP. Direct launches remain unchanged. See [`docs/managed-workstreams.md`](docs/managed-workstreams.md). || Claude Desktop | MCP-only | Uses `mcp-remote`; no lifecycle hooks. || OpenClaw | Supported | MCP config + native plugin lifecycle hooks; generated plugin enforces capture exclusions. || Antigravity CLI | Supported | MCP config (`serverUrl`) + lifecycle hooks (`agy` alias). || 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 handoff injection — Grok ignores `SessionStart` stdout, so recover handoffs via MCP `memory_handoff_accept`. Skills root: `.grok/skills` / `$GROK_HOME/skills` (default `~/.grok/skills`). || 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 `SessionStart` stdout. |+| 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. || VS Code Copilot | MCP-only | `.vscode/mcp.json` for Copilot agent mode; no lifecycle hooks (Copilot does not expose them yet). || Hermes Agent | Community | A community-maintained [`ai-memory-hermes-plugin`](https://github.com/MrLuciano/ai-memory-hermes-plugin) is available. It is not part of ai-memory's first-party install surface; review its compatibility matrix, install/uninstall scripts, and secret handling before using it. || LLM/auth providers | Supported | Anthropic, OpenAI, OpenAI OAuth/Codex, GitHub Copilot, Gemini, OpenCode Zen/Go, OpenAI-compatible endpoints, and generic OIDC device auth for native hooks. |diff --git a/docs/install.md b/docs/install.mdindex 27bea4ef..597c86ee 100644--- a/docs/install.md+++ b/docs/install.md@@ -637,8 +637,12 @@ native `ai-memory hook --event … --agent kimi-code` commands on local installs(local spool plus batched delivery, capture-policy v1 enforced); the stagedscript bundle under `~/.local/share/ai-memory/hooks/kimi-code/` is thecompatibility fallback (fire-and-forget POSTs to `/hook`). A pending handoff-is injected at `SessionStart` through the hook's stdout, which Kimi Code-appends to the model context.+is injected at `UserPromptSubmit` through the hook's stdout, which Kimi Code+appends to the model context as a user message before the turn; Kimi Code+fires `SessionStart` but discards that hook's stdout, so hooks installed by+an older release consumed handoffs without delivering them. Re-run+`ai-memory install-hooks --agent kimi-code --apply` after upgrading to pick+up the corrected delivery path (required for `ai-memory run kimi`).Kimi Code hook entries accept only `event`, `matcher`, `command`, and`timeout`; extra fields make the whole `config.toml` fail to load, so preferdiff --git a/docs/managed-harness-contributions.md b/docs/managed-harness-contributions.mdindex 4e87641a..b9edf574 100644--- a/docs/managed-harness-contributions.md+++ b/docs/managed-harness-contributions.md@@ -1,10 +1,10 @@# Adding a managed harnessManaged-workstream support is narrower than MCP or lifecycle-hook support. This-release can manage Claude Code, Codex, OpenCode, Pi, Crush, and OMP. Gemini CLI,-Kimi Code, Devin CLI, Cursor, Grok Build CLI, and the other integrations in the-README support matrix do not become managed merely because ai-memory can capture-their hooks.+release can manage Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, and OMP.+Gemini CLI, Devin CLI, Cursor, Grok Build CLI, and the other integrations in+the README support matrix do not become managed merely because ai-memory can+capture their hooks.A managed adapter must preserve a harness's real native session, deliver theportable workstream delta exactly once, and import only visible history withoutdiff --git a/docs/managed-workstreams.md b/docs/managed-workstreams.mdindex 42934ad1..41c9b53c 100644--- a/docs/managed-workstreams.md+++ b/docs/managed-workstreams.md@@ -1,7 +1,8 @@# Managed cross-harness workstreams`ai-memory run` is an opt-in launcher that lets one logical coding session move-between Claude Code, Codex, OpenCode, Pi, Crush, and OMP. Direct agent launches+between Claude Code, Codex, OpenCode, Pi, Crush, Kimi Code, and OMP. Direct+agent launcheskeep their existing ai-memory behavior. There is no global mode toggle and no`switch` command: using `run` selects the current workstream and transparentlycreates or resumes the correct native session for the requested harness.@@ -25,7 +26,7 @@ second copy of each harness's option schema. Other wrapper options come first:```textai-memory run [--workspace NAME] [--project NAME][--workstream NAME | --new NAME] [--executable PATH] [--yolo]- [claude|codex|opencode|pi|crush|omp] [native arguments...]+ [claude|codex|opencode|pi|crush|omp|kimi] [native arguments...]```The default is the most recently selected workstream for the current repository@@ -36,7 +37,8 @@ branching controls, not harness-switch controls.## Automatic harness selectionWith no harness name, `ai-memory run` inspects checkout-local sessions for-Claude Code, Codex, OpenCode, Pi, and Crush. For an empty workstream it resumes+Claude Code, Codex, OpenCode, Pi, Crush, and Kimi Code. For an empty workstream+it resumesthe newest session automatically. For an established workstream, server statetakes precedence: ai-memory resumes the most recently linked harness that stillhas a usable local session. It never chooses a newer but obsolete session from@@ -84,7 +86,10 @@ consume the later adoption opportunity.3. `AI_MEMORY_RUN_ID` marks lifecycle hooks as managed. SessionStart links theactual native session and injects only the portable events that session hasnot seen. Crush, which has no SessionStart hook, receives the same bounded- packet through a temporary `options.global_context_paths` entry. Direct+ packet through a temporary `options.global_context_paths` entry. Kimi Code+ fires SessionStart but discards its stdout, so the kimi adapter links there+ and delivers the packet through the UserPromptSubmit hook instead, whose+ stdout Kimi Code injects as a user message before the turn. Directlaunches continue to use the existing single-use handoff path.4. When the child exits, ai-memory reads the native transcript store withoutmodifying it. Visible user/assistant messages, completed tool calls/results,@@ -118,6 +123,7 @@ is labelled completed evidence and must never be replayed as a pending call.| OpenCode | native default creation | `--session <id>` | `~/.local/share/opencode/opencode.db` opened read-only || Pi | generated `--session-id` | `--session <id>` | `~/.pi/agent/sessions/**/*.jsonl` || Crush | native default creation | `--session <id>` | `<project>/.crush/crush.db` opened read-only |+| Kimi Code | native default creation | `--session <id>` | `$KIMI_CODE_HOME/sessions/*/*/agents/main/wire.jsonl` || OMP | native default creation | `--resume=<id>` | `~/.omp/agent/sessions/**/*.jsonl` |An explicit native selector such as Claude's `--resume`, OpenCode's `--session`,@@ -127,7 +133,8 @@ Pi and OMP `--session-dir` values and Crush `--data-dir` values are passedthrough unchanged and used as the read-only import root. Native storeenvironment overrides are also honored:`CLAUDE_CONFIG_DIR`, `CODEX_HOME`, `XDG_DATA_HOME`,-`PI_CODING_AGENT_SESSION_DIR`, and `PI_CODING_AGENT_DIR`. The Pi-family adapter+`PI_CODING_AGENT_SESSION_DIR`, `PI_CODING_AGENT_DIR`, and `KIMI_CODE_HOME`.+The Pi-family adapteralso recognizes a complete `.jsonl.<nonce>.tmp` atomic-write file when a nativeprocess exits before renaming it; incomplete final JSONL records are neverimported. Help, version, and known utility subcommands pass through without@@ -139,11 +146,12 @@ chooser.the harness's native dangerous mode. The translation is Claude Code`--dangerously-skip-permissions`, Codex`--dangerously-bypass-approvals-and-sandbox`, OpenCode `--auto`, Pi `--approve`,-and Crush `--yolo`. OMP currently needs no added flag. ai-memory does not add a-duplicate when the translated native flag is already present.+Crush `--yolo`, and Kimi Code `--yolo`. OMP currently needs no added flag.+ai-memory does not add a duplicate when the translated native flag is already+present.Managed support is intentionally narrower than the general integration matrix.-Gemini CLI, Kimi Code, Devin CLI, Cursor, Grok Build CLI, and other agents may+Gemini CLI, Devin CLI, Cursor, Grok Build CLI, and other agents mayhave MCP or lifecycle-hook support without native managed resume. Contributorsadding another managed harness must follow the [managed-harness contributionprotocol](managed-harness-contributions.md), including read-only extraction,@@ -161,8 +169,21 @@ ai-memory install-hooks --agent codex --applyai-memory install-hooks --agent opencode --applyai-memory install-hooks --agent pi --applyai-memory install-hooks --agent omp --apply+ai-memory install-hooks --agent kimi-code --apply```+Refreshing the Kimi Code hooks is mandatory when upgrading from a release+before managed kimi support: those hooks fetched the handoff at SessionStart,+whose stdout Kimi Code discards, so pending handoffs were consumed without+ever reaching the model. Current hooks deliver it at UserPromptSubmit.++Known Kimi Code adapter limitations: subagent transcripts+(`agents/<id>/wire.jsonl` other than `main`) are not imported in v1 and are+recorded as an extraction-loss annotation; the session bucket directory name+is a one-way hash of the working directory, so discovery always reads+`state.json`'s `workDir` and never parses the bucket name. The native+contract was verified against Kimi Code v0.28.1.+Crush needs no ai-memory hook installation for managed mode. The launcher readsits one-time context from the server, copies the existing global Crush JSON intoa private temporary directory, appends an ephemeral context path, and points the@@ -205,7 +226,7 @@ process launch is fatal; ai-memory does not silently start an unmanaged agent.## Privacy and storage boundariesai-memory's managed adapters do not write to Claude, Codex, OpenCode, Pi, Crush,-or OMP private stores. The launched harness retains normal ownership of its own+Kimi Code, or OMP private stores. The launched harness retains normal ownership of its ownsession writes. Adapters read only documented or observed local session formats.Provider credentials, encrypted content, system/developer prompt records, andhidden reasoning are not copied. The server sanitizer runs before both the@@ -222,8 +243,8 @@ belong in wiki pages through consolidation or explicit durable writes.project name. Wiki paths are UUID-keyed, so it moves no server directory, sourcecheckout, or native harness session. If the source checkout path itself isrenamed, absolute-path session locators used by Claude Code, Codex, OpenCode,-Pi, and OMP may still reference the old path; Crush's project-local `.crush`-database moves with the checkout.+Pi, Kimi Code (`state.json`'s `workDir`), and OMP may still reference the old+path; Crush's project-local `.crush` database moves with the checkout.There is no portable, supported API that rewrites every harness's privateproject locator. ai-memory therefore does not mutate those stores or silently@@ -238,8 +259,8 @@ checkout to match exactly.## Manual acceptanceThe opt-in acceptance runner exercises launcher edge cases and then orchestrates-the locally installed Claude, Codex, OpenCode, Pi, Crush, and OMP CLIs through-one real workstream:+the locally installed Claude, Codex, OpenCode, Pi, Crush, OMP, and Kimi CLIs+through one real workstream:```bashscripts/managed-workstream-acceptance.sh@@ -251,9 +272,11 @@ the Git fixture are isolated under a temporary directory. Claude, Codex, andOpenCode receive only copied authentication material; OMP receives a temporaryagent directory with read-consistent credential/model database backups andcopied settings. Crush uses its existing global provider configuration and an-isolated project database. The deterministic phase also covers first-run-adoption, bare-mode selection and empty-directory failure, wrapper `--yolo`,-lease exclusion, Crush context cleanup, and the established-workstream guard+isolated project database. Kimi Code runs with an isolated `$KIMI_CODE_HOME`+seeded with the operator's provider configuration. The deterministic phase+also covers first-run adoption, bare-mode selection and empty-directory+failure, wrapper `--yolo`, lease exclusion, Crush context cleanup, a fake-mode+Kimi store/resume/import round trip, and the established-workstream guardagainst obsolete sessions. Native session creation, read-only extraction,cross-harness injection, and returning resume paths are all exercised. Dockerwrapper host execution and remote URL preservation are covered separately by