holetron-lab/fleet-memory
1
0
Fork 0
Code Releases Packages Activity Actions
fleet-memory/hindsight-docs/static/openapi.json
Nicolò Boschi e2baca8bfe
feat: mental model history tracking and UI diff view (#516) 
* feat: mental model refresh history tracking and UI diff view

- DB migration: add history JSONB column to mental_models table
- Track previous content on each refresh in update_mental_model
- Add get_mental_model_history() engine method
- New GET /mental-models/{id}/history endpoint
- Control plane proxy route and getMentalModelHistory() in api.ts
- MentalModelDetailModal: add History tab with lazy loading, carousel
  navigation (left=older, right=newer), word-level content diff view

* fix: resolve alembic migration head conflict for mental model history

* feat: mental model history tracking, side-by-side diff UI, and config flag

- Track content changes on every mental model update/refresh (persisted in JSONB history column)
- New GET /mental-models/{id}/history endpoint returning changes most-recent-first
- Side-by-side diff view in History tab (Before/After columns, line-level highlights)
- Actions dropdown in detail panel (Edit, Refresh, View History, Delete)
- HINDSIGHT_API_ENABLE_MENTAL_MODEL_HISTORY config flag (default: true)
- Also adds missing HINDSIGHT_API_ENABLE_OBSERVATION_HISTORY to configuration docs
- Python client wrapper method get_mental_model_history()
- Tests for history persistence (recorded, ordered, name-only skipped, missing returns None)
- Fix NameError: timezone not imported in update_mental_model

* fix: call get_mental_model_history before delete in doc example
2026-03-06 17:50:48 +01:00

8007 lines
No EOL
215 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.16"
},
"paths": {
"/health": {
"get": {
"tags": [
"Monitoring"
],
"summary": "Health check endpoint",
"description": "Checks the health of the API and database connection",
"operationId": "health_endpoint_health_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
},
"/version": {
"get": {
"tags": [
"Monitoring"
],
"summary": "Get API version and feature flags",
"description": "Returns API version information and enabled feature flags. Use this to check which capabilities are available in this deployment.",
"operationId": "get_version",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/VersionResponse"
}
}
}
}
}
}
},
"/metrics": {
"get": {
"tags": [
"Monitoring"
],
"summary": "Prometheus metrics endpoint",
"description": "Exports metrics in Prometheus format for scraping",
"operationId": "metrics_endpoint_metrics_get",
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/graph": {
"get": {
"tags": [
"Memory"
],
"summary": "Get memory graph data",
"description": "Retrieve graph data for visualization, optionally filtered by type (world/experience/opinion).",
"operationId": "get_graph",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Type"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 1000,
"title": "Limit"
}
},
{
"name": "q",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Q"
}
},
{
"name": "tags",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"title": "Tags"
}
},
{
"name": "tags_match",
"in": "query",
"required": false,
"schema": {
"type": "string",
"default": "all_strict",
"title": "Tags Match"
}
},
{
"name": "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. Note: the 'history' field is deprecated and always returns an empty list - use GET /memories/{memory_id}/history instead.",
"operationId": "get_memory",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "memory_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Memory Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/memories/{memory_id}/history": {
"get": {
"tags": [
"Memory"
],
"summary": "Get observation history",
"description": "Get the full history of an observation, with each change's source facts resolved to their text.",
"operationId": "get_observation_history",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "memory_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Memory Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/memories/recall": {
"post": {
"tags": [
"Memory"
],
"summary": "Recall memory",
"description": "Recall memory using semantic similarity and spreading activation.\n\nThe type parameter is optional and must be one of:\n- `world`: General knowledge about people, places, events, and things that happen\n- `experience`: Memories about experience, conversations, actions taken, and tasks performed",
"operationId": "recall_memories",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecallRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RecallResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/reflect": {
"post": {
"tags": [
"Memory"
],
"summary": "Reflect and generate answer",
"description": "Reflect and formulate an answer using bank identity, world facts, and opinions.\n\nThis endpoint:\n1. Retrieves experience (conversations and events)\n2. Retrieves world facts relevant to the query\n3. Retrieves existing opinions (bank's perspectives)\n4. Uses LLM to formulate a contextual answer\n5. Returns plain text answer and the facts used",
"operationId": "reflect",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReflectRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ReflectResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks": {
"get": {
"tags": [
"Banks"
],
"summary": "List all memory banks",
"description": "Get a list of all agents with their profiles",
"operationId": "list_banks",
"parameters": [
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankListResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/stats": {
"get": {
"tags": [
"Banks"
],
"summary": "Get statistics for memory bank",
"description": "Get statistics about nodes and links for a specific agent",
"operationId": "get_agent_stats",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankStatsResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/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}/history": {
"get": {
"tags": [
"Mental Models"
],
"summary": "Get mental model history",
"description": "Get the refresh history of a mental model, showing content changes over time.",
"operationId": "get_mental_model_history",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "mental_model_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Mental Model Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/mental-models/{mental_model_id}/refresh": {
"post": {
"tags": [
"Mental Models"
],
"summary": "Refresh mental model",
"description": "Submit an async task to re-run the source query through reflect and update the content.",
"operationId": "refresh_mental_model",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "mental_model_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Mental Model Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AsyncOperationSubmitResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/directives": {
"get": {
"tags": [
"Directives"
],
"summary": "List directives",
"description": "List hard rules that are injected into prompts.",
"operationId": "list_directives",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "tags",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Filter by tags",
"title": "Tags"
},
"description": "Filter by tags"
},
{
"name": "tags_match",
"in": "query",
"required": false,
"schema": {
"enum": [
"any",
"all",
"exact"
],
"type": "string",
"description": "How to match tags",
"default": "any",
"title": "Tags Match"
},
"description": "How to match tags"
},
{
"name": "active_only",
"in": "query",
"required": false,
"schema": {
"type": "boolean",
"description": "Only return active directives",
"default": true,
"title": "Active Only"
},
"description": "Only return active directives"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 1000,
"minimum": 1,
"default": 100,
"title": "Limit"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"minimum": 0,
"default": 0,
"title": "Offset"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DirectiveListResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"post": {
"tags": [
"Directives"
],
"summary": "Create directive",
"description": "Create a hard rule that will be injected into prompts.",
"operationId": "create_directive",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateDirectiveRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DirectiveResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/directives/{directive_id}": {
"get": {
"tags": [
"Directives"
],
"summary": "Get directive",
"description": "Get a specific directive by ID.",
"operationId": "get_directive",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "directive_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Directive Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DirectiveResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Directives"
],
"summary": "Update directive",
"description": "Update a directive's properties.",
"operationId": "update_directive",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "directive_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Directive Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDirectiveRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DirectiveResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Directives"
],
"summary": "Delete directive",
"description": "Delete a directive.",
"operationId": "delete_directive",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "directive_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Directive Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/documents": {
"get": {
"tags": [
"Documents"
],
"summary": "List documents",
"description": "List documents with pagination and optional search. Documents are the source content from which memory units are extracted.",
"operationId": "list_documents",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "q",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Case-insensitive substring filter on document ID (e.g. 'report' matches 'report-2024')",
"title": "Q"
},
"description": "Case-insensitive substring filter on document ID (e.g. 'report' matches 'report-2024')"
},
{
"name": "tags",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "null"
}
],
"description": "Filter documents by tags",
"title": "Tags"
},
"description": "Filter documents by tags"
},
{
"name": "tags_match",
"in": "query",
"required": false,
"schema": {
"type": "string",
"description": "How to match tags: 'any', 'all', 'any_strict', 'all_strict'",
"default": "any_strict",
"title": "Tags Match"
},
"description": "How to match tags: 'any', 'all', 'any_strict', 'all_strict'"
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 100,
"title": "Limit"
}
},
{
"name": "offset",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"default": 0,
"title": "Offset"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ListDocumentsResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/documents/{document_id}": {
"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",
"deprecated": true,
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankProfileResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"put": {
"tags": [
"Banks"
],
"summary": "Update memory bank disposition",
"description": "Update bank's disposition traits (skepticism, literalism, empathy)",
"operationId": "update_bank_disposition",
"deprecated": true,
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateDispositionRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankProfileResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/background": {
"post": {
"tags": [
"Banks"
],
"summary": "Add/merge memory bank background (deprecated)",
"description": "Deprecated: Use PUT /mission instead. This endpoint now updates the mission field.",
"operationId": "add_bank_background",
"deprecated": true,
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AddBackgroundRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BackgroundResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}": {
"put": {
"tags": [
"Banks"
],
"summary": "Create or update memory bank",
"description": "Create a new agent or update existing agent with disposition and mission. Auto-fills missing fields with defaults.",
"operationId": "create_or_update_bank",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateBankRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankProfileResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Banks"
],
"summary": "Partial update memory bank",
"description": "Partially update an agent's profile. Only provided fields will be updated.",
"operationId": "update_bank",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateBankRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankProfileResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Banks"
],
"summary": "Delete memory bank",
"description": "Delete an entire memory bank including all memories, entities, documents, and the bank profile itself. This is a destructive operation that cannot be undone.",
"operationId": "delete_bank",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/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}/memories/{memory_id}/observations": {
"delete": {
"tags": [
"Memory"
],
"summary": "Clear observations for a memory",
"description": "Delete all observations derived from a specific memory and reset it for re-consolidation. The memory itself is not deleted. A consolidation job is triggered automatically so the memory will produce fresh observations on the next consolidation run.",
"operationId": "clear_memory_observations",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "memory_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Memory Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ClearMemoryObservationsResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/config": {
"get": {
"tags": [
"Banks"
],
"summary": "Get bank configuration",
"description": "Get fully resolved configuration for a bank including all hierarchical overrides (global \u2192 tenant \u2192 bank). The 'config' field contains all resolved config values. The 'overrides' field shows only bank-specific overrides.",
"operationId": "get_bank_config",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankConfigResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Banks"
],
"summary": "Update bank configuration",
"description": "Update configuration overrides for a bank. Only hierarchical fields can be overridden (LLM settings, retention parameters, etc.). Keys can be provided in Python field format (llm_provider) or environment variable format (HINDSIGHT_API_LLM_PROVIDER).",
"operationId": "update_bank_config",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankConfigUpdate"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankConfigResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Banks"
],
"summary": "Reset bank configuration",
"description": "Reset bank configuration to defaults by removing all bank-specific overrides. The bank will then use global and tenant-level configuration only.",
"operationId": "reset_bank_config",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/BankConfigResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/consolidate": {
"post": {
"tags": [
"Banks"
],
"summary": "Trigger consolidation",
"description": "Run memory consolidation to create/update observations from recent memories.",
"operationId": "trigger_consolidation",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ConsolidationResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/webhooks": {
"post": {
"tags": [
"Webhooks"
],
"summary": "Register webhook",
"description": "Register a webhook endpoint to receive event notifications for this bank.",
"operationId": "create_webhook",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CreateWebhookRequest"
}
}
}
},
"responses": {
"201": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"get": {
"tags": [
"Webhooks"
],
"summary": "List webhooks",
"description": "List all webhooks registered for a bank.",
"operationId": "list_webhooks",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookListResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/webhooks/{webhook_id}": {
"delete": {
"tags": [
"Webhooks"
],
"summary": "Delete webhook",
"description": "Remove a registered webhook.",
"operationId": "delete_webhook",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "webhook_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Webhook Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"patch": {
"tags": [
"Webhooks"
],
"summary": "Update webhook",
"description": "Update one or more fields of a registered webhook. Only provided fields are changed.",
"operationId": "update_webhook",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "webhook_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Webhook Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/UpdateWebhookRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/webhooks/{webhook_id}/deliveries": {
"get": {
"tags": [
"Webhooks"
],
"summary": "List webhook deliveries",
"description": "Inspect delivery history for a webhook (useful for debugging).",
"operationId": "list_webhook_deliveries",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "webhook_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Webhook Id"
}
},
{
"name": "limit",
"in": "query",
"required": false,
"schema": {
"type": "integer",
"maximum": 200,
"description": "Maximum number of deliveries to return",
"default": 50,
"title": "Limit"
},
"description": "Maximum number of deliveries to return"
},
{
"name": "cursor",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Pagination cursor (created_at of last item)",
"title": "Cursor"
},
"description": "Pagination cursor (created_at of last item)"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/WebhookDeliveryListResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/memories": {
"post": {
"tags": [
"Memory"
],
"summary": "Retain memories",
"description": "Retain memory items with automatic fact extraction.\n\nThis is the main endpoint for storing memories. It supports both synchronous and asynchronous processing via the `async` parameter.\n\n**Features:**\n- Efficient batch processing\n- Automatic fact extraction from natural language\n- Entity recognition and linking\n- Document tracking with automatic upsert (when document_id is provided)\n- Temporal and semantic linking\n- Optional asynchronous processing\n\n**The system automatically:**\n1. Extracts semantic facts from the content\n2. Generates embeddings\n3. Deduplicates similar facts\n4. Creates temporal, semantic, and entity links\n5. Tracks document metadata\n\n**When `async=true`:** Returns immediately after queuing. Use the operations endpoint to monitor progress.\n\n**When `async=false` (default):** Waits for processing to complete.\n\n**Note:** If a memory item has a `document_id` that already exists, the old document and its memory units will be deleted before creating new ones (upsert behavior).",
"operationId": "retain_memories",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetainRequest"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/RetainResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
},
"delete": {
"tags": [
"Memory"
],
"summary": "Clear memory bank memories",
"description": "Delete memory units for a memory bank. Optionally filter by type (world, experience, opinion) to delete only specific types. This is a destructive operation that cannot be undone. The bank profile (disposition and background) will be preserved.",
"operationId": "clear_bank_memories",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "type",
"in": "query",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"description": "Optional fact type filter (world, experience, opinion)",
"title": "Type"
},
"description": "Optional fact type filter (world, experience, opinion)"
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/DeleteResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
},
"/v1/default/banks/{bank_id}/files/retain": {
"post": {
"tags": [
"Files"
],
"summary": "Convert files to memories",
"description": "Upload files (PDF, DOCX, etc.), convert them to markdown, and retain as memories.\n\nThis endpoint handles file upload, conversion, and memory creation in a single operation.\n\n**Features:**\n- Supports PDF, DOCX, PPTX, XLSX, images (with OCR), audio (with transcription)\n- Automatic file-to-markdown conversion using pluggable parsers\n- Files stored in object storage (PostgreSQL by default, S3 for production)\n- Each file becomes a separate document with optional metadata/tags\n- Always processes asynchronously \u2014 returns operation IDs immediately\n\n**The system automatically:**\n1. Stores uploaded files in object storage\n2. Converts files to markdown\n3. Creates document records with file metadata\n4. Extracts facts and creates memory units (same as regular retain)\n\nUse the operations endpoint to monitor progress.\n\n**Request format:** multipart/form-data with:\n- `files`: One or more files to upload\n- `request`: JSON string with FileRetainRequest model\n\n**Parser selection:**\n- Set `parser` in the request body to override the server default for all files.\n- Set `parser` inside a `files_metadata` entry for per-file control.\n- Pass a list (e.g. `['iris', 'markitdown']`) to define an ordered fallback chain \u2014 each parser is tried in sequence until one succeeds.\n- Falls back to the server default (`HINDSIGHT_API_FILE_PARSER`) if not specified.\n- Only parsers enabled on the server may be requested; others return HTTP 400.",
"operationId": "file_retain",
"parameters": [
{
"name": "bank_id",
"in": "path",
"required": true,
"schema": {
"type": "string",
"title": "Bank Id"
}
},
{
"name": "authorization",
"in": "header",
"required": false,
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Authorization"
}
}
],
"requestBody": {
"required": true,
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/Body_file_retain"
}
}
}
},
"responses": {
"200": {
"description": "Successful Response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/FileRetainResponse"
}
}
}
},
"422": {
"description": "Validation Error",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/HTTPValidationError"
}
}
}
}
}
}
}
},
"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"
}
},
"ClearMemoryObservationsResponse": {
"properties": {
"deleted_count": {
"type": "integer",
"title": "Deleted Count"
}
},
"type": "object",
"required": [
"deleted_count"
],
"title": "ClearMemoryObservationsResponse",
"description": "Response model for clearing observations for a specific memory.",
"example": {
"deleted_count": 3
}
},
"ConsolidationResponse": {
"properties": {
"operation_id": {
"type": "string",
"title": "Operation Id",
"description": "ID of the async consolidation operation"
},
"deduplicated": {
"type": "boolean",
"title": "Deduplicated",
"description": "True if an existing pending task was reused",
"default": false
}
},
"type": "object",
"required": [
"operation_id"
],
"title": "ConsolidationResponse",
"description": "Response model for consolidation trigger endpoint."
},
"CreateBankRequest": {
"properties": {
"name": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Name",
"description": "Deprecated: display label only, not advertised"
},
"disposition": {
"anyOf": [
{
"$ref": "#/components/schemas/DispositionTraits"
},
{
"type": "null"
}
],
"description": "Deprecated: use update_bank_config instead"
},
"disposition_skepticism": {
"anyOf": [
{
"type": "integer",
"maximum": 5.0,
"minimum": 1.0
},
{
"type": "null"
}
],
"title": "Disposition Skepticism",
"description": "Deprecated: use update_bank_config instead"
},
"disposition_literalism": {
"anyOf": [
{
"type": "integer",
"maximum": 5.0,
"minimum": 1.0
},
{
"type": "null"
}
],
"title": "Disposition Literalism",
"description": "Deprecated: use update_bank_config instead"
},
"disposition_empathy": {
"anyOf": [
{
"type": "integer",
"maximum": 5.0,
"minimum": 1.0
},
{
"type": "null"
}
],
"title": "Disposition Empathy",
"description": "Deprecated: use update_bank_config instead"
},
"mission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mission",
"description": "Deprecated: use update_bank_config with reflect_mission instead"
},
"background": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Background",
"description": "Deprecated: use update_bank_config with reflect_mission instead"
},
"reflect_mission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Reflect Mission",
"description": "Mission/context for Reflect operations. Guides how Reflect interprets and uses memories."
},
"retain_mission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Retain Mission",
"description": "Steers what gets extracted during retain(). Injected alongside built-in extraction rules."
},
"retain_extraction_mode": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Retain Extraction Mode",
"description": "Fact extraction mode: 'concise' (default), 'verbose', or 'custom'."
},
"retain_custom_instructions": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Retain Custom Instructions",
"description": "Custom extraction prompt. Only active when retain_extraction_mode is 'custom'."
},
"retain_chunk_size": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Retain Chunk Size",
"description": "Maximum token size for each content chunk during retain."
},
"enable_observations": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enable Observations",
"description": "Toggle automatic observation consolidation after retain()."
},
"observations_mission": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Observations Mission",
"description": "Controls what gets synthesised into observations. Replaces built-in consolidation rules entirely."
}
},
"type": "object",
"title": "CreateBankRequest",
"description": "Request model for creating/updating a bank.",
"example": {
"observations_mission": "Observations are stable facts about people and projects. Always include preferences and skills.",
"retain_mission": "Always include technical decisions and architectural trade-offs. Ignore meeting logistics."
}
},
"CreateDirectiveRequest": {
"properties": {
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable name for the directive"
},
"content": {
"type": "string",
"title": "Content",
"description": "The directive text to inject into prompts"
},
"priority": {
"type": "integer",
"title": "Priority",
"description": "Higher priority directives are injected first",
"default": 0
},
"is_active": {
"type": "boolean",
"title": "Is Active",
"description": "Whether this directive is active",
"default": true
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"description": "Tags for filtering",
"default": []
}
},
"type": "object",
"required": [
"name",
"content"
],
"title": "CreateDirectiveRequest",
"description": "Request model for creating a directive."
},
"CreateMentalModelRequest": {
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Id",
"description": "Optional custom ID for the mental model (alphanumeric lowercase with hyphens)"
},
"name": {
"type": "string",
"title": "Name",
"description": "Human-readable name for the mental model"
},
"source_query": {
"type": "string",
"title": "Source Query",
"description": "The query to run to generate content"
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"description": "Tags for scoped visibility",
"default": []
},
"max_tokens": {
"type": "integer",
"maximum": 8192.0,
"minimum": 256.0,
"title": "Max Tokens",
"description": "Maximum tokens for generated content",
"default": 2048
},
"trigger": {
"$ref": "#/components/schemas/MentalModelTrigger",
"description": "Trigger settings",
"default": {}
}
},
"type": "object",
"required": [
"name",
"source_query"
],
"title": "CreateMentalModelRequest",
"description": "Request model for creating a mental model.",
"example": {
"id": "team-communication",
"max_tokens": 2048,
"name": "Team Communication Preferences",
"source_query": "How does the team prefer to communicate?",
"tags": [
"team"
],
"trigger": {
"refresh_after_consolidation": false
}
}
},
"CreateMentalModelResponse": {
"properties": {
"mental_model_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mental Model Id",
"description": "ID of the created mental model"
},
"operation_id": {
"type": "string",
"title": "Operation Id",
"description": "Operation ID to track refresh progress"
}
},
"type": "object",
"required": [
"operation_id"
],
"title": "CreateMentalModelResponse",
"description": "Response model for mental model creation."
},
"CreateWebhookRequest": {
"properties": {
"url": {
"type": "string",
"title": "Url",
"description": "HTTP(S) endpoint URL to deliver events to"
},
"secret": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Secret",
"description": "HMAC-SHA256 signing secret (optional)"
},
"event_types": {
"items": {
"type": "string"
},
"type": "array",
"title": "Event Types",
"description": "List of event types to deliver. Currently supported: 'consolidation.completed'",
"default": [
"consolidation.completed"
]
},
"enabled": {
"type": "boolean",
"title": "Enabled",
"description": "Whether this webhook is active",
"default": true
},
"http_config": {
"$ref": "#/components/schemas/WebhookHttpConfig",
"description": "HTTP delivery configuration (method, timeout, headers, params)"
}
},
"type": "object",
"required": [
"url"
],
"title": "CreateWebhookRequest",
"description": "Request model for registering a webhook."
},
"DeleteDocumentResponse": {
"properties": {
"success": {
"type": "boolean",
"title": "Success"
},
"message": {
"type": "string",
"title": "Message"
},
"document_id": {
"type": "string",
"title": "Document Id"
},
"memory_units_deleted": {
"type": "integer",
"title": "Memory Units Deleted"
}
},
"type": "object",
"required": [
"success",
"message",
"document_id",
"memory_units_deleted"
],
"title": "DeleteDocumentResponse",
"description": "Response model for delete document endpoint.",
"example": {
"document_id": "session_1",
"memory_units_deleted": 5,
"message": "Document 'session_1' and 5 associated memory units deleted successfully",
"success": true
}
},
"DeleteResponse": {
"properties": {
"success": {
"type": "boolean",
"title": "Success"
},
"message": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Message"
},
"deleted_count": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Deleted Count"
}
},
"type": "object",
"required": [
"success"
],
"title": "DeleteResponse",
"description": "Response model for delete operations.",
"example": {
"deleted_count": 10,
"message": "Deleted successfully",
"success": true
}
},
"DirectiveListResponse": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/DirectiveResponse"
},
"type": "array",
"title": "Items"
}
},
"type": "object",
"required": [
"items"
],
"title": "DirectiveListResponse",
"description": "Response model for listing directives."
},
"DirectiveResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"name": {
"type": "string",
"title": "Name"
},
"content": {
"type": "string",
"title": "Content"
},
"priority": {
"type": "integer",
"title": "Priority",
"default": 0
},
"is_active": {
"type": "boolean",
"title": "Is Active",
"default": true
},
"tags": {
"items": {
"type": "string"
},
"type": "array",
"title": "Tags",
"default": []
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"bank_id",
"name",
"content"
],
"title": "DirectiveResponse",
"description": "Response model for a directive."
},
"DispositionTraits": {
"properties": {
"skepticism": {
"type": "integer",
"maximum": 5.0,
"minimum": 1.0,
"title": "Skepticism",
"description": "How skeptical vs trusting (1=trusting, 5=skeptical)"
},
"literalism": {
"type": "integer",
"maximum": 5.0,
"minimum": 1.0,
"title": "Literalism",
"description": "How literally to interpret information (1=flexible, 5=literal)"
},
"empathy": {
"type": "integer",
"maximum": 5.0,
"minimum": 1.0,
"title": "Empathy",
"description": "How much to consider emotional context (1=detached, 5=empathetic)"
}
},
"type": "object",
"required": [
"skepticism",
"literalism",
"empathy"
],
"title": "DispositionTraits",
"description": "Disposition traits that influence how memories are formed and interpreted.",
"example": {
"empathy": 3,
"literalism": 3,
"skepticism": 3
}
},
"DocumentResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"original_text": {
"type": "string",
"title": "Original Text"
},
"content_hash": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Content Hash"
},
"created_at": {
"type": "string",
"title": "Created At"
},
"updated_at": {
"type": "string",
"title": "Updated At"
},
"memory_unit_count": {
"type": "integer",
"title": "Memory Unit Count"
},
"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)."
},
"source_facts": {
"anyOf": [
{
"$ref": "#/components/schemas/SourceFactsIncludeOptions"
},
{
"type": "null"
}
],
"description": "Include source facts for observation-type results. Set to {} to enable, null to disable (default: disabled)."
}
},
"type": "object",
"title": "IncludeOptions",
"description": "Options for including additional data in recall results."
},
"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": "string"
},
{
"type": "null"
}
],
"title": "Timestamp",
"description": "When the content occurred. Accepts an ISO 8601 datetime string (e.g. '2024-01-15T10:30:00Z'), null/omitted (defaults to now), or the special string 'unset' to explicitly store without any timestamp (use this for timeless content such as fictional documents or static reference material)."
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Context"
},
"metadata": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Metadata"
},
"document_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Document Id",
"description": "Optional document ID for this memory item."
},
"entities": {
"anyOf": [
{
"items": {
"$ref": "#/components/schemas/EntityInput"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Entities",
"description": "Optional entities to combine with auto-extracted entities."
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags",
"description": "Optional tags for visibility scoping. Memories with tags can be filtered during recall."
},
"observation_scopes": {
"anyOf": [
{
"type": "string",
"enum": [
"per_tag",
"combined",
"all_combinations"
]
},
{
"items": {
"items": {
"type": "string"
},
"type": "array"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "ObservationScopes",
"description": "How to scope observations during consolidation. 'per_tag' runs one consolidation pass per individual tag, creating separate observations for each tag. 'combined' (default) runs a single pass with all tags together. A list of tag lists runs one pass per inner list, giving full control over which combinations to use."
}
},
"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"
},
"source_facts": {
"anyOf": [
{
"additionalProperties": {
"$ref": "#/components/schemas/RecallResult"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Source Facts",
"description": "Source facts for observation-type results, keyed by fact ID"
}
},
"type": "object",
"required": [
"results"
],
"title": "RecallResponse",
"description": "Response model for recall endpoints.",
"example": {
"chunks": {
"456e7890-e12b-34d5-a678-901234567890": {
"chunk_index": 0,
"id": "456e7890-e12b-34d5-a678-901234567890",
"text": "Alice works at Google on the AI team. She's been there for 3 years..."
}
},
"entities": {
"Alice": {
"canonical_name": "Alice",
"entity_id": "123e4567-e89b-12d3-a456-426614174001",
"observations": [
{
"mentioned_at": "2024-01-15T10:30:00Z",
"text": "Alice works at Google on the AI team"
}
]
}
},
"results": [
{
"chunk_id": "456e7890-e12b-34d5-a678-901234567890",
"context": "work info",
"entities": [
"Alice",
"Google"
],
"id": "123e4567-e89b-12d3-a456-426614174000",
"occurred_end": "2024-01-15T10:30:00Z",
"occurred_start": "2024-01-15T10:30:00Z",
"text": "Alice works at Google on the AI team",
"type": "world"
}
],
"trace": {
"num_results": 1,
"query": "What did Alice say about machine learning?",
"time_seconds": 0.123
}
}
},
"RecallResult": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"text": {
"type": "string",
"title": "Text"
},
"type": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Type"
},
"entities": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Entities"
},
"context": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Context"
},
"occurred_start": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Occurred Start"
},
"occurred_end": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Occurred End"
},
"mentioned_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Mentioned At"
},
"document_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Document Id"
},
"metadata": {
"anyOf": [
{
"additionalProperties": {
"type": "string"
},
"type": "object"
},
{
"type": "null"
}
],
"title": "Metadata"
},
"chunk_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Chunk Id"
},
"tags": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Tags"
},
"source_fact_ids": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Source Fact Ids"
}
},
"type": "object",
"required": [
"id",
"text"
],
"title": "RecallResult",
"description": "Single recall result item.",
"example": {
"chunk_id": "456e7890-e12b-34d5-a678-901234567890",
"context": "work info",
"document_id": "session_abc123",
"entities": [
"Alice",
"Google"
],
"id": "123e4567-e89b-12d3-a456-426614174000",
"mentioned_at": "2024-01-15T10:30:00Z",
"metadata": {
"source": "slack"
},
"occurred_end": "2024-01-15T10:30:00Z",
"occurred_start": "2024-01-15T10:30:00Z",
"tags": [
"user_a",
"user_b"
],
"text": "Alice works at Google on the AI team",
"type": "world"
}
},
"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": "Deprecated. Use item-level tags instead.",
"deprecated": true
}
},
"type": "object",
"required": [
"items"
],
"title": "RetainRequest",
"description": "Request model for retain endpoint.",
"example": {
"async": false,
"items": [
{
"content": "Alice works at Google",
"context": "work",
"document_id": "conversation_123"
},
{
"content": "Bob went hiking yesterday",
"document_id": "conversation_123",
"timestamp": "2024-01-15T10:00:00Z"
}
]
}
},
"RetainResponse": {
"properties": {
"success": {
"type": "boolean",
"title": "Success"
},
"bank_id": {
"type": "string",
"title": "Bank Id"
},
"items_count": {
"type": "integer",
"title": "Items Count"
},
"async": {
"type": "boolean",
"title": "Async",
"description": "Whether the operation was processed asynchronously"
},
"operation_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Operation Id",
"description": "Operation ID for tracking async operations. Use GET /v1/default/banks/{bank_id}/operations to list operations. Only present when async=true."
},
"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
}
}
},
"SourceFactsIncludeOptions": {
"properties": {
"max_tokens": {
"type": "integer",
"title": "Max Tokens",
"description": "Maximum total tokens for source facts across all observations (-1 = unlimited)",
"default": 4096
},
"max_tokens_per_observation": {
"type": "integer",
"title": "Max Tokens Per Observation",
"description": "Maximum tokens of source facts per observation (-1 = unlimited)",
"default": -1
}
},
"type": "object",
"title": "SourceFactsIncludeOptions",
"description": "Options for including source facts for observation-type results."
},
"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
}
}
},
"UpdateWebhookRequest": {
"properties": {
"url": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Url",
"description": "HTTP(S) endpoint URL"
},
"secret": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Secret",
"description": "HMAC-SHA256 signing secret. Omit to keep existing; send null to clear."
},
"event_types": {
"anyOf": [
{
"items": {
"type": "string"
},
"type": "array"
},
{
"type": "null"
}
],
"title": "Event Types",
"description": "List of event types"
},
"enabled": {
"anyOf": [
{
"type": "boolean"
},
{
"type": "null"
}
],
"title": "Enabled",
"description": "Whether this webhook is active"
},
"http_config": {
"anyOf": [
{
"$ref": "#/components/schemas/WebhookHttpConfig"
},
{
"type": "null"
}
],
"description": "HTTP delivery configuration"
}
},
"type": "object",
"title": "UpdateWebhookRequest",
"description": "Request model for updating a webhook. Only provided fields are updated."
},
"ValidationError": {
"properties": {
"loc": {
"items": {
"anyOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
},
"type": "array",
"title": "Location"
},
"msg": {
"type": "string",
"title": "Message"
},
"type": {
"type": "string",
"title": "Error Type"
}
},
"type": "object",
"required": [
"loc",
"msg",
"type"
],
"title": "ValidationError"
},
"VersionResponse": {
"properties": {
"api_version": {
"type": "string",
"title": "Api Version",
"description": "API version string"
},
"features": {
"$ref": "#/components/schemas/FeaturesInfo",
"description": "Enabled feature flags"
}
},
"type": "object",
"required": [
"api_version",
"features"
],
"title": "VersionResponse",
"description": "Response model for the version/info endpoint.",
"example": {
"api_version": "0.4.0",
"features": {
"bank_config_api": false,
"file_upload_api": true,
"mcp": true,
"observations": false,
"worker": true
}
}
},
"WebhookDeliveryListResponse": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/WebhookDeliveryResponse"
},
"type": "array",
"title": "Items"
},
"next_cursor": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Next Cursor"
}
},
"type": "object",
"required": [
"items"
],
"title": "WebhookDeliveryListResponse",
"description": "Response model for listing webhook deliveries."
},
"WebhookDeliveryResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"webhook_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Webhook Id"
},
"url": {
"type": "string",
"title": "Url"
},
"event_type": {
"type": "string",
"title": "Event Type"
},
"status": {
"type": "string",
"title": "Status"
},
"attempts": {
"type": "integer",
"title": "Attempts"
},
"next_retry_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Next Retry At"
},
"last_error": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Error"
},
"last_response_status": {
"anyOf": [
{
"type": "integer"
},
{
"type": "null"
}
],
"title": "Last Response Status"
},
"last_response_body": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Response Body"
},
"last_attempt_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Last Attempt At"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"webhook_id",
"url",
"event_type",
"status",
"attempts"
],
"title": "WebhookDeliveryResponse",
"description": "Response model for a webhook delivery record."
},
"WebhookHttpConfig": {
"properties": {
"method": {
"type": "string",
"title": "Method",
"description": "HTTP method: GET or POST",
"default": "POST"
},
"timeout_seconds": {
"type": "integer",
"title": "Timeout Seconds",
"description": "HTTP request timeout in seconds",
"default": 30
},
"headers": {
"additionalProperties": {
"type": "string"
},
"type": "object",
"title": "Headers",
"description": "Custom HTTP headers"
},
"params": {
"additionalProperties": {
"type": "string"
},
"type": "object",
"title": "Params",
"description": "Custom HTTP query parameters"
}
},
"type": "object",
"title": "WebhookHttpConfig",
"description": "HTTP delivery configuration for a webhook."
},
"WebhookListResponse": {
"properties": {
"items": {
"items": {
"$ref": "#/components/schemas/WebhookResponse"
},
"type": "array",
"title": "Items"
}
},
"type": "object",
"required": [
"items"
],
"title": "WebhookListResponse",
"description": "Response model for listing webhooks."
},
"WebhookResponse": {
"properties": {
"id": {
"type": "string",
"title": "Id"
},
"bank_id": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Bank Id"
},
"url": {
"type": "string",
"title": "Url"
},
"secret": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Secret",
"description": "Signing secret (redacted in responses)"
},
"event_types": {
"items": {
"type": "string"
},
"type": "array",
"title": "Event Types"
},
"enabled": {
"type": "boolean",
"title": "Enabled"
},
"http_config": {
"$ref": "#/components/schemas/WebhookHttpConfig"
},
"created_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Created At"
},
"updated_at": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
],
"title": "Updated At"
}
},
"type": "object",
"required": [
"id",
"bank_id",
"url",
"event_types",
"enabled"
],
"title": "WebhookResponse",
"description": "Response model for a webhook."
}
}
}
}
View git blame Copy permalink