What is an Anima?

An Anima is the root entity in Elephantasm. It represents an agent (or user-specific agent instance) and owns all associated memories, events, knowledge, and identity.

Think of it as a persistent identity container — everything your agent remembers, learns, and becomes is scoped to its Anima.

Key Properties

Creating Animas

from elephantasm import Elephantasm

client = Elephantasm(api_key="sk_live_...")

# Create an anima for your agent
anima = client.create_anima(
  name="research-assistant",
  description="Helps users find and summarize research papers",
  meta={"role": "research", "version": "1.0"}
)

print(f"Anima ID: {anima.id}")

One Anima Per Agent (or Per User)

The most common patterns:

• Single-agent app — One Anima for your assistant. Set ELEPHANTASM_ANIMA_ID and use module-level functions.
• Multi-user app — One Anima per user. Each user gets their own memory space. See Separate Animas pattern.
• Multi-agent system — One shared Anima with author attribution, or separate Animas per agent role. See Integration Patterns.

Default Anima

When using module-level functions (inject(), extract()), the SDK reads ELEPHANTASM_ANIMA_ID from environment variables:

export ELEPHANTASM_ANIMA_ID=your-anima-uuid

When using the explicit client, pass anima_id to the constructor or per-call.

What an Anima Owns

Each Anima has isolated:

• Events — Raw interactions captured via extract()
• Memories — Structured reflections synthesized from events
• Knowledge — Canonicalized truths extracted from memories
• Identity — Emergent behavioral fingerprint
• Memory Packs — Compiled context snapshots returned by inject()