{ "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.6.2" }, "paths": { "/health": { "get": { "tags": [ "Monitoring" ], "summary": "Health check endpoint", "description": "Checks the health of the API and database connection", "operationId": "health_endpoint_health_get", "responses": { "200": { "description": "Successful Response", "content": { "application/json": { "schema": {} } } } } } }, "/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/opinion).", "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", "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" } } } }, "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. 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": "limit", "in": "query", "required": false, "schema": { "type": "integer", "default": 100, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "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" } } } }, "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" } } } } } } }, "/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 type parameter is optional and must be one of:\n- `world`: General knowledge about people, places, events, and things that happen\n- `experience`: Memories about experience, conversations, actions taken, and tasks performed", "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, and opinions.\n\nThis endpoint:\n1. Retrieves experience (conversations and events)\n2. Retrieves world facts relevant to the query\n3. Retrieves existing opinions (bank's 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 all memory banks", "description": "Get a list of all agents with their profiles", "operationId": "list_banks", "parameters": [ { "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": "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" } } } }, "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" } } } }, "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", "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", "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" } } } }, "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", "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" } } } }, "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" } } } }, "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}/directives": { "get": { "tags": [ "Directives" ], "summary": "List directives", "description": "List hard rules that are injected into prompts.", "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 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": "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" } } } }, "422": { "description": "Validation Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HTTPValidationError" } } } } } }, "post": { "tags": [ "Directives" ], "summary": "Create directive", "description": "Create a hard rule that will be injected into 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. 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", "default": 100, "title": "Limit" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "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" } } } }, "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", "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", "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" } } } }, "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" } } } }, "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', 'completed', or 'failed'. Completed operations are removed from storage, so 'completed' means the operation finished successfully.", "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 async operation", "description": "Cancel a pending async operation by removing it from the queue", "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}/profile": { "get": { "tags": [ "Banks" ], "summary": "Get memory bank profile", "description": "Get disposition traits and mission for a memory bank. Returns 404 if the bank does not exist.", "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", "description": "Update bank's disposition traits (skepticism, literalism, empathy)", "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 (deprecated)", "description": "Deprecated: Use PUT /mission instead. This endpoint now updates the mission field.", "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" } } } }, "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}/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.", "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" } } } }, "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 fields can be overridden (LLM settings, retention parameters, etc.). Keys can be provided in Python field format (llm_provider) or environment variable format (HINDSIGHT_API_LLM_PROVIDER).", "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" } } ], "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 all webhooks registered for a bank.", "operationId": "list_webhooks", "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/WebhookListResponse" } } } }, "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, opinion) 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, opinion)", "title": "Type" }, "description": "Optional fact type filter (world, experience, opinion)" }, { "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 (with 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" } } } }, "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" } } } }, "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": { "llm_model": "gpt-4", "llm_provider": "openai", "retain_extraction_mode": "verbose" }, "overrides": { "llm_model": "gpt-4", "retain_extraction_mode": "verbose" } } }, "BankConfigUpdate": { "properties": { "updates": { "additionalProperties": true, "type": "object", "title": "Updates", "description": "Configuration overrides. Keys can be in Python field format (llm_provider) or environment variable format (HINDSIGHT_API_LLM_PROVIDER). Only hierarchical fields can be overridden per-bank." } }, "type": "object", "required": [ "updates" ], "title": "BankConfigUpdate", "description": "Request model for updating bank configuration.", "example": { "updates": { "llm_model": "claude-sonnet-4-5", "retain_custom_instructions": "Extract technical details carefully", "retain_extraction_mode": "verbose" } } }, "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" } }, "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" } }, "type": "object", "required": [ "banks" ], "title": "BankListResponse", "description": "Response model for listing all banks.", "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", "mission": "I am a software engineer helping my team ship quality code", "name": "Alice", "updated_at": "2024-01-16T14:20:00Z" } ] } }, "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)" }, "pending_consolidation": { "type": "integer", "title": "Pending Consolidation", "description": "Number of memories not yet processed into observations", "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", "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', or 'custom'" }, "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": "Max token size for each content chunk" }, "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" }, "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": { "additionalProperties": true, "type": "object" }, "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)" }, "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" }, "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" }, "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)" } }, "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." }, "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" }, "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)." }, "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 } }, "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" } }, "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 } }, "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', or 'custom'." }, "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": "Maximum token size for each content chunk during retain." }, "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." } }, "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": "Tags for filtering", "default": [] } }, "type": "object", "required": [ "name", "content" ], "title": "CreateDirectiveRequest", "description": "Request model for creating a directive." }, "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." }, "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. Currently supported: 'consolidation.completed'", "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 } }, "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" } }, "type": "object", "required": [ "items" ], "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 } }, "DocumentResponse": { "properties": { "id": { "type": "string", "title": "Id" }, "bank_id": { "type": "string", "title": "Bank Id" }, "original_text": { "type": "string", "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" } }, "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" } }, "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." }, "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" }, "file_upload_api": { "type": "boolean", "title": "File Upload Api", "description": "Whether file upload/conversion API is enabled" } }, "type": "object", "required": [ "observations", "mcp", "worker", "bank_config_api", "file_upload_api" ], "title": "FeaturesInfo", "description": "Feature flags indicating which capabilities are enabled." }, "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" }, "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." }, "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", "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 } }, "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": { "type": "string", "title": "Content" }, "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." }, "entities": { "anyOf": [ { "items": { "$ref": "#/components/schemas/EntityInput" }, "type": "array" }, { "type": "null" } ], "title": "Entities", "description": "Optional entities to combine with auto-extracted entities." }, "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" ] }, { "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. 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." }, "MentalModelListResponse": { "properties": { "items": { "items": { "$ref": "#/components/schemas/MentalModelResponse" }, "type": "array", "title": "Items" } }, "type": "object", "required": [ "items" ], "title": "MentalModelListResponse", "description": "Response model for listing mental models." }, "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" }, "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 new memories matching this mental model's tag/fact_type scope have been ingested since last_refreshed_at, or consolidation has pending items. Only populated when detail=full." } }, "type": "object", "required": [ "id", "bank_id", "name" ], "title": "MentalModelResponse", "description": "Response model for a mental model (stored reflect response)." }, "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 }, "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" ] }, { "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. Set to 'any' to include untagged memories alongside tagged ones during refresh." }, "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)." } }, "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 }, "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" ] }, { "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. Set to 'any' to include untagged memories alongside tagged ones during refresh." }, "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)." } }, "type": "object", "title": "MentalModelTrigger", "description": "Trigger settings for a mental model." }, "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" }, "created_at": { "type": "string", "title": "Created At" }, "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 for example, an extension may have raised DeferOperation to park the task until some backpressure window opens. Always null for completed tasks." } }, "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 (e.g. by an extension raising DeferOperation) rather than awaiting immediate pickup." }, "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." }, "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_models", "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", "status": "pending", "task_type": "retain" } ], "total": 150 } }, "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 world and experience if not specified." }, "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')" }, "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." }, "tags_match": { "type": "string", "enum": [ "any", "all", "any_strict", "all_strict" ], "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).", "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: ...}." } }, "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", "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" } }, "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" } }, "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" } }, "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": "Filter memories by tags during reflection. If not specified, all memories are considered." }, "tags_match": { "type": "string", "enum": [ "any", "all", "any_strict", "all_strict" ], "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).", "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: ...}." }, "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." }, "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 } }, "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 } }, "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" ], "title": "Match", "default": "any_strict" } }, "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." }, "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 output/completion tokens generated", "default": 0 }, "total_tokens": { "type": "integer", "title": "Total Tokens", "description": "Total tokens (input + output)", "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." }, "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 } } }, "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": { "title": "Context", "type": "object" }, "url": { "title": "URL", "type": "string" } }, "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.4.0", "features": { "bank_config_api": false, "file_upload_api": true, "mcp": true, "observations": false, "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" } }, "type": "object", "required": [ "items" ], "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." } } } }