Sign in
v1
Memory

Search V1

Search through memories with authentication required.

**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

**Response Format Options**:
Choose between standard JSON or TOON (Token-Oriented Object Notation) format:
- **JSON (default)**: Standard JSON response format
- **TOON**: Optimized format achieving 30-60% token reduction for LLM contexts
  - Use `response_format=toon` query parameter
  - Returns `text/plain` with TOON-formatted content
  - Ideal for LLM integrations to reduce API costs and latency
  - Maintains semantic clarity while minimizing token usage
  - Example: `/v1/memory/search?response_format=toon`

**Custom Schema Support**:
This endpoint supports both system-defined and custom user-defined node types:
- **System nodes**: Memory, Person, Company, Project, Task, Insight, Meeting, Opportunity, Code
- **Custom nodes**: Defined by developers via UserGraphSchema (e.g., Developer, Product, Customer, Function)

When custom schema nodes are returned:
- Each custom node includes a `schema_id` field referencing the UserGraphSchema
- The response includes a `schemas_used` array listing all schema IDs used
- Use `GET /v1/schemas/{schema_id}` to retrieve full schema definitions including:
  - Node type definitions and properties
  - Relationship type definitions and constraints
  - Validation rules and requirements

**Recommended Headers**:
```
Accept-Encoding: gzip
```

The API supports response compression for improved performance. Responses larger than 1KB will be automatically compressed when this header is present.

**HIGHLY RECOMMENDED SETTINGS FOR BEST RESULTS:**
- Set `enable_agentic_graph: true` for intelligent, context-aware search that can understand ambiguous references
- Use `max_memories: 15-20` for comprehensive memory coverage
- Use `max_nodes: 10-15` for comprehensive graph entity relationships
- Use `response_format: toon` when integrating with LLMs to reduce token costs by 30-60%

**Agentic Graph Benefits:**
When enabled, the system can understand vague references by first identifying specific entities from your memory graph, then performing targeted searches. For example:
- "customer feedback" → identifies your customers first, then finds their specific feedback
- "project issues" → identifies your projects first, then finds related issues
- "team meeting notes" → identifies your team members first, then finds meeting notes
- "code functions" → identifies your functions first, then finds related code

**Role-Based Memory Filtering:**
Filter memories by role and category using metadata fields:
- `metadata.role`: Filter by "user" or "assistant" 
- `metadata.category`: Filter by category (user: preference, task, goal, facts, context | assistant: skills, learning)

**User Resolution Precedence:**
- If both user_id and external_user_id are provided, user_id takes precedence.
- If only external_user_id is provided, it will be resolved to the internal user.
- If neither is provided, the authenticated user is used.
post/v1/memory/search

Query parameters

max_memoriesinteger

HIGHLY RECOMMENDED: Maximum number of memories to return. Use at least 15-20 for comprehensive results. Lower values (5-10) may miss relevant information. Default is 20 for optimal coverage.

HIGHLY RECOMMENDED: Maximum number of memories to return. Use at least 15-20 for comprehensive results. Lower values (5-10) may miss relevant information. Default is 20 for optimal coverage.

max_nodesinteger

HIGHLY RECOMMENDED: Maximum number of neo nodes to return. Use at least 10-15 for comprehensive graph results. Lower values may miss important entity relationships. Default is 15 for optimal coverage.

HIGHLY RECOMMENDED: Maximum number of neo nodes to return. Use at least 10-15 for comprehensive graph results. Lower values may miss important entity relationships. Default is 15 for optimal coverage.

response_format'json' | 'toon'

Response format options for API endpoints.

  • json: Standard JSON format (default)
  • toon: Token-Oriented Object Notation format for 30-60% token reduction in LLM contexts

Response format: 'json' (default) or 'toon' (Token-Oriented Object Notation for 30-60% token reduction in LLM contexts)

Headers

Accept-Encodingstring

Recommended to use 'gzip' for response compression

Request body

querystring required

Detailed search query describing what you're looking for. For best results, write 2-3 sentences that include specific details, context, and time frame. Examples: 'Find recurring customer complaints about API performance from the last month. Focus on issues where customers specifically mentioned timeout errors or slow response times in their conversations.' 'What are the main issues and blockers in my current projects? Focus on technical challenges and timeline impacts.' 'Find insights about team collaboration and communication patterns from recent meetings and discussions.'

rank_resultsboolean

DEPRECATED: Use 'reranking_config' instead. Whether to enable additional ranking of search results. Default is false because results are already ranked when using an LLM for search (recommended approach). Only enable this if you're not using an LLM in your search pipeline and need additional result ranking. Migration: Replace 'rank_results: true' with 'reranking_config: {reranking_enabled: true, reranking_provider: "cohere", reranking_model: "rerank-v3.5"}'

enable_agentic_graphboolean

HIGHLY RECOMMENDED: Enable agentic graph search for intelligent, context-aware results. When enabled, the system can understand ambiguous references by first identifying specific entities from your memory graph, then performing targeted searches. Examples: 'customer feedback' → identifies your customers first, then finds their specific feedback; 'project issues' → identifies your projects first, then finds related issues; 'team meeting notes' → identifies team members first, then finds meeting notes. This provides much more relevant and comprehensive results. Set to false only if you need faster, simpler keyword-based search.

external_user_idstring nullable

Your application's user identifier to filter search results. This is the primary way to identify users. Use this for your app's user IDs (e.g., 'user_alice_123', UUID, email).

user_idstring nullable

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

organization_idstring nullable

Optional organization ID for multi-tenant search scoping. When provided, search is scoped to memories within this organization.

namespace_idstring nullable

Optional namespace ID for multi-tenant search scoping. When provided, search is scoped to memories within this namespace.

schema_idstring nullable

Optional user-defined schema ID to use for this search. If provided, this schema (plus system schema) will be used for query generation. If not provided, system will automatically select relevant schema based on query content.

Example request

{
  "enable_agentic_graph": false,
  "external_user_id": "external_user_123",
  "query": "Find recurring customer complaints about API performance from the last month. Focus on issues that multiple customers have mentioned and any specific feature requests or workflow improvements they've suggested.",
  "rank_results": true
}

Response

Successfully retrieved memories

codeinteger

HTTP status code

statusstring

'success' or 'error'

errorstring nullable

Error message if failed

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

Unique identifier for this search query, maps to QueryLog objectId in Parse Server

Example response

{
  "code": 200,
  "data": {
    "memories": [],
    "nodes": []
  },
  "search_id": "abc123def456",
  "status": "success"
}

Changes

Changed in 20 of the 37 revisions of this API.1234300

  • f29d29d1ad1611See the full diff
    • ▲

      removed UserMemoryCategory AssistantMemoryCategory from the metadata/anyOf[subschema #1: MemoryMetadata]/category request property anyOf list

      request-property-any-of-removed

    • ○

      added subschema #1 to the metadata/anyOf[subschema #1: MemoryMetadata]/category 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

  • 22d84aa060d611See the full diff
    • ▲

      removed subschema #1 from the metadata/anyOf[subschema #1: MemoryMetadata]/category request property anyOf list

      request-property-any-of-removed

    • ○

      added UserMemoryCategory AssistantMemoryCategory to the metadata/anyOf[subschema #1: MemoryMetadata]/category 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

  • c81ae5036e691See the full diff
    • ○

      added the new optional request property holographic_config

      new-optional-request-property

    This revision also has 7 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 8a7fd5a949bf1See the full diff
    • ●

      removed the request property holographic_config

      request-property-removed

    This revision also has 11 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 02daa1da4e8211See the full diff
    • ▲

      removed UserMemoryCategory AssistantMemoryCategory from the metadata/anyOf[subschema #1: MemoryMetadata]/category request property anyOf list

      request-property-any-of-removed

    • ○

      added subschema #1 to the metadata/anyOf[subschema #1: MemoryMetadata]/category request property anyOf list

      request-property-any-of-added

  • 56af15e4d864212See the full diff
    • ●

      removed the request property policy/anyOf[subschema #1: MemorySearchPolicy]/acl

      request-property-removed

    • ●

      removed the request property policy/anyOf[subschema #1: MemorySearchPolicy]/rerank

      request-property-removed

    • ○

      added the new optional request property reranking_config/anyOf[subschema #1: RerankingConfig]/domain_id

      new-optional-request-property

    • ○

      added the new optional request property reranking_config/anyOf[subschema #1: RerankingConfig]/return_debug

      new-optional-request-property

    • ○

      added the new optional request property reranking_config/anyOf[subschema #1: RerankingConfig]/return_signal_scores

      new-optional-request-property

    • ○

      added the new optional request property reranking_config/anyOf[subschema #1: RerankingConfig]/signal_multipliers

      new-optional-request-property

    • ○

      added the new optional request property reranking_config/anyOf[subschema #1: RerankingConfig]/signal_thresholds

      new-optional-request-property

    • ○

      the reranking_enabled request property default value changed from false to true

      request-property-default-value-changed

    • ○

      the reranking_model request property default value changed from gpt-5-nano to rerank-v3.5

      request-property-default-value-changed

    • ○

      the reranking_provider request property default value changed from openai to cohere

      request-property-default-value-changed

    • ○

      request property policy deprecated

      request-property-deprecated

    • ○

      added the new none enum value to the request property reranking_config/anyOf[subschema #1: RerankingConfig]/reranking_provider

      request-property-enum-value-added

    • ○

      added the new papr_enhanced enum value to the request property reranking_config/anyOf[subschema #1: RerankingConfig]/reranking_provider

      request-property-enum-value-added

    • ○

      added the new papr_max enum value to the request property reranking_config/anyOf[subschema #1: RerankingConfig]/reranking_provider

      request-property-enum-value-added

    This revision also has 3 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 3f6cc27b443e10See the full diff
    • ○

      added the new optional request property policy

      new-optional-request-property

    • ○

      for the query request parameter max_memories, the max was increased from 50.00 to 200.00

      request-parameter-max-increased

    • ○

      request property holographic_config deprecated

      request-property-deprecated

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/holographic_frequency_scores to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/holographic_frequency_scores to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/holographic_frequency_scores to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/holographic_frequency_scores to the response with the 403 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/holographic_frequency_scores to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/holographic_frequency_scores to the response with the 415 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/holographic_frequency_scores to the response with the 500 status

      response-optional-property-added

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 108f632ed6352See the full diff
    • ○

      added the new optional request property holographic_config/anyOf[subschema #1: HolographicConfig]/frequency_filters

      new-optional-request-property

    • ○

      added the new optional request property holographic_config/anyOf[subschema #1: HolographicConfig]/include_frequency_scores

      new-optional-request-property

    This revision also has 1 change that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 0e4854909d2a5See the full diff
    • ○

      added the new optional request property holographic_config/anyOf[subschema #1: HolographicConfig]/frequency_schema_id

      new-optional-request-property

    • ○

      added the new optional request property holographic_config/anyOf[subschema #1: HolographicConfig]/scoring_method

      new-optional-request-property

    • ○

      added the new optional request property search_acl

      new-optional-request-property

    • ○

      added the optional property detail/items/ctx to the response with the 422 status

      response-optional-property-added

    • ○

      added the optional property detail/items/input to the response with the 422 status

      response-optional-property-added

  • 5f5df128dbcd170See the full diff
    • ●

      removed the request property simple_schema_mode

      request-property-removed

    • ○

      added the new optional request property holographic_config

      new-optional-request-property

    • ○

      added the new optional request property metadata/anyOf[subschema #1: MemoryMetadata]/acl

      new-optional-request-property

    • ○

      added the new optional request property metadata/anyOf[subschema #1: MemoryMetadata]/consent

      new-optional-request-property

    • ○

      added the new optional request property metadata/anyOf[subschema #1: MemoryMetadata]/risk

      new-optional-request-property

    • ○

      added the new optional request property omo_filter

      new-optional-request-property

    • ○

      added the new optional request property reranking_config

      new-optional-request-property

    • ○

      added the new optional request property search_override

      new-optional-request-property

    • ○

      request property metadata/anyOf[subschema #1: MemoryMetadata]/external_user_id deprecated

      request-property-deprecated

    • ○

      request property metadata/anyOf[subschema #1: MemoryMetadata]/namespace_id deprecated

      request-property-deprecated

    • ○

      request property metadata/anyOf[subschema #1: MemoryMetadata]/organization_id deprecated

      request-property-deprecated

    • ○

      request property metadata/anyOf[subschema #1: MemoryMetadata]/user_id deprecated

      request-property-deprecated

    • ○

      request property rank_results deprecated

      request-property-deprecated

    • ○

      request property user_id deprecated

      request-property-deprecated

    • ○

      request property metadata/anyOf[subschema #1: MemoryMetadata]/hierarchical_structures list-of-types was widened by adding types array to media type application/json

      request-property-list-of-types-widened

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/metrics to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/metrics to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/metrics to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/metrics to the response with the 403 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/metrics to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/metrics to the response with the 415 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/metrics to the response with the 500 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/popularity_score to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/popularity_score to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/popularity_score to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/popularity_score to the response with the 403 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/popularity_score to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/popularity_score to the response with the 415 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/popularity_score to the response with the 500 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/recency_score to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/recency_score to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/recency_score to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/recency_score to the response with the 403 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/recency_score to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/recency_score to the response with the 415 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/recency_score to the response with the 500 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_confidence to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_confidence to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_confidence to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_confidence to the response with the 403 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_confidence to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_confidence to the response with the 415 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_confidence to the response with the 500 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_score to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_score to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_score to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_score to the response with the 403 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_score to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_score to the response with the 415 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_score to the response with the 500 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_type to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_type to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_type to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_type to the response with the 403 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_type to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_type to the response with the 415 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/reranker_type to the response with the 500 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/similarity_score to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/similarity_score to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/similarity_score to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/similarity_score to the response with the 403 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/similarity_score to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/similarity_score to the response with the 415 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/similarity_score to the response with the 500 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/totalProcessingCost to the response with the 200 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/totalProcessingCost to the response with the 400 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/totalProcessingCost to the response with the 401 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/totalProcessingCost to the response with the 403 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/totalProcessingCost to the response with the 404 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/totalProcessingCost to the response with the 415 status

      response-optional-property-added

    • ○

      added the optional property data/anyOf[subschema #1: SearchResult]/memories/items/totalProcessingCost to the response with the 500 status

      response-optional-property-added