Messages

Papr Memory API (1.0.0)

API for managing personal memory items with authentication and user-specific data.

Authentication

This API supports three authentication methods:

  • API Key: Include your API key in the X-API-Key header
    X-API-Key: <your-api-key>
  • Session Token: Include your session token in the X-Session-Token header
    X-Session-Token: <your-session-token>
  • Bearer Token: Include your OAuth2 token from Auth0 in the Authorization header
    Authorization: Bearer <token>

All endpoints require one of these authentication methods.

Download OpenAPI description
arazzo.json
arazzo.yaml
Languages
Servers
Production server
http://memory.papr.ai/

v1

Operations

Memory

Operations

User

Operations

Feedback

Operations

Schema Management

Operations

Messages

Operations

Store Message

Request

Store a chat message and queue it for AI analysis and memory creation.

Authentication Required: Bearer token, API key, or session token

Processing Control:

  • Set process_messages: true (default) to enable full AI analysis and memory creation
  • Set process_messages: false to store messages only without processing into memories

Processing Flow (when process_messages=true):

  1. Message is immediately stored in PostMessage class
  2. Background processing analyzes the message for memory-worthiness
  3. If worthy, creates a memory with appropriate role-based categorization
  4. Links the message to the created memory

Role-Based Categories:

  • User messages: preference, task, goal, facts, context
  • Assistant messages: skills, learning

Session Management:

  • sessionId is required to group related messages
  • Use the same sessionId for an entire conversation
  • Optional title: Set a human-readable title for the conversation (e.g., "Q4 Planning Session")
  • Retrieve conversation history using GET /messages/sessions/{sessionId}
Bodyapplication/jsonrequired
contentContent (string) or Array of Content (objects)(Content)required

The content of the chat message - can be a simple string or structured content objects

Any of:

The content of the chat message - can be a simple string or structured content objects

string(Content)

The content of the chat message - can be a simple string or structured content objects

rolestring(MessageRole)required

Role of the message sender (user or assistant)

Enum"user""assistant"
sessionIdstring(Sessionid)required

Session ID to group related messages in a conversation

titleTitle (string) or Title (null)(Title)

Optional title for the conversation session. Sets the Chat.title in Parse Server for easy identification.

Any of:

Optional title for the conversation session. Sets the Chat.title in Parse Server for easy identification.

string(Title)

Optional title for the conversation session. Sets the Chat.title in Parse Server for easy identification.

metadataMemoryMetadata (object) or null

Optional metadata for the message (topics, location, etc.)

Any of:

Optional metadata for the message (topics, location, etc.)

contextArray of Context (objects) or Context (null)(Context)

Optional context for the message (conversation history or relevant context)

Any of:

Optional context for the message (conversation history or relevant context)

relationships_jsonArray of Relationships Json (objects) or Relationships Json (null)(Relationships Json)

Optional array of relationships for Graph DB (Neo4j)

Any of:

Optional array of relationships for Graph DB (Neo4j)

process_messagesboolean(Process Messages)

Whether to process messages into memories (true) or just store them (false). Default is true.

Default true
memory_policyMemoryPolicy (object) or null

Unified policy for graph generation and OMO safety. Use mode='auto' (LLM extraction), 'manual' (exact nodes), or 'hybrid' (LLM with constraints). Includes consent, risk, and ACL settings.

Any of:

Unified policy for graph generation and OMO safety. Use mode='auto' (LLM extraction), 'manual' (exact nodes), or 'hybrid' (LLM with constraints). Includes consent, risk, and ACL settings.

organization_idOrganization Id (string) or Organization Id (null)(Organization Id)

Optional organization ID for multi-tenant message scoping

Any of:

Optional organization ID for multi-tenant message scoping

string(Organization Id)

Optional organization ID for multi-tenant message scoping

namespace_idNamespace Id (string) or Namespace Id (null)(Namespace Id)

Optional namespace ID for multi-tenant message scoping

Any of:

Optional namespace ID for multi-tenant message scoping

string(Namespace Id)

Optional namespace ID for multi-tenant message scoping

