Recall

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

Recall returns governed memory results and optional prompt-ready context. For normal current recall, current_state is a validity/versioning signal, not a relevance signal. A result must clear the system relevance floor through semantic, indexed keyword, entity, graph, profile, or focused exact lexical evidence. If nothing clears the floor, UnifiedMemory returns an empty result set with diagnostics.abstained=true instead of unrelated top-k filler. An exact current-state row that is only surfaced by temporal/currentness, and not by semantic, keyword/entity index, graph/profile evidence, or focused lexical matching, can still abstain; currentness alone is not relevance.

Authentication

-H "Authorization: Bearer $UNIFIED_MEMORY_API_KEY"

The key determines effective identity. Non-admin callers cannot widen scope by passing another agent_id or another source_app.

Path parameters

Name	Required	Description
container_tag	Yes	Memory container to search.

Request fields

Field	Type	Default	Notes
query	string	required	Natural-language recall query.
limit	integer	10	1 to 100 results.
mode	string	hybrid	Retrieval mode.
threshold	number	0.0	Additional caller relevance floor. 0.0 means use the system minimum, currently 0.10; it does not disable abstention.
trust_policy	string	off	Use balanced or strict for prompt-facing recall.
include_trust_report	boolean	false	Attach inline trust verdict/action fields.
view	string	assistant	Assistant-facing view applies hard suppression.
memory_plane	string	-	Filter by personal, task, tool, or working.
memory_scope	string	-	Filter by session, user, agent, app, or org.
memory_type	string	-	Filter by memory type when available.
tags	string[]	-	Include matching tags.
exclude_tags	string[]	-	Exclude matching tags.
tag_mode	string	all	Tag matching mode.
tag_match	string	exact	Tag matching strategy.
created_after / created_before	string	-	Time filters.
source / source_app	string	-	Source filters.
agent_id, app_id, run_id, user_id, org_id	string	-	Identity hints constrained by key metadata.
graph_traversal	boolean	true	Allow relationship expansion after eligibility checks.
graph_max_hops	integer	2	1 to 5 hops.
rewrite_query / rewrite_context	boolean	false	Optional query/context rewriting.
rerank	boolean	false	Optional reranking.
priority_ids	string[]	-	Prefer specific memory ids when eligible.
time_query	string	-	Temporal intent hint, such as current or historical.

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

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

Request schema

Schema: RecallRequest

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	-	-
created_after	No	string	Yes	-	-
created_before	No	string	Yes	-	-
exclude_tags	No	array of string	Yes	-	-
graph_max_hops	No	integer	No	2	minimum=1.0, maximum=5.0
graph_traversal	No	boolean	No	true	-
include_trust_report	No	boolean	No	false	-
limit	No	integer	No	10	minimum=1.0, maximum=100.0
memory_plane	No	string	Yes	-	-
memory_scope	No	string	Yes	-	-
memory_type	No	string	Yes	-	-
mode	No	string	No	"hybrid"	-
org_id	No	string	Yes	-	-
priority_ids	No	array of string	Yes	-	-
query	Yes	string	No	-	minLength=1
request_id	No	string	Yes	-	-
rerank	No	boolean	No	false	-
reranking_backend	No	string	Yes	-	-
rewrite_context	No	boolean	No	false	-
rewrite_query	No	boolean	No	false	-
run_id	No	string	Yes	-	-
sort	No	string	No	"score"	-
source	No	string	Yes	-	-
source_app	No	string	Yes	-	-
tag_match	No	string	No	"exact"	-
tag_mode	No	string	No	"all"	-
tags	No	array of string	Yes	-	-
threshold	No	number	No	0.0	minimum=0.0, maximum=1.0
time_query	No	string	Yes	-	-
trust_policy	No	string	No	"off"	-
user_id	No	string	Yes	-	-
view	No	string	No	"assistant"	-

200 response schema

Schema: RecallResponse

Field	Required	Type	Nullable	Default	Constraints
container_tag	Yes	string	No	-	-
diagnostics	No	object	No	-	-
expanded_query	No	string	Yes	-	-
mode	Yes	string	No	-	-
needs_confirmation	No	array of object	No	-	-
original_query	No	string	Yes	-	-
query	Yes	string	No	-	-
recall_context	No	string	No	""	-
results	Yes	array of object	No	-	-
suppressed	No	array of object	No	-	-
total	Yes	integer	No	-	-
trust_diagnostics	No	object	No	-	-
trust_policy	No	string	No	"off"	-

Example

curl -sS https://edge-api.jithendranara.dev/api/v2/containers/jeethendra/recall \
  -H "Authorization: Bearer $UNIFIED_MEMORY_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "query": "What search tool should I use first?",
    "limit": 5,
    "trust_policy": "balanced",
    "include_trust_report": true
  }'

