---
title: memhtml write
description: Write one memory. Content-hash duplicates return the existing path, uncommitted.
---

## 1. Synopsis

Write one memory. Content-hash duplicates return the existing path, uncommitted.

```sh
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](/reference/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](/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

The guide blocks that name this command:

* [`write-surfaces`](/reference/guide/write-surfaces/)
* [`when-to-batch`](/reference/guide/when-to-batch/)
* [`code-mode`](/reference/guide/code-mode/)

## 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.