Skip to content

feat(docs): add the persistence guide - #1594

Open
joesaunderson wants to merge 1 commit into
vercel:mainfrom
joesaunderson:docs/persistence-guide
Open

feat(docs): add the persistence guide#1594
joesaunderson wants to merge 1 commit into
vercel:mainfrom
joesaunderson:docs/persistence-guide

Conversation

@joesaunderson

Copy link
Copy Markdown

Closes #1382.

Summary

Adds a dedicated Persistence guide (docs/guides/persistence.md) covering the full storage story that today only exists as a short section in the hooks guide:

  • What to persist: the chat row, the SessionState cursor, and the event log — and why they are three separate things
  • A recommended two-table schema for a chat product (chats + chat_events), with meta.id as the dedupe key and an app-owned seq for ordering
  • Storing events from the client (onEvent/onFinish) and from a server-side hook, including the sessionId → chatId mapping a hook needs
  • Skipping *.appended delta events in storage, and backfilling from the durable stream with stream({ follow: false })
  • Loading events back and reconstructing the conversation: initialEvents/initialSession in the browser, and folding defaultMessageReducer() from eve/client into EveMessage[] anywhere else
  • Resuming across session expiry/completion while keeping one chat history

Builds on the stable event ids from #1239. Cross-links added from the hooks, continuations, and frontend overview pages, and the page is registered in docs/guides/meta.json.

Verification

  • pnpm docs:check — 82 files validated, all snippet import paths resolve, MDX compiles

PR Checklist

  • I linked an issue with prior discussion confirming this change is wanted
  • I ran the relevant checks from CONTRIBUTING.md
  • I added tests and documentation where relevant (docs-only change)
  • I added a changeset if this touches the published eve package (docs-only, no changeset)
  • DCO sign-off passes for every commit (git commit --signoff)

🤖 Generated with Claude Code

https://claude.ai/code/session_01R9KPb7XDbWjxngtZ93EDeH

Add a dedicated guide covering event storage, a chat schema, loading
events back, reconstructing conversations with defaultMessageReducer,
and resuming sessions. Cross-link it from the hooks, continuations, and
frontend pages.

Closes vercel#1382

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01R9KPb7XDbWjxngtZ93EDeH
Signed-off-by: Joe Saunderson <joe.saunderson@mention-me.com>
@vercel

vercel Bot commented Aug 4, 2026

Copy link
Copy Markdown
Contributor

@joesaunderson is attempting to deploy a commit to the Vercel Team on Vercel.

A member of the Team first needs to authorize it.

@joesaunderson
joesaunderson marked this pull request as ready for review August 4, 2026 12:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add guide for chat persistence

1 participant