Creates the entry if it is new and revises it if the key already
    exists. Returns an opaque entry version you can pass to `revise` or
    `forget` as `expected_version` for optimistic concurrency.

    Pass `idempotency_key` when retrying: the same key with the same
    payload returns the original result instead of writing twice.
    

    `profile` selects retrieval quality and cost: fast, balanced,
    verified, or deep. Higher profiles do more reflection and return more
    provenance, and are gated by the workspace plan — call `status` to see
    which profiles this key may use. Smart retrieval is this argument, not
    a separate tool.
    

    Use this instead of `commit_mem` when you intend to correct or
    supersede something you already know, so the change is recorded as a
    revision rather than an accidental overwrite.

    Fails with `memory_not_found` if the key does not exist: revise never
    creates. Pass `expected_version` from a previous write to fail with
    `version_conflict` instead of clobbering a concurrent change.
    

    This is a destructive operation: the entry stops influencing every
    future recall in this project. `reason` is required and is written to
    the audit trail. The deleted value is never returned.

    Use this for state that is genuinely obsolete. To correct a memory
    rather than remove it, use `revise`.
    

    Take a checkpoint with `action="create"` before risky work so you can
    inspect or restore it later; `action="list"` returns existing
    checkpoints newest first and is free. Neither returns the checkpoint's
    contents.
    

    Read-only and free. Leave `to_snapshot_id` empty to see what has
    changed since the checkpoint was taken. Values are redacted unless
    `include_values` is set; a value-bearing diff that would be too large
    is refused rather than silently truncated.
    

    Two stages, and you must run them in order:

    1. `mode="preview"` is free and changes nothing. It reports what would
       be created, updated, and removed, and returns a short-lived
       `confirmation_token`.
    2. `mode="execute"` requires that token and permanently discards every
       memory created or changed since the checkpoint.

    Execute fails with `state_changed_since_preview` if the project
    changed after the preview, so review the preview and act on it
    promptly rather than reusing an old one. `reason` is required in both
    modes and is written to the audit trail.