---
title: "Write Memory"
method: POST
path: "/api/v1/memory/write"
tags: ["memory"]
---

# Write Memory

`POST /api/v1/memory/write`

## Request

- Base URL: `https://core.mnemoverse.com`
- URL: `https://core.mnemoverse.com/api/v1/memory/write`
- Auth: one of:
  - API key in header `X-Api-Key`
  - HTTP bearer

Store a new memory atom.

Content is embedded, filtered by importance, then stored with Hebbian links.

With `supersedes`, the write instead replaces the listed atoms: the successor
is stored and every target is marked as superseded by it, in one transaction
— all of it or none of it. The importance/novelty REJECTION is skipped for
such a write (a successor resembles its predecessor by construction) while
the score is still computed and returned.

## Request body

- WriteRequestSchema: Request body for storing a new memory atom.
  - `content` string, required: The insight, pattern, or lesson to remember.
  - `concepts` string[]: Key concepts (used for Hebbian associations). At most 256 items — the write-time association pass is quadratic in this count.
  - `domain` string: Namespace: 'general', 'user:X', 'room:Y', 'project:Z'.
  - `fingerprint` string, nullable: Optional SHA256-like fingerprint for exact episodic match (e.g. task hash). At most 512 characters.
  - `metadata` object: Arbitrary key-value metadata. The serialized JSON must be at most 65536 bytes.
  - `external_ref` string, nullable: Client-provided unique reference for idempotent writes and cross-system correlation. May not start with `secret:`, the namespace of Vault secret aliases (400 VALIDATION_ERROR).
  - `supersedes` string[], nullable: Ids of atoms this write REPLACES. The successor is stored and every listed atom is marked as superseded by it, in one transaction — all of it or none. At most 32 ids, all distinct. Supersession is caller-asserted: the engine never infers that two atoms describe the same fact. Not accepted on write_batch, and not accepted alongside an `xroom:` domain.
  - `author` ProvenanceWriteSchema: SUPPLIER-vouched authorship sent in a write body (CN-001b). The reserved, optional ``author`` object a SERVICE/supplier caller may send to VOUCH for the participant behind a write (e.g. the supplier's own end user). It is HONORED ONLY for supplier/service tokens and IGNORED (silently dropped) for OIDC end-users — an end-user can never set authorship (see routes._get_provenance). Even for a supplier the shape is not blindly trusted: the route re-normalizes every field via auth._normalize_supplier_ author (client_env allow-list, length caps, is_external→bool). All fields are optional and loosely typed here so an odd supplier value is normalized rather than 422-ing the whole write; ``extra="forbid"`` still blocks unknown keys INSIDE the author object.
    - `principal` string, nullable: Participant the supplier vouches for.
    - `agent` string, nullable: Stable agent identifier, if any.
    - `agent_name` string, nullable: Human-readable agent name, if any.
    - `client_env` string, nullable: Calling client environment (cursor·claude·chatgpt·chat·api·unknown); anything else normalizes to null.
    - `is_external` boolean: True when the vouched principal is external to the org.

## Response `200`

Successful Response

- WriteResponseSchema: Response after attempting to store a memory atom.
  - `stored` boolean, required: True if the atom was stored (passed importance gate).
  - `atom_id` string, uuid, nullable: UUID of the stored atom, or None if filtered.
  - `importance` number: Computed importance score in [0, 1].
  - `reason` string: Short reason (e.g. why filtered or stored).
  - `superseded` string[]: Ids this write superseded, in request order. Empty on an ordinary write, so clients can read it unconditionally. Non-empty means every listed atom is now marked superseded and points at `atom_id`; they will be excluded from default reads once read-side filtering (D2) ships. Until then they still appear in search and listing results.

## Other responses

- `400`: Validation error
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `422`: Validation Error
- `429`: Rate limited
- `500`: Internal server error
- `503`: Service unavailable

---

[API](https://skmtc.dev/mnemoverse/apis/mnemoverse-core.md) · [All operations](https://skmtc.dev/mnemoverse/apis/mnemoverse-core/llms.txt) · [OpenAPI document](https://skmtc.dev/mnemoverse/apis/mnemoverse-core/revisions/1f5e0048f017?raw)