TypeScript: Client — Elephantasm Docs

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

Elephantasm Class

The main client for interacting with the Elephantasm API. Uses the native fetch API with automatic timeout and error handling.

import { Elephantasm } from "@elephantasm/client";
 
const client = new Elephantasm({
  apiKey: "sk_live_...",
  animaId: "your-anima-id",
});

Constructor Parameters

Takes an ElephantasmConfig object:

Name	Type	Required	Description
apiKey	string	optional	API key for authentication. Falls back to ELEPHANTASM_API_KEY env var.
animaId	string	optional	Default anima ID for all operations. Falls back to ELEPHANTASM_ANIMA_ID.
endpoint	string	optional	API base URL. Falls back to ELEPHANTASM_ENDPOINT. Default: https://api.elephantasm.com
timeout	number	optional	Request timeout in milliseconds. Default: 30000.

An AuthenticationError is thrown if no API key is provided and ELEPHANTASM_API_KEY is not set.

Timeout is in milliseconds (TypeScript) vs seconds (Python). Default is 30000ms (30s).

inject()

Retrieve the latest compiled memory pack for LLM context injection.

const pack = await client.inject();
if (pack) {
  const systemPrompt = `You are a helpful assistant.\n\n${pack.asPrompt()}`;
}

Parameters

Takes an optional InjectOptions object:

Name	Type	Required	Description
animaId	string	optional	Override the client's default anima ID for this call.
query	string	optional	Semantic search query to influence memory retrieval.
preset	string	optional	Pack compilation preset: 'conversational' or 'self_determined'.

Returns

Promise<MemoryPackWithHelpers | null> — pack with helper methods, or null if no packs exist.

extract()

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

import { Elephantasm } from "@elephantasm/client";
 
const client = new Elephantasm({ apiKey: "sk_live_...", animaId: "..." });
 
// Basic capture
await client.extract("message.in", "What's the weather?", { role: "user" });
 
// With full options
await client.extract("message.out", "It's 72°F and sunny.", {
  role: "assistant",
  author: "weather-agent",
  sessionId: "conv-123",
  meta: { confidence: 0.95 },
  importanceScore: 0.7,
});

Parameters

Name	Type	Required	Description
eventType	EventType \| string	required	Type of event: 'message.in', 'message.out', 'tool.call', 'tool.result', or 'system'.
content	string	required	Event content — message text, tool output, system signal, etc.
options	ExtractOptions	optional	Additional options object (see below).

ExtractOptions

Name	Type	Required	Description
animaId	string	optional	Override the client's default anima ID.
sessionId	string	optional	Group related events by conversation or task.
role	string	optional	Message role: user, assistant, system, or tool.
author	string	optional	Identifier for who produced this event.
occurredAt	string	optional	ISO 8601 datetime string. Defaults to now.
meta	Record<string, unknown>	optional	Arbitrary metadata object.
importanceScore	number	optional	Priority hint for curation, 0.0–1.0.

Returns

Promise<Event> — the created event object.

TypeScript uses camelCase options (sessionId, importanceScore) while the Python SDK uses snake_case (session_id, importance_score). The SDK handles conversion automatically.

createAnima()

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

const anima = await client.createAnima("my-agent", "Customer support bot");
console.log(anima.id); // Use this ID for inject() and extract()

Parameters

Name	Type	Required	Description
name	string	required	Human-readable name for the anima.
description	string	optional	Optional description of the anima's purpose.
meta	Record<string, unknown>	optional	Optional metadata object.

Returns

Promise<Anima> — the created anima object.

MemoryPackWithHelpers

inject() returns a MemoryPackWithHelpers object that extends MemoryPack with helper methods for accessing individual layers.

const pack = await client.inject();
if (pack) {
  // Pre-formatted context for LLM
  const prompt = pack.asPrompt();
 
  // Individual layers
  const identity = pack.getIdentity();
  const sessionMems = pack.getSessionMemories();
  const knowledge = pack.getKnowledge();
  const ltMems = pack.getLongTermMemories();
  const temporal = pack.getTemporalContext();
}

Method	Return Type	Description
`asPrompt()`	`string`	Pre-formatted context string for LLM injection
`getIdentity()`	`IdentityContext \| undefined`	Agent personality and behavioral context
`getSessionMemories()`	`ScoredMemory[]`	Recent scored memories
`getKnowledge()`	`ScoredKnowledge[]`	Canonicalized knowledge items
`getLongTermMemories()`	`ScoredMemory[]`	Scored long-term memories
`getTemporalContext()`	`TemporalContext \| undefined`	Time gap awareness context

Module-Level Functions

For simpler usage, the SDK exports top-level async functions that use a shared client configured from environment variables.

import { inject, extract, createAnima } from "@elephantasm/client";
 
// No client instantiation needed
await extract("message.in", "Hello!", { role: "user" });
const pack = await 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:

createAnima(name, description?, meta?) → Promise<Anima>
inject(options?) → Promise<MemoryPackWithHelpers | null>
extract(eventType, content, options?) → Promise<Event>

All client methods and module-level functions are async. Always use await.