holetron-lab/fleet-memory
1
0
Fork 0
Code Releases Packages Activity Actions
fleet-memory/hindsight-docs/static/openapi.json
Nicolò Boschi 224b7b74c1
feat: accept pdf, images and office files (#390) 
* feat: accept pdf, images and office files

* refactor: rename FileConverter to FileParser, simplify file retain API

- Rename engine/converters/ → engine/parsers/, FileConverter → FileParser,
  ConverterRegistry → FileParserRegistry, MarkitdownConverter → MarkitdownParser
- Rename env var HINDSIGHT_API_FILE_CONVERTER → HINDSIGHT_API_FILE_PARSER
- Remove async/document_tags params from FileRetainRequest (always async now)
- Add retain_files() to Python Hindsight client and retainFiles() to TypeScript client
- Add sample.pdf to doc examples for working file upload demonstrations
- Update test_file_retain.py to use new parser names and always-async behavior
- Fix Go client missing os import in api_files.go
- Simplify postgresql.py storage to minimal schema

* fix: update rust CLI tests to use is_supported_file instead of is_text_file

* fix: patch Go api_files.go to add missing 'os' import after generation

* fix: insert 'os' import after 'net/url' in api_files.go patch for correct position

* chore: regenerate OpenAPI spec and clients (converter→parser description update)
2026-02-17 18:15:03 +01:00

6729 lines
No EOL
180 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.11"
},
"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}/config": {
"get": {
"tags": [
"Banks"
],
"summary": "Get bank configuration",
"description": "Get fully resolved configuration for a bank including all hierarchical overrides (global \u2192 tenant \u2192 bank). The 'config' field contains all resolved config values. The 'overrides' field shows only bank-specific overrides.",
"operationId": "get_bank_config",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankConfigResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Banks"
],
"summary": "Update bank configuration",
"description": "Update configuration overrides for a bank. Only hierarchical fields can be overridden (LLM settings, retention parameters, etc.). Keys can be provided in Python field format (llm_provider) or environment variable format (HINDSIGHT_API_LLM_PROVIDER).",
"operationId": "update_bank_config",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankConfigUpdate"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankConfigResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Banks"
],
"summary": "Reset bank configuration",
"description": "Reset bank configuration to defaults by removing all bank-specific overrides. The bank will then use global and tenant-level configuration only.",
"operationId": "reset_bank_config",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankConfigResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/consolidate": {
"post": {
"tags": [
"Banks"
],
"summary": "Trigger consolidation",
"description": "Run memory consolidation to create/update observations from recent memories.",
"operationId": "trigger_consolidation",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConsolidationResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/memories": {
"post": {
"tags": [
"Memory"
],
"summary": "Retain memories",
"description": "Retain memory items with automatic fact extraction.\n\nThis is the main endpoint for storing memories. It supports both synchronous and asynchronous processing via the `async` parameter.\n\n**Features:**\n- Efficient batch processing\n- Automatic fact extraction from natural language\n- Entity recognition and linking\n- Document tracking with automatic upsert (when document_id is provided)\n- Temporal and semantic linking\n- Optional asynchronous processing\n\n**The system automatically:**\n1. Extracts semantic facts from the content\n2. Generates embeddings\n3. Deduplicates similar facts\n4. Creates temporal, semantic, and entity links\n5. Tracks document metadata\n\n**When `async=true`:** Returns immediately after queuing. Use the operations endpoint to monitor progress.\n\n**When `async=false` (default):** Waits for processing to complete.\n\n**Note:** If a memory item has a `document_id` that already exists, the old document and its memory units will be deleted before creating new ones (upsert behavior).",
"operationId": "retain_memories",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetainRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetainResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Memory"
],
"summary": "Clear memory bank memories",
"description": "Delete memory units for a memory bank. Optionally filter by type (world, experience, opinion) to delete only specific types. This is a destructive operation that cannot be undone. The bank profile (disposition and background) will be preserved.",
"operationId": "clear_bank_memories",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional fact type filter (world, experience, opinion)",
"title": "Type"
},
"description": "Optional fact type filter (world, experience, opinion)"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/files/retain": {
"post": {
"tags": [
"Files"
],
"summary": "Convert files to memories",
"description": "Upload files (PDF, DOCX, etc.), convert them to markdown, and retain as memories.\n\nThis endpoint handles file upload, conversion, and memory creation in a single operation.\n\n**Features:**\n- Supports PDF, DOCX, PPTX, XLSX, images (with OCR), audio (with transcription)\n- Automatic file-to-markdown conversion using pluggable parsers\n- Files stored in object storage (PostgreSQL by default, S3 for production)\n- Each file becomes a separate document with optional metadata/tags\n- Always processes asynchronously \u2014 returns operation IDs immediately\n\n**The system automatically:**\n1. Stores uploaded files in object storage\n2. Converts files to markdown\n3. Creates document records with file metadata\n4. Extracts facts and creates memory units (same as regular retain)\n\nUse the operations endpoint to monitor progress.\n\n**Request format:** multipart/form-data with:\n- `files`: One or more files to upload\n- `request`: JSON string with FileRetainRequest model (files_metadata)\n\n**Note:** File parser is configured server-side via `HINDSIGHT_API_FILE_PARSER` (default: markitdown).",
"operationId": "file_retain",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_file_retain"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileRetainResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
}
},
"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."
}
},
"BankConfigResponse": {
"properties": {
"bank_id": {
"type": "string",
"title": "Bank Id",
"description": "Bank identifier"
},
"config": {
"additionalProperties": true,
"type": "object",
"title": "Config",
"description": "Fully resolved configuration with all hierarchical overrides applied (Python field names)"
},
"overrides": {
"additionalProperties": true,
"type": "object",
"title": "Overrides",
"description": "Bank-specific configuration overrides only (Python field names)"
}
},
"type": "object",
"required": [
"bank_id",
"config",
"overrides"
],
"title": "BankConfigResponse",
"description": "Response model for bank configuration.",
"example": {
"bank_id": "my-bank",
"config": {
"llm_model": "gpt-4",
"llm_provider": "openai",
"retain_extraction_mode": "verbose"
},
"overrides": {
"llm_model": "gpt-4",
"retain_extraction_mode": "verbose"
}
}
},
"BankConfigUpdate": {
"properties": {
"updates": {
"additionalProperties": true,
"type": "object",
"title": "Updates",
"description": "Configuration overrides. Keys can be in Python field format (llm_provider) or environment variable format (HINDSIGHT_API_LLM_PROVIDER). Only hierarchical fields can be overridden per-bank."
}
},
"type": "object",
"required": [
"updates"
],
"title": "BankConfigUpdate",
"description": "Request model for updating bank configuration.",
"example": {
"updates": {
"llm_model": "claude-sonnet-4-5",
"retain_custom_instructions": "Extract technical details carefully",
"retain_extraction_mode": "verbose"
}
}
},
"BankListItem": {
"properties": {
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name"
},
"disposition": {
"$ref": "#/components/schemas/DispositionTraits"
},
"mission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mission"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"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
}
},
"Body_file_retain": {
"properties": {
"files": {
"items": {
"type": "string",
"format": "binary"
},
"type": "array",
"title": "Files",
"description": "Files to upload and convert"
},
"request": {
"type": "string",
"title": "Request",
"description": "JSON string with FileRetainRequest model"
}
},
"type": "object",
"required": [
"files",
"request"
],
"title": "Body_file_retain"
},
"Budget": {
"type": "string",
"enum": [
"low",
"mid",
"high"
],
"title": "Budget",
"description": "Budget levels for recall/reflect operations."
},
"CancelOperationResponse": {
"properties": {
"success": {
"type": "boolean",
"title": "Success"
},
"message": {
"type": "string",
"title": "Message"
},
"operation_id": {
"type": "string",
"title": "Operation Id"
}
},
"type": "object",
"required": [
"success",
"message",
"operation_id"
],
"title": "CancelOperationResponse",
"description": "Response model for cancel operation endpoint.",
"example": {
"message": "Operation 550e8400-e29b-41d4-a716-446655440000 cancelled",
"operation_id": "550e8400-e29b-41d4-a716-446655440000",
"success": true
}
},
"ChildOperationStatus": {
"properties": {
"operation_id": {
"type": "string",
"title": "Operation Id"
},
"status": {
"type": "string",
"title": "Status"
},
"sub_batch_index": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Sub Batch Index"
},
"items_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Items Count"
},
"error_message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Error Message"
}
},
"type": "object",
"required": [
"operation_id",
"status"
],
"title": "ChildOperationStatus",
"description": "Status of a child operation (for batch operations)."
},
"ChunkData": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"text": {
"type": "string",
"title": "Text"
},
"chunk_index": {
"type": "integer",
"title": "Chunk Index"
},
"truncated": {
"type": "boolean",
"title": "Truncated",
"description": "Whether the chunk text was truncated due to token limits",
"default": false
}
},
"type": "object",
"required": [
"id",
"text",
"chunk_index"
],
"title": "ChunkData",
"description": "Chunk data for a single chunk."
},
"ChunkIncludeOptions": {
"properties": {
"max_tokens": {
"type": "integer",
"title": "Max Tokens",
"description": "Maximum tokens for chunks (chunks may be truncated)",
"default": 8192
}
},
"type": "object",
"title": "ChunkIncludeOptions",
"description": "Options for including chunks in recall results."
},
"ChunkResponse": {
"properties": {
"chunk_id": {
"type": "string",
"title": "Chunk Id"
},
"document_id": {
"type": "string",
"title": "Document Id"
},
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"chunk_index": {
"type": "integer",
"title": "Chunk Index"
},
"chunk_text": {
"type": "string",
"title": "Chunk Text"
},
"created_at": {
"type": "string",
"title": "Created At"
}
},
"type": "object",
"required": [
"chunk_id",
"document_id",
"bank_id",
"chunk_index",
"chunk_text",
"created_at"
],
"title": "ChunkResponse",
"description": "Response model for get chunk endpoint.",
"example": {
"bank_id": "user123",
"chunk_id": "user123_session_1_0",
"chunk_index": 0,
"chunk_text": "This is the first chunk of the document...",
"created_at": "2024-01-15T10:30:00Z",
"document_id": "session_1"
}
},
"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",
"default": []
}
},
"type": "object",
"required": [
"name",
"content"
],
"title": "CreateDirectiveRequest",
"description": "Request model for creating a directive."
},
"CreateMentalModelRequest": {
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id",
"description": "Optional custom ID for the mental model (alphanumeric lowercase with hyphens)"
},
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable name for the mental model"
},
"source_query": {
"type": "string",
"title": "Source Query",
"description": "The query to run to generate content"
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"description": "Tags for scoped visibility",
"default": []
},
"max_tokens": {
"type": "integer",
"maximum": 8192.0,
"minimum": 256.0,
"title": "Max Tokens",
"description": "Maximum tokens for generated content",
"default": 2048
},
"trigger": {
"$ref": "#/components/schemas/MentalModelTrigger",
"description": "Trigger settings",
"default": {}
}
},
"type": "object",
"required": [
"name",
"source_query"
],
"title": "CreateMentalModelRequest",
"description": "Request model for creating a mental model.",
"example": {
"id": "team-communication",
"max_tokens": 2048,
"name": "Team Communication Preferences",
"source_query": "How does the team prefer to communicate?",
"tags": [
"team"
],
"trigger": {
"refresh_after_consolidation": false
}
}
},
"CreateMentalModelResponse": {
"properties": {
"mental_model_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mental Model Id",
"description": "ID of the created mental model"
},
"operation_id": {
"type": "string",
"title": "Operation Id",
"description": "Operation ID to track refresh progress"
}
},
"type": "object",
"required": [
"operation_id"
],
"title": "CreateMentalModelResponse",
"description": "Response model for mental model creation."
},
"DeleteDocumentResponse": {
"properties": {
"success": {
"type": "boolean",
"title": "Success"
},
"message": {
"type": "string",
"title": "Message"
},
"document_id": {
"type": "string",
"title": "Document Id"
},
"memory_units_deleted": {
"type": "integer",
"title": "Memory Units Deleted"
}
},
"type": "object",
"required": [
"success",
"message",
"document_id",
"memory_units_deleted"
],
"title": "DeleteDocumentResponse",
"description": "Response model for delete document endpoint.",
"example": {
"document_id": "session_1",
"memory_units_deleted": 5,
"message": "Document 'session_1' and 5 associated memory units deleted successfully",
"success": true
}
},
"DeleteResponse": {
"properties": {
"success": {
"type": "boolean",
"title": "Success"
},
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Message"
},
"deleted_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Deleted Count"
}
},
"type": "object",
"required": [
"success"
],
"title": "DeleteResponse",
"description": "Response model for delete operations.",
"example": {
"deleted_count": 10,
"message": "Deleted successfully",
"success": true
}
},
"DirectiveListResponse": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/DirectiveResponse"
},
"type": "array",
"title": "Items"
}
},
"type": "object",
"required": [
"items"
],
"title": "DirectiveListResponse",
"description": "Response model for listing directives."
},
"DirectiveResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"name": {
"type": "string",
"title": "Name"
},
"content": {
"type": "string",
"title": "Content"
},
"priority": {
"type": "integer",
"title": "Priority",
"default": 0
},
"is_active": {
"type": "boolean",
"title": "Is Active",
"default": true
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"default": []
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"bank_id",
"name",
"content"
],
"title": "DirectiveResponse",
"description": "Response model for a directive."
},
"DispositionTraits": {
"properties": {
"skepticism": {
"type": "integer",
"maximum": 5.0,
"minimum": 1.0,
"title": "Skepticism",
"description": "How skeptical vs trusting (1=trusting, 5=skeptical)"
},
"literalism": {
"type": "integer",
"maximum": 5.0,
"minimum": 1.0,
"title": "Literalism",
"description": "How literally to interpret information (1=flexible, 5=literal)"
},
"empathy": {
"type": "integer",
"maximum": 5.0,
"minimum": 1.0,
"title": "Empathy",
"description": "How much to consider emotional context (1=detached, 5=empathetic)"
}
},
"type": "object",
"required": [
"skepticism",
"literalism",
"empathy"
],
"title": "DispositionTraits",
"description": "Disposition traits that influence how memories are formed and interpreted.",
"example": {
"empathy": 3,
"literalism": 3,
"skepticism": 3
}
},
"DocumentResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"original_text": {
"type": "string",
"title": "Original Text"
},
"content_hash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content Hash"
},
"created_at": {
"type": "string",
"title": "Created At"
},
"updated_at": {
"type": "string",
"title": "Updated At"
},
"memory_unit_count": {
"type": "integer",
"title": "Memory Unit Count"
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"description": "Tags associated with this document",
"default": []
}
},
"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"
},
"bank_config_api": {
"type": "boolean",
"title": "Bank Config Api",
"description": "Whether per-bank configuration API is enabled"
},
"file_upload_api": {
"type": "boolean",
"title": "File Upload Api",
"description": "Whether file upload/conversion API is enabled"
}
},
"type": "object",
"required": [
"observations",
"mcp",
"worker",
"bank_config_api",
"file_upload_api"
],
"title": "FeaturesInfo",
"description": "Feature flags indicating which capabilities are enabled."
},
"FileRetainResponse": {
"properties": {
"operation_ids": {
"items": {
"type": "string"
},
"type": "array",
"title": "Operation Ids",
"description": "Operation IDs for tracking file conversion operations. Use GET /v1/default/banks/{bank_id}/operations to list operations."
}
},
"type": "object",
"required": [
"operation_ids"
],
"title": "FileRetainResponse",
"description": "Response model for file upload endpoint.",
"example": {
"operation_ids": [
"550e8400-e29b-41d4-a716-446655440000",
"550e8400-e29b-41d4-a716-446655440001",
"550e8400-e29b-41d4-a716-446655440002"
]
}
},
"GraphDataResponse": {
"properties": {
"nodes": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Nodes"
},
"edges": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Edges"
},
"table_rows": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array",
"title": "Table Rows"
},
"total_units": {
"type": "integer",
"title": "Total Units"
},
"limit": {
"type": "integer",
"title": "Limit"
}
},
"type": "object",
"required": [
"nodes",
"edges",
"table_rows",
"total_units",
"limit"
],
"title": "GraphDataResponse",
"description": "Response model for graph data endpoint.",
"example": {
"edges": [
{
"from": "1",
"to": "2",
"type": "semantic",
"weight": 0.8
}
],
"limit": 1000,
"nodes": [
{
"id": "1",
"label": "Alice works at Google",
"type": "world"
},
{
"id": "2",
"label": "Bob went hiking",
"type": "world"
}
],
"table_rows": [
{
"context": "Work info",
"date": "2024-01-15 10:30",
"entities": "Alice (PERSON), Google (ORGANIZATION)",
"id": "abc12345...",
"text": "Alice works at Google"
}
],
"total_units": 2
}
},
"HTTPValidationError": {
"properties": {
"detail": {
"items": {
"$ref": "#/components/schemas/ValidationError"
},
"type": "array",
"title": "Detail"
}
},
"type": "object",
"title": "HTTPValidationError"
},
"IncludeOptions": {
"properties": {
"entities": {
"anyOf": [
{
"$ref": "#/components/schemas/EntityIncludeOptions"
},
{
"type": "null"
}
],
"description": "Include entity observations. Set to null to disable entity inclusion.",
"default": {
"max_tokens": 500
}
},
"chunks": {
"anyOf": [
{
"$ref": "#/components/schemas/ChunkIncludeOptions"
},
{
"type": "null"
}
],
"description": "Include raw chunks. Set to {} to enable, null to disable (default: disabled)."
}
},
"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",
"default": []
},
"max_tokens": {
"type": "integer",
"title": "Max Tokens",
"default": 2048
},
"trigger": {
"$ref": "#/components/schemas/MentalModelTrigger",
"default": {}
},
"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"
},
"result_metadata": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Result Metadata",
"description": "Internal metadata for debugging. Structure may change without notice. Not for production use."
},
"child_operations": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/ChildOperationStatus"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Child Operations",
"description": "Child operations for batch operations (if applicable)"
}
},
"type": "object",
"required": [
"operation_id",
"status"
],
"title": "OperationStatusResponse",
"description": "Response model for getting a single operation status.",
"example": {
"completed_at": "2024-01-15T10:31:30Z",
"created_at": "2024-01-15T10:30:00Z",
"operation_id": "550e8400-e29b-41d4-a716-446655440000",
"operation_type": "refresh_mental_models",
"status": "completed",
"updated_at": "2024-01-15T10:31:30Z"
}
},
"OperationsListResponse": {
"properties": {
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"total": {
"type": "integer",
"title": "Total"
},
"limit": {
"type": "integer",
"title": "Limit"
},
"offset": {
"type": "integer",
"title": "Offset"
},
"operations": {
"items": {
"$ref": "#/components/schemas/OperationResponse"
},
"type": "array",
"title": "Operations"
}
},
"type": "object",
"required": [
"bank_id",
"total",
"limit",
"offset",
"operations"
],
"title": "OperationsListResponse",
"description": "Response model for list operations endpoint.",
"example": {
"bank_id": "user123",
"limit": 20,
"offset": 0,
"operations": [
{
"created_at": "2024-01-15T10:30:00Z",
"id": "550e8400-e29b-41d4-a716-446655440000",
"status": "pending",
"task_type": "retain"
}
],
"total": 150
}
},
"RecallRequest": {
"properties": {
"query": {
"type": "string",
"title": "Query"
},
"types": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Types",
"description": "List of fact types to recall: 'world', 'experience', 'observation'. Defaults to world and experience if not specified."
},
"budget": {
"$ref": "#/components/schemas/Budget",
"default": "mid"
},
"max_tokens": {
"type": "integer",
"title": "Max Tokens",
"default": 4096
},
"trace": {
"type": "boolean",
"title": "Trace",
"default": false
},
"query_timestamp": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Query Timestamp",
"description": "ISO format date string (e.g., '2023-05-30T23:40:00')"
},
"include": {
"$ref": "#/components/schemas/IncludeOptions",
"description": "Options for including additional data (entities are included by default)",
"default": {}
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags",
"description": "Filter memories by tags. If not specified, all memories are returned."
},
"tags_match": {
"type": "string",
"enum": [
"any",
"all",
"any_strict",
"all_strict"
],
"title": "Tags Match",
"description": "How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged).",
"default": "any"
}
},
"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",
"default": []
},
"mental_models": {
"items": {
"$ref": "#/components/schemas/ReflectMentalModel"
},
"type": "array",
"title": "Mental Models",
"description": "Mental models used during reflection",
"default": []
},
"directives": {
"items": {
"$ref": "#/components/schemas/ReflectDirective"
},
"type": "array",
"title": "Directives",
"description": "Directives applied during reflection",
"default": []
}
},
"type": "object",
"title": "ReflectBasedOn",
"description": "Evidence the response is based on: memories, mental models, and directives."
},
"ReflectDirective": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Directive ID"
},
"name": {
"type": "string",
"title": "Name",
"description": "Directive name"
},
"content": {
"type": "string",
"title": "Content",
"description": "Directive content"
}
},
"type": "object",
"required": [
"id",
"name",
"content"
],
"title": "ReflectDirective",
"description": "A directive applied during reflect."
},
"ReflectFact": {
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id"
},
"text": {
"type": "string",
"title": "Text",
"description": "Fact text. When type='observation', this contains markdown-formatted consolidated knowledge"
},
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Type"
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Context"
},
"occurred_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Occurred Start"
},
"occurred_end": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Occurred End"
}
},
"type": "object",
"required": [
"text"
],
"title": "ReflectFact",
"description": "A fact used in think response.",
"example": {
"context": "healthcare discussion",
"id": "123e4567-e89b-12d3-a456-426614174000",
"occurred_end": "2024-01-15T10:30:00Z",
"occurred_start": "2024-01-15T10:30:00Z",
"text": "AI is used in healthcare",
"type": "world"
}
},
"ReflectIncludeOptions": {
"properties": {
"facts": {
"anyOf": [
{
"$ref": "#/components/schemas/FactsIncludeOptions"
},
{
"type": "null"
}
],
"description": "Include facts that the answer is based on. Set to {} to enable, null to disable (default: disabled)."
},
"tool_calls": {
"anyOf": [
{
"$ref": "#/components/schemas/ToolCallsIncludeOptions"
},
{
"type": "null"
}
],
"description": "Include tool calls trace. Set to {} for full trace (input+output), {output: false} for inputs only."
}
},
"type": "object",
"title": "ReflectIncludeOptions",
"description": "Options for including additional data in reflect results."
},
"ReflectLLMCall": {
"properties": {
"scope": {
"type": "string",
"title": "Scope",
"description": "Call scope: agent_1, agent_2, final, etc."
},
"duration_ms": {
"type": "integer",
"title": "Duration Ms",
"description": "Execution time in milliseconds"
}
},
"type": "object",
"required": [
"scope",
"duration_ms"
],
"title": "ReflectLLMCall",
"description": "An LLM call made during reflect agent execution."
},
"ReflectMentalModel": {
"properties": {
"id": {
"type": "string",
"title": "Id",
"description": "Mental model ID"
},
"text": {
"type": "string",
"title": "Text",
"description": "Mental model content"
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Context",
"description": "Additional context"
}
},
"type": "object",
"required": [
"id",
"text"
],
"title": "ReflectMentalModel",
"description": "A mental model used during reflect."
},
"ReflectRequest": {
"properties": {
"query": {
"type": "string",
"title": "Query"
},
"budget": {
"$ref": "#/components/schemas/Budget",
"default": "low"
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Context",
"description": "DEPRECATED: Additional context is now concatenated with the query. Pass context directly in the query field instead. If provided, it will be appended to the query for backward compatibility.",
"deprecated": true
},
"max_tokens": {
"type": "integer",
"title": "Max Tokens",
"description": "Maximum tokens for the response",
"default": 4096
},
"include": {
"$ref": "#/components/schemas/ReflectIncludeOptions",
"description": "Options for including additional data (disabled by default)"
},
"response_schema": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Response Schema",
"description": "Optional JSON Schema for structured output. When provided, the response will include a 'structured_output' field with the LLM response parsed according to this schema."
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags",
"description": "Filter memories by tags during reflection. If not specified, all memories are considered."
},
"tags_match": {
"type": "string",
"enum": [
"any",
"all",
"any_strict",
"all_strict"
],
"title": "Tags Match",
"description": "How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged).",
"default": "any"
}
},
"type": "object",
"required": [
"query"
],
"title": "ReflectRequest",
"description": "Request model for reflect endpoint.",
"example": {
"budget": "low",
"include": {
"facts": {}
},
"max_tokens": 4096,
"query": "What do you think about artificial intelligence?",
"response_schema": {
"properties": {
"summary": {
"type": "string"
},
"key_points": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"summary",
"key_points"
],
"type": "object"
},
"tags": [
"user_a"
],
"tags_match": "any"
}
},
"ReflectResponse": {
"properties": {
"text": {
"type": "string",
"title": "Text",
"description": "The reflect response as well-formatted markdown (headers, lists, bold/italic, code blocks, etc.)"
},
"based_on": {
"anyOf": [
{
"$ref": "#/components/schemas/ReflectBasedOn"
},
{
"type": "null"
}
],
"description": "Evidence used to generate the response. Only present when include.facts is set."
},
"structured_output": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Structured Output",
"description": "Structured output parsed according to the request's response_schema. Only present when response_schema was provided in the request."
},
"usage": {
"anyOf": [
{
"$ref": "#/components/schemas/TokenUsage"
},
{
"type": "null"
}
],
"description": "Token usage metrics for LLM calls during reflection."
},
"trace": {
"anyOf": [
{
"$ref": "#/components/schemas/ReflectTrace"
},
{
"type": "null"
}
],
"description": "Execution trace of tool and LLM calls. Only present when include.tool_calls is set."
}
},
"type": "object",
"required": [
"text"
],
"title": "ReflectResponse",
"description": "Response model for think endpoint.",
"example": {
"based_on": {
"memories": [
{
"id": "123",
"text": "AI is used in healthcare",
"type": "world"
},
{
"id": "456",
"text": "I discussed AI applications last week",
"type": "experience"
}
]
},
"structured_output": {
"key_points": [
"Used in healthcare",
"Discussed recently"
],
"summary": "AI is transformative"
},
"text": "## AI Overview\n\nBased on my understanding, AI is a **transformative technology**:\n\n- Used extensively in healthcare\n- Discussed in recent conversations\n- Continues to evolve rapidly",
"trace": {
"llm_calls": [
{
"duration_ms": 1200,
"scope": "agent_1"
}
],
"observations": [
{
"id": "obs-1",
"name": "AI Technology",
"subtype": "structural",
"type": "concept"
}
],
"tool_calls": [
{
"duration_ms": 150,
"input": {
"query": "AI"
},
"tool": "recall"
}
]
},
"usage": {
"input_tokens": 1500,
"output_tokens": 500,
"total_tokens": 2000
}
}
},
"ReflectToolCall": {
"properties": {
"tool": {
"type": "string",
"title": "Tool",
"description": "Tool name: lookup, recall, learn, expand"
},
"input": {
"additionalProperties": true,
"type": "object",
"title": "Input",
"description": "Tool input parameters"
},
"output": {
"anyOf": [
{
"additionalProperties": true,
"type": "object"
},
{
"type": "null"
}
],
"title": "Output",
"description": "Tool output (only included when include.tool_calls.output is true)"
},
"duration_ms": {
"type": "integer",
"title": "Duration Ms",
"description": "Execution time in milliseconds"
},
"iteration": {
"type": "integer",
"title": "Iteration",
"description": "Iteration number (1-based) when this tool was called",
"default": 0
}
},
"type": "object",
"required": [
"tool",
"input",
"duration_ms"
],
"title": "ReflectToolCall",
"description": "A tool call made during reflect agent execution."
},
"ReflectTrace": {
"properties": {
"tool_calls": {
"items": {
"$ref": "#/components/schemas/ReflectToolCall"
},
"type": "array",
"title": "Tool Calls",
"description": "Tool calls made during reflection",
"default": []
},
"llm_calls": {
"items": {
"$ref": "#/components/schemas/ReflectLLMCall"
},
"type": "array",
"title": "Llm Calls",
"description": "LLM calls made during reflection",
"default": []
}
},
"type": "object",
"title": "ReflectTrace",
"description": "Execution trace of LLM and tool calls during reflection."
},
"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. 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": {
"bank_config_api": false,
"file_upload_api": true,
"mcp": true,
"observations": false,
"worker": true
}
}
}
}
}
}
View git blame Copy permalink