CerebeCerebe Docs

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/harvest

Request Body

ParameterTypeRequiredDescription
session_idstringYesSession identifier (shared with memory fabric)
transcriptstringYesConversation transcript as plain text
metadataobjectNoArbitrary key-value metadata (e.g., student_id, domain)

Options Object

FieldTypeDefaultDescription
enabledbooleantrueToggle harvesting on/off
max_memoriesinteger4Maximum memories to extract per run (1-12)
min_confidencefloat0.55Confidence floor for persisting a memory
force_reharvestbooleanfalseIgnore 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="User: I really struggle with fractions\nAssistant: Let me try a visual approach...\nUser: Oh that makes much more sense! I love diagrams",
    metadata={"student_id": "student_456", "domain": "education"},
)

for memory in result.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: 'User: I really struggle with fractions\nAssistant: Let me try a visual approach...\nUser: Oh that makes much more sense! I love diagrams',
  metadata: { studentId: 'student_456', domain: 'education' },
})

for (const memory of result.harvestedMemories) {
  console.log(`[${memory.memoryType}] ${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": "User: I really struggle with fractions\nAssistant: Let me try a visual approach...\nUser: Oh that makes much more sense! I love diagrams",
    "metadata": {
      "student_id": "student_456",
      "domain": "education"
    }
  }'

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

  1. Deduplication — The transcript is hashed. If this exact transcript was already harvested, cached results are returned (unless force_reharvest is set).
  2. LLM Extraction — An LLM analyzes the transcript and identifies candidate memories with type classification and confidence scores.
  3. Heuristic Fallback — If the LLM is unavailable, a heuristic extractor identifies high-signal patterns (preferences, struggles, achievements).
  4. Confidence Filtering — Only memories above min_confidence are persisted.
  5. Storage — Accepted memories are stored in the Memory Fabric and become searchable immediately.

Error Responses

StatusDescription
400Invalid request (empty transcript)
401Missing or invalid API key
500Harvest processing failed

Next Steps

On this page