Python: Client — Elephantasm Docs

Complete reference for the Elephantasm Python client class and module-level convenience functions.

Elephantasm Class

The main client for interacting with the Elephantasm API. Handles authentication, request lifecycle, and response parsing.

from elephantasm import Elephantasm
 
client = Elephantasm(
    api_key="sk_live_...",
    anima_id="your-anima-id",
)

Constructor Parameters

Name	Type	Required	Description
api_key	str \| None	optional	API key for authentication. Falls back to ELEPHANTASM_API_KEY env var.
anima_id	str \| None	optional	Default anima ID for all operations. Falls back to ELEPHANTASM_ANIMA_ID.
endpoint	str \| None	optional	API base URL. Falls back to ELEPHANTASM_ENDPOINT. Default: https://api.elephantasm.com
timeout	int \| None	optional	Request timeout in seconds. Falls back to ELEPHANTASM_TIMEOUT. Default: 30

A ValueError is raised if no API key is provided and ELEPHANTASM_API_KEY is not set.

inject()

Retrieve the latest compiled memory pack for LLM context injection.

pack = client.inject()
if pack:
    system_prompt = f"You are a helpful assistant.\n\n{pack.as_prompt()}"

Parameters

Name	Type	Required	Description
anima_id	str \| UUID \| None	optional	Override the client's default anima ID for this call.
query	str \| None	optional	Semantic search query to influence memory retrieval.
preset	str \| None	optional	Pack compilation preset: 'conversational' or 'self_determined'.

Returns

MemoryPack if a pack exists, None otherwise.

Use .as_prompt() to get the pre-formatted context string, or access individual layers via properties like .session_memories, .knowledge, .identity.

extract()

Capture an event (message, tool call, system signal) for memory synthesis.

from elephantasm import Elephantasm, EventType
 
client = Elephantasm(api_key="sk_live_...", anima_id="...")
 
# Basic capture
client.extract(EventType.MESSAGE_IN, "What's the weather?", role="user")
 
# With full options
client.extract(
    EventType.MESSAGE_OUT,
    "It's 72°F and sunny.",
    role="assistant",
    author="weather-agent",
    session_id="conv-123",
    meta={"confidence": 0.95},
    importance_score=0.7,
)

Parameters

Name	Type	Required	Description
event_type	str \| EventType	required	Type of event: MESSAGE_IN, MESSAGE_OUT, TOOL_CALL, TOOL_RESULT, or SYSTEM.
content	str	required	Event content — message text, tool output, system signal, etc.
anima_id	str \| UUID \| None	optional	Override the client's default anima ID for this call.
session_id	str \| None	optional	Group related events by conversation or task.
role	str \| None	optional	Message role: user, assistant, system, or tool.
author	str \| None	optional	Identifier for who produced this event (username, model name, tool name).
occurred_at	datetime \| None	optional	When the event actually happened. Defaults to now.
meta	dict \| None	optional	Arbitrary metadata dictionary attached to the event.
importance_score	float \| None	optional	Priority hint for curation, 0.0–1.0.

Returns

Event — the created event object.

create_anima()

Create a new anima (agent entity) that owns memories and events.

anima = client.create_anima("my-agent", description="Customer support bot")
print(anima.id)  # Use this ID for inject() and extract()

Parameters

Name	Type	Required	Description
name	str	required	Human-readable name for the anima (max 255 chars).
description	str \| None	optional	Optional description of the anima's purpose.
meta	dict \| None	optional	Optional metadata dictionary.

Returns

Anima — the created anima object.

close()

Close the underlying HTTP client and release resources.

client.close()

Called automatically when using the context manager pattern.

Context Manager

The client supports Python's with statement for automatic cleanup:

from elephantasm import Elephantasm
 
with Elephantasm(api_key="sk_live_...") as client:
    client.extract(EventType.MESSAGE_IN, "Hello!", role="user")
    pack = client.inject()
# client.close() called automatically

Module-Level Functions

For simpler usage, the SDK exports top-level functions that use a shared client configured from environment variables. The client is lazily created on first call.

from elephantasm import inject, extract, create_anima, EventType
 
# No client instantiation needed — reads ELEPHANTASM_API_KEY and ELEPHANTASM_ANIMA_ID from env
extract(EventType.MESSAGE_IN, "Hello!", role="user")
pack = inject()

Module-level functions create a shared client on first call using environment variables. See Environment Variables for setup.

The functions have identical signatures to the class methods:

create_anima(name, description=None, meta=None) → Anima
inject(anima_id=None, query=None, preset=None) → MemoryPack | None
extract(event_type, content, anima_id=None, session_id=None, role=None, author=None, occurred_at=None, meta=None, importance_score=None) → Event

See the method sections above for full parameter details.