API Documentation

Node SDK Python SDK Download Skill

Long-term memory service for creation, retrieval, semantic search, mutation, supersession handling, restoration, and recall observability.

Memories

GETmemoriesPOSTmemoriesGET:idGETclaimsPATCH:idDELETE:idGETsearchGETsupersededPOSTrestoreGETrecalls

GET/api/v1/memories

List all memories for a subject. Use this for full memory management.

Scope:memories:read

subject_idrequired

string

The subject to fetch memories for.

limit

number

Max memories to return. Default: 50

offset

number

Pagination offset. Default: 0

Request

bash

curl -G "https://www.mnexium.com/api/v1/memories" \
  -H "x-mnexium-key: $MNX_KEY" \
  --data-urlencode "subject_id=user_123" \
  --data-urlencode "limit=20"

Response

json

{
  "data": [
    {
      "id": "mem_abc123",
      "text": "User prefers dark mode interfaces",
      "kind": "preference",
      "importance": 75,
      "created_at": "2024-12-15T10:30:00Z"
    }
  ],
  "count": 1
}

GET/api/v1/memories/search

Semantic search over a subject's memories. Returns the most relevant items by similarity score.

Scope:memories:search

subject_idrequired

string

The subject to search memories for.

qrequired

string

Search query.

limit

number

Max results. Default: 25

Request

bash

curl -G "https://www.mnexium.com/api/v1/memories/search" \
  -H "x-mnexium-key: $MNX_KEY" \
  --data-urlencode "subject_id=user_123" \
  --data-urlencode "q=food preferences" \
  --data-urlencode "limit=5"

Response

json

{
  "data": [
    {
      "id": "mem_xyz789",
      "text": "User is vegetarian and enjoys Italian cuisine",
      "score": 0.92
    },
    {
      "id": "mem_uvw012",
      "text": "User is allergic to peanuts",
      "score": 0.78
    }
  ],
  "query": "food preferences",
  "count": 2
}

POST/api/v1/memories

Manually create a memory. For automatic extraction with LLM-chosen classification, use the Responses or Chat API with learn: true instead.

Scope:memories:write

Guidance: When you use the Responses or Chat Completions API with learn: true, the LLM automatically extracts memories and intelligently chooses the kind, importance, and tags based on conversation context. Use learn: "force" to always create a memory. This endpoint is for manual injection when you need direct control.

subject_idrequired

string

The subject this memory belongs to.

textrequired

string

The memory content (max 10,000 chars).

kind

string

Optional. Type: fact, preference, context, instruction. Fallback: "fact"

visibility

string

Optional. Visibility: private, shared, public. Fallback: "private"

importance

number

Optional. Priority 0-100. Fallback: 50

tags

array

Optional. Tags for categorization. Fallback: []

metadata

object

Optional. Custom metadata object. Fallback:

no_supersede

boolean

Optional. If true, skip conflict detection and never supersede existing memories. Useful for bulk imports. Fallback: false

Note: When using learn: true with the Responses/Chat API, the LLM intelligently chooses kind, visibility, importance, and tags based on context. The fallback values above only apply when manually creating memories via this endpoint.

Request

bash

curl -X POST "https://www.mnexium.com/api/v1/memories" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "subject_id": "user_123",
    "text": "User prefers dark mode interfaces",
    "kind": "preference",
    "importance": 75,
    "no_supersede": false
  }'

Response

json

{
  "id": "mem_abc123",
  "subject_id": "user_123",
  "text": "User prefers dark mode interfaces",
  "kind": "preference",
  "created": true,
  "superseded_count": 0,
  "superseded_ids": []
}

GET/api/v1/memories/:id

Get a specific memory by ID.

Scope:memories:read

idrequired

path

The memory ID.

Request

bash

curl "https://www.mnexium.com/api/v1/memories/mem_abc123" \
  -H "x-mnexium-key: $MNX_KEY"

Response

json

{
  "data": {
    "id": "mem_abc123",
    "subject_id": "user_123",
    "text": "User prefers dark mode interfaces",
    "kind": "preference",
    "importance": 75,
    "created_at": "2024-12-15T10:30:00Z"
  }
}

GET/api/v1/memories/:id/claims

Get structured claims/assertions extracted from a specific memory.

Scope:memories:read

idrequired

path

The memory ID.

Request

bash

curl "https://www.mnexium.com/api/v1/memories/mem_abc123/claims" \
  -H "x-mnexium-key: $MNX_KEY"

Response

json

{
  "data": [
    {
      "id": "ast_abc123",
      "predicate": "favorite_color",
      "type": "string",
      "value": "yellow",
      "confidence": 0.95,
      "status": "active",
      "first_seen_at": "2024-12-15T10:30:00Z",
      "last_seen_at": "2024-12-15T10:30:00Z"
    }
  ],
  "count": 1
}

PATCH/api/v1/memories/:id

