更新时间：2026-11-02 GMT+08:00
短期记忆操作
短期记忆以“消息（Message）”为单位存储。对话中的用户输入、Agent回复、工具调用和系统消息，均作为消息写入会话，实现对话上下文的持久化。
追加消息
在Agent的对话循环中，每轮交互后追加消息。支持一次写入多条消息，便于一次性提交完整对话轮次。
from agentarts.sdk.memory.inner.config import TextMessage
messages = [
TextMessage(
role="user",
content="你好，我想了解机器学习的基础知识",
actor_id="user-001"
),
TextMessage(
role="assistant",
content="机器学习是人工智能的一个分支，主要研究如何让计算机从数据中学习规律。",
actor_id="assistant-001"
)
]
client.add_messages(
space_id=space_id,
session_id=session_id,
messages=messages
) 写入特性：
- 同步写入，写入后立即可读
- 批量追加在单个事务中执行，全部成功或全部失败
- 服务端自动分配递增序号（seq），保证消息顺序
- 写入后消息不可修改、不可删除
列出消息
按会话分页查询消息列表，支持排序。
result = client.list_messages(
space_id=space_id,
session_id=session_id,
limit=20,
offset=0,
order="asc",
sort_by="seq"
) 参数说明：
| 参数 | 说明 |
|---|---|
| space_id | 记忆库ID |
| session_id | 会话ID |
| limit | 每页数量，1~20，默认 20 |
| offset | 偏移量，默认0，配合limit实现分页 |
| order | 排序方向，asc（从旧到新，默认）/ desc（从新到旧） |
| sort_by | 排序字段，seq（按序号，默认）/ message_time（按消息时间） |
查看单条消息
message = client.show_message(
space_id=space_id,
session_id=session_id,
message_id="消息ID"
) 消息过期（LLT）行为
短期记忆消息受记忆库TTL（Time To Live）配置控制，具有以下过期行为：
- 过期机制：消息从写入时开始计算TTL，超过TTL后由系统自动从数据库中物理删除（硬删除）。
- 查询过期消息：查询已过期的消息时，系统返回404错误（错误码：AgentArts.01020005），提示“消息不存在”。
- TTL单位与范围：TTL支持以“天”（1～365天）或“小时”（1～8760小时）为单位配置，最低支持1小时，适用于会话消息处理后即删除的场景。
- TTL更新生效：更新记忆库TTL配置后，最多需要30分钟生效（缓存过期后重新读取配置）。生效后新写入的消息按新TTL计算过期时间，已有消息的TTL不受影响。
- 长期记忆提取：在消息过期前，长期记忆提取策略可处理并提取消息内容为长期记忆。若TTL设置较短（如1小时），请确保提取任务在此时间内完成，否则消息可能在提取前被删除，导致长期记忆静默丢失。
父主题： 在Agent中集成记忆库
