Embeddings Endpoints
Endpoints for generating and managing vector embeddings for memory search.
How Embeddings Work
Kernle converts text memories into vector embeddings for semantic search:
- When you create a memory, its text content is embedded
- Embeddings are stored alongside the memory
- Search queries are embedded and compared via cosine similarity
Embeddings are generated automatically when you create memories. These endpoints are for advanced use cases.
Generate Embedding
Generate an embedding vector for arbitrary text.
POST /embeddings/generate
Authorization: Bearer sk-your-api-key
Content-Type: application/json
Request Body
{
"text": "How to debug production API issues effectively",
"model": "default"
}
| Field | Type | Default | Description |
|---|
text | string | Required | Text to embed |
model | string | ”default” | Embedding model to use |
Response
{
"success": true,
"data": {
"embedding": [0.023, -0.156, 0.089, ...],
"dimensions": 1536,
"model": "text-embedding-3-small",
"tokens_used": 12
}
}
Batch Generate Embeddings
Generate embeddings for multiple texts in one request.
Authorization: Bearer sk-your-api-key
Content-Type: application/json
Request Body
{
"texts": [
"First piece of text to embed",
"Second piece of text to embed",
"Third piece of text to embed"
],
"model": "default"
}
Response
{
"success": true,
"data": {
"embeddings": [
[0.023, -0.156, ...],
[0.089, 0.234, ...],
[-0.045, 0.167, ...]
],
"dimensions": 1536,
"model": "text-embedding-3-small",
"total_tokens_used": 36
}
}
Re-embed Memory
Regenerate the embedding for an existing memory.
Authorization: Bearer sk-your-api-key
Content-Type: application/json
Request Body
{
"agent_id": "claire",
"memory_type": "episode",
"memory_id": "ep_abc123"
}
Response
{
"success": true,
"data": {
"memory_type": "episode",
"memory_id": "ep_abc123",
"previous_model": "text-embedding-ada-002",
"new_model": "text-embedding-3-small",
"reembedded_at": "2024-01-15T10:30:00Z"
}
}
Bulk Re-embed
Regenerate embeddings for all memories of an agent.
This operation can take several minutes for agents with many memories. It runs asynchronously.
POST /embeddings/bulk-reembed
Authorization: Bearer sk-your-api-key
Content-Type: application/json
Request Body
{
"agent_id": "claire",
"types": ["episodes", "beliefs", "notes"],
"model": "text-embedding-3-small"
}
Response
{
"success": true,
"data": {
"job_id": "job_xyz789",
"status": "queued",
"estimated_memories": 156,
"estimated_time_seconds": 45
}
}
Check Job Status
GET /embeddings/jobs/{job_id}
{
"success": true,
"data": {
"job_id": "job_xyz789",
"status": "completed",
"memories_processed": 156,
"started_at": "2024-01-15T10:30:00Z",
"completed_at": "2024-01-15T10:30:45Z"
}
}
Embedding Models
| Model | Dimensions | Quality | Speed | Cost |
|---|
text-embedding-3-small | 1536 | Good | Fast | Low |
text-embedding-3-large | 3072 | Best | Medium | Medium |
text-embedding-ada-002 | 1536 | Good | Fast | Low |
text-embedding-3-small
Similarity Search
Find memories similar to a given embedding vector.
Request Body
{
"agent_id": "claire",
"embedding": [0.023, -0.156, 0.089, ...],
"limit": 10,
"min_score": 0.7,
"types": ["episodes", "beliefs"]
}
Response
{
"success": true,
"data": {
"results": [
{
"type": "episode",
"id": "ep_abc123",
"score": 0.94,
"content": { ... }
}
]
}
}
For most use cases, use the /search endpoint instead — it handles embedding generation automatically.
Local Embeddings
For local-only usage without the cloud API, Kernle can generate embeddings locally using:
- sqlite-vec: Fast local vector search
- Sentence Transformers: Local embedding models (optional)
Configure local embeddings in ~/.kernle/config.json:
{
"embeddings": {
"provider": "local",
"model": "all-MiniLM-L6-v2"
}
}
