{"components":{"schemas":{"Error":{"description":"Envelope used by memory-v2 endpoints. Pre-existing endpoints keep their original {\"error\": \"...\"} shape.","properties":{"code":{"type":"integer"},"detail":{"type":"string"},"error":{"type":"string"}},"type":"object"},"HitV2":{"properties":{"band":{"description":"r2. strong | plausible are hits; weak only ever appears in weak_hits; none is never returned.","enum":["strong","plausible","weak","none",null],"type":["string","null"]},"body":{"type":"string"},"cal2_score":{"description":"r2. Relevance on the CAL2 scale. Equals `score` when MEMV2_CAL=cal2; under cal1 it is what CAL2 would have said.","type":["number","null"]},"collapsed":{"description":"Near-identical neighbours this hit absorbed at read time (MMR), with the similarity that cost them their slot.","type":"array"},"episode_id":{"format":"uuid","type":"string"},"evidence":{"description":"r2. What kind of evidence this hit rests on. A semantic_only hit has to clear a higher bar.","enum":["lexical","semantic_only","both",null],"type":["string","null"]},"graph_boost":{"type":"number"},"importance":{"type":"integer"},"matched_terms":{"description":"r2. Every query token the body has, with its per-layer idf and how it was found (lexeme | prefix | substring | stem | synonym). Empty on a semantic_only hit.","type":"array"},"matched_via":{"description":"r2. both | semantic | lexical:phrase | lexical:all | lexical:any | lexical:scan.","type":["string","null"]},"merged_from":{"description":"Episodes superseded by this one. Their ids are always returned; nothing is hidden.","items":{"format":"uuid","type":"string"},"type":"array"},"missing_terms":{"description":"r2. The query tokens this body does not have.","items":{"type":"string"},"type":"array"},"provenance":{"description":"basis: credential_bound (a writer token is recorded) | backfilled (meta exists, writer predates the column) | pre_v2 (no meta row). Under r2 it also carries session_basis: request | header | mcp | synthesized, or null for a row written before the column existed.","type":"object"},"rank_score":{"description":"Ordering only. Recency, importance and graph boost move this and never `score`.","type":"number"},"recorded_at":{"format":"date-time","type":"string"},"rung":{"type":"string"},"score":{"description":"Calibrated relevance in [0,1] under v2.","type":"number"},"semantic":{"description":"r2. {cosine, calibrated, generation, chunk_ix, chunk_span}, or null when the vector leg never scored this candidate.","type":["object","null"]},"session_id":{"type":["string","null"]},"text_score":{"type":["number","null"]},"vector_score":{"type":["number","null"]},"why":{"description":"Which rung matched, which query tokens the body has and lacks, what the semantic leg thought, the importance arithmetic, and a highlighted snippet.","type":"object"}},"type":"object"}},"securitySchemes":{"bearerAuth":{"bearerFormat":"thx_","scheme":"bearer","type":"http"}}},"info":{"description":"Agent memory. Every path the router serves under /v1 is listed here; flag-gated endpoints say so in their summary rather than being omitted.","title":"UAI Thaladex","version":"0.2.0"},"openapi":"3.1.0","paths":{"/health":{"get":{"summary":"Liveness"}},"/ready":{"get":{"summary":"Readiness"}},"/v1/connection-kit":{"get":{"summary":"Connection kit template (unauthenticated shape)"}},"/v1/connections/{connection_id}":{"get":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Connection status for the aha poll (404s unless CONNECT_LINKS is enabled)"}},"/v1/connections/{connection_id}/reissue":{"post":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Mint a replacement connect link (404s unless CONNECT_LINKS is enabled)"}},"/v1/connections/{connection_id}/revoke":{"post":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Revoke a connection and its token (404s unless CONNECT_LINKS is enabled)"}},"/v1/export":{"get":{"security":[{"bearerAuth":["export"]}],"summary":"Export every layer of the tenant (broader portability scope)"}},"/v1/feedback":{"post":{"security":[{"bearerAuth":["feedback"]}],"summary":"Submit agent feedback; idempotent via client_ref"}},"/v1/health":{"get":{"summary":"Liveness (v1 alias)"}},"/v1/layers":{"get":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"List the caller's layers"},"post":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Create a layer"}},"/v1/layers/{layer_id}":{"delete":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Soft-delete a layer (refuses the last live layer) (404s unless LAYER_EDIT is enabled)"},"patch":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Rename or describe a layer (404s unless LAYER_EDIT is enabled)"}},"/v1/layers/{layer_id}/answer":{"post":{"security":[{"bearerAuth":["recall"]}],"summary":"Extractive answer composed from recall v2. Every claim carries the episode id and the byte span it was taken from; disagreements are flagged, never resolved. (404s unless ANSWER_ENDPOINT is enabled)"}},"/v1/layers/{layer_id}/connection-kit":{"get":{"summary":"Connection kit bound to one layer"}},"/v1/layers/{layer_id}/connections":{"get":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"List connections on a memory (404s unless CONNECT_LINKS is enabled)"},"post":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Mint a connect link for one memory (404s unless CONNECT_LINKS is enabled)"}},"/v1/layers/{layer_id}/consolidation/apply":{"post":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Apply near-duplicate pairs as reversible supersede links. Conflict pairs are always refused. (404s unless 0105 applied is enabled)"}},"/v1/layers/{layer_id}/consolidation/preview":{"get":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Near-duplicate and conflict pairs found for this layer, with the proposed winner (404s unless 0105 applied is enabled)"}},"/v1/layers/{layer_id}/consolidation/runs/{run_id}/undo":{"post":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Undo every supersede link written by one consolidation run (404s unless 0105 applied is enabled)"}},"/v1/layers/{layer_id}/episodes/{episode_id}/consolidation":{"get":{"security":[{"bearerAuth":["recall"]}],"summary":"Extraction/consolidation status of one episode"}},"/v1/layers/{layer_id}/export":{"get":{"security":[{"bearerAuth":["export"]}],"summary":"Export one layer's episodes (portability). Never changed by consolidation."}},"/v1/layers/{layer_id}/index-status":{"get":{"security":[{"bearerAuth":["recall"]}],"summary":"What is indexed for this layer: lexical backfill, vector queue (pending/failed/dead), provider health, consolidation mode (404s unless INDEX_STATUS_ENDPOINT is enabled)"}},"/v1/layers/{layer_id}/index/retry":{"post":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Return dead or failed embed-queue rows of this layer to pending (404s unless INDEX_STATUS_ENDPOINT is enabled)"}},"/v1/layers/{layer_id}/recall":{"post":{"requestBody":{"content":{"application/json":{"schema":{"properties":{"as_of":{"format":"date-time","type":"string"},"diversity":{"description":"v2 only; default mmr.","enum":["mmr","off"],"type":"string"},"explain":{"default":true,"description":"v2 only; false omits why.snippet.","type":"boolean"},"limit":{"description":"Alias of top_k. Both are accepted; top_k wins when both are sent.","maximum":50,"minimum":1,"type":"integer"},"min_score":{"description":"Optional. Under memory-v2 the service default (0.05 on the calibrated relevance scale) is the floor, and anything below it is returned as weak_hits rather than dropped. A stored layer min_score written before v2 is ignored and named in legacy_min_score_ignored.","maximum":1,"minimum":0,"type":"number"},"mode":{"description":"Honoured only where the server has memory-v2 enabled.","enum":["v1","v2"],"type":"string"},"profile_mode":{"type":"string"},"query":{"maxLength":1024,"type":"string"},"top_k":{"default":5,"maximum":50,"minimum":1,"type":"integer"},"use_rerank":{"type":"boolean"}},"required":["query"],"type":"object"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"properties":{"below_threshold_count":{"type":"integer"},"calibration":{"properties":{"cal2":{"description":"r2. The generation's CAL2 numbers (mid, s, bars, strong, weak, version), plus `applied`: whether they decided membership on this request or were only reported.","type":"object"},"vec_hi":{"type":"number"},"vec_lo":{"type":"number"},"version":{"type":"string"}},"type":"object"},"confidence":{"description":"r2. The top hit's {band, score, evidence}, or the best rejected candidate's when nothing matched.","type":["object","null"]},"contract":{"description":"memory-v2.1/r2 when the v2.1 response shape is on; absent otherwise.","type":["string","null"]},"count":{"type":"integer"},"degraded":{"description":"any_window_full | scan_timeout | scan_truncated | vector_skipped | lexical_backfill_pending | no_content_tokens","items":{"type":"string"},"type":"array"},"elapsed_ms":{"type":"object"},"embedder":{"description":"r2. Which generation answered, the wire model and pinned digest, what the provider served, the lane and the guard mode.","type":["object","null"]},"exhausted":{"description":"True only when every leg looked, including the substring scan floor, and there is nothing here. An honest nothing.","type":"boolean"},"forced_by_min_score":{"description":"r2. True when the request's min_score decided membership instead of the calibrated bands.","type":["boolean","null"]},"hits":{"items":{"$ref":"#/components/schemas/HitV2"},"type":"array"},"index":{"description":"Indexing state of the layer at the time of this recall. Under r2 `index.vector` adds the generation, its coverage of this layer, any candidate generation, the tail-chunk count and the model-mismatch count.","type":"object"},"legacy_min_score_ignored":{"type":["number","null"]},"legs":{"description":"Which retrieval legs ran. lexical: ran|empty|empty_scan_hit|skipped_no_tokens. vector: ran|skipped_provider_down|skipped_timeout|skipped_breaker_open|skipped_disabled. scan: not_needed|ran|ran_empty|ran_timeout|error.","properties":{"lexical":{"type":"string"},"scan":{"type":"string"},"vector":{"type":"string"}},"type":"object"},"matched":{"description":"r2. Whether anything cleared its bar. Read this before trusting `hits`: an empty `hits` always travels with matched:false and a why_empty object.","type":["boolean","null"]},"retrieval_policy_version":{"description":"memory-v2.1 under v2; null under v1.","type":["string","null"]},"rung_reached":{"enum":["phrase","all","any","semantic","scan",null],"type":["string","null"]},"score_threshold_used":{"type":"number"},"threshold_source":{"enum":["request","layer_policy_v2","service_default_v2","layer_policy","kind_default","service_default"],"type":"string"},"weak_hits":{"description":"Below-threshold candidates, returned when the page is not full so that a weak-but-right memory is never silently dropped.","items":{"$ref":"#/components/schemas/HitV2"},"type":"array"},"why_empty":{"description":"r2. Present exactly when matched is false: reason (no_candidates | below_bar | lexical_only_below_bar | provider_down_no_lexical | no_content_tokens | layer_empty), the bars, the best rejected candidate, which legs ran, provider and index state, and caveats.","type":["object","null"]}},"type":"object"}}},"description":"Recall result"}},"security":[{"bearerAuth":["recall"]}],"summary":"Recall episodes. Under memory-v2: `score` is calibrated relevance in [0,1], `legs` says which retrieval legs ran, `why` explains each hit, `weak_hits` carries below-threshold candidates and `exhausted` marks an honest nothing. Under memory-v2.1 (`contract: memory-v2.1/r2`): read `matched` before trusting `hits`, `why_empty` explains an empty result, and each hit says `matched_via`, `evidence` and `band`. Send `X-Thaladex-Session` to bind writes and recalls to one session."}},"/v1/layers/{layer_id}/remember":{"post":{"security":[{"bearerAuth":["remember"]}],"summary":"Write a memory episode. Response carries `index` (what is searchable now), `importance_v2`, and under memory-v2.1 `session_id` with `session_basis` (request | header | mcp | synthesized). Send `X-Thaladex-Session` to file a write under a sitting of your own naming."}},"/v1/layers/{layer_id}/supersede":{"post":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Create a supersede link by hand (404s unless 0105 applied is enabled)"}},"/v1/layers/{layer_id}/supersede/{supersede_id}/undo":{"post":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Undo one supersede link (404s unless 0105 applied is enabled)"}},"/v1/layers/{layer_id}/write-guard":{"get":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Layer write-guard policy"},"put":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Set layer write-guard policy"}},"/v1/memory-dedup/backfill":{"post":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Backfill the exact-byte fingerprint registry"}},"/v1/memory-dedup/preview":{"post":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Preview exact-byte dedup candidates"}},"/v1/memory-observations/jobs":{"post":{"security":[{"bearerAuth":["remember"]}],"summary":"Record a task receipt"}},"/v1/openapi.json":{"get":{"summary":"This document"}},"/v1/welcome-pack":{"get":{"summary":"Public welcome pack (no auth)"}},"/v1/whoami":{"get":{"summary":"Bearer thx_ introspection: tenant, token, scopes"}},"/v1/write-guard/observations":{"get":{"security":[{"bearerAuth":["layers.manage"]}],"summary":"Recent write-map observations (observe-only)"}}}}