Response shape

{
  "container_tag": "jeethendra",
  "query": "What search tool should I use first?",
  "mode": "hybrid",
  "results": [
    {
      "id": "mem_example_123",
      "content": "The owner prefers MiniMax-backed search first for factual/current queries.",
      "score": 0.91,
      "relevance_score": 0.91,
      "answer_relevance_score": 0.91,
      "answer_match_type": "direct_answer",
      "direct_answer": true,
      "trust_bucket": "trusted",
      "why_recalled": {
        "signals": ["keyword", "semantic", "entity", "profile"],
        "relevance_signals": ["keyword", "semantic", "entity", "profile"],
        "relevance_score": 0.91,
        "answer_match_type": "direct_answer",
        "direct_answer": true,
        "min_relevance_threshold": 0.1,
        "current_state_only": false,
        "lexical_overlap": 0.5,
        "entity_hits": 1,
        "profile_hits": 1,
        "trust_policy_applied": "balanced",
        "scope": "own-agent plus canonical owner fact"
      },
      "courtroom_url": "/api/v1/memories/mem_example_123/courtroom"
    }
  ],
  "related_context": [],
  "total": 1,
  "suppressed": [],
  "needs_confirmation": [],
  "recall_context": "Search preference: MiniMax-backed search first for factual/current queries.",
  "trust_policy": "balanced",
  "diagnostics": {
    "candidate_sources": ["semantic", "keyword", "entity", "profile", "graph"],
    "cross_agent_candidates_suppressed": 0,
    "trust_policy_applied": "balanced",
    "strict_suppressed_count": 0,
    "balanced_caution_count": 0,
    "current_state_only_top1": false,
    "fallback_reason": null,
    "abstained": false,
    "min_relevance_threshold": 0.1,
    "source_health_status": "healthy_multi_signal",
    "semantic_count": 4,
    "keyword_count": 2,
    "entity_count": 1,
    "profile_count": 1,
    "lexical_count": 6,
    "entity_hits_merged": 1,
    "entity_signal_promoted_count": 1,
    "profile_intent_detected": "location",
    "single_signal_keyword_suppressed_count": 0,
    "stale_suppressed_count": 0,
    "weak_lexical_suppressed_count": 0,
    "weak_keyword_suppressed_count": 0,
    "direct_answer_count": 1,
    "supporting_context_count": 0,
    "tangential_context_count": 0,
    "tangential_suppressed_count": 0
  },
  "trust_diagnostics": {}
}

Required response fields are container_tag, query, mode, results, and total. results is the direct-answer lane. related_context may include safe adjacent memories that passed relevance and trust gates but did not answer the query directly; those records are explanatory context, not prompt-injected answers. suppressed, needs_confirmation, diagnostics, trust_diagnostics, and recall_context explain filtering and prompt assembly.

Related context without a direct answer

When UnifiedMemory finds safe but tangential/supporting memories, it abstains in the answer lane and returns them separately:

{
  "results": [],
  "related_context": [
    {
      "id": "mem_related_123",
      "content": "The team keeps a deployment checklist and a separate incident-review runbook.",
      "answer_match_type": "supporting_context",
      "direct_answer": false,
      "relevance_score": 0.8,
      "why_recalled": {
        "relevance_signals": ["semantic"],
        "answer_match_type": "supporting_context",
        "direct_answer": false
      }
    }
  ],
  "diagnostics": {
    "abstained": true,
    "fallback_reason": "no_direct_answer_above_threshold",
    "supporting_context_count": 1,
    "tangential_context_count": 0
  }
}

Abstention response

{
  "container_tag": "jeethendra",
  "query": "sourdough starter hydration schedule",
  "mode": "hybrid",
  "results": [],
  "total": 0,
  "diagnostics": {
    "abstained": true,
    "fallback_reason": "no_relevant_candidates_above_threshold",
    "min_relevance_threshold": 0.1,
    "source_health_status": "degraded_no_primary_sources",
    "semantic_count": 0,
    "keyword_count": 0,
    "entity_count": 0,
    "profile_count": 0,
    "lexical_count": 12,
    "single_signal_keyword_suppressed_count": 0,
    "weak_lexical_suppressed_count": 12,
    "weak_keyword_suppressed_count": 0
  }
}

Common outcomes

Status	Meaning
401	Missing or invalid key.
403	Key lacks read capability for this container or view.
404	Container or requested priority memory is unavailable to the caller.
422	Request validation failed, such as empty query or invalid limit.

Recall safety

Current assistant recall excludes forensic/test/eval/system-generated rows, secret-like records, wrong-agent working memory, stale/superseded facts unless a historical query asks for them, unresolved conflicts, and rows hidden by review or quarantine.

Next steps

• Use Agent context when building a prompt.
• Use Courtroom to inspect evidence for a result.