tavern-labs-ai/character-ai-sdk

character-ai-sdk is a TypeScript package for applications that need an AI character to keep a recognizable identity and recall relevant context across conversations. It bundles eight ready-made persona cards, a persona-and-memory runtime, and adapters for OpenAI and Amazon Bedrock, so a single npm install covers the character layer and provider calls.

How a character response works

The runtime separates five replaceable layers: personas (prompts, traits, greetings, memory seeds), memory (extraction, provenance, consolidation, recall, lifecycle), the model, persistence, and the interface. Each runtime.respond() call runs the full loop: it recalls relevant memories, compiles the persona into instructions, asks the model, ingests the completed turn, advances relationship state, and returns text plus voice delivery metadata and a trace of provider, model, timings, and recalled memory IDs. That trace is useful for debugging why a character said something.

Choosing providers and storage

Extraction, embeddings, and generation are independent ports, so you can mix vendors: Bedrock for generation and OpenAI embeddings, for example, or a local embeddings adapter. Storage choices are in-memory (test and ephemeral sessions), atomic JSON files (prototypes), and SQLite (desktop, single-node, small services). SQLite is an optional native dependency on better-sqlite3. For horizontally scaled deployments the README points to implementing the MemoryStore contract on a tenant-partitioned database such as PostgreSQL or DynamoDB rather than offering a ready-made adapter. Interfaces are equally open: chat, voice, game, HTTP service, or SillyTavern, with character-card and JSONL chat import documented.

Requirements and caveats

• Node.js 20 or newer.
• An OpenAI API key or AWS credentials with Bedrock model access; the Bedrock path uses the standard AWS SDK credential chain, and the execution identity needs permission to invoke the configured models.
• Model IDs should be set explicitly so package upgrades do not silently change model behavior.
• Persona traits are advisory, and a card's suggestedModel is a recommendation, not proof the model is enabled in your account or region.
• getPersona falls back to Atlas for unknown IDs; check IDs first if that fallback is unwanted.
• Memory seeds from cards go through the normal extraction pipeline and may be normalized, merged, or rejected, so they are not privileged records.
• Live provider tests are opt-in because they consume paid API quota.

The package is MIT-licensed, and the README's security and privacy guide is the place to look when handling real users, secrets, tenancy, or erasure. The supplied material documents no benchmarks, so no performance claims are made here.

Project source and documentation