---
title: "Retrieve semantically similar fragments from active memory"
method: POST
path: "/active-memory/retrieve"
tags: ["active-memory"]
---

# Retrieve semantically similar fragments from active memory

`POST /active-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/active-memory/retrieve`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/metacognition/apis/tex-api/docs/active-memory/retrieve/post.ts> (a function with typed inputs; its response is checked against the schema)

Embed `body.query_text`, then query the Cloudflare Worker for the top-k most
similar fragments.  The Worker performs cosine similarity over the Durable
Object's SQLite vector store and hydrates fragment texts from Workers KV.

If `episode_id` is omitted, all open episodes for `agent_id` are searched.

## Request body

- ActiveEpisodeRetrieveRequest: Retrieve semantically similar fragments from the active memory store.
  - `agent_id` string, required: Agent identifier
  - `user_hash` string, nullable: Hashed user ID. If omitted, backend derives it from authenticated org_id + effective user scope.
  - `episode_id` string, nullable: Scope search to one episode; None = all open episodes for agent
  - `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
  - `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

- ActiveEpisodeRetrieveResponse
  - `hits` ActiveRetrievalHitResponse[]
    - `fragment_id` string, required
    - `score` number, required
    - `text` string, required
    - `timestamp_ms` integer, required
    - `entities` string[]
    - `agent_id` string, required
    - `episode_id` string, required
    - `scope_id` string, nullable: Scope stamp of the fragment
    - `kind` 'turn' | 'observation': Fragment kind ("turn" when the worker does not report one)
    - `metadata` object, nullable
  - `total_scanned` integer, required
  - `active_episodes_searched` integer, required

## 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)