graph_generationGraphGeneration (object) or nullDeprecated

DEPRECATED: Use 'memory_policy' instead. Legacy graph generation configuration.

Any of:
Deprecated

DEPRECATED: Use 'memory_policy' instead. Legacy graph generation configuration.

curl -i -X POST \
  http://memory.papr.ai/v1/messages \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: YOUR_API_KEY_HERE' \
  -d '{
    "content": "Can you help me plan the Q4 product roadmap?",
    "metadata": {
      "location": "Office",
      "topics": [
        "product",
        "planning",
        "roadmap"
      ]
    },
    "process_messages": true,
    "role": "user",
    "sessionId": "session_123",
    "title": "Q4 Product Planning"
  }'

Responses

Message stored and queued for processing

Bodyapplication/json
objectIdstring(Objectid)required

Parse Server objectId of the stored message

Example: "msg_abc123"
sessionIdstring(Sessionid)required

Session ID of the conversation

Example: "session_123"
rolestring(MessageRole)required

Role of the message sender

Enum"user""assistant"
Example: "user"
contentContent (string) or Array of Content (objects)(Content)required

Content of the message - can be a simple string or structured content objects

Example: "Can you help me plan the Q4 product roadmap?"
Any of:

Content of the message - can be a simple string or structured content objects

string(Content)

Content of the message - can be a simple string or structured content objects

createdAtstring(date-time)(Createdat)required

When the message was created

Example: "2024-01-15T10:30:00Z"
processing_statusstring(Processing Status)

Status of background processing (queued, analyzing, completed, failed)

Default "queued"
Example: "queued"
Response
application/json
{
  "content": "Can you help me plan the Q4 product roadmap?",
  "createdAt": "2024-01-15T10:30:00Z",
  "objectId": "msg_abc123",
  "processing_status": "queued",
  "role": "user",
  "sessionId": "session_123"
}

Get Session History

Request

Retrieve message history for a specific conversation session.

Authentication Required: Bearer token, API key, or session token

Pagination:

  • Use limit and skip parameters for pagination
  • Messages are returned in chronological order (oldest first)
  • total_count indicates total messages in the session

Summaries (if available):

  • Returns hierarchical conversation summaries (short/medium/long-term)
  • Includes context_for_llm field with pre-compressed context
  • Summaries are automatically generated every 15 messages
  • Use /sessions/{session_id}/compress endpoint to retrieve on-demand

Access Control:

  • Only returns messages for the authenticated user
  • Workspace scoping is applied if available
Path
session_idstring(Session Id)required
Query
limitinteger(Limit)[ 1 .. 100 ]

Maximum number of messages to return

Default 50
skipinteger(Skip)>= 0

Number of messages to skip for pagination

Default 0
curl -i -X GET \
  'http://memory.papr.ai/v1/messages/sessions/{session_id}?limit=50&skip=0' \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

Message history retrieved

Bodyapplication/json
sessionIdstring(Sessionid)required

Session ID of the conversation

Example: "session_123"
messagesArray of objects(Messages)required

List of messages in chronological order

Example: [{"content":"Can you help me plan the Q4 product roadmap?","createdAt":"2024-01-15T10:30:00Z","objectId":"msg_abc123","processing_status":"completed","role":"user","sessionId":"session_123"},{"content":"I'd be happy to help you plan your Q4 roadmap. Let's start by identifying your key objectives.","createdAt":"2024-01-15T10:31:00Z","objectId":"msg_def456","processing_status":"completed","role":"assistant","sessionId":"session_123"}]
messages[].​objectIdstring(Objectid)required

Parse Server objectId of the stored message

Example: "msg_abc123"
messages[].​sessionIdstring(Sessionid)required

Session ID of the conversation

Example: "session_123"
messages[].​rolestring(MessageRole)required

Role of the message sender

Enum"user""assistant"
Example: "user"
messages[].​contentContent (string) or Array of Content (objects)(Content)required

Content of the message - can be a simple string or structured content objects

Example: "Can you help me plan the Q4 product roadmap?"
Any of:

