Store agent tool calls, order updates, and business events. Rebuild application state from that history — in your own PostgreSQL database. Alvyn brings type-safe event sourcing to TypeScript, without requiring a new agent framework or a separate message broker.
npm install alvyn pgStart with one stream. No prior event sourcing or CQRS knowledge needed.
Keep the steps, not just the latest result.
Try a familiar library checkout. The same principle applies to an agent run or an order: save what happened, then derive the current state. This interactive illustration runs locally in your browser, not against a database.
Live Domain & State Simulator
Compare a current-state-only table with recorded events.
No transactions executed yet.
Click step 1 above to trigger the database state.
Event stream is empty.
Click step 1 above to append your first CloudEvent.
Start with a book loan
Click an action above to begin simulating real member library activity.
A few events. A state you can explain.
No complex external message brokers or distributed consensus clusters. Alvyn runs directly inside your existing PostgreSQL database. Typed events and reducers keep your application contracts explicit.
Engineers as domain experts
Define event payloads explicitly using standard TypeScript types. Your codebase represents business reality without translation-loss.
1// Define type-safe event payload contracts2export type CartEvents = {3 CartCreated: { cartId: string; userId: string };4 ItemAdded: { sku: string; price: number; name: string };5 CouponApplied: { code: string; discount: number };6 CheckoutCompleted: { paymentId: string; totalPaid: number };7};Deterministic replay & audit trails
for AI & distributed systems.
A final status cannot tell you which tool timed out, why an order changed, or which approval preceded a payment. If your application only stores the latest state, those transitions are missing.
With Alvyn, your application explicitly records meaningful events. Pure reducers turn them into current state. That is event sourcing: start small, without splitting your whole application into separate read and write services. Add projections when your queries need them.
Replay reconstructs state from recorded events. It does not rerun models deterministically, reveal their internal reasoning, or automatically resume external tool calls. Keep your existing AI SDK, web framework, and observability tools.
Useful records.
Explicit boundaries.
Append-oriented APIs and CloudEvents provide a structured history. They do not make PostgreSQL tamper-proof: database permissions, retention, backups, and monitoring remain part of your deployment.
Optional AES-256-GCM envelope encryption supports crypto-shredding. Protect snapshots separately and account for exported data, keys, and backups. Reducers must explicitly handle redacted events.
These primitives can support audit and privacy requirements; using Alvyn alone does not establish GDPR or EU AI Act compliance. Article 12 addresses logging for high-risk AI systems, not a universal requirement to record every model token.
Start small. Add the primitives you need.
Rebuild application state
Replay recorded events through your reducers. Inspect agent steps or business transitions without calling the model or external tools again.
Structured event history
Record the inputs, outputs, and decisions your application chooses to persist as CloudEvents. Complement traces with durable business history.
Optional envelope encryption
Built-in envelope encryption. Revoking a cryptographic tenant or user key renders PII unreadable (tombstoned), helping teams honor erasure requests while keeping the event stream intact.
PostgreSQL-native outbox
Commit events and outbox records together. Relay with at-least-once delivery; external side effects still need idempotency. No separate broker required to get started.
Type-Safe Aggregates & Invariants
Typed payloads and handler inference help keep events and reducers consistent. Your application validates inputs and enforces business rules before appending.
Read-time schema evolution
Upcasters transform older event payloads when reading, without rewriting history. Plan compatible reader and writer rollouts as your application changes.
Is Alvyn right for your application?
Choose it when transitions matter: tool execution records, approvals, orders, subscriptions, or other state with a history worth keeping. Ordinary CRUD is still a good choice when you only need current values.
Alvyn is not a workflow runtime, vector memory service, or observability platform. Keep those tools where you need scheduling, semantic retrieval, or tracing. Event history is the complementary persistence layer.
“The event log is not a side effect.
It is your system.”
You do not need to redesign your whole application. Pick one agent run or business process, record its events, and rebuild its state. Learn event sourcing by solving a problem you already have.