Quick Start — Elephantasm Docs

First-Time Setup

Get an API key — Sign up at elephantasm.com, go to Settings → API Keys, and create a key (starts with sk_live_)
Set environment variables:

export ELEPHANTASM_API_KEY=sk_live_...
export ELEPHANTASM_ANIMA_ID=your-anima-id   # optional — can pass explicitly

Create your first Anima (or use the dashboard):

from elephantasm import create_anima
anima = create_anima("my-agent", description="My first agent")
print(anima.id)  # use this as your anima_id

extract() does not auto-create an Anima. You must create one first via create_anima(), the dashboard, or the REST API.

The Two Core Operations

Elephantasm has two primary SDK functions:

extract() — Capture events (messages, tool calls) for memory synthesis
inject() — Retrieve a compiled memory pack for your LLM's context

Minimal Example

from elephantasm import inject, extract, EventType

# Get memory context for your LLM
pack = inject()
system_prompt = f"You are a helpful assistant.\n\n{pack.as_prompt()}"

# Capture conversation events
extract(EventType.MESSAGE_IN, "Hello!", role="user")
extract(EventType.MESSAGE_OUT, "Hi there!", role="assistant")

The module-level functions (inject, extract) read ELEPHANTASM_API_KEY and ELEPHANTASM_ANIMA_ID from environment variables automatically.

Async Usage

The Python SDK makes synchronous HTTP calls. In async contexts (FastAPI, Django async), wrap calls to avoid blocking the event loop:

import asyncio
from elephantasm import inject, extract, EventType

# Wrap in asyncio.to_thread()
pack = await asyncio.to_thread(inject, anima_id="my-agent")
await asyncio.to_thread(extract, EventType.MESSAGE_IN, "Hello!", anima_id="my-agent")

Using the Explicit Client

For more control — multiple animas, custom endpoints, or dependency injection — use the client class directly:

from elephantasm import Elephantasm, EventType

# Initialize with credentials
with Elephantasm(api_key="sk_live_...", anima_id="...") as client:
  # Get memory pack
  pack = client.inject()

  # Capture events
  client.extract(EventType.MESSAGE_IN, "Hello!", role="user")

  # Create a new anima
  anima = client.create_anima("my-agent", description="Personal assistant")

Full Chat Example

A complete chat function with memory injection:

from elephantasm import inject, extract, EventType

def chat(user_message: str) -> str:
  # Get memory context
  pack = inject()

  # Build prompt with memory
  messages = [
      {"role": "system", "content": f"You are a helpful assistant.\n\n{pack.as_prompt()}"},
      {"role": "user", "content": user_message}
  ]

  # Call your LLM
  response = openai.chat.completions.create(model="gpt-4", messages=messages)
  assistant_message = response.choices[0].message.content

  # Capture both sides of conversation
  extract(EventType.MESSAGE_IN, user_message, role="user")
  extract(EventType.MESSAGE_OUT, assistant_message, role="assistant")

  return assistant_message

What Happens Next

Once you extract events, the Dreamer background process automatically:

Synthesizes events into structured memories
Extracts knowledge from memory patterns
Builds an identity fingerprint over time

The next time you call inject(), these curated layers are compiled into a deterministic memory pack for your agent's context.

Top-Level Exports

Everything importable from the SDK at a glance:

from elephantasm import (
  Elephantasm,        # Client class (explicit credentials)
  inject,             # Module-level: retrieve memory pack
  extract,            # Module-level: capture event
  create_anima,       # Module-level: create agent entity
  EventType,          # Enum: MESSAGE_IN, MESSAGE_OUT, TOOL_CALL, TOOL_RESULT, SYSTEM
  # Types
  Anima, Event, Memory, MemoryPack, MemoryState,
  ScoredMemory, ScoredKnowledge, TemporalContext, IdentityContext,
  # Exceptions
  ElephantasmError, AuthenticationError, NotFoundError,
  RateLimitError, ValidationError, ServerError,
)

Error Handling

The SDK raises typed exceptions. Default timeout is 30 seconds. No built-in retry — handle retries in your application:

from elephantasm import inject, AuthenticationError, NotFoundError, RateLimitError

try:
  pack = inject(anima_id="my-agent")
except AuthenticationError:
  # Invalid or expired API key (401)
  pass
except NotFoundError:
  # Anima ID doesn't exist (404)
  pass
except RateLimitError as e:
  # Too many requests (429) — check e.retry_after
  pass

See the full Exceptions reference for all error types and fields.

Next Steps

Authentication — Get your API key
Events — Understand event types and capture options
Memory Packs — How inject() builds context