文件记忆

控制台

1. 登录 Agent Storage 控制台，进入记忆库管理，点击创建记忆库。

2. 输入类型选择短期消息，输出类型勾选文件记忆（如需同时进行语义检索可加选结构记忆）。

3. 点击确定完成创建。

SDK

from tablestore_agent_storage import AgentStorageClient

client = AgentStorageClient(
    api_key="your-api-key",
    ots_endpoint="https://your-instance.cn-beijing.ots.aliyuncs.com",
    ots_instance_name="your-instance-name",
)

client.create_memory_store({
    "memoryStoreName": "agent_memory",
    "description": "Agent 对话记忆",
    "inputType": "messages",
    "outputTypes": ["structured", "file"],
})

如果只需要文件，将 outputTypes 设置为 ["file"]。inputType 创建后不可修改；以 messages 作为输入的记忆库可以通过 UpdateMemoryStore 调整 outputTypes。

控制台

1. 打开文件记忆库，进入短期记忆页，点击写入记忆。

2. 输入模式选择对话消息(JSON)，填写完整的四级 Scope（应用 appId、租户/用户 tenantId、智能体 agentId、会话 runId）。

3. 粘贴对话消息 JSON，点击确定提交。文件为异步生成，提交后可在请求日志页查看生成任务状态。

SDK

调用 AddMemories 写入消息。文件输出只支持异步生成，因此 sync 必须为 false 或省略。

resp = client.add_memories({
    "memoryStoreName": "agent_memory",
    "scope": {
        "appId": "shopping-app",
        "tenantId": "user-001",
        "agentId": "shopping-assistant",
        "runId": "session-001",
    },
    "messages": [
        {"role": "user", "content": "我平时喝美式咖啡，不加糖。"},
        {"role": "assistant", "content": "好的，我会记住你的饮品偏好。"},
    ],
    "sync": False,
})
request_id = resp["requestId"]

保存响应中的 requestId。传入 sync=true 会返回 400 INVALID_PARAMETER。

控制台

1. 打开文件记忆库，进入请求日志页。

2. 按写入时保存的 Request ID 找到对应记录，查看状态列，等待状态变为 completed。

SDK

使用 AddMemories 返回的requestId 调用 GetMemoryTask：

task = client.get_memory_task({
    "memoryStoreName": "agent_memory",
    "requestId": request_id,
})
print(task["task"]["status"])

控制台

1. 登录 Agent Storage 控制台，打开文件记忆库，进入长期记忆页。

2. 切换到文件记忆，选择写入时的完整 Scope。

3. 在文件树浏览生成的只读文件，点击文件可查看内容及版本历史。

SDK

调用 ListItems 列出文件，再逐个读取内容。

scope = {
    "appId": "shopping-app",
    "tenantId": "user-001",
    "agentId": "shopping-assistant",
    "runId": "session-001",
}

page = client.list_items({
    "type": "memoryfile",
    "memoryStoreName": "agent_memory",
    "scope": scope,
    "limit": 20,
})

# 先从 items 取得实际 path，再读取内容
for entry in page["items"]:
    item = client.get_item({
        "type": "memoryfile",
        "memoryStoreName": "agent_memory",
        "scope": scope,
        "path": entry["path"],
        "view": "full",
    })
    print(item["path"], item["content"])

响应顶层的 readOnly 为 true 表示这些文件由服务维护，读取内容需设置 view=full。

控制台

在左侧文件列表选中目标文件，右侧详情面板直接显示文件内容以及创建时间、更新时间和当前版本 ID，无需额外操作即可查看元数据。

SDK

将 includeContent 设置为 False，响应不会包含 content，适合检查文件摘要和更新时间。

current = client.get_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "includeContent": False,
})
print(current["contentSha256"], current["updatedAt"])

控制台

选中文件，点击编辑或替换资料，修改文件内容后保存。控制台基于当前版本做并发校验，若文件已被其他请求修改则保存失败，需刷新后重试。

SDK

并发写入场景建议把上一次读取到的 contentSha256 作为 expectedSha256 传入。文件已被其他请求修改时，服务拒绝覆盖，应用重新读取后再决定是否重试。

updated = client.update_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "content": "# 用户偏好\n\n- 喜欢拿铁\n- 偏好简洁回答\n",
    "expectedSha256": current["contentSha256"],
})

控制台

选中文件，点击重命名，输入新的文件路径后确定。目标路径已存在时会提示冲突。

SDK

UpdateItem 同时承载内容更新和重命名。单次请求必须在 content 与 newPath 中恰好选择一个。

renamed = client.update_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/preferences.md",
    "newPath": "/profile/user-preferences.md",
    "expectedSha256": updated["contentSha256"],
})

目标路径已经存在时，默认返回冲突。只有业务确认允许替换目标文件时，才设置 "overwrite": True。

控制台

在长期记忆页选择 Scope 后，左侧文件列表按路径前缀筛选并分页浏览，点击刷新获取最新列表。

SDK

ListItems 默认每页返回 100 个文件，单页最多返回 500 个。响应包含 nextToken 时，将其原样传入下一次请求。

next_token = None
while True:
    request = {
        "memoryStoreName": "agent_files",
        "scope": scope,
        "pathPrefix": "/profile/",
        "limit": 100,
    }
    if next_token:
        request["nextToken"] = next_token

    page = client.list_items(request)
    for entry in page["items"]:
        print(entry["path"])

    next_token = page.get("nextToken")
    if not next_token:
        break

控制台

选中文件，点击删除并确认。删除会移除当前文件并产生一条删除版本，历史版本仍可在版本历史中查看。

SDK

client.delete_item({
    "memoryStoreName": "agent_files",
    "scope": scope,
    "path": "/profile/user-preferences.md",
    "expectedSha256": renamed["contentSha256"],
})

删除操作会移除当前文件，但历史版本仍可以按文件 ID 查询。