What is an Event?
An Event is an atomic unit of experience — a single interaction, signal, or observation captured from your agent. Events are the raw material from which memories are synthesized.
Every message your agent sends or receives, every tool call it makes, every system signal — these are all events.
Event Types
from elephantasm import EventType
EventType.MESSAGE_IN # User messages
EventType.MESSAGE_OUT # Assistant responses
EventType.TOOL_CALL # Tool invocations
EventType.TOOL_RESULT # Tool outputs
EventType.SYSTEM # System eventsCapturing Events
Use extract() to send events to Elephantasm:
from elephantasm import extract, EventType
# Basic capture
extract(EventType.MESSAGE_IN, "What's the weather?", role="user")
# With full options
extract(
EventType.MESSAGE_OUT,
"It's 72°F and sunny in San Francisco.",
role="assistant",
author="weather-agent",
session_id="conv-123",
meta={"confidence": 0.95},
importance_score=0.7,
)Extract Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| event_type | EventType | required | Type of event (MESSAGE_IN, MESSAGE_OUT, TOOL_CALL, TOOL_RESULT, SYSTEM) |
| content | string | required | The event content (message text, tool call details, etc.) |
| anima_id | string | optional | Override the default anima for this event |
| session_id | string | optional | Group related events by conversation or task |
| role | string | optional | Message role: user, assistant, system, or tool |
| author | string | optional | Identifier for the agent or entity that produced this event |
| occurred_at | datetime | optional | Override the timestamp (defaults to now) |
| meta | object | optional | Arbitrary metadata attached to the event |
| importance_score | float | optional | Priority hint for curation (0.0–1.0) |
Key Fields Explained
session_id
- Stored with events for filtering and querying
- Not used in synthesis (synthesis is per-Anima, not per-session)
- Useful for grouping events by conversation, task, or workflow
author
- Included in the synthesis prompt — the Dreamer sees who said what
- Critical for multi-agent systems where concurrent agents share an Anima
- Format in synthesis:
[1] timestamp | role (author): content
importance_score
- A hint to the curation system (0.0 = low, 1.0 = high)
- Higher-importance events are more likely to be synthesized into memories
- Optional — the system assigns scores if omitted
Deduplication
Events are automatically deduplicated using a hash of spirit_id + event_type + content + occurred_at + source_uri. Safe to retry failed extract() calls without creating duplicates.
Capture generously. The Dreamer's curation loop handles filtering noise — it's better to over-capture than miss important interactions.