Writeback

POST /api/v2/containers/{container_tag}/agent/writeback

Writeback is the post-turn capture path. Agents should call it after a useful turn to submit durable outcomes, decisions, preferences, artifacts, or extracted facts. UnifiedMemory stores evidence first, rejects residue, and promotes only safe memory through lifecycle and trust gates.

Auth

Use a scoped key with agent.writeback and any required memory write capabilities.

Authorization: Bearer $UNIFIED_MEMORY_API_KEY

The stored source_app, agent_id, and visibility scope come from key metadata. Caller-supplied identity is diagnostic only when it conflicts.

Request fields

Field	Required	Type	Default	Description
observed_facts	No	string[]	[]	Atomic facts observed during the turn.
decisions	No	string[]	[]	Durable decisions or chosen approaches.
preferences	No	string[]	[]	User preferences worth remembering.
artifacts	No	object[]	[]	Files, links, or outputs worth tracking.
auto_extract	No	boolean	false	Ask cognition to extract atomic claims from supplied content.
source	No	string	agent_runtime	Source label for this writeback event.
agent_id	No	string	key metadata	Compatibility-only identity hint.
app_id	No	string	key metadata	Compatibility-only app hint.
run_id	No	string		Run/session identifier.
default_confidence	No	number	0.82	Compatibility signal. Cannot create trusted memory alone.
default_trust_score	No	number	0.8	Compatibility signal. Trust bucket gates remain authoritative.
metadata	No	object	{}	Integration-specific evidence metadata.

Schema from OpenAPI

This section is generated from /openapi.public.json. Edit the OpenAPI source or generator, not this block.

POST /api/v2/containers/{container_tag}/agent/writeback

• Operation ID: agent_memory_writeback_api_v2_containers__container_tag__agent_writeback_post
• Declared response statuses: 200, 422

Request schema

Schema: AgentWritebackRequest

Field	Required	Type	Nullable	Default	Constraints
agent_id	No	string	Yes	-	-
app_id	No	string	Yes	-	-
artifacts	No	array of string or AgentMemoryCandidate	No	-	-
assistant_response	No	string	Yes	-	maxLength=50000
auto_extract	No	boolean	No	false	-
decisions	No	array of string or AgentMemoryCandidate	No	-	-
default_confidence	No	number	No	0.82	minimum=0.0, maximum=1.0
default_trust_score	No	number	No	0.8	minimum=0.0, maximum=1.0
observed_facts	No	array of string or AgentMemoryCandidate	No	-	-
org_id	No	string	Yes	-	-
preferences	No	array of string or AgentMemoryCandidate	No	-	-
request_id	No	string	Yes	-	-
review_required	No	boolean	No	false	-
run_id	No	string	Yes	-	-
session_id	No	string	Yes	-	-
source	No	string	No	"agent_runtime"	-
user_id	No	string	Yes	-	-
user_message	No	string	Yes	-	maxLength=20000

200 response schema

Schema: AgentWritebackResponse

Field	Required	Type	Nullable	Default	Constraints
container_tag	Yes	string	No	-	-
dedupe_supersession_decisions	No	array of object	No	-	-
diagnostics	No	object	No	-	-
operation_trail_id	Yes	string	No	-	-
retained_memories	No	array of object	No	-	-
review_required_items	No	array of object	No	-	-
skipped_candidates	No	array of object	No	-	-

Example

curl https://edge-api.jithendranara.dev/api/v2/containers/jeethendra/agent/writeback \
  -H "Authorization: Bearer $UNIFIED_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "decisions": [
      "Hosted docs API pages should be handwritten before adding generated Scalar or Redoc."
    ],
    "observed_facts": [
      "Docusaurus local search is enabled with @easyops-cn/docusaurus-search-local."
    ],
    "source": "codex",
    "run_id": "docs-depth-repair"
  }'

Response shape

{
  "container_tag": "jeethendra",
  "operation_trail_id": "docs-depth-repair",
  "committed": true,
  "committed_memory_ids": ["mem_01"],
  "enrichment_status": "pending",
  "pending_jobs": ["profile_atomic_merge"],
  "client_retry_safe": true,
  "idempotency_status": "request_id_recorded",
  "retained_memories": [
    {
      "id": "mem_01",
      "content": "Hosted docs API pages should be handwritten before adding generated API UI.",
      "lifecycle_state": "pending",
      "trust_bucket": "needs_review",
      "next_action": "review"
    }
  ],
  "skipped_candidates": [],
  "review_required_items": [],
  "diagnostics": {
    "committed": true,
    "retained_count": 1
  },
  "effective_identity": {
    "source_app": "codex",
    "agent_id": "codex",
    "agent_scope": "own"
  },
  "stored_visibility_scope": "private_agent",
  "sharing_eligible": false,
  "sharing_blocked_reason": "pending_review"
}

The commit acknowledgement fields have the same meaning as retain: committed and committed_memory_ids describe durable writes, while enrichment_status and pending_jobs describe slower post-commit work such as profile merge or cognitive promotion. When possible, send request_id so client_retry_safe can be true after client timeouts.

Common outcomes

Status	Meaning
200	Writeback processed. Some items may be quarantined or rejected.
401	Missing or invalid key.
403	Key lacks writeback capability.
404	Container is not visible to the key.
409	Conflicting current fact requires review or supersession.
422	Payload validation failed.
200 degraded	Heavy cognition unavailable; deterministic admission still runs.

Bad candidates

Do not write back raw transcript blocks, full assistant answers, greetings, emoji-only messages, secrets, smoke/eval rows, or lifecycle logs as normal memory. See Bad candidates and residue.