Introduction

What is Elephantasm?

Elephantasm is a Long-Term Agentic Memory (LTAM) framework. It gives AI agents continuity beyond the context window — structured memory that persists, curates, and evolves across conversations.

Unlike simple RAG systems that retrieve nearest-neighbor chunks from a vector store, Elephantasm builds a layered cognitive substrate:

Events — Raw interactions (messages, tool calls, API responses)
Memories — Structured reflections synthesized from events
Knowledge — Canonicalized truths extracted from memory patterns
Identity — Emergent behavioral fingerprint

Elephantasm works with any LLM provider — OpenAI, Anthropic, local models. The SDKs handle event capture and retrieval; you keep full control of your agent logic.

How It Works

The core loop is simple:

Extract — Capture events (conversations, tool calls) into Elephantasm
Synthesize — The system creates structured memories from raw events
Inject — Retrieve a deterministic memory pack to enrich your agent's context

from elephantasm import inject, extract, EventType

# Capture a conversation event
extract(EventType.MESSAGE_IN, "User asked about deployment", anima_id="agent-01")

# Get memory context for your next prompt
pack = inject(anima_id="agent-01")
if pack:
  print(pack.as_prompt())

Complete Integration Example

A typical agent integration — inject context before your LLM call, extract events during and after:

from elephantasm import inject, extract, EventType

# Before your agent loop — retrieve accumulated memories
pack = inject(anima_id="my-agent")
system_prompt = f"You are helpful.\n\n{pack.as_prompt()}" if pack else "You are helpful."

# During the agent loop — capture key events
extract(EventType.MESSAGE_IN, "User asked about deployment", anima_id="my-agent", session_id="run-123", role="user")
extract(EventType.TOOL_CALL, "Called search API, got 15 results", anima_id="my-agent", session_id="run-123", importance_score=0.5)

# After completion — capture the summary (highest importance)
extract(EventType.MESSAGE_OUT, "Deployed to prod in 45s.", anima_id="my-agent", session_id="run-123", role="assistant", importance_score=0.9)

`extract()` Signature

The full set of parameters available when capturing events:

extract(
  event_type,          # str | EventType — MESSAGE_IN, MESSAGE_OUT, TOOL_CALL, TOOL_RESULT, SYSTEM
  content,             # str — the event content
  anima_id=None,       # str | UUID — falls back to ELEPHANTASM_ANIMA_ID env var
  session_id=None,     # str — groups events within a conversation/run
  role=None,           # str — e.g. "user", "assistant"
  author=None,         # str — agent or human name
  occurred_at=None,    # datetime — defaults to now
  meta=None,           # dict — arbitrary metadata
  importance_score=None  # float — 0.0 to 1.0, influences memory synthesis
)

Key Features

Deterministic retrieval — Memory packs are assembled via scoring algorithms, not just vector similarity
Four-factor recall — Importance, confidence, recency, and decay govern what surfaces
Full provenance — Every memory links back to its source events
Background curation — The Dreamer loop merges, archives, and promotes memories automatically
Multi-language SDKs — Python and TypeScript clients with identical APIs

Next Steps