Retain

POST /api/v2/containers/{container_tag}/retain

Retain captures evidence and candidate memory. The runtime classifies junk, extracts atomic claims, and promotes only clean supported facts.

Authentication

Send a scoped UnifiedMemory key:

-H "Authorization: Bearer $UNIFIED_MEMORY_API_KEY"

The key determines the effective workspace, source app, agent identity, and capabilities. Request body agent_id and source_app are diagnostics only when they conflict with key metadata.

Path parameters

Name	Required	Description
container_tag	Yes	Memory container, usually jeethendra for the primary workspace.

Request fields

At least one of content or contents is required.

Field	Type	Default	Notes
content	string	-	Single memory candidate, 1 to 50000 characters.
contents	array	-	Batch form, 1 to 100 content items.
source	string	api	Caller source label.
source_app	string	-	App identity hint; key metadata wins on conflict.
agent_id	string	-	Agent identity hint; key metadata wins on conflict.
app_id	string	-	App/run grouping hint.
run_id	string	-	Run identifier for grouping and audit.
user_id	string	-	User hint when allowed by key scope.
memory_plane	string	-	Common values: personal, task, tool, working.
memory_scope	string	-	Common values: session, user, agent, app, org.
tags	string[]	-	Optional retrieval and proof tags.
metadata	object	-	Additional non-secret provenance.
auto_extract	boolean	true	Whether cognition may extract atomic claims.
review_required	boolean	false	Force human review instead of direct promotion.
review_reason	string	-	Why review is requested.
confidence	number	-	Compatibility-only signal from 0 to 1. Not a trust override.
trust_score	number	-	Compatibility-only signal from 0 to 1. Not a trust override.
expires_in_hours	number	-	Optional positive TTL for short-lived memory.
recall_hint	string	-	Optional hint for future retrieval.
custom_id	string	-	Caller idempotency/reference identifier.
request_id	string	-	Caller request id for tracing.

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}/retain

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

Request schema

Schema: RetainRequest

Field	Required	Type	Nullable	Default	Constraints
agent_id	No	string	Yes	-	-
app_id	No	string	Yes	-	-
auto_extract	No	boolean	No	true	-
capture_kind	No	string	Yes	-	-
confidence	No	number	Yes	-	minimum=0.0, maximum=1.0
content	No	string	Yes	-	minLength=1, maxLength=50000
contents	No	array of RetainContentItem	Yes	-	minItems=1, maxItems=100
custom_id	No	string	Yes	-	-
durability	No	string	Yes	-	-
expires_in_hours	No	number	Yes	-	-
extraction_profile	No	string	Yes	-	-
lifecycle_state	No	string	Yes	-	-
memory_plane	No	string	Yes	-	-
memory_scope	No	string	Yes	-	-
metadata	No	object	Yes	-	-
org_id	No	string	Yes	-	-
promotion_state	No	string	Yes	-	-
recall_hint	No	string	Yes	-	-
request_id	No	string	Yes	-	-
review_reason	No	string	Yes	-	-
review_required	No	boolean	No	false	-
run_id	No	string	Yes	-	-
source	No	string	No	"api"	-
source_app	No	string	Yes	-	-
source_ref	No	string	Yes	-	-
source_type	No	string	Yes	-	-
tags	No	array of string	Yes	-	-
trust_score	No	number	Yes	-	minimum=0.0, maximum=1.0
user_id	No	string	Yes	-	-

200 response schema

Schema: RetainResponse

Field	Required	Type	Nullable	Default	Constraints
container_tag	Yes	string	No	-	-
errors	No	array of object	No	-	-
memories	Yes	array of object	No	-	-
runtime_fanout	No	object	Yes	-	-
saved	Yes	integer	No	-	-

Example

curl -sS https://edge-api.jithendranara.dev/api/v2/containers/jeethendra/retain \
  -H "Authorization: Bearer $UNIFIED_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "content": "The owner prefers MiniMax-backed search first for factual/current queries.",
    "source": "codex",
    "source_app": "codex",
    "agent_id": "codex",
    "memory_plane": "task",
    "memory_scope": "agent",
    "tags": ["search", "preference"]
  }'

Response shape

{
  "container_tag": "jeethendra",
  "saved": 1,
  "committed": true,
  "committed_memory_ids": ["mem_example_123"],
  "enrichment_status": "queued",
  "pending_jobs": ["runtime_lifecycle"],
  "client_retry_safe": false,
  "idempotency_status": "request_id_missing",
  "memories": [
    {
      "id": "mem_example_123",
      "content": "The owner prefers MiniMax-backed search first for factual/current queries.",
      "lifecycle_state": "active",
      "trust_bucket": "needs_review"
    }
  ],
  "errors": [],
  "runtime_fanout": {
    "queued": true,
    "routes": ["distill", "embed", "google_memory_bank_compare"]
  }
}

Required response fields are container_tag, saved, and memories. errors is an array when batch items fail. The acknowledgement fields separate durable commit from slower enrichment:

Field	Meaning
committed	Whether memory rows were durably written before the response.
committed_memory_ids	IDs that are safe to use for follow-up reads, evidence, or Courtroom.
enrichment_status	complete, queued, pending, or not_applicable for slower lifecycle work.
pending_jobs	Async lifecycle/enrichment jobs still running after commit.
client_retry_safe	Whether retrying the same request is safe from the client side. Prefer setting request_id.
idempotency_status	Diagnostic explaining whether a caller request id was present.

runtime_fanout is present when async lifecycle work is queued.

Common outcomes

Status	Meaning
401	Missing or invalid key.
403	Key lacks write capability for this container or source.
409	Write conflicts with lifecycle, review, or scope policy.
422	Request validation failed, such as empty content or invalid field bounds.

Notes

• Retain is additive at the evidence layer. Updates, conflicts, and deletes are represented as reconciliation state, not silent evidence erasure.
• Secret-like strings and test/eval rows are quarantined or forensic-only.
• See Bad candidates and residue before wiring automatic writeback.