skills/vectorize-io__hindsight
1
0
Fork 0
mirror of https://github.com/vectorize-io/hindsight.git synced 2026-09-14 19:31:49 +08:00
Code Issues Packages Projects Releases Wiki Activity
Files
perf/profiling-env
vectorize-io__hindsight/hindsight-docs/static/openapi.json
T
Nicolò Boschi 9e6d9e76cc feat(api,control-plane): a prompt tester for retain, and prompt preview for every operation (#4140) 
* feat(api,control-plane): a prompt tester for retain, and prompt preview for every operation

Closes the "render prompts without calling an LLM" half of #3774.

A bank's missions only mean something once you can see the prompt they land in,
and today that means tracing Python constants and format calls.

`POST /banks/{id}/prompts/preview` returns the messages retain, consolidation or
reflect would send — in send order, no LLM call, no writes. The operation is the
whole request: everything comes from the bank, and the runtime data an operation
would be given is a fixed placeholder.

A message arrives as `blocks`. The active ones concatenate back to the exact text
sent — enforced by a test against what the extraction path itself builds. Each is
identified by machine values only (`field`, a `section` slug, or the `heading` the
prompt text carries); the response ships no display copy, so names and
explanations live in the UI that localises them. An inactive block has no text and
marks a setting switched off at the point it would land, so an unset mission is
still visible where it would go.

Both messages always come back: retain and consolidation keep their system prompt
bank-agnostic so one provider-side cache serves every bank, and carry the mission
in the user message instead. Only reflect puts its mission in the system prompt.

**Two bugs found on the way, both pre-existing in dry-run extraction:**

- Neither dry-run nor the preview applied retain strategies. Both resolved config
  directly instead of through `_resolve_retain_config`, so they ignored the bank's
  `retain_default_strategy` too — silently extracting and previewing under
  settings a real retain would never use. Both now resolve the way retain does and
  take an optional `strategy`.
- The preview read the bank's config without running `validate_bank_read`, so a
  tenant extension denying `GET_BANK_CONFIG` was bypassed by an endpoint that
  renders that config as prompt text. Both paths now share
  `_authorize_bank_config_read`, which also carries the bank-existence check.

**Control plane.** The dry-run dialog is gone; its work moved into the prompt
tester on the bank Configuration tab, because changing a mission and seeing what
it extracts is one loop that was split across two dialogs. Blocks re-render for
free as settings change; a sample-text box and a Run button spend the LLM call on
demand. A strategy picker renders any of the bank's named strategies. Editing a
block saves that setting to the bank; `editable` comes from the config layer's own
allowlist, so server-level fields say so rather than offering an edit that would
collect a 400.

`PromptBlockModel.kind` is required with no default: progenitor rejects a default
on an inline enum with TypeError(InvalidValue), which breaks the Rust client.

* chore(cli): skip preview_prompt in the OpenAPI coverage manifest
2026-09-07 17:27:51 +02:00

17072 lines
508 KiB
JSON
Raw Permalink Blame History

{
"openapi": "3.1.0",
"info": {
"title": "Hindsight HTTP API",
"description": "HTTP API for Hindsight",
"contact": {
"name": "Memory System"
},
"license": {
"name": "Apache 2.0",
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
},
"version": "0.9.2"
},
"paths": {
"/health": {
"get": {
"tags": [
"Monitoring"
],
"summary": "Health check endpoint",
"description": "Readiness check: verifies the API can reach the database. Alias of /health/ready. Use /health/live for liveness probes \u2014 this one fails whenever the database is unreachable, which must gate traffic, not restart the process.",
"operationId": "health_endpoint_health_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
},
"/health/ready": {
"get": {
"tags": [
"Monitoring"
],
"summary": "Readiness probe",
"description": "Returns 200 when the API can serve traffic (database reachable), 503 otherwise. Identical to /health, which stays supported as its alias.",
"operationId": "get_readiness",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
},
"/health/live": {
"get": {
"tags": [
"Monitoring"
],
"summary": "Liveness probe",
"description": "Returns 200 whenever the process can serve a request. Performs no database access, so a slow or unreachable database never restarts the pod. Point livenessProbe here and readinessProbe at /health.",
"operationId": "get_liveness",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LivenessResponse"
}
}
}
}
}
}
},
"/version": {
"get": {
"tags": [
"Monitoring"
],
"summary": "Get API version and feature flags",
"description": "Returns API version information and enabled feature flags. Use this to check which capabilities are available in this deployment.",
"operationId": "get_version",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VersionResponse"
}
}
}
}
}
}
},
"/metrics": {
"get": {
"tags": [
"Monitoring"
],
"summary": "Prometheus metrics endpoint",
"description": "Exports metrics in Prometheus format for scraping",
"operationId": "metrics_endpoint_metrics_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/graph": {
"get": {
"tags": [
"Memory"
],
"summary": "Get memory graph data",
"description": "Retrieve graph data for visualization, optionally filtered by type (world/experience/observation).",
"operationId": "get_graph",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Type"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 1000,
"title": "Limit"
}
},
{
"name": "q",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Q"
}
},
{
"name": "tags",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"title": "Tags"
}
},
{
"name": "tags_match",
"in": "query",
"required": false,
"schema": {
"type": "string",
"default": "all_strict",
"title": "Tags Match"
}
},
{
"name": "document_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Document Id"
}
},
{
"name": "chunk_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Chunk Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/GraphDataResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/memories/list": {
"get": {
"tags": [
"Memory"
],
"summary": "List memory units",
"description": "List memory units with pagination and optional full-text search. Supports filtering by type, source document, and linked entity ID. Results are sorted by most recent first (mentioned_at DESC, then created_at DESC).",
"operationId": "list_memories",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Type"
}
},
{
"name": "q",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Q"
}
},
{
"name": "consolidation_state",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Consolidation State"
}
},
{
"name": "state",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "State"
}
},
{
"name": "document_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Document Id"
}
},
{
"name": "entity_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Entity Id"
}
},
{
"name": "tags",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"title": "Tags"
}
},
{
"name": "tags_match",
"in": "query",
"required": false,
"schema": {
"enum": [
"any",
"all",
"any_strict",
"all_strict",
"exact"
],
"type": "string",
"default": "any",
"title": "Tags Match"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 100,
"title": "Limit"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "Offset"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListMemoryUnitsResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/memories/dry-run-extract": {
"post": {
"tags": [
"Memory"
],
"summary": "Dry-run fact extraction (preview, no persistence)",
"description": "Preview what the retain step would extract from text WITHOUT changing the bank \u2014 no entity resolution, links, embeddings, or persistence. Returns the candidate facts and the LLM token usage. Every prompt-affecting setting (retain mission, extraction mode, chunk size, \u2026) is overridable in the body to A/B a candidate config against the bank's current one. This is a read-only tool: nothing is stored.",
"operationId": "dry_run_extract_memories",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DryRunExtractRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DryRunExtractionResult"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/prompts/preview": {
"post": {
"tags": [
"Banks"
],
"summary": "Preview an operation's prompts (no LLM call)",
"description": "Render the exact system and user messages retain, consolidation or reflect would send for this bank, without calling an LLM, reading memories, or changing anything. Everything that shapes the prompt comes from the bank; the runtime data an operation would be given is a fixed placeholder. Both messages are returned: retain and consolidation keep their system prompt bank-agnostic (one provider-side cache serves every bank) and carry the mission in the user message instead.",
"operationId": "preview_prompt",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PromptPreviewRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/PromptPreviewResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/memories/{memory_id}": {
"get": {
"tags": [
"Memory"
],
"summary": "Get memory unit",
"description": "Get a single memory unit by ID with all its metadata including entities and tags. Note: the 'history' field is deprecated and always returns an empty list - use GET /memories/{memory_id}/history instead.",
"operationId": "get_memory",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "memory_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Memory Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Memory"
],
"summary": "Curate memory unit",
"description": "Edit a memory's text and/or change its curation state (invalidate / revert). Invalidated memories are excluded from recall, consolidation, and graph maintenance but kept for audit (reversible). Only world/experience facts can be curated; observations are derived.",
"operationId": "update_memory",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "memory_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Memory Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateMemoryRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/memories/{memory_id}/history": {
"get": {
"tags": [
"Memory"
],
"summary": "Get observation history",
"description": "Get the full history of an observation, with each change's source facts resolved to their text.",
"operationId": "get_observation_history",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "memory_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Memory Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/memories/recall": {
"post": {
"tags": [
"Memory"
],
"summary": "Recall memory",
"description": "Recall memory using semantic similarity and spreading activation.\n\nThe `types` parameter is optional and may contain any of:\n- `world`: General knowledge about people, places, events, and things that happen\n- `experience`: Memories about experience, conversations, actions taken, and tasks performed\n- `observation`: Consolidated knowledge synthesized from facts\n\nIf `types` is omitted, all fact types are recalled.",
"operationId": "recall_memories",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecallRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecallResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/reflect": {
"post": {
"tags": [
"Memory"
],
"summary": "Reflect and generate answer",
"description": "Reflect and formulate an answer using bank identity, world facts, observations, and mental models.\n\nThis endpoint:\n1. Retrieves experience (conversations and events)\n2. Retrieves world facts relevant to the query\n3. Retrieves observations and mental models (bank's synthesized perspectives)\n4. Uses LLM to formulate a contextual answer\n5. Returns plain text answer and the facts used",
"operationId": "reflect",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReflectRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReflectResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks": {
"get": {
"tags": [
"Banks"
],
"summary": "List memory banks",
"description": "List banks with their profiles and summary stats, most recently written first (`last_write_at` descending), with pagination and optional search.",
"operationId": "list_banks",
"parameters": [
{
"name": "q",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Case-insensitive substring filter on bank ID or name (e.g. 'alice')",
"title": "Q"
},
"description": "Case-insensitive substring filter on bank ID or name (e.g. 'alice')"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"description": "Maximum number of banks to return",
"default": 100,
"title": "Limit"
},
"description": "Maximum number of banks to return"
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"description": "Offset for pagination",
"default": 0,
"title": "Offset"
},
"description": "Offset for pagination"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankListResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/stats": {
"get": {
"tags": [
"Banks"
],
"summary": "Get statistics for memory bank",
"description": "Get statistics about nodes and links for a specific agent",
"operationId": "get_agent_stats",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "refresh",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "Force a fresh recompute, bypassing the cached value (and refreshing the cache).",
"default": false,
"title": "Refresh"
},
"description": "Force a fresh recompute, bypassing the cached value (and refreshing the cache)."
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankStatsResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/health/llm": {
"post": {
"tags": [
"Banks"
],
"summary": "Test the bank's LLM connectivity",
"description": "Probe the LLMs this bank would use for retain / consolidation / reflect with one minimal call each (configs shared across operations are probed once), so you can discover 'not configured / unreachable' instead of a silent stall. Deliberate action (makes a real provider call); not for polling. Returns status only \u2014 never the provider, model, endpoint, API key, or raw error. Disable with HINDSIGHT_API_ENABLE_BANK_LLM_HEALTH=false.",
"operationId": "test_bank_llm",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankLlmHealthResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/stats/memories-timeseries": {
"get": {
"tags": [
"Banks"
],
"summary": "Memory ingestion time-series",
"description": "Memories ingested over a period, bucketed by time and broken down by fact type.",
"operationId": "get_memories_timeseries",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "period",
"in": "query",
"required": false,
"schema": {
"type": "string",
"default": "7d",
"title": "Period"
}
},
{
"name": "time_field",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Timestamp column to bucket on. `created_at` (default) = ingest time; `mentioned_at` / `occurred_start` = event time, useful for migrated corpora where ingest time is a single point and doesn't reflect the underlying knowledge timeline. Unknown values fall back to `created_at`.",
"default": "created_at",
"title": "Time Field"
},
"description": "Timestamp column to bucket on. `created_at` (default) = ingest time; `mentioned_at` / `occurred_start` = event time, useful for migrated corpora where ingest time is a single point and doesn't reflect the underlying knowledge timeline. Unknown values fall back to `created_at`."
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MemoriesTimeseriesResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/entities": {
"get": {
"tags": [
"Entities"
],
"summary": "List entities",
"description": "List all entities (people, organizations, etc.) known by the bank, ordered by mention count. Supports pagination.",
"operationId": "list_entities",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"description": "Maximum number of entities to return",
"default": 100,
"title": "Limit"
},
"description": "Maximum number of entities to return"
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"description": "Offset for pagination",
"default": 0,
"title": "Offset"
},
"description": "Offset for pagination"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityListResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/entities/graph": {
"get": {
"tags": [
"Entities"
],
"summary": "Get entity co-occurrence graph",
"description": "Return a graph of entities (nodes) and their co-occurrences (edges) for visualization.",
"operationId": "get_entity_graph",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"description": "Maximum number of co-occurrence edges to return",
"default": 1000,
"title": "Limit"
},
"description": "Maximum number of co-occurrence edges to return"
},
{
"name": "min_count",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"description": "Minimum cooccurrence_count to include an edge",
"default": 1,
"title": "Min Count"
},
"description": "Minimum cooccurrence_count to include an edge"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityGraphResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/entities/{entity_id}": {
"get": {
"tags": [
"Entities"
],
"summary": "Get entity details",
"description": "Get detailed information about an entity including observations (mental model).",
"operationId": "get_entity",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "entity_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Entity Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityDetailResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/entities/{entity_id}/regenerate": {
"post": {
"tags": [
"Entities"
],
"summary": "Regenerate entity observations (deprecated)",
"description": "This endpoint is deprecated. Entity observations have been replaced by mental models.",
"operationId": "regenerate_entity_observations",
"deprecated": true,
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "entity_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Entity Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/EntityDetailResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/mental-models": {
"get": {
"tags": [
"Mental Models"
],
"summary": "List mental models",
"description": "List user-curated living documents that stay current.",
"operationId": "list_mental_models",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "tags",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Filter by tags",
"title": "Tags"
},
"description": "Filter by tags"
},
{
"name": "tags_match",
"in": "query",
"required": false,
"schema": {
"enum": [
"any",
"all",
"exact"
],
"type": "string",
"description": "How to match tags",
"default": "any",
"title": "Tags Match"
},
"description": "How to match tags"
},
{
"name": "detail",
"in": "query",
"required": false,
"schema": {
"enum": [
"metadata",
"content",
"full"
],
"type": "string",
"description": "Detail level: 'metadata' (names/tags only), 'content' (adds content/config), 'full' (includes reflect_response)",
"default": "full",
"title": "Detail"
},
"description": "Detail level: 'metadata' (names/tags only), 'content' (adds content/config), 'full' (includes reflect_response)"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 1000,
"minimum": 1,
"default": 100,
"title": "Limit"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "Offset"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MentalModelListResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"post": {
"tags": [
"Mental Models"
],
"summary": "Create mental model",
"description": "Create a mental model by running reflect with the source query in the background. Returns an operation ID to track progress. The content is auto-generated by the reflect endpoint. Use the operations endpoint to check completion status.",
"operationId": "create_mental_model",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateMentalModelRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateMentalModelResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/mental-models/{mental_model_id}": {
"get": {
"tags": [
"Mental Models"
],
"summary": "Get mental model",
"description": "Get a specific mental model by ID.",
"operationId": "get_mental_model",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "mental_model_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Mental Model Id"
}
},
{
"name": "detail",
"in": "query",
"required": false,
"schema": {
"enum": [
"metadata",
"content",
"full"
],
"type": "string",
"description": "Detail level: 'metadata' (names/tags only), 'content' (adds content/config), 'full' (includes reflect_response)",
"default": "full",
"title": "Detail"
},
"description": "Detail level: 'metadata' (names/tags only), 'content' (adds content/config), 'full' (includes reflect_response)"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MentalModelResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Mental Models"
],
"summary": "Update mental model",
"description": "Update a mental model's name and/or source query.",
"operationId": "update_mental_model",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "mental_model_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Mental Model Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateMentalModelRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MentalModelResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Mental Models"
],
"summary": "Delete mental model",
"description": "Delete a mental model.",
"operationId": "delete_mental_model",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "mental_model_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Mental Model Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/mental-models/{mental_model_id}/history": {
"get": {
"tags": [
"Mental Models"
],
"summary": "Get mental model history",
"description": "Get the refresh history of a mental model, showing content changes over time.",
"operationId": "get_mental_model_history",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "mental_model_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Mental Model Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/mental-models/{mental_model_id}/refresh": {
"post": {
"tags": [
"Mental Models"
],
"summary": "Refresh mental model",
"description": "Submit an async task to re-run the source query through reflect and update the content.",
"operationId": "refresh_mental_model",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "mental_model_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Mental Model Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncOperationSubmitResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/mental-models/{mental_model_id}/dry-run-refresh": {
"post": {
"tags": [
"Mental Models"
],
"summary": "Dry-run mental model refresh (preview, no persistence)",
"description": "Preview what a refresh would do to this mental model WITHOUT changing it \u2014 no content, structured document, watermark, or last_refreshed_at is written. Returns the mode the refresh ran in and why (delta silently falls back to full when there is no baseline or the source query changed), the resolved tag scope and time window it read, how many facts retrieval returned versus how many the reflect agent actually used, the delta operations it emitted, and a unified diff from the stored content to the content it would write.\n\nThis is the production refresh pipeline with two writes skipped \u2014 the content and the watermark \u2014 and nothing about it is configurable, so what it reports is what the next refresh will do. Because nothing is persisted, a delta dry run reads exactly the window the next real refresh would, and repeating it reads that same window again.\n\nIt costs the same LLM tokens as a refresh and is validated the same way.",
"operationId": "dry_run_refresh_mental_model",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "mental_model_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Mental Model Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MentalModelDryRunRefreshResult"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/mental-models/{mental_model_id}/clear": {
"post": {
"tags": [
"Mental Models"
],
"summary": "Clear mental model content",
"description": "Clear a mental model's content so the next refresh performs a full re-synthesis. This is useful for delta-mode models that have accumulated drift over many incremental refreshes. After clearing, call the /refresh endpoint to trigger a clean full rebuild.",
"operationId": "clear_mental_model",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "mental_model_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Mental Model Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/MentalModelResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/knowledge-base/tree": {
"get": {
"tags": [
"Knowledge Base"
],
"summary": "Get the knowledge-base tree",
"description": "Return the knowledge base as a nested tree of folders and pages.",
"operationId": "get_knowledge_base_tree",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeTreeResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/knowledge-base/folders": {
"post": {
"tags": [
"Knowledge Base"
],
"summary": "Create a knowledge-base folder",
"description": "Create a folder, optionally nested under a parent folder.",
"operationId": "create_knowledge_folder",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateFolderRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeNode"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/knowledge-base/pages": {
"post": {
"tags": [
"Knowledge Base"
],
"summary": "Create a knowledge-base page",
"description": "Create a page (a mental model + tree node). Content is generated asynchronously; use the returned operation_id to track completion.",
"operationId": "create_knowledge_page",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreatePageRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateKnowledgePageResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/knowledge-base/export": {
"get": {
"tags": [
"Knowledge Base"
],
"summary": "Export the knowledge base as a markdown bundle",
"description": "Return a portable markdown bundle: a nested index.md, one <id>.md per page, and history logs.",
"operationId": "export_knowledge_base",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgePageBundleResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/knowledge-base/search": {
"get": {
"tags": [
"Knowledge Base"
],
"summary": "Hybrid search over knowledge pages (BM25 + vector)",
"description": "Doc-level hybrid search across a bank's knowledge pages: a full-text (BM25) match and a vector-similarity match, Reciprocal-Rank-Fusion fused. No reranker \u2014 tuned for latency.",
"operationId": "search_knowledge_base",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "q",
"in": "query",
"required": true,
"schema": {
"type": "string",
"minLength": 1,
"description": "Search query",
"title": "Q"
},
"description": "Search query"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 50,
"minimum": 1,
"description": "Maximum results to return",
"default": 10,
"title": "Limit"
},
"description": "Maximum results to return"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgePageSearchResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/knowledge-base/pages/{page_id}": {
"get": {
"tags": [
"Knowledge Base"
],
"summary": "Get a knowledge-base page",
"description": "Return a single page as a markdown document (frontmatter + markdown body).",
"operationId": "get_knowledge_page",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "page_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Page Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgePageResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/knowledge-base/nodes/{node_id}": {
"patch": {
"tags": [
"Knowledge Base"
],
"summary": "Rename/move a knowledge-base node or update a page's options",
"description": "Rename a node (set `name`), move it under another folder (set `parent_id`, null for the root), and/or update a page's options (`source_query`, `tags`, `max_tokens`, `trigger`). Changing `source_query` schedules an async refresh so the page rebuilds against the new question. `trigger` is applied as a patch: the fields you send are updated and the rest keep the page's current values.",
"operationId": "update_knowledge_node",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "node_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Node Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateNodeRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/KnowledgeNode"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Knowledge Base"
],
"summary": "Delete a knowledge-base node",
"description": "Delete a folder or page and its whole subtree (pages' mental models are removed too).",
"operationId": "delete_knowledge_node",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "node_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Node Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/directives": {
"get": {
"tags": [
"Directives"
],
"summary": "List directives",
"description": "List directive definitions. Unlike reflect, an omitted tag filter returns all directives.",
"operationId": "list_directives",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "tags",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Filter directives by execution scope. Omit or pass [] to list all directives.",
"title": "Tags"
},
"description": "Filter directives by execution scope. Omit or pass [] to list all directives."
},
{
"name": "tags_match",
"in": "query",
"required": false,
"schema": {
"enum": [
"any",
"all",
"exact"
],
"type": "string",
"description": "How tagged directives match the requested scope. Untagged/global directives are included.",
"default": "any",
"title": "Tags Match"
},
"description": "How tagged directives match the requested scope. Untagged/global directives are included."
},
{
"name": "active_only",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "Only return active directives",
"default": true,
"title": "Active Only"
},
"description": "Only return active directives"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 1000,
"minimum": 1,
"default": 100,
"title": "Limit"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "Offset"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DirectiveListResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"post": {
"tags": [
"Directives"
],
"summary": "Create directive",
"description": "Create a global or tag-scoped hard rule for reflect prompts.",
"operationId": "create_directive",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDirectiveRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DirectiveResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/directives/{directive_id}": {
"get": {
"tags": [
"Directives"
],
"summary": "Get directive",
"description": "Get a specific directive by ID.",
"operationId": "get_directive",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "directive_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Directive Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DirectiveResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Directives"
],
"summary": "Update directive",
"description": "Update a directive's properties.",
"operationId": "update_directive",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "directive_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Directive Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDirectiveRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DirectiveResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Directives"
],
"summary": "Delete directive",
"description": "Delete a directive.",
"operationId": "delete_directive",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "directive_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Directive Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/documents": {
"get": {
"tags": [
"Documents"
],
"summary": "List documents",
"description": "List documents with pagination and optional search, most recently written first (`updated_at` descending). Documents are the source content from which memory units are extracted.",
"operationId": "list_documents",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "q",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Case-insensitive substring filter on document ID (e.g. 'report' matches 'report-2024')",
"title": "Q"
},
"description": "Case-insensitive substring filter on document ID (e.g. 'report' matches 'report-2024')"
},
{
"name": "tags",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Filter documents by tags",
"title": "Tags"
},
"description": "Filter documents by tags"
},
{
"name": "tags_match",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "How to match tags: 'any', 'all', 'any_strict', 'all_strict'",
"default": "any_strict",
"title": "Tags Match"
},
"description": "How to match tags: 'any', 'all', 'any_strict', 'all_strict'"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 100,
"title": "Limit"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "Offset"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListDocumentsResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/documents/{document_id}/chunks": {
"get": {
"tags": [
"Documents"
],
"summary": "List document chunks",
"description": "List all chunks for a given document, ordered by chunk index.",
"operationId": "list_document_chunks",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Document Id"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 1000,
"minimum": 1,
"description": "Maximum number of chunks to return",
"default": 100,
"title": "Limit"
},
"description": "Maximum number of chunks to return"
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"description": "Offset for pagination",
"default": 0,
"title": "Offset"
},
"description": "Offset for pagination"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListChunksResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/documents/{document_id}/reprocess": {
"post": {
"tags": [
"Documents"
],
"summary": "Reprocess document",
"description": "Re-run the retain pipeline on an existing document without changing its content. This deletes the existing memory units and re-extracts facts using the current engine configuration. Useful when the LLM model, chunking strategy, or extraction settings have changed.",
"operationId": "reprocess_document",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Document Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReprocessDocumentResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/documents/{document_id}": {
"get": {
"tags": [
"Documents"
],
"summary": "Get document details",
"description": "Get a specific document including its original text",
"operationId": "get_document",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Document Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Documents"
],
"summary": "Update document",
"description": "Update mutable fields on a document without re-processing its content.\n\n**Tags** (`tags`): Propagated to all associated memory units. Observations derived from those units are invalidated and queued for re-consolidation under the new tags. Co-source memories from other documents that shared those observations are also reset.\n\nAt least one field must be provided.",
"operationId": "update_document",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Document Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDocumentRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDocumentResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Documents"
],
"summary": "Delete a document",
"description": "Delete a document and all its associated memory units and links.\n\nThis will cascade delete:\n- The document itself\n- All memory units extracted from this document\n- All links (temporal, semantic, entity) associated with those memory units\n\nThis operation cannot be undone.",
"operationId": "delete_document",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "document_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Document Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteDocumentResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/tags": {
"get": {
"tags": [
"Memory"
],
"summary": "List tags",
"description": "List all unique tags in a memory bank with usage counts. Supports wildcard search using '*' (e.g., 'user:*', '*-fred', 'tag*-2'). Case-insensitive. Use `source=mental_models` to list tags used on mental models instead of memories.",
"operationId": "list_tags",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "q",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Wildcard pattern to filter tags (e.g., 'user:*' for user:alice, '*-admin' for role-admin). Use '*' as wildcard. Case-insensitive.",
"title": "Q"
},
"description": "Wildcard pattern to filter tags (e.g., 'user:*' for user:alice, '*-admin' for role-admin). Use '*' as wildcard. Case-insensitive."
},
{
"name": "source",
"in": "query",
"required": false,
"schema": {
"enum": [
"memories",
"mental_models"
],
"type": "string",
"description": "Where to read tags from: 'memories' (memory_units, default) or 'mental_models'.",
"default": "memories",
"title": "Source"
},
"description": "Where to read tags from: 'memories' (memory_units, default) or 'mental_models'."
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"description": "Maximum number of tags to return",
"default": 100,
"title": "Limit"
},
"description": "Maximum number of tags to return"
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"description": "Offset for pagination",
"default": 0,
"title": "Offset"
},
"description": "Offset for pagination"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListTagsResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/chunks/{chunk_id}": {
"get": {
"tags": [
"Documents"
],
"summary": "Get chunk details",
"description": "Get a specific chunk by its ID",
"operationId": "get_chunk",
"parameters": [
{
"name": "chunk_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Chunk Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ChunkResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/operations": {
"get": {
"tags": [
"Operations"
],
"summary": "List async operations",
"description": "Get a list of async operations for a specific agent, with optional filtering by status and operation type. Results are sorted by most recent first.",
"operationId": "list_operations",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by status: pending, processing, completed, failed, or cancelled",
"title": "Status"
},
"description": "Filter by status: pending, processing, completed, failed, or cancelled"
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by operation type: retain, consolidation, refresh_mental_model, file_convert_retain, webhook_delivery",
"title": "Type"
},
"description": "Filter by operation type: retain, consolidation, refresh_mental_model, file_convert_retain, webhook_delivery"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Maximum number of operations to return",
"default": 20,
"title": "Limit"
},
"description": "Maximum number of operations to return"
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"description": "Number of operations to skip",
"default": 0,
"title": "Offset"
},
"description": "Number of operations to skip"
},
{
"name": "exclude_parents",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "Exclude parent batch operations from results",
"default": false,
"title": "Exclude Parents"
},
"description": "Exclude parent batch operations from results"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OperationsListResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/operations/{operation_id}": {
"get": {
"tags": [
"Operations"
],
"summary": "Get operation status",
"description": "Get the status of a specific async operation. Returns 'pending', 'processing', 'completed', 'failed', or 'cancelled'. Completed operations remain queryable with their payload for the configured retention window and are pruned afterward.",
"operationId": "get_operation_status",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "operation_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Operation Id"
}
},
{
"name": "include_payload",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "Include the raw task payload (submission params) in the response. May be large.",
"default": false,
"title": "Include Payload"
},
"description": "Include the raw task payload (submission params) in the response. May be large."
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/OperationStatusResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Operations"
],
"summary": "Cancel a pending or in-flight async operation",
"description": "Cancel a queued or running async operation. A 'pending' operation is never started. A 'processing' one is cancelled cooperatively: the row is marked 'cancelled' immediately and the worker running it stops at its next checkpoint, so work already in flight may finish the batch it is on. This also clears operations stranded in 'processing' by a crashed worker. Returns 409 for operations that already reached a terminal state.",
"operationId": "cancel_operation",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "operation_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Operation Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CancelOperationResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/operations/{operation_id}/retry": {
"post": {
"tags": [
"Operations"
],
"summary": "Retry a failed async operation",
"description": "Re-queue a failed async operation so the worker picks it up again",
"operationId": "retry_operation",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "operation_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Operation Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetryOperationResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/operations/{operation_id}/delete": {
"delete": {
"tags": [
"Operations"
],
"summary": "Delete a terminal async operation",
"description": "Permanently remove a failed, cancelled, or completed async operation record",
"operationId": "delete_operation",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "operation_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Operation Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteOperationResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/profile": {
"get": {
"tags": [
"Banks"
],
"summary": "Get memory bank profile (removed \u2014 use GET .../config)",
"description": "**Removed.** The bank profile endpoints have been removed. Disposition traits and the reflect mission are bank configuration: read them from GET /v1/default/banks/{bank_id}/config as `disposition_skepticism`, `disposition_literalism`, `disposition_empathy` and `reflect_mission`, and write them with PATCH /v1/default/banks/{bank_id}/config. The `name` field this endpoint also returned was a display-only label; read it from GET /v1/default/banks.",
"operationId": "get_bank_profile",
"deprecated": true,
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankProfileResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"put": {
"tags": [
"Banks"
],
"summary": "Update memory bank disposition (removed \u2014 use PATCH .../config)",
"description": "**Removed.** The bank profile endpoints have been removed. Disposition traits and the reflect mission are bank configuration: read them from GET /v1/default/banks/{bank_id}/config as `disposition_skepticism`, `disposition_literalism`, `disposition_empathy` and `reflect_mission`, and write them with PATCH /v1/default/banks/{bank_id}/config. The `name` field this endpoint also returned was a display-only label; read it from GET /v1/default/banks.",
"operationId": "update_bank_disposition",
"deprecated": true,
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDispositionRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankProfileResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/background": {
"post": {
"tags": [
"Banks"
],
"summary": "Add/merge memory bank background (removed \u2014 use PATCH .../config)",
"description": "**Removed.** The bank background was folded into the reflect mission. Write it with PATCH /v1/default/banks/{bank_id}/config as `reflect_mission`. That call replaces the value rather than merging into it, so read the current mission from GET .../config first if you relied on this endpoint's append behaviour.",
"operationId": "add_bank_background",
"deprecated": true,
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddBackgroundRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BackgroundResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}": {
"put": {
"tags": [
"Banks"
],
"summary": "Create or update memory bank",
"description": "Create a new agent or update existing agent with disposition and mission. Auto-fills missing fields with defaults.",
"operationId": "create_or_update_bank",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateBankRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankProfileResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Banks"
],
"summary": "Partial update memory bank",
"description": "Partially update an agent's profile. Only provided fields will be updated.",
"operationId": "update_bank",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateBankRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankProfileResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Banks"
],
"summary": "Delete memory bank",
"description": "Delete an entire memory bank including all memories, entities, documents, and the bank profile itself. This is a destructive operation that cannot be undone.",
"operationId": "delete_bank",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/import": {
"post": {
"tags": [
"Bank Templates"
],
"summary": "Import bank template",
"description": "Import a bank template manifest to create or update a bank's configuration, mental models, and directives. If the bank does not exist it is created. Config fields are applied as per-bank overrides. Mental models are matched by id, directives by name \u2014 existing ones are updated, new ones are created. Use dry_run=true to validate the manifest without applying changes.",
"operationId": "import_bank_template",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "dry_run",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "Validate only, do not apply changes",
"default": false,
"title": "Dry Run"
},
"description": "Validate only, do not apply changes"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankTemplateImportResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/export": {
"get": {
"tags": [
"Bank Templates"
],
"summary": "Export bank template",
"description": "Export a bank's current configuration, mental models, and directives as a template manifest. The exported manifest can be imported into another bank to replicate the setup.",
"operationId": "export_bank_template",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankTemplateManifest"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/document-transfer": {
"get": {
"tags": [
"Document Transfer"
],
"summary": "Export documents (removed \u2014 use POST .../document-transfer/export)",
"description": "**Removed.** The synchronous whole-bank export loaded the entire bank into memory and held a database connection for the full request, which could exhaust memory and take down the shared API on large banks. Use the asynchronous POST /v1/default/banks/{bank_id}/document-transfer/export instead: it returns an operation_id, runs the export in the background, and exposes a download URL on completion.",
"operationId": "export_documents_sync_removed",
"deprecated": true,
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"post": {
"tags": [
"Document Transfer"
],
"summary": "Import documents (async)",
"description": "Submit a transfer archive (produced by the export endpoint) for import into a bank. Runs as a background operation: facts are re-embedded with the target bank's embedding model and entities are re-resolved \u2014 no LLM extraction. Returns an operation_id; poll GET /v1/default/banks/{bank_id}/operations/{operation_id} for status and the imported/skipped counts in result_metadata. Use on_conflict to control existing document ids: skip (default), replace, or new-id.",
"operationId": "import_documents",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "on_conflict",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "skip | replace | new-id",
"default": "skip",
"title": "On Conflict"
},
"description": "skip | replace | new-id"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_import_documents"
}
}
}
},
"responses": {
"202": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentImportSubmitResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/document-transfer/export": {
"post": {
"tags": [
"Document Transfer"
],
"summary": "Export documents (async)",
"description": "Submit an async export of a bank's documents (extracted facts, entity names, causal links, chunks) as a transfer ZIP archive. Embeddings and database ids are not included \u2014 importing re-embeds with the target bank's model and re-resolves entities. Runs as a background operation to avoid pinning the API on large banks. Returns an operation_id; poll GET /v1/default/banks/{bank_id}/operations/{operation_id}. On completion the operation's result_metadata carries download_url (fetch the ZIP from GET /v1/default/files/download/{key}), storage_key, byte_size, and filename. Pass document_id query params to export specific documents, or omit to export the whole bank; include_observations=true carries consolidated observations and include_knowledge_base=true carries Mental Models plus Knowledge Pages (all whole-bank export only).",
"operationId": "export_documents",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "document_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Document id(s) to export; omit for all",
"title": "Document Id"
},
"description": "Document id(s) to export; omit for all"
},
{
"name": "include_observations",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "Also export consolidated observations (restored on import; whole-bank only)",
"default": false,
"title": "Include Observations"
},
"description": "Also export consolidated observations (restored on import; whole-bank only)"
},
{
"name": "include_knowledge_base",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "Also export Mental Models and Knowledge Pages (restored on import; whole-bank only)",
"default": false,
"title": "Include Knowledge Base"
},
"description": "Also export Mental Models and Knowledge Pages (restored on import; whole-bank only)"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"202": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DocumentExportSubmitResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/attachments/{attachment_id}": {
"get": {
"tags": [
"Memory"
],
"summary": "Fetch an attachment retained inline with a document",
"description": "Serve the bytes of an attachment retained as inline content. The id is the one inside a placeholder token, and is returned on `attachments[].url` by recall and by the document/chunk/memory reads \u2014 so an agent can show or reason over the original behind an attachment-derived fact.\n\nBytes are served with the Content-Type the caller declared at retain. Access is authorized against the bank; a missing attachment and an invisible bank both return 404, so the endpoint cannot be used to probe what a bank holds.",
"operationId": "get_bank_attachment",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "attachment_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Attachment Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Attachment bytes",
"content": {
"application/json": {
"schema": {}
},
"application/octet-stream": {}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/files/download/{key}": {
"get": {
"tags": [
"Document Transfer"
],
"summary": "Download a stored file (async export archive)",
"description": "Stream a file previously written to file storage \u2014 currently the transfer ZIP produced by an async document export. The key comes from the export operation's result_metadata (storage_key / download_url). Access is authorized against the bank the key belongs to.",
"operationId": "download_file",
"parameters": [
{
"name": "key",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Key"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Stored file",
"content": {
"application/json": {
"schema": {}
},
"application/zip": {}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/bank-template-schema": {
"get": {
"tags": [
"Bank Templates"
],
"summary": "Get bank template JSON Schema",
"description": "Returns the JSON Schema for the bank template manifest format. Use this to validate template manifests before importing.",
"operationId": "get_bank_template_schema",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/observations": {
"delete": {
"tags": [
"Banks"
],
"summary": "Clear all observations",
"description": "Delete all observations for a memory bank. This is useful for resetting the consolidated knowledge.",
"operationId": "clear_observations",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/observations/scopes": {
"get": {
"tags": [
"Memory"
],
"summary": "List observation scopes",
"description": "Enumerate the distinct scopes across a bank's observations. Each observation lives under a scope: the exact set of tags it was consolidated with. Returns every distinct scope (tag order normalized) with the number of observations in it; the empty tag list is the global/untagged scope. Use a returned scope with the graph endpoint (tags=<scope> & tags_match=exact) to filter observations to exactly that scope. Paged: `total` reports every distinct scope in the bank.",
"operationId": "list_observation_scopes",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 1000,
"minimum": 0,
"description": "Maximum number of scopes to return",
"default": 100,
"title": "Limit"
},
"description": "Maximum number of scopes to return"
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"description": "Offset for pagination",
"default": 0,
"title": "Offset"
},
"description": "Offset for pagination"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ObservationScopesResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/consolidation/recover": {
"post": {
"tags": [
"Banks"
],
"summary": "Recover failed consolidation",
"description": "Reset all memories that were permanently marked as failed during consolidation (after exhausting all LLM retries and adaptive batch splitting) so they are picked up again on the next consolidation run. Does not delete any observations.",
"operationId": "recover_consolidation",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecoverConsolidationResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/memories/{memory_id}/observations": {
"delete": {
"tags": [
"Memory"
],
"summary": "Clear observations for a memory",
"description": "Delete all observations derived from a specific memory and reset it for re-consolidation. The memory itself is not deleted. A consolidation job is triggered automatically so the memory will produce fresh observations on the next consolidation run.",
"operationId": "clear_memory_observations",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "memory_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Memory Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClearMemoryObservationsResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/config": {
"get": {
"tags": [
"Banks"
],
"summary": "Get bank configuration",
"description": "Get fully resolved configuration for a bank including all hierarchical overrides (global \u2192 tenant \u2192 bank). The 'config' field contains all resolved config values. The 'overrides' field shows only bank-specific overrides. Always available: HINDSIGHT_API_ENABLE_BANK_CONFIG_API gates only the write operations on this resource.",
"operationId": "get_bank_config",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankConfigResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Banks"
],
"summary": "Update bank configuration",
"description": "Update configuration overrides for a bank. Only hierarchical behavioral settings can be overridden (retention parameters, recall settings, etc.). Keys can be provided in Python field format (retain_extraction_mode) or environment variable format (HINDSIGHT_API_RETAIN_EXTRACTION_MODE).",
"operationId": "update_bank_config",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankConfigUpdate"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankConfigResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Banks"
],
"summary": "Reset bank configuration",
"description": "Reset bank configuration to defaults by removing all bank-specific overrides. The bank will then use global and tenant-level configuration only.",
"operationId": "reset_bank_config",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankConfigResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/consolidate": {
"post": {
"tags": [
"Banks"
],
"summary": "Trigger consolidation",
"description": "Run memory consolidation to create/update observations from recent memories.",
"operationId": "trigger_consolidation",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"$ref": "#/components/schemas/ConsolidationRequest"
},
{
"type": "null"
}
],
"title": "Request"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConsolidationResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/webhooks": {
"post": {
"tags": [
"Webhooks"
],
"summary": "Register webhook",
"description": "Register a webhook endpoint to receive event notifications for this bank.",
"operationId": "create_webhook",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWebhookRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"get": {
"tags": [
"Webhooks"
],
"summary": "List webhooks",
"description": "List the webhooks registered for a bank, oldest first. Paged: `total` reports every webhook on the bank.",
"operationId": "list_webhooks",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 1000,
"minimum": 0,
"description": "Maximum number of webhooks to return",
"default": 100,
"title": "Limit"
},
"description": "Maximum number of webhooks to return"
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"description": "Offset for pagination",
"default": 0,
"title": "Offset"
},
"description": "Offset for pagination"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookListResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/webhooks/{webhook_id}": {
"delete": {
"tags": [
"Webhooks"
],
"summary": "Delete webhook",
"description": "Remove a registered webhook.",
"operationId": "delete_webhook",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "webhook_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Webhook Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Webhooks"
],
"summary": "Update webhook",
"description": "Update one or more fields of a registered webhook. Only provided fields are changed.",
"operationId": "update_webhook",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "webhook_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Webhook Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWebhookRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/webhooks/{webhook_id}/deliveries": {
"get": {
"tags": [
"Webhooks"
],
"summary": "List webhook deliveries",
"description": "Inspect delivery history for a webhook (useful for debugging).",
"operationId": "list_webhook_deliveries",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "webhook_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Webhook Id"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 200,
"description": "Maximum number of deliveries to return",
"default": 50,
"title": "Limit"
},
"description": "Maximum number of deliveries to return"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Pagination cursor (created_at of last item)",
"title": "Cursor"
},
"description": "Pagination cursor (created_at of last item)"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookDeliveryListResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/memories": {
"post": {
"tags": [
"Memory"
],
"summary": "Retain memories",
"description": "Retain memory items with automatic fact extraction.\n\nThis is the main endpoint for storing memories. It supports both synchronous and asynchronous processing via the `async` parameter.\n\n**Features:**\n- Efficient batch processing\n- Automatic fact extraction from natural language\n- Entity recognition and linking\n- Document tracking with automatic upsert (when document_id is provided)\n- Temporal and semantic linking\n- Optional asynchronous processing\n\n**The system automatically:**\n1. Extracts semantic facts from the content\n2. Generates embeddings\n3. Deduplicates similar facts\n4. Creates temporal, semantic, and entity links\n5. Tracks document metadata\n\n**When `async=true`:** Returns immediately after queuing. Use the operations endpoint to monitor progress.\n\n**When `async=false` (default):** Waits for processing to complete.\n\n**Note:** If a memory item has a `document_id` that already exists, the old document and its memory units will be deleted before creating new ones (upsert behavior).",
"operationId": "retain_memories",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetainRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetainResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Memory"
],
"summary": "Clear memory bank memories",
"description": "Delete memory units for a memory bank. Optionally filter by type (world, experience, observation) to delete only specific types. This is a destructive operation that cannot be undone. The bank profile (disposition and background) will be preserved.",
"operationId": "clear_bank_memories",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional fact type filter (world, experience, observation)",
"title": "Type"
},
"description": "Optional fact type filter (world, experience, observation)"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/files/retain": {
"post": {
"tags": [
"Files"
],
"summary": "Convert files to memories",
"description": "Upload files (PDF, DOCX, etc.), convert them to markdown, and retain as memories.\n\nThis endpoint handles file upload, conversion, and memory creation in a single operation.\n\n**Features:**\n- Supports PDF, DOCX, PPTX, XLSX, images (parser-dependent OCR), audio (with transcription)\n- Automatic file-to-markdown conversion using pluggable parsers\n- Files stored in object storage (PostgreSQL by default, S3 for production)\n- Each file becomes a separate document with optional metadata/tags\n- Always processes asynchronously \u2014 returns operation IDs immediately\n\n**The system automatically:**\n1. Stores uploaded files in object storage\n2. Converts files to markdown\n3. Creates document records with file metadata\n4. Extracts facts and creates memory units (same as regular retain)\n\nUse the operations endpoint to monitor progress.\n\n**Request format:** multipart/form-data with:\n- `files`: One or more files to upload\n- `request`: JSON string with FileRetainRequest model\n\n**Parser selection:**\n- Set `parser` in the request body to override the server default for all files.\n- Set `parser` inside a `files_metadata` entry for per-file control.\n- Pass a list (e.g. `['iris', 'markitdown']`) to define an ordered fallback chain \u2014 each parser is tried in sequence until one succeeds.\n- Falls back to the server default (`HINDSIGHT_API_FILE_PARSER`) if not specified.\n- Only parsers enabled on the server may be requested; others return HTTP 400.",
"operationId": "file_retain",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_file_retain"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileRetainResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/audit-logs": {
"get": {
"tags": [
"Audit"
],
"summary": "List audit logs",
"description": "List audit log entries for a bank, ordered by most recent first.",
"operationId": "list_audit_logs",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "action",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by action type",
"title": "Action"
},
"description": "Filter by action type"
},
{
"name": "transport",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by transport (http, mcp, system)",
"title": "Transport"
},
"description": "Filter by transport (http, mcp, system)"
},
{
"name": "start_date",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter from this ISO datetime (inclusive)",
"title": "Start Date"
},
"description": "Filter from this ISO datetime (inclusive)"
},
{
"name": "end_date",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter until this ISO datetime (exclusive)",
"title": "End Date"
},
"description": "Filter until this ISO datetime (exclusive)"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Max items to return",
"default": 50,
"title": "Limit"
},
"description": "Max items to return"
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"description": "Offset for pagination",
"default": 0,
"title": "Offset"
},
"description": "Offset for pagination"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditLogListResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/audit-logs/stats": {
"get": {
"tags": [
"Audit"
],
"summary": "Audit log statistics",
"description": "Get audit log counts grouped by time bucket for charting.",
"operationId": "audit_log_stats",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "action",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by action type",
"title": "Action"
},
"description": "Filter by action type"
},
{
"name": "period",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Time period: 1d, 7d, or 30d",
"default": "7d",
"title": "Period"
},
"description": "Time period: 1d, 7d, or 30d"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AuditLogStatsResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/llm-requests": {
"get": {
"tags": [
"LLM Traces"
],
"summary": "List LLM request traces",
"description": "List traced LLM requests for a bank, ordered by most recent first. Requires LLM request tracing to be enabled (HINDSIGHT_API_LLM_TRACE_ENABLED).",
"operationId": "list_llm_requests",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "status",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by status (success, error)",
"title": "Status"
},
"description": "Filter by status (success, error)"
},
{
"name": "operation",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by operation (retain, reflect, consolidation)",
"title": "Operation"
},
"description": "Filter by operation (retain, reflect, consolidation)"
},
{
"name": "scope",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by call scope",
"title": "Scope"
},
"description": "Filter by call scope"
},
{
"name": "provider",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by LLM provider",
"title": "Provider"
},
"description": "Filter by LLM provider"
},
{
"name": "trace_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter to one operation run (all LLM calls sharing a trace)",
"title": "Trace Id"
},
"description": "Filter to one operation run (all LLM calls sharing a trace)"
},
{
"name": "document_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter to LLM calls that processed a given document",
"title": "Document Id"
},
"description": "Filter to LLM calls that processed a given document"
},
{
"name": "memory_id",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter to the operation run(s) that produced or consumed a given memory_unit",
"title": "Memory Id"
},
"description": "Filter to the operation run(s) that produced or consumed a given memory_unit"
},
{
"name": "group",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "Paginate by operation run (trace) instead of by call; returns whole runs",
"default": false,
"title": "Group"
},
"description": "Paginate by operation run (trace) instead of by call; returns whole runs"
},
{
"name": "start_date",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter from this ISO datetime (inclusive)",
"title": "Start Date"
},
"description": "Filter from this ISO datetime (inclusive)"
},
{
"name": "end_date",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter until this ISO datetime (exclusive)",
"title": "End Date"
},
"description": "Filter until this ISO datetime (exclusive)"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 500,
"minimum": 1,
"description": "Max items to return",
"default": 50,
"title": "Limit"
},
"description": "Max items to return"
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"description": "Offset for pagination",
"default": 0,
"title": "Offset"
},
"description": "Offset for pagination"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LLMRequestListResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/llm-requests/stats": {
"get": {
"tags": [
"LLM Traces"
],
"summary": "LLM request statistics",
"description": "Get LLM request counts grouped by time bucket and status for charting.",
"operationId": "llm_request_stats",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "operation",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Filter by operation",
"title": "Operation"
},
"description": "Filter by operation"
},
{
"name": "period",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "Time period: 1d, 7d, or 30d",
"default": "7d",
"title": "Period"
},
"description": "Time period: 1d, 7d, or 30d"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/LLMRequestStatsResponse"
}
}
}
},
"404": {
"description": "The bank does not exist."
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
}
},
"components": {
"schemas": {
"AddBackgroundRequest": {
"properties": {
"content": {
"type": "string",
"title": "Content",
"description": "New background information to add or merge"
},
"update_disposition": {
"type": "boolean",
"title": "Update Disposition",
"description": "Deprecated - disposition is no longer auto-inferred from mission",
"default": true
}
},
"type": "object",
"required": [
"content"
],
"title": "AddBackgroundRequest",
"description": "Request model for adding/merging background information. Deprecated: use SetMissionRequest instead.",
"example": {
"content": "I was born in Texas",
"update_disposition": true
}
},
"AsyncOperationSubmitResponse": {
"properties": {
"operation_id": {
"type": "string",
"title": "Operation Id"
},
"status": {
"type": "string",
"title": "Status"
}
},
"type": "object",
"required": [
"operation_id",
"status"
],
"title": "AsyncOperationSubmitResponse",
"description": "Response model for submitting an async operation.",
"example": {
"operation_id": "550e8400-e29b-41d4-a716-446655440000",
"status": "queued"
}
},
"AuditLogEntry": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"action": {
"type": "string",
"title": "Action"
},
"transport": {
"type": "string",
"title": "Transport"
},
"bank_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Bank Id"
},
"started_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Started At"
},
"ended_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Ended At"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Duration Ms",
"description": "Server-computed duration in milliseconds (started_at \u2192 ended_at). Null if not yet completed."
},
"request": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Request"
},
"response": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Response"
},
"metadata": {
"additionalProperties": true,
"type": "object",
"title": "Metadata"
}
},
"type": "object",
"required": [
"id",
"action",
"transport",
"bank_id",
"started_at",
"ended_at",
"request",
"response",
"metadata"
],
"title": "AuditLogEntry",
"description": "A single audit log entry."
},
"AuditLogListResponse": {
"properties": {
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"total": {
"type": "integer",
"title": "Total"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
},
"items": {
"items": {
"$ref": "#/components/schemas/AuditLogEntry"
},
"type": "array",
"title": "Items"
}
},
"type": "object",
"required": [
"bank_id",
"total",
"limit",
"offset",
"items"
],
"title": "AuditLogListResponse",
"description": "Response model for list audit logs endpoint."
},
"AuditLogStatsBucket": {
"properties": {
"time": {
"type": "string",
"title": "Time"
},
"actions": {
"additionalProperties": {
"type": "integer"
},
"type": "object",
"title": "Actions"
},
"total": {
"type": "integer",
"title": "Total"
}
},
"type": "object",
"required": [
"time",
"actions",
"total"
],
"title": "AuditLogStatsBucket",
"description": "A single time bucket in audit log stats."
},
"AuditLogStatsResponse": {
"properties": {
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"period": {
"type": "string",
"title": "Period"
},
"trunc": {
"type": "string",
"title": "Trunc"
},
"start": {
"type": "string",
"title": "Start"
},
"buckets": {
"items": {
"$ref": "#/components/schemas/AuditLogStatsBucket"
},
"type": "array",
"title": "Buckets"
}
},
"type": "object",
"required": [
"bank_id",
"period",
"trunc",
"start",
"buckets"
],
"title": "AuditLogStatsResponse",
"description": "Response model for audit log stats endpoint."
},
"BackgroundResponse": {
"properties": {
"mission": {
"type": "string",
"title": "Mission"
},
"background": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Background",
"description": "Deprecated: same as mission"
},
"disposition": {
"anyOf": [
{
"$ref": "#/components/schemas/DispositionTraits"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"mission"
],
"title": "BackgroundResponse",
"description": "Response model for background update. Deprecated: use MissionResponse instead.",
"example": {
"mission": "I was born in Texas. I am a software engineer with 10 years of experience."
}
},
"BankConfigResponse": {
"properties": {
"bank_id": {
"type": "string",
"title": "Bank Id",
"description": "Bank identifier"
},
"config": {
"additionalProperties": true,
"type": "object",
"title": "Config",
"description": "Fully resolved configuration with all hierarchical overrides applied (Python field names)"
},
"overrides": {
"additionalProperties": true,
"type": "object",
"title": "Overrides",
"description": "Bank-specific configuration overrides only (Python field names)"
}
},
"type": "object",
"required": [
"bank_id",
"config",
"overrides"
],
"title": "BankConfigResponse",
"description": "Response model for bank configuration.",
"example": {
"bank_id": "my-bank",
"config": {
"retain_chunk_size": 3000,
"retain_extraction_mode": "verbose"
},
"overrides": {
"retain_extraction_mode": "verbose"
}
}
},
"BankConfigUpdate": {
"properties": {
"updates": {
"additionalProperties": true,
"type": "object",
"title": "Updates",
"description": "Configuration overrides. Keys can be in Python field format (retain_extraction_mode) or environment variable format (HINDSIGHT_API_RETAIN_EXTRACTION_MODE). Only hierarchical fields can be overridden per-bank."
}
},
"type": "object",
"required": [
"updates"
],
"title": "BankConfigUpdate",
"description": "Request model for updating bank configuration.",
"example": {
"updates": {
"retain_custom_instructions": "Extract technical details carefully",
"retain_extraction_mode": "custom"
}
}
},
"BankListItem": {
"properties": {
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"disposition": {
"$ref": "#/components/schemas/DispositionTraits"
},
"mission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mission"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
},
"fact_count": {
"type": "integer",
"title": "Fact Count",
"default": 0
},
"last_document_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Document At",
"description": "When a document was last *ingested* into this bank. Appending to an existing document does not move this \u2014 use `last_write_at` for write activity."
},
"last_write_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Write At",
"description": "When anything was last written to this bank: a document retained (including appends to an existing document) or a fact stored. Null if the bank is empty."
}
},
"type": "object",
"required": [
"bank_id",
"disposition"
],
"title": "BankListItem",
"description": "Bank list item with profile summary and stats."
},
"BankListResponse": {
"properties": {
"banks": {
"items": {
"$ref": "#/components/schemas/BankListItem"
},
"type": "array",
"title": "Banks"
},
"total": {
"type": "integer",
"title": "Total",
"description": "Total number of banks visible to the caller, ignoring `limit`/`offset`."
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
}
},
"type": "object",
"required": [
"banks",
"total",
"limit",
"offset"
],
"title": "BankListResponse",
"description": "Response model for listing banks, one page at a time.",
"example": {
"banks": [
{
"bank_id": "user123",
"created_at": "2024-01-15T10:30:00Z",
"disposition": {
"empathy": 3,
"literalism": 3,
"skepticism": 3
},
"fact_count": 156,
"last_document_at": "2024-01-16T14:20:00Z",
"last_write_at": "2024-01-17T09:05:00Z",
"mission": "I am a software engineer helping my team ship quality code",
"name": "Alice",
"updated_at": "2024-01-16T14:20:00Z"
}
],
"limit": 100,
"offset": 0,
"total": 50
}
},
"BankLlmHealthResponse": {
"properties": {
"bank_id": {
"type": "string",
"title": "Bank Id",
"description": "Bank identifier"
},
"operations": {
"items": {
"$ref": "#/components/schemas/LlmOperationHealth"
},
"type": "array",
"title": "Operations",
"description": "Connectivity status per operation (retain, consolidation, reflect)"
}
},
"type": "object",
"required": [
"bank_id",
"operations"
],
"title": "BankLlmHealthResponse",
"description": "Per-bank LLM connectivity probe across retain/consolidation/reflect. Operations\nthat share a configuration are probed once. Discloses status only \u2014 never the\nprovider, model, endpoint, API key, or raw error.",
"example": {
"bank_id": "user123",
"operations": [
{
"latency_ms": 412.0,
"ok": true,
"operation": "retain",
"status": "connected"
},
{
"latency_ms": 412.0,
"ok": true,
"operation": "consolidation",
"status": "connected"
},
{
"ok": false,
"operation": "reflect",
"status": "not_configured"
}
]
}
},
"BankProfileResponse": {
"properties": {
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"name": {
"type": "string",
"title": "Name"
},
"disposition": {
"$ref": "#/components/schemas/DispositionTraits"
},
"mission": {
"type": "string",
"title": "Mission",
"description": "The agent's mission - who they are and what they're trying to accomplish"
},
"background": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Background",
"description": "Deprecated: use mission instead"
}
},
"type": "object",
"required": [
"bank_id",
"name",
"disposition",
"mission"
],
"title": "BankProfileResponse",
"description": "Response model for bank profile.",
"example": {
"bank_id": "user123",
"disposition": {
"empathy": 3,
"literalism": 3,
"skepticism": 3
},
"mission": "I am a software engineer helping my team stay organized and ship quality code",
"name": "Alice"
}
},
"BankStatsResponse": {
"properties": {
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"total_nodes": {
"type": "integer",
"title": "Total Nodes"
},
"total_links": {
"type": "integer",
"title": "Total Links"
},
"total_documents": {
"type": "integer",
"title": "Total Documents"
},
"nodes_by_fact_type": {
"additionalProperties": {
"type": "integer"
},
"type": "object",
"title": "Nodes By Fact Type"
},
"links_by_link_type": {
"additionalProperties": {
"type": "integer"
},
"type": "object",
"title": "Links By Link Type"
},
"links_by_fact_type": {
"additionalProperties": {
"type": "integer"
},
"type": "object",
"title": "Links By Fact Type"
},
"links_breakdown": {
"additionalProperties": {
"additionalProperties": {
"type": "integer"
},
"type": "object"
},
"type": "object",
"title": "Links Breakdown"
},
"pending_operations": {
"type": "integer",
"title": "Pending Operations"
},
"failed_operations": {
"type": "integer",
"title": "Failed Operations"
},
"operations_by_status": {
"additionalProperties": {
"type": "integer"
},
"type": "object",
"title": "Operations By Status",
"description": "Async operations grouped by status (pending, processing, completed, failed, cancelled)."
},
"last_consolidated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Consolidated At",
"description": "When consolidation last ran (ISO format)"
},
"last_memory_write_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Memory Write At",
"description": "When a memory was last written in this bank \u2014 stored, edited, or consolidated (ISO format). Null if the bank has no memories. A mental model whose `last_memory_seen_at` is at or after this is up to date whatever its tags; an older one may need a refresh, which only the single mental-model read can confirm."
},
"pending_consolidation": {
"type": "integer",
"title": "Pending Consolidation",
"description": "Number of source memories (world/experience) still queued for consolidation into observations. Excludes memories whose consolidation permanently failed \u2014 those are counted only in failed_consolidation \u2014 so this drains to 0 when the consolidator catches up.",
"default": 0
},
"failed_consolidation": {
"type": "integer",
"title": "Failed Consolidation",
"description": "Number of source memories (world/experience) whose consolidation permanently failed and can be retried via the consolidation recovery endpoint.",
"default": 0
},
"total_observations": {
"type": "integer",
"title": "Total Observations",
"description": "Total number of observations",
"default": 0
}
},
"type": "object",
"required": [
"bank_id",
"total_nodes",
"total_links",
"total_documents",
"nodes_by_fact_type",
"links_by_link_type",
"links_by_fact_type",
"links_breakdown",
"pending_operations",
"failed_operations"
],
"title": "BankStatsResponse",
"description": "Response model for bank statistics endpoint.",
"example": {
"bank_id": "user123",
"failed_consolidation": 0,
"failed_operations": 0,
"last_consolidated_at": "2024-01-15T10:30:00Z",
"last_memory_write_at": "2024-01-15T11:05:00Z",
"links_breakdown": {
"fact": {
"entity": 40,
"semantic": 60,
"temporal": 100
}
},
"links_by_fact_type": {
"fact": 200,
"observation": 40,
"preference": 60
},
"links_by_link_type": {
"entity": 50,
"semantic": 100,
"temporal": 150
},
"nodes_by_fact_type": {
"fact": 100,
"observation": 20,
"preference": 30
},
"pending_consolidation": 0,
"pending_operations": 2,
"total_documents": 10,
"total_links": 300,
"total_nodes": 150,
"total_observations": 45
}
},
"BankTemplateConfig": {
"properties": {
"reflect_mission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reflect Mission",
"description": "Mission/context for Reflect operations"
},
"retain_mission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Retain Mission",
"description": "Steers what gets extracted during retain"
},
"retain_extraction_mode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Retain Extraction Mode",
"description": "Fact extraction mode: 'concise' (default), 'verbose', 'custom', 'verbatim', or 'chunks'"
},
"retain_custom_instructions": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Retain Custom Instructions",
"description": "Custom extraction prompt (when mode='custom')"
},
"retain_chunk_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Retain Chunk Size",
"description": "Target max characters for each content chunk"
},
"retain_structured_chunk_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Retain Structured Chunk Size",
"description": "Max characters for a single JSONL line or conversation turn to keep whole; defaults to retain_chunk_size when unset"
},
"enable_observations": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Observations",
"description": "Toggle observation consolidation"
},
"observations_mission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Observations Mission",
"description": "Controls what gets synthesised"
},
"enable_text_search": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Text Search",
"description": "Toggle the keyword (BM25) arm during recall, leaving pure vector search"
},
"enable_temporal_retrieval": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Temporal Retrieval",
"description": "Toggle the temporal arm (and its date-aware query analysis) during recall"
},
"enable_graph_retrieval": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Graph Retrieval",
"description": "Toggle the entity/link graph arm during recall"
},
"enable_reranking": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Reranking",
"description": "Toggle cross-encoder reranking during recall"
},
"disposition_skepticism": {
"anyOf": [
{
"type": "integer",
"maximum": 5.0,
"minimum": 1.0
},
{
"type": "null"
}
],
"title": "Disposition Skepticism",
"description": "Skepticism trait (1-5)"
},
"disposition_literalism": {
"anyOf": [
{
"type": "integer",
"maximum": 5.0,
"minimum": 1.0
},
{
"type": "null"
}
],
"title": "Disposition Literalism",
"description": "Literalism trait (1-5)"
},
"disposition_empathy": {
"anyOf": [
{
"type": "integer",
"maximum": 5.0,
"minimum": 1.0
},
{
"type": "null"
}
],
"title": "Disposition Empathy",
"description": "Empathy trait (1-5)"
},
"entity_labels": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/LabelGroup-Output"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Entity Labels",
"description": "Controlled vocabulary for entity labels"
},
"entities_allow_free_form": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Entities Allow Free Form",
"description": "Allow entities outside the label vocabulary"
},
"retain_default_strategy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Retain Default Strategy",
"description": "Name of the default retain strategy (key into retain_strategies map)"
},
"retain_strategies": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Retain Strategies",
"description": "Map of retain strategy name to per-strategy config dict"
},
"retain_chunk_batch_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Retain Chunk Batch Size",
"description": "Max chunks per streaming batch (0 disables batching)"
},
"retain_max_attachments_per_chunk": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Retain Max Attachments Per Chunk",
"description": "Hard cap on inline images in a single extraction chunk"
},
"mcp_enabled_tools": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Mcp Enabled Tools",
"description": "MCP tool allowlist for this bank (None = all tools)"
},
"consolidation_llm_batch_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Consolidation Llm Batch Size",
"description": "LLM batch size for observation consolidation"
},
"consolidation_source_facts_max_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Consolidation Source Facts Max Tokens",
"description": "Max tokens of source facts per consolidation batch"
},
"consolidation_source_facts_max_tokens_per_observation": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Consolidation Source Facts Max Tokens Per Observation",
"description": "Max tokens of source facts per observation"
},
"max_observations_per_scope": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max Observations Per Scope",
"description": "Max observations to retain per consolidation scope"
},
"observation_scope_limits": {
"anyOf": [
{
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Observation Scope Limits",
"description": "Per-scope overrides of max_observations_per_scope: [{\"scope\": [\"run_*\", \"shared\"], \"limit\": 1}]. Each scope is a list of fnmatch tag-globs; a consolidation scope matches under exact cover (every tag matched by a glob and every glob matched by a tag). The first matching rule wins; unmatched scopes fall back to max_observations_per_scope."
},
"reflect_source_facts_max_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Reflect Source Facts Max Tokens",
"description": "Max tokens of source facts per reflect call"
},
"mental_model_min_refresh_interval_seconds": {
"anyOf": [
{
"type": "integer",
"minimum": 0.0
},
{
"type": "null"
}
],
"title": "Mental Model Min Refresh Interval Seconds",
"description": "Minimum seconds between two automatic refreshes of the same mental model in this bank. 0 (the default) means no floor. Overridable per model via the trigger's min_refresh_interval_seconds."
},
"llm_gemini_safety_settings": {
"anyOf": [
{
"items": {},
"type": "array"
},
{
"type": "null"
}
],
"title": "Llm Gemini Safety Settings",
"description": "Per-bank Gemini/VertexAI safety filter settings"
},
"recall_budget_function": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Recall Budget Function",
"description": "Recall budget mapping function: 'fixed' or 'adaptive'"
},
"recall_budget_fixed_low": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Recall Budget Fixed Low",
"description": "Fixed thinking_budget for budget=low (function='fixed')"
},
"recall_budget_fixed_mid": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Recall Budget Fixed Mid",
"description": "Fixed thinking_budget for budget=mid (function='fixed')"
},
"recall_budget_fixed_high": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Recall Budget Fixed High",
"description": "Fixed thinking_budget for budget=high (function='fixed')"
},
"recall_budget_adaptive_low": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Recall Budget Adaptive Low",
"description": "Ratio of max_tokens for budget=low (function='adaptive')"
},
"recall_budget_adaptive_mid": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Recall Budget Adaptive Mid",
"description": "Ratio of max_tokens for budget=mid (function='adaptive')"
},
"recall_budget_adaptive_high": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Recall Budget Adaptive High",
"description": "Ratio of max_tokens for budget=high (function='adaptive')"
},
"recall_budget_min": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Recall Budget Min",
"description": "Floor for the adaptive function (after clamping)"
},
"recall_budget_max": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Recall Budget Max",
"description": "Ceiling for the adaptive function (after clamping)"
},
"audit_log_enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Audit Log Enabled",
"description": "Enable audit logging for this bank (overrides the server default)"
},
"store_document_text": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Store Document Text",
"description": "Persist raw source text (documents.original_text / chunks.chunk_text). Set false to keep only derived facts."
},
"enable_auto_consolidation": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Auto Consolidation",
"description": "Automatically consolidate observations after retain"
},
"consolidation_max_memories_per_round": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Consolidation Max Memories Per Round",
"description": "Max memory units fed into a single consolidation round"
},
"consolidation_llm_parallelism": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Consolidation Llm Parallelism",
"description": "Number of consolidation LLM batches processed concurrently"
},
"recall_include_chunks": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Recall Include Chunks",
"description": "Include raw chunks in recall results"
},
"recall_max_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Recall Max Tokens",
"description": "Max tokens of results returned by recall"
},
"recall_chunks_max_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Recall Chunks Max Tokens",
"description": "Max tokens of raw chunks returned by recall (when recall_include_chunks is set)"
},
"memory_defense": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Memory Defense",
"description": "Memory Defense policy for this bank (validated against the DefensePolicy schema on write)"
}
},
"type": "object",
"title": "BankTemplateConfig",
"description": "Bank configuration fields within a template manifest.\n\nOnly includes configurable (per-bank) fields. Credential fields\n(API keys, base URLs) are intentionally excluded for security."
},
"BankTemplateDirective": {
"properties": {
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable name for the directive (used as match key on re-import)"
},
"content": {
"type": "string",
"title": "Content",
"description": "The directive text to inject into prompts"
},
"priority": {
"type": "integer",
"title": "Priority",
"description": "Higher priority directives are injected first",
"default": 0
},
"is_active": {
"type": "boolean",
"title": "Is Active",
"description": "Whether this directive is active",
"default": true
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"description": "Tags for filtering",
"default": []
}
},
"type": "object",
"required": [
"name",
"content"
],
"title": "BankTemplateDirective",
"description": "A directive definition within a bank template manifest.\n\nDirectives are matched by name on re-import: existing directives\nwith the same name are updated, new ones are created."
},
"BankTemplateImportResponse": {
"properties": {
"bank_id": {
"type": "string",
"title": "Bank Id",
"description": "Bank that was imported into"
},
"config_applied": {
"type": "boolean",
"title": "Config Applied",
"description": "Whether bank config was updated"
},
"mental_models_created": {
"items": {
"type": "string"
},
"type": "array",
"title": "Mental Models Created",
"description": "IDs of newly created mental models",
"default": []
},
"mental_models_updated": {
"items": {
"type": "string"
},
"type": "array",
"title": "Mental Models Updated",
"description": "IDs of updated mental models",
"default": []
},
"directives_created": {
"items": {
"type": "string"
},
"type": "array",
"title": "Directives Created",
"description": "Names of newly created directives",
"default": []
},
"directives_updated": {
"items": {
"type": "string"
},
"type": "array",
"title": "Directives Updated",
"description": "Names of updated directives",
"default": []
},
"operation_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Operation Ids",
"description": "Operation IDs for mental model content generation (async)",
"default": []
},
"dry_run": {
"type": "boolean",
"title": "Dry Run",
"description": "True if this was a validation-only run",
"default": false
}
},
"type": "object",
"required": [
"bank_id",
"config_applied"
],
"title": "BankTemplateImportResponse",
"description": "Response model for the bank template import endpoint."
},
"BankTemplateManifest": {
"properties": {
"version": {
"type": "string",
"title": "Version",
"description": "Manifest schema version (currently '1')"
},
"bank": {
"anyOf": [
{
"$ref": "#/components/schemas/BankTemplateConfig"
},
{
"type": "null"
}
],
"description": "Bank configuration to apply. Omit to leave config unchanged."
},
"mental_models": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/BankTemplateMentalModel"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Mental Models",
"description": "Mental models to create or update (matched by id). Omit to leave unchanged."
},
"directives": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/BankTemplateDirective"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Directives",
"description": "Directives to create or update (matched by name). Omit to leave unchanged."
}
},
"type": "object",
"required": [
"version"
],
"title": "BankTemplateManifest",
"description": "A bank template manifest for import/export.\n\nVersion field enables forward-compatible schema evolution: the API\nauto-upgrades older manifest versions to the current schema on import.",
"example": {
"bank": {
"disposition_empathy": 5,
"enable_observations": true,
"reflect_mission": "You are helping a support agent remember customer interactions.",
"retain_mission": "Extract customer issues, resolutions, and sentiment."
},
"directives": [
{
"content": "Always respond with empathy and understanding.",
"name": "Always be empathetic",
"priority": 10
}
],
"mental_models": [
{
"id": "sentiment-overview",
"name": "Customer Sentiment Overview",
"source_query": "What is the overall sentiment trend?",
"trigger": {
"refresh_after_consolidation": true
}
}
],
"version": "1"
}
},
"BankTemplateMentalModel": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Unique ID for the mental model (alphanumeric lowercase with hyphens)"
},
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable name for the mental model"
},
"source_query": {
"type": "string",
"title": "Source Query",
"description": "The query to run to generate content"
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"description": "Tags for scoped visibility",
"default": []
},
"max_tokens": {
"type": "integer",
"maximum": 8192.0,
"minimum": 256.0,
"title": "Max Tokens",
"description": "Maximum tokens for generated content",
"default": 2048
},
"trigger": {
"$ref": "#/components/schemas/MentalModelTrigger-Output",
"description": "Trigger settings",
"default": {}
}
},
"type": "object",
"required": [
"id",
"name",
"source_query"
],
"title": "BankTemplateMentalModel",
"description": "A mental model definition within a bank template manifest."
},
"Base64AttachmentSource": {
"properties": {
"type": {
"type": "string",
"const": "base64",
"title": "Type",
"default": "base64"
},
"media_type": {
"type": "string",
"title": "Media Type",
"description": "MIME type of the attachment, e.g. 'image/png' or 'application/pdf'. Any well-formed type is accepted; whether the model can read it is the model's answer to give, and a provider that rejects it fails the retain with its own error."
},
"data": {
"type": "string",
"title": "Data",
"description": "Base64-encoded bytes (no data: URI prefix)."
}
},
"type": "object",
"required": [
"media_type",
"data"
],
"title": "Base64AttachmentSource",
"description": "Inline attachment bytes, base64-encoded.\n\nThe only source type in this version. ``url`` (server-side fetch) and\n``blob_id`` (pre-uploaded handle) are the natural next ones, which is why this\nis modelled as a discriminated union on ``type`` rather than as bare fields."
},
"Body_file_retain": {
"properties": {
"files": {
"items": {
"type": "string",
"format": "binary"
},
"type": "array",
"title": "Files",
"description": "Files to upload and convert"
},
"request": {
"type": "string",
"title": "Request",
"description": "JSON string with FileRetainRequest model"
}
},
"type": "object",
"required": [
"files",
"request"
],
"title": "Body_file_retain"
},
"Body_import_documents": {
"properties": {
"file": {
"type": "string",
"title": "File",
"description": "Transfer ZIP archive",
"format": "binary"
}
},
"type": "object",
"required": [
"file"
],
"title": "Body_import_documents"
},
"Budget": {
"type": "string",
"enum": [
"low",
"mid",
"high"
],
"title": "Budget",
"description": "Budget levels for recall/reflect operations."
},
"CancelOperationResponse": {
"properties": {
"success": {
"type": "boolean",
"title": "Success"
},
"message": {
"type": "string",
"title": "Message"
},
"operation_id": {
"type": "string",
"title": "Operation Id"
}
},
"type": "object",
"required": [
"success",
"message",
"operation_id"
],
"title": "CancelOperationResponse",
"description": "Response model for cancel operation endpoint.",
"example": {
"message": "Operation 550e8400-e29b-41d4-a716-446655440000 cancelled",
"operation_id": "550e8400-e29b-41d4-a716-446655440000",
"success": true
}
},
"ChildOperationStatus": {
"properties": {
"operation_id": {
"type": "string",
"title": "Operation Id"
},
"status": {
"type": "string",
"title": "Status"
},
"sub_batch_index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Sub Batch Index"
},
"items_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Items Count"
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error Message"
}
},
"type": "object",
"required": [
"operation_id",
"status"
],
"title": "ChildOperationStatus",
"description": "Status of a child operation (for batch operations)."
},
"ChunkAttachment": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "The id inside the text's placeholder; a prefix of the bytes' sha256."
},
"hash": {
"type": "string",
"title": "Hash",
"description": "Full sha256 of the attachment bytes."
},
"kind": {
"type": "string",
"title": "Kind",
"description": "'image' or 'file', as the caller sent it."
},
"media_type": {
"type": "string",
"title": "Media Type",
"description": "MIME type of the attachment."
},
"byte_size": {
"type": "integer",
"title": "Byte Size",
"description": "Size of the attachment in bytes."
},
"filename": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Filename",
"description": "Original filename, when the caller supplied one."
},
"url": {
"type": "string",
"title": "Url",
"description": "Bank-scoped API path serving the bytes. Requires the same authorization as the bank."
}
},
"type": "object",
"required": [
"id",
"hash",
"kind",
"media_type",
"byte_size",
"url"
],
"title": "ChunkAttachment",
"description": "An attachment referenced by retained text, and where to fetch it."
},
"ChunkData": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"text": {
"type": "string",
"title": "Text"
},
"chunk_index": {
"type": "integer",
"title": "Chunk Index"
},
"truncated": {
"type": "boolean",
"title": "Truncated",
"description": "Whether the chunk text was truncated due to token limits",
"default": false
},
"attachments": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/ChunkAttachment"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attachments",
"description": "Attachments this chunk's text references, in order of first appearance, when it was retained with inline content. The text keeps each attachment's placeholder token (\u27e6hs-att:...\u27e7) where it sat, so a multimodal agent can render or reason over the original at the position it occupied in the source document. Omitted when there are none."
}
},
"type": "object",
"required": [
"id",
"text",
"chunk_index"
],
"title": "ChunkData",
"description": "Chunk data for a single chunk."
},
"ChunkIncludeOptions": {
"properties": {
"max_tokens": {
"type": "integer",
"title": "Max Tokens",
"description": "Maximum tokens for chunks (chunks may be truncated)",
"default": 8192
}
},
"type": "object",
"title": "ChunkIncludeOptions",
"description": "Options for including chunks in recall results."
},
"ChunkResponse": {
"properties": {
"chunk_id": {
"type": "string",
"title": "Chunk Id"
},
"document_id": {
"type": "string",
"title": "Document Id"
},
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"chunk_index": {
"type": "integer",
"title": "Chunk Index"
},
"chunk_text": {
"type": "string",
"title": "Chunk Text"
},
"created_at": {
"type": "string",
"title": "Created At"
},
"attachments": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/ChunkAttachment"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attachments",
"description": "Attachments referenced by this chunk's text, when it was retained with inline content. Each carries a bank-scoped `url` serving the original bytes. Omitted when there are none."
}
},
"type": "object",
"required": [
"chunk_id",
"document_id",
"bank_id",
"chunk_index",
"chunk_text",
"created_at"
],
"title": "ChunkResponse",
"description": "Response model for get chunk endpoint.",
"example": {
"bank_id": "user123",
"chunk_id": "user123_session_1_0",
"chunk_index": 0,
"chunk_text": "This is the first chunk of the document...",
"created_at": "2024-01-15T10:30:00Z",
"document_id": "session_1"
}
},
"ClearMemoryObservationsResponse": {
"properties": {
"deleted_count": {
"type": "integer",
"title": "Deleted Count"
}
},
"type": "object",
"required": [
"deleted_count"
],
"title": "ClearMemoryObservationsResponse",
"description": "Response model for clearing observations for a specific memory.",
"example": {
"deleted_count": 3
}
},
"ConsolidationRequest": {
"properties": {
"observation_scopes": {
"anyOf": [
{
"items": {
"items": {
"type": "string"
},
"type": "array"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Observation Scopes",
"description": "Optional list of tag scopes to consolidate. Each scope is a list of tags. Only unconsolidated memories whose tags contain all tags in at least one scope will be processed. If omitted, all unconsolidated memories are processed."
}
},
"type": "object",
"title": "ConsolidationRequest",
"description": "Request model for consolidation trigger endpoint."
},
"ConsolidationResponse": {
"properties": {
"operation_id": {
"type": "string",
"title": "Operation Id",
"description": "ID of the async consolidation operation"
},
"deduplicated": {
"type": "boolean",
"title": "Deduplicated",
"description": "True if an existing pending task was reused",
"default": false
}
},
"type": "object",
"required": [
"operation_id"
],
"title": "ConsolidationResponse",
"description": "Response model for consolidation trigger endpoint."
},
"CreateBankRequest": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Deprecated: display label only, not advertised"
},
"disposition": {
"anyOf": [
{
"$ref": "#/components/schemas/DispositionTraits"
},
{
"type": "null"
}
],
"description": "Deprecated: use update_bank_config instead"
},
"disposition_skepticism": {
"anyOf": [
{
"type": "integer",
"maximum": 5.0,
"minimum": 1.0
},
{
"type": "null"
}
],
"title": "Disposition Skepticism",
"description": "Deprecated: use update_bank_config instead"
},
"disposition_literalism": {
"anyOf": [
{
"type": "integer",
"maximum": 5.0,
"minimum": 1.0
},
{
"type": "null"
}
],
"title": "Disposition Literalism",
"description": "Deprecated: use update_bank_config instead"
},
"disposition_empathy": {
"anyOf": [
{
"type": "integer",
"maximum": 5.0,
"minimum": 1.0
},
{
"type": "null"
}
],
"title": "Disposition Empathy",
"description": "Deprecated: use update_bank_config instead"
},
"mission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mission",
"description": "Deprecated: use update_bank_config with reflect_mission instead"
},
"background": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Background",
"description": "Deprecated: use update_bank_config with reflect_mission instead"
},
"reflect_mission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reflect Mission",
"description": "Mission/context for Reflect operations. Guides how Reflect interprets and uses memories."
},
"retain_mission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Retain Mission",
"description": "Steers what gets extracted during retain(). Injected alongside built-in extraction rules."
},
"retain_extraction_mode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Retain Extraction Mode",
"description": "Fact extraction mode: 'concise' (default), 'verbose', 'custom', 'verbatim', or 'chunks'."
},
"retain_custom_instructions": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Retain Custom Instructions",
"description": "Custom extraction prompt. Only active when retain_extraction_mode is 'custom'."
},
"retain_chunk_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Retain Chunk Size",
"description": "Target maximum characters for each content chunk during retain."
},
"retain_structured_chunk_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Retain Structured Chunk Size",
"description": "Maximum characters for a single JSONL line or conversation turn to keep whole during retain. Defaults to retain_chunk_size when unset."
},
"retain_max_attachments_per_chunk": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Retain Max Attachments Per Chunk",
"description": "Maximum inline attachments one extraction chunk may carry. retain_chunk_size budgets text only \u2014 a placeholder costs the characters it occupies and nothing more \u2014 so this is what bounds attachments. Match it to the provider's per-request limit."
},
"enable_observations": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Observations",
"description": "Toggle automatic observation consolidation after retain()."
},
"observations_mission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Observations Mission",
"description": "Controls what gets synthesised into observations. Replaces built-in consolidation rules entirely."
},
"enable_text_search": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Text Search",
"description": "Toggle the keyword (BM25) retrieval arm during recall. Disabling leaves pure vector search: the arm is left out of the query entirely rather than filtered to nothing, so none of its cost is paid. Also drops the keyword arm from knowledge-page search."
},
"enable_temporal_retrieval": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Temporal Retrieval",
"description": "Toggle the temporal retrieval arm during recall, together with the date-aware query analysis that feeds it. Useful for banks whose content carries no meaningful dates."
},
"enable_graph_retrieval": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Graph Retrieval",
"description": "Toggle the entity/link graph traversal arm during recall. Disabling trades relational recall for latency on banks whose content has little entity structure."
},
"enable_reranking": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Reranking",
"description": "Toggle cross-encoder reranking during recall. Disabling returns the RRF-fused ordering directly, which is faster but less precise."
}
},
"type": "object",
"title": "CreateBankRequest",
"description": "Request model for creating/updating a bank.",
"example": {
"observations_mission": "Observations are stable facts about people and projects. Always include preferences and skills.",
"retain_mission": "Always include technical decisions and architectural trade-offs. Ignore meeting logistics."
}
},
"CreateDirectiveRequest": {
"properties": {
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable name for the directive"
},
"content": {
"type": "string",
"title": "Content",
"description": "The directive text to inject into prompts"
},
"priority": {
"type": "integer",
"title": "Priority",
"description": "Higher priority directives are injected first",
"default": 0
},
"is_active": {
"type": "boolean",
"title": "Is Active",
"description": "Whether this directive is active",
"default": true
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"description": "Directive execution scope. Empty means global; non-empty requires a matching reflect scope.",
"default": []
}
},
"type": "object",
"required": [
"name",
"content"
],
"title": "CreateDirectiveRequest",
"description": "Request model for creating a directive."
},
"CreateFolderRequest": {
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"parent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Parent Id"
}
},
"type": "object",
"required": [
"name"
],
"title": "CreateFolderRequest",
"description": "Create a folder under an optional parent folder."
},
"CreateKnowledgePageResponse": {
"properties": {
"page_id": {
"type": "string",
"title": "Page Id"
},
"mental_model_id": {
"type": "string",
"title": "Mental Model Id"
},
"operation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Operation Id"
}
},
"type": "object",
"required": [
"page_id",
"mental_model_id"
],
"title": "CreateKnowledgePageResponse",
"description": "Result of creating a page: the node id, its mental model, and the refresh op."
},
"CreateMentalModelRequest": {
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id",
"description": "Optional custom ID for the mental model (alphanumeric lowercase with hyphens)"
},
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable name for the mental model"
},
"source_query": {
"type": "string",
"title": "Source Query",
"description": "The query to run to generate content"
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"description": "Tags for scoped visibility",
"default": []
},
"max_tokens": {
"type": "integer",
"maximum": 8192.0,
"minimum": 256.0,
"title": "Max Tokens",
"description": "Maximum tokens for generated content",
"default": 2048
},
"trigger": {
"$ref": "#/components/schemas/MentalModelTrigger-Input",
"description": "Trigger settings",
"default": {}
}
},
"type": "object",
"required": [
"name",
"source_query"
],
"title": "CreateMentalModelRequest",
"description": "Request model for creating a mental model.",
"example": {
"id": "team-communication",
"max_tokens": 2048,
"name": "Team Communication Preferences",
"source_query": "How does the team prefer to communicate?",
"tags": [
"team"
],
"trigger": {
"refresh_after_consolidation": false
}
}
},
"CreateMentalModelResponse": {
"properties": {
"mental_model_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mental Model Id",
"description": "ID of the created mental model"
},
"operation_id": {
"type": "string",
"title": "Operation Id",
"description": "Operation ID to track refresh progress"
}
},
"type": "object",
"required": [
"operation_id"
],
"title": "CreateMentalModelResponse",
"description": "Response model for mental model creation."
},
"CreatePageRequest": {
"properties": {
"name": {
"type": "string",
"title": "Name"
},
"source_query": {
"type": "string",
"title": "Source Query"
},
"parent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Parent Id"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags",
"description": "Tags that SCOPE which memories this page is built from \u2014 not labels. Every tag here, including a `type:<x>` tag used to set the page's rendered type, is part of the filter. By default a tagged page matches with `all_strict`: a memory must carry EVERY one of these tags, and untagged memories are excluded entirely. Tags invented for the page (a topic, a document type) therefore match nothing unless your memories were retained with those exact tags, and the page generates as 'I don't have information about this'. Omit this field to build the page from the whole bank, or set `trigger.tags_match` to 'all' to require the tags while still including untagged memories."
},
"max_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max Tokens"
},
"trigger": {
"anyOf": [
{
"$ref": "#/components/schemas/MentalModelTrigger-Input"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"name",
"source_query"
],
"title": "CreatePageRequest",
"description": "Create a page (a mental model + tree node) under an optional parent folder."
},
"CreateWebhookRequest": {
"properties": {
"url": {
"type": "string",
"title": "Url",
"description": "HTTP(S) endpoint URL to deliver events to"
},
"secret": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Secret",
"description": "HMAC-SHA256 signing secret (optional)"
},
"event_types": {
"items": {
"type": "string"
},
"type": "array",
"title": "Event Types",
"description": "List of event types to deliver. Supported: 'retain.completed', 'consolidation.completed', 'memory_defense.triggered'.",
"default": [
"consolidation.completed"
]
},
"enabled": {
"type": "boolean",
"title": "Enabled",
"description": "Whether this webhook is active",
"default": true
},
"http_config": {
"$ref": "#/components/schemas/WebhookHttpConfig",
"description": "HTTP delivery configuration (method, timeout, headers, params)"
}
},
"type": "object",
"required": [
"url"
],
"title": "CreateWebhookRequest",
"description": "Request model for registering a webhook."
},
"DeleteDocumentResponse": {
"properties": {
"success": {
"type": "boolean",
"title": "Success"
},
"message": {
"type": "string",
"title": "Message"
},
"document_id": {
"type": "string",
"title": "Document Id"
},
"memory_units_deleted": {
"type": "integer",
"title": "Memory Units Deleted"
}
},
"type": "object",
"required": [
"success",
"message",
"document_id",
"memory_units_deleted"
],
"title": "DeleteDocumentResponse",
"description": "Response model for delete document endpoint.",
"example": {
"document_id": "session_1",
"memory_units_deleted": 5,
"message": "Document 'session_1' and 5 associated memory units deleted successfully",
"success": true
}
},
"DeleteOperationResponse": {
"properties": {
"success": {
"type": "boolean",
"title": "Success"
},
"message": {
"type": "string",
"title": "Message"
},
"operation_id": {
"type": "string",
"title": "Operation Id"
}
},
"type": "object",
"required": [
"success",
"message",
"operation_id"
],
"title": "DeleteOperationResponse",
"description": "Response model for delete operation endpoint.",
"example": {
"message": "Operation 550e8400-e29b-41d4-a716-446655440000 deleted",
"operation_id": "550e8400-e29b-41d4-a716-446655440000",
"success": true
}
},
"DeleteResponse": {
"properties": {
"success": {
"type": "boolean",
"title": "Success"
},
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Message"
},
"deleted_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Deleted Count"
}
},
"type": "object",
"required": [
"success"
],
"title": "DeleteResponse",
"description": "Response model for delete operations.",
"example": {
"deleted_count": 10,
"message": "Deleted successfully",
"success": true
}
},
"DirectiveListResponse": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/DirectiveResponse"
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"title": "Total",
"description": "Total number of directives matching the filter (not just this page)"
},
"limit": {
"type": "integer",
"title": "Limit",
"description": "Page size that was applied"
},
"offset": {
"type": "integer",
"title": "Offset",
"description": "Offset that was applied"
}
},
"type": "object",
"required": [
"items",
"total",
"limit",
"offset"
],
"title": "DirectiveListResponse",
"description": "Response model for listing directives."
},
"DirectiveResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"name": {
"type": "string",
"title": "Name"
},
"content": {
"type": "string",
"title": "Content"
},
"priority": {
"type": "integer",
"title": "Priority",
"default": 0
},
"is_active": {
"type": "boolean",
"title": "Is Active",
"default": true
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"default": []
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"bank_id",
"name",
"content"
],
"title": "DirectiveResponse",
"description": "Response model for a directive."
},
"DispositionTraits": {
"properties": {
"skepticism": {
"type": "integer",
"maximum": 5.0,
"minimum": 1.0,
"title": "Skepticism",
"description": "How skeptical vs trusting (1=trusting, 5=skeptical)"
},
"literalism": {
"type": "integer",
"maximum": 5.0,
"minimum": 1.0,
"title": "Literalism",
"description": "How literally to interpret information (1=flexible, 5=literal)"
},
"empathy": {
"type": "integer",
"maximum": 5.0,
"minimum": 1.0,
"title": "Empathy",
"description": "How much to consider emotional context (1=detached, 5=empathetic)"
}
},
"type": "object",
"required": [
"skepticism",
"literalism",
"empathy"
],
"title": "DispositionTraits",
"description": "Disposition traits that influence how memories are formed and interpreted.",
"example": {
"empathy": 3,
"literalism": 3,
"skepticism": 3
}
},
"DocumentExportSubmitResponse": {
"properties": {
"operation_id": {
"type": "string",
"title": "Operation Id"
},
"status": {
"type": "string",
"title": "Status",
"default": "pending"
}
},
"type": "object",
"required": [
"operation_id"
],
"title": "DocumentExportSubmitResponse",
"description": "Response for the async document-export endpoint (202).\n\nThe export runs in the background; poll the operations endpoint for status.\nOn completion the operation's ``result_metadata`` carries ``download_url``\n(fetch the ZIP from GET /v1/default/files/download/{key}), ``storage_key``,\n``byte_size``, and ``filename``."
},
"DocumentImportSubmitResponse": {
"properties": {
"operation_id": {
"type": "string",
"title": "Operation Id"
},
"status": {
"type": "string",
"title": "Status",
"default": "pending"
}
},
"type": "object",
"required": [
"operation_id"
],
"title": "DocumentImportSubmitResponse",
"description": "Response for the async document-import endpoint (202).\n\nThe import runs in the background; poll the operations endpoint for status.\nThe imported/skipped counts (documents_imported, facts_imported,\nobservations_imported, etc.) are written to the operation's result_metadata."
},
"DocumentResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"original_text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Original Text"
},
"content_hash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content Hash"
},
"created_at": {
"type": "string",
"title": "Created At"
},
"updated_at": {
"type": "string",
"title": "Updated At"
},
"memory_unit_count": {
"type": "integer",
"title": "Memory Unit Count"
},
"nodes_by_fact_type": {
"anyOf": [
{
"additionalProperties": {
"type": "integer"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Nodes By Fact Type",
"description": "Memory count per fact type (world, experience, observation)"
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"description": "Tags associated with this document",
"default": []
},
"document_metadata": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Document Metadata",
"description": "Document metadata"
},
"retain_params": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Retain Params",
"description": "Parameters used during retain"
},
"observation_scopes": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"items": {
"type": "string"
},
"type": "array"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Observation Scopes",
"description": "The observation_scopes spec configured at retain time (e.g. 'all_combinations', 'per_tag', or explicit tag-set lists), captured into retain_params. None when none was set (default 'combined' scoping) or for documents retained before this was captured."
},
"attachments": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/ChunkAttachment"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Attachments",
"description": "Attachments referenced by this document, when it was retained with inline content. Each carries a bank-scoped `url` serving the original bytes. Omitted when there are none."
}
},
"type": "object",
"required": [
"id",
"bank_id",
"original_text",
"content_hash",
"created_at",
"updated_at",
"memory_unit_count"
],
"title": "DocumentResponse",
"description": "Response model for get document endpoint.",
"example": {
"bank_id": "user123",
"content_hash": "abc123",
"created_at": "2024-01-15T10:30:00Z",
"document_metadata": {
"channel": "#general",
"source": "slack"
},
"id": "session_1",
"memory_unit_count": 15,
"original_text": "Full document text here...",
"retain_params": {
"context": "Team meeting notes",
"event_date": "2024-01-15"
},
"tags": [
"user_a",
"session_123"
],
"updated_at": "2024-01-15T10:30:00Z"
}
},
"DryRunExtractRequest": {
"properties": {
"content": {
"type": "string",
"title": "Content",
"description": "Text to extract facts from (e.g. a document or a single chunk)."
},
"context": {
"type": "string",
"title": "Context",
"description": "Optional context about the content.",
"default": ""
},
"timestamp": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Timestamp",
"description": "Reference timestamp for resolving relative times (ISO 8601)."
},
"agent_name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Agent Name",
"description": "Deprecated: describe the speaker in `context` instead. Narrator override (memory owner) primed in the prompt; still honored for backwards compatibility.",
"deprecated": true
},
"strategy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Strategy",
"description": "Name of a retain strategy to extract under (a key of the bank's `retain_strategies`). Omit it and the bank's `retain_default_strategy` applies, exactly as it does for a retain that names none."
},
"retain_mission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Retain Mission"
},
"retain_extraction_mode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Retain Extraction Mode"
},
"retain_custom_instructions": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Retain Custom Instructions"
},
"retain_extract_causal_links": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Retain Extract Causal Links"
},
"retain_chunk_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Retain Chunk Size"
},
"entity_labels": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/LabelGroup-Input"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Entity Labels",
"description": "Controlled vocabulary for entity labels (overrides the bank's config for this call)"
},
"entities_allow_free_form": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Entities Allow Free Form"
},
"llm_output_language": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Llm Output Language"
}
},
"type": "object",
"required": [
"content"
],
"title": "DryRunExtractRequest",
"description": "Request to run fact extraction ONLY (no resolution/links/embeddings/persistence).\n\nEvery field below the content/context/date is a prompt-affecting override applied just for this\ncall \u2014 used to preview what a candidate retain mission (or any extraction setting) would extract,\nwithout changing the bank. Unset (null) fields fall back to the bank's resolved config."
},
"DryRunExtractionResult": {
"properties": {
"facts": {
"items": {
"$ref": "#/components/schemas/ExtractedFact"
},
"type": "array",
"title": "Facts",
"description": "Candidate facts the retain step would extract."
},
"chunks": {
"items": {
"$ref": "#/components/schemas/ExtractionChunk"
},
"type": "array",
"title": "Chunks",
"description": "The chunks the input was cut into before extraction. Already computed on every path; returned because `retain_chunk_size` is otherwise a number with no visible effect."
},
"usage": {
"$ref": "#/components/schemas/TokenUsage",
"description": "Aggregated token usage across the extraction LLM calls."
}
},
"type": "object",
"title": "DryRunExtractionResult",
"description": "Result of dry-run fact extraction: candidate facts, the chunks they came from,\nand aggregated LLM token usage."
},
"EntityDetailResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"canonical_name": {
"type": "string",
"title": "Canonical Name"
},
"mention_count": {
"type": "integer",
"title": "Mention Count"
},
"first_seen": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "First Seen"
},
"last_seen": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Seen"
},
"metadata": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Metadata"
},
"observations": {
"items": {
"$ref": "#/components/schemas/EntityObservationResponse"
},
"type": "array",
"title": "Observations"
}
},
"type": "object",
"required": [
"id",
"canonical_name",
"mention_count",
"observations"
],
"title": "EntityDetailResponse",
"description": "Response model for entity detail endpoint.",
"example": {
"canonical_name": "John",
"first_seen": "2024-01-15T10:30:00Z",
"id": "123e4567-e89b-12d3-a456-426614174000",
"last_seen": "2024-02-01T14:00:00Z",
"mention_count": 15,
"observations": [
{
"mentioned_at": "2024-01-15T10:30:00Z",
"text": "John works at Google"
}
]
}
},
"EntityGraphResponse": {
"properties": {
"nodes": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Nodes"
},
"edges": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Edges"
},
"total_entities": {
"type": "integer",
"title": "Total Entities"
},
"total_edges": {
"type": "integer",
"title": "Total Edges"
},
"limit": {
"type": "integer",
"title": "Limit"
}
},
"type": "object",
"required": [
"nodes",
"edges",
"total_entities",
"total_edges",
"limit"
],
"title": "EntityGraphResponse",
"description": "Response model for entity co-occurrence graph endpoint.",
"example": {
"edges": [
{
"data": {
"color": "#ffd700",
"id": "uuid-1-uuid-2",
"lastCooccurred": "2024-02-01T14:00:00Z",
"lineStyle": "solid",
"linkType": "cooccurrence",
"source": "uuid-1",
"target": "uuid-2",
"weight": 5
}
}
],
"limit": 1000,
"nodes": [
{
"data": {
"color": "#42a5f5",
"id": "uuid-1",
"label": "Alice",
"mentionCount": 12
}
},
{
"data": {
"color": "#42a5f5",
"id": "uuid-2",
"label": "Google",
"mentionCount": 8
}
}
],
"total_edges": 1,
"total_entities": 2
}
},
"EntityIncludeOptions": {
"properties": {
"max_tokens": {
"type": "integer",
"title": "Max Tokens",
"description": "Maximum tokens for entity observations",
"default": 500
}
},
"type": "object",
"title": "EntityIncludeOptions",
"description": "Options for including entity observations in recall results."
},
"EntityInput": {
"properties": {
"text": {
"type": "string",
"title": "Text",
"description": "The entity name/text"
},
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Type",
"description": "Optional entity type (e.g., 'PERSON', 'ORG', 'CONCEPT')"
}
},
"type": "object",
"required": [
"text"
],
"title": "EntityInput",
"description": "Entity to associate with retained content."
},
"EntityListItem": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"canonical_name": {
"type": "string",
"title": "Canonical Name"
},
"mention_count": {
"type": "integer",
"title": "Mention Count"
},
"first_seen": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "First Seen"
},
"last_seen": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Seen"
},
"metadata": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Metadata"
}
},
"type": "object",
"required": [
"id",
"canonical_name",
"mention_count"
],
"title": "EntityListItem",
"description": "Entity list item with summary.",
"example": {
"canonical_name": "John",
"first_seen": "2024-01-15T10:30:00Z",
"id": "123e4567-e89b-12d3-a456-426614174000",
"last_seen": "2024-02-01T14:00:00Z",
"mention_count": 15
}
},
"EntityListResponse": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/EntityListItem"
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"title": "Total"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
}
},
"type": "object",
"required": [
"items",
"total",
"limit",
"offset"
],
"title": "EntityListResponse",
"description": "Response model for entity list endpoint.",
"example": {
"items": [
{
"canonical_name": "John",
"first_seen": "2024-01-15T10:30:00Z",
"id": "123e4567-e89b-12d3-a456-426614174000",
"last_seen": "2024-02-01T14:00:00Z",
"mention_count": 15
}
],
"limit": 100,
"offset": 0,
"total": 150
}
},
"EntityObservationResponse": {
"properties": {
"text": {
"type": "string",
"title": "Text"
},
"mentioned_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mentioned At"
}
},
"type": "object",
"required": [
"text"
],
"title": "EntityObservationResponse",
"description": "An observation about an entity."
},
"EntityStateResponse": {
"properties": {
"entity_id": {
"type": "string",
"title": "Entity Id"
},
"canonical_name": {
"type": "string",
"title": "Canonical Name"
},
"observations": {
"items": {
"$ref": "#/components/schemas/EntityObservationResponse"
},
"type": "array",
"title": "Observations"
}
},
"type": "object",
"required": [
"entity_id",
"canonical_name",
"observations"
],
"title": "EntityStateResponse",
"description": "Current mental model of an entity."
},
"ExtractedFact": {
"properties": {
"text": {
"type": "string",
"title": "Text",
"description": "The extracted fact text."
},
"fact_type": {
"type": "string",
"title": "Fact Type",
"description": "Perspective classification: 'world' or 'experience'."
},
"occurred_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Occurred Start",
"description": "ISO timestamp the fact's event started, if dated."
},
"occurred_end": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Occurred End",
"description": "ISO timestamp the fact's event ended, if dated."
},
"entities": {
"items": {
"type": "string"
},
"type": "array",
"title": "Entities",
"description": "Raw (unresolved) entity names mentioned in the fact."
},
"chunk_index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Chunk Index",
"description": "Index into `chunks` of the chunk this fact came from; null if it could not be attributed."
}
},
"type": "object",
"required": [
"text",
"fact_type"
],
"title": "ExtractedFact",
"description": "A single candidate fact produced by dry-run extraction (no resolution/links/persistence).\n\nA deliberate subset of the persisted memory-unit shape \u2014 only the fields a fresh extraction\nyields. Storage/consolidation/curation fields (id, document_id, chunk_id, proof_count, state, \u2026)\nare omitted because nothing is stored. Entities are raw, unresolved names."
},
"ExtractionChunk": {
"properties": {
"text": {
"type": "string",
"title": "Text",
"description": "The chunk as the extractor saw it."
},
"fact_count": {
"type": "integer",
"title": "Fact Count",
"description": "How many facts came out of this chunk."
}
},
"type": "object",
"required": [
"text",
"fact_count"
],
"title": "ExtractionChunk",
"description": "One chunk the extractor was handed, and how much it yielded."
},
"FactsIncludeOptions": {
"properties": {},
"type": "object",
"title": "FactsIncludeOptions",
"description": "Options for including facts (based_on) in reflect results."
},
"FeaturesInfo": {
"properties": {
"observations": {
"type": "boolean",
"title": "Observations",
"description": "Whether observations (auto-consolidation) are enabled"
},
"mcp": {
"type": "boolean",
"title": "Mcp",
"description": "Whether MCP (Model Context Protocol) server is enabled"
},
"worker": {
"type": "boolean",
"title": "Worker",
"description": "Whether the background worker is enabled"
},
"bank_config_api": {
"type": "boolean",
"title": "Bank Config Api",
"description": "Whether per-bank configuration API is enabled"
},
"bank_llm_health": {
"type": "boolean",
"title": "Bank Llm Health",
"description": "Whether the per-bank LLM connectivity probe is enabled"
},
"file_upload_api": {
"type": "boolean",
"title": "File Upload Api",
"description": "Whether file upload/conversion API is enabled"
},
"document_export_api": {
"type": "boolean",
"title": "Document Export Api",
"description": "Whether the document export endpoint is enabled"
},
"document_import_api": {
"type": "boolean",
"title": "Document Import Api",
"description": "Whether the document import endpoint is enabled"
},
"audit_log": {
"type": "boolean",
"title": "Audit Log",
"description": "Whether audit logging is enabled by default (overridable per bank)"
},
"llm_trace": {
"type": "boolean",
"title": "Llm Trace",
"description": "Whether per-bank LLM request tracing is enabled"
},
"store_document_text": {
"type": "boolean",
"title": "Store Document Text",
"description": "Whether raw source text is persisted. When false, document/chunk source text is not stored."
}
},
"type": "object",
"required": [
"observations",
"mcp",
"worker",
"bank_config_api",
"bank_llm_health",
"file_upload_api",
"document_export_api",
"document_import_api",
"audit_log",
"llm_trace",
"store_document_text"
],
"title": "FeaturesInfo",
"description": "Feature flags indicating which capabilities are enabled."
},
"FileContentBlock": {
"properties": {
"type": {
"type": "string",
"const": "file",
"title": "Type"
},
"source": {
"$ref": "#/components/schemas/Base64AttachmentSource"
},
"filename": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Filename",
"description": "Original filename, passed to providers that show one to the model (e.g. OpenAI)."
}
},
"type": "object",
"required": [
"type",
"source"
],
"title": "FileContentBlock",
"description": "A non-image attachment \u2014 a PDF, a spreadsheet \u2014 in the position it was written.\n\nSplit from ``image`` rather than folded into one type because the providers\nsplit it: Anthropic has distinct image and document blocks, OpenAI has\nimage_url and file parts. Carrying the caller's own distinction through means\nthe per-provider conversion never has to guess from the media type alone."
},
"FileRetainResponse": {
"properties": {
"operation_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Operation Ids",
"description": "Operation IDs for tracking file conversion operations. Use GET /v1/default/banks/{bank_id}/operations to list operations."
}
},
"type": "object",
"required": [
"operation_ids"
],
"title": "FileRetainResponse",
"description": "Response model for file upload endpoint.",
"example": {
"operation_ids": [
"550e8400-e29b-41d4-a716-446655440000",
"550e8400-e29b-41d4-a716-446655440001",
"550e8400-e29b-41d4-a716-446655440002"
]
}
},
"GraphDataResponse": {
"properties": {
"nodes": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Nodes"
},
"edges": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Edges"
},
"table_rows": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Table Rows"
},
"total_units": {
"type": "integer",
"title": "Total Units"
},
"limit": {
"type": "integer",
"title": "Limit"
}
},
"type": "object",
"required": [
"nodes",
"edges",
"table_rows",
"total_units",
"limit"
],
"title": "GraphDataResponse",
"description": "Response model for graph data endpoint.",
"example": {
"edges": [
{
"from": "1",
"to": "2",
"type": "semantic",
"weight": 0.8
}
],
"limit": 1000,
"nodes": [
{
"id": "1",
"label": "Alice works at Google",
"type": "world"
},
{
"id": "2",
"label": "Bob went hiking",
"type": "world"
}
],
"table_rows": [
{
"context": "Work info",
"date": "2024-01-15 10:30",
"entities": "Alice (PERSON), Google (ORGANIZATION)",
"id": "abc12345...",
"text": "Alice works at Google"
}
],
"total_units": 2
}
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"ImageContentBlock": {
"properties": {
"type": {
"type": "string",
"const": "image",
"title": "Type"
},
"source": {
"$ref": "#/components/schemas/Base64AttachmentSource"
}
},
"type": "object",
"required": [
"type",
"source"
],
"title": "ImageContentBlock",
"description": "An image within a multimodal item, in the position the caller wrote it."
},
"IncludeOptions": {
"properties": {
"entities": {
"anyOf": [
{
"$ref": "#/components/schemas/EntityIncludeOptions"
},
{
"type": "null"
}
],
"description": "Include entity observations. Set to null to disable entity inclusion.",
"default": {
"max_tokens": 500
}
},
"chunks": {
"anyOf": [
{
"$ref": "#/components/schemas/ChunkIncludeOptions"
},
{
"type": "null"
}
],
"description": "Include raw chunks. Set to {} to enable, null to disable (default: disabled)."
},
"source_facts": {
"anyOf": [
{
"$ref": "#/components/schemas/SourceFactsIncludeOptions"
},
{
"type": "null"
}
],
"description": "Include source facts for observation-type results. Set to {} to enable, null to disable (default: disabled)."
}
},
"type": "object",
"title": "IncludeOptions",
"description": "Options for including additional data in recall results."
},
"KnowledgeNode": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"kind": {
"type": "string",
"enum": [
"folder",
"page"
],
"title": "Kind"
},
"name": {
"type": "string",
"title": "Name"
},
"parent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Parent Id"
},
"mental_model_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mental Model Id",
"description": "Backing mental model id (pages only)."
},
"managed": {
"type": "boolean",
"title": "Managed",
"description": "Client-set flag: true = system-owned, false = hand-authored.",
"default": false
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"description": "Page source query (the page's `description`)."
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"default": []
},
"timestamp": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Timestamp",
"description": "Last refresh (page) or last update (folder)."
},
"is_stale": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is Stale",
"description": "Pages only, populated by the tree endpoint. True when a memory in *this page's* scope \u2014 its tags and fact types \u2014 has been written since the page last read the memories. That is the same check a scheduled refresh runs before spending an LLM call, so a flagged page is one a refresh would actually rewrite. Deletions are not observed: removing an in-scope memory leaves no write behind, so it does not raise this flag."
},
"trigger": {
"anyOf": [
{
"$ref": "#/components/schemas/MentalModelTrigger-Output"
},
{
"type": "null"
}
],
"description": "Pages only: the page's refresh settings \u2014 when it rebuilds itself (`refresh_after_consolidation` or `refresh_cron`), in which mode, and over which facts. This is the EFFECTIVE policy: a setting the page never stored is reported at its default, so compare the fields you care about rather than the whole object against a patch you sent. Absent on folders, which have no backing mental model, and on a page with no trigger stored."
},
"children": {
"items": {
"$ref": "#/components/schemas/KnowledgeNode"
},
"type": "array",
"title": "Children",
"default": []
}
},
"type": "object",
"required": [
"id",
"kind",
"name"
],
"title": "KnowledgeNode",
"description": "A node in the knowledge-base tree \u2014 a folder or a page.\n\nPages carry ``description``/``tags`` from their backing mental model. The\nknowledge base is client-managed (CRUD); ``managed`` lets a client tag a node\nas system-owned vs. hand-authored."
},
"KnowledgePageBundleFile": {
"properties": {
"path": {
"type": "string",
"title": "Path"
},
"content": {
"type": "string",
"title": "Content"
}
},
"type": "object",
"required": [
"path",
"content"
],
"title": "KnowledgePageBundleFile",
"description": "One file in a portable markdown bundle."
},
"KnowledgePageBundleResponse": {
"properties": {
"files": {
"items": {
"$ref": "#/components/schemas/KnowledgePageBundleFile"
},
"type": "array",
"title": "Files"
}
},
"type": "object",
"required": [
"files"
],
"title": "KnowledgePageBundleResponse",
"description": "A portable markdown bundle \u2014 a flat set of markdown files (index + pages + logs)."
},
"KnowledgePageResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"type": {
"type": "string",
"title": "Type",
"description": "Page type \u2014 from a `type:<x>` tag, else 'knowledge-page'."
},
"description": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Description",
"description": "The source query that rebuilds the page."
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"default": []
},
"timestamp": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Timestamp",
"description": "Last refresh time (falls back to creation)."
},
"body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Body",
"description": "The page's synthesized markdown body."
},
"markdown": {
"type": "string",
"title": "Markdown",
"description": "The full markdown document: YAML frontmatter + markdown body."
}
},
"type": "object",
"required": [
"id",
"name",
"type",
"markdown"
],
"title": "KnowledgePageResponse",
"description": "A knowledge page rendered as a markdown document."
},
"KnowledgePageSearchResponse": {
"properties": {
"results": {
"items": {
"$ref": "#/components/schemas/KnowledgePageSearchResult"
},
"type": "array",
"title": "Results"
},
"total": {
"type": "integer",
"title": "Total"
}
},
"type": "object",
"required": [
"results",
"total"
],
"title": "KnowledgePageSearchResponse",
"description": "Ranked knowledge-page search results (BM25 + vector, RRF-fused)."
},
"KnowledgePageSearchResult": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"name": {
"type": "string",
"title": "Name"
},
"mental_model_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mental Model Id"
},
"snippet": {
"type": "string",
"title": "Snippet"
},
"score": {
"type": "number",
"title": "Score"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"name",
"snippet",
"score"
],
"title": "KnowledgePageSearchResult",
"description": "One hybrid-search hit: a knowledge page and its fused relevance score."
},
"KnowledgeTreeResponse": {
"properties": {
"roots": {
"items": {
"$ref": "#/components/schemas/KnowledgeNode"
},
"type": "array",
"title": "Roots"
}
},
"type": "object",
"required": [
"roots"
],
"title": "KnowledgeTreeResponse",
"description": "The knowledge base as a nested folder/page tree."
},
"LLMCallTrace": {
"properties": {
"scope": {
"type": "string",
"title": "Scope",
"description": "Call scope: agent_1, agent_2, final, etc."
},
"duration_ms": {
"type": "integer",
"title": "Duration Ms",
"description": "Execution time in milliseconds"
}
},
"type": "object",
"required": [
"scope",
"duration_ms"
],
"title": "LLMCallTrace",
"description": "A single LLM call made during reflect."
},
"LLMRequestEntry": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"bank_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Bank Id"
},
"operation": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Operation"
},
"scope": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Scope"
},
"trace_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Trace Id"
},
"span_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Span Id"
},
"parent_span_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Parent Span Id"
},
"provider": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Provider"
},
"model": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Model"
},
"status": {
"type": "string",
"title": "Status"
},
"started_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Started At"
},
"ended_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Ended At"
},
"duration_ms": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Duration Ms"
},
"input_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Input Tokens"
},
"output_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Output Tokens"
},
"cached_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Cached Tokens"
},
"total_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Total Tokens"
},
"input": {
"title": "Input"
},
"output": {
"title": "Output"
},
"error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error"
},
"llm_info": {
"additionalProperties": true,
"type": "object",
"title": "Llm Info"
},
"metadata": {
"additionalProperties": true,
"type": "object",
"title": "Metadata"
}
},
"type": "object",
"required": [
"id",
"bank_id",
"operation",
"scope",
"trace_id",
"span_id",
"parent_span_id",
"provider",
"model",
"status",
"started_at",
"ended_at",
"duration_ms",
"input_tokens",
"output_tokens",
"cached_tokens",
"total_tokens",
"error",
"llm_info",
"metadata"
],
"title": "LLMRequestEntry",
"description": "A single LLM request trace row, as returned by the read API."
},
"LLMRequestListResponse": {
"properties": {
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"total": {
"type": "integer",
"title": "Total"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
},
"items": {
"items": {
"$ref": "#/components/schemas/LLMRequestEntry"
},
"type": "array",
"title": "Items"
}
},
"type": "object",
"required": [
"bank_id",
"total",
"limit",
"offset",
"items"
],
"title": "LLMRequestListResponse",
"description": "Paginated list of LLM request traces for a bank."
},
"LLMRequestStatsBucket": {
"properties": {
"time": {
"type": "string",
"title": "Time"
},
"statuses": {
"additionalProperties": {
"type": "integer"
},
"type": "object",
"title": "Statuses"
},
"total": {
"type": "integer",
"title": "Total"
},
"tokens": {
"$ref": "#/components/schemas/LLMRequestTokenSums"
}
},
"type": "object",
"required": [
"time",
"statuses",
"total",
"tokens"
],
"title": "LLMRequestStatsBucket",
"description": "A single time bucket in LLM request stats."
},
"LLMRequestStatsResponse": {
"properties": {
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"period": {
"type": "string",
"title": "Period"
},
"trunc": {
"type": "string",
"title": "Trunc"
},
"start": {
"type": "string",
"title": "Start"
},
"buckets": {
"items": {
"$ref": "#/components/schemas/LLMRequestStatsBucket"
},
"type": "array",
"title": "Buckets"
}
},
"type": "object",
"required": [
"bank_id",
"period",
"trunc",
"start",
"buckets"
],
"title": "LLMRequestStatsResponse",
"description": "LLM request counts and token sums grouped by time bucket."
},
"LLMRequestTokenSums": {
"properties": {
"input": {
"type": "integer",
"title": "Input"
},
"output": {
"type": "integer",
"title": "Output"
},
"cached": {
"type": "integer",
"title": "Cached"
},
"total": {
"type": "integer",
"title": "Total"
}
},
"type": "object",
"required": [
"input",
"output",
"cached",
"total"
],
"title": "LLMRequestTokenSums",
"description": "Token totals for a time bucket."
},
"LabelGroup-Input": {
"properties": {
"key": {
"type": "string",
"title": "Key"
},
"description": {
"type": "string",
"title": "Description",
"default": ""
},
"type": {
"type": "string",
"enum": [
"value",
"multi-values",
"text",
"multi-text",
"map"
],
"title": "Type",
"default": "value"
},
"optional": {
"type": "boolean",
"title": "Optional",
"default": true
},
"tag": {
"type": "boolean",
"title": "Tag",
"default": false
},
"values": {
"items": {
"$ref": "#/components/schemas/LabelValue"
},
"type": "array",
"title": "Values",
"default": []
},
"fields": {
"additionalProperties": {
"$ref": "#/components/schemas/MapField-Input"
},
"type": "object",
"title": "Fields",
"default": {}
}
},
"type": "object",
"required": [
"key"
],
"title": "LabelGroup",
"description": "A label group (dimension) with its type and allowed values."
},
"LabelGroup-Output": {
"properties": {
"key": {
"type": "string",
"title": "Key"
},
"description": {
"type": "string",
"title": "Description",
"default": ""
},
"type": {
"type": "string",
"enum": [
"value",
"multi-values",
"text",
"multi-text",
"map"
],
"title": "Type",
"default": "value"
},
"optional": {
"type": "boolean",
"title": "Optional",
"default": true
},
"tag": {
"type": "boolean",
"title": "Tag",
"default": false
},
"values": {
"items": {
"$ref": "#/components/schemas/LabelValue"
},
"type": "array",
"title": "Values",
"default": []
},
"fields": {
"additionalProperties": {
"$ref": "#/components/schemas/MapField-Output"
},
"type": "object",
"title": "Fields",
"default": {}
}
},
"type": "object",
"required": [
"key"
],
"title": "LabelGroup",
"description": "A label group (dimension) with its type and allowed values."
},
"LabelValue": {
"properties": {
"value": {
"type": "string",
"title": "Value"
},
"description": {
"type": "string",
"title": "Description",
"default": ""
}
},
"type": "object",
"required": [
"value"
],
"title": "LabelValue",
"description": "A single allowed value for a label group."
},
"ListChunksResponse": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/ChunkResponse"
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"title": "Total"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
}
},
"type": "object",
"required": [
"items",
"total",
"limit",
"offset"
],
"title": "ListChunksResponse",
"description": "Response model for listing chunks of a document."
},
"ListDocumentsResponse": {
"properties": {
"items": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"title": "Total"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
}
},
"type": "object",
"required": [
"items",
"total",
"limit",
"offset"
],
"title": "ListDocumentsResponse",
"description": "Response model for list documents endpoint.",
"example": {
"items": [
{
"bank_id": "user123",
"content_hash": "abc123",
"created_at": "2024-01-15T10:30:00Z",
"id": "session_1",
"memory_unit_count": 15,
"tags": [
"user_a",
"session_123"
],
"text_length": 5420,
"updated_at": "2024-01-15T10:30:00Z"
}
],
"limit": 100,
"offset": 0,
"total": 50
}
},
"ListMemoryUnitsResponse": {
"properties": {
"items": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"title": "Total"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
}
},
"type": "object",
"required": [
"items",
"total",
"limit",
"offset"
],
"title": "ListMemoryUnitsResponse",
"description": "Response model for list memory units endpoint.",
"example": {
"items": [
{
"context": "Work conversation",
"date": "2024-01-15T10:30:00Z",
"entities": "Alice (PERSON), Google (ORGANIZATION)",
"id": "550e8400-e29b-41d4-a716-446655440000",
"metadata": {
"channel": "engineering",
"source": "slack"
},
"text": "Alice works at Google on the AI team",
"type": "world"
}
],
"limit": 100,
"offset": 0,
"total": 150
}
},
"ListTagsResponse": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/TagItem"
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"title": "Total"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
}
},
"type": "object",
"required": [
"items",
"total",
"limit",
"offset"
],
"title": "ListTagsResponse",
"description": "Response model for list tags endpoint.",
"example": {
"items": [
{
"count": 42,
"tag": "user:alice"
},
{
"count": 15,
"tag": "user:bob"
},
{
"count": 8,
"tag": "session:abc123"
}
],
"limit": 100,
"offset": 0,
"total": 25
}
},
"LivenessResponse": {
"properties": {
"status": {
"type": "string",
"const": "alive",
"title": "Status",
"description": "Always \"alive\" \u2014 reaching this handler is the check"
},
"version": {
"type": "string",
"title": "Version",
"description": "Hindsight version this process is running"
},
"uptime_seconds": {
"type": "number",
"title": "Uptime Seconds",
"description": "Seconds since the process started"
}
},
"type": "object",
"required": [
"status",
"version",
"uptime_seconds"
],
"title": "LivenessResponse",
"description": "Payload for the API's DB-free liveness probe.",
"example": {
"status": "alive",
"uptime_seconds": 812.4,
"version": "0.4.0"
}
},
"LlmOperationHealth": {
"properties": {
"operation": {
"type": "string",
"enum": [
"retain",
"consolidation",
"reflect"
],
"title": "LlmHealthOperation",
"description": "Operation whose LLM was probed"
},
"ok": {
"type": "boolean",
"title": "Ok",
"description": "True only when the probe connected successfully"
},
"status": {
"type": "string",
"enum": [
"connected",
"not_configured",
"auth_failed",
"unreachable",
"timeout"
],
"title": "LlmHealthStatus",
"description": "'connected'; 'not_configured' (provider is 'none'); 'auth_failed' (rejected \u2014 usually a wrong/expired API key); 'unreachable' (call failed); 'timeout'"
},
"latency_ms": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Latency Ms",
"description": "Round-trip latency of the probe call"
}
},
"type": "object",
"required": [
"operation",
"ok",
"status"
],
"title": "LlmOperationHealth",
"description": "LLM connectivity status for a single operation. Status only \u2014 no provider/model/\nendpoint/error, so the probe never discloses the LLM configuration."
},
"MapField-Input": {
"properties": {
"type": {
"type": "string",
"enum": [
"text",
"multi-text",
"value",
"multi-values",
"map"
],
"title": "Type",
"default": "text"
},
"description": {
"type": "string",
"title": "Description",
"default": ""
},
"values": {
"items": {
"$ref": "#/components/schemas/LabelValue"
},
"type": "array",
"title": "Values",
"default": []
},
"fields": {
"additionalProperties": {
"$ref": "#/components/schemas/MapField-Input"
},
"type": "object",
"title": "Fields",
"default": {}
}
},
"type": "object",
"title": "MapField",
"description": "A field within a map-type entity label group. Supports recursion via type='map'."
},
"MapField-Output": {
"properties": {
"type": {
"type": "string",
"enum": [
"text",
"multi-text",
"value",
"multi-values",
"map"
],
"title": "Type",
"default": "text"
},
"description": {
"type": "string",
"title": "Description",
"default": ""
},
"values": {
"items": {
"$ref": "#/components/schemas/LabelValue"
},
"type": "array",
"title": "Values",
"default": []
},
"fields": {
"additionalProperties": {
"$ref": "#/components/schemas/MapField-Output"
},
"type": "object",
"title": "Fields",
"default": {}
}
},
"type": "object",
"title": "MapField",
"description": "A field within a map-type entity label group. Supports recursion via type='map'."
},
"MemoriesTimeseriesResponse": {
"properties": {
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"period": {
"type": "string",
"title": "Period",
"description": "One of: 1h, 12h, 1d, 7d, 30d, 90d."
},
"trunc": {
"type": "string",
"title": "Trunc",
"description": "Bucket granularity: minute, hour, day."
},
"time_field": {
"type": "string",
"title": "Time Field",
"description": "Timestamp column used to assign each row to a bucket. `created_at` shows ingest time; `mentioned_at` / `occurred_start` show event time (falls back to `created_at` per row when null).",
"default": "created_at"
},
"buckets": {
"items": {
"$ref": "#/components/schemas/MemoryTimeseriesBucket"
},
"type": "array",
"title": "Buckets",
"description": "Per-bucket counts, always returned fully padded for the requested period."
}
},
"type": "object",
"required": [
"bank_id",
"period",
"trunc"
],
"title": "MemoriesTimeseriesResponse",
"description": "Time-series of memory ingestion bucketed by time and fact type."
},
"MemoryItem": {
"properties": {
"content": {
"anyOf": [
{
"type": "string"
},
{
"items": {
"oneOf": [
{
"$ref": "#/components/schemas/TextContentBlock"
},
{
"$ref": "#/components/schemas/ImageContentBlock"
},
{
"$ref": "#/components/schemas/FileContentBlock"
}
],
"discriminator": {
"propertyName": "type",
"mapping": {
"file": "#/components/schemas/FileContentBlock",
"image": "#/components/schemas/ImageContentBlock",
"text": "#/components/schemas/TextContentBlock"
}
}
},
"type": "array"
}
],
"title": "Content",
"description": "The raw content to retain. Either a plain string, or an ordered list of content blocks so images sit inline where they actually appear:\n\n [{\"type\": \"text\", \"text\": \"click the button shown:\"},\n {\"type\": \"image\", \"source\": {\"type\": \"base64\", \"media_type\": \"image/png\", \"data\": \"...\"}},\n {\"type\": \"text\", \"text\": \"...then reconnect.\"}]\n\nThe block form requires a vision-capable retain LLM; a retain carrying images against a text-only model is rejected rather than silently dropping them. A single text block is equivalent to the plain string form."
},
"timestamp": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Timestamp",
"description": "When the content occurred. Accepts an ISO 8601 datetime string (e.g. '2024-01-15T10:30:00Z'), null/omitted (defaults to now), or the special string 'unset' to explicitly store without any timestamp (use this for timeless content such as fictional documents or static reference material)."
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Context"
},
"metadata": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Metadata"
},
"document_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Document Id",
"description": "Optional document ID for this memory item. Provide a distinct document_id per source document \u2014 items sharing a document_id are grouped into the same document. Auto-generated when omitted."
},
"entities": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/EntityInput"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Entities",
"description": "Optional entities to combine with auto-extracted entities."
},
"resolve_entities": {
"type": "boolean",
"title": "Resolve Entities",
"description": "Whether the names in 'entities' are resolved against the entities already in the bank. True (default) matches each name to a similar existing entity when it scores above the match threshold, so a name close to one already in the bank may resolve to that one instead of the one you wrote. False takes your names literally \u2014 an existing entity is reused only on a case-insensitive name match, any other name creates a new entity, and your names are never merged with each other. This applies only to the entities you supply here; auto-extracted entities are always resolved, since they are the extractor's guess at a name rather than yours. Ignored when 'entities' is omitted.",
"default": true
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags",
"description": "Optional tags for visibility scoping. Memories with tags can be filtered during recall."
},
"observation_scopes": {
"anyOf": [
{
"type": "string",
"enum": [
"per_tag",
"combined",
"all_combinations",
"shared"
]
},
{
"items": {
"items": {
"type": "string"
},
"type": "array"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "ObservationScopes",
"description": "How to scope observations during consolidation. 'per_tag' runs one consolidation pass per individual tag, creating separate observations for each tag. 'combined' (default) runs a single pass with all tags together. 'shared' runs a single pass over one global, untagged scope, so memories consolidate together regardless of their tags \u2014 useful for deduplicating across volatile per-call provenance tags (e.g. per-session ids) while keeping those tags on the source facts. A list of tag lists runs one pass per inner list, giving full control over which combinations to use."
},
"strategy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Strategy",
"description": "Named retain strategy for this item. Overrides the bank's default strategy for this item only. Strategies are defined in the bank config under 'retain_strategies'."
},
"update_mode": {
"anyOf": [
{
"type": "string",
"enum": [
"replace",
"append"
]
},
{
"type": "null"
}
],
"title": "Update Mode",
"description": "How to handle an existing document with the same document_id. 'replace' (default) deletes old data and reprocesses from scratch. 'append' concatenates new content to the existing document text and reprocesses."
}
},
"type": "object",
"required": [
"content"
],
"title": "MemoryItem",
"description": "Single memory item for retain.",
"example": {
"content": "Alice mentioned she's working on a new ML model",
"context": "team meeting",
"document_id": "meeting_notes_2024_01_15",
"entities": [
{
"text": "Alice"
},
{
"text": "ML model",
"type": "CONCEPT"
}
],
"metadata": {
"channel": "engineering",
"source": "slack"
},
"tags": [
"user_a",
"user_b"
],
"timestamp": "2024-01-15T10:30:00Z"
}
},
"MemoryTimeseriesBucket": {
"properties": {
"time": {
"type": "string",
"title": "Time",
"description": "Bucket start timestamp in ISO-8601 (UTC)."
},
"world": {
"type": "integer",
"title": "World",
"description": "World-fact memories ingested in this bucket.",
"default": 0
},
"experience": {
"type": "integer",
"title": "Experience",
"description": "Experience memories ingested in this bucket.",
"default": 0
},
"observation": {
"type": "integer",
"title": "Observation",
"description": "Observations recorded in this bucket.",
"default": 0
}
},
"type": "object",
"required": [
"time"
],
"title": "MemoryTimeseriesBucket",
"description": "One bucket in the memory ingestion time-series."
},
"MentalModelDeltaOperations": {
"properties": {
"applied": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Applied",
"description": "Operations applied to the document, in order."
},
"skipped": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Skipped",
"description": "Operations dropped as invalid, each with a reason."
}
},
"type": "object",
"title": "MentalModelDeltaOperations",
"description": "Structured operations a delta refresh emitted against the existing document."
},
"MentalModelDryRunRefreshResult": {
"properties": {
"mental_model_id": {
"type": "string",
"title": "Mental Model Id",
"description": "The mental model previewed."
},
"name": {
"type": "string",
"title": "Name",
"description": "Display name of the mental model."
},
"requested_mode": {
"type": "string",
"enum": [
"full",
"delta"
],
"title": "Requested Mode",
"description": "The mode asked for (from the model's trigger, or overridden)."
},
"effective_mode": {
"type": "string",
"enum": [
"full",
"delta"
],
"title": "Effective Mode",
"description": "The mode the refresh actually ran in."
},
"mode_fallback_reason": {
"anyOf": [
{
"type": "string",
"enum": [
"no_baseline_content",
"source_query_changed",
"structured_doc_unreadable",
"delta_ops_failed",
"delta_ops_all_skipped"
]
},
{
"type": "null"
}
],
"title": "Mode Fallback Reason",
"description": "Why delta was requested but not applied, if that happened."
},
"outcome": {
"type": "string",
"enum": [
"content_written",
"content_unchanged",
"content_preserved_no_new_facts",
"refresh_failed_empty_candidate",
"refresh_failed_delta_not_applied"
],
"title": "Outcome",
"description": "What a real refresh would do with the document."
},
"would_persist": {
"type": "boolean",
"title": "Would Persist",
"description": "Whether a real refresh would write new content."
},
"scope": {
"$ref": "#/components/schemas/MentalModelRefreshScope",
"description": "The resolved memory scope."
},
"window": {
"$ref": "#/components/schemas/MentalModelRefreshWindow",
"description": "The snapshot window read from."
},
"facts": {
"$ref": "#/components/schemas/MentalModelFactCounts",
"description": "Facts retrieved versus actually used."
},
"based_on": {
"additionalProperties": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"type": "object",
"title": "Based On",
"description": "The evidence this run would ground the document on, keyed by fact type \u2014 the same shape a refresh persists under reflect_response.based_on. Returned so a preview can show its sources without having to write them anywhere."
},
"current_content": {
"type": "string",
"title": "Current Content",
"description": "The model's content as it stands now."
},
"candidate_content": {
"type": "string",
"title": "Candidate Content",
"description": "Raw reflect synthesis, before any delta operations."
},
"preview_content": {
"type": "string",
"title": "Preview Content",
"description": "The content a real refresh would store: the delta-edited document, or the candidate in full mode."
},
"diff": {
"type": "string",
"title": "Diff",
"description": "Unified diff from current_content to preview_content. Empty when identical."
},
"delta_operations": {
"anyOf": [
{
"$ref": "#/components/schemas/MentalModelDeltaOperations"
},
{
"type": "null"
}
],
"description": "Structured operations emitted, in delta mode."
},
"retraction": {
"anyOf": [
{
"$ref": "#/components/schemas/MentalModelRetraction"
},
{
"type": "null"
}
],
"description": "Facts the document cites that no longer exist, and what a real refresh would do about them."
},
"trace": {
"$ref": "#/components/schemas/MentalModelRefreshTrace",
"description": "Execution trace of the run, always included for a dry run."
},
"usage": {
"$ref": "#/components/schemas/TokenUsage",
"description": "Token usage across the run's LLM calls."
},
"duration_ms": {
"type": "integer",
"title": "Duration Ms",
"description": "Wall-clock duration of the run.",
"default": 0
},
"warnings": {
"items": {
"type": "string"
},
"type": "array",
"title": "Warnings",
"description": "Conditions worth a human's attention, in plain language."
}
},
"type": "object",
"required": [
"mental_model_id",
"name",
"requested_mode",
"effective_mode",
"outcome",
"would_persist",
"scope",
"window",
"facts",
"current_content",
"candidate_content",
"preview_content",
"diff",
"trace"
],
"title": "MentalModelDryRunRefreshResult",
"description": "Preview of what a mental model refresh would do, having changed nothing.\n\nRuns the real pipeline \u2014 same scope resolution, same reflect call, same\ndelta operations \u2014 then reports the result instead of persisting it. The\nmodel's content, structured content, watermark, and last_refreshed_at are\nall left untouched, so a delta dry run is repeatable: it reads the same\nwindow the next real refresh would.",
"example": {
"effective_mode": "full",
"facts": {
"retrieved": {
"observation": 12
},
"used": {
"observation": 4
}
},
"mental_model_id": "coding-style",
"mode_fallback_reason": "source_query_changed",
"name": "Coding Style",
"outcome": "content_written",
"requested_mode": "delta",
"warnings": [],
"would_persist": true
}
},
"MentalModelFactCounts": {
"properties": {
"retrieved": {
"additionalProperties": {
"type": "integer"
},
"type": "object",
"title": "Retrieved",
"description": "Facts the reflect agent's tool calls returned, by fact type."
},
"used": {
"additionalProperties": {
"type": "integer"
},
"type": "object",
"title": "Used",
"description": "Facts the agent declared it actually based the answer on, by fact type."
}
},
"type": "object",
"title": "MentalModelFactCounts",
"description": "Facts the refresh saw, keyed by fact type.\n\n``retrieved`` and ``used`` diverging is the single most common cause of a\ndisappointing refresh: recall found plenty, but the reflect agent declared\nnone of it relevant to the topic, so none of it reached the document."
},
"MentalModelListResponse": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/MentalModelResponse"
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"title": "Total",
"description": "Total number of mental models matching the filter (not just this page)"
},
"limit": {
"type": "integer",
"title": "Limit",
"description": "Page size that was applied"
},
"offset": {
"type": "integer",
"title": "Offset",
"description": "Offset that was applied"
}
},
"type": "object",
"required": [
"items",
"total",
"limit",
"offset"
],
"title": "MentalModelListResponse",
"description": "Response model for listing mental models."
},
"MentalModelRefreshScope": {
"properties": {
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags",
"description": "Flat tags used to filter memories (null when unused)."
},
"tags_match": {
"type": "string",
"enum": [
"any",
"all",
"any_strict",
"all_strict",
"exact"
],
"title": "Tags Match",
"description": "Resolved tag match mode."
},
"tag_groups": {
"anyOf": [
{
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TagGroupLeaf"
},
{
"$ref": "#/components/schemas/TagGroupAnd-Output"
},
{
"$ref": "#/components/schemas/TagGroupOr-Output"
},
{
"$ref": "#/components/schemas/TagGroupNot-Output"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tag Groups",
"description": "Compound tag expressions used instead of flat tags, when set."
},
"fact_types": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Fact Types",
"description": "Fact types retrieved (null means all)."
},
"exclude_mental_models": {
"type": "boolean",
"title": "Exclude Mental Models",
"description": "Whether other mental models were excluded from the reflect loop."
},
"exclude_mental_model_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Exclude Mental Model Ids",
"description": "Mental models excluded by ID (always includes the model being refreshed)."
}
},
"type": "object",
"required": [
"tags_match",
"exclude_mental_models"
],
"title": "MentalModelRefreshScope",
"description": "The memory scope a refresh actually resolved to.\n\nA model's stored ``tags`` are not what filters memories \u2014 ``tags_match``\ndefaults to ``all_strict`` when tags are present, and ``tag_groups``\noverride flat tags entirely. This reports the resolved result."
},
"MentalModelRefreshTrace": {
"properties": {
"recorded_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Recorded At",
"description": "When this trace was recorded."
},
"effective_mode": {
"type": "string",
"enum": [
"full",
"delta"
],
"title": "Effective Mode",
"description": "Whether the refresh ran as full or delta."
},
"mode_fallback_reason": {
"anyOf": [
{
"type": "string",
"enum": [
"no_baseline_content",
"source_query_changed",
"structured_doc_unreadable",
"delta_ops_failed",
"delta_ops_all_skipped"
]
},
{
"type": "null"
}
],
"title": "Mode Fallback Reason",
"description": "Why delta was requested but not applied, if that happened."
},
"outcome": {
"type": "string",
"enum": [
"content_written",
"content_unchanged",
"content_preserved_no_new_facts",
"refresh_failed_empty_candidate",
"refresh_failed_delta_not_applied"
],
"title": "Outcome",
"description": "What the refresh did with the document."
},
"tool_calls": {
"items": {
"$ref": "#/components/schemas/MentalModelTraceToolCall"
},
"type": "array",
"title": "Tool Calls",
"description": "Reflect tool calls made during the refresh."
},
"llm_calls": {
"items": {
"$ref": "#/components/schemas/LLMCallTrace"
},
"type": "array",
"title": "Llm Calls",
"description": "LLM calls made during the refresh."
},
"delta_operations": {
"anyOf": [
{
"$ref": "#/components/schemas/MentalModelDeltaOperations"
},
{
"type": "null"
}
],
"description": "Structured operations emitted, in delta mode."
},
"retraction": {
"anyOf": [
{
"$ref": "#/components/schemas/MentalModelRetraction"
},
{
"type": "null"
}
],
"description": "Facts the document cited that no longer exist, when the refresh found any."
},
"usage": {
"anyOf": [
{
"$ref": "#/components/schemas/TokenUsage"
},
{
"type": "null"
}
],
"description": "Token usage across the refresh's LLM calls."
},
"duration_ms": {
"type": "integer",
"title": "Duration Ms",
"description": "Wall-clock duration of the refresh.",
"default": 0
},
"warnings": {
"items": {
"type": "string"
},
"type": "array",
"title": "Warnings",
"description": "Conditions worth a human's attention, in plain language."
}
},
"type": "object",
"required": [
"effective_mode",
"outcome"
],
"title": "MentalModelRefreshTrace",
"description": "Execution trace of a mental model refresh, recorded when trigger.keep_trace is on.\n\nDeliberately shaped like reflect's trace \u2014 the calls the agent made, plus the\nrefresh-specific decision \u2014 and nothing more. This is persisted on the mental\nmodel row and re-read on every fetch, so anything derivable from elsewhere is\nleft out: the evidence lives in ``reflect_response.based_on``, and the\nresolved scope and snapshot window are reported by the dry run."
},
"MentalModelRefreshWindow": {
"properties": {
"created_after": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Created After",
"description": "Lower bound on when a memory last changed. Set only in delta mode, where it is the model's last_memory_seen_at \u2014 so a delta refresh only sees memories written or edited since the newest one the previous refresh saw."
},
"created_before": {
"type": "string",
"format": "date-time",
"title": "Created Before",
"description": "Database-time snapshot bounding the refresh. Memories written or edited after this are not read, so they stay newer than the persisted watermark and are caught by the next refresh."
},
"watermark": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Watermark",
"description": "The last_memory_seen_at a real refresh would persist: the newest in-scope memory visible at the snapshot, not now(). Null means no in-scope memory was visible."
}
},
"type": "object",
"required": [
"created_before"
],
"title": "MentalModelRefreshWindow",
"description": "The time window a refresh read memories from."
},
"MentalModelResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"name": {
"type": "string",
"title": "Name"
},
"source_query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Query"
},
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content",
"description": "The mental model content as well-formatted markdown (auto-generated from reflect endpoint)"
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"default": []
},
"max_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max Tokens"
},
"trigger": {
"anyOf": [
{
"$ref": "#/components/schemas/MentalModelTrigger-Output"
},
{
"type": "null"
}
]
},
"last_refreshed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Refreshed At",
"description": "When a refresh last finished for this model \u2014 wall-clock, in ISO format. Advances on every refresh that completes, including one that found nothing new and preserved the content, and on a direct edit of `content`. A refresh that failed leaves it alone. This is the field to answer 'have I already refreshed this?'; it says nothing about whether the model is behind the data, which is `last_memory_seen_at` / `is_stale`."
},
"last_memory_seen_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Memory Seen At",
"description": "How far through the bank's memories this model is written \u2014 the newest in-scope memory the last refresh saw, in ISO format. Stands still when nothing in the model's scope has been written, however often it is refreshed. At or after the bank's `last_memory_write_at` (GET /stats) the model is provably up to date; when it is older, `is_stale` settles it against the model's own scope. Null for a model no refresh has stamped yet."
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"reflect_response": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Reflect Response",
"description": "Full reflect API response payload including based_on facts and observations"
},
"is_stale": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is Stale",
"description": "True when memories matching this mental model's tag/fact_type scope have been written since last_memory_seen_at \u2014 the same check that decides whether a scheduled refresh does any work, so a model flagged here is one a refresh would actually rewrite. Populated on both the single read and the list. Deletions are not observed: removing an in-scope memory leaves no write behind, so it does not raise this flag."
}
},
"type": "object",
"required": [
"id",
"bank_id",
"name"
],
"title": "MentalModelResponse",
"description": "Response model for a mental model (stored reflect response)."
},
"MentalModelRetraction": {
"properties": {
"fact_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Fact Ids",
"description": "Ids the document's based_on cites that no longer exist in the bank."
},
"fact_texts": {
"items": {
"type": "string"
},
"type": "array",
"title": "Fact Texts",
"description": "What those facts said, as the document recorded them. The rows themselves are gone \u2014 an observation swept away with its source keeps no history \u2014 so this copy is the only surviving record."
},
"applied": {
"type": "boolean",
"title": "Applied",
"description": "Whether the pass that removes them ran to completion (zero edits still counts)."
},
"deferred_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Deferred Reason",
"description": "Why removal was postponed, when it was. Re-ingested facts return under new ids once consolidation catches up, so a retraction seen while facts are still pending is not acted on \u2014 removing content before the replacements land would delete claims that are still true."
}
},
"type": "object",
"required": [
"applied"
],
"title": "MentalModelRetraction",
"description": "Facts the document cited that no longer exist, and what was done about them.\n\nA retraction is the one refresh input that is *invisible* in every other\nreport: the fact is gone from the bank, so it appears in no recall, no tool\ncall, and no supporting-fact list. Without this, a refresh that quietly\ndeleted a paragraph \u2014 or quietly declined to \u2014 leaves no evidence of why."
},
"MentalModelTraceToolCall": {
"properties": {
"tool": {
"type": "string",
"title": "Tool",
"description": "Tool name: recall, search_observations, get_mental_model, expand, \u2026"
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reason",
"description": "The agent's stated reason for the call."
},
"input": {
"additionalProperties": true,
"type": "object",
"title": "Input",
"description": "Tool input parameters."
},
"output": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Output",
"description": "What the tool returned. Present on a dry run, which stores nothing; omitted from the trace persisted by a real refresh to keep that row bounded."
},
"updated_at": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Updated At",
"description": "The refresh window's lower bound as given to this call \u2014 the delta watermark. Named for what it actually filters: the predicate is on the memory's updated_at, so a memory merely touched since the last refresh qualifies. Null means the tool applies no time bound at all, so its results are not limited to the window (mental-model lookup and chunk expansion behave this way)."
},
"result_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Result Count",
"description": "Number of items the tool returned, when countable."
},
"duration_ms": {
"type": "integer",
"title": "Duration Ms",
"description": "Execution time in milliseconds."
},
"iteration": {
"type": "integer",
"title": "Iteration",
"description": "Agent loop iteration (1-based) this call belongs to.",
"default": 0
}
},
"type": "object",
"required": [
"tool",
"duration_ms"
],
"title": "MentalModelTraceToolCall",
"description": "One reflect tool call made during a refresh.\n\n``output`` is carried only by the dry run, which persists nothing. The trace\nstored on the model row keeps ``result_count`` instead: it is re-read on every\nfetch, so embedding full recall payloads there would bloat the row without\nbound. Raw prompts and responses are available separately via LLM request\ntracing."
},
"MentalModelTrigger-Input": {
"properties": {
"mode": {
"type": "string",
"enum": [
"full",
"delta"
],
"title": "Mode",
"description": "Refresh mode. 'full' (default) regenerates the mental model content from scratch on each refresh. 'delta' performs surgical edits against the existing content: unchanged sections are preserved byte-for-byte, stale content is removed, new content is added. If the mental model has no existing content, or if the source_query has changed since the last refresh, delta mode falls back to a full regeneration automatically.",
"default": "full"
},
"refresh_after_consolidation": {
"type": "boolean",
"title": "Refresh After Consolidation",
"description": "If true, refresh this mental model after observations consolidation (real-time mode)",
"default": false
},
"refresh_cron": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Refresh Cron",
"description": "Cron expression (UTC, standard 5-field syntax, e.g. '0 3 * * *' for daily at 03:00 UTC) for refreshing this mental model on a fixed schedule. Mutually exclusive with refresh_after_consolidation \u2014 a model refreshes either after consolidation or on a cron schedule, not both. A scheduled refresh only runs when the model is stale (new memories in its scope since the last refresh); if nothing changed, the tick is skipped to avoid a wasted LLM call. null = no schedule."
},
"min_refresh_interval_seconds": {
"anyOf": [
{
"type": "integer",
"minimum": 0.0
},
{
"type": "null"
}
],
"title": "Min Refresh Interval Seconds",
"description": "Minimum seconds between two automatic refreshes of this mental model. A triggered refresh that arrives sooner is not dropped: it is queued and parked until the window expires, and every further trigger in the meantime folds into that one queued refresh, so a burst of retains costs one refresh instead of one per retain. Applies to both refresh_after_consolidation and refresh_cron. Explicit refreshes (API, MCP, control plane) ignore it and run immediately. 0 disables the floor for this model; null falls back to the bank/global mental_model_min_refresh_interval_seconds setting (itself 0 by default, i.e. no floor)."
},
"fact_types": {
"anyOf": [
{
"items": {
"type": "string",
"enum": [
"world",
"experience",
"observation"
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Fact Types",
"description": "Filter which fact types are retrieved during reflect. None means all types (world, experience, observation)."
},
"exclude_mental_models": {
"type": "boolean",
"title": "Exclude Mental Models",
"description": "If true, exclude all mental models from the reflect loop (skip search_mental_models tool).",
"default": false
},
"exclude_mental_model_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Exclude Mental Model Ids",
"description": "Exclude specific mental models by ID from the reflect loop."
},
"tags_match": {
"anyOf": [
{
"type": "string",
"enum": [
"any",
"all",
"any_strict",
"all_strict",
"exact"
]
},
{
"type": "null"
}
],
"title": "Tags Match",
"description": "Override how the model's tags filter memories during refresh. If not set, defaults to 'all_strict' when the model has tags (security isolation) or 'any' when the model has no tags. Under 'all_strict' a memory must carry EVERY one of the model's tags and untagged memories are excluded, which is why a model tagged with labels its memories do not carry refreshes to empty content. Set to 'all' to keep requiring the tags while including untagged memories, or to 'any' to include untagged memories alongside any single tag match."
},
"tag_groups": {
"anyOf": [
{
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TagGroupLeaf"
},
{
"$ref": "#/components/schemas/TagGroupAnd-Input"
},
{
"$ref": "#/components/schemas/TagGroupOr-Input"
},
{
"$ref": "#/components/schemas/TagGroupNot-Input"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tag Groups",
"description": "Compound boolean tag expressions to use during refresh instead of the model's own tags. When set, these tag groups are passed to reflect and the model's flat tags are NOT used for filtering. Supports nested and/or/not expressions for complex tag-based scoping."
},
"include_chunks": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Include Chunks",
"description": "Override whether the internal recall used during refresh returns raw chunk text. None means use the bank/global config default (recall_include_chunks)."
},
"recall_max_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Recall Max Tokens",
"description": "Override the token budget for facts returned by the internal recall during refresh. None means use the bank/global config default (recall_max_tokens)."
},
"recall_chunks_max_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Recall Chunks Max Tokens",
"description": "Override the token budget for raw chunks returned by the internal recall during refresh. None means use the bank/global config default (recall_chunks_max_tokens)."
},
"response_schema": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Response Schema",
"description": "Optional JSON Schema for structured output. When set, each refresh runs the same structured-output extraction as reflect's response_schema and stores the parsed result under reflect_response.structured_output alongside the markdown content."
},
"keep_trace": {
"type": "boolean",
"title": "Keep Trace",
"description": "If true, every refresh of this mental model records how it reached its result under reflect_response.trace: the mode it ran in and why, the resolved scope and time window, how many facts retrieval returned versus how many the agent used, the tool and LLM calls, and any delta operations. Only the latest refresh's trace is kept. This is the only way to diagnose a cron- or consolidation-driven refresh after the fact, since no human sees those run. Tool outputs are reduced to result counts to keep the stored trace bounded; use LLM request tracing for raw prompts and responses.",
"default": false
}
},
"type": "object",
"title": "MentalModelTrigger",
"description": "Trigger settings for a mental model."
},
"MentalModelTrigger-Output": {
"properties": {
"mode": {
"type": "string",
"enum": [
"full",
"delta"
],
"title": "Mode",
"description": "Refresh mode. 'full' (default) regenerates the mental model content from scratch on each refresh. 'delta' performs surgical edits against the existing content: unchanged sections are preserved byte-for-byte, stale content is removed, new content is added. If the mental model has no existing content, or if the source_query has changed since the last refresh, delta mode falls back to a full regeneration automatically.",
"default": "full"
},
"refresh_after_consolidation": {
"type": "boolean",
"title": "Refresh After Consolidation",
"description": "If true, refresh this mental model after observations consolidation (real-time mode)",
"default": false
},
"refresh_cron": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Refresh Cron",
"description": "Cron expression (UTC, standard 5-field syntax, e.g. '0 3 * * *' for daily at 03:00 UTC) for refreshing this mental model on a fixed schedule. Mutually exclusive with refresh_after_consolidation \u2014 a model refreshes either after consolidation or on a cron schedule, not both. A scheduled refresh only runs when the model is stale (new memories in its scope since the last refresh); if nothing changed, the tick is skipped to avoid a wasted LLM call. null = no schedule."
},
"min_refresh_interval_seconds": {
"anyOf": [
{
"type": "integer",
"minimum": 0.0
},
{
"type": "null"
}
],
"title": "Min Refresh Interval Seconds",
"description": "Minimum seconds between two automatic refreshes of this mental model. A triggered refresh that arrives sooner is not dropped: it is queued and parked until the window expires, and every further trigger in the meantime folds into that one queued refresh, so a burst of retains costs one refresh instead of one per retain. Applies to both refresh_after_consolidation and refresh_cron. Explicit refreshes (API, MCP, control plane) ignore it and run immediately. 0 disables the floor for this model; null falls back to the bank/global mental_model_min_refresh_interval_seconds setting (itself 0 by default, i.e. no floor)."
},
"fact_types": {
"anyOf": [
{
"items": {
"type": "string",
"enum": [
"world",
"experience",
"observation"
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Fact Types",
"description": "Filter which fact types are retrieved during reflect. None means all types (world, experience, observation)."
},
"exclude_mental_models": {
"type": "boolean",
"title": "Exclude Mental Models",
"description": "If true, exclude all mental models from the reflect loop (skip search_mental_models tool).",
"default": false
},
"exclude_mental_model_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Exclude Mental Model Ids",
"description": "Exclude specific mental models by ID from the reflect loop."
},
"tags_match": {
"anyOf": [
{
"type": "string",
"enum": [
"any",
"all",
"any_strict",
"all_strict",
"exact"
]
},
{
"type": "null"
}
],
"title": "Tags Match",
"description": "Override how the model's tags filter memories during refresh. If not set, defaults to 'all_strict' when the model has tags (security isolation) or 'any' when the model has no tags. Under 'all_strict' a memory must carry EVERY one of the model's tags and untagged memories are excluded, which is why a model tagged with labels its memories do not carry refreshes to empty content. Set to 'all' to keep requiring the tags while including untagged memories, or to 'any' to include untagged memories alongside any single tag match."
},
"tag_groups": {
"anyOf": [
{
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TagGroupLeaf"
},
{
"$ref": "#/components/schemas/TagGroupAnd-Output"
},
{
"$ref": "#/components/schemas/TagGroupOr-Output"
},
{
"$ref": "#/components/schemas/TagGroupNot-Output"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tag Groups",
"description": "Compound boolean tag expressions to use during refresh instead of the model's own tags. When set, these tag groups are passed to reflect and the model's flat tags are NOT used for filtering. Supports nested and/or/not expressions for complex tag-based scoping."
},
"include_chunks": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Include Chunks",
"description": "Override whether the internal recall used during refresh returns raw chunk text. None means use the bank/global config default (recall_include_chunks)."
},
"recall_max_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Recall Max Tokens",
"description": "Override the token budget for facts returned by the internal recall during refresh. None means use the bank/global config default (recall_max_tokens)."
},
"recall_chunks_max_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Recall Chunks Max Tokens",
"description": "Override the token budget for raw chunks returned by the internal recall during refresh. None means use the bank/global config default (recall_chunks_max_tokens)."
},
"response_schema": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Response Schema",
"description": "Optional JSON Schema for structured output. When set, each refresh runs the same structured-output extraction as reflect's response_schema and stores the parsed result under reflect_response.structured_output alongside the markdown content."
},
"keep_trace": {
"type": "boolean",
"title": "Keep Trace",
"description": "If true, every refresh of this mental model records how it reached its result under reflect_response.trace: the mode it ran in and why, the resolved scope and time window, how many facts retrieval returned versus how many the agent used, the tool and LLM calls, and any delta operations. Only the latest refresh's trace is kept. This is the only way to diagnose a cron- or consolidation-driven refresh after the fact, since no human sees those run. Tool outputs are reduced to result counts to keep the stored trace bounded; use LLM request tracing for raw prompts and responses.",
"default": false
}
},
"type": "object",
"title": "MentalModelTrigger",
"description": "Trigger settings for a mental model."
},
"MinScores": {
"properties": {
"semantic": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Semantic",
"description": "Retrieval-level, semantic arm only: minimum vector similarity (0-1). A result the semantic arm did not surface reports `semantic: null` and is unaffected by this floor."
},
"keyword": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Keyword",
"description": "Retrieval-level, keyword arm only: minimum keyword/full-text (BM25) score. A result the keyword arm did not surface reports `keyword: null` and is unaffected by this floor."
},
"reranker": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Reranker",
"description": "Post-query: minimum normalized reranker score (0-1). Applied to every returned result."
},
"final": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Final",
"description": "Post-query: minimum final ranking score. Applied to every returned result."
}
},
"type": "object",
"title": "MinScores",
"description": "Optional per-stage score floors for recall. Every floor is inclusive (``>=``).\n\nThe four floors act at two different levels, and the distinction decides what a\nreturned result is guaranteed to satisfy.\n\n``semantic`` and ``keyword`` are **retrieval-level** cutoffs pushed into their own\nSQL arm (overriding the global ``semantic_min_similarity`` / ``bm25_min_score``\nconfig for this request), so they prune weak matches before fusion. Each one\nconstrains **only the arm it names**. Recall fuses four arms \u2014 semantic, keyword,\ngraph and temporal \u2014 and a result reaches the response if *any* arm surfaced it,\nso a returned result may legitimately carry ``null`` for a stage it was not\nsurfaced by, and results reached through the graph or temporal arm carry neither\n``semantic`` nor ``keyword``. A *non-null* score always clears its floor \u2014 the\ngap is only ever a ``null``. Setting both does **not** restrict the response to\nresults that clear both: they are not a predicate over each fused result. This is\ndeliberate \u2014 an intersection would discard the strong single-arm matches that\nhybrid retrieval exists to find (a paraphrase with no lexical overlap, an exact\nidentifier the embedding scores poorly).\n\n``reranker`` and ``final`` are **post-query** filters applied to every scored\nresult after fusion and reranking, so these *are* per-result predicates: a\nreturned result always clears them. Use them, not the retrieval floors, to make\nrecall abstain on low-confidence queries.\n\nAny field left None imposes no floor; all-None (the default) means no score\nfiltering."
},
"ObservationScope": {
"properties": {
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"description": "The exact tag set defining this scope (normalized order). Empty list is the global/untagged scope."
},
"count": {
"type": "integer",
"title": "Count",
"description": "Number of observations that live under this scope"
}
},
"type": "object",
"required": [
"tags",
"count"
],
"title": "ObservationScope",
"description": "A distinct observation scope: an exact tag set plus its observation count."
},
"ObservationScopesResponse": {
"properties": {
"scopes": {
"items": {
"$ref": "#/components/schemas/ObservationScope"
},
"type": "array",
"title": "Scopes",
"description": "Distinct observation scopes, most populous first"
},
"total": {
"type": "integer",
"title": "Total",
"description": "Total number of distinct scopes in the bank (ignores limit/offset)"
},
"limit": {
"type": "integer",
"title": "Limit",
"description": "Maximum number of scopes returned in this page"
},
"offset": {
"type": "integer",
"title": "Offset",
"description": "Offset this page started at"
}
},
"type": "object",
"required": [
"scopes",
"total",
"limit",
"offset"
],
"title": "ObservationScopesResponse",
"description": "Response model for the observation scopes enumeration endpoint.",
"example": {
"limit": 100,
"offset": 0,
"scopes": [
{
"count": 12,
"tags": [
"user:alice"
]
},
{
"count": 4,
"tags": [
"user:alice",
"project:apollo"
]
},
{
"count": 2,
"tags": []
}
],
"total": 3
}
},
"OperationProgress": {
"properties": {
"stage": {
"type": "string",
"title": "Stage",
"description": "Coarse phase the operation last reported (e.g. 'processing_batch')."
},
"at": {
"type": "string",
"title": "At",
"description": "ISO-8601 timestamp when this snapshot was written."
},
"processed": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Processed",
"description": "Units of work finished so far (sub-batches, memories), when known."
},
"total": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Total",
"description": "Total units of work for the operation, when known."
},
"detail": {
"anyOf": [
{
"additionalProperties": {
"type": "integer"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Detail",
"description": "Operation-specific counters (e.g. observations_created, round, items_in_sub_batch)."
}
},
"type": "object",
"required": [
"stage",
"at"
],
"title": "OperationProgress",
"description": "Last-known progress snapshot for a long-running async operation.\n\nWritten at coarse phase/batch boundaries by the worker (consolidation, batch\nretain). Lets an operator polling the operation status API distinguish a healthy\nlong-running job (``processed`` advancing across polls) from a frozen one (same\nnumbers, no movement in ``at``). Absent (``null``) on operations that never\nreached a checkpoint \u2014 completed-instantly or pre-feature rows."
},
"OperationResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"task_type": {
"type": "string",
"title": "Task Type"
},
"items_count": {
"type": "integer",
"title": "Items Count"
},
"document_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Document Id"
},
"filename": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Filename",
"description": "Original filename for file-conversion operations (file_convert_retain); null for other task types."
},
"mental_model_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mental Model Id",
"description": "Mental model this operation acted on (refresh_mental_model); null for other task types. Without it the list cannot say which model an operation refreshed \u2014 `document_id` is null for these, and the list carries no result_metadata. The single-operation read exposes the same value under `result_metadata`."
},
"details": {
"anyOf": [
{
"$ref": "#/components/schemas/RefreshMentalModelOperationDetails"
},
{
"type": "null"
}
],
"description": "Typed, per-operation-type outcome detail, discriminated by its own `operation_type`. Populated for `refresh_mental_model` operations that have finished; null for operation types that report no typed detail, for operations still in flight, and for operations recorded before this field existed. Unlike `result_metadata` this is a supported field \u2014 new operation types add their own shape here rather than flattening fields onto the operation."
},
"created_at": {
"type": "string",
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At",
"description": "When this operation's row last changed (claim, progress heartbeat, or completion)."
},
"status": {
"type": "string",
"title": "Status"
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error Message"
},
"retry_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Retry Count",
"description": "Number of times this operation has been retried after failure."
},
"next_retry_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Next Retry At",
"description": "When the worker will next attempt this operation. For a pending operation, a value in the future indicates the task is waiting rather than available for immediate pickup \u2014 a refresh_mental_model held back by min_refresh_interval_seconds, or an extension raising DeferOperation until some backpressure window opens. It is not cleared when the task finally runs, so on a terminal operation it is a record of the last wait rather than a pending one: read it together with status."
},
"progress": {
"anyOf": [
{
"$ref": "#/components/schemas/OperationProgress"
},
{
"type": "null"
}
],
"description": "Last-known progress snapshot for a running operation; null if none was recorded."
}
},
"type": "object",
"required": [
"id",
"task_type",
"items_count",
"created_at",
"status",
"error_message"
],
"title": "OperationResponse",
"description": "Response model for a single async operation.",
"example": {
"created_at": "2024-01-15T10:30:00Z",
"id": "550e8400-e29b-41d4-a716-446655440000",
"items_count": 5,
"retry_count": 0,
"status": "pending",
"task_type": "retain"
}
},
"OperationStatusResponse": {
"properties": {
"operation_id": {
"type": "string",
"title": "Operation Id"
},
"status": {
"type": "string",
"enum": [
"pending",
"processing",
"completed",
"failed",
"cancelled",
"not_found"
],
"title": "Status"
},
"operation_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Operation Type"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
},
"completed_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Completed At"
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error Message"
},
"retry_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Retry Count",
"description": "Number of times this operation has been retried after failure."
},
"next_retry_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Next Retry At",
"description": "When the worker will next attempt this operation. For a pending operation, a value in the future indicates the task is parked \u2014 a refresh_mental_model held back by min_refresh_interval_seconds, or an extension raising DeferOperation \u2014 rather than awaiting immediate pickup."
},
"progress": {
"anyOf": [
{
"$ref": "#/components/schemas/OperationProgress"
},
{
"type": "null"
}
],
"description": "Last-known progress snapshot for a running operation; null if none was recorded."
},
"result_metadata": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Result Metadata",
"description": "Internal metadata for debugging. Structure may change without notice. Not for production use."
},
"details": {
"anyOf": [
{
"$ref": "#/components/schemas/RefreshMentalModelOperationDetails"
},
{
"type": "null"
}
],
"description": "Typed, per-operation-type outcome detail, discriminated by its own `operation_type`. Populated for `refresh_mental_model` operations that have finished; null for operation types that report no typed detail, for operations still in flight, and for operations recorded before this field existed. Unlike `result_metadata` this is a supported field \u2014 new operation types add their own shape here rather than flattening fields onto the operation."
},
"child_operations": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/ChildOperationStatus"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Child Operations",
"description": "Child operations for batch operations (if applicable)"
},
"task_payload": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Task Payload",
"description": "Raw task payload (params the operation was submitted with). Only populated when include_payload=true."
}
},
"type": "object",
"required": [
"operation_id",
"status"
],
"title": "OperationStatusResponse",
"description": "Response model for getting a single operation status.",
"example": {
"completed_at": "2024-01-15T10:31:30Z",
"created_at": "2024-01-15T10:30:00Z",
"operation_id": "550e8400-e29b-41d4-a716-446655440000",
"operation_type": "refresh_mental_model",
"status": "completed",
"updated_at": "2024-01-15T10:31:30Z"
}
},
"OperationsListResponse": {
"properties": {
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"total": {
"type": "integer",
"title": "Total"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
},
"operations": {
"items": {
"$ref": "#/components/schemas/OperationResponse"
},
"type": "array",
"title": "Operations"
}
},
"type": "object",
"required": [
"bank_id",
"total",
"limit",
"offset",
"operations"
],
"title": "OperationsListResponse",
"description": "Response model for list operations endpoint.",
"example": {
"bank_id": "user123",
"limit": 20,
"offset": 0,
"operations": [
{
"created_at": "2024-01-15T10:30:00Z",
"id": "550e8400-e29b-41d4-a716-446655440000",
"items_count": 5,
"status": "pending",
"task_type": "retain"
}
],
"total": 150
}
},
"PromptBlockModel": {
"properties": {
"text": {
"type": "string",
"title": "Text",
"description": "The block's text; empty when the block is inactive."
},
"source": {
"type": "string",
"enum": [
"config",
"builtin"
],
"title": "Source",
"description": "`config` \u2014 produced by a setting (`field` names it); `builtin` \u2014 Hindsight's own wording."
},
"field": {
"type": "string",
"title": "Field",
"description": "Config field behind this block; empty when no single field owns it.",
"default": ""
},
"section": {
"type": "string",
"title": "Section",
"description": "Slug for a part the preview names itself and no field owns: `bank_identity`, `disposition`, `directives`. Empty otherwise.",
"default": ""
},
"heading": {
"type": "string",
"title": "Heading",
"description": "The section heading the prompt text carries at this point, extracted from the prompt itself. Empty when it carries none.",
"default": ""
},
"active": {
"type": "boolean",
"title": "Active",
"description": "Whether this block is in the prompt as configured.",
"default": true
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Value",
"description": "The field's effective value; null when unset."
},
"kind": {
"type": "string",
"enum": [
"text",
"boolean",
"choice",
"complex"
],
"title": "Kind",
"description": "Shape of the value, so a client can offer the right control for editing it."
},
"choices": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Choices",
"description": "Allowed values, when `kind` is `choice`."
},
"editable": {
"type": "boolean",
"title": "Editable",
"description": "Whether this bank may override the field via the bank config API. Server-level fields shape the prompt but cannot be set per bank, and offering to edit one would only collect a 400.",
"default": false
}
},
"type": "object",
"required": [
"text",
"source",
"kind"
],
"title": "PromptBlockModel",
"description": "One block of a message: its text, and the setting that decides it.\n\nThe **active** blocks of a message concatenate back to the exact text sent, so a\nclient can render them separately without showing the reader something the model\nnever receives. An **inactive** block has no text: it marks a setting that is\nswitched off, at the point where it would land if it were on.\n\nEverything identifying a block is a machine value, never display copy \u2014 what a\nblock is called, and what turning a switched-off one on would do, is for the\nclient to say in the language it is running in."
},
"PromptMessageModel": {
"properties": {
"role": {
"type": "string",
"enum": [
"system",
"user"
],
"title": "Role"
},
"blocks": {
"items": {
"$ref": "#/components/schemas/PromptBlockModel"
},
"type": "array",
"title": "Blocks"
}
},
"type": "object",
"required": [
"role"
],
"title": "PromptMessageModel",
"description": "One message of the request, as the blocks it is built from."
},
"PromptPreviewRequest": {
"properties": {
"operation": {
"type": "string",
"enum": [
"retain",
"consolidation",
"reflect"
],
"title": "Operation",
"description": "Which operation's prompts to render.",
"default": "retain"
},
"strategy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Strategy",
"description": "Name of a retain strategy to render under (a key of the bank's `retain_strategies`). Retain only. Omit it and the bank's `retain_default_strategy` applies, exactly as it does for a retain that names none."
}
},
"type": "object",
"title": "PromptPreviewRequest",
"description": "Request to render the prompts an operation would send, without calling an LLM.\n\nThe operation is the whole request: everything that shapes the prompt comes from\nthe bank \u2014 its resolved config, profile and directives \u2014 and the runtime data an\noperation would be given is a fixed placeholder. There is deliberately nothing to\noverride. A preview answers \"what does this bank send\"; letting a caller pass its\nown mission or sample text only moved that question somewhere the bank cannot\nanswer it. To try a candidate value, save it and look again \u2014 the response says\nwhich settings are editable.",
"example": {
"operation": "retain"
}
},
"PromptPreviewResponse": {
"properties": {
"messages": {
"items": {
"$ref": "#/components/schemas/PromptMessageModel"
},
"type": "array",
"title": "Messages",
"description": "Request messages, in send order. Each is given as the blocks it is built from."
},
"strategy": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Strategy",
"description": "The retain strategy these prompts were rendered under, if any."
},
"strategies": {
"items": {
"type": "string"
},
"type": "array",
"title": "Strategies",
"description": "Names of the bank's retain strategies, so a client can offer them without a second call."
},
"run_settings": {
"items": {
"$ref": "#/components/schemas/RunSettingModel"
},
"type": "array",
"title": "Run Settings",
"description": "Settings that shape the operation without appearing in its prompt, such as chunk sizes."
},
"response_schema": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Response Schema",
"description": "JSON schema the response is constrained to, when the operation constrains it."
},
"skipped_reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Skipped Reason",
"description": "Why no prompt is sent, when the configuration means none is."
}
},
"type": "object",
"title": "PromptPreviewResponse",
"description": "The messages one call of the requested operation would send.\n\n`messages` is in send order, system first. Both are always present because a\nmission is not necessarily in the system prompt: retain and consolidation keep\ntheir system prompt bank-agnostic (so one provider-side cache serves every bank)\nand carry the mission in the user message instead.\n\nWhen `skipped_reason` is set the configuration means no prompt is sent at all \u2014\n`chunks` extraction mode stores each chunk verbatim and never calls an LLM \u2014 and\n`messages` is empty."
},
"RecallRequest": {
"properties": {
"query": {
"type": "string",
"title": "Query"
},
"types": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Types",
"description": "List of fact types to recall: 'world', 'experience', 'observation'. Defaults to all fact types if not specified."
},
"prefer_observations": {
"type": "boolean",
"title": "Prefer Observations",
"description": "When recalling raw facts ('world'/'experience') together with 'observation', drop any raw fact that an observation in the results was consolidated from, so the observation supersedes it and you don't get duplicate content. The freed slots are backfilled with the next results, keeping the result count at the requested budget. Disabled by default; set to true to enable. No effect unless 'observation' and at least one raw type are both requested.",
"default": false
},
"budget": {
"$ref": "#/components/schemas/Budget",
"default": "mid"
},
"max_tokens": {
"type": "integer",
"title": "Max Tokens",
"default": 4096
},
"trace": {
"type": "boolean",
"title": "Trace",
"default": false
},
"query_timestamp": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Query Timestamp",
"description": "ISO format date string (e.g., '2023-05-30T23:40:00'). Used as the query-time anchor for relative temporal expressions and recency scoring."
},
"include": {
"$ref": "#/components/schemas/IncludeOptions",
"description": "Options for including additional data (entities are included by default)",
"default": {}
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags",
"description": "Filter memories by tags. If not specified, all memories are returned. Omitting tags (or passing []) together with tags_match='exact' filters to untagged/global observations only (the scope written by observation_scopes='shared')."
},
"tags_match": {
"type": "string",
"enum": [
"any",
"all",
"any_strict",
"all_strict",
"exact"
],
"title": "Tags Match",
"description": "How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged), 'exact' (set-equality on the full scope, excludes untagged). With 'exact' and no tags (or []), the empty global scope is selected and only untagged memories match.",
"default": "any"
},
"tag_groups": {
"anyOf": [
{
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TagGroupLeaf"
},
{
"$ref": "#/components/schemas/TagGroupAnd-Input"
},
{
"$ref": "#/components/schemas/TagGroupOr-Input"
},
{
"$ref": "#/components/schemas/TagGroupNot-Input"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tag Groups",
"description": "Compound tag filter using boolean groups. Groups in the list are AND-ed. Each group is a leaf {tags, match} or compound {and: [...]}, {or: [...]}, {not: ...}. A leaf may set resolve='fuzzy' to match its tags against the bank's tags by trigram similarity instead of literally, so a query that says 'typsecript' still reaches memories tagged 'typescript'."
},
"min_scores": {
"anyOf": [
{
"$ref": "#/components/schemas/MinScores"
},
{
"type": "null"
}
],
"description": "Optional per-stage score floors, each inclusive (`>=`). `semantic` and `keyword` are retrieval-level cutoffs pushed into the SQL arm they name (overriding the global similarity/BM25 minimums for this request), and constrain only that arm: recall fuses four arms (semantic, keyword, graph, temporal) and returns a result surfaced by any of them, so a returned result reports null for a stage that did not surface it (a non-null score always clears its floor). Setting both therefore does not restrict the response to results clearing both. `reranker` and `final` are post-ranking filters applied to every scored result, so those floors *are* guaranteed by each result returned \u2014 use them for query abstention. Any field left unset imposes no floor; omitting `min_scores` entirely (the default) applies no score filtering. Use with care \u2014 the reranker's absolute scores are not calibrated across queries (a clearly-relevant match may score ~0.001 even though it is ranked first)."
},
"temporal_window": {
"anyOf": [
{
"$ref": "#/components/schemas/TemporalWindow"
},
{
"type": "null"
}
],
"description": "Window for the temporal retrieval arm, supplied instead of extracting dates from `query`. Set this when you already know the range you mean \u2014 a date picker, or an agent that resolved 'last quarter' itself \u2014 and recall will skip parsing the query text for dates. **This ranks, it does not filter**: the temporal arm surfaces memories whose own dates (`mentioned_at`, `occurred_start`, `occurred_end`) fall inside the window so they rank higher, while the semantic, keyword and graph arms are unaffected \u2014 so memories dated outside the window are still returned. Ignored when the bank has temporal retrieval disabled."
}
},
"type": "object",
"required": [
"query"
],
"title": "RecallRequest",
"description": "Request model for recall endpoint.",
"example": {
"budget": "mid",
"include": {
"entities": {
"max_tokens": 500
}
},
"max_tokens": 4096,
"query": "What did Alice say about machine learning?",
"query_timestamp": "2023-05-30T23:40:00",
"tags": [
"user_a"
],
"tags_match": "any",
"temporal_window": {
"end": "2023-06-30T23:59:59Z",
"start": "2023-04-01T00:00:00Z"
},
"trace": true,
"types": [
"world",
"experience"
]
}
},
"RecallResponse": {
"properties": {
"results": {
"items": {
"$ref": "#/components/schemas/RecallResult"
},
"type": "array",
"title": "Results"
},
"trace": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Trace"
},
"entities": {
"anyOf": [
{
"additionalProperties": {
"$ref": "#/components/schemas/EntityStateResponse"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Entities",
"description": "Entity states for entities mentioned in results"
},
"chunks": {
"anyOf": [
{
"additionalProperties": {
"$ref": "#/components/schemas/ChunkData"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Chunks",
"description": "Chunks for facts, keyed by chunk_id"
},
"source_facts": {
"anyOf": [
{
"additionalProperties": {
"$ref": "#/components/schemas/RecallResult"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Source Facts",
"description": "Source facts for observation-type results, keyed by fact ID"
},
"source_facts_truncated": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Source Facts Truncated",
"description": "Whether the source_facts map was cut short by the token budget. When true, some IDs in results[].source_fact_ids have no entry in source_facts \u2014 the budget ran out, the references are not dangling. Only set when source facts were requested."
}
},
"type": "object",
"required": [
"results"
],
"title": "RecallResponse",
"description": "Response model for recall endpoints.",
"example": {
"chunks": {
"456e7890-e12b-34d5-a678-901234567890": {
"chunk_index": 0,
"id": "456e7890-e12b-34d5-a678-901234567890",
"text": "Alice works at Google on the AI team. She's been there for 3 years..."
}
},
"entities": {
"Alice": {
"canonical_name": "Alice",
"entity_id": "123e4567-e89b-12d3-a456-426614174001",
"observations": [
{
"mentioned_at": "2024-01-15T10:30:00Z",
"text": "Alice works at Google on the AI team"
}
]
}
},
"results": [
{
"chunk_id": "456e7890-e12b-34d5-a678-901234567890",
"context": "work info",
"entities": [
"Alice",
"Google"
],
"id": "123e4567-e89b-12d3-a456-426614174000",
"occurred_end": "2024-01-15T10:30:00Z",
"occurred_start": "2024-01-15T10:30:00Z",
"text": "Alice works at Google on the AI team",
"type": "world"
}
],
"trace": {
"num_results": 1,
"query": "What did Alice say about machine learning?",
"time_seconds": 0.123
}
}
},
"RecallResult": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"text": {
"type": "string",
"title": "Text"
},
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Type"
},
"entities": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Entities"
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Context"
},
"occurred_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Occurred Start"
},
"occurred_end": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Occurred End"
},
"mentioned_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mentioned At"
},
"document_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Document Id"
},
"metadata": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Metadata"
},
"chunk_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Chunk Id"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags"
},
"source_fact_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Source Fact Ids"
},
"scores": {
"anyOf": [
{
"$ref": "#/components/schemas/RecallScores"
},
{
"type": "null"
}
]
}
},
"type": "object",
"required": [
"id",
"text"
],
"title": "RecallResult",
"description": "Single recall result item.",
"example": {
"chunk_id": "456e7890-e12b-34d5-a678-901234567890",
"context": "work info",
"document_id": "session_abc123",
"entities": [
"Alice",
"Google"
],
"id": "123e4567-e89b-12d3-a456-426614174000",
"mentioned_at": "2024-01-15T10:30:00Z",
"metadata": {
"source": "slack"
},
"occurred_end": "2024-01-15T10:30:00Z",
"occurred_start": "2024-01-15T10:30:00Z",
"tags": [
"user_a",
"user_b"
],
"text": "Alice works at Google on the AI team",
"type": "world"
}
},
"RecallScores": {
"properties": {
"final": {
"type": "number",
"title": "Final",
"description": "Final ranking score (combined reranker + recency/temporal/proof boosts)"
},
"reranker": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Reranker",
"description": "Cross-encoder relevance, normalized 0-1. None when the reranker is a passthrough (rrf/interleave modes)."
},
"semantic": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Semantic",
"description": "Vector cosine similarity (0-1). None if this result was not surfaced semantically."
},
"keyword": {
"anyOf": [
{
"type": "number"
},
{
"type": "null"
}
],
"title": "Keyword",
"description": "Keyword/full-text (BM25) score (>= 0, unbounded). None if this result was not surfaced by keyword search."
}
},
"type": "object",
"required": [
"final"
],
"title": "RecallScores",
"description": "Per-result recall scores from different stages of the pipeline.\n\n``final`` is the value results are ranked by. The others are diagnostic and\ncan be filtered on via the recall ``min_scores`` request parameter. ``semantic``\nand ``keyword`` are the raw per-strategy retrieval scores (``None`` when that\nstrategy did not surface this result); ``reranker`` is the cross-encoder's\nnormalized relevance."
},
"RecoverConsolidationResponse": {
"properties": {
"retried_count": {
"type": "integer",
"title": "Retried Count"
}
},
"type": "object",
"required": [
"retried_count"
],
"title": "RecoverConsolidationResponse",
"description": "Response model for recovering failed consolidation.",
"example": {
"retried_count": 42
}
},
"ReflectBasedOn": {
"properties": {
"memories": {
"items": {
"$ref": "#/components/schemas/ReflectFact"
},
"type": "array",
"title": "Memories",
"description": "Memory facts used to generate the response",
"default": []
},
"mental_models": {
"items": {
"$ref": "#/components/schemas/ReflectMentalModel"
},
"type": "array",
"title": "Mental Models",
"description": "Mental models used during reflection",
"default": []
},
"directives": {
"items": {
"$ref": "#/components/schemas/ReflectDirective"
},
"type": "array",
"title": "Directives",
"description": "Directives applied during reflection",
"default": []
}
},
"type": "object",
"title": "ReflectBasedOn",
"description": "Evidence the response is based on: memories, mental models, and directives."
},
"ReflectDirective": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Directive ID"
},
"name": {
"type": "string",
"title": "Name",
"description": "Directive name"
},
"content": {
"type": "string",
"title": "Content",
"description": "Directive content"
}
},
"type": "object",
"required": [
"id",
"name",
"content"
],
"title": "ReflectDirective",
"description": "A directive applied during reflect."
},
"ReflectFact": {
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id"
},
"text": {
"type": "string",
"title": "Text",
"description": "Fact text. When type='observation', this contains markdown-formatted consolidated knowledge"
},
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Type"
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Context"
},
"occurred_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Occurred Start"
},
"occurred_end": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Occurred End"
}
},
"type": "object",
"required": [
"text"
],
"title": "ReflectFact",
"description": "A fact used in think response.",
"example": {
"context": "healthcare discussion",
"id": "123e4567-e89b-12d3-a456-426614174000",
"occurred_end": "2024-01-15T10:30:00Z",
"occurred_start": "2024-01-15T10:30:00Z",
"text": "AI is used in healthcare",
"type": "world"
}
},
"ReflectIncludeOptions": {
"properties": {
"facts": {
"anyOf": [
{
"$ref": "#/components/schemas/FactsIncludeOptions"
},
{
"type": "null"
}
],
"description": "Include facts that the answer is based on. Set to {} to enable, null to disable (default: disabled)."
},
"tool_calls": {
"anyOf": [
{
"$ref": "#/components/schemas/ToolCallsIncludeOptions"
},
{
"type": "null"
}
],
"description": "Include tool calls trace. Set to {} for full trace (input+output), {output: false} for inputs only."
}
},
"type": "object",
"title": "ReflectIncludeOptions",
"description": "Options for including additional data in reflect results."
},
"ReflectLLMCall": {
"properties": {
"scope": {
"type": "string",
"title": "Scope",
"description": "Call scope: agent_1, agent_2, final, etc."
},
"duration_ms": {
"type": "integer",
"title": "Duration Ms",
"description": "Execution time in milliseconds"
}
},
"type": "object",
"required": [
"scope",
"duration_ms"
],
"title": "ReflectLLMCall",
"description": "An LLM call made during reflect agent execution."
},
"ReflectMentalModel": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Mental model ID"
},
"text": {
"type": "string",
"title": "Text",
"description": "Mental model content"
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Context",
"description": "Additional context"
}
},
"type": "object",
"required": [
"id",
"text"
],
"title": "ReflectMentalModel",
"description": "A mental model used during reflect."
},
"ReflectRequest": {
"properties": {
"query": {
"type": "string",
"title": "Query"
},
"budget": {
"$ref": "#/components/schemas/Budget",
"default": "low"
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Context",
"description": "DEPRECATED: Additional context is now concatenated with the query. Pass context directly in the query field instead. If provided, it will be appended to the query for backward compatibility.",
"deprecated": true
},
"max_tokens": {
"type": "integer",
"title": "Max Tokens",
"description": "Maximum tokens for the response",
"default": 4096
},
"include": {
"$ref": "#/components/schemas/ReflectIncludeOptions",
"description": "Options for including additional data (disabled by default)"
},
"response_schema": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Response Schema",
"description": "Optional JSON Schema for structured output. When provided, the response will include a 'structured_output' field with the LLM response parsed according to this schema."
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags",
"description": "Scope raw facts, observations, mental models, and tagged directives during reflection. With no tags, memory retrieval is unfiltered while only untagged/global directives are loaded. Use tags=[] with tags_match='exact' to select the untagged/global scope."
},
"tags_match": {
"type": "string",
"enum": [
"any",
"all",
"any_strict",
"all_strict",
"exact"
],
"title": "Tags Match",
"description": "How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged), or 'exact' (set equality). Untagged directives remain global in every mode.",
"default": "any"
},
"tag_groups": {
"anyOf": [
{
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TagGroupLeaf"
},
{
"$ref": "#/components/schemas/TagGroupAnd-Input"
},
{
"$ref": "#/components/schemas/TagGroupOr-Input"
},
{
"$ref": "#/components/schemas/TagGroupNot-Input"
}
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tag Groups",
"description": "Compound tag filter using boolean groups. Groups in the list are AND-ed. Each group is a leaf {tags, match} or compound {and: [...]}, {or: [...]}, {not: ...}. Mutually exclusive with tags. A leaf may set resolve='fuzzy' to match its tags against the bank's tags by trigram similarity instead of literally, so a query that says 'typsecript' still reaches memories tagged 'typescript'."
},
"apply_all_directives": {
"type": "boolean",
"title": "Apply All Directives",
"description": "Apply every active directive regardless of tags. By default directives are scoped like memories: untagged directives always apply, and tagged directives apply only when the request's tags match them. Set true to apply all active directives, ignoring tag scope.",
"default": false
},
"fact_types": {
"anyOf": [
{
"items": {
"type": "string",
"enum": [
"world",
"experience",
"observation"
]
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Fact Types",
"description": "Filter which fact types are retrieved during reflect. None means all types (world, experience, observation)."
},
"exclude_mental_models": {
"type": "boolean",
"title": "Exclude Mental Models",
"description": "If true, exclude all mental models from the reflect loop (skip search_mental_models tool).",
"default": false
},
"exclude_mental_model_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Exclude Mental Model Ids",
"description": "Exclude specific mental models by ID from the reflect loop."
}
},
"type": "object",
"required": [
"query"
],
"title": "ReflectRequest",
"description": "Request model for reflect endpoint.",
"example": {
"budget": "low",
"include": {
"facts": {}
},
"max_tokens": 4096,
"query": "What do you think about artificial intelligence?",
"response_schema": {
"properties": {
"summary": {
"type": "string"
},
"key_points": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"summary",
"key_points"
],
"type": "object"
},
"tags": [
"user_a"
],
"tags_match": "any"
}
},
"ReflectResponse": {
"properties": {
"text": {
"type": "string",
"title": "Text",
"description": "The reflect response as well-formatted markdown (headers, lists, bold/italic, code blocks, etc.)"
},
"based_on": {
"anyOf": [
{
"$ref": "#/components/schemas/ReflectBasedOn"
},
{
"type": "null"
}
],
"description": "Evidence used to generate the response. Only present when include.facts is set."
},
"structured_output": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Structured Output",
"description": "Structured output parsed according to the request's response_schema. Only present when response_schema was provided in the request."
},
"usage": {
"anyOf": [
{
"$ref": "#/components/schemas/TokenUsage"
},
{
"type": "null"
}
],
"description": "Token usage metrics for LLM calls during reflection."
},
"trace": {
"anyOf": [
{
"$ref": "#/components/schemas/ReflectTrace"
},
{
"type": "null"
}
],
"description": "Execution trace of tool and LLM calls. Only present when include.tool_calls is set."
}
},
"type": "object",
"required": [
"text"
],
"title": "ReflectResponse",
"description": "Response model for think endpoint.",
"example": {
"based_on": {
"memories": [
{
"id": "123",
"text": "AI is used in healthcare",
"type": "world"
},
{
"id": "456",
"text": "I discussed AI applications last week",
"type": "experience"
}
]
},
"structured_output": {
"key_points": [
"Used in healthcare",
"Discussed recently"
],
"summary": "AI is transformative"
},
"text": "## AI Overview\n\nBased on my understanding, AI is a **transformative technology**:\n\n- Used extensively in healthcare\n- Discussed in recent conversations\n- Continues to evolve rapidly",
"trace": {
"llm_calls": [
{
"duration_ms": 1200,
"scope": "agent_1"
}
],
"observations": [
{
"id": "obs-1",
"name": "AI Technology",
"subtype": "structural",
"type": "concept"
}
],
"tool_calls": [
{
"duration_ms": 150,
"input": {
"query": "AI"
},
"tool": "recall"
}
]
},
"usage": {
"input_tokens": 1500,
"output_tokens": 500,
"total_tokens": 2000
}
}
},
"ReflectToolCall": {
"properties": {
"tool": {
"type": "string",
"title": "Tool",
"description": "Tool name: lookup, recall, learn, expand"
},
"input": {
"additionalProperties": true,
"type": "object",
"title": "Input",
"description": "Tool input parameters"
},
"output": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Output",
"description": "Tool output (only included when include.tool_calls.output is true)"
},
"duration_ms": {
"type": "integer",
"title": "Duration Ms",
"description": "Execution time in milliseconds"
},
"iteration": {
"type": "integer",
"title": "Iteration",
"description": "Iteration number (1-based) when this tool was called",
"default": 0
}
},
"type": "object",
"required": [
"tool",
"input",
"duration_ms"
],
"title": "ReflectToolCall",
"description": "A tool call made during reflect agent execution."
},
"ReflectTrace": {
"properties": {
"tool_calls": {
"items": {
"$ref": "#/components/schemas/ReflectToolCall"
},
"type": "array",
"title": "Tool Calls",
"description": "Tool calls made during reflection",
"default": []
},
"llm_calls": {
"items": {
"$ref": "#/components/schemas/ReflectLLMCall"
},
"type": "array",
"title": "Llm Calls",
"description": "LLM calls made during reflection",
"default": []
}
},
"type": "object",
"title": "ReflectTrace",
"description": "Execution trace of LLM and tool calls during reflection."
},
"RefreshMentalModelOperationDetails": {
"properties": {
"operation_type": {
"type": "string",
"const": "refresh_mental_model",
"title": "Operation Type",
"description": "Discriminator: which operation type this detail describes.",
"default": "refresh_mental_model"
},
"outcome": {
"type": "string",
"enum": [
"content_written",
"content_unchanged",
"content_preserved_no_new_facts",
"refresh_failed_empty_candidate",
"refresh_failed_delta_not_applied",
"refresh_failed_structured_output",
"refresh_failed_error"
],
"title": "Outcome",
"description": "What the refresh did with the document: rewrote it (`content_written`), produced a document identical to the stored one (`content_unchanged`), had no new facts to read at all (`content_preserved_no_new_facts`), or refused to write (the `refresh_failed_*` values)."
},
"failure_reason": {
"anyOf": [
{
"type": "string",
"enum": [
"empty_candidate",
"structured_doc_unreadable",
"delta_ops_failed",
"delta_ops_all_skipped",
"delta_not_applied",
"structured_output_failed",
"retrieval_failed",
"no_answer",
"unexpected_error"
]
},
{
"type": "null"
}
],
"title": "Failure Reason",
"description": "Why the refresh refused to write, finer-grained than the outcome \u2014 it distinguishes an op call that failed from one whose operations were all rejected, and from a baseline document that could not be read. Null unless `outcome` is one of the `refresh_failed_*` values."
}
},
"type": "object",
"required": [
"outcome"
],
"title": "RefreshMentalModelOperationDetails",
"description": "What a refresh_mental_model operation did, on the operation record itself.\n\nReported under an async operation's ``details``, which is keyed by\n``operation_type``: each type that has a typed outcome to report contributes\nits own shape there, rather than every type's fields being flattened onto the\noperation. Today refresh is the only one.\n\nThis exists because ``result_metadata`` \u2014 the only per-refresh record kept\nindefinitely \u2014 could not say what a refresh did (#3274), and is documented as\ndebug-only and unstable, so it is not something a caller can build on."
},
"ReprocessDocumentResponse": {
"properties": {
"success": {
"type": "boolean",
"title": "Success"
},
"operation_id": {
"type": "string",
"title": "Operation Id"
},
"items_count": {
"type": "integer",
"title": "Items Count"
}
},
"type": "object",
"required": [
"success",
"operation_id",
"items_count"
],
"title": "ReprocessDocumentResponse",
"description": "Response model for reprocess document endpoint."
},
"RetainRequest": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/MemoryItem"
},
"type": "array",
"title": "Items"
},
"async": {
"type": "boolean",
"title": "Async",
"description": "If true, process asynchronously in background. If false, wait for completion (default: false)",
"default": false
},
"document_tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Document Tags",
"description": "Deprecated. Use item-level tags instead.",
"deprecated": true
},
"operation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Operation Id",
"description": "Optional client-supplied UUID used as the identity of an async retain operation. Re-submitting with the same operation_id returns the original operation and creates no new work, so retrying after a lost or timed-out acknowledgement will not enqueue a duplicate. Reusing an id that belongs to a different operation returns HTTP 409. Ignored for synchronous retain."
}
},
"type": "object",
"required": [
"items"
],
"title": "RetainRequest",
"description": "Request model for retain endpoint.",
"example": {
"async": false,
"items": [
{
"content": "Alice works at Google",
"context": "work",
"document_id": "conversation_123"
},
{
"content": "Bob went hiking yesterday",
"document_id": "conversation_123",
"timestamp": "2024-01-15T10:00:00Z"
}
]
}
},
"RetainResponse": {
"properties": {
"success": {
"type": "boolean",
"title": "Success"
},
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"items_count": {
"type": "integer",
"title": "Items Count"
},
"async": {
"type": "boolean",
"title": "Async",
"description": "Whether the operation was processed asynchronously"
},
"operation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Operation Id",
"description": "Operation ID for tracking async operations. Use GET /v1/default/banks/{bank_id}/operations to list operations. Only present when async=true. When items use different per-item strategies, use operation_ids instead."
},
"operation_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Operation Ids",
"description": "Operation IDs when items were submitted as multiple strategy groups (async=true with mixed per-item strategies). operation_id is set to the first entry for backward compatibility."
},
"usage": {
"anyOf": [
{
"$ref": "#/components/schemas/TokenUsage"
},
{
"type": "null"
}
],
"description": "Token usage metrics for LLM calls during fact extraction (only present for synchronous operations)"
}
},
"type": "object",
"required": [
"success",
"bank_id",
"items_count",
"async"
],
"title": "RetainResponse",
"description": "Response model for retain endpoint.",
"example": {
"async": false,
"bank_id": "user123",
"items_count": 2,
"success": true,
"usage": {
"input_tokens": 500,
"output_tokens": 100,
"total_tokens": 600
}
}
},
"RetryOperationResponse": {
"properties": {
"success": {
"type": "boolean",
"title": "Success"
},
"message": {
"type": "string",
"title": "Message"
},
"operation_id": {
"type": "string",
"title": "Operation Id"
}
},
"type": "object",
"required": [
"success",
"message",
"operation_id"
],
"title": "RetryOperationResponse",
"description": "Response model for retry operation endpoint.",
"example": {
"message": "Operation 550e8400-e29b-41d4-a716-446655440000 queued for retry",
"operation_id": "550e8400-e29b-41d4-a716-446655440000",
"success": true
}
},
"RunSettingModel": {
"properties": {
"field": {
"type": "string",
"title": "Field"
},
"value": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Value",
"description": "Effective value; null when unset."
},
"kind": {
"type": "string",
"enum": [
"text",
"boolean",
"choice",
"complex"
],
"title": "Kind",
"description": "Shape of the value, so a client can offer the right control."
},
"editable": {
"type": "boolean",
"title": "Editable",
"description": "Whether this bank may override the field via the bank config API.",
"default": false
}
},
"type": "object",
"required": [
"field",
"kind"
],
"title": "RunSettingModel",
"description": "A setting that shapes the operation without appearing in its prompt.\n\nChunk sizes decide how the input is cut before extraction runs, so they change\nwhat comes back while contributing no prompt text \u2014 they cannot be blocks, which\npartition the message, and these are in none of it."
},
"SourceFactsIncludeOptions": {
"properties": {
"max_tokens": {
"type": "integer",
"title": "Max Tokens",
"description": "Maximum total tokens for source facts across all observations (-1 = unlimited)",
"default": 4096
},
"max_tokens_per_observation": {
"type": "integer",
"title": "Max Tokens Per Observation",
"description": "Maximum tokens of source facts per observation (-1 = unlimited)",
"default": -1
}
},
"type": "object",
"title": "SourceFactsIncludeOptions",
"description": "Options for including source facts for observation-type results."
},
"TagGroupAnd-Input": {
"properties": {
"and": {
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TagGroupLeaf"
},
{
"$ref": "#/components/schemas/TagGroupAnd-Input"
},
{
"$ref": "#/components/schemas/TagGroupOr-Input"
},
{
"$ref": "#/components/schemas/TagGroupNot-Input"
}
]
},
"type": "array",
"title": "And"
}
},
"type": "object",
"required": [
"and"
],
"title": "TagGroupAnd",
"description": "Compound AND group: all child filters must match."
},
"TagGroupAnd-Output": {
"properties": {
"and": {
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TagGroupLeaf"
},
{
"$ref": "#/components/schemas/TagGroupAnd-Output"
},
{
"$ref": "#/components/schemas/TagGroupOr-Output"
},
{
"$ref": "#/components/schemas/TagGroupNot-Output"
}
]
},
"type": "array",
"title": "And"
}
},
"type": "object",
"required": [
"and"
],
"title": "TagGroupAnd",
"description": "Compound AND group: all child filters must match."
},
"TagGroupLeaf": {
"properties": {
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags"
},
"match": {
"type": "string",
"enum": [
"any",
"all",
"any_strict",
"all_strict",
"exact"
],
"title": "Match",
"default": "any_strict"
},
"resolve": {
"type": "string",
"enum": [
"exact",
"fuzzy"
],
"title": "Resolve",
"default": "exact"
}
},
"type": "object",
"required": [
"tags"
],
"title": "TagGroupLeaf",
"description": "A leaf tag filter: matches memories by tag list and match mode."
},
"TagGroupNot-Input": {
"properties": {
"not": {
"anyOf": [
{
"$ref": "#/components/schemas/TagGroupLeaf"
},
{
"$ref": "#/components/schemas/TagGroupAnd-Input"
},
{
"$ref": "#/components/schemas/TagGroupOr-Input"
},
{
"$ref": "#/components/schemas/TagGroupNot-Input"
}
],
"title": "Not"
}
},
"type": "object",
"required": [
"not"
],
"title": "TagGroupNot",
"description": "Compound NOT group: child filter must NOT match."
},
"TagGroupNot-Output": {
"properties": {
"not": {
"anyOf": [
{
"$ref": "#/components/schemas/TagGroupLeaf"
},
{
"$ref": "#/components/schemas/TagGroupAnd-Output"
},
{
"$ref": "#/components/schemas/TagGroupOr-Output"
},
{
"$ref": "#/components/schemas/TagGroupNot-Output"
}
],
"title": "Not"
}
},
"type": "object",
"required": [
"not"
],
"title": "TagGroupNot",
"description": "Compound NOT group: child filter must NOT match."
},
"TagGroupOr-Input": {
"properties": {
"or": {
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TagGroupLeaf"
},
{
"$ref": "#/components/schemas/TagGroupAnd-Input"
},
{
"$ref": "#/components/schemas/TagGroupOr-Input"
},
{
"$ref": "#/components/schemas/TagGroupNot-Input"
}
]
},
"type": "array",
"title": "Or"
}
},
"type": "object",
"required": [
"or"
],
"title": "TagGroupOr",
"description": "Compound OR group: at least one child filter must match."
},
"TagGroupOr-Output": {
"properties": {
"or": {
"items": {
"anyOf": [
{
"$ref": "#/components/schemas/TagGroupLeaf"
},
{
"$ref": "#/components/schemas/TagGroupAnd-Output"
},
{
"$ref": "#/components/schemas/TagGroupOr-Output"
},
{
"$ref": "#/components/schemas/TagGroupNot-Output"
}
]
},
"type": "array",
"title": "Or"
}
},
"type": "object",
"required": [
"or"
],
"title": "TagGroupOr",
"description": "Compound OR group: at least one child filter must match."
},
"TagItem": {
"properties": {
"tag": {
"type": "string",
"title": "Tag",
"description": "The tag value"
},
"count": {
"type": "integer",
"title": "Count",
"description": "Number of memories with this tag"
}
},
"type": "object",
"required": [
"tag",
"count"
],
"title": "TagItem",
"description": "Single tag with usage count."
},
"TemporalWindow": {
"properties": {
"start": {
"type": "string",
"format": "date-time",
"title": "Start",
"description": "Start of the window (inclusive)."
},
"end": {
"type": "string",
"format": "date-time",
"title": "End",
"description": "End of the window (inclusive)."
}
},
"type": "object",
"required": [
"start",
"end"
],
"title": "TemporalWindow",
"description": "A caller-supplied window for recall's temporal arm.\n\nSupplying this **replaces the date extraction** recall would otherwise run\nover the query text, so a caller that already knows the range it means does\nnot have to phrase it in English and hope the parser agrees.\n\nIt is **not a filter**. The temporal arm is one of four retrieval arms: it\nsurfaces memories whose own dates (``mentioned_at`` / ``occurred_start`` /\n``occurred_end``) fall inside the window so fusion can rank them higher.\nThe semantic, keyword and graph arms are unaffected, so results dated\noutside the window are still returned. Narrowing results to a date range is\na different operation this does not provide.\n\nHas no effect when the bank's ``enable_temporal_retrieval`` config is off:\nthat flag gates the arm itself, and stays the single switch for it."
},
"TextContentBlock": {
"properties": {
"type": {
"type": "string",
"const": "text",
"title": "Type"
},
"text": {
"type": "string",
"title": "Text"
}
},
"type": "object",
"required": [
"type",
"text"
],
"title": "TextContentBlock",
"description": "A run of text within a multimodal item, in the position the caller wrote it."
},
"TokenUsage": {
"properties": {
"input_tokens": {
"type": "integer",
"title": "Input Tokens",
"description": "Number of input/prompt tokens consumed",
"default": 0
},
"output_tokens": {
"type": "integer",
"title": "Output Tokens",
"description": "Number of visible output/completion tokens generated (excludes reasoning/thoughts)",
"default": 0
},
"total_tokens": {
"type": "integer",
"title": "Total Tokens",
"description": "Total tokens (input + output, excludes thoughts)",
"default": 0
},
"cached_tokens": {
"type": "integer",
"title": "Cached Tokens",
"description": "Cached/cache-read prompt tokens, when reported by the provider",
"default": 0
},
"thoughts_tokens": {
"type": "integer",
"title": "Thoughts Tokens",
"description": "Reasoning/thinking tokens generated by the model. Billed at the output rate by some providers (e.g. Gemini 2.5+ family) but not surfaced in the visible response.",
"default": 0
}
},
"type": "object",
"title": "TokenUsage",
"description": "Token usage metrics for LLM calls.\n\nTracks input/output tokens for a single request to enable\nper-request cost tracking and monitoring.",
"example": {
"input_tokens": 1500,
"output_tokens": 500,
"total_tokens": 2000
}
},
"ToolCallsIncludeOptions": {
"properties": {
"output": {
"type": "boolean",
"title": "Output",
"description": "Include tool outputs in the trace. Set to false to only include inputs (smaller payload).",
"default": true
}
},
"type": "object",
"title": "ToolCallsIncludeOptions",
"description": "Options for including tool calls in reflect results."
},
"UpdateDirectiveRequest": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "New name"
},
"content": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content",
"description": "New content"
},
"priority": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Priority",
"description": "New priority"
},
"is_active": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Is Active",
"description": "New active status"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags",
"description": "New tags"
}
},
"type": "object",
"title": "UpdateDirectiveRequest",
"description": "Request model for updating a directive."
},
"UpdateDispositionRequest": {
"properties": {
"disposition": {
"$ref": "#/components/schemas/DispositionTraits"
}
},
"type": "object",
"required": [
"disposition"
],
"title": "UpdateDispositionRequest",
"description": "Request model for updating disposition traits."
},
"UpdateDocumentRequest": {
"properties": {
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags",
"description": "New tags for the document and its memory units. Triggers observation invalidation and re-consolidation."
}
},
"type": "object",
"title": "UpdateDocumentRequest",
"description": "Request model for updating a document's mutable fields.",
"example": {
"tags": [
"team-a",
"team-b"
]
}
},
"UpdateDocumentResponse": {
"properties": {
"success": {
"type": "boolean",
"title": "Success",
"default": true
}
},
"type": "object",
"title": "UpdateDocumentResponse",
"description": "Response model for update document endpoint."
},
"UpdateMemoryRequest": {
"properties": {
"text": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Text",
"description": "New fact text. Re-embeds the memory, drops its derived observations and links, and triggers re-consolidation."
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Context",
"description": "New context for the fact. '' clears it; omit to leave unchanged."
},
"occurred_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Occurred Start",
"description": "New occurred-range start (ISO 8601). '' clears it; omit to leave unchanged."
},
"occurred_end": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Occurred End",
"description": "New occurred-range end (ISO 8601). '' clears it; omit to leave unchanged."
},
"fact_type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Fact Type",
"description": "Reclassify the fact: 'world' or 'experience'. Omit to leave unchanged."
},
"entities": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Entities",
"description": "Replace the fact's entities. How each name is matched to an entity is governed by 'resolve_entities'. '[]' detaches all entities. Omit to leave unchanged."
},
"resolve_entities": {
"type": "boolean",
"title": "Resolve Entities",
"description": "Whether the names in 'entities' are resolved against the entities already in the bank. True (default) is what retain does: a similar existing entity is reused when it scores above the match threshold, so a name close to one already in the bank may resolve to that one instead of the one you wrote. False takes the names literally \u2014 an existing entity is reused only on a case-insensitive name match, any other name creates a new entity, and names in the same request are never merged with each other. Use False for hand-authored corrections, where the name you sent is the answer rather than a guess. Ignored when 'entities' is omitted.",
"default": true
},
"state": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "State",
"description": "Curation state: 'invalidated' to soft-retire the memory (excluded from recall/consolidation, links and derived observations pruned, moved to the archive) or 'valid' to revert. Reversible."
},
"reason": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reason",
"description": "Optional free-text reason recorded when invalidating."
}
},
"type": "object",
"title": "UpdateMemoryRequest",
"description": "Request model for curating a single memory unit (edit / invalidate / revert).\n\nProvide ``text`` to correct the fact, and/or ``state`` to invalidate\n('invalidated') or revert ('valid') it. ``reason`` is optional free text\nrecorded on the memory. At least one of ``text`` or ``state`` must be set.\nOnly world/experience facts can be curated; observations are derived.",
"example": {
"reason": "superseded: server decommissioned 2026-06-01",
"state": "invalidated"
}
},
"UpdateMentalModelRequest": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "New name for the mental model"
},
"source_query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Query",
"description": "New source query for the mental model"
},
"max_tokens": {
"anyOf": [
{
"type": "integer",
"maximum": 8192.0,
"minimum": 256.0
},
{
"type": "null"
}
],
"title": "Max Tokens",
"description": "Maximum tokens for generated content"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags",
"description": "Tags for scoped visibility"
},
"trigger": {
"anyOf": [
{
"$ref": "#/components/schemas/MentalModelTrigger-Input"
},
{
"type": "null"
}
],
"description": "Trigger settings"
}
},
"type": "object",
"title": "UpdateMentalModelRequest",
"description": "Request model for updating a mental model.",
"example": {
"max_tokens": 4096,
"name": "Updated Team Communication Preferences",
"source_query": "How does the team prefer to communicate?",
"tags": [
"team",
"communication"
],
"trigger": {
"refresh_after_consolidation": true
}
}
},
"UpdateNodeRequest": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"parent_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Parent Id"
},
"source_query": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Source Query"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags",
"description": "Replaces the page's tags, which SCOPE which memories it is built from. Pass `[]` to clear them and rebuild the page from the whole bank \u2014 the fix when a page generates 'I don't have information about this' because its tags match no memory. See the matching rules on this field in `CreatePageRequest`; `trigger.tags_match` widens them."
},
"max_tokens": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Max Tokens"
},
"trigger": {
"anyOf": [
{
"$ref": "#/components/schemas/MentalModelTrigger-Input"
},
{
"type": "null"
}
],
"description": "Refresh settings to change. Applied as a patch: only the fields present in this object are updated, and the rest keep the page's current values \u2014 so moving a page onto a schedule does not reset how it refreshes. Setting refresh_cron clears refresh_after_consolidation and vice versa, since a page refreshes on one or the other, never both."
}
},
"type": "object",
"title": "UpdateNodeRequest",
"description": "Rename/move a node and/or update a page's options. Each field applies only\nwhen present in the request body."
},
"UpdateWebhookRequest": {
"properties": {
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Url",
"description": "HTTP(S) endpoint URL"
},
"secret": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Secret",
"description": "HMAC-SHA256 signing secret. Omit to keep existing; send null to clear."
},
"event_types": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Event Types",
"description": "List of event types"
},
"enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enabled",
"description": "Whether this webhook is active"
},
"http_config": {
"anyOf": [
{
"$ref": "#/components/schemas/WebhookHttpConfig"
},
{
"type": "null"
}
],
"description": "HTTP delivery configuration"
}
},
"type": "object",
"title": "UpdateWebhookRequest",
"description": "Request model for updating a webhook. Only provided fields are updated."
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
},
"input": {
"title": "Input"
},
"ctx": {
"type": "object",
"title": "Context"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"VersionResponse": {
"properties": {
"api_version": {
"type": "string",
"title": "Api Version",
"description": "API version string"
},
"features": {
"$ref": "#/components/schemas/FeaturesInfo",
"description": "Enabled feature flags"
}
},
"type": "object",
"required": [
"api_version",
"features"
],
"title": "VersionResponse",
"description": "Response model for the version/info endpoint.",
"example": {
"api_version": "0.9.0",
"features": {
"audit_log": false,
"bank_config_api": false,
"bank_llm_health": true,
"document_export_api": true,
"document_import_api": true,
"file_upload_api": true,
"llm_trace": false,
"mcp": true,
"observations": false,
"store_document_text": true,
"worker": true
}
}
},
"WebhookDeliveryListResponse": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/WebhookDeliveryResponse"
},
"type": "array",
"title": "Items"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Next Cursor"
}
},
"type": "object",
"required": [
"items"
],
"title": "WebhookDeliveryListResponse",
"description": "Response model for listing webhook deliveries."
},
"WebhookDeliveryResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"webhook_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Webhook Id"
},
"url": {
"type": "string",
"title": "Url"
},
"event_type": {
"type": "string",
"title": "Event Type"
},
"status": {
"type": "string",
"title": "Status"
},
"attempts": {
"type": "integer",
"title": "Attempts"
},
"next_retry_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Next Retry At"
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Error"
},
"last_response_status": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Last Response Status"
},
"last_response_body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Response Body"
},
"last_attempt_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Attempt At"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"webhook_id",
"url",
"event_type",
"status",
"attempts"
],
"title": "WebhookDeliveryResponse",
"description": "Response model for a webhook delivery record."
},
"WebhookHttpConfig": {
"properties": {
"method": {
"type": "string",
"title": "Method",
"description": "HTTP method: GET or POST",
"default": "POST"
},
"timeout_seconds": {
"type": "integer",
"title": "Timeout Seconds",
"description": "HTTP request timeout in seconds",
"default": 30
},
"headers": {
"additionalProperties": {
"type": "string"
},
"type": "object",
"title": "Headers",
"description": "Custom HTTP headers"
},
"params": {
"additionalProperties": {
"type": "string"
},
"type": "object",
"title": "Params",
"description": "Custom HTTP query parameters"
}
},
"type": "object",
"title": "WebhookHttpConfig",
"description": "HTTP delivery configuration for a webhook."
},
"WebhookListResponse": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/WebhookResponse"
},
"type": "array",
"title": "Items"
},
"total": {
"type": "integer",
"title": "Total",
"description": "Total number of webhooks on the bank (ignores limit/offset)"
},
"limit": {
"type": "integer",
"title": "Limit",
"description": "Maximum number of webhooks returned in this page"
},
"offset": {
"type": "integer",
"title": "Offset",
"description": "Offset this page started at"
}
},
"type": "object",
"required": [
"items",
"total",
"limit",
"offset"
],
"title": "WebhookListResponse",
"description": "Response model for listing webhooks."
},
"WebhookResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"bank_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Bank Id"
},
"url": {
"type": "string",
"title": "Url"
},
"secret": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Secret",
"description": "Signing secret (redacted in responses)"
},
"event_types": {
"items": {
"type": "string"
},
"type": "array",
"title": "Event Types"
},
"enabled": {
"type": "boolean",
"title": "Enabled"
},
"http_config": {
"$ref": "#/components/schemas/WebhookHttpConfig"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"bank_id",
"url",
"event_types",
"enabled"
],
"title": "WebhookResponse",
"description": "Response model for a webhook."
}
}
}
}
Reference in New Issue View Git Blame Copy Permalink