Agent context

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

Agent context is the pre-turn path. It returns a compact, scoped memory packet for an agent before it answers. Use it when you are building an integration and want UnifiedMemory to decide which memories are safe and useful for the next prompt.

Auth

Send a scoped agent key:

Authorization: Bearer $UNIFIED_MEMORY_API_KEY

The key decides the effective agent identity. If the request body tries to pretend to be another agent, the server should ignore or downgrade that value and expose the diagnostic fields.

Path parameters

Name	Required	Description
container_tag	Yes	Memory container. The default first-party container is jeethendra.

Request fields

Field	Required	Type	Default	Description
user_message	Yes	string		The current user message or task.
agent_id	No	string	key metadata	Compatibility field. Key metadata remains authoritative.
app_id	No	string	key metadata	Client app identifier.
run_id	No	string		Current run/session identifier.
source_app	No	string	key metadata	Caller surface such as codex, claude, or hermes.
limit	No	integer	8	Maximum memories to include before budget trimming.
max_context_tokens	No	integer	1200	Target token budget for the context block.
trust_policy	No	string	balanced	Recall trust mode. Use stricter policies for prompt injection.
include_courtroom_links	No	boolean	true	Include Courtroom URLs where available.
metadata	No	object	{}	Integration-specific diagnostics.

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/context

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

Request schema

Schema: AgentContextRequest

Field	Required	Type	Nullable	Default	Constraints
agent_id	No	string	Yes	-	-
app_id	No	string	Yes	-	-
context_tags	No	array of string	Yes	-	-
context_types	No	array of string	Yes	-	-
limit	No	integer	No	8	minimum=1.0, maximum=50.0
max_context_tokens	No	integer	No	1200	minimum=128.0, maximum=8000.0
memory_plane	No	string	Yes	-	-
memory_scope	No	string	Yes	-	-
org_id	No	string	Yes	-	-
request_id	No	string	Yes	-	-
run_id	No	string	Yes	-	-
session_id	No	string	Yes	-	-
tags	No	array of string	Yes	-	-
task_goal	No	string	Yes	-	maxLength=8000
threshold	No	number	No	0.0	minimum=0.0, maximum=1.0
trust_policy	No	string	No	"balanced"	-
user_id	No	string	Yes	-	-
user_message	Yes	string	No	-	minLength=1, maxLength=20000

200 response schema

Schema: AgentContextResponse

Field	Required	Type	Nullable	Default	Constraints
citations	No	array of object	No	-	-
container_tag	Yes	string	No	-	-
diagnostics	No	object	No	-	-
needs_confirmation	No	array of object	No	-	-
prompt_memory_block	No	string	No	""	-
query	Yes	string	No	-	-
suppressed	No	array of object	No	-	-
trust_policy	Yes	string	No	-	-
trusted_context	No	array of object	No	-	-

Example

curl https://edge-api.jithendranara.dev/api/v2/containers/jeethendra/agent/context \
  -H "Authorization: Bearer $UNIFIED_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "user_message": "What should I remember before editing the docs?",
    "source_app": "codex",
    "run_id": "docs-depth-repair",
    "limit": 6,
    "max_context_tokens": 900
  }'

Response shape

{
  "container_tag": "jeethendra",
  "context": "Relevant memory:\n- Docs are hosted at docs.jithendranara.dev...",
  "memories": [
    {
      "id": "mem_docs_surface",
      "content": "Hosted docs are a first-class product surface.",
      "trust_bucket": "trusted",
      "source": "codex",
      "courtroom_url": "/memories?view=courtroom&case=mem_docs_surface"
    }
  ],
  "tokens_injected": 82,
  "suppressed_count": 4,
  "trust_policy": "balanced",
  "effective_agent_id": "codex",
  "effective_source_app": "codex",
  "caller_agent_id_dropped": false
}

Fields may include additional diagnostics such as cross_agent_candidates_suppressed, scope_filter_stage_counts, algorithm_version, and why_recalled.

Common outcomes

Status	Meaning
200	Context assembled. The memories array may be empty if no safe memory exists.
401	Missing or invalid key.
403	Key lacks agent.context or container access.
404	Container not found or not visible to the key.
422	Request validation failed, usually missing user_message.
200 degraded	Context returned with a fallback path; inspect algorithm_fallback_reason if present.

Next steps

• Save useful post-turn outcomes with Writeback.
• Inspect why a memory appeared with Courtroom.