Search Endpoint
The search endpoint provides semantic search across all memory types using vector similarity.
Search Memories
Perform semantic search across an agent’s memories.
Authorization: Bearer sk-your-api-key
Content-Type: application/json
Request Body
{
"agent_id": "claire",
"query": "performance optimization techniques",
"limit": 10,
"types": ["episodes", "beliefs", "notes"],
"min_score": 0.5
}
| Field | Type | Default | Description |
|---|
agent_id | string | Required | Agent identifier |
query | string | Required | Search query text |
limit | integer | 10 | Maximum results to return |
types | array | all | Memory types to search |
min_score | float | 0.0 | Minimum similarity score (0-1) |
Response
{
"success": true,
"data": {
"results": [
{
"type": "episode",
"id": "ep_abc123",
"score": 0.92,
"content": {
"objective": "Optimized database queries",
"outcome": "Reduced latency by 60%",
"lessons": ["Index frequently queried columns"]
},
"created_at": "2024-01-10T15:30:00Z"
},
{
"type": "belief",
"id": "bel_def456",
"score": 0.87,
"content": {
"statement": "Premature optimization is the root of all evil",
"confidence": 0.75
},
"created_at": "2024-01-05T10:00:00Z"
},
{
"type": "note",
"id": "note_ghi789",
"score": 0.81,
"content": {
"content": "Caching reduces database load significantly",
"note_type": "insight"
},
"created_at": "2024-01-12T09:15:00Z"
}
],
"total": 3,
"query_time_ms": 45
}
}
CLI Equivalent
kernle -a claire search "performance optimization techniques" --limit 10
Searchable Memory Types
| Type | What’s Indexed |
|---|
episodes | Objective, outcome, lessons |
beliefs | Statement |
notes | Content |
agent_values | Name, statement |
goals | Title, description |
playbooks | Name, description, steps |
raw_entries | Content |
relationships | Entity name, notes |
Search Modes
Hybrid Search (Default)
Combines vector similarity with keyword matching for best results:
{
"agent_id": "claire",
"query": "API rate limiting",
"mode": "hybrid"
}
Vector Only
Pure semantic similarity search:
{
"agent_id": "claire",
"query": "API rate limiting",
"mode": "vector"
}
Keyword Only
Traditional text search:
{
"agent_id": "claire",
"query": "API rate limiting",
"mode": "keyword"
}
Filtered Search
By Memory Type
{
"agent_id": "claire",
"query": "debugging techniques",
"types": ["episodes"]
}
By Time Range
{
"agent_id": "claire",
"query": "debugging",
"created_after": "2024-01-01T00:00:00Z",
"created_before": "2024-01-31T23:59:59Z"
}
{
"agent_id": "claire",
"query": "debugging",
"tags": ["production", "urgent"]
}
Search Quality
Search quality depends on:
- Embedding model: Kernle uses modern embedding models for semantic understanding
- Memory quality: Well-written lessons and descriptions improve search
- Query clarity: Specific queries return better results than vague ones
For best results, write clear, descriptive content when recording memories. “Fixed the bug” is less searchable than “Resolved race condition in async queue handler”.
Local vs Cloud Search
| Feature | Local | Cloud |
|---|
| Speed | ~10ms | ~50-100ms |
| Quality | Text matching | Vector similarity |
| Offline | ✓ | — |
| Cross-device | — | ✓ |
# Uses cloud if available, local otherwise
kernle -a claire search "query"
