diff --git a/docs/en/docs/workflows/artifacts.md b/docs/en/docs/workflows/artifacts.md index d6f12c7ff..1096afeed 100644 --- a/docs/en/docs/workflows/artifacts.md +++ b/docs/en/docs/workflows/artifacts.md @@ -5,8 +5,8 @@ description: Read current and historical revisions, then choose the write workfl # Manage Artifacts -Artifacts preserve versioned results. Memory, Experience, Skill, Handoff, Profile, and Prompt have family-specific write rules; -sharing a REST envelope does not make those workflows interchangeable. +Artifacts preserve versioned results. Memory, Topic Memory, Experience, Skill, Handoff, Profile, and Prompt have +family-specific write rules; sharing a REST envelope does not make those workflows interchangeable. ## Create and replace @@ -44,11 +44,14 @@ The Python Client exposes this field as a string; use it directly instead of acc See the [complete HTTP API reference](/api/) for request fields, response models, and interactive operation examples. For authentication, concurrency control, and common call flows, see the [HTTP API guide](../develop/http-api.md). -Topic Memory is currently a specialized read-only retrieval view and does not use the generic write operations above. +Topic Memory also uses these generic interfaces: creation and replacement submit complete `title`, `summary`, and +`detail` text without semantic generation. See [Use Topic Memory](topic-memory.md) for its dedicated search and scoped +reads. ## Change content through its workflow - [Memory](memory-and-context.md): explicitly write, revise, or retire entries. +- [Topic Memory](topic-memory.md): submit complete topic content directly, or read a topic by exact Revision. - [Experience and Skill](experience-and-skill-lifecycle.md): inspect and approve Candidates before publication or export. - [Handoff](handoff-with-codex.md): inspect and commit the current work boundary. - [Prompt](manage-prompts.md): customize operation guidance within one Scope. diff --git a/docs/en/docs/workflows/topic-memory.md b/docs/en/docs/workflows/topic-memory.md index 834ef8a04..fd1e04585 100644 --- a/docs/en/docs/workflows/topic-memory.md +++ b/docs/en/docs/workflows/topic-memory.md @@ -5,9 +5,10 @@ description: Search topic summaries produced from long-running Sources and read # Use Topic Memory -Topic Memory is a read-oriented Artifact family for long-running topics. It turns accumulated Sources in one Scope into a -`title`, `summary`, and progressively disclosed `detail`, so an Agent can locate a topic first and read the full detail only -when needed. It does not replace Memory, Experience, Skill, or Handoff. +Topic Memory is an Artifact family for long-running topics. It turns accumulated Sources in one Scope into a `title`, +`summary`, and progressively disclosed `detail`, so an Agent can locate a topic first and read the full detail only +when needed; callers can also submit complete topic content directly through the generic interfaces in +[Manage Artifacts](artifacts.md). It does not replace Memory, Experience, Skill, or Handoff. Topic Memory is Scope-local. Capturing a Source does not synchronously create a topic; configured background processing must advance it. @@ -132,6 +133,31 @@ Content-Type: application/json The response contains `title`, `summary`, full `detail`, and `source_refs`. Even after the current topic head advances, the exact reference resolves to the same historical Revision for audit, citation, and progressive disclosure. +## Write through the generic Artifact interfaces + +Besides Source processing, Topic Memory also uses the generic interfaces in [Manage Artifacts](artifacts.md): + +| Operation | Route | +| --- | --- | +| Create | `POST /v1/scopes/{scope_id}/artifacts` (`family` is `topic-memory`) | +| Replace | `PUT /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id}` | +| List heads | `GET /v1/scopes/{scope_id}/artifacts/{family}` | +| Read a head, list revisions, read an exact revision | `GET /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id}`, `.../revisions`, `.../revisions/{revision}` | +| Read, replace, and query tags | `GET`/`PUT /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id}/tags`, `POST /v1/scopes/{scope_id}/artifact-tags/query` | + +Creation requires `scope.contribute` on the target Scope, and the request body carries the complete `title`, `summary`, +and `detail`. The content skips semantic generation: topic content, the current head, chunks, and the retrieval indexes +enabled by the deployment are committed in one operation, so generic reads and the dedicated search see the same topic +version. A replace requires current `scope.admin` access, creates the next immutable Revision, and must carry the current +head's `If-Match`. + +Manage tags as described in [Organize with tags](manage-artifact-tags.md); whole-Artifact Topic Memory tags are +read with `scope.read` and modified with `scope.admin`. + +Publish one exact Revision into another Scope with `POST /v1/artifact-publications`, which requires `scope.admin` in +both the source and target Scopes. Publication creates an independent identity in the target Scope and carries its +retrieval indexes; tags and direct Sources are not copied. + ## Assemble into PreparedContext To inject topic summaries into one Agent turn, add `topic-memory` explicitly to `assembly` in @@ -164,8 +190,7 @@ HTTP-only and is not exposed as an MCP tool. ## Current boundaries -- There is no generic Topic Memory create, update, delete, or retire endpoint; topics are generated from Sources and stored as immutable Revisions. -- Topic Memory is not in the current Taggable Artifact family list, so Memory, Experience, Skill, and Handoff tag APIs do not apply. +- The generic interfaces do not accept Topic Memory delete or retire operations; topics are stored as immutable Revisions, and background processing or an explicit write advances the current head. - Source capture does not synchronously generate a topic; background processing and the required generation capability are needed. - Backups, recovery, worker availability, and retrieval failures belong to [deployment and operations](../operate/index.md), not this lifecycle. diff --git a/docs/zh/docs/workflows/artifacts.md b/docs/zh/docs/workflows/artifacts.md index 8c9ce9ba6..f8c711571 100644 --- a/docs/zh/docs/workflows/artifacts.md +++ b/docs/zh/docs/workflows/artifacts.md @@ -5,7 +5,7 @@ description: 读取当前与历史版本,并按 Artifact 家族选择修改方 # 管理 Artifact -Artifact 保存有版本的结果。Memory、Experience、Skill、Handoff、Profile 和 Prompt 各自有不同的写入规则; +Artifact 保存有版本的结果。Memory、Topic Memory、Experience、Skill、Handoff、Profile 和 Prompt 各自有不同的写入规则; 共用 REST 外层结构不意味着可以互换这些工作流。 ## 创建和替换 @@ -42,11 +42,13 @@ Python Client 将该字段表示为字符串,请直接使用,不再访问枚 完整的请求字段、响应模型和可调试的接口示例请参阅[完整 HTTP API 参考](/api/)。 接口鉴权、并发控制和常用调用流程见 [HTTP API 使用说明](../develop/http-api.md)。 -Topic Memory 当前是专用的只读检索视图,不使用上述通用写接口。 +Topic Memory 也使用上述通用接口:创建和整体替换提交完整的 `title`、`summary` 和 `detail`,内容不经过语义生成。 +它的专用搜索和范围化读取见[使用 Topic Memory](topic-memory.md)。 ## 按对应工作流修改 - [Memory](memory-and-context.md):显式写入、修订或退役条目。 +- [Topic Memory](topic-memory.md):直接提交完整主题内容,或按精确 Revision 读取主题。 - [Experience 与 Skill](experience-and-skill-lifecycle.md):发布或导出前检查并批准 Candidate。 - [Handoff](handoff-with-codex.md):检查并提交当前工作边界。 - [Prompt](manage-prompts.md):在一个 Scope 内自定义操作提示词。 diff --git a/docs/zh/docs/workflows/topic-memory.md b/docs/zh/docs/workflows/topic-memory.md index cc9453199..96909af27 100644 --- a/docs/zh/docs/workflows/topic-memory.md +++ b/docs/zh/docs/workflows/topic-memory.md @@ -5,9 +5,9 @@ description: 从长期 Source 处理中查找主题摘要,并按精确 Revisio # 使用 Topic Memory -Topic Memory 是面向长期主题的只读检索型 Artifact family。它把一个 Scope 中持续累积的 Source 处理成 -`title`、`summary` 和渐进式展开的 `detail`,适合先定位主题、再按需读取全文;它不替代 Memory、Experience、Skill -或 Handoff。 +Topic Memory 是面向长期主题的 Artifact family。它把一个 Scope 中持续累积的 Source 处理成 `title`、`summary` +和渐进式展开的 `detail`,适合先定位主题、再按需读取全文;调用方也可以按[管理 Artifact](artifacts.md)中的通用接口 +直接提交完整主题内容。它不替代 Memory、Experience、Skill 或 Handoff。 Topic Memory 只属于当前 Scope。Source 被采集后不会同步生成主题,必须由已配置的后台处理能力推进。 @@ -122,6 +122,29 @@ Content-Type: application/json 响应包含 `title`、`summary`、完整 `detail` 和 `source_refs`。即使主题的当前 head 后续前进,精确引用仍指向同一 历史 Revision,适合审计、引用和渐进式 disclosure。 +## 通过通用 Artifact 接口写入 + +除 Source 处理外,Topic Memory 也使用[管理 Artifact](artifacts.md)中的通用接口: + +| 操作 | 路由 | +| --- | --- | +| 创建 | `POST /v1/scopes/{scope_id}/artifacts`(`family` 为 `topic-memory`) | +| 整体替换 | `PUT /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id}` | +| 列举 head | `GET /v1/scopes/{scope_id}/artifacts/{family}` | +| 读取 head、列举修订、读取精确修订 | `GET /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id}`、`.../revisions`、`.../revisions/{revision}` | +| 标签读写与查询 | `GET`/`PUT /v1/scopes/{scope_id}/artifacts/{family}/{artifact_id}/tags`、`POST /v1/scopes/{scope_id}/artifact-tags/query` | + +创建需要目标 Scope 的 `scope.contribute` 权限,请求体提交完整的 `title`、`summary` 和 `detail`。内容不经过语义 +生成,主题内容、当前 head、分块和当前部署启用的检索索引会在同一次提交内完成,因此通用读取和专用检索看到的是同一个 +主题版本。整体替换需要当前 Scope 的 `scope.admin` 权限,生成下一条不可变 Revision,并且必须携带当前 head 的 +`If-Match`。 + +标签按[使用标签整理内容](manage-artifact-tags.md)管理;Topic Memory 的整体标签使用 `scope.read` 读取、 +`scope.admin` 修改。 + +把某个精确 Revision 发布到另一个 Scope 使用 `POST /v1/artifact-publications`,需要源 Scope 和目标 Scope 的 +`scope.admin` 权限。发布会在目标 Scope 中创建独立身份并携带其检索索引;标签和直接 Source 不会复制。 + ## 组装到 PreparedContext 需要把主题摘要注入一次 Agent turn 时,在 `POST /v1/context/prepare` 的 `assembly` 中显式加入 @@ -151,8 +174,7 @@ MCP 暴露只读的 `search_topic_memory` 和 `get_topic_memory` 工具。Agent ## 当前边界 -- 没有通用的 Topic Memory create、update、delete 或 retire 接口;主题由 Source 处理产生,并以不可变 Revision 保存。 -- Topic Memory 不在当前 Taggable Artifact family 列表中,不能套用 Memory、Experience、Skill 或 Handoff 的标签接口。 +- 通用接口不接受 Topic Memory delete 或 retire 操作;主题以不可变 Revision 保存,当前 head 由后台处理或显式写入推进。 - Source capture 不会同步生成主题;需要后台处理和相应的生成能力。 - 备份、恢复、worker 可用性和检索故障属于[部署与运维](../operate/index.md),不是本生命周期的一部分。