AI Infra
Harvest Memories
Automatically extract and store memories from conversation transcripts.
Harvest Memories
The Memory Harvester uses LLM-powered extraction to automatically identify and store memories from conversation transcripts. It detects facts, preferences, experiences, and skills mentioned in a chat and persists them to the Memory Fabric.
Endpoint
POST /api/v1/memory/harvestRequest Body
| Parameter | Type | Required | Description |
|---|---|---|---|
session_id | string | Yes | Session identifier (shared with memory fabric) |
transcript | array | Yes | Conversation transcript — an array of { role, content } message objects (at least one) |
entity_id | string | No | Owner entity for the harvested memories, so they're retrievable across sessions for that entity |
Options Object
| Field | Type | Default | Description |
|---|---|---|---|
enabled | boolean | true | Toggle harvesting on/off |
max_memories | integer | 4 | Maximum memories to extract per run (1-12) |
min_confidence | float | 0.55 | Confidence floor for persisting a memory |
force_reharvest | boolean | false | Ignore cached hashes and force re-extraction |
Examples
from cerebe import AsyncCerebe
client = AsyncCerebe(api_key="ck_live_...")
result = await client.memory.harvest(
session_id="session_abc",
transcript=[
{"role": "user", "content": "I really struggle with fractions"},
{"role": "assistant", "content": "Let me try a visual approach..."},
{"role": "user", "content": "Oh that makes much more sense! I love diagrams"},
],
entity_id="student_456",
)
# The payload is a plain dict on `.data`.
for memory in result.data["harvested_memories"]:
print(f"[{memory['memory_type']}] {memory['summary']}")
print(f" Confidence: {memory['confidence']}")import Cerebe from '@cerebe/sdk'
const client = new Cerebe({ apiKey: 'ck_live_...' })
const result = await client.memory.harvest({
sessionId: 'session_abc',
transcript: [
{ role: 'user', content: 'I really struggle with fractions' },
{ role: 'assistant', content: 'Let me try a visual approach...' },
{ role: 'user', content: 'Oh that makes much more sense! I love diagrams' },
],
entityId: 'student_456',
})
// The payload is on `result.data` (typed `unknown`); narrow it before use.
const { harvested_memories } = result.data as {
harvested_memories: Array<{ memory_type: string; summary: string; confidence: number }>
}
for (const memory of harvested_memories) {
console.log(`[${memory.memory_type}] ${memory.summary}`)
console.log(` Confidence: ${memory.confidence}`)
}curl -X POST https://api.cerebe.ai/api/v1/memory/harvest \
-H "X-API-Key: ck_live_..." \
-H "Content-Type: application/json" \
-d '{
"session_id": "session_abc",
"transcript": [
{"role": "user", "content": "I really struggle with fractions"},
{"role": "assistant", "content": "Let me try a visual approach..."},
{"role": "user", "content": "Oh that makes much more sense! I love diagrams"}
],
"entity_id": "student_456"
}'Response
{
"session_id": "session_abc",
"transcript_hash": "a1b2c3d4e5f6...",
"harvested_memories": [
{
"summary": "Student struggles with fractions",
"memory_type": "episodic",
"importance": 0.7,
"confidence": 0.85,
"source_turn_indices": [0],
"metadata": {}
},
{
"summary": "Student prefers visual/diagram-based explanations",
"memory_type": "semantic",
"importance": 0.9,
"confidence": 0.92,
"source_turn_indices": [1, 2],
"metadata": {}
}
],
"stored_memory_ids": ["mem_x1y2z3", "mem_a4b5c6"],
"duration_ms": 1250.5,
"warnings": [],
"trace_id": "trace_abc123"
}How It Works
- Deduplication — The transcript is hashed. If this exact transcript was already harvested, cached results are returned (unless
force_reharvestis set). - LLM Extraction — An LLM analyzes the transcript and identifies candidate memories with type classification and confidence scores.
- Heuristic Fallback — If the LLM is unavailable, a heuristic extractor identifies high-signal patterns (preferences, struggles, achievements).
- Confidence Filtering — Only memories above
min_confidenceare persisted. - Storage — Accepted memories are stored in the Memory Fabric and become searchable immediately.
Error Responses
| Status | Description |
|---|---|
400 | Invalid request (empty transcript) |
401 | Missing or invalid API key |
500 | Harvest processing failed |
Next Steps
- Store Memory — Manually store individual memories
- Search Memories — Find harvested memories
- Memory Overview — Full guide to the Memory Fabric