Changelog

All notable changes to Papr Memory API will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

• Memory status — GET /v1/memory/status/{memory_id} and GET /v1/memory/batch/status/{batch_id} for async processing lifecycle; WebSocket paths documented in OpenAPI (/ws/memory-status/...).
• Webhooks on memory create — Optional webhook_url and webhook_secret query parameters on POST /v1/memory.
• Scoped user deletion — Optional namespace_id on DELETE /v1/user.
• AI proxy and usage — /v1/ai/* routes and /v1/ai/usage (see API reference).

Changed

• Session history order — GET /v1/messages/sessions/{session_id} returns messages in reverse chronological order (newest first). Documentation examples that build chronological transcripts now reverse the list before joining.

[1.9.0] - 2026-06-01

Added

Unified Reranking Configuration

• NEW: reranking_config - Simplified reranking configuration for search
  • Replaces policy.vector, rank_results, and holographic_config
  • Five providers: none, cohere (default), openai, papr_enhanced, papr_max
  • Cohere rerank-v3.5 is now the default reranker (enabled automatically)
  • OpenAI reranking support with gpt-5-nano and gpt-5-mini models
  • Graph-native reranking via papr_enhanced and papr_max providers

Changed

Search Ranking Simplification

• Default reranking now uses Cohere rerank-v3.5 (previously cosine-only)
• Reranking provider names simplified and standardized
• API description updated: "personal memory items" → "enterprise context and memory items"

Deprecated

🚨 Breaking: Search Ranking Field Changes

On Search Endpoint:

• ❌ policy.vector → ✅ reranking_config
• ❌ policy.vector.mode → ✅ reranking_config.reranking_provider
• ❌ rank_results → ✅ reranking_config
• ❌ holographic_config → ✅ reranking_config.reranking_provider: "papr_enhanced" or "papr_max"

Mode → Provider Mapping:

Removed

Deprecated Endpoints (Removed)

• ❌ GET /v1/frequencies
• ❌ GET /v1/frequencies/{frequency_schema_id}
• ❌ POST /v1/holographic/transform
• ❌ POST /v1/holographic/transform/batch
• ❌ POST /v1/holographic/rerank
• ❌ POST /v1/holographic/metadata
• ❌ GET /v1/holographic/domains
• ❌ POST /v1/holographic/domains

Deprecated Query Parameters (Removed)

• ❌ enable_holographic query parameter on /v1/memory POST
• ❌ frequency_schema_id query parameter on /v1/memory POST

Use policy.transform_embedding in request body instead.

Migration Guide

Migrating Search Reranking

Before (Deprecated):

# OLD: policy.vector
results = client.memory.search(
    query="How to sort a list?",
    policy={
        "vector": {
            "mode": "enhanced",
            "domain_id": "cosqa",
            "signal_thresholds": {"language": 0.9}
        }
    }
)

After (Current):

# NEW: reranking_config
results = client.memory.search(
    query="How to sort a list?",
    reranking_config={
        "reranking_provider": "papr_enhanced",  # or "papr_max", "cohere", "openai", "none"
        "domain_id": "cosqa",
        "signal_thresholds": {"language": 0.9}
    }
)

Default Behavior Changed:

• Before: No reranking (cosine-only) unless explicitly configured
• After: Cohere rerank-v3.5 enabled by default
• To disable: Set reranking_provider: "none"

[1.8.0] - 2026-05-31

Added

Graph Transform API (CAESAR-8)

• NEW: /v1/graph/* endpoints - Next-generation graph-aware embedding pipeline
  • POST /v1/graph/transform - Transform text to signals + embeddings (producer endpoint)
  • POST /v1/graph/rerank - Rerank candidates against a query
  • GET /v1/graph/domains - List available domains (builtins + custom)
  • POST /v1/graph/domains - Register custom domain schemas
  • GET /v1/graph/domains/{domain_id} - Get domain details
  • GET /v1/graph/domains/{domain_id}/catalog - View signal catalog
  • POST /v1/graph/domains/{domain_id}/catalog/refresh - Refresh domain catalog

Namespace API Keys

• NEW: POST /v1/namespace/{namespace_id}/api-keys - Create namespace-scoped API keys
  • Enables fine-grained access control per namespace
  • Full key returned once on creation (secure storage required)
  • Supports multi-environment isolation (prod, staging, dev)

Enhanced Policies

• policy.transform_embedding - Unified transform configuration
  • mode: "none" | "auto" | "manual"
  • domain_id: Domain schema identifier (replaces frequency_schema_id)
  • signals: BYO band text values for manual mode
• policy.vector - Unified vector search configuration
  • mode: "fast" | "enhanced" | "max"
  • domain_id: Domain for graph-aware scoring
  • signal_thresholds: Per-signal filtering (replaces frequency_filters)

Search Improvements

• Increased search limit - Maximum results increased from 50 to 200
  • Applies to POST /v1/memory/search limit parameter
  • Better support for comprehensive retrieval scenarios

Changed

Graph-Aware Embeddings Terminology

• frequency_schema_id → domain_id everywhere
• fields → signals in domain definitions
• schema_id → domain_id in domain responses
• Tag rename: "Holographic Transform" → "Graph (CAESAR-8)"
• Improved clarity: "frequency schema" → "domain schema"

Deprecated

🚨 Breaking: Holographic Fields → Policy Structure

On Add/Update/Document Endpoints:

• ❌ enable_holographic → ✅ policy.transform_embedding.mode
  • Use "auto" instead of true, "none" instead of false
• ❌ frequency_schema_id → ✅ policy.transform_embedding.domain_id

On Search Endpoint:

• ❌ holographic_config → ✅ policy.vector
• ❌ holographic_config.enabled → ✅ policy.vector.mode
  • Use "enhanced" or "max" instead of true
• ❌ holographic_config.frequency_schema_id → ✅ policy.vector.domain_id
• ❌ holographic_config.frequency_filters → ✅ policy.vector.signal_thresholds

🚨 Breaking: Holographic Endpoints → Graph Endpoints

All /v1/holographic/* endpoints are deprecated. Use /v1/graph/* equivalents:

Migration Guide

Migrating Graph-Aware Embeddings

See complete migration guide at Deprecations and Migrations.

Quick Migration:

# OLD (deprecated)
memory = client.memory.add(
    content="Python sorting example",
    enable_holographic=True,
    frequency_schema_id="cosqa"
)

# NEW (current)
memory = client.memory.add(
    content="Python sorting example",
    policy={
        "transform_embedding": {
            "mode": "auto",
            "domain_id": "cosqa"
        }
    }
)

# OLD (deprecated)
results = client.memory.search(
    query="How to sort?",
    holographic_config={
        "enabled": True,
        "frequency_schema_id": "cosqa",
        "frequency_filters": {"language": 0.9}
    }
)

# NEW (current)
results = client.memory.search(
    query="How to sort?",
    policy={
        "vector": {
            "mode": "enhanced",
            "domain_id": "cosqa",
            "signal_thresholds": {"language": 0.9}
        }
    }
)

[2.0.0] - 2026-02-11

Added

Messages API

• NEW: /v1/messages endpoint - Store chat messages with automatic memory creation
  • POST /v1/messages - Store user and assistant messages
  • GET /v1/messages/sessions/{session_id} - Retrieve conversation history
  • GET /v1/messages/sessions/{session_id}/compress - Get compressed conversation context
  • GET /v1/messages/sessions/{session_id}/status - Check session metadata
  • POST /v1/messages/sessions/{session_id}/process - Batch process messages into memories
• Session Management - Built-in grouping and compression of chat conversations
• Automatic Compression - Hierarchical summaries generated every 15 messages
• Role-Based Memory Creation - User messages and assistant learnings automatically categorized

Memory Policy (Replaces graph_generation)

• memory_policy field - Unified field for controlling knowledge graph generation, ACL, consent, and risk
• Node Constraints - More powerful entity matching and property control
  • Control when entities are created vs linked (create: "auto" | "never" | "always")
  • Define search strategies (exact vs semantic matching)
  • Force specific property values on matched entities
• Edge Constraints - Control relationship creation between entities
• link_to DSL - Shorthand syntax for defining node/edge constraints
• Schema-Level Policies - Define default memory_policy in schema definitions
• Document-Level Policies - Apply memory_policy during document uploads
• ACL Support - Access control lists for read/write permissions (OMO standard)
• Consent Tracking - Track consent level: explicit, implicit, terms, none (OMO standard)
• Risk Classification - Classify data as none, sensitive, or flagged (OMO standard)

Changed

Breaking Changes

• graph_generation → memory_policy (backward compatible, but deprecated)
  • Old graph_generation.auto.schema_id → New memory_policy.schema_id
  • Old graph_generation.auto.property_overrides → New memory_policy.node_constraints
  • Old graph_generation.auto.simple_schema_mode → Removed (use schema_id directly)
  • Nodes: label field renamed to type
  • Relationships: Simplified field names (source_node_id → source, etc.)

Document Processing

• POST /v1/document now accepts memory_policy parameter
• Document uploads can inherit schema-level memory_policy settings
• Removed simple_schema_mode parameter (use memory_policy.schema_id instead)

Schema Definitions

• UserGraphSchema-Input now supports memory_policy field for schema-level defaults
• Schemas can enforce default node/edge constraints for all memories using that schema

Deprecated

• graph_generation field - Still works but use memory_policy instead
  • All graph_generation functionality is now in memory_policy
  • Will be removed in a future version
• simple_schema_mode parameter - Use schema_id within memory_policy instead
• property_overrides - Use node_constraints with more granular control

Migration Guide

Migrating from graph_generation to memory_policy

Before (deprecated):

client.memory.add(
    content="Meeting with Jane",
    graph_generation={
        "mode": "auto",
        "auto": {
            "schema_id": "crm_schema",
            "simple_schema_mode": True,
            "property_overrides": [
                {
                    "nodeLabel": "Contact",
                    "match": {"name": "Jane"},
                    "set": {"id": "contact_jane", "role": "manager"}
                }
            ]
        }
    }
)

After (recommended):

client.memory.add(
    content="Meeting with Jane",
    memory_policy={
        "mode": "auto",
        "schema_id": "crm_schema",
        "node_constraints": [
            {
                "node_type": "Contact",
                "search": {
                    "properties": [{"name": "name", "mode": "semantic"}]
                },
                "set": {
                    "role": {"mode": "exact", "value": "manager"}
                }
            }
        ]
    }
)

Manual Mode Changes:

# Before
memory_policy={
    "mode": "manual",
    "manual": {
        "nodes": [
            {"id": "n1", "label": "Contract", "properties": {...}}
        ],
        "relationships": [
            {"source_node_id": "n1", "target_node_id": "n2", "relationship_type": "REFERS_TO"}
        ]
    }
}

# After
memory_policy={
    "mode": "manual",
    "nodes": [
        {"id": "n1", "type": "Contract", "properties": {...}}
    ],
    "relationships": [
        {"source": "n1", "target": "n2", "type": "REFERS_TO"}
    ]
}

Migrating to Messages API

If you're building chat applications, switch from direct memory storage to the Messages API:

Before:

# Storing chat messages as direct memories
client.memory.add(
    content="User message",
    metadata={"role": "user", "conversation_id": "conv_123"}
)

After (recommended for chat):

# Using Messages API
client.messages.store(
    content="User message",
    role="user",
    session_id="session_123",
    external_user_id="user_456",
    process_messages=True  # Automatically create memories
)

# Get conversation history
history = client.messages.get_history(session_id="session_123", limit=50)

# Compress long conversations
compressed = client.messages.compress_session(session_id="session_123")
context = compressed.context_for_llm  # Use in LLM prompts

Schema-Level Policies

Before:

# Schema without policies
schema = client.schemas.create(
    name="E-commerce Schema",
    node_types={...}
)

# Apply policies per memory
client.memory.add(
    content="...",
    graph_generation={"mode": "auto", "auto": {"schema_id": schema.id}}
)

After (DRY approach):

# Schema with default policy
schema = client.schemas.create(
    name="E-commerce Schema",
    node_types={...},
    memory_policy={
        "mode": "auto",
        "node_constraints": [
            {
                "node_type": "Product",
                "create": "never",  # Never create products via chat
                "search": {"properties": [{"name": "sku", "mode": "exact"}]}
            }
        ]
    }
)

# Inherits schema's policy automatically
client.memory.add(
    content="...",
    memory_policy={"schema_id": schema.id}
)

Impact Summary

* graph_generation is deprecated but still works. Plan to migrate before future removal.

Backward Compatibility

All changes are backward compatible:

• graph_generation field still works (deprecated)
• Existing schemas and memories work unchanged
• Old property_overrides format still accepted
• No immediate action required for existing implementations

However, we recommend migrating to the new syntax for:

• Access to new features (ACL, consent, risk)
• More powerful node/edge constraints
• Better schema-level policy inheritance
• Future-proofing your code

Resources

• Messages Management Guide
• Graph Generation (with memory_policy)
• Custom Schemas with Policies
• Document Processing
• API Reference

Support

If you encounter issues during migration:

1. Check the Migration Guide above
2. Review updated documentation
3. Contact support with specific questions

Version History Summary

v2.0.0 (2026-02-11) - Major release with Messages API and memory_policy architecture

• New Messages API for chat applications
• memory_policy field replacing graph_generation
• Schema-level policies
• Message compression and summarization
• ACL, consent, and risk tracking (OMO standard)

Previous Versions

For detailed information about earlier versions, see our GitHub releases.