Memory

Add Memory V1

Add a new memory item to the system with size validation and background processing.

**Authentication Required**:
One of the following authentication methods must be used:
- Bearer token in `Authorization` header
- API Key in `X-API-Key` header
- Session token in `X-Session-Token` header

**Required Headers**:
- Content-Type: application/json
- X-Client-Type: (e.g., 'papr_plugin', 'browser_extension')

**Role-Based Memory Categories**:
- **User memories**: preference, task, goal, facts, context
- **Assistant memories**: skills, learning

**New Metadata Fields**:
- `metadata.role`: Optional field to specify who generated the memory (user or assistant)
- `metadata.category`: Optional field for memory categorization based on role
- Both fields are stored within metadata at the same level as topics, location, etc.

The API validates content size against MAX_CONTENT_LENGTH environment variable (defaults to 15000 bytes).

post/v1/memory

Query parameters

skip_background_processingboolean

If True, skips adding background tasks for processing

formatstring nullable

Response format. Use 'omo' for Open Memory Object standard format (portable across platforms).

webhook_urlstring nullable

Webhook URL to notify when background processing completes. Receives POST with {event, memory_id, status, completed_at}.

webhook_secretstring nullable

Secret for webhook HMAC authentication. Sent as X-Webhook-Secret header and used to generate X-Webhook-Signature.

Request body

contentstring required

The content of the memory item you want to add to memory

type'text' | 'code_snippet' | 'document'

Valid memory types

organization_idstring nullable

DEPRECATED - Internal only. Auto-populated from API key scope. Do not set manually. The organization is resolved automatically from the API key's associated organization.

namespace_idstring nullable

Optional namespace ID for multi-tenant memory scoping. When provided, memory is associated with this namespace.

external_user_idstring nullable

Your application's user identifier. This is the primary way to identify users. Use this for your app's user IDs (e.g., 'user_alice_123', UUID, email). Papr will automatically resolve or create internal users as needed.

user_idstring nullable

DEPRECATED: Use 'external_user_id' instead. Internal Papr Parse user ID. Most developers should not use this field directly.

Example request

{
  "content": "Meeting with John Smith from Acme Corp about the Q4 project timeline",
  "context": [
    {
      "content": "Let's discuss the Q4 project timeline with John",
      "role": "user"
    },
    {
      "content": "I'll help you prepare for the timeline discussion. What are your key milestones?",
      "role": "assistant"
    }
  ],
  "external_user_id": "user_alice_123",
  "metadata": {
    "conversationId": "conv-123",
    "customMetadata": {
      "meeting_type": "planning",
      "project_id": "q4-roadmap"
    },
    "emoji_tags": [
      "📅",
      "👥",
      "📋"
    ],
    "emotion_tags": [
      "focused",
      "productive"
    ],
    "hierarchical_structures": "Business/Meetings/Project Planning",
    "location": "Conference Room A",
    "sourceUrl": "https://calendar.example.com/meeting/123",
    "topics": [
      "product",
      "planning",
      "meetings"
    ]
  },
  "policy": {
    "acl": {
      "read": [
        "external_user:user_alice_123"
      ],
      "write": [
        "external_user:user_alice_123"
      ]
    },
    "consent": "implicit",
    "graph": {
      "link_to": [
        "Person:name~John Smith",
        "Company:name~Acme Corp",
        "Meeting:title~Q4 project timeline"
      ],
      "mode": "auto"
    },
    "risk": "none",
    "transform_embedding": {
      "domain_id": "general",
      "mode": "auto"
    }
  },
  "type": "text"
}

Response

Memory successfully added

codeinteger

HTTP status code

statusstring

'success' or 'error'

errorstring nullable

Error message if failed

{"stackTrail":"components:schemas:AddMemoryResponse:properties:details:anyOf","oasType":"schema","type":"unknown","title":"Details","description":"Additional error details or context","nullable":true}

Changes

Changed in 11 of the 37 revisions of this API.3748

Jun 11, 2026b553be9aad372See the full diff
- ●
  deleted the query request parameter enable_holographic
  request-parameter-removed
- ●
  deleted the query request parameter frequency_schema_id
  request-parameter-removed
Jun 11, 2026f29d29d1ad1613See the full diff
- ▲
  removed from the // request property anyOf list
  request-property-any-of-removed
- ○
  added the new optional query request parameter enable_holographic
  new-optional-request-parameter
- ○
  added the new optional query request parameter frequency_schema_id
  new-optional-request-parameter
- ○
  added subschema #1 to the // request property anyOf list
  request-property-any-of-added
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jun 11, 202622d84aa060d6121See the full diff
- ▲
  removed subschema #1 from the // request property anyOf list
  request-property-any-of-removed
- ●
  deleted the query request parameter enable_holographic
  request-parameter-removed
- ●
  deleted the query request parameter frequency_schema_id
  request-parameter-removed
- ○
  added to the // request property anyOf list
  request-property-any-of-added
This revision also has 8 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Jun 10, 202602daa1da4e8211See the full diff
- ▲
  removed from the // request property anyOf list
  request-property-any-of-removed
- ○
  added subschema #1 to the // request property anyOf list
  request-property-any-of-added
Jun 10, 2026b8ef009d36062See the full diff
- ○
  added the new optional query request parameter enable_holographic
  new-optional-request-parameter
- ○
  added the new optional query request parameter frequency_schema_id
  new-optional-request-parameter
Jun 1, 202656af15e4d8642See the full diff
- ●
  deleted the query request parameter enable_holographic
  request-parameter-removed
- ●
  deleted the query request parameter frequency_schema_id
  request-parameter-removed
This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
May 31, 20263f6cc27b443e3See the full diff
- ○
  added the new optional request property
  new-optional-request-property
- ○
  request property deprecated
  request-property-deprecated
- ○
  request property deprecated
  request-property-deprecated
This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog
Mar 13, 20260e4854909d2a8See the full diff
- ○
  added the new optional query request parameter frequency_schema_id
  new-optional-request-parameter
- ○
  added the new optional query request parameter webhook_secret
  new-optional-request-parameter
- ○
  added the new optional query request parameter webhook_url
  new-optional-request-parameter
- ○
  added the new optional request property /////////
  new-optional-request-property
- ○
  added the new optional request property /////////
  new-optional-request-property
- ○
  request property deprecated
  request-property-deprecated
- ○
  added the optional property // to the response with the status
  response-optional-property-added
- ○
  added the optional property // to the response with the status
  response-optional-property-added
Feb 7, 20265f5df128dbcd116See the full diff
- ●
  removed the request property ////
  request-property-removed
- ○
  added the new optional query request parameter enable_holographic
  new-optional-request-parameter
- ○
  added the new optional query request parameter format
  new-optional-request-parameter
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new optional request property
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property
  new-optional-request-property
- ○
  request property deprecated
  request-property-deprecated
- ○
  request property // deprecated
  request-property-deprecated
- ○
  request property // deprecated
  request-property-deprecated
- ○
  request property // deprecated
  request-property-deprecated
- ○
  request property // deprecated
  request-property-deprecated
- ○
  request property deprecated
  request-property-deprecated
- ○
  request property // list-of-types was widened by adding types array to media type application/json
  request-property-list-of-types-widened
Nov 19, 20252422ab514a9d4See the full diff
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property
- ○
  added the new optional request property //
  new-optional-request-property

Full history (11 revisions)