1. Synopsis
Write one memory. Content-hash duplicates return the existing path, uncommitted.
memhtml write --title <string> --type <string> [options]2. Arguments
This command takes no positional arguments.
3. Flags
| Flag | Type | Default | Values | Description |
|---|---|---|---|---|
--title |
string | no default | no fixed set | The memory’s title. Becomes the <title> and the filename slug. Required. |
--claim |
string | no default | no fixed set | The one load-bearing sentence. Becomes the <mark> span and files.gist. Exactly one of --claim or --article-html. |
--body |
string, repeatable | no default | no fixed set | A prose paragraph after the claim. Repeatable, one <p> each. |
--article-html |
string | no default | no fixed set | Raw <article> markup used verbatim in place of --claim/--body. Must contain exactly one <mark> in the first <p> or <li>; the first <time datetime> becomes the memory’s event time. The store refuses format violations before any commit. Exactly one of --claim or --article-html. |
--type |
string | no default | episodic, semantic, procedural, agent_insight, user_preference, error_pattern, verdict, precedent, arc, task |
The memory type. arc is admitted here, on the operator surface, for curated import and deliberately authored rules; the agent tools (memory_write) still refuse it, because an agent naming an arc asserts a conclusion the corpus has not earned. Required. |
--path |
string | no default | no fixed set | An explicit path override. One that is not a usable memory path (rooted in a PARA bucket, ending in .html, no . or .. segment) is IGNORED and the placement rule decides instead, so a malformed override lands the memory somewhere you did not name — pass --strict-path to have it refused instead. One a file ALREADY occupies is REFUSED with ERR_WRITE_CONFLICT and nothing is written or committed: this corpus overwrites nothing, and an explicit path gets no -2 suffix because you named one path. To replace what a memory says, use memhtml correct <path>. |
--strict-path |
flag | false |
no fixed set | Refuse an unusable --path instead of letting the placement rule decide. By default a --path that is not a usable memory path is re-derived, so the memory lands somewhere you did not name and the response reports that other path as a success. With this flag the write is REFUSED with ERR_INVALID_MEMORY naming the clause the path broke, and nothing is written, staged, or committed. It governs the path you NAMED: with no --path there is nothing to be strict about and the flag changes nothing, while an EMPTY or blank --path is named rather than absent and is refused — that is what your own path template renders when it produced nothing. An OCCUPIED path is refused with ERR_WRITE_CONFLICT with or without it. |
--workspace |
string | no default | no fixed set | Routes the memory to projects/<slug>/. |
--tag |
string | no default | no fixed set | A tag. Repeatable; the first one routes an unplaced resource memory. |
--entity |
string, repeatable | no default | no fixed set | A type:name entity reference, e.g. service:checkout-api. Repeatable. |
--importance |
integer | no default | no fixed set | 1-10, a display ordinal. The retention scorer divides by 10. |
--confidence |
string | no default | no fixed set | 0-1. 1.0 is an unqualified assertion. |
--session-id |
string | no default | no fixed set | The Claude Code session. Stamped into the head AND indexed as a link. |
--prompt-id |
string | no default | no fixed set | The prompt within that session. |
--turn-uuid |
string | no default | no fixed set | The turn within that session. |
Every command also accepts the global flags.
4. Response
On success the command writes one JSON envelope to stdout, and its type is memory.written.
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.