Quick Start Guide

Deployment Options: This guide uses Papr Cloud (managed service). For self-hosted deployment, see the Self-Hosted Guide.

Welcome to Papr Memory! Get your AI agent from forgetful assistant to intelligent system in 15 minutes.

What is Papr? Papr is a memory layer for AI applications. It stores and retrieves context across chat, documents, and structured data through a single API.

You can start with simple memory APIs (store and search), then expand to graph-aware retrieval, consolidation, and predictive context as your application grows.

Why Papr? You could build memory with SQLite + keyword search. It works for demos, then typically hits vocabulary mismatch, memory drift, and context explosion in production.

Papr gives you the simple API you'd build yourself (store messages, retrieve by keyword) plus the intelligence that prevents production failures (semantic search, relationship tracking, predictive caching, memory consolidation).

Start simple: POST /v1/messages works like event storage
Add intelligence: enable_agentic_graph=true activates hybrid retrieval
Scale seamlessly: Same API from prototype to millions of users

Traditional RAG returns fragments. Papr's Predictive Memory Graph connects context across sources and delivers 91%+ accuracy (ranked #1 on Stanford's STaRK benchmark) in under 150ms (when cached).

Comparing approaches? See Why Papr for detailed comparison with DIY stacks.

First Success in 60 Seconds

Run these two calls to store and retrieve memory immediately. This works with external_user_id and does not require pre-creating a user.

export PAPR_MEMORY_API_KEY='your_api_key_here'

curl -X POST https://memory.papr.ai/v1/memory \
  -H "X-API-Key: $PAPR_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Client-Type: curl" \
  -d '{
    "content": "User prefers weekly email summaries.",
    "external_user_id": "user_123",
    "memory_policy": {"mode": "auto"}
  }'

curl -X POST "https://memory.papr.ai/v1/memory/search?max_memories=5&max_nodes=5" \
  -H "X-API-Key: $PAPR_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Client-Type: curl" \
  -d '{
    "query": "What communication preferences does this user have?",
    "external_user_id": "user_123",
    "enable_agentic_graph": true
  }'

Choose Your Path

Add Memory to Existing Agent - Retrofit memory into any existing agent loop (retrieve before response, write back after)
Chat Memory - Build conversation/session memory with Messages API and compression
Document Memory - Ingest docs and retrieve grounded answers
Structured Data Memory - Convert structured records (for example from Postgres) into graph nodes and relationships
Agent Memory - Persist agent runtime learnings/policies (assistant memory) and reuse them at runtime

What You'll Learn

By the end of this guide, you'll know how to:

Set up Papr Memory in your project (one API call)
Add memories that automatically connect across sources
Retrieve context with 91%+ accuracy using semantic + graph-based search
Query insights with natural language or GraphQL

Get your API Key

Create a free account then get your API Key from settings.

Installation

# No installation needed for curl
# Just make sure curl is installed on your system

Authentication

Add PAPR_MEMORY_API_KEY to your .env file, then use it to authenticate:

# Set your API key as an environment variable
export PAPR_MEMORY_API_KEY='your_api_key_here'

Creating Users

Before adding memories, create users to associate with your memories. This enables:

User-specific memory storage and retrieval
Access control for memories
Organizing memories by user
Sharing of memories between users

Note: While creating users explicitly is recommended for better performance and control, you can also use external_user_id directly in memory operations without creating users first. Papr will automatically create users for you behind the scenes.

# Create a user
curl -X POST https://memory.papr.ai/v1/user \
  -H "X-API-Key: $PAPR_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Client-Type: curl" \
  -d '{
    "external_id": "user123", # Your application's user identifier
    "email": "user@example.com", # Optional
    "metadata": {
      "name": "John Doe", # Optional
      "role": "developer" # Optional
    }
  }'

User ID Storage Best Practices

You have two options for associating memories with users:

Using external_user_id (Recommended for most cases)
- Use your application's existing user IDs
- No need to store additional IDs
- Automatic user creation behind the scenes
Using Papr-generated user_id (For advanced use cases)
- Pre-create users for better performance
- More control over user metadata and settings
- Requires storing the Papr user ID

# Example: Storing user ID in your database
def save_papr_user_id(app_user_id, papr_user_id):
    # Your database code here
    db.users.update_one(
        {"id": app_user_id},  # Your application's internal user ID
        {"$set": {"papr_user_id": papr_user_id}}  # The Papr-generated ID (e.g., "usr_abc123")
    )
    
# Example: Retrieving user ID from your database
def get_papr_user_id(app_user_id):
    user = db.users.find_one({"id": app_user_id})
    return user.get("papr_user_id")  # Returns the Papr-generated ID

Performance Optimization with Batch User Creation

For applications with many users, pre-creating users in bulk can improve performance:

# Pre-create users in bulk
bulk_users = client.user.create_batch(
    users=[
        {"external_id": "user123", "email": "user123@example.com"},
        {"external_id": "user456", "email": "user456@example.com"},
        {"external_id": "user789", "email": "user789@example.com"}
    ]
)

Adding Memories

Add a new memory to your knowledge base, using either your external user ID or the Papr-generated user ID:

curl -X POST https://memory.papr.ai/v1/memory \
  -H "X-API-Key: $PAPR_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Client-Type: curl" \
  -d '{
    "content": "Meeting notes from the product planning session",
    "type": "text",
    "external_user_id": "user123",  // Your application's user identifier
    "metadata": {
      "createdAt": "2024-03-21T10:00:00Z",
      "topics": ["meeting", "planning", "product"],
      "customMetadata": {
        "priority": "high",
        "department": "product",
        "meeting_type": "planning"
      }
    }
  }'

Searching Memories

Search through memories using natural language and either your external user ID or the Papr-generated user ID:

curl -X POST https://memory.papr.ai/v1/memory/search \
  -H "X-API-Key: $PAPR_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept-Encoding: gzip" \
  -H "X-Client-Type: curl" \
  -d '{
    "query": "What are the key points from our recent product planning?",
    "external_user_id": "user123",  // Your application's user identifier
    "enable_agentic_graph": true,  // Enable intelligent entity-aware search
    "max_memories": 20,
    "max_nodes": 15,
    "metadata": {
      "topics": ["planning", "product"],
      "customMetadata": {
        "priority": "high",
        "department": "product"
      }
    }
  }'

User-Specific vs. Global Search

You can choose whether to search memories for a specific user or across all accessible memories:

# Search only for a specific user's memories (using external_user_id)
user_specific_results = client.memory.search(
    query="product planning",
    external_user_id="user123",  # Your application's user identifier
    enable_agentic_graph=True  # Enable intelligent entity-aware search
)

# Search across all accessible memories
global_results = client.memory.search(
    query="product planning",
    enable_agentic_graph=True  # Enable intelligent entity-aware search
    # No user filter means search all accessible memories
)

Getting a Specific Memory

Retrieve a specific memory by its ID to verify it was added correctly:

curl -X GET https://memory.papr.ai/v1/memory/mem_abc123 \
  -H "X-API-Key: $PAPR_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Client-Type: curl"

Providing Search Feedback

After retrieving search results, you can provide feedback to improve future search quality:

curl -X POST https://memory.papr.ai/v1/feedback \
  -H "X-API-Key: $PAPR_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Client-Type: curl" \
  -d '{
    "search_id": "search_def456",
    "feedbackData": {
      "feedbackType": "thumbs_up",
      "feedbackSource": "inline",
      "feedbackText": "These results were helpful!"
    }
  }'

Advanced Topics (Recommended Next)

Use dedicated pages for deeper implementation details: