memory

Unified episodic memory retrieval — routes across active and passive tiers

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.

post/memory/retrieve

Request

Base URL
https://api.getmetacognition.com (the document declares no server; this is the origin it was published from)
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.

agent_idstring required

Agent identifier

user_hashstring nullable

Hashed user ID (never raw PII). If omitted, backend derives it from authenticated org_id + effective user scope.

scope_user_idstring nullable

Optional effective user_id for agent/service tokens. If provided, user_hash must match server-derived hash for this user.

query_textstring required

Text to embed and search

top_kinteger

Max hits to return across all sources

include_activeboolean

Query ACTIVE episodes (Cloudflare Durable Object)

include_passiveboolean

Query PASSIVE episodes (HelixDB consolidated summaries)

scopestring nullable

Optional scope "<kind>:<value>" to narrow the read to. Must be in the caller's visible scopes (403 otherwise); omitted = every visible scope.

Successful Response

total_hitsinteger required

Number of hits returned (≤ top_k)

active_episodes_searchedinteger required

Number of ACTIVE episodes found in the registry

passive_episodes_searchedinteger required

Number of PASSIVE episodes found in the registry

No recorded changes to this operation across all 1 revision of this API.