Skip to content

docs(topic-memory): align the guide with the shipped generic Artifact APIs - #1690

Merged
Teingi merged 2 commits into
masterfrom
docs/topic-memory-generic-api
Sep 21, 2026
Merged

Teingi merged 2 commits into
masterfrom
docs/topic-memory-generic-api

Conversation

@AlexStocks

Copy link
Copy Markdown
Contributor

Which issue or RFC does this PR close?

Closes #1685.

Rationale for this change

docs/{en,zh}/docs/workflows/topic-memory.md told readers that Topic Memory has no generic create, update, delete, or retire endpoint and is not in the Taggable Artifact family list. Neither claim holds for the contract at powercontext-v1.1.0: CreateTopicMemoryArtifactRequest and ReplaceTopicMemoryArtifactRequest accept topic-memory, ArtifactReadFamily covers all seven families, and publish_artifact supports Topic Memory. docs/{en,zh}/docs/workflows/artifacts.md repeated the same read-only claim.

Guidance that contradicts the interface it documents is worse than missing guidance: it tells integrators that shipped capabilities do not exist.

What changes are included in this PR?

  • Replace the two stale boundary bullets with what the interfaces actually refuse: there is no delete or retire operation, and the head advances through background processing or an explicit write.
  • Add a "Write through the generic Artifact interfaces" section covering the create, replace, head/revision read, and tag routes, the scope.contribute requirement for creation, the fact that submitted content skips semantic generation and commits together with the head, chunks, and retrieval indexes, the If-Match requirement for replacement, and the dual scope.admin requirement for cross-Scope publication, which does not copy tags or direct Sources.
  • Drop "read-oriented" from the opening description and mention the generic write path there.
  • Correct the same claim in docs/{en,zh}/docs/workflows/artifacts.md, and add Topic Memory to its family list and per-family workflow list.

docs/{en,zh}/docs/rfcs/ is left untouched. Those documents record the boundary as it stood when they were written, and a later RFC supersedes them.

Are there any user-facing changes?

Documentation only. No behaviour, API, or persisted-format change.

How was this change tested?

  • Contract, openapi/powercontext.yaml: create_artifact (POST /v1/scopes/{scope_id}/artifacts), replace_artifact, get_artifact_revision, list_artifact_revisions, and publish_artifact (POST /v1/artifact-publications). CreateTopicMemoryArtifactRequest requires family = topic-memory with TopicMemoryWriteContent (title, summary, detail), and create_artifact documents that Topic Memory accepts complete text without semantic generation and commits its active head, chunks, and retrieval indexes atomically.
  • Confirmed the contract defines no DELETE operation at all and that retire exists only for Memory entries (/v1/memory/entries/retire), so the remaining boundary bullet states what is genuinely refused.
  • Family list: BaseArtifactFamily in src/powercontext/builtin/records.py covers all seven families including topic-memory.
  • Every route, permission, and request field in the new section was read from the contract rather than inferred.
  • Cross-checked the two locales.

AI usage statement

Built with an AI assistant (WorkBuddy), which read the contract and sources, drafted both locales, and verified each route and permission above. Claims that could not be confirmed from the contract or code were removed rather than softened.

… APIs

`docs/{en,zh}/docs/workflows/topic-memory.md` told readers that Topic Memory has no
generic create, update, delete, or retire endpoint and is not in the taggable family
list. Both claims contradict the contract and code shipped in v1.1.0:
`CreateTopicMemoryArtifactRequest` and `ReplaceTopicMemoryArtifactRequest` accept
`topic-memory`, `ArtifactReadFamily` covers all seven families, and `publish_artifact`
supports Topic Memory.

Document the generic write, revision, tag, and publication paths, replace the two stale
boundary bullets with what the interfaces actually refuse, and correct the same
read-only claim in `docs/{en,zh}/docs/workflows/artifacts.md`.

@Teingi Teingi left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

One non-blocking documentation clarification.

Comment thread docs/en/docs/workflows/topic-memory.md Outdated
@AlexStocks

Copy link
Copy Markdown
Contributor Author

@Teingi I have completed all works which related to your comment. Please review again.

@Teingi Teingi left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@Teingi
Teingi merged commit cca0499 into master Sep 21, 2026
22 checks passed
@PsiACE
PsiACE deleted the docs/topic-memory-generic-api branch September 28, 2026 03:05
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

bug: Topic Memory guide contradicts the generic Artifact APIs and tag support it ships with

2 participants