| 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 설정 시. Use when this capability is needed. |
Chat Agent Persistence Guide
Chat 서비스의 데이터 영속화 레이어 (Checkpointer + Message Storage)
Architecture Overview
┌───────────────────────────────────────────────────────────────────────────┐
│ 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
| Path | Purpose | Component | Target |
|---|
| Checkpointer | 멀티턴 컨텍스트 (LangGraph state) | CachedPostgresSaver | checkpoints 테이블 |
| Message Storage | 대화 이력 (user/assistant) | ChatPersistenceConsumer | chat.messages 테이블 |
Quick Diagnosis
kubectl exec -n postgres deploy/postgresql -- psql -U sesacthon -d ecoeco -c \
"SELECT COUNT(*) FROM chat.messages;"
kubectl logs -n chat deploy/chat-worker --tail=100 | grep -E "(CachedPostgresSaver|checkpointer|InMemory)"
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)
로그:
[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건
진단:
kubectl exec -n redis rfr-streams-redis-0 -c redis -- redis-cli XINFO GROUPS chat:events:0
원인: ChatPersistenceConsumer 미배포
상세: See message-consumer.md
Code Locations
| Component | Path |
|---|
| Checkpointer | apps/chat_worker/infrastructure/orchestration/langgraph/checkpointer.py |
| Dependencies | apps/chat_worker/setup/dependencies.py (Lines 641-678) |
| Consumer Entry | apps/chat/consumer.py |
| Consumer Infra | apps/chat/infrastructure/messaging/redis_streams_consumer.py |
| Consumer Adapter | apps/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
Converted and distributed by TomeVault — claim your Tome and manage your conversions.
