1. Synopsis
Ranked search: four RRF arms plus MMR. Degrades to the lexical floor.
memhtml search <query> [options]2. Arguments
| Argument | Required | Description |
|---|---|---|
query |
yes | Prose. A double-quoted span demands those words in that order; nothing else is syntax. |
3. Flags
| Flag | Type | Default | Values | Description |
|---|---|---|---|---|
--type |
string, repeatable | no default | episodic, semantic, procedural, agent_insight, user_preference, error_pattern, verdict, precedent, task |
Restrict to one memory type. Repeatable; each occurrence broadens (ANY-of). |
--workspace |
string | no default | no fixed set | Restrict to one workspace. STRICT: a scoped query never returns a memory with no workspace. |
--tag |
string, repeatable | no default | no fixed set | Restrict to memories carrying any of these tags. Repeatable; each broadens. |
--entity |
string | no default | no fixed set | Restrict to memories carrying one type:name entity reference, e.g. service:checkout-api, the form a hit’s entities publishes, so a hop is a copy. A scope matching nothing returns no hits and says so; it never widens. |
--facet |
string, repeatable | no default | no fixed set | Restrict to memories carrying a <dl> facet, as name=value; the value may contain =, the name may not. Repeatable, and the composition is fixed: values under the SAME name broaden (--facet doc-type=runbook --facet doc-type=guide is either), DIFFERENT names narrow (--facet doc-type=runbook --facet tier=1 is both). This is the extension axis: memhtml’s element and meta vocabularies are closed, so a consumer’s own document kinds, states, and tiers live in <dt>/<dd> pairs and are queried here. The match is on the facet’s TEXT with no case folding, so write the halves you mean to query. The stored form is the element’s text content, which the parser collapses whitespace runs in and trims — so <dd>runbook rollback</dd> is stored and queried single-spaced. There is no numeric comparison: a <data value> is indexed UNITLESS because the unit lives in the prose beside it, so the caller owns the unit and matches the text it wrote. |
--include-archived |
flag | false |
no fixed set | Include archived memories. Eviction is a git mv, so they still exist. |
--as-of |
string | no default | no fixed set | Point-in-time view: returns what was believed valid at this ISO instant, including since-superseded memories (marked superseded_by). The validity window is coalesce(valid_from, event_at, created_at) <= as-of < valid_until. |
--limit |
integer | 10 |
no fixed set | Hits to return. |
Every command also accepts the global flags.
4. Response
On success the command writes one JSON envelope to stdout, and its type is memory.hits.
On failure it writes the failure envelope, whose code comes from error codes.
The JSON envelope gives the fields both shapes carry. Response types lists every value type takes across the binary.
5. Further reading
The guide blocks that name this command:
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.