ai-chat-persistence_skill

Overview

This skill persists AI chat conversations to Neon Postgres with full support for AI SDK message parts, including tool calls, chain-of-thought reasoning, and streaming fragments. It uses UUID v7 for chronologically-sortable IDs and is implemented in TypeScript as a production-ready pattern and recipe collection. The implementation fits modern full-stack web AI apps and pairs well with Shadcn UI conventions.

How this skill works

The skill captures incoming and outgoing AI messages, decomposes them into SDK-supported parts (content, tool calls, reasoning metadata, and stream deltas), and writes structured records to Neon Postgres. Each message and message part is assigned a UUID v7 to preserve chronological order and enable efficient range queries. Streaming segments are appended incrementally so you can reconstruct partial outputs in real time.

When to use it

• You need durable storage for chat history with fine-grained message part fidelity (tools, reasoning, streams).
• Building analytics or audit trails that require ordering by creation time across distributed systems.
• Implementing resumable or incremental streaming playback of AI responses.
• Storing tool invocation details and reasoning traces for debugging or compliance.
• Integrating chat persistence into a TypeScript full-stack app with Neon Postgres.

Best practices

• Normalize and validate message parts before writing to the database to keep schemas stable.
• Use UUID v7 for IDs and index timestamp-derived fields for fast chronological queries.
• Write streaming fragments in append-only fashion and mark message completion with status flags.
• Store tool inputs and outputs separately and reference them from message parts to reduce duplication.
• Provide retention and archival policies for long-term storage and compliance.

Example use cases

• A customer support chat that logs tool calls (ticket creation, CRM lookups) and reasoning traces for audits.
• A tutoring app that streams partial answers and stores reasoning steps for later review.
• An AI-assisted code review tool that persists tool-run outputs and decision traces for traceability.
• Analytics dashboard that queries chronologically-sorted chat events for session reconstruction.