memory

Write Memory

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.

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

Request body

contentstring required

The insight, pattern, or lesson to remember.

conceptsstring[]

Key concepts (used for Hebbian associations). At most 256 items — the write-time association pass is quadratic in this count.

domainstring

Namespace: 'general', 'user:X', 'room:Y', 'project:Z'.

fingerprintstring nullable

Optional SHA256-like fingerprint for exact episodic match (e.g. task hash). At most 512 characters.

metadataobject

Arbitrary key-value metadata. The serialized JSON must be at most 65536 bytes.

external_refstring 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).

supersedesstring[] 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.

Example request

{
  "concepts": [
    "rotation",
    "symmetry",
    "grid"
  ],
  "content": "Rotation preserves symmetry in grid transformations.",
  "domain": "arc",
  "metadata": {}
}

Response

Successful Response

storedboolean required

True if the atom was stored (passed importance gate).

atom_idstring uuid nullable

UUID of the stored atom, or None if filtered.

importancenumber

Computed importance score in [0, 1].

reasonstring

Short reason (e.g. why filtered or stored).

supersededstring[]

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.

Changes

No recorded changes to this operation across all 1 revision of this API.