SmartMemory
POST
/memory/add

Add a memory item with optional full ingestion pipeline.

Requires authentication and operates on user-scoped data.

Args: content: The memory content memory_type: Type of memory (semantic, episodic, procedural) metadata: Additional metadata. A metadata.status outside the lifecycle vocabulary is refused with 422 error_code=status_not_lifecycle and nothing is stored (CORE-2.0-CALLER-STATUS-LIFECYCLE-1). use_pipeline: If True, uses full ingestion pipeline with entity extraction (default: True) conversation_context: Optional conversation context for conversation-aware entity extraction embed: SVC-EMBED-CONTROL-1 tri-state embedding override. True forces an embedding, False suppresses one, None (default) leaves existing behaviour untouched. Only honoured when use_pipeline is False (see the 400 below).

Note: Provenance like retrieved_context_ids travels in metadata. The storage layer flattens metadata onto the node and lifts known fields back onto the MemoryItem on read, so no dedicated body field is needed (GRAPH-API-1i, wire field added then removed 2026-08-02. Metadata takes precedence at storage regardless, node_types.py).

Authorization

AuthorizationBearer <token>

Send Authorization: Bearer <token>. The token is either a Clerk session JWT or a SmartMemory API key (prefix sm_live_, sm_test_, or legacy sk_).

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/memory/add" \  -H "Content-Type: application/json" \  -d '{    "content": "string"  }'
null
{
  "detail": {
    "code": "invalid_scoped_validity",
    "message": "string",
    "retryable": false
  }
}
{
  "detail": {
    "code": "invalid_scoped_validity",
    "message": "string",
    "retryable": false
  }
}
{
  "detail": [
    {
      "loc": [
        "string"
      ],
      "msg": "string",
      "type": "string",
      "input": null,
      "ctx": {}
    }
  ]
}
{
  "detail": {
    "code": "invalid_scoped_validity",
    "message": "string",
    "retryable": false
  }
}