Update an existing memory. Embeddings are regenerated if text changes.

Scope:memories:write

idrequired

path

The memory ID to update.

text

string

New memory content.

kind

string

New type.

importance

number

New importance (0-100).

tags

array

New tags.

Request

bash

curl -X PATCH "https://www.mnexium.com/api/v1/memories/mem_abc123" \
  -H "x-mnexium-key: $MNX_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "User strongly prefers dark mode",
    "importance": 90
  }'

Response

json

{
  "id": "mem_abc123",
  "updated": true
}

DELETE/api/v1/memories/:id

Soft-delete a memory. The memory is deactivated but retained for audit.

Scope:memories:delete

idrequired

path

The memory ID to delete.

Request

bash

curl -X DELETE "https://www.mnexium.com/api/v1/memories/mem_abc123" \
  -H "x-mnexium-key: $MNX_KEY"

Response

json

{
  "ok": true,
  "deleted": true
}

GET/api/v1/memories/superseded

List memories that have been superseded (replaced by newer memories). Useful for audit and debugging.

Scope:memories:read

subject_idrequired

string

The subject to fetch superseded memories for.

limit

number

Max memories to return. Default: 50

offset

number

Pagination offset. Default: 0

Request

bash

curl -G "https://www.mnexium.com/api/v1/memories/superseded" \
  -H "x-mnexium-key: $MNX_KEY" \
  --data-urlencode "subject_id=user_123"

Response

json

{
  "data": [
    {
      "id": "mem_old123",
      "text": "Favorite fruit is blueberry",
      "status": "superseded",
      "superseded_by": "mem_new456",
      "created_at": "2024-12-10T10:00:00Z"
    }
  ],
  "count": 1
}

POST/api/v1/memories/:id/restore

Restore a superseded memory back to active status. Use this to undo an incorrect supersede.

Scope:memories:write

idrequired

path

The memory ID to restore.

Request

bash

curl -X POST "https://www.mnexium.com/api/v1/memories/mem_old123/restore" \
  -H "x-mnexium-key: $MNX_KEY"

Response

json

{
  "ok": true,
  "restored": true,
  "id": "mem_old123",
  "subject_id": "user_123",
  "text": "Favorite fruit is blueberry"
}

Memory Versioning & Conflict Resolution

Mnexium automatically handles conflicting memories. When a user updates a preference or fact, the system detects semantically similar memories and supersedes them.

Example: If a user has the memory "Favorite fruit is blueberry" and later says "my new favorite fruit is strawberry", the system will:

Extract the new memory: "User's favorite fruit is strawberry"
Detect the old "blueberry" memory as a conflict
Mark the old memory as superseded
Only the new "strawberry" memory will be recalled in future conversations

Memory Status

activeMemory is current and will be included in recall searches.

supersededMemory has been replaced by a newer one. Excluded from recall but retained for audit.

Usage Tracking

When memories are recalled during a chat completion with recall: true, the system automatically tracks:

last_seen_at — Timestamp of the most recent recall
seen_count — Total number of times the memory has been recalled

GET/api/v1/memories/recalls

Query memory recall events for auditability. Track which memories were used in which conversations.

Scope:memories:read

chat_id

string

Get all memories recalled in a specific chat. Provide either chat_id or memory_id.

memory_id

string

Get all chats where a specific memory was recalled.

stats

boolean

If true with memory_id, returns aggregated stats instead of individual events.

limit

number

Max results. Default: 100, Max: 1000

Query by Chat

bash

curl -G "https://www.mnexium.com/api/v1/memories/recalls" \
  -H "x-mnexium-key: $MNX_KEY" \
  --data-urlencode "chat_id=550e8400-e29b-41d4-a716-446655440000"

Response

json

{
  "data": [
    {
      "event_id": "evt_abc123",
      "memory_id": "mem_xyz789",
      "memory_text": "User prefers dark mode",
      "similarity_score": 78.5,
      "message_index": 0,
      "recalled_at": "2024-12-15T10:30:00Z"
    }
  ],
  "count": 1,
  "chat_id": "550e8400-e29b-41d4-a716-446655440000"
}

Query by Memory (with stats)

bash

curl -G "https://www.mnexium.com/api/v1/memories/recalls" \
  -H "x-mnexium-key: $MNX_KEY" \
  --data-urlencode "memory_id=mem_xyz789" \
  --data-urlencode "stats=true"

Response

json

{
  "memory_id": "mem_xyz789",
  "stats": {
    "total_recalls": 15,
    "unique_chats": 8,
    "avg_score": 72.4,
    "first_recalled_at": "2024-12-01T09:00:00Z",
    "last_recalled_at": "2024-12-15T10:30:00Z"
  }
}

Note: The chat_logged field indicates whether the chat was saved to history (log: true). When chat_logged = 0, the recall event is tracked but the chat messages are not stored.