记忆库是什么
记忆库（Memory Store）是项目级的持久化文件集合。创建会话时挂载记忆库后，智能体就可以在会话中读取或更新其中的文件。 记忆库、记忆文件和文件版本分别表示不同的对象：
记忆库不提供自动向量检索。会话启动时，平台会向智能体提供根目录
README.md 和 index.md 的有限内容，每个文件最多 16 KiB。其他文件需要智能体通过文件工具按需读取。
创建并挂载记忆库
完成一次最短使用流程需要三步：创建记忆库、创建记忆文件、在创建会话时挂载记忆库。记忆库也可以在控制台的「记忆」页面创建和管理，详见 使用控制台。除控制台和 API 外，你也可以通过 kha CLI 创建和管理记忆库。 以下示例提供 cURL 与 kha CLI 两种写法，介绍记忆库和记忆文件的具体操作。创建记忆库
下面的请求创建一个名为project-conventions 的记忆库：
id，作为后续请求的 MEMORY_STORE_ID。name 必须在项目内唯一，长度为 1 到 64 个字符，并以 Unicode 字母或数字开头；后续字符可以包含 _ 和 -。
创建记忆文件
使用记忆库 ID 和文件路径创建文件。content 是文件正文的 Base64 编码，解码后的正文最多 20 MiB。示例中，content 的值是文件正文「项目约定」的 Base64 编码：
id，作为后续读取、更新和查看版本时使用的 MEMORY_ID。省略 content 或传入空字符串可以创建空文件，但同一路径不能重复创建。
path 必须是规范化的相对路径，最长 900 字节（UTF-8 编码），并使用 / 分隔目录。不能使用绝对路径，也不能包含空路径段、.、..、反斜杠、控制字符或百分号编码。
在会话中挂载记忆库
记忆库只能在创建会话时绑定。下面的请求使用前一步得到的MEMORY_STORE_ID，并以读写方式挂载记忆库：
agent_id 和 environment_id 替换为已有资源的 ID，将 MEMORY_STORE_ID 替换为创建记忆库响应中的 id。
access 可以是 read_only 或 read_write：
read_only只允许读取记忆库；read_write允许读取和写入记忆库。
/mnt/agents/memories/<store-name>/。绑定关系、访问模式和 instructions 在会话创建后不能修改。
管理记忆文件
读取文件
使用记忆库 ID 和文件 ID 读取文件。API 响应中的content 是 Base64 编码，保存响应中的 content_sha256，更新文件时可以将它原样传回做并发校验：
更新文件
把新正文编码为 Base64 后更新文件。请求中的content_sha256 应使用读取当前文件时得到的值，平台会用它检查文件在读取后是否被修改：
content_sha256 更新会返回 409，平台不会覆盖新内容。通过会话挂载路径和文件工具写入时，不经过 API 的 content_sha256 并发校验，并发写入可能互相覆盖。每次成功的文件变更都会生成一个新版本。
删除文件
删除只移除当前文件，历史版本仍然保留：memory_id 的版本列表和历史版本内容仍可查询，但不能再对这个 memory_id 使用 PATCH。
查看版本和恢复
查看文件版本
创建、修改、重命名和删除都会生成版本，版本的operation 字段分别对应 created、modified、renamed 和 deleted。先查询文件的版本列表，再选择要读取的版本：
content。operation 为 deleted 的版本不返回 content，不能用于恢复：
source 为 api 表示通过 API 写入，为 session 表示由会话写入；source_id 是产生该版本的会话 ID。要找出某次会话产生的变更，筛选 source 为 session 且 source_id 等于该会话 ID 的版本。
历史版本的 content 也是 Base64 编码。恢复文件时，将历史版本的 content 作为新的文件正文写回，并同时传入当前文件的 content_sha256：
content_sha256 并写回历史正文，恢复结果也要逐个确认。
恢复已删除的文件
删除版本不包含正文。要恢复已删除的文件，请读取删除前某个包含正文的版本，再使用该版本的content 和原路径重新创建文件：
memory_id，版本记录从新的 created 版本重新开始；删除前的版本历史仍保留在原 memory_id 下，可继续查询。恢复前应确认历史版本中的 content 未被清除。
删除历史版本正文
如果某个历史版本的正文不再需要保留，可以通过 Redact 接口永久删除正文，仅保留版本元数据：- 只影响所选版本，当前文件和其他版本不受影响；
- 文件当前对应的版本不能删除正文，对已经删除过正文的版本重复执行是空操作；
- 已删除的正文无法恢复，响应中带有
redacted_at的版本不能再用于恢复。
记忆库生命周期
更新记忆库
通过PATCH /v1/memory-stores/{id} 修改记忆库的名称和描述，请求体中未出现的字段保持当前值。已归档的记忆库不能更新。
复制记忆库
复制记忆库目前仅支持在控制台操作，暂不提供 API 接口。在控制台记忆库详情页点击「复制记忆库」，平台会创建一个新记忆库，并将当前库的全部记忆文件复制进去。复制只包含文件的当前内容，不包含历史版本；副本中的文件从新的created 版本开始，并使用新的 memory_id。
归档记忆库
通过POST /v1/memory-stores/{id}/archive 归档不再使用的记忆库，也可以在控制台详情页点击「归档」。归档不可撤销。归档后：
- 记忆库不能挂载到新会话，元数据和记忆文件不能通过 API 修改；
- 文件和版本历史仍可读取，历史版本的正文仍可删除。
删除记忆库
通过DELETE /v1/memory-stores/{id} 永久删除记忆库及其全部文件、版本历史。记忆库的梦境策略一并删除；其持有的触发器改为归档，不再触发，运行记录保留。记忆库必须先归档，且不能绑定任何会话。
相关资源
梦境
按策略整理记忆库，并通过版本记录检查和恢复变更。
会话
了解会话创建以及资源绑定方式。
沙箱规格
查看记忆库挂载路径和沙箱边界。
凭据库
管理会话使用的凭据。