Memories API

The Memories API allows you to store, search, and manage semantic memories.

Create Memory

Create a new memory with automatic vector embedding.

POST /v1/memories

Request Body

Field	Type	Required	Description
`content`	string	Yes	The memory content (max 10,000 characters)
`userId`	string	Yes	User identifier for the memory
`agentId`	string	No	Agent identifier
`tags`	string[]	No	Array of tags for categorization
`metadata`	object	No	Custom metadata object

Example Request

curl -X POST https://api.memokit.dev/v1/memories \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The user mentioned they prefer Python for data science work",
    "userId": "user_123",
    "agentId": "agent_456",
    "tags": ["preference", "programming"],
    "metadata": {
      "source": "chat",
      "sessionId": "sess_789"
    }
  }'

Response

{
  "id": "mem_abc123def456",
  "content": "The user mentioned they prefer Python for data science work",
  "userId": "user_123",
  "agentId": "agent_456",
  "tags": ["preference", "programming"],
  "metadata": {
    "source": "chat",
    "sessionId": "sess_789"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Search Memories

Search for relevant memories using semantic similarity.

POST /v1/memories/search

Request Body

Field	Type	Required	Description
`query`	string	Yes	Natural language search query
`userId`	string	No	Filter by user ID
`agentId`	string	No	Filter by agent ID
`tags`	string[]	No	Filter by tags (AND logic)
`limit`	number	No	Max results (default: 10, max: 100)
`threshold`	number	No	Minimum similarity score (0-1, default: 0.5)

Example Request

curl -X POST https://api.memokit.dev/v1/memories/search \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What programming languages does the user prefer?",
    "userId": "user_123",
    "limit": 5,
    "threshold": 0.6
  }'

Response

{
  "results": [
    {
      "id": "mem_abc123def456",
      "content": "The user mentioned they prefer Python for data science work",
      "score": 0.87,
      "userId": "user_123",
      "agentId": "agent_456",
      "tags": ["preference", "programming"],
      "createdAt": "2024-01-15T10:30:00Z"
    },
    {
      "id": "mem_xyz789",
      "content": "User said they use JavaScript for web development",
      "score": 0.74,
      "userId": "user_123",
      "tags": ["programming"],
      "createdAt": "2024-01-14T15:20:00Z"
    }
  ]
}

The score field indicates semantic similarity (0-1, higher is more relevant).

List Memories

Retrieve a paginated list of memories.

GET /v1/memories

Query Parameters

Parameter	Type	Required	Description
`userId`	string	No	Filter by user ID
`agentId`	string	No	Filter by agent ID
`tags`	string	No	Comma-separated tags to filter
`page`	number	No	Page number (default: 1)
`limit`	number	No	Items per page (default: 20, max: 100)

Example Request

curl -X GET "https://api.memokit.dev/v1/memories?userId=user_123&limit=10" \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "items": [
    {
      "id": "mem_abc123def456",
      "content": "The user mentioned they prefer Python for data science work",
      "userId": "user_123",
      "agentId": "agent_456",
      "tags": ["preference", "programming"],
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 45,
    "totalPages": 5
  }
}

Get Memory

Retrieve a specific memory by ID.

GET /v1/memories/:id

Path Parameters

Parameter	Type	Description
`id`	string	Memory ID

Example Request

curl -X GET https://api.memokit.dev/v1/memories/mem_abc123def456 \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "id": "mem_abc123def456",
  "content": "The user mentioned they prefer Python for data science work",
  "userId": "user_123",
  "agentId": "agent_456",
  "tags": ["preference", "programming"],
  "metadata": {
    "source": "chat",
    "sessionId": "sess_789"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T10:30:00Z"
}

Delete Memory

Delete a memory permanently.

DELETE /v1/memories/:id

Path Parameters

Parameter	Type	Description
`id`	string	Memory ID

Example Request

curl -X DELETE https://api.memokit.dev/v1/memories/mem_abc123def456 \
  -H "Authorization: Bearer mk_your_api_key"

Response

{
  "success": true,
  "id": "mem_abc123def456"
}

Error Codes

Code	Description
`MEMORY_NOT_FOUND`	The specified memory does not exist
`CONTENT_TOO_LONG`	Content exceeds 10,000 characters
`INVALID_USER_ID`	User ID is required
`QUOTA_EXCEEDED`	Monthly quota has been exceeded

Memories API

On this page