TypeScript: Types — Elephantasm Docs

Complete reference for all interfaces and type aliases in the Elephantasm TypeScript SDK.

All types are importable from the package:

import type {
  Anima, AnimaCreate, Event, EventCreate, EventType,
  Memory, MemoryState, MemoryPack, MemoryPackContent,
  ScoredMemory, ScoredKnowledge, TemporalContext, IdentityContext,
  ElephantasmConfig, ExtractOptions, InjectOptions,
} from "@elephantasm/client";

Type Aliases

EventType

Event classification for message capture. Used as the first argument to extract().

type EventType = "message.in" | "message.out" | "tool.call" | "tool.result" | "system";

Value	Description
`"message.in"`	User messages received by the agent
`"message.out"`	Assistant responses generated by the agent
`"tool.call"`	Tool/function invocations
`"tool.result"`	Tool/function return values
`"system"`	System-level events and signals

MemoryState

Lifecycle states for memory recall and curation.

type MemoryState = "active" | "decaying" | "archived";

Value	Description
`"active"`	Currently relevant, included in recall
`"decaying"`	Losing relevance, deprioritized in recall
`"archived"`	No longer active, preserved for provenance

Core Interfaces

Anima

Agent entity that owns memories and events. Returned by createAnima().

Name	Type	Required	Description
id	string	required	UUID identifier.
name	string	required	Human-readable name.
description	string	optional	Optional description.
meta	Record<string, unknown>	optional	Arbitrary metadata.
user_id	string	optional	Owning user UUID (set by server).
created_at	string	required	ISO 8601 creation timestamp.
updated_at	string	required	ISO 8601 last update timestamp.

AnimaCreate

Request interface for creating an anima. Used internally by the client.

Name	Type	Required	Description
name	string	required	Name for the anima.
description	string	optional	Optional description.
meta	Record<string, unknown>	optional	Optional metadata.

Event

Atomic unit of experience — a single captured interaction. Returned by extract().

Name	Type	Required	Description
id	string	required	UUID identifier.
anima_id	string	required	Owning anima UUID.
event_type	string	required	Event type (e.g. 'message.in').
role	string	optional	Message role: user, assistant, system, tool.
author	string	optional	Who produced this event.
summary	string	optional	Server-generated summary.
content	string	required	Event content body.
occurred_at	string	optional	ISO 8601 timestamp of when the event happened.
session_id	string	optional	Session grouping identifier.
meta	Record<string, unknown>	required	Metadata object.
source_uri	string	optional	Source system identifier.
dedupe_key	string	optional	Deduplication hash.
importance_score	number	optional	Curation priority, 0.0–1.0.
created_at	string	required	ISO 8601 ingestion timestamp.
updated_at	string	required	ISO 8601 last update timestamp.

EventCreate

Request interface for creating an event. Used internally by the client.

Name	Type	Required	Description
anima_id	string	required	Target anima UUID.
event_type	string	required	Event type string.
content	string	required	Event content body.
role	string	optional	Message role.
author	string	optional	Event author.
summary	string	optional	Optional summary.
occurred_at	string	optional	ISO 8601 override timestamp.
session_id	string	optional	Session identifier.
meta	Record<string, unknown>	optional	Metadata object.
source_uri	string	optional	Source system URI.
dedupe_key	string	optional	Custom deduplication key.
importance_score	number	optional	Importance hint, 0.0–1.0.

Memory

Subjective interpretation synthesized from one or more events.

Name	Type	Required	Description
id	string	required	UUID identifier.
anima_id	string	required	Owning anima UUID.
content	string	optional	Full memory content.
summary	string	optional	Compact narrative essence.
importance	number	optional	Recall priority, 0.0–1.0.
confidence	number	optional	Stability/certainty, 0.0–1.0.
state	MemoryState	optional	Lifecycle state.
recency_score	number	optional	Cached recency score.
decay_score	number	optional	Cached decay score.
time_start	string	optional	ISO 8601 event timespan start.
time_end	string	optional	ISO 8601 event timespan end.
meta	Record<string, unknown>	required	Metadata object.
created_at	string	required	ISO 8601 creation timestamp.
updated_at	string	required	ISO 8601 last update timestamp.

Pack Interfaces

MemoryPack

Compiled memory context for LLM injection. Returned by inject() (wrapped as MemoryPackWithHelpers).

Name	Type	Required	Description
id	string	required	Pack UUID.
anima_id	string	required	Owning anima UUID.
query	string	optional	Semantic query used for compilation.
preset_name	string	optional	Preset used for compilation.
session_memory_count	number	required	Session memories included.
knowledge_count	number	required	Knowledge items included.
long_term_memory_count	number	required	Long-term memories included.
has_identity	boolean	required	Whether identity context is included.
token_count	number	required	Estimated token count.
max_tokens	number	required	Token budget (default: 4000).
content	MemoryPackContent	required	Pack content with all layers.
compiled_at	string	required	ISO 8601 compilation timestamp.
created_at	string	required	ISO 8601 creation timestamp.

MemoryPackContent

Content structure nested within MemoryPack.content.

Name	Type	Required	Description
context	string	optional	Pre-formatted context string (used by asPrompt()).
identity	IdentityContext	optional	Agent identity layer.
session_memories	ScoredMemory[]	optional	Recent scored memories.
knowledge	ScoredKnowledge[]	optional	Knowledge items with scores.
long_term_memories	ScoredMemory[]	optional	Long-term scored memories.
temporal_context	TemporalContext	optional	Time gap awareness.

ScoredMemory

Memory with scoring breakdown from pack compilation.

Name	Type	Required	Description
id	string	required	Memory UUID.
summary	string	optional	Compact narrative summary.
score	number	required	Composite recall score.
reason	string	optional	Human-readable scoring explanation.
breakdown	Record<string, number>	required	Per-factor score breakdown.
similarity	number	optional	Semantic similarity score.

ScoredKnowledge

Knowledge item with similarity score from pack compilation.

Name	Type	Required	Description
id	string	required	Knowledge UUID.
content	string	required	Knowledge content text.
type	string	required	Knowledge type classification.
score	number	required	Relevance score.
similarity	number	optional	Semantic similarity score.

TemporalContext

Temporal awareness context for bridging gaps between sessions.

Name	Type	Required	Description
last_event_at	string	required	ISO 8601 timestamp of most recent event.
hours_ago	number	required	Hours since last event.
memory_summary	string	optional	Natural language summary of last session.
formatted	string	required	Pre-formatted temporal context string.

IdentityContext

Agent identity layer from pack compilation.

Name	Type	Required	Description
personality_type	string	optional	Personality classification.
communication_style	string	optional	Preferred communication approach.
self_reflection	Record<string, unknown>	optional	Anima's self-reflection data.
prose	string	optional	Natural language identity description (~70–100 tokens).

Config Interfaces

ElephantasmConfig

Configuration for the Elephantasm constructor.

Name	Type	Required	Description
apiKey	string	optional	API key. Falls back to ELEPHANTASM_API_KEY.
animaId	string	optional	Default anima ID. Falls back to ELEPHANTASM_ANIMA_ID.
endpoint	string	optional	API URL. Falls back to ELEPHANTASM_ENDPOINT.
timeout	number	optional	Timeout in milliseconds. Default: 30000.

ExtractOptions

Options for the extract() method.

Name	Type	Required	Description
animaId	string	optional	Override default anima ID.
sessionId	string	optional	Session grouping identifier.
role	string	optional	Message role.
author	string	optional	Event author identifier.
occurredAt	string	optional	ISO 8601 timestamp override.
meta	Record<string, unknown>	optional	Metadata object.
importanceScore	number	optional	Importance hint, 0.0–1.0.

InjectOptions

Options for the inject() method.

Name	Type	Required	Description
animaId	string	optional	Override default anima ID.
query	string	optional	Semantic search query.
preset	string	optional	Pack compilation preset.