holetron-lab/fleet-memory
1
0
Fork 0
Code Releases Packages Activity Actions
fleet-memory/hindsight-docs/static/openapi.json
Nicolò Boschi c4ef090a20
feat: support markdown in reflect and mental models (#307) 
* feat: support markdown in reflect and mental models

* chore: regenerate clients and OpenAPI spec with markdown field descriptions
2026-02-06 10:49:13 +01:00

6257 lines
No EOL
166 KiB
JSON
Raw Blame History

{
"openapi": "3.1.0",
"info": {
"title": "Hindsight HTTP API",
"description": "HTTP API for Hindsight",
"contact": {
"name": "Memory System"
},
"license": {
"name": "Apache 2.0",
"url": "https://www.apache.org/licenses/LICENSE-2.0.html"
},
"version": "0.4.9"
},
"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": "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": "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.",
"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/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}/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/{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": "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": "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}/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"
}
],
"title": "Q"
}
},
{
"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}": {
"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"
}
}
}
}
}
},
"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.",
"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": "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. 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, completed, or failed",
"title": "Status"
},
"description": "Filter by status: pending, completed, or failed"
},
{
"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": "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": "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}/profile": {
"get": {
"tags": [
"Banks"
],
"summary": "Get memory bank profile",
"description": "Get disposition traits and mission for a memory bank. Auto-creates agent with defaults if not exists.",
"operationId": "get_bank_profile",
"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",
"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}/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}/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}/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"
}
}
}
}
}
}
}
},
"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"
}
},
"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."
}
},
"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"
}
},
"type": "object",
"required": [
"bank_id",
"disposition"
],
"title": "BankListItem",
"description": "Bank list item with profile summary."
},
"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
},
"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"
},
"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
},
"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_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
}
},
"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
}
},
"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"
}
},
"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"
},
"disposition": {
"anyOf": [
{
"$ref": "#/components/schemas/DispositionTraits"
},
{
"type": "null"
}
]
},
"mission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mission",
"description": "The agent's mission"
},
"background": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Background",
"description": "Deprecated: use mission instead"
}
},
"type": "object",
"title": "CreateBankRequest",
"description": "Request model for creating/updating a bank.",
"example": {
"disposition": {
"empathy": 3,
"literalism": 3,
"skepticism": 3
},
"mission": "I am a PM helping my engineering team stay organized",
"name": "Alice"
}
},
"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"
}
},
"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"
},
"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",
"description": "Trigger settings"
}
},
"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."
},
"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"
},
"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"
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"description": "Tags associated with this document"
}
},
"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",
"id": "session_1",
"memory_unit_count": 15,
"original_text": "Full document text here...",
"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"
}
]
}
},
"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"
}
},
"type": "object",
"required": [
"observations",
"mcp",
"worker"
],
"title": "FeaturesInfo",
"description": "Feature flags indicating which capabilities are enabled."
},
"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)."
}
},
"type": "object",
"title": "IncludeOptions",
"description": "Options for including additional data in recall results."
},
"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
}
},
"MemoryItem": {
"properties": {
"content": {
"type": "string",
"title": "Content"
},
"timestamp": {
"anyOf": [
{
"type": "string",
"format": "date-time"
},
{
"type": "null"
}
],
"title": "Timestamp"
},
"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."
}
},
"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"
}
},
"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": {
"type": "string",
"title": "Source Query"
},
"content": {
"type": "string",
"title": "Content",
"description": "The mental model content as well-formatted markdown (auto-generated from reflect endpoint)"
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags"
},
"max_tokens": {
"type": "integer",
"title": "Max Tokens",
"default": 2048
},
"trigger": {
"$ref": "#/components/schemas/MentalModelTrigger"
},
"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"
}
},
"type": "object",
"required": [
"id",
"bank_id",
"name",
"source_query",
"content"
],
"title": "MentalModelResponse",
"description": "Response model for a mental model (stored reflect response)."
},
"MentalModelTrigger": {
"properties": {
"refresh_after_consolidation": {
"type": "boolean",
"title": "Refresh After Consolidation",
"description": "If true, refresh this mental model after observations consolidation (real-time mode)",
"default": false
}
},
"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"
}
},
"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,
"status": "pending",
"task_type": "retain"
}
},
"OperationStatusResponse": {
"properties": {
"operation_id": {
"type": "string",
"title": "Operation Id"
},
"status": {
"type": "string",
"enum": [
"pending",
"completed",
"failed",
"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"
}
},
"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)"
},
"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"
}
},
"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"
}
},
"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"
}
},
"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"
}
},
"ReflectBasedOn": {
"properties": {
"memories": {
"items": {
"$ref": "#/components/schemas/ReflectFact"
},
"type": "array",
"title": "Memories",
"description": "Memory facts used to generate the response"
},
"mental_models": {
"items": {
"$ref": "#/components/schemas/ReflectMentalModel"
},
"type": "array",
"title": "Mental Models",
"description": "Mental models used during reflection"
},
"directives": {
"items": {
"$ref": "#/components/schemas/ReflectDirective"
},
"type": "array",
"title": "Directives",
"description": "Directives applied during reflection"
}
},
"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"
}
},
"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"
},
"llm_calls": {
"items": {
"$ref": "#/components/schemas/ReflectLLMCall"
},
"type": "array",
"title": "Llm Calls",
"description": "LLM calls made during reflection"
}
},
"type": "object",
"title": "ReflectTrace",
"description": "Execution trace of LLM and tool calls during reflection."
},
"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": "Tags applied to all items in this request. These are merged with any item-level tags."
}
},
"type": "object",
"required": [
"items"
],
"title": "RetainRequest",
"description": "Request model for retain endpoint.",
"example": {
"async": false,
"document_tags": [
"user_a",
"user_b"
],
"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 and find this ID. Only present when async=true."
},
"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
}
}
},
"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."
},
"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"
},
{
"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
}
}
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"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": {
"mcp": true,
"observations": false,
"worker": true
}
}
}
}
}
}
View git blame Copy permalink