POST /v1/remember

Store facts, preferences, and events into long-term memory for a scope.

Facts are extracted by an LLM, embedded, and stored. If a new fact contradicts an existing one, the old entry is automatically decayed.

Request

POST https://api.memcone.com/v1/remember
Authorization: Bearer mem_live_...
Content-Type: application/json

POST https://api.memcone.com/v1/remember
Authorization: Bearer mem_live_...
Content-Type: application/json

{
  "scopeId": "user_123",
  "event": "User said they prefer TypeScript over JavaScript and always uses strict mode."
}

{
  "scopeId": "user_123",
  "event": "User said they prefer TypeScript over JavaScript and always uses strict mode."
}

Parameters

| Field | Type | Required | Description | |---|---|---|---| | scopeId | string | ✓ | Namespace for this memory. Any string you control. | | event | string | object | ✓ | Text or structured data to remember. |

The event field

Pass anything — a raw message, a structured action, a JSON object:

{ "event": "User completed onboarding step 3" }
{ "event": { "action": "purchase", "item": "Pro plan", "amount": 29 } }
{ "event": "I prefer dark mode and terse responses" }

{ "event": "User completed onboarding step 3" }
{ "event": { "action": "purchase", "item": "Pro plan", "amount": 29 } }
{ "event": "I prefer dark mode and terse responses" }

Response

{
  "ok": true,
  "extracted": 2,
  "facts": [
    "user prefers TypeScript over JavaScript",
    "user always uses strict mode"
  ],
  "contradictions_resolved": 0,
  "preview": "user prefers TypeScript over JavaScript",
  "latency_ms": 312
}

{
  "ok": true,
  "extracted": 2,
  "facts": [
    "user prefers TypeScript over JavaScript",
    "user always uses strict mode"
  ],
  "contradictions_resolved": 0,
  "preview": "user prefers TypeScript over JavaScript",
  "latency_ms": 312
}

| Field | Type | Description | |---|---|---| | ok | boolean | Always true on success | | extracted | number | Number of facts stored | | facts | string[] | The extracted and stored facts | | contradictions_resolved | number | Prior conflicting facts that were decayed | | preview | string | null | The first fact — useful for debugging | | latency_ms | number | Server-side processing time |

Response headers

| Header | Value | |---|---| | X-Memcone-Latency-Ms | Server latency in ms |

Fire-and-forget pattern

remember is designed to be called without awaiting in your response path:

// never blocks the user response
fetch('https://api.memcone.com/v1/remember', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.MEMCONE_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ scopeId: userId, event: userMessage }),
})
// no await — fire and forget

// never blocks the user response
fetch('https://api.memcone.com/v1/remember', {
  method: 'POST',
  headers: { 'Authorization': `Bearer ${process.env.MEMCONE_API_KEY}`, 'Content-Type': 'application/json' },
  body: JSON.stringify({ scopeId: userId, event: userMessage }),
})
// no await — fire and forget

Errors

| Status | Code | Meaning | |---|---|---| | 401 | — | Missing or invalid API key | | 400 | — | scopeId or event missing |