Content of the message - can be a simple string or structured content objects

string(Content)

Content of the message - can be a simple string or structured content objects

messages[].​createdAtstring(date-time)(Createdat)required

When the message was created

Example: "2024-01-15T10:30:00Z"
messages[].​processing_statusstring(Processing Status)

Status of background processing (queued, analyzing, completed, failed)

Default "queued"
Example: "queued"
total_countinteger(Total Count)required

Total number of messages in the session

Example: 2
summariesConversationSummaryResponse (object) or null

Hierarchical conversation summaries for context compression

Example: {"long_term":"Product planning and strategy conversation","medium_term":"Ongoing product planning discussion for Q4","short_term":"User requested help planning Q4 product roadmap","topics":["product","roadmap","planning","Q4"]}
Any of:

Hierarchical conversation summaries for context compression

context_for_llmContext For Llm (string) or Context For Llm (null)(Context For Llm)

Pre-formatted compressed context ready for LLM consumption (summaries + recent messages)

Example: "FULL SESSION: Product planning and strategy conversation\nRECENT (last ~100): Ongoing product planning discussion for Q4\nCURRENT (last 15): User requested help planning Q4 product roadmap"
Any of:

Pre-formatted compressed context ready for LLM consumption (summaries + recent messages)

string(Context For Llm)

Pre-formatted compressed context ready for LLM consumption (summaries + recent messages)

Response
application/json
{
  "context_for_llm": "FULL SESSION: Product planning and strategy conversation\nRECENT (last ~100): Ongoing product planning discussion for Q4\nCURRENT (last 15): User requested help planning Q4 product roadmap",
  "messages": [
    { … },
    { … }
  ],
  "sessionId": "session_123",
  "summaries": {
    "long_term": "Product planning and strategy conversation",
    "medium_term": "Ongoing product planning discussion for Q4",
    "short_term": "User requested help planning Q4 product roadmap",
    "topics": [ … ]
  },
  "total_count": 2
}

Update Session

Request

Update session properties (e.g., title, metadata).

Authentication Required: Bearer token, API key, or session token

Updatable Fields:

  • title: Update the conversation title
  • metadata: Update session metadata (merged with existing)

Example Request:

{
    "title": "Updated Session Title",
    "metadata": {"custom_field": "value"}
}
Path
session_idstring(Session Id)required
Bodyapplication/jsonrequired
titleTitle (string) or Title (null)(Title)

New title for the session

Any of:

New title for the session

string(Title)

New title for the session

metadataMetadata (object) or Metadata (null)(Metadata)

Metadata to merge with existing session metadata

Any of:

Metadata to merge with existing session metadata

curl -i -X PATCH \
  'http://memory.papr.ai/v1/messages/sessions/{session_id}' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "string",
    "metadata": {}
  }'

Responses

Session updated successfully

Bodyapplication/json
any
Response
application/json
null

Get Session Status

Request

Get processing status for messages in a session.

Authentication Required: Bearer token, API key, or session token

Status Information:

  • Total messages in session
  • Processing status breakdown (queued, analyzing, completed, failed)
  • Any messages with processing errors
Path
session_idstring(Session Id)required
curl -i -X GET \
  'http://memory.papr.ai/v1/messages/sessions/{session_id}/status' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Session processing status

Bodyapplication/json
any
Response
application/json
null

Compress Session

Request

Get compressed conversation context for a session.

Compress your conversation into hierarchical summaries with rich metadata, perfect for reducing token usage in LLM context windows.

Authentication Required: Bearer token, API key, or session token

What it returns:

  • short_term: Last 15 messages compressed
  • medium_term: Last ~100 messages compressed
  • long_term: Full session compressed
  • topics: Key topics discussed
  • enhanced_fields: Project context, tech stack, key decisions, next steps, files accessed

Perfect for:

  • Reducing token usage in LLM prompts (96% savings)
  • Providing conversation context without full history
  • Quick conversation overview for AI agents
  • Project documentation and status snapshots

Input: Just the session ID - all context is extracted automatically

Path
session_idstring(Session Id)required
curl -i -X GET \
  'http://memory.papr.ai/v1/messages/sessions/{session_id}/compress' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Session summary (compressed context)

Bodyapplication/json
session_idstring(Session Id)required

Session ID of the conversation

Example: "session_123"
summariesobject(ConversationSummaryResponse)required

Hierarchical conversation summaries

Example: {"last_updated":"2024-01-15T10:31:00Z","long_term":"Product planning and strategy conversation focused on Q4 roadmap development and execution.","medium_term":"Ongoing product planning discussion for Q4, covering objectives, timelines, and resource allocation.","short_term":"User requested help planning Q4 product roadmap. Assistant offered to help identify key objectives.","topics":["product planning","Q4 roadmap","objectives","strategy"]}
summaries.​short_termShort Term (string) or Short Term (null)(Short Term)

Summary of last 15 messages

Example: "User requested help planning Q4 product roadmap. Assistant offered to help identify key objectives."
Any of:

Summary of last 15 messages

string(Short Term)

Summary of last 15 messages

summaries.​medium_termMedium Term (string) or Medium Term (null)(Medium Term)

Summary of last ~100 messages

Example: "Ongoing product planning discussion for Q4, covering objectives, timelines, and resource allocation."
Any of:

Summary of last ~100 messages

string(Medium Term)

Summary of last ~100 messages

summaries.​long_termLong Term (string) or Long Term (null)(Long Term)

Full session summary

Example: "Product planning and strategy conversation focused on Q4 roadmap development and execution."
Any of:

Full session summary

string(Long Term)

Full session summary

summaries.​topicsArray of strings(Topics)

Key topics discussed

Example: ["product planning","Q4 roadmap","objectives","strategy"]
summaries.​last_updatedLast Updated (string) or Last Updated (null)(Last Updated)

When summaries were last updated

Example: "2024-01-15T10:31:00Z"
Any of:

When summaries were last updated

string(date-time)(Last Updated)

When summaries were last updated

ai_agent_notestring(Ai Agent Note)required

Instructions for AI agents on how to search for more details about this conversation

Example: "To find more details about this conversation, search memories with metadata filter: sessionId='session_123'"
from_cacheboolean(From Cache)required

Whether summaries were retrieved from cache (true) or just generated (false)

Example: true
message_countMessage Count (integer) or Message Count (null)(Message Count)

Number of messages summarized (only present if just generated)

Any of:

Number of messages summarized (only present if just generated)

integer(Message Count)

Number of messages summarized (only present if just generated)

Response
application/json
{
  "ai_agent_note": "To find more details about this conversation, search memories with metadata filter: sessionId='session_123'",
  "from_cache": true,
  "session_id": "session_123",
  "summaries": {
    "last_updated": "2024-01-15T10:31:00Z",
    "long_term": "Product planning and strategy conversation focused on Q4 roadmap development and execution.",
    "medium_term": "Ongoing product planning discussion for Q4, covering objectives, timelines, and resource allocation.",
    "short_term": "User requested help planning Q4 product roadmap. Assistant offered to help identify key objectives.",
    "topics": [ … ]
  }
}

Process Session Messages

Request

Process all stored messages in a session that were previously stored with process_messages=false.

Authentication Required: Bearer token, API key, or session token

This endpoint allows you to retroactively process messages that were initially stored without processing. Useful for:

  • Processing messages after deciding you want them as memories
  • Batch processing large conversation sessions
  • Re-processing sessions with updated AI models

Processing Behavior:

  • Only processes messages with status 'stored_only' or 'pending'
  • Uses the same smart batch analysis (every 15 messages)
  • Respects existing memory creation pipeline
Path
session_idstring(Session Id)required
curl -i -X POST \
  'http://memory.papr.ai/v1/messages/sessions/{session_id}/process' \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>'

Responses

Session messages queued for processing

Bodyapplication/json
any
Response
application/json
null

omo

Operations

Sync

Operations

Telemetry

Operations

Document

Operations

GraphQL

Operations

Authentication

Operations