---
title: "Search V1"
method: POST
path: "/v1/memory/search"
tags: ["v1", "Memory"]
---

# Search V1

`POST /v1/memory/search`

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

## Query parameters

- `max_memories` integer — 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_nodes` integer — 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.
- `enable_agentic_graph` boolean, nullable — HIGHLY RECOMMENDED: Enable agentic graph search for intelligent, context-aware results. Can be set via URL parameter or JSON body. URL parameter takes precedence if both are provided.

## Headers

- `Accept-Encoding` string

## Request body

- SearchRequest — Search request parameters
  - `query` string, 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_results` boolean — 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.
  - `enable_agentic_graph` boolean — 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.
  - `user_id` string, nullable — Optional internal user ID to filter search results by a specific user. If not provided, results are not filtered by user. If both user_id and external_user_id are provided, user_id takes precedence.
  - `external_user_id` string, nullable — Optional external user ID to filter search results by a specific external user. If both user_id and external_user_id are provided, user_id takes precedence.
  - `organization_id` string, nullable — Optional organization ID for multi-tenant search scoping. When provided, search is scoped to memories within this organization.
  - `namespace_id` string, nullable — Optional namespace ID for multi-tenant search scoping. When provided, search is scoped to memories within this namespace.
  - `schema_id` string, 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.
  - `simple_schema_mode` boolean — If true, uses simple schema mode: system schema + ONE most relevant user schema. This ensures better consistency between add/search operations and reduces query complexity. Recommended for production use.
  - `metadata` MemoryMetadata — Metadata for memory request
    - `hierarchical_structures` string, nullable — Hierarchical structures to enable navigation from broad topics to specific ones
    - `createdAt` string, nullable — ISO datetime when the memory was created
    - `location` string, nullable
    - `topics` string[], nullable
    - `emoji tags` string[], nullable
    - `emotion tags` string[], nullable
    - `conversationId` string, nullable
    - `sourceUrl` string, nullable
    - `role` 'user' | 'assistant' — Role of the message sender
    - `category` union — Memory category based on role. For users: preference, task, goal, fact, context. For assistants: skills, learning, task, goal, fact, context.
      - 'preference' | 'task' | 'goal' | 'fact' | 'context' — Memory categories for user messages
      - 'skills' | 'learning' | 'task' | 'goal' | 'fact' | 'context' — Memory categories for assistant messages
    - `user_id` string, nullable
    - `external_user_id` string, nullable
    - `external_user_read_access` string[], nullable
    - `external_user_write_access` string[], nullable
    - `user_read_access` string[], nullable
    - `user_write_access` string[], nullable
    - `workspace_read_access` string[], nullable
    - `workspace_write_access` string[], nullable
    - `role_read_access` string[], nullable
    - `role_write_access` string[], nullable
    - `pageId` string, nullable
    - `sourceType` string, nullable
    - `workspace_id` string, nullable
    - `upload_id` string, nullable — Upload ID for document processing workflows
    - `organization_id` string, nullable
    - `namespace_id` string, nullable
    - `sessionId` string, nullable
    - `post` string, nullable
    - `userMessage` string, nullable
    - `assistantMessage` string, nullable
    - `relatedGoals` string[], nullable
    - `relatedUseCases` string[], nullable
    - `relatedSteps` string[], nullable
    - `goalClassificationScores` number[], nullable
    - `useCaseClassificationScores` number[], nullable
    - `stepClassificationScores` number[], nullable
    - `customMetadata` object, nullable — Optional object for arbitrary custom metadata fields. Only string, number, boolean, or list of strings allowed. Nested dicts are not allowed.
  - `search_override` SearchOverrideSpecification — Complete search override specification provided by developer
    - `pattern` SearchOverridePattern, required — Developer-specified search pattern for search override
      - `source_label` string, required — Source node label (e.g., 'Memory', 'Person', 'Company'). Must match schema node types.
      - `relationship_type` string, required — Relationship type (e.g., 'ASSOCIATED_WITH', 'WORKS_FOR'). Must match schema relationship types.
      - `target_label` string, required — Target node label (e.g., 'Person', 'Company', 'Project'). Must match schema node types.
      - `direction` string — Relationship direction: '->' (outgoing), '<-' (incoming), or '-' (bidirectional)
    - `filters` SearchOverrideFilter[] — Property filters to apply to the search pattern
      - `node_type` string, required — Node type to filter (e.g., 'Person', 'Memory', 'Company')
      - `property_name` string, required — Property name to filter on (e.g., 'name', 'content', 'role')
      - `operator` string, required — Filter operator: 'CONTAINS', 'EQUALS', 'STARTS_WITH', 'IN'
      - `value` union, required — Filter value(s). Use list for 'IN' operator.
        - string
        - string[]
        - integer
        - number
        - boolean
    - `return_properties` string[], nullable — Specific properties to return. If not specified, returns all properties.

## Response `200`

Successfully retrieved memories

- SearchResponse
  - `code` integer — HTTP status code
  - `status` string — 'success' or 'error'
  - `data` SearchResult — Return type for SearchResult
    - `memories` Memory[], required
      - `id` string, required
      - `content` string, required
      - `title` string, nullable
      - `type` string, required
      - `metadata` union
        - string
        - object
      - `external_user_id` string, nullable
      - `customMetadata` object, nullable
      - `source_type` string
      - `context` ContextItem[], nullable
        - `role` 'user' | 'assistant', required
        - `content` string, required
      - `location` string, nullable
      - `tags` string[]
      - `hierarchical_structures` string
      - `source_url` string
      - `conversation_id` string
      - `topics` string[]
      - `steps` string[]
      - `current_step` string, nullable
      - `role` string, nullable — Role that generated this memory (user or assistant)
      - `category` string, nullable — Memory category based on role
      - `created_at` string, date-time, nullable
      - `updated_at` string, date-time, nullable
      - `acl` object, required
      - `user_id` string, required
      - `workspace_id` string, nullable
      - `organization_id` string, nullable — Organization ID that owns this memory
      - `namespace_id` string, nullable — Namespace ID this memory belongs to
      - `source_document_id` string, nullable
      - `source_message_id` string, nullable
      - `page_number` integer, nullable
      - `total_pages` integer, nullable
      - `file_url` string, nullable
      - `filename` string, nullable
      - `page` string, nullable
      - `external_user_read_access` string[], nullable
      - `external_user_write_access` string[], nullable
      - `user_read_access` string[], nullable
      - `user_write_access` string[], nullable
      - `workspace_read_access` string[], nullable
      - `workspace_write_access` string[], nullable
      - `role_read_access` string[], nullable
      - `role_write_access` string[], nullable
    - `nodes` Node[], required
      - `label` string, required — Node type label - can be system type (Memory, Person, etc.) or custom type from UserGraphSchema
      - `properties` object, required — Node properties - structure depends on node type and schema
      - `schema_id` string, nullable — Reference to UserGraphSchema ID for custom nodes. Use GET /v1/schemas/{schema_id} to get full schema definition. Null for system nodes.
    - `schemas_used` string[], nullable — List of UserGraphSchema IDs used in this response. Use GET /v1/schemas/{id} to get full schema definitions.
  - `error` string, nullable — Error message if failed
  - `details` unknown
  - `search_id` string, nullable — Unique identifier for this search query, maps to QueryLog objectId in Parse Server

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Rate limit exceeded
- `404` — No relevant items found
- `415` — Unsupported Media Type
- `422` — Validation Error
- `500` — Internal server error

## Changes

- **2025-11-07** `14ff13755871` — 7 breaking, 123 info
  - the `data/anyOf[subschema #1: SearchResult]/nodes/items/properties` response's property type changed from no type to `object` for status `200`
  - the `data/anyOf[subschema #1: SearchResult]/nodes/items/properties` response's property type changed from no type to `object` for status `400`
  - the `data/anyOf[subschema #1: SearchResult]/nodes/items/properties` response's property type changed from no type to `object` for status `401`
  - the `data/anyOf[subschema #1: SearchResult]/nodes/items/properties` response's property type changed from no type to `object` for status `403`
  - …126 more

[Change history](https://skmtc.dev/papr-ai/apis/papr-memory-api/changes/v1/memory/search/post.md)

---

[API](https://skmtc.dev/papr-ai/apis/papr-memory-api.md) · [All operations](https://skmtc.dev/papr-ai/apis/papr-memory-api/llms.txt) · [OpenAPI document](https://skmtc.dev/papr-ai/apis/papr-memory-api/revisions/34b5e739fd20?raw)