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.