buildingjoshbetter · Oct 11, 2026 · Oct 11, 2026 · Oct 11, 2026 · Oct 11, 2026 · Oct 11, 2026
diff --git a/docs/compatibility.md b/docs/compatibility.md
@@ -2,22 +2,26 @@
 
 TrueMemory integrates with multiple AI CLI tools. Each CLI has different config formats and hook systems, but TrueMemory provides a unified adapter layer.
 
-## Feature Support
+## Configuration support
+
+This table describes what the adapters register or write. A `Registered` entry is not native lifecycle acceptance. See [validation status](#validation-status) before relying on automatic recall or extraction.
 
 | Feature | Claude Code | ChatGPT Desktop* | Codex CLI | Cursor | Gemini CLI | Kimi CLI | Hermes Agent | OpenClaw |
 |---------|:-----------:|:-------:|:---------:|:------:|:----------:|:--------:|:------------:|:--------:|
 | MCP server | JSON | JSON (experimental) | TOML | JSON | JSON | JSON | YAML | JSON |
-| Auto-recall at session start | Yes | No | Yes | Yes | Yes | Yes | Yes | Yes |
-| Auto-extract at session end | Yes | No | Yes | Yes | Yes | Yes | Yes | Yes |
-| Mid-session extraction (PreCompact) | Yes | No | No | Yes | Yes | Yes | No | No |
-| Message buffering (UserPromptSubmit) | Yes | No | Yes | No | No | No | No | No |
-| System prompt injection | Yes | No | Yes | Yes | Yes | No | No | No |
-| Hook protocol | JSON stdin/stdout | None | JSON stdin/stdout | JSON stdin/stdout | JSON stdin/stdout | JSON stdin/stdout | JSON stdin/stdout | JS plugin API |
+| Session-start hook | Registered | No | Registered | Registered | Registered | Registered | Registered | Staged JS |
+| Extraction boundary | Registered | No | Turn stop | Turn stop | Session end | Turn stop | Session end | Staged JS |
+| Compaction/finalization hook | Registered | No | PreCompact | preCompact | PreCompress | PreCompact | Session finalize | Staged JS |
+| Prompt/call hook | Registered | No | UserPromptSubmit | beforeSubmitPrompt | BeforeAgent | UserPromptSubmit | pre_llm_call | before_tool_call |
+| Instruction file written | Yes | No | AGENTS.md | .cursorrules* | GEMINI.md | truememory_prompt.md* | truememory_prompt.md* | truememory_prompt.md* |
+| Hook wire format | JSON stdin/stdout | None | JSON stdin/stdout | JSON stdin/stdout | JSON stdin/stdout | JSON stdin/stdout | JSON stdin/stdout | JS plugin API |
 | Config format | JSON | JSON | TOML | JSON (2 files) | JSON | TOML + JSON | YAML | JSON5 + JS |
 | Non-interactive install | `--cli claude` | `--cli chatgpt` | `--cli codex` | `--cli cursor` | `--cli gemini` | `--cli kimi` | `--cli hermes` | `--cli openclaw` |
 
 \* **ChatGPT Desktop is experimental and forward-looking:** ChatGPT Desktop does **not** currently load local MCP servers. OpenAI supports only remote HTTPS MCP connectors, enabled via developer mode in the ChatGPT *web* UI, and the macOS desktop app cannot enable developer mode (as of mid-2026). The adapter pre-stages `mcp.json` for when/if OpenAI enables local MCP support — TrueMemory will not appear in ChatGPT until then. See [ChatGPT Setup](setup-chatgpt.md).
 
+\* An instruction file being written does not establish that the host loads that file. Current loading of the adapter's legacy `.cursorrules` path and its generic `truememory_prompt.md` files has not been established by these checks.
+
 ## Config Locations
 
 | CLI | MCP Config | Hook Config | Detection Path |
@@ -27,30 +31,55 @@ TrueMemory integrates with multiple AI CLI tools. Each CLI has different config
 | Codex CLI | `~/.codex/config.toml` | `~/.codex/config.toml` | `~/.codex/` |
 | Cursor | `~/.cursor/mcp.json` | `~/.cursor/hooks.json` | `~/.cursor/` |
 | Gemini CLI | `~/.gemini/settings.json` | `~/.gemini/settings.json` | `~/.gemini/` |
-| Kimi CLI | `~/.kimi/mcp.json` | `~/.kimi/config.toml` | `~/.kimi/` |
-| Hermes Agent | `~/.hermes/config.yaml` | `~/.hermes/cli-config.yaml` | `~/.hermes/` |
-| OpenClaw | `~/.openclaw/openclaw.json` | `~/.openclaw/plugins/truememory/` | `~/.openclaw/` |
+| Kimi CLI (legacy adapter target) | `~/.kimi/mcp.json` | `~/.kimi/config.toml` | `~/.kimi/` |
+| Hermes Agent | `~/.hermes/config.yaml` | `~/.hermes/config.yaml` under `hooks` | `~/.hermes/` |
+| OpenClaw | `~/.openclaw/openclaw.json` | Manual: `~/.openclaw/extensions/truememory/`; adapter staging: `~/.openclaw/plugins/truememory/` | `~/.openclaw/` |
 
 ## Hook Events
 
 | Event | Claude Code | ChatGPT Desktop | Codex CLI | Cursor | Gemini CLI | Kimi CLI | Hermes Agent | OpenClaw |
 |-------|------------|---------|-----------|--------|------------|----------|-------------|----------|
-| Session start | `SessionStart` | — | `SessionStart` | `sessionStart` | `SessionStart` | `SessionStart` | `on_session_start` | `before_agent_run` |
-| Session end | `SessionEnd` | — | `Stop` | `stop` | `SessionEnd` | `Stop` | `on_session_end` | `agent_end` |
-| Pre-compact | `PreCompact` | — | — | `preCompact` | `PreCompress` | `PreCompact` | — | — |
-| User message | `UserPromptSubmit` | — | `UserPromptSubmit` | — | — | — | — | — |
+| Session start | `SessionStart` | None | `SessionStart` | `sessionStart` | `SessionStart` | `SessionStart` | `on_session_start` | `session_start` |
+| Extraction trigger | `SessionEnd` | None | `Stop` (turn) | `stop` (turn) | `SessionEnd` | `Stop` (turn) | `on_session_end` | `session_end` |
+| Compaction/finalization | `PreCompact` | None | `PreCompact` | `preCompact` | `PreCompress` | `PreCompact` | `on_session_finalize` | `before_compaction` |
+| Prompt/call registration | `UserPromptSubmit` | None | `UserPromptSubmit` | `beforeSubmitPrompt` | `BeforeAgent` | `UserPromptSubmit` | `pre_llm_call` | `before_tool_call` |
+
+Hermes `pre_llm_call` and OpenClaw `before_tool_call` are not exact user-message boundaries. OpenClaw names above are the shipped JavaScript registrations, whose native payload and lifecycle contract remain unverified.
+
+## Hook schemas and timeout units
+
+| Host | Registration shape | Session-start timeout | Other registered timeouts | Unit |
+| --- | --- | ---: | --- | --- |
+| Codex | `hooks.Event[]` groups with nested `hooks[]` and `type = "command"` | 10 | 5 | Seconds |
+| Cursor | `version: 1`, camelCase event arrays | 10 | 5 | Seconds |
+| Gemini | Event arrays of HookDefinition groups with nested `hooks[]` and `type: "command"` | 10000 | 5000 | Milliseconds |
+| Kimi legacy CLI | Flat `[[hooks]]` entries with `event` | 10 | 5 | Seconds |
+| Hermes | `config.yaml` event lists under `hooks` | 30 | Session end 30, pre-LLM 10, finalize 15 | Seconds |
+| OpenClaw | `openclaw.plugin.json` + `package.json` entrypoint + `index.js` | 10000 | Sync prompt 5000, compaction 5000 | JavaScript subprocess milliseconds |
+
+For second-based hooks, `10000 / 60 = 166.67` minutes and `5000 / 60 = 83.33` minutes, which are the old unintended values. The corrected values are 10 and 5 seconds. Gemini's native conversion is `10000 / 1000 = 10` seconds and `5000 / 1000 = 5` seconds.
+
+## Validation status
+
+Configuration contracts were reviewed against the adapters and official host documentation on 2026-10-10. Documentation checks parse the snippets and use synthetic isolated configurations; they do not launch a native host. Native tested versions for Codex, Cursor, Gemini, Kimi, Hermes and OpenClaw: none in this parity validation.
+
+Codex and Gemini recall commands identify both `--host` and the exact `--event`; their context output uses `hookSpecificOutput.additionalContext` and the corresponding `hookEventName`. Cursor `sessionStart` uses `additional_context`. Cursor `beforeSubmitPrompt` supports `continue`/`user_message`, so per-prompt recall injection is unsupported there; its hook remains registered for capture. These contracts depend on the host-aware hook changes in [#761](https://github.com/buildingjoshbetter/TrueMemory/issues/761) and [#763](https://github.com/buildingjoshbetter/TrueMemory/issues/763).
+
+Config presence and `truememory-ingest status` do not prove execution, payload translation, transcript capture or model-visible recall. [C05/#761](https://github.com/buildingjoshbetter/TrueMemory/issues/761), [C07/#763](https://github.com/buildingjoshbetter/TrueMemory/issues/763), [C08/#764](https://github.com/buildingjoshbetter/TrueMemory/issues/764) and [C09/#765](https://github.com/buildingjoshbetter/TrueMemory/issues/765) remain incomplete. The separately implemented [C06/#762 Codex rollout reader](https://github.com/buildingjoshbetter/TrueMemory/issues/762) does not establish the other host lifecycles. C10/#766 corrects manual configuration only.
+
+Contract references: [official OpenAI hooks](https://learn.chatgpt.com/docs/hooks), [Cursor hooks](https://prod.cursor.com/docs/hooks), [Gemini hooks](https://geminicli.com/docs/hooks/reference/), [legacy Kimi source](https://github.com/MoonshotAI/kimi-cli/blob/main/docs/en/customization/hooks.md), [current Kimi Code hooks](https://www.kimi.ai/help/kimi-code/cli-hooks), [Hermes shell hooks](https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks/), [OpenClaw discovery](https://docs.openclaw.ai/cli/plugins/install) and [package entrypoints](https://docs.openclaw.ai/plugins/manifest/package-json).
 
 ## Shared Memory
 
 All CLIs share the same TrueMemory database (`~/.truememory/memories.db`). Memories stored from one CLI are available in all others. User scoping via `--user` flag works across CLIs.
 
 ## Known Limitations
 
-- **Codex CLI**: MCP and hooks share a single `config.toml`. TrueMemory uses additive merges to avoid overwriting other settings.
+- **Codex CLI**: MCP and inline hooks share `config.toml`. Hook handlers are nested under event groups, use second-based timeouts and require Codex hook trust. `Stop` is a turn boundary.
 - **ChatGPT Desktop**: Local MCP configs are **not currently loaded by ChatGPT Desktop** — OpenAI supports only remote HTTPS MCP connectors via developer mode on the web UI (the macOS app cannot enable it as of mid-2026). The adapter pre-stages config for a possible future and requires the actual app to be installed. Lifecycle hooks and system prompt file injection are not supported. There is no ChatGPT Desktop for Linux.
-- **Cursor**: MCP (`mcp.json`) and hooks (`hooks.json`) are separate files. Event names are camelCase. `hooks.json` requires `"version": 1` top-level key.
-- **Gemini CLI**: MCP and hooks share a single `settings.json`. Uses different event names than Claude Code (`SessionEnd` instead of `Stop`, `PreCompress` instead of `PreCompact`).
-- **Kimi CLI**: Hooks are in beta. Event availability may change.
-- **Hermes Agent**: Gateway hooks (Telegram/Discord/etc.) require separate `handler.py` setup.
-- **OpenClaw**: Uses a JS plugin system — requires Node.js at runtime for the plugin.
+- **Cursor**: MCP (`mcp.json`) and hooks (`hooks.json`) are separate files. Event names are camelCase, timeouts are seconds and `hooks.json` requires `"version": 1`. Local user hooks are unavailable to cloud agents. Per-prompt recall injection is unsupported by `beforeSubmitPrompt`.
+- **Gemini CLI**: MCP and nested hook definitions share `settings.json`; timeouts are milliseconds. Its `SessionEnd`, `BeforeAgent` and `PreCompress` events differ from Claude Code.
+- **Kimi CLI**: The adapter targets legacy `~/.kimi/` and its beta hooks. Current Kimi Code documentation uses `~/.kimi-code/`; support for that location is unverified.
+- **Hermes Agent**: MCP and shell hooks share `config.yaml`. Hermes supports shell hooks on CLI and gateway surfaces, but TrueMemory's native translation remains unverified. Separate gateway extensions use `HOOK.yaml`/`handler.py`.
+- **OpenClaw**: Requires a JavaScript runtime and all three package files. The adapter's `plugins` staging directory differs from documented `extensions` discovery. Plugin user/database propagation, native payloads and context delivery remain unverified.
 - **All CLIs**: The first search after model download may be slow (model loading).
diff --git a/docs/setup-codex.md b/docs/setup-codex.md
@@ -23,29 +23,46 @@ truememory-ingest setup
 
 ### 1. MCP Server + Lifecycle Hooks
 
-Both MCP and hooks live in `~/.codex/config.toml`. Add the following:
+Both MCP and inline hooks live in `~/.codex/config.toml`. Merge the MCP entry and append the TrueMemory matcher groups below, preserving other settings and hook handlers. Replace the placeholder paths with absolute paths in the environment where TrueMemory is installed.
 
 ```toml
 [mcp_servers.truememory]
 command = "/path/to/python"
 args = ["-m", "truememory.mcp_server"]
 
-[[hooks]]
-event = "SessionStart"
-command = "/path/to/python /path/to/truememory/ingest/hooks/session_start.py"
-timeout = 10000
+[[hooks.SessionStart]]
 
-[[hooks]]
-event = "Stop"
-command = "/path/to/python /path/to/truememory/ingest/hooks/stop.py"
-timeout = 5000
+[[hooks.SessionStart.hooks]]
+type = "command"
+command = "/path/to/python /path/to/truememory/ingest/hooks/session_start.py --host codex --event SessionStart"
+timeout = 10
 
-[[hooks]]
-event = "UserPromptSubmit"
-command = "/path/to/python /path/to/truememory/ingest/hooks/user_prompt_submit.py"
-timeout = 5000
+[[hooks.Stop]]
+
+[[hooks.Stop.hooks]]
+type = "command"
+command = "/path/to/python /path/to/truememory/ingest/hooks/stop.py --host codex --event Stop"
+timeout = 5
+
+[[hooks.UserPromptSubmit]]
+
+[[hooks.UserPromptSubmit.hooks]]
+type = "command"
+command = "/path/to/python /path/to/truememory/ingest/hooks/user_prompt_submit.py --host codex --event UserPromptSubmit"
+timeout = 5
+
+[[hooks.PreCompact]]
+
+[[hooks.PreCompact.hooks]]
+type = "command"
+command = "/path/to/python /path/to/truememory/ingest/hooks/compact.py --host codex --event PreCompact"
+timeout = 5
 ```
 
+Codex uses event groups with nested command handlers, and `timeout` is in seconds. Keep one hook representation per configuration layer to avoid duplicate execution. Review and trust the new definitions through Codex's `/hooks` command before expecting execution. See the [official OpenAI hooks documentation](https://learn.chatgpt.com/docs/hooks).
+
+The installed command identifies the host and exact event independently of stdin. `SessionStart` and `UserPromptSubmit` use `hookSpecificOutput.additionalContext` with the matching `hookEventName`. `Stop` is a turn completion event, not proof that the session ended. Native execution, transcript capture and model-visible context remain unverified here; see [compatibility limits](compatibility.md#validation-status).
+
 Find your Python path: `python3 -c "import sys; print(sys.executable)"`
 
 Find hook paths: `python3 -c "from pathlib import Path; import truememory; print(Path(truememory.__file__).parent / 'ingest' / 'hooks')"`
@@ -58,17 +75,19 @@ For auto-recall/auto-store instructions, run:
 truememory-ingest setup --cli codex
 ```
 
-This creates `~/.codex/AGENTS.md` with TrueMemory system prompt instructions.
+This adds TrueMemory instructions to `~/.codex/AGENTS.md`; preserve unrelated instructions when editing manually.
 
 ## Verification
 
 ```bash
 truememory-ingest status
 ```
 
+This checks configuration presence. It does not prove that a Codex event ran or that its output reached the model. No native Codex version was exercised by the documentation parity checks.
+
 ## Troubleshooting
 
 - **MCP not connecting**: Verify the Python path in `config.toml` points to the environment with TrueMemory installed.
 - **Existing config**: TrueMemory uses additive merges — your existing Codex config is preserved.
-- **Hooks not firing**: Check that the hook script paths are absolute and the Python executable is correct.
+- **Hooks not firing**: Check absolute paths, the Python environment and `/hooks` trust status. Quote each path inside `command` if it contains spaces.
 - **Windows Defender ASR**: If commands are blocked, use `python -m` form instead. See [debugging guide](guides/debugging.md#windows-defender-asr-blocks-truememory-mcpexe).
diff --git a/docs/setup-cursor.md b/docs/setup-cursor.md
@@ -23,7 +23,7 @@ truememory-ingest setup
 
 ### 1. MCP Server
 
-Add to `~/.cursor/mcp.json`:
+Merge this server entry into `~/.cursor/mcp.json`, preserving other servers and settings:
 
 ```json
 {
@@ -38,34 +38,44 @@ Add to `~/.cursor/mcp.json`:
 
 ### 2. Lifecycle Hooks
 
-Add to `~/.cursor/hooks.json`:
+Merge these event entries into `~/.cursor/hooks.json`, preserving other handlers. Replace the placeholder paths with absolute installed paths:
 
 ```json
 {
   "version": 1,
   "hooks": {
     "sessionStart": [
       {
-        "command": "/path/to/python /path/to/truememory/ingest/hooks/session_start.py",
-        "timeout": 10000
+        "command": "/path/to/python /path/to/truememory/ingest/hooks/session_start.py --host cursor --event sessionStart",
+        "timeout": 10
       }
     ],
     "stop": [
       {
-        "command": "/path/to/python /path/to/truememory/ingest/hooks/stop.py",
-        "timeout": 5000
+        "command": "/path/to/python /path/to/truememory/ingest/hooks/stop.py --host cursor --event stop",
+        "timeout": 5
+      }
+    ],
+    "beforeSubmitPrompt": [
+      {
+        "command": "/path/to/python /path/to/truememory/ingest/hooks/user_prompt_submit.py --host cursor --event beforeSubmitPrompt",
+        "timeout": 5
       }
     ],
     "preCompact": [
       {
-        "command": "/path/to/python /path/to/truememory/ingest/hooks/compact.py",
-        "timeout": 5000
+        "command": "/path/to/python /path/to/truememory/ingest/hooks/compact.py --host cursor --event preCompact",
+        "timeout": 5
       }
     ]
   }
 }
 ```
 
+Cursor's `timeout` is in seconds. `sessionStart` accepts `additional_context`; `beforeSubmitPrompt` accepts `continue` and `user_message`, so TrueMemory registers it for prompt capture and does not inject per-prompt recall there. `stop` marks agent completion, and `preCompact` observes compaction. See the [official Cursor hooks contract](https://prod.cursor.com/docs/hooks).
+
+These are local user hooks. Cursor cloud agents do not load `~/.cursor/hooks.json`. Native delivery, capture and model-visible recall remain unverified here; see [compatibility limits](compatibility.md#validation-status).
+
 Find your Python path: `python3 -c "import sys; print(sys.executable)"`
 
 Find hook paths: `python3 -c "from pathlib import Path; import truememory; print(Path(truememory.__file__).parent / 'ingest' / 'hooks')"`
@@ -78,19 +88,21 @@ For auto-recall/auto-store instructions, run:
 truememory-ingest setup --cli cursor
 ```
 
-This creates `~/.cursor/.cursorrules` with TrueMemory system prompt instructions.
+The adapter writes `~/.cursor/.cursorrules`. This documentation check does not establish that the current Cursor release loads that legacy location as rules.
 
 ## Verification
 
 ```bash
 truememory-ingest status
 ```
 
+This checks configuration presence, not event execution or model-visible context. No native Cursor version was exercised by the documentation parity checks.
+
 ## Troubleshooting
 
 - **MCP not connecting**: Verify the Python path in `mcp.json` points to the environment with TrueMemory installed.
 - **Existing config**: TrueMemory uses additive merges — your existing Cursor config is preserved.
-- **Hooks not firing**: Check that event names are camelCase (`sessionStart`, `stop`, `preCompact`). PascalCase will silently fail.
+- **Hooks not firing**: Check exact camelCase event names (`sessionStart`, `stop`, `beforeSubmitPrompt`, `preCompact`), installed paths and the Python environment. Quote paths inside `command` if they contain spaces.
 - **Two config files**: MCP lives in `~/.cursor/mcp.json`, hooks live in `~/.cursor/hooks.json`. They are separate files.
 - **Version key**: `hooks.json` requires `"version": 1` at the top level.
 - **Windows Defender ASR**: If commands are blocked, use `python -m` form instead. See [debugging guide](guides/debugging.md#windows-defender-asr-blocks-truememory-mcpexe).