AgentSkillsCN

chat-agent-persistence

聊天服务持久化层指南。Checkpointer（多轮对话上下文）、Message Persistence（PostgreSQL）、Redis Streams Consumer 架构及故障排查。适用场景：(1) 当 chat.messages 表为空时；(2) 出现 Checkpointer 相关错误时；(3) 多轮对话上下文无法正常保持时；(4) 配置 Redis Streams Consumer Group 时。

SKILL.md
--- frontmatter
name: chat-agent-persistence
description: Chat 서비스의 영속화 레이어 가이드. Checkpointer(멀티턴 컨텍스트), Message Persistence(PostgreSQL), Redis Streams Consumer 아키텍처 및 트러블슈팅. Use when: (1) chat.messages 테이블이 비어있을 때, (2) checkpointer 관련 에러 발생 시, (3) 멀티턴 대화 컨텍스트가 유지되지 않을 때, (4) Redis Streams consumer group 설정 시.

Chat Agent Persistence Guide

Chat 서비스의 데이터 영속화 레이어 (Checkpointer + Message Storage)

Architecture Overview

code
┌───────────────────────────────────────────────────────────────────────────┐
│                     Chat Persistence Architecture                          │
├───────────────────────────────────────────────────────────────────────────┤
│                                                                            │
│  ┌─────────────┐                                                          │
│  │ chat-worker │                                                          │
│  │ (LangGraph) │                                                          │
│  └──────┬──────┘                                                          │
│         │                                                                  │
│    ┌────┴────┐                                                            │
│    │         │                                                            │
│    ▼         ▼                                                            │
│  Checkpointer    Progress Events                                          │
│  (Multi-turn)    (Stage updates)                                          │
│    │                  │                                                   │
│    │                  │ XADD                                              │
│    ▼                  ▼                                                   │
│  ┌────────────┐  ┌──────────────────┐                                    │
│  │ PostgreSQL │  │  Redis Streams   │                                    │
│  │checkpoints │  │ chat:events:{0-3}│                                    │
│  └────────────┘  └────────┬─────────┘                                    │
│                           │                                               │
│              ┌────────────┼────────────┐                                 │
│              │            │            │                                 │
│              ▼            ▼            ▼                                 │
│      ┌─────────────┐ ┌─────────────┐ ┌──────────────────┐              │
│      │ eventrouter │ │chat-persist │ │  (other groups)  │              │
│      │   (group)   │ │  (group)    │ │                  │              │
│      └──────┬──────┘ └──────┬──────┘ └──────────────────┘              │
│             │               │                                           │
│             ▼               ▼                                           │
│      ┌─────────────┐ ┌──────────────┐                                  │
│      │event-router │ │chat-consumer │                                  │
│      │  (SSE fan)  │ │  (DB write)  │                                  │
│      └─────────────┘ └──────┬───────┘                                  │
│                             │                                           │
│                             ▼                                           │
│                      ┌──────────────┐                                  │
│                      │  PostgreSQL  │                                  │
│                      │chat.messages │                                  │
│                      └──────────────┘                                  │
│                                                                         │
└───────────────────────────────────────────────────────────────────────────┘

Two Persistence Paths

PathPurposeComponentTarget
Checkpointer멀티턴 컨텍스트 (LangGraph state)CachedPostgresSavercheckpoints 테이블
Message Storage대화 이력 (user/assistant)ChatPersistenceConsumerchat.messages 테이블

Quick Diagnosis

bash
# 1. chat.messages 테이블 확인
kubectl exec -n postgres deploy/postgresql -- psql -U sesacthon -d ecoeco -c \
  "SELECT COUNT(*) FROM chat.messages;"

# 2. Checkpointer 상태 확인 (worker 로그)
kubectl logs -n chat deploy/chat-worker --tail=100 | grep -E "(CachedPostgresSaver|checkpointer|InMemory)"

# 3. Redis Streams consumer group 확인
kubectl exec -n redis rfr-streams-redis-0 -c redis -- redis-cli XINFO GROUPS chat:events:0

Common Issues

Issue 1: CachedPostgresSaver 초기화 실패

증상: InMemory checkpointer created (Redis fallback disabled)

로그:

code
[WARNING] CachedPostgresSaver failed, falling back to Redis only:
object _AsyncGeneratorContextManager can't be used in 'await' expression

원인: checkpointer.py:228에서 async context manager를 await로 호출

상세: See checkpointer.md

Issue 2: chat.messages 테이블 비어있음

증상: chat.conversations에 데이터 있지만 chat.messages는 0건

진단:

bash
# Consumer group 확인 - "chat-persistence" 없으면 미배포
kubectl exec -n redis rfr-streams-redis-0 -c redis -- redis-cli XINFO GROUPS chat:events:0

원인: ChatPersistenceConsumer 미배포

상세: See message-consumer.md

Code Locations

ComponentPath
Checkpointerapps/chat_worker/infrastructure/orchestration/langgraph/checkpointer.py
Dependenciesapps/chat_worker/setup/dependencies.py (Lines 641-678)
Consumer Entryapps/chat/consumer.py
Consumer Infraapps/chat/infrastructure/messaging/redis_streams_consumer.py
Consumer Adapterapps/chat/presentation/consumer/redis_streams_adapter.py

Reference Files

  • •Checkpointer 상세: See checkpointer.md - Cache-Aside 패턴, LangGraph API
  • •Message Consumer 상세: See message-consumer.md - 배포 방법, Consumer Group
  • •트러블슈팅 문서: docs/troubleshooting/chat-messages-not-persisted.md
  • •PostgreSQL 분석: docs/reports/postgres-chat-data-analysis.md