[!info] related notes

• 所属 MOC: AI Agent Application MOC
• 相关: Session Management, Message Persistence, Checkpoint

Conversation Persistence

一句话定义

Conversation Persistence 是将完整对话上下文持久化到数据库的工程实践。它不只是保存聊天记录，还包括会话元数据、Agent 状态、工具调用记录和执行轨迹。

它解决什么问题

用户刷新页面后，对话应该还在。用户换设备登录，历史对话应该同步。出问题时，应该能回溯完整的对话过程。

核心原理

持久化内容

内容	存储位置	说明
会话元数据	sessions 表	session_id, user_id, title, status
消息列表	messages 表	role, content, status, tool_calls
Agent 状态	agent_states 表	当前阶段、结构化数据
工具调用	tool_calls 表	工具名、参数、结果、耗时
Checkpoint	checkpoints 表	状态快照（用于恢复）

数据库 Schema

CREATE TABLE sessions (
    id VARCHAR(36) PRIMARY KEY,
    user_id VARCHAR(36) NOT NULL,
    title VARCHAR(255),
    status VARCHAR(20) DEFAULT 'active',
    created_at TIMESTAMP DEFAULT NOW(),
    updated_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE messages (
    id VARCHAR(36) PRIMARY KEY,
    session_id VARCHAR(36) REFERENCES sessions(id),
    turn_id VARCHAR(36),
    role VARCHAR(20) NOT NULL,
    content TEXT,
    status VARCHAR(20) DEFAULT 'completed',
    token_usage JSONB,
    created_at TIMESTAMP DEFAULT NOW()
);

CREATE TABLE tool_calls (
    id VARCHAR(36) PRIMARY KEY,
    message_id VARCHAR(36) REFERENCES messages(id),
    tool_name VARCHAR(100),
    arguments JSONB,
    result JSONB,
    status VARCHAR(20),
    duration_ms INT,
    created_at TIMESTAMP DEFAULT NOW()
);

常见坑

1. 只保存消息不保存状态: 刷新后丢失 Agent 进度
2. 不做软删除: 删除会话后数据不可恢复
3. 不做分页查询: 消息多了查询慢
4. 不记录 token 用量: 无法统计成本

参考资料

• Message Persistence
• Session Management