POST /v1/memories/add

Endpoint

POST /v1/memories/add

Authentication

Authorization: ApiKey mem_live_xxx
Content-Type: application/json

Simple mode: no source block required

For solo builders, MVPs, small teams, and single-agent products, omit source. MemoryOS automatically creates internal event IDs, timestamps, and default provenance.

Request body

{
  "external_user_id": "customer_123",
  "agent_id": "support-bot",
  "messages": [
    {
      "role": "user",
      "content": "Please remember that I prefer weekly summaries."
    }
  ],
  "metadata": {
    "source": "chat"
  }
}

Fields

Field	Type	Required	Notes
`external_user_id`	`string`	Yes	End-user identifier inside your tenant
`agent_id`	`string \| null`	No	Optional agent identifier
`messages`	`ConversationMessage[]`	Yes	1-64 messages; each content value is at most 16,000 characters
`metadata`	`object`	No	Arbitrary JSON metadata
`source`	`MemorySource \| null`	No	Provenance source block for multi-service governance

ConversationMessage

Field	Type	Required	Notes
`role`	`"user" \| "assistant" \| "system"`	Yes	Conversation role
`content`	`string`	Yes	Non-empty, at most 16,000 characters
`external_turn_id`	`string`	No	Stable caller turn identifier, at most 255 characters
`source_kind`	`string`	No	`direct_user_input`, `assistant_output`, `tool_output`, `fetched_document`, `system_instruction`, or `client_assertion`
`occurred_at`	RFC 3339 datetime	No	When this turn occurred
`is_memory_proposal`	`boolean`	No	Marks a deliberately user-visible assistant memory proposal; requires `role: "assistant"` and `source_kind: "assistant_output"`
`proposed_memory`	`ProposedMemory \| null`	No	Exact durable claim and category proposed to the user; requires `is_memory_proposal: true` and the claim text must appear in `content`

ProposedMemory

Field	Type	Required	Notes
`content`	`string`	Yes	Exact user-visible durable claim, 10-500 characters
`category`	`string`	Yes	`preference`, `fact`, `goal`, `procedure`, `relationship`, or `expertise`

For a durable evidence trail, give each persisted chat turn a stable external_turn_id. MemoryOS stores a server-verified reference and content hash with extracted memories.

In normal conversational mode, MemoryOS preserves every submitted role but only creates durable user memory when a user turn directly states or confirms the claim. A user question and an unsupported assistant answer are not sufficient evidence. This prevents an assistant from turning its own suggestion into a user preference or fact.

Explicit assistant proposals

This contract requires a backend deployment containing the structured-proposal migration and an SDK version that exposes the matching fields. Proposal confirmation is feature-gated and remains off until the tenant environment passes its release evaluation.

The assistant must show the proposed durable claim to the user and submit that same claim as proposed_memory. Registering it does not create a memory and does not grant user authority. When confirmation is enabled, a later direct user turn can accept it only after MemoryOS verifies the immutable proposal turn, its content hash, the conversation scope, the referenced proposal, and the user’s confirmation. Model confidence is diagnostic only and cannot grant authority.

{
  "role": "assistant",
  "content": "I can remember this for later. Proposed memory: User prefers a one-line diagnosis before numbered troubleshooting steps.",
  "external_turn_id": "support-884:turn-13",
  "source_kind": "assistant_output",
  "is_memory_proposal": true,
  "proposed_memory": {
    "content": "User prefers a one-line diagnosis before numbered troubleshooting steps.",
    "category": "preference"
  }
}

Use the same conversation_id and stable turn IDs when you later submit the proposal turn with the user’s direct reply. Tool output, fetched documents, system instructions, and assistant text cannot act as the confirming user turn.

Multi-service mode: add provenance

Use source when multiple services can write memories for the same user. This is for Billing, Support, CRM, Product, or other backend services that may disagree and need source-authority policies.

{
  "external_user_id": "customer_123",
  "messages": [
    {
      "role": "user",
      "content": "What plan am I currently using?"
    },
    {
      "role": "assistant",
      "content": "Your current subscription plan is Growth."
    }
  ],
  "source": {
    "service": "billing-service",
    "event_id": "billing-plan-2026-06-30-001",
    "observed_at": "2026-06-30T10:00:00Z",
    "scope": {
      "workspace_id": "ws_123"
    },
    "evidence": [
      {
        "source_type": "subscription_record",
        "reference": "billing/subscriptions/ws_123"
      }
    ]
  }
}

If you provide source.service, register that service writer in the Tenant Dashboard first. MemoryOS rejects unknown or inactive service keys. Dedicated API keys can then be bound to writers so authority rules and source credentials are enforced consistently. Authenticated source-aware events have a different authority boundary: declarative observations from the registered service may be extracted from an assistant-role message because the service identity, event, evidence, and writer policy provide the provenance. Do not add source merely to make an ordinary chatbot response authoritative.

Response: queued

{
  "job_id": "72a20629-a76d-4a18-ab36-1c2778ba21d0",
  "status": "queued",
  "blocked_reason": null,
  "nothing_to_extract": false,
  "retry_after_seconds": null,
  "budget_remaining_pct": 0.9134,
  "processing_eta_seconds": null,
  "processing_status": "normal",
  "request_id": "c3d4fd63-77ff-48b6-9316-6bcbadf9476b",
  "timestamp": "2026-04-05T09:23:40.077265Z"
}

add() is asynchronous. A queued response means MemoryOS accepted the request, not that a memory has already been stored.

Check extraction job status

GET /v1/memories/jobs/{job_id}
Authorization: ApiKey mem_live_xxx

Example response:

{
  "data": {
    "job_id": "72a20629-a76d-4a18-ab36-1c2778ba21d0",
    "status": "completed",
    "memories_created": 0,
    "created_memory_ids": [],
    "pending_candidates_buffered": 1,
    "pending_candidates_promoted": 0,
    "attempts": 2,
    "queue_name": "free-extraction",
    "error": null,
    "error_summary": null,
    "extraction_metadata": {
      "compositional_pass_attempted": false,
      "compositional_pass_used": false,
      "compositional_entities": 0,
      "compositional_relationships": 0,
      "compositional_error": null
    }
  }
}

Job status fields

Field	Meaning
`memories_created`	Permanent memories created
`created_memory_ids`	Exact ids of permanent memories created by this job
`pending_candidates_buffered`	Weak signals buffered instead of stored
`pending_candidates_promoted`	Weak signals promoted to memory
`attempts`	Number of processing attempts, including provider retries
`extraction_metadata`	Extraction diagnostics; do not use these internals as an authorization decision

created_memory_ids is the reliable way to inspect or explain the records created by this write. Do not search recent memory history to guess which records came from the job.

Explicitly request a memory clarification

If a direct user message says not to decide between two existing memories and asks to choose, MemoryOS can complete the extraction job with memories_created: 0 and queue a clarification instead of storing the uncertain sentence as a new memory. On the next retrieve call, clarification contains the backend-approved question and answer options for the customer’s existing chat. The extraction model can only select memory IDs that MemoryOS placed in its bounded prompt context. The backend then revalidates the cited user turn, verbatim evidence, tenant, user profile, active status, and category before it queues anything. Tool output, assistant text, invented IDs, and records owned by another user or tenant cannot create a clarification. See Resolve a clarification in your existing chat.

Working PowerShell polling example

$Api = $env:MEMORYOS_API_BASE_URL
if (-not $Api) { $Api = "https://api.memoryo.dev" }

$TenantKey = $env:MEMORYOS_API_KEY
if (-not $TenantKey) { throw "Set MEMORYOS_API_KEY before running this example." }

$UserId = "customer_123"

$body = @{
  external_user_id = $UserId
  messages = @(
    @{
      role = "user"
      content = "Maybe I prefer shorter replies for difficult technical topics, but I am not completely sure yet."
    },
    @{
      role = "assistant"
      content = "Got it. I will adapt if that pattern becomes clearer."
    }
  )
} | ConvertTo-Json -Depth 10

$add = Invoke-RestMethod `
  -Method Post `
  -Uri "$Api/v1/memories/add" `
  -Headers @{
    Authorization = "ApiKey $TenantKey"
    "Content-Type" = "application/json"
  } `
  -Body $body

$JobId = $add.job_id

for ($i = 1; $i -le 60; $i++) {
  Start-Sleep -Seconds 3

  $job = Invoke-RestMethod `
    -Method Get `
    -Uri "$Api/v1/memories/jobs/$JobId" `
    -Headers @{ Authorization = "ApiKey $TenantKey" }

  Write-Host "Attempt $i -> status=$($job.data.status), memories=$($job.data.memories_created), buffered=$($job.data.pending_candidates_buffered)"

  if ($job.data.status -in @("completed", "processed", "failed", "dead")) {
    $job.data | ConvertTo-Json -Depth 10
    break
  }
}

Response: blocked by the quality gate

{
  "job_id": null,
  "status": "L2",
  "blocked_reason": "low_quality",
  "retry_after_seconds": null,
  "budget_remaining_pct": 0.9134,
  "request_id": "11111111-2222-3333-4444-555555555555",
  "timestamp": "2026-04-17T09:30:00Z"
}

Possible blocked status values: L1, L2, L3, L4, and blocked.

Nothing to extract

Some conversations pass the quality gate but contain no durable memory. This is normal. Examples:

greetings
acknowledgements
one-session debugging instructions
temporary UI instructions
off-topic questions

Idempotency-Key

Use Idempotency-Key when your application may retry the same write request.

Idempotency-Key: 8b7f95f1-a98c-4d43-b321-889e881d29b8

MemoryOS replays the same queued response for duplicate requests instead of creating a second job.

Memory APIs

Domain APIs

Reference

POST /v1/memories/add

Endpoint

Authentication

Simple mode: no source block required

Request body

Fields

ConversationMessage

ProposedMemory

Explicit assistant proposals

Multi-service mode: add provenance

Response: queued

Check extraction job status

Job status fields

Explicitly request a memory clarification

Working PowerShell polling example

Response: blocked by the quality gate

Nothing to extract

Idempotency-Key

​Endpoint

​Authentication

​Simple mode: no source block required

​Request body

​Fields

​ConversationMessage

​ProposedMemory

​Explicit assistant proposals

​Multi-service mode: add provenance

​Response: queued

​Check extraction job status

​Job status fields

​Explicitly request a memory clarification

​Working PowerShell polling example

​Response: blocked by the quality gate

​Nothing to extract

​Idempotency-Key

​Related pages

Endpoint

Authentication

Simple mode: no source block required

Request body

Fields

ConversationMessage

ProposedMemory

Explicit assistant proposals

Multi-service mode: add provenance

Response: queued

Check extraction job status

Job status fields

Explicitly request a memory clarification

Working PowerShell polling example

Response: blocked by the quality gate

Nothing to extract

Idempotency-Key

Related pages