---
title: "Unified episodic memory retrieval — routes across active and passive tiers"
method: POST
path: "/memory/retrieve"
tags: ["memory"]
---

# Unified episodic memory retrieval — routes across active and passive tiers

`POST /memory/retrieve`

## Request

- Base URL: `https://api.getmetacognition.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.getmetacognition.com/memory/retrieve`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/metacognition/apis/tex-api/docs/memory/retrieve/post.ts> (a function with typed inputs; its response is checked against the schema)

Embed ``body.query_text``, consult the Episode Registry, then query the
appropriate backends in parallel:

* **ACTIVE episodes**  → ``POST /retrieve/active`` on the Cloudflare Worker.
  Returns per-fragment cosine hits + KV-hydrated text.  Hits receive a
  +0.15 recency boost before ranking.

* **PASSIVE episodes** → HelixDB ``EPISODE_SUMMARY`` nodes (GET /nodes, on
  the caller's scoped token), ranked by cosine similarity. Scored as-is.

Results from both tiers are merged, sorted by final score descending, and
the top ``body.top_k`` hits are returned with a ``source`` annotation.

Each tier is queried independently — a failure in one tier surfaces as a
warning log and the other tier's results are still returned.

## Request body

- MemoryRetrieveRequest: Unified episodic memory retrieval request. Routes automatically across two memory tiers based on the Episode Registry: ACTIVE episodes → Cloudflare Durable Object (recent, fast, per-fragment) PASSIVE episodes → HelixDB (consolidated summaries, older) Results from both tiers are merged and re-ranked before being returned. Active hits receive a recency score boost because an agent's current session is statistically more likely to be relevant than months-old consolidations.
  - `agent_id` string, required: Agent identifier
  - `user_hash` string, nullable: Hashed user ID (never raw PII). If omitted, backend derives it from authenticated org_id + effective user scope.
  - `scope_user_id` string, nullable: Optional effective user_id for agent/service tokens. If provided, user_hash must match server-derived hash for this user.
  - `query_text` string, required: Text to embed and search
  - `top_k` integer: Max hits to return across all sources
  - `include_active` boolean: Query ACTIVE episodes (Cloudflare Durable Object)
  - `include_passive` boolean: Query PASSIVE episodes (HelixDB consolidated summaries)
  - `scope` string, nullable: Optional scope "<kind>:<value>" to narrow the read to. Must be in the caller's visible scopes (403 otherwise); omitted = every visible scope.

## Response `200`

Successful Response

- MemoryRetrieveResponse: Unified retrieval response with merged and re-ranked results from both tiers.
  - `hits` MemoryRetrievalHit[]
    - `fragment_id` string, required: Fragment ID (active) or HelixDB node ID (passive)
    - `score` number, required: Final ranked score in [0, 1]. Active hits include a +0.15 recency boost prior to clamping.
    - `text` string, required: Fragment text (active) or LLM episode summary text (passive)
    - `timestamp_ms` integer, required: Fragment or episode-window timestamp (ms since epoch)
    - `episode_id` string, required: Episode this hit belongs to
    - `agent_id` string, required: Agent that produced this memory
    - `source` string, required: Memory tier: 'active' or 'passive'
    - `entities` string[]: Extracted entities (populated for active episodes only)
    - `metadata` object, nullable: Opaque metadata forwarded from the backing store
  - `total_hits` integer, required: Number of hits returned (≤ top_k)
  - `active_episodes_searched` integer, required: Number of ACTIVE episodes found in the registry
  - `passive_episodes_searched` integer, required: Number of PASSIVE episodes found in the registry

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/metacognition/apis/tex-api.md) - [All operations](https://skmtc.dev/metacognition/apis/tex-api/llms.txt) - [OpenAPI document](https://skmtc.dev/metacognition/apis/tex-api/revisions/3bef47e50f2e?raw)