Manage Artifacts

Artifacts preserve versioned results. Atomic 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

Artifact management primarily uses the following two write operations. Both create an immutable Revision and return the new head and its ETag:

The request body is a discriminated union by family; content from one family cannot be submitted to another. Atomic Memory submits complete kind and text content. Legacy family=memory collection Create/Replace returns 422 legacy_memory_operation_unsupported. Handoff is a Scope singleton: Create returns 409 when it already exists, so use Replace instead. Missing If-Match returns 428; a stale ETag returns 412. The API does not perform automatic merging.

Inspect current and historical content

Use the scoped HTTP routes in the API contract:

Keep the family, Artifact ID, and exact Revision when citing a result or handing it to another Agent. The current head can advance while a historical Revision remains unchanged.

Name an exact revision with a stable handle

A stable handle gives one exact Artifact Revision a human-readable, Scope-local name. Bind it with PUT /v1/scopes/{scope_id}/artifact-handles/{family}/{key} and resolve it with GET on the same route.

Bindings are permanent. After (scope_id, family, key) is committed, it cannot be updated, released, or deleted. Repeating the same binding is idempotent; binding the key to another Artifact Revision returns 409 Conflict. Verify the family, Artifact ID, Revision, and key before binding. If a key is bound by mistake, choose a new key.

Artifact sources preserve each source's source_type and source_id, including dynamically registered types such as note. Treat source_type as an open Source name when reading lists, details, and historical revisions. Source IDs retain accepted Unicode characters and interior spaces, such as 用户偏好 and release notes. The Python Client exposes this field as a string; use it directly instead of accessing an enum's .value.

See the complete HTTP API reference for request fields, response models, and interactive operation examples. For authentication, concurrency control, and common call flows, see the HTTP API guide. Topic Memory also uses these generic interfaces: creation and replacement submit complete title, summary, and detail text without semantic generation. See Use Topic Memory for its dedicated search and scoped reads.

Search relevant current heads

Use POST /v1/scopes/{scope_id}/artifacts/{family}/search for relevance search within one Scope. The built-in route supports Experience, managed Skill, Topic Memory, and Atomic Memory. Results contain complete content and exact revisions; optional scores belong to the search response. See Search Artifacts for Family support, admission, thresholds, and failure behavior, and Fusion algorithms and parameters for Topic and Atomic RRF controls.

Change content through its workflow

• Atomic Memory: create, replace, forget, merge and restore independent memories.
• Topic Memory: submit complete topic content directly, or read a topic by exact Revision.
• Experience and Skill: inspect and approve Candidates before publication or export.
• Handoff: inspect and commit the current work boundary.
• Prompt: customize operation guidance within one Scope.
• Tags: organize logical Artifacts; old Memory entry targets map to migrated Artifacts.

For direct REST replacement, read the current ETag and send it in If-Match. Missing preconditions return 428; a stale head returns 412. Reload and reconcile the content before retrying. Candidate review uses its own expected_version contract instead. Access checks apply to the selected target in both cases.