Elephantasm

SDK Documentation

Give your AI agents persistent, evolving memory across sessions.

v0.1.0Python
PyPIGitHubGet API Key

Installation

pip install elephantasm

Quick Start

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")

Configuration

Set these environment variables:

VariableRequiredDescription
ELEPHANTASM_API_KEYYesYour API key (starts with sk_live_)
ELEPHANTASM_ANIMA_IDNoDefault anima ID for operations
ELEPHANTASM_ENDPOINTNoAPI endpoint (default: https://api.elephantasm.com)
ELEPHANTASM_TIMEOUTNoRequest timeout in seconds (default: 30)

Core Concepts

inject()

Retrieves a compiled MemoryPack containing relevant memories, knowledge, and identity context. Use .as_prompt() to inject into your LLM system prompt.

extract()

Captures events (messages, tool calls, etc.) for memory synthesis. Events are processed by the Dreamer to form memories, lessons, and knowledge over time.

Anima

Your agent entity. Each anima has its own memories, events, knowledge, and identity. Create multiple animas for different agents or users.

MemoryPack

A compiled bundle of session memories, long-term memories, knowledge, and identity context optimized for your token budget.

Explicit Client

For more control, use the Elephantasm 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")

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 events

Error Handling

from elephantasm import inject
from elephantasm.exceptions import (
    AuthenticationError,  # 401 - Invalid API key
    NotFoundError,        # 404 - Anima not found
    RateLimitError,       # 429 - Too many requests
    ValidationError,      # 422 - Invalid parameters
    ServerError,          # 5xx - Server error
)

try:
    pack = inject()
except AuthenticationError:
    print("Check your ELEPHANTASM_API_KEY")
except NotFoundError:
    print("Anima not found - check ELEPHANTASM_ANIMA_ID")
except RateLimitError:
    print("Rate limited - retry later")

Examples

See the examples directory for complete integration patterns:

Getting an API Key

To use the SDK, you need an API key from your Elephantasm dashboard:

  1. Sign up or log in to your account
  2. Navigate to Settings → API Keys
  3. Click "Create API Key"
  4. Copy your key (it starts with sk_live_)
  5. Set it as ELEPHANTASM_API_KEY in your environment

Questions? Open an issue on GitHub or reach out on X: @elephantasm_ai