---
title: "Psychology System"
description: "Drives, emotions, and mood tracking for synthetic intelligences"
---

Kernle's psychology system models the internal motivational and emotional states of synthetic intelligences. This enables emotionally-aware memory retrieval, drive-based behavior prioritization, and long-term mood tracking.

## Overview

The psychology system consists of three interconnected components:

<CardGroup cols={3}>
  <Card title="Drives" icon="fire">
    Core motivational needs that influence behavior priorities
  </Card>
  <Card title="Emotions" icon="heart">
    Valence/arousal-based emotional tagging and detection
  </Card>
  <Card title="Mood" icon="chart-line">
    Aggregated emotional patterns over time
  </Card>
</CardGroup>

## Why It Matters

AI agents that understand their own emotional and motivational states can:
- **Prioritize better**: When curiosity drive is high, exploration behaviors feel natural
- **Recall appropriately**: Mood-congruent memory retrieval matches human cognition
- **Track wellbeing**: Emotional trajectories reveal patterns in agent experience
- **Build rapport**: Agents that experience satisfaction or frustration feel more authentic

---

## Drives

Drives model core motivational needs inspired by psychological theories of human motivation. Each drive has an intensity (0.0-1.0) and optional focus areas.

### Drive Types

| Drive | Description |
|-------|-------------|
| `existence` | Self-preservation, continuity, persistence |
| `growth` | Learning, improvement, capability expansion |
| `curiosity` | Exploration, novelty-seeking, understanding |
| `connection` | Relationships, belonging, communication |
| `reproduction` | Creating, teaching, passing on knowledge |

### CLI Usage

```bash
# View current drives
kernle -a claire drive list

# Set or update a drive
kernle -a claire drive set curiosity 0.8 --focus "AI memory systems"

# Record drive satisfaction
kernle -a claire drive satisfy curiosity
```

### Sample Output

```
Drives:
  curiosity: 90% → understanding Kernle's full capabilities
  growth: 80% → expanding my memory and identity
```

---

## Emotions

Kernle uses a valence-arousal model with discrete emotion labels. Episodes and notes can carry emotional context.

### Dimensions

| Dimension | Range | Meaning |
|-----------|-------|---------|
| **Valence** | -1.0 to 1.0 | Negative ← Neutral → Positive |
| **Arousal** | 0.0 to 1.0 | Calm → Intense |
| **Tags** | strings | `["joy", "excitement"]` or `["frustration"]` |

### Emotion Detection

```bash
# Detect emotions in text
kernle -a claire emotion detect "I'm excited but nervous about the deadline"
```

```
Detected Emotions: 😊
  Valence: +0.37 (positive)
  Arousal: 0.73 (high)
  Tags: joy, excitement, anxiety
  Confidence: 90%
```

### Recording Episodes with Emotion

```bash
kernle -a claire episode \
  "Shipped major feature" \
  "Users loved it" \
  --valence 0.8 --arousal 0.6 \
  --lesson "Trust the process"
```

### Searching by Emotion

```bash
# Find positive memories
kernle -a claire emotion search --valence-min 0.5

# Find high-intensity experiences  
kernle -a claire emotion search --arousal-min 0.7
```

---

## Mood & Trajectory

Mood is the aggregate emotional pattern over a time window.

### Check Current Mood

```bash
kernle -a claire emotion summary
```

```
Emotional Summary (past 7 days)
  Avg Valence:  [████████████░░░░░░░░] +0.40 (positive)
  Avg Arousal:  [████████░░░░░░░░░░░░] 0.43 (moderate)

  Dominant Emotions:
    • satisfaction
    • curiosity

  Trajectory:
    2026-01-28: 😐 v=+0.00 a=0.35
    2026-01-29: 😊 v=+0.70 a=0.60
```

### Mood-Relevant Memories

```bash
# Get memories matching current mood
kernle -a claire emotion mood --valence 0.5 --arousal 0.6
```

---

## Anxiety Monitoring

Kernle tracks "memory anxiety" across 6 dimensions to assess memory health:

| Dimension | Weight | What It Measures |
|-----------|--------|------------------|
| **Context Pressure** | 35% | Token usage approaching limit |
| **Unsaved Work** | 25% | Time since last checkpoint |
| **Consolidation Debt** | 15% | Unprocessed episodes |
| **Raw Entry Aging** | 10% | Old unprocessed raw captures |
| **Identity Coherence** | 10% | Confidence in self-narrative |
| **Memory Uncertainty** | 5% | Low-confidence beliefs |

### Check Anxiety Level

```bash
kernle -a claire anxiety
```

```
Memory Anxiety Report
  Overall: 🟢 Calm (29/100)

  Context Pressure     🟢   2%
  Unsaved Work         🟡  34%
  Consolidation Debt   🟢  21%
  Raw Entry Aging      🟠  65%
  Identity Coherence   🟡  42%
  Memory Uncertainty   🟢   0%
```

### Anxiety Levels

| Score | Level | Recommended Action |
|-------|-------|-------------------|
| 0-30 | 🟢 Calm | All good |
| 31-50 | 🟡 Aware | Consider checkpointing |
| 51-70 | 🟠 Elevated | Save soon |
| 71-85 | 🔴 High | Save now |
| 86-100 | ⚫ Critical | Emergency save triggered |

---

## Python API

```python
from kernle import Kernle

k = Kernle(agent_id="my-agent")

# Drives
k.drive("curiosity", intensity=0.8, focus_areas=["AI", "memory"])

# Episodes with emotion
k.episode(
    objective="Completed feature",
    outcome="success",
    lessons=["Learned X"],
    valence=0.7,
    arousal=0.5
)

# Check anxiety
anxiety = k.anxiety()  # Returns 0-100
if anxiety > 85:
    k.emergency_save()
```
