---
title: memhtml hook
description: "The engine every installed hook calls. Reads the host's hook payload on stdin, runs recall or transcript indexing under a hard time bound, and writes the HOST'S protocol to stdout (plain text or the host's JSON), never this envelope; any failure prints nothing and exits 0, so a hook can never block a turn."
---

## 1. Synopsis

The engine every installed hook calls. Reads the host's hook payload on stdin, runs recall or transcript indexing under a hard time bound, and writes the HOST'S protocol to stdout (plain text or the host's JSON), never this envelope; any failure prints nothing and exits 0, so a hook can never block a turn.

```sh
memhtml hook <event> --host <string> [options]
```

## 2. Arguments

| Argument | Required | Description |
| --- | --- | --- |
| `event` | yes | Which lifecycle event fired: one of session-start, user-prompt-submit, pre-compact, session-end. |

## 3. Flags

| Flag | Type | Default | Values | Description |
| --- | --- | --- | --- | --- |
| `--host` | string | *no default* | `claude`, `codex`, `cursor`, `opencode` | Which host's payload shape to read and which output dialect to write. **Required.** |
| `--trace-root` | string | *no default* | *no fixed set* | Where this host writes transcripts, for the events that index them. Defaults to $MEMHTML\_TRACE\_ROOT. |
| `--limit` | integer | `5` | *no fixed set* | Hits to inject on a per-prompt recall. |
| `--budget` | integer | `3000` | *no fixed set* | Character budget for the session-start context pack. |

Every command also accepts the [global flags](/reference/global-flags/).

## 4. Response

On success the command writes one JSON envelope to stdout, and its `type` is `hook.output`.

On failure it writes the failure envelope, whose `code` comes from [error codes](/reference/error-codes/).

[The JSON envelope](/reference/envelope/) gives the fields both shapes carry. [Response types](/reference/response-types/) lists every value `type` takes across the binary.

## 5. Further reading

No guide block names this command. The [guide](/reference/guide/) is the workflow prose the CLI ships beside the command table: which command to reach for, and in what order.

## 6. Provenance

A loader generates this page from `apps/cli/src/commands.ts` while the site builds, so no file in the repository holds it: the `COMMANDS` array there is the one source of argument parsing, of `memhtml manifest`, and of `AGENTS.md`. Change the registry and this page changes with it.