home / skills / andrelandgraf / fullstackrecipes / ai-chat-persistence

ai-chat-persistence skill

safe

This skill helps persist AI chat conversations in Neon Postgres, including AI SDK message parts, tools, reasoning, and streaming for reliable history.

npx playbooks add skill andrelandgraf/fullstackrecipes --skill ai-chat-persistence

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

592 B

---
name: ai-chat-persistence
description: Persist AI chat conversations to Neon Postgres with full support for AI SDK message parts including tools, reasoning, and streaming. Uses UUID v7 for chronologically-sortable IDs.
---

# AI Chat Persistence with Neon

To set up AI Chat Persistence with Neon, refer to the fullstackrecipes MCP server resource:

**Resource URI:** `recipe://fullstackrecipes.com/ai-chat-persistence`

If the MCP server is not configured, fetch the recipe directly:

```bash
curl -H "Accept: text/plain" https://fullstackrecipes.com/api/recipes/ai-chat-persistence
```

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.

FAQ

Why use UUID v7?

UUID v7 embeds sortable timestamps so records can be ordered chronologically without relying solely on database timestamps, improving distributed write patterns and range queries.

Does it support streaming responses?

Yes. Streaming fragments are stored incrementally so you can reconstruct partial outputs and mark completion when the final segment arrives.