Skip to content
DashboardGet API key

Remember a fact

View .md
POST

Store one fact so the agent can recall it later by meaning. The text is embedded on write; retrieval is semantic, not keyword.

Scope goes in the body here. Pass scope plus the matching contactId / conversationId. Omit it for the project scope. Every read endpoint takes the scope as a ?scope= query parameter instead — see the scope parameter on GET /v1/memory.

One fact per call. A paragraph carrying five unrelated facts is embedded as an average of all five and retrieved well by none of them.

Authorization

  • Authorizationheaderrequired

    Bearer YOUR_API_KEY. Create a key in the dashboard.

Body

application/json

  • textstringrequired

    What to remember. Max 8,192 bytes of UTF-8. Write one fact per call: a paragraph holding five unrelated facts embeds as an average of all five and is retrieved well by none of them.

  • scopestring

    Which namespace a memory belongs to. Scopes are isolated: a search in one never returns a memory from another.

    • project: shared by the whole project. What the agent knows in general.
    • contact: what the agent knows about one person, across every conversation with them.
    • conversation: what the agent knows about one inbox thread.

    Defaults to project everywhere. contact and conversation require the matching id.

    One ofprojectcontactconversation
  • contactIdstring

    Required when scope is contact.

  • conversationIdstring

    Required when scope is conversation.

  • metadataobject

    Arbitrary string tags stored alongside the fact and returned with it. Keys max 64 chars, values max 512, whole object max 2,048 bytes. Not searchable — search matches text only.

    1 properties
    • {key}string
  • ttlSecondsinteger

    Delete the fact after this many seconds. 60 to 63,072,000 (2 years). Omit to keep it until deleted.

    Limitsmin 60 · max 63072000

Responses

201Fact stored.
  • memoryobjectrequired

    A stored fact, as returned when it is created.

    4 properties
    • idstringrequired
    • scopestringrequired

      Which namespace a memory belongs to. Scopes are isolated: a search in one never returns a memory from another.

      • project: shared by the whole project. What the agent knows in general.
      • contact: what the agent knows about one person, across every conversation with them.
      • conversation: what the agent knows about one inbox thread.

      Defaults to project everywhere. contact and conversation require the matching id.

      One ofprojectcontactconversation
    • createdAtstring<date-time>required
    • expiresAtstring<date-time>

      When the fact self-deletes. Present only when it was stored with ttlSeconds, or when the key is a test-mode key (forced to 30 days).

400Invalid body, oversized text, or a scope without its id.
  • codestringrequired
  • messagestringrequired
  • detailsobject
401Unauthorized.
  • codestringrequired
  • messagestringrequired
  • detailsobject
429A quota is exhausted. `memory_scope_full` means this scope is at its cap (10,000 facts for project, 2,000 per contact, 1,000 per conversation); `memory_limit_exceeded` means the plan's monthly unit quota is spent. Reads and deletes keep working in both cases.
  • codestringrequired
  • messagestringrequired
  • detailsobject
503Memory is not available for this deployment.
  • codestringrequired
  • messagestringrequired
  • detailsobject