Encode Operations

Store and update memories using CMP encode operations.

encode.store

Store a new memory record. This is the primary way to add memories to Cerememory.

Endpoint: POST /v1/encode

Request

json

{
  "content": {
    "blocks": [
      {
        "modality": "text",
        "format": "text/plain",
        "data": [72, 101, 108, 108, 111],
        "embedding": null
      }
    ],
    "summary": null
  },
  "store": "episodic",
  "emotion": {
    "joy": 0.0,
    "trust": 0.8,
    "intensity": 0.6,
    "valence": 0.7
  },
  "context": {
    "source": "chat-session-42",
    "session_id": "sess_abc123"
  },
  "meta": {
    "intent": "Remember why this preference matters",
    "rationale": "The user repeatedly asked for low-load workflows during long test runs.",
    "decision": "Prefer low-load verification commands by default",
    "confidence": 0.9
  },
  "associations": [
    {
      "target_id": "01916e3a-0000-7000-8000-000000000001",
      "association_type": "semantic",
      "weight": 0.75
    }
  ]
}

Field	Type	Required	Default	Description
`content`	MemoryContent	Yes	--	The memory payload (blocks + optional summary)
`store`	StoreType	No	Engine auto-selects	Target store (episodic, semantic, procedural, emotional, working)
`emotion`	EmotionVector	No	Neutral	Emotional context for this memory
`context`	EncodeContext	No	None	Source, session, spatial, and temporal context
`meta`	MetaMemory	No	unavailable	Structured intent, rationale, evidence, assumptions, alternatives, decision, and context-graph edges
`associations`	ManualAssociation[]	No	None	Explicit associations to existing records

Response

json

{
  "record_id": "01916e3a-5678-7000-8000-000000000002",
  "store": "episodic",
  "initial_fidelity": 1.0,
  "associations_created": 1
}

encode.batch

Store multiple records in a single request with optional automatic association inference between the batch members.

Endpoint: POST /v1/encode/batch

Request

json

{
  "records": [
    {
      "content": {
        "blocks": [{ "modality": "text", "format": "text/plain", "data": [65, 66, 67] }]
      },
      "store": "episodic"
    },
    {
      "content": {
        "blocks": [{ "modality": "text", "format": "text/plain", "data": [68, 69, 70] }]
      },
      "store": "episodic"
    }
  ],
  "infer_associations": true
}

Field	Type	Required	Default	Description
`records`	EncodeStoreRequest[]	Yes	--	Array of individual store requests
`infer_associations`	bool	No	false	Automatically create associations between batch members

Response

json

{
  "results": [
    {
      "record_id": "01916e3a-aaaa-7000-8000-000000000001",
      "store": "episodic",
      "initial_fidelity": 1.0,
      "associations_created": 1
    },
    {
      "record_id": "01916e3a-bbbb-7000-8000-000000000002",
      "store": "episodic",
      "initial_fidelity": 1.0,
      "associations_created": 1
    }
  ],
  "associations_inferred": 2
}

When infer_associations is true, the engine creates temporal and sequential associations between consecutive records in the batch. If an LLM provider is configured, semantic associations are also inferred.

encode.update

Update an existing record's content, emotion, metadata, or structured meta-memory. Uses optimistic concurrency control via the record's version field.

Endpoint: PATCH /v1/encode/:record_id

Request

json

{
  "content": {
    "blocks": [
      {
        "modality": "text",
        "format": "text/plain",
        "data": [85, 112, 100, 97, 116, 101, 100]
      }
    ],
    "summary": "Updated memory content"
  },
  "emotion": {
    "trust": 1.0,
    "intensity": 0.9,
    "valence": 0.7
  },
  "metadata": {
    "reviewed": true,
    "source": "manual-correction"
  },
  "meta": {
    "intent": "Correct the explanation attached to this memory",
    "rationale": "The previous rationale omitted the security reason for the decision.",
    "capture_status": "provided"
  }
}

Field	Type	Required	Description
`content`	MemoryContent	No	Replace content entirely
`emotion`	EmotionVector	No	Replace emotion vector
`metadata`	JSON	No	Replace metadata object
`meta`	MetaMemory	No	Replace structured meta-memory

All fields are optional -- only provided fields are updated. The record's updated_at timestamp and version are automatically incremented.

{
  "content": {
    "blocks": [
      {
        "modality": "text",
        "format": "text/plain",
        "data": [72, 101, 108, 108, 111]
      }
    ]
  },
  "session_id": "sess_abc123",
  "turn_id": "turn_001",
  "topic_id": null,
  "source": "conversation",
  "speaker": "user",
  "visibility": "normal",
  "secrecy_level": "public",
  "metadata": {},
  "meta": {
    "intent": "Preserve the exact source turn before summarization",
    "rationale": "The raw wording may be needed for forensic recall or later dream processing."
  }
}

Field	Type	Required	Default	Description
`content`	MemoryContent	Yes	--	Verbatim content to preserve
`session_id`	string	Yes	--	Session identifier for grouping
`turn_id`	string	No	None	Turn identifier within the session
`topic_id`	string	No	None	Topic identifier for dream grouping
`source`	RawSource	No	`conversation`	`conversation`, `tool_io`, `scratchpad`, `summary`, or `imported`
`speaker`	RawSpeaker	No	`user`	`user`, `assistant`, `system`, or `tool`
`visibility`	RawVisibility	No	`normal`	`normal`, `private_scratch`, or `sealed`
`secrecy_level`	SecrecyLevel	No	`public`	`public`, `sensitive`, or `secret`
`metadata`	JSON	No	`{}`	Arbitrary metadata
`meta`	MetaMemory	No	unavailable	Structured explanation for why this raw entry is preserved

Response

json

{
  "record_id": "01916e3a-5678-7000-8000-000000000003",
  "session_id": "sess_abc123",
  "visibility": "normal",
  "secrecy_level": "public"
}

encode.batch_raw

Store multiple raw journal entries in a single request.

Endpoint: POST /v1/encode/raw/batch

Request

json

{
  "records": [
    {
      "content": {
        "blocks": [{ "modality": "text", "format": "text/plain", "data": [65, 66, 67] }]
      },
      "session_id": "sess_abc123",
      "source": "conversation",
      "speaker": "user"
    },
    {
      "content": {
        "blocks": [{ "modality": "text", "format": "text/plain", "data": [68, 69, 70] }]
      },
      "session_id": "sess_abc123",
      "source": "conversation",
      "speaker": "assistant"
    }
  ]
}

Field	Type	Required	Description
`records`	EncodeStoreRawRequest[]	Yes	Array of raw journal entries

Response

json

{
  "results": [
    {
      "record_id": "01916e3a-aaaa-7000-8000-000000000001",
      "session_id": "sess_abc123",
      "visibility": "normal",
      "secrecy_level": "public"
    },
    {
      "record_id": "01916e3a-bbbb-7000-8000-000000000002",
      "session_id": "sess_abc123",
      "visibility": "normal",
      "secrecy_level": "public"
    }
  ]
}

Next Steps

Recall Operations

Query and retrieve memories with multimodal cues