Python: Types — Elephantasm Docs

Complete reference for all Pydantic models and enums in the Elephantasm Python SDK.

All types are importable from the top-level package:

from elephantasm import Anima, Event, EventType, Memory, MemoryPack, MemoryState

Or from the types module directly:

from elephantasm.types import ScoredMemory, ScoredKnowledge, TemporalContext, IdentityContext

Enums

EventType

Event classification for message capture. Used as the first argument to extract().

from elephantasm import EventType

Value	String	Description
`EventType.MESSAGE_IN`	`"message.in"`	User messages received by the agent
`EventType.MESSAGE_OUT`	`"message.out"`	Assistant responses generated by the agent
`EventType.TOOL_CALL`	`"tool.call"`	Tool/function invocations
`EventType.TOOL_RESULT`	`"tool.result"`	Tool/function return values
`EventType.SYSTEM`	`"system"`	System-level events and signals

MemoryState

Lifecycle states for memory recall and curation.

Value	String	Description
`MemoryState.ACTIVE`	`"active"`	Currently relevant, included in recall
`MemoryState.DECAYING`	`"decaying"`	Losing relevance, deprioritized in recall
`MemoryState.ARCHIVED`	`"archived"`	No longer active, preserved for provenance

Core Models

Anima

Agent entity that owns memories and events. Returned by create_anima().

Name	Type	Required	Description
id	UUID	required	Unique identifier.
name	str	required	Human-readable name.
description	str \| None	optional	Optional description.
meta	dict \| None	optional	Arbitrary metadata.
user_id	UUID \| None	optional	Owning user ID (set by the server).
created_at	datetime	required	Creation timestamp.
updated_at	datetime	required	Last update timestamp.

AnimaCreate

Request model for creating an anima. Used internally by the client.

Name	Type	Required	Description
name	str	required	Name for the anima (max 255 characters).
description	str \| None	optional	Optional description.
meta	dict \| None	optional	Optional metadata dictionary.

Event

Atomic unit of experience — a single captured interaction. Returned by extract().

Name	Type	Required	Description
id	UUID	required	Unique identifier.
anima_id	UUID	required	Owning anima ID.
event_type	str	required	Event type string (e.g. 'message.in').
role	str \| None	optional	Message role: user, assistant, system, tool.
author	str \| None	optional	Who produced this event.
summary	str \| None	optional	Server-generated summary (if applicable).
content	str	required	Event content body.
occurred_at	datetime \| None	optional	When the event actually happened.
session_id	str \| None	optional	Session grouping identifier.
meta	dict	required	Metadata dictionary (default: {}).
source_uri	str \| None	optional	Source system identifier.
dedupe_key	str \| None	optional	Deduplication hash (auto-generated).
importance_score	float \| None	optional	Curation priority hint, 0.0–1.0.
created_at	datetime	required	Ingestion timestamp.
updated_at	datetime	required	Last update timestamp.

EventCreate

Request model for creating an event. Used internally by the client.

Name	Type	Required	Description
anima_id	UUID	required	Target anima ID.
event_type	str	required	Event type string.
content	str	required	Event content body.
role	str \| None	optional	Message role.
author	str \| None	optional	Event author.
summary	str \| None	optional	Optional summary.
occurred_at	datetime \| None	optional	Override timestamp.
session_id	str \| None	optional	Session identifier.
meta	dict	required	Metadata (default: {}).
source_uri	str \| None	optional	Source system URI.
dedupe_key	str \| None	optional	Custom deduplication key.
importance_score	float \| None	optional	Importance hint, validated 0.0–1.0.

Memory

Subjective interpretation synthesized from one or more events.

Name	Type	Required	Description
id	UUID	required	Unique identifier.
anima_id	UUID	required	Owning anima ID.
content	str \| None	optional	Full memory content.
summary	str \| None	optional	Compact narrative essence.
importance	float \| None	optional	Recall priority, 0.0–1.0.
confidence	float \| None	optional	Stability/certainty, 0.0–1.0.
state	MemoryState \| None	optional	Lifecycle state: active, decaying, or archived.
recency_score	float \| None	optional	Cached recency score.
decay_score	float \| None	optional	Cached decay score.
time_start	datetime \| None	optional	Start of event timespan covered.
time_end	datetime \| None	optional	End of event timespan covered.
meta	dict	required	Metadata dictionary (default: {}).
created_at	datetime	required	Creation timestamp.
updated_at	datetime	required	Last update timestamp.

Pack Models

MemoryPack

Compiled memory context for LLM injection. Returned by inject().

Name	Type	Required	Description
id	UUID	required	Pack identifier.
anima_id	UUID	required	Owning anima ID.
query	str \| None	optional	Semantic query used for compilation (if any).
preset_name	str \| None	optional	Preset used for compilation.
session_memory_count	int	required	Number of session memories included.
knowledge_count	int	required	Number of knowledge items included.
long_term_memory_count	int	required	Number of long-term memories included.
has_identity	bool	required	Whether identity context is included.
token_count	int	required	Estimated token count of the pack.
max_tokens	int	required	Token budget used for compilation (default: 4000).
content	dict	required	Raw pack content with all layers.
compiled_at	datetime	required	When the pack was compiled.
created_at	datetime	required	Creation timestamp.

Methods

`as_prompt() -> str`

Returns the pre-formatted context string ready for LLM system prompt injection.

pack = client.inject()
if pack:
    prompt = pack.as_prompt()
    # Use prompt in your LLM call's system message

Properties

Access individual pack layers as typed objects:

pack = client.inject()
if pack:
    # Identity context
    identity = pack.identity           # IdentityContext | None
 
    # Session memories (recent, high-scoring)
    for mem in pack.session_memories:  # list[ScoredMemory]
        print(f"{mem.summary} (score: {mem.score})")
 
    # Knowledge items
    for k in pack.knowledge:           # list[ScoredKnowledge]
        print(f"{k.type}: {k.content}")
 
    # Long-term memories
    for mem in pack.long_term_memories:  # list[ScoredMemory]
        print(mem.summary)
 
    # Temporal awareness
    temporal = pack.temporal_context    # TemporalContext | None
    if temporal:
        print(temporal.formatted)

Property	Return Type	Description
`identity`	`IdentityContext \| None`	Agent personality and behavioral context
`session_memories`	`list[ScoredMemory]`	Recent scored memories from current session
`knowledge`	`list[ScoredKnowledge]`	Canonicalized knowledge items
`long_term_memories`	`list[ScoredMemory]`	Scored long-term memories
`temporal_context`	`TemporalContext \| None`	Time gap awareness context

ScoredMemory

Memory with scoring breakdown from pack compilation.

Name	Type	Required	Description
id	UUID	required	Memory identifier.
summary	str \| None	optional	Compact narrative summary.
score	float	required	Composite recall score.
reason	str \| None	optional	Human-readable scoring explanation.
breakdown	dict[str, float]	required	Per-factor score breakdown (importance, recency, etc.).
similarity	float \| None	optional	Semantic similarity score (if query-based retrieval).

ScoredKnowledge

Knowledge item with similarity score from pack compilation.

Name	Type	Required	Description
id	UUID	required	Knowledge identifier.
content	str	required	Knowledge content text.
type	str	required	Knowledge type classification.
score	float	required	Relevance score.
similarity	float \| None	optional	Semantic similarity score (if query-based).

TemporalContext

Temporal awareness context for bridging gaps between sessions.

Name	Type	Required	Description
last_event_at	datetime	required	Timestamp of the most recent event.
hours_ago	float	required	Hours since the last event.
memory_summary	str \| None	optional	Natural language summary of what happened last.
formatted	str	required	Pre-formatted temporal context string.

IdentityContext

Agent identity layer from pack compilation.

Name	Type	Required	Description
personality_type	str \| None	optional	Personality classification (e.g. MBTI type).
communication_style	str \| None	optional	Preferred communication approach.
self_reflection	dict \| None	optional	Anima's self-reflection data.
prose	str \| None	optional	Natural language identity description (~70–100 tokens).