tavern-labs-ai/persona-ai-sdk

persona-ai-sdk is a TypeScript package for applications where an AI character should keep a consistent identity and remember relevant details across conversations. It bundles eight persona cards, a memory runtime, and model adapters in one npm install, so a developer can start from a catalog character rather than writing prompts and memory logic from scratch.

How a response is produced

The runtime is split into replaceable layers: personas, memory, model, persistence, and interface. A single respond() call recalls relevant memories, compiles the persona into instructions, asks the model for a reply, ingests the finished turn, advances relationship state, and returns text plus voice delivery metadata (emotion, pace, expressiveness) and a trace with provider, timings, and recalled memory IDs. That trace is useful when debugging why a character behaved a certain way.

Persona cards contain prompts, traits, greetings, and memory seeds. Seeds are not privileged records: they pass through the normal extraction pipeline and may be normalized, merged, or rejected by the configured extractor. Traits are advisory, and a card's suggestedModel is only a recommendation, not a guarantee that the model is enabled in your account or region.

Providers, storage, and swapping pieces

Extraction, embeddings, and generation are independent ports, so they can be mixed — for example, Bedrock for generation with OpenAI embeddings, or a local embedding adapter. The OpenAI adapters use the Responses API for extraction and generation and the Embeddings API for vectors; the Bedrock adapters use Converse and Titan V2 embeddings. The README recommends specifying model IDs explicitly so a package upgrade does not silently change model behavior.

Persistence offers in-memory storage for tests, atomic JSON files for prototypes, and SQLite for desktop or single-node use. SQLite is an optional native dependency via better-sqlite3. For horizontally scaled deployments, the documented alternative is implementing the MemoryStore contract on a tenant-partitioned database such as PostgreSQL or DynamoDB. The package also includes framework-neutral service handlers, a SillyTavern character-card and JSONL chat importer, and retrieval/persona evaluation helpers.

Requirements and constraints

• Node.js 20 or newer, plus 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.
• Unknown persona IDs return Atlas rather than an error; call personaIds() first if that should be treated as an error.
• The bundled stores cover single-node use; multi-node deployments are left to your own store implementation.
• Live provider tests are opt-in because they spend paid API quota.

Version 1.0.3 is the current release documented in the README, and the project is MIT-licensed. For real-user deployments, the project points to separate Security and Privacy docs covering secrets, tenancy, and erasure project repository; setup and API details live in the Getting Started guide and API reference.