initial_docs/docs/MEMORY_AND_EVENTS.md

# Memory and Events

## Event log

Recent events come from the simulation, not from the LLM.

Every meaningful state transition should emit an event.

Event sources:

- map generation,
- object placement,
- object compiler acceptance,
- user movement,
- user speech,
- creature movement,
- creature inspection,
- creature consumption,
- resource changes above threshold,
- fear spike,
- health loss,
- entering shelter,
- failed action,
- repeated action loop,
- slow cognition output,
- memory update,
- belief update.

Event schema:

```json
{
  "id": "evt_123",
  "tick": 145,
  "type": "consume | inspect | notice | fear_spike | user_speech | memory_update | belief_update | rest | move | failed_action",
  "actor": "creature | user | system | slow_cognition",
  "target_id": "obj_17",
  "position": [12, 7],
  "summary": "creature stopped before consuming hot sweet fruit",
  "state_delta": {
    "hunger": -0.12,
    "fear": 0.08
  },
  "source": "action_resolver | world_update | user_input | slow_cognition"
}
```

Keep:

- full event log for export,
- recent event ring buffer for UI,
- compact event summary for slow cognition.

## Recent events

`recent_events` are generated by selecting and summarizing the event log.

Slow cognition should receive only compact recent events, for example the last 8–20 relevant entries.

Do not let the LLM invent recent events. It may summarize or interpret them, but the source is the event log.

## Object memory

Object memory stores what the creature has learned.

Use both object-specific and signature-level memory.

Object-specific memory:

```json
{
  "object_id": "obj_17",
  "familiarity": 0.22,
  "valence": -0.08,
  "last_seen_tick": 145,
  "last_interaction_tick": 138,
  "interaction_counts": {
    "noticed": 2,
    "inspected": 1,
    "consumed": 0,
    "avoided": 1
  },
  "associations": {
    "food": 0.30,
    "heat_risk": 0.25,
    "safety": 0.0,
    "harm": 0.05,
    "shelter": 0.0,
    "user_related": 0.0
  }
}
```

Signature-level memory:

```json
{
  "signature": "visual:red|smell:sweet|touch:hot",
  "familiarity": 0.18,
  "valence": -0.05,
  "associations": {
    "food": 0.20,
    "heat_risk": 0.18
  }
}
```

Use signature-level memory so the creature can generalize:

- red + sweet + hot,
- shiny + sound,
- dark + home smell,
- bitter + energy.

## What is `memory_valence`?

`memory_valence` is a scalar summary of past outcomes for an object or object signature.

Range:

```text
-1.0 to 1.0
```

Meaning:

- negative: previous interactions were harmful, frightening, uncomfortable, or failed,
- positive: previous interactions were useful, safe, nourishing, comforting, or socially positive,
- near zero: unknown or mixed.

Where it exists:

- stored in `CreatureMemory.object_memory[object_id].valence`,
- stored in `CreatureMemory.signature_memory[signature].valence`,
- copied into percept/appraisal summaries as `memory_valence`.

How it is generated:

1. Event-based deterministic update.
2. Optional slow cognition adjustment within bounded deltas.

Example deterministic update:

```text
valence_delta =
  +0.40 * hunger_reduction
  +0.25 * thirst_reduction
  +0.20 * comfort_gain
  +0.10 * energy_gain
  -0.50 * fear_spike
  -0.70 * health_loss
  -0.30 * temperature_stress
  -0.15 * repeated_failed_action
```

Clamp after update:

```text
valence = clamp(valence + valence_delta, -1.0, 1.0)
```

Slow cognition may propose:

```json
{
  "target": "signature:visual:red|smell:sweet|touch:hot",
  "valence_delta": -0.04,
  "reason": "approach caused heat/fear conflict"
}
```

But the simulation must validate and clamp this. The LLM cannot set arbitrary memory values.

## Rolling memory text

The creature also has a small text memory:

```json
{
  "rolling_memory_text": "Red-sweet warmth made the body stop. User voice sometimes means food, sometimes danger."
}
```

Limit:

```text
1000 characters
```

How it updates:

- slow cognition returns `memory_append`,
- append to the end,
- trim oldest text if over 1000 characters,
- never use it as the only memory store.

Why it exists:

- gives slow cognition continuity,
- makes thoughts more creature-like,
- supports the demo visually.

Structured memory remains the source of behavioral scoring.

## Beliefs

Beliefs are semi-structured hypotheses.

Example:

```json
{
  "id": "belief_07",
  "text": "blue stones may precede food",
  "confidence": 0.22,
  "evidence_event_ids": ["evt_41", "evt_44"],
  "trait_filters": {
    "visual_words": ["blue"],
    "object_types": ["stone"]
  },
  "behavioral_effect": {
    "inspect_bias": 0.06,
    "seek_bias": 0.02
  },
  "last_updated_tick": 144
}
```

Beliefs should be weak and interpretable.

They may influence attention, inspection, and mild approach/avoidance. They must not override urgent survival.

## Social memory

Store user-related memory.

Example:

```json
{
  "entity_id": "user",
  "trust": 0.42,
  "familiarity": 0.35,
  "valence": 0.12,
  "recent_speech": ["come here", "food here"],
  "associations": {
    "food_after_call": 0.2,
    "danger_after_call": 0.1,
    "shelter_near_user": 0.0
  }
}
```

User speech should change memory only through outcomes.

If the user says “come here” and food is found near the user, trust may rise.

If the user says “come here” and the path causes harm/fear, trust may fall.