Reflect

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

Reflect recalls eligible memory, assembles bounded context, and returns a grounded answer. It is useful for applications that want UnifiedMemory to do both memory retrieval and answer synthesis.

Reflect does not silently save the generated answer. Use Writeback for durable post-turn capture.

Request fields

Field	Required	Type	Default	Description
query	Yes	string		Question to answer with memory.
answer_mode	No	string	grounded	Synthesis style. Grounded mode should cite memory context.
recall_limit	No	integer	6	Number of memory candidates to retrieve.
trust_policy	No	string	balanced	Trust policy for recall.
max_tokens	No	integer	1200	Output budget.
temperature	No	number	0.35	Synthesis temperature.
save_memory	No	boolean	false	Whether to create a separate memory candidate from the reflection.
metadata	No	object	{}	Integration-specific request 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}/reflect

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

Request schema

Schema: ReflectRequest

Field	Required	Type	Nullable	Default	Constraints
agent_id	No	string	Yes	-	-
answer_mode	No	string	No	"grounded"	-
app_id	No	string	Yes	-	-
context	No	string	Yes	-	-
context_tags	No	array of string	Yes	-	-
context_types	No	array of string	Yes	-	-
max_tokens	No	integer	No	1200	minimum=128.0, maximum=4096.0
memory_plane	No	string	Yes	-	-
memory_scope	No	string	Yes	-	-
org_id	No	string	Yes	-	-
priority_ids	No	array of string	Yes	-	-
query	Yes	string	No	-	minLength=1
recall_limit	No	integer	No	6	minimum=3.0, maximum=12.0
request_id	No	string	Yes	-	-
rewrite_context	No	boolean	No	true	-
run_id	No	string	Yes	-	-
save_memory	No	boolean	No	false	-
source_app	No	string	Yes	-	-
temperature	No	number	No	0.35	minimum=0.0, maximum=1.0
user_id	No	string	Yes	-	-

200 response schema

Schema: ReflectResponse

Field	Required	Type	Nullable	Default	Constraints
container_tag	Yes	string	No	-	-
diagnostics	No	object	No	-	-
memory_capture	No	object	Yes	-	-
model	No	string	Yes	-	-
query	Yes	string	No	-	-
recall_context	No	string	No	""	-
reply	Yes	string	No	-	-
sources	No	array of object	No	-	-
usage	No	object	No	-	-

Example

curl https://edge-api.jithendranara.dev/api/v2/containers/jeethendra/reflect \
  -H "Authorization: Bearer $UNIFIED_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "How should agents decide what to retain?",
    "answer_mode": "grounded",
    "recall_limit": 5
  }'

Response shape

{
  "answer": "Agents should retain atomic facts, decisions, tool outcomes, and durable preferences. They should avoid raw transcripts and assistant dumps.",
  "memories": [
    {
      "id": "mem_bad_candidates",
      "content": "Full assistant answer dumps should be forensic residue unless atomic outcomes are extracted.",
      "trust_bucket": "trusted"
    }
  ],
  "citations": [
    {
      "memory_id": "mem_bad_candidates",
      "courtroom_url": "/memories?view=courtroom&case=mem_bad_candidates"
    }
  ],
  "tokens_injected": 112,
  "trust_policy": "balanced",
  "saved_memory_id": null
}

Common outcomes

Status	Meaning
200	Reflection completed.
401	Missing or invalid key.
403	Key lacks recall/reflect capability.
404	Container not found or not visible.
422	Missing or invalid query.
200 degraded	Synthesis provider unavailable; response may include recall context and an unavailable status.

Next steps

• Use Recall when the caller wants memory context only.
• Use Courtroom when an answer depends on a disputed memory.