From 3f3067e5721341aaf6d40eda328331aff22889ce Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Thu, 19 Mar 2026 10:32:10 +0100 Subject: [PATCH 1/6] feat(skill): validate links, strip images, include openapi.json and changelog - Add post-processing step to rewrite Docusaurus site-root paths (e.g. /developer/foo) to proper relative .md paths within the skill - Strip markdown and HTML images from all generated files since assets are not bundled with the skill - Copy hindsight-docs/static/openapi.json into references/openapi.json and map /api-reference links to it - Include changelog.md from src/pages/ alongside faq and best-practices - Add final validation step that fails the build if any link still points outside the skill directory --- scripts/generate-docs-skill.sh | 114 +- skills/hindsight-docs/references/openapi.json | 8512 +++++++++++++++++ 2 files changed, 8625 insertions(+), 1 deletion(-) create mode 100644 skills/hindsight-docs/references/openapi.json diff --git a/scripts/generate-docs-skill.sh b/scripts/generate-docs-skill.sh index 05a241ca..63f021f2 100755 --- a/scripts/generate-docs-skill.sh +++ b/scripts/generate-docs-skill.sh @@ -159,7 +159,7 @@ done # Process standalone pages (e.g. best-practices, faq) from src/pages/ print_info "Processing standalone pages..." -for page in best-practices faq; do +for page in best-practices faq changelog; do for ext in md mdx; do src="$PAGES_DIR/$page.$ext" if [ -f "$src" ]; then @@ -175,6 +175,15 @@ for page in best-practices faq; do done done +# Copy OpenAPI spec into the skill +OPENAPI_SRC="$ROOT_DIR/hindsight-docs/static/openapi.json" +if [ -f "$OPENAPI_SRC" ]; then + cp "$OPENAPI_SRC" "$REFS_DIR/openapi.json" + print_info "Included: openapi.json" +else + print_warn "openapi.json not found at $OPENAPI_SRC — skipping" +fi + # Generate SKILL.md print_info "Generating SKILL.md..." cat > "$SKILL_DIR/SKILL.md" <<'EOF' @@ -208,6 +217,8 @@ All documentation is in `references/` organized by category: references/ ├── best-practices.md # START HERE — missions, tags, formats, anti-patterns ├── faq.md # Common questions and decisions +├── changelog.md # Release history and version changes +├── openapi.json # Full OpenAPI spec — endpoint schemas, request/response models ├── developer/ │ ├── api/ # Core operations: retain, recall, reflect, memory banks │ └── *.md # Architecture, configuration, deployment, performance @@ -302,6 +313,107 @@ print_info "✓ Generated skill at: $SKILL_DIR" print_info "✓ Documentation files: $(find "$REFS_DIR" -type f | wc -l | tr -d ' ')" print_info "✓ SKILL.md created with search guidance" +# Rewrite Docusaurus absolute paths (e.g. /developer/foo) to relative paths +print_info "Rewriting Docusaurus absolute paths to relative paths..." +python3 - "$REFS_DIR" <<'PYTHON' +import sys +import re +import os +from pathlib import Path + +refs_dir = Path(sys.argv[1]).resolve() +link_pattern = re.compile(r'\[([^\]]*)\]\((/[^)]*)\)') + +SPECIAL_MAPPINGS = { + '/api-reference': 'openapi.json', +} + +def try_resolve(url_path, refs_dir): + """Try to find the file in refs_dir for a Docusaurus absolute path like /developer/foo.""" + if url_path in SPECIAL_MAPPINGS: + candidate = refs_dir / SPECIAL_MAPPINGS[url_path] + return candidate if candidate.exists() else None + doc_path = url_path.lstrip('/') + for candidate in [ + refs_dir / (doc_path + '.md'), + refs_dir / doc_path / 'index.md', + refs_dir / doc_path, + ]: + if candidate.exists(): + return candidate + return None + +image_pattern = re.compile(r'!\[[^\]]*\]\([^)]*\)') +html_img_pattern = re.compile(r']*/?>', re.IGNORECASE) + +changed = 0 +for md_file in refs_dir.rglob("*.md"): + content = md_file.read_text() + + # Strip images (markdown and HTML) + content = image_pattern.sub('', content) + content = html_img_pattern.sub('', content) + + def rewrite(match): + text = match.group(1) + url = match.group(2) + anchor = '' + if '#' in url: + url, frag = url.split('#', 1) + anchor = '#' + frag + if not url or url == '/': + return match.group(0) + resolved = try_resolve(url, refs_dir) + if resolved is None: + return match.group(0) + rel = os.path.relpath(resolved, md_file.parent) + return f'[{text}]({rel}{anchor})' + + new_content = link_pattern.sub(rewrite, content) + if new_content != content: + md_file.write_text(new_content) + changed += 1 + +print(f"[INFO] Rewrote Docusaurus links in {changed} file(s)") +PYTHON + +# Validate: no links point outside the skill directory +print_info "Validating links in generated skill files..." +python3 - "$SKILL_DIR" <<'PYTHON' +import sys +import re +from pathlib import Path + +skill_dir = Path(sys.argv[1]).resolve() +errors = [] + +# Find all markdown links: [text](url) — exclude images too +link_pattern = re.compile(r'\[([^\]]*)\]\(([^)]+)\)') + +for md_file in skill_dir.rglob("*.md"): + content = md_file.read_text() + for match in link_pattern.finditer(content): + url = match.group(2).split("#")[0].strip() # strip anchors + if not url: + continue + # Absolute URLs and anchors-only are fine + if url.startswith(("http://", "https://", "mailto:", "ftp://")): + continue + # Resolve relative to the file's directory + resolved = (md_file.parent / url).resolve() + if not str(resolved).startswith(str(skill_dir)): + errors.append(f" {md_file.relative_to(skill_dir)}: '{url}' -> {resolved}") + +if errors: + print("ERROR: The following links point outside the skill directory.") + print("All links must be absolute URLs or relative paths within the skill.") + for e in errors: + print(e) + sys.exit(1) + +print(f"[INFO] Link validation passed ({skill_dir})") +PYTHON + echo "" print_info "Usage:" echo " - Agents can use Glob to find files: references/developer/api/*.md" diff --git a/skills/hindsight-docs/references/openapi.json b/skills/hindsight-docs/references/openapi.json new file mode 100644 index 00000000..7f271354 --- /dev/null +++ b/skills/hindsight-docs/references/openapi.json @@ -0,0 +1,8512 @@ +{ + "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.19" + }, + "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" + } + } + } + } + } + }, + "patch": { + "tags": [ + "Documents" + ], + "summary": "Update document", + "description": "Update mutable fields on a document without re-processing its content.\n\n**Tags** (`tags`): Propagated to all associated memory units. Observations derived from those units are invalidated and queued for re-consolidation under the new tags. Co-source memories from other documents that shared those observations are also reset.\n\nAt least one field must be provided.", + "operationId": "update_document", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Document Id" + } + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateDocumentRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateDocumentResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": [ + "Documents" + ], + "summary": "Delete a document", + "description": "Delete a document and all its associated memory units and links.\n\nThis will cascade delete:\n- The document itself\n- All memory units extracted from this document\n- All links (temporal, semantic, entity) associated with those memory units\n\nThis operation cannot be undone.", + "operationId": "delete_document", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "document_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Document Id" + } + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteDocumentResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v1/default/banks/{bank_id}/tags": { + "get": { + "tags": [ + "Memory" + ], + "summary": "List tags", + "description": "List all unique tags in a memory bank with usage counts. Supports wildcard search using '*' (e.g., 'user:*', '*-fred', 'tag*-2'). Case-insensitive.", + "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 and operation type. Results are sorted by most recent first.", + "operationId": "list_operations", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "status", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Filter by status: pending, completed, or failed", + "title": "Status" + }, + "description": "Filter by status: pending, completed, or failed" + }, + { + "name": "type", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Filter by operation type: retain, consolidation, refresh_mental_model, file_convert_retain, webhook_delivery", + "title": "Type" + }, + "description": "Filter by operation type: retain, consolidation, refresh_mental_model, file_convert_retain, webhook_delivery" + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "maximum": 100, + "minimum": 1, + "description": "Maximum number of operations to return", + "default": 20, + "title": "Limit" + }, + "description": "Maximum number of operations to return" + }, + { + "name": "offset", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "minimum": 0, + "description": "Number of operations to skip", + "default": 0, + "title": "Offset" + }, + "description": "Number of operations to skip" + }, + { + "name": "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}/operations/{operation_id}/retry": { + "post": { + "tags": [ + "Operations" + ], + "summary": "Retry a failed async operation", + "description": "Re-queue a failed async operation so the worker picks it up again", + "operationId": "retry_operation", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "operation_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Operation Id" + } + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetryOperationResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v1/default/banks/{bank_id}/profile": { + "get": { + "tags": [ + "Banks" + ], + "summary": "Get memory bank profile", + "description": "Get disposition traits and mission for a memory bank. 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}/consolidation/recover": { + "post": { + "tags": [ + "Banks" + ], + "summary": "Recover failed consolidation", + "description": "Reset all memories that were permanently marked as failed during consolidation (after exhausting all LLM retries and adaptive batch splitting) so they are picked up again on the next consolidation run. Does not delete any observations.", + "operationId": "recover_consolidation", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RecoverConsolidationResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v1/default/banks/{bank_id}/memories/{memory_id}/observations": { + "delete": { + "tags": [ + "Memory" + ], + "summary": "Clear observations for a memory", + "description": "Delete all observations derived from a specific memory and reset it for re-consolidation. The memory itself is not deleted. A consolidation job is triggered automatically so the memory will produce fresh observations on the next consolidation run.", + "operationId": "clear_memory_observations", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "memory_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Memory Id" + } + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ClearMemoryObservationsResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v1/default/banks/{bank_id}/config": { + "get": { + "tags": [ + "Banks" + ], + "summary": "Get bank configuration", + "description": "Get fully resolved configuration for a bank including all hierarchical overrides (global \u2192 tenant \u2192 bank). The 'config' field contains all resolved config values. The 'overrides' field shows only bank-specific overrides.", + "operationId": "get_bank_config", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BankConfigResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "patch": { + "tags": [ + "Banks" + ], + "summary": "Update bank configuration", + "description": "Update configuration overrides for a bank. Only hierarchical fields can be overridden (LLM settings, retention parameters, etc.). Keys can be provided in Python field format (llm_provider) or environment variable format (HINDSIGHT_API_LLM_PROVIDER).", + "operationId": "update_bank_config", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BankConfigUpdate" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BankConfigResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": [ + "Banks" + ], + "summary": "Reset bank configuration", + "description": "Reset bank configuration to defaults by removing all bank-specific overrides. The bank will then use global and tenant-level configuration only.", + "operationId": "reset_bank_config", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/BankConfigResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v1/default/banks/{bank_id}/consolidate": { + "post": { + "tags": [ + "Banks" + ], + "summary": "Trigger consolidation", + "description": "Run memory consolidation to create/update observations from recent memories.", + "operationId": "trigger_consolidation", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ConsolidationResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v1/default/banks/{bank_id}/webhooks": { + "post": { + "tags": [ + "Webhooks" + ], + "summary": "Register webhook", + "description": "Register a webhook endpoint to receive event notifications for this bank.", + "operationId": "create_webhook", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/CreateWebhookRequest" + } + } + } + }, + "responses": { + "201": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "get": { + "tags": [ + "Webhooks" + ], + "summary": "List webhooks", + "description": "List all webhooks registered for a bank.", + "operationId": "list_webhooks", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookListResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v1/default/banks/{bank_id}/webhooks/{webhook_id}": { + "delete": { + "tags": [ + "Webhooks" + ], + "summary": "Delete webhook", + "description": "Remove a registered webhook.", + "operationId": "delete_webhook", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "webhook_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Webhook Id" + } + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "patch": { + "tags": [ + "Webhooks" + ], + "summary": "Update webhook", + "description": "Update one or more fields of a registered webhook. Only provided fields are changed.", + "operationId": "update_webhook", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "webhook_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Webhook Id" + } + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/UpdateWebhookRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v1/default/banks/{bank_id}/webhooks/{webhook_id}/deliveries": { + "get": { + "tags": [ + "Webhooks" + ], + "summary": "List webhook deliveries", + "description": "Inspect delivery history for a webhook (useful for debugging).", + "operationId": "list_webhook_deliveries", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "webhook_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Webhook Id" + } + }, + { + "name": "limit", + "in": "query", + "required": false, + "schema": { + "type": "integer", + "maximum": 200, + "description": "Maximum number of deliveries to return", + "default": 50, + "title": "Limit" + }, + "description": "Maximum number of deliveries to return" + }, + { + "name": "cursor", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Pagination cursor (created_at of last item)", + "title": "Cursor" + }, + "description": "Pagination cursor (created_at of last item)" + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WebhookDeliveryListResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v1/default/banks/{bank_id}/memories": { + "post": { + "tags": [ + "Memory" + ], + "summary": "Retain memories", + "description": "Retain memory items with automatic fact extraction.\n\nThis is the main endpoint for storing memories. It supports both synchronous and asynchronous processing via the `async` parameter.\n\n**Features:**\n- Efficient batch processing\n- Automatic fact extraction from natural language\n- Entity recognition and linking\n- Document tracking with automatic upsert (when document_id is provided)\n- Temporal and semantic linking\n- Optional asynchronous processing\n\n**The system automatically:**\n1. Extracts semantic facts from the content\n2. Generates embeddings\n3. Deduplicates similar facts\n4. Creates temporal, semantic, and entity links\n5. Tracks document metadata\n\n**When `async=true`:** Returns immediately after queuing. Use the operations endpoint to monitor progress.\n\n**When `async=false` (default):** Waits for processing to complete.\n\n**Note:** If a memory item has a `document_id` that already exists, the old document and its memory units will be deleted before creating new ones (upsert behavior).", + "operationId": "retain_memories", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "requestBody": { + "required": true, + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetainRequest" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/RetainResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + }, + "delete": { + "tags": [ + "Memory" + ], + "summary": "Clear memory bank memories", + "description": "Delete memory units for a memory bank. Optionally filter by type (world, experience, opinion) to delete only specific types. This is a destructive operation that cannot be undone. The bank profile (disposition and background) will be preserved.", + "operationId": "clear_bank_memories", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "type", + "in": "query", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "description": "Optional fact type filter (world, experience, opinion)", + "title": "Type" + }, + "description": "Optional fact type filter (world, experience, opinion)" + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/DeleteResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/v1/default/banks/{bank_id}/files/retain": { + "post": { + "tags": [ + "Files" + ], + "summary": "Convert files to memories", + "description": "Upload files (PDF, DOCX, etc.), convert them to markdown, and retain as memories.\n\nThis endpoint handles file upload, conversion, and memory creation in a single operation.\n\n**Features:**\n- Supports PDF, DOCX, PPTX, XLSX, images (with OCR), audio (with transcription)\n- Automatic file-to-markdown conversion using pluggable parsers\n- Files stored in object storage (PostgreSQL by default, S3 for production)\n- Each file becomes a separate document with optional metadata/tags\n- Always processes asynchronously \u2014 returns operation IDs immediately\n\n**The system automatically:**\n1. Stores uploaded files in object storage\n2. Converts files to markdown\n3. Creates document records with file metadata\n4. Extracts facts and creates memory units (same as regular retain)\n\nUse the operations endpoint to monitor progress.\n\n**Request format:** multipart/form-data with:\n- `files`: One or more files to upload\n- `request`: JSON string with FileRetainRequest model\n\n**Parser selection:**\n- Set `parser` in the request body to override the server default for all files.\n- Set `parser` inside a `files_metadata` entry for per-file control.\n- Pass a list (e.g. `['iris', 'markitdown']`) to define an ordered fallback chain \u2014 each parser is tried in sequence until one succeeds.\n- Falls back to the server default (`HINDSIGHT_API_FILE_PARSER`) if not specified.\n- Only parsers enabled on the server may be requested; others return HTTP 400.", + "operationId": "file_retain", + "parameters": [ + { + "name": "bank_id", + "in": "path", + "required": true, + "schema": { + "type": "string", + "title": "Bank Id" + } + }, + { + "name": "authorization", + "in": "header", + "required": false, + "schema": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Authorization" + } + } + ], + "requestBody": { + "required": true, + "content": { + "multipart/form-data": { + "schema": { + "$ref": "#/components/schemas/Body_file_retain" + } + } + } + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/FileRetainResponse" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + } + }, + "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." + }, + "strategy": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Strategy", + "description": "Named retain strategy for this item. Overrides the bank's default strategy for this item only. Strategies are defined in the bank config under 'retain_strategies'." + } + }, + "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" + }, + "tag_groups": { + "anyOf": [ + { + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/TagGroupLeaf" + }, + { + "$ref": "#/components/schemas/TagGroupAnd" + }, + { + "$ref": "#/components/schemas/TagGroupOr" + }, + { + "$ref": "#/components/schemas/TagGroupNot" + } + ] + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Tag Groups", + "description": "Compound tag filter using boolean groups. Groups in the list are AND-ed. Each group is a leaf {tags, match} or compound {and: [...]}, {or: [...]}, {not: ...}." + } + }, + "type": "object", + "required": [ + "query" + ], + "title": "RecallRequest", + "description": "Request model for recall endpoint.", + "example": { + "budget": "mid", + "include": { + "entities": { + "max_tokens": 500 + } + }, + "max_tokens": 4096, + "query": "What did Alice say about machine learning?", + "query_timestamp": "2023-05-30T23:40:00", + "tags": [ + "user_a" + ], + "tags_match": "any", + "trace": true, + "types": [ + "world", + "experience" + ] + } + }, + "RecallResponse": { + "properties": { + "results": { + "items": { + "$ref": "#/components/schemas/RecallResult" + }, + "type": "array", + "title": "Results" + }, + "trace": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Trace" + }, + "entities": { + "anyOf": [ + { + "additionalProperties": { + "$ref": "#/components/schemas/EntityStateResponse" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Entities", + "description": "Entity states for entities mentioned in results" + }, + "chunks": { + "anyOf": [ + { + "additionalProperties": { + "$ref": "#/components/schemas/ChunkData" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Chunks", + "description": "Chunks for facts, keyed by chunk_id" + }, + "source_facts": { + "anyOf": [ + { + "additionalProperties": { + "$ref": "#/components/schemas/RecallResult" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Source Facts", + "description": "Source facts for observation-type results, keyed by fact ID" + } + }, + "type": "object", + "required": [ + "results" + ], + "title": "RecallResponse", + "description": "Response model for recall endpoints.", + "example": { + "chunks": { + "456e7890-e12b-34d5-a678-901234567890": { + "chunk_index": 0, + "id": "456e7890-e12b-34d5-a678-901234567890", + "text": "Alice works at Google on the AI team. She's been there for 3 years..." + } + }, + "entities": { + "Alice": { + "canonical_name": "Alice", + "entity_id": "123e4567-e89b-12d3-a456-426614174001", + "observations": [ + { + "mentioned_at": "2024-01-15T10:30:00Z", + "text": "Alice works at Google on the AI team" + } + ] + } + }, + "results": [ + { + "chunk_id": "456e7890-e12b-34d5-a678-901234567890", + "context": "work info", + "entities": [ + "Alice", + "Google" + ], + "id": "123e4567-e89b-12d3-a456-426614174000", + "occurred_end": "2024-01-15T10:30:00Z", + "occurred_start": "2024-01-15T10:30:00Z", + "text": "Alice works at Google on the AI team", + "type": "world" + } + ], + "trace": { + "num_results": 1, + "query": "What did Alice say about machine learning?", + "time_seconds": 0.123 + } + } + }, + "RecallResult": { + "properties": { + "id": { + "type": "string", + "title": "Id" + }, + "text": { + "type": "string", + "title": "Text" + }, + "type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Type" + }, + "entities": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Entities" + }, + "context": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Context" + }, + "occurred_start": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Occurred Start" + }, + "occurred_end": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Occurred End" + }, + "mentioned_at": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Mentioned At" + }, + "document_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Document Id" + }, + "metadata": { + "anyOf": [ + { + "additionalProperties": { + "type": "string" + }, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Metadata" + }, + "chunk_id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Chunk Id" + }, + "tags": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Tags" + }, + "source_fact_ids": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Source Fact Ids" + } + }, + "type": "object", + "required": [ + "id", + "text" + ], + "title": "RecallResult", + "description": "Single recall result item.", + "example": { + "chunk_id": "456e7890-e12b-34d5-a678-901234567890", + "context": "work info", + "document_id": "session_abc123", + "entities": [ + "Alice", + "Google" + ], + "id": "123e4567-e89b-12d3-a456-426614174000", + "mentioned_at": "2024-01-15T10:30:00Z", + "metadata": { + "source": "slack" + }, + "occurred_end": "2024-01-15T10:30:00Z", + "occurred_start": "2024-01-15T10:30:00Z", + "tags": [ + "user_a", + "user_b" + ], + "text": "Alice works at Google on the AI team", + "type": "world" + } + }, + "RecoverConsolidationResponse": { + "properties": { + "retried_count": { + "type": "integer", + "title": "Retried Count" + } + }, + "type": "object", + "required": [ + "retried_count" + ], + "title": "RecoverConsolidationResponse", + "description": "Response model for recovering failed consolidation.", + "example": { + "retried_count": 42 + } + }, + "ReflectBasedOn": { + "properties": { + "memories": { + "items": { + "$ref": "#/components/schemas/ReflectFact" + }, + "type": "array", + "title": "Memories", + "description": "Memory facts used to generate the response", + "default": [] + }, + "mental_models": { + "items": { + "$ref": "#/components/schemas/ReflectMentalModel" + }, + "type": "array", + "title": "Mental Models", + "description": "Mental models used during reflection", + "default": [] + }, + "directives": { + "items": { + "$ref": "#/components/schemas/ReflectDirective" + }, + "type": "array", + "title": "Directives", + "description": "Directives applied during reflection", + "default": [] + } + }, + "type": "object", + "title": "ReflectBasedOn", + "description": "Evidence the response is based on: memories, mental models, and directives." + }, + "ReflectDirective": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Directive ID" + }, + "name": { + "type": "string", + "title": "Name", + "description": "Directive name" + }, + "content": { + "type": "string", + "title": "Content", + "description": "Directive content" + } + }, + "type": "object", + "required": [ + "id", + "name", + "content" + ], + "title": "ReflectDirective", + "description": "A directive applied during reflect." + }, + "ReflectFact": { + "properties": { + "id": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Id" + }, + "text": { + "type": "string", + "title": "Text", + "description": "Fact text. When type='observation', this contains markdown-formatted consolidated knowledge" + }, + "type": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Type" + }, + "context": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Context" + }, + "occurred_start": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Occurred Start" + }, + "occurred_end": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Occurred End" + } + }, + "type": "object", + "required": [ + "text" + ], + "title": "ReflectFact", + "description": "A fact used in think response.", + "example": { + "context": "healthcare discussion", + "id": "123e4567-e89b-12d3-a456-426614174000", + "occurred_end": "2024-01-15T10:30:00Z", + "occurred_start": "2024-01-15T10:30:00Z", + "text": "AI is used in healthcare", + "type": "world" + } + }, + "ReflectIncludeOptions": { + "properties": { + "facts": { + "anyOf": [ + { + "$ref": "#/components/schemas/FactsIncludeOptions" + }, + { + "type": "null" + } + ], + "description": "Include facts that the answer is based on. Set to {} to enable, null to disable (default: disabled)." + }, + "tool_calls": { + "anyOf": [ + { + "$ref": "#/components/schemas/ToolCallsIncludeOptions" + }, + { + "type": "null" + } + ], + "description": "Include tool calls trace. Set to {} for full trace (input+output), {output: false} for inputs only." + } + }, + "type": "object", + "title": "ReflectIncludeOptions", + "description": "Options for including additional data in reflect results." + }, + "ReflectLLMCall": { + "properties": { + "scope": { + "type": "string", + "title": "Scope", + "description": "Call scope: agent_1, agent_2, final, etc." + }, + "duration_ms": { + "type": "integer", + "title": "Duration Ms", + "description": "Execution time in milliseconds" + } + }, + "type": "object", + "required": [ + "scope", + "duration_ms" + ], + "title": "ReflectLLMCall", + "description": "An LLM call made during reflect agent execution." + }, + "ReflectMentalModel": { + "properties": { + "id": { + "type": "string", + "title": "Id", + "description": "Mental model ID" + }, + "text": { + "type": "string", + "title": "Text", + "description": "Mental model content" + }, + "context": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Context", + "description": "Additional context" + } + }, + "type": "object", + "required": [ + "id", + "text" + ], + "title": "ReflectMentalModel", + "description": "A mental model used during reflect." + }, + "ReflectRequest": { + "properties": { + "query": { + "type": "string", + "title": "Query" + }, + "budget": { + "$ref": "#/components/schemas/Budget", + "default": "low" + }, + "context": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Context", + "description": "DEPRECATED: Additional context is now concatenated with the query. Pass context directly in the query field instead. If provided, it will be appended to the query for backward compatibility.", + "deprecated": true + }, + "max_tokens": { + "type": "integer", + "title": "Max Tokens", + "description": "Maximum tokens for the response", + "default": 4096 + }, + "include": { + "$ref": "#/components/schemas/ReflectIncludeOptions", + "description": "Options for including additional data (disabled by default)" + }, + "response_schema": { + "anyOf": [ + { + "additionalProperties": true, + "type": "object" + }, + { + "type": "null" + } + ], + "title": "Response Schema", + "description": "Optional JSON Schema for structured output. When provided, the response will include a 'structured_output' field with the LLM response parsed according to this schema." + }, + "tags": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Tags", + "description": "Filter memories by tags during reflection. If not specified, all memories are considered." + }, + "tags_match": { + "type": "string", + "enum": [ + "any", + "all", + "any_strict", + "all_strict" + ], + "title": "Tags Match", + "description": "How to match tags: 'any' (OR, includes untagged), 'all' (AND, includes untagged), 'any_strict' (OR, excludes untagged), 'all_strict' (AND, excludes untagged).", + "default": "any" + }, + "tag_groups": { + "anyOf": [ + { + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/TagGroupLeaf" + }, + { + "$ref": "#/components/schemas/TagGroupAnd" + }, + { + "$ref": "#/components/schemas/TagGroupOr" + }, + { + "$ref": "#/components/schemas/TagGroupNot" + } + ] + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Tag Groups", + "description": "Compound tag filter using boolean groups. Groups in the list are AND-ed. Each group is a leaf {tags, match} or compound {and: [...]}, {or: [...]}, {not: ...}." + } + }, + "type": "object", + "required": [ + "query" + ], + "title": "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. When items use different per-item strategies, use operation_ids instead." + }, + "operation_ids": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Operation Ids", + "description": "Operation IDs when items were submitted as multiple strategy groups (async=true with mixed per-item strategies). operation_id is set to the first entry for backward compatibility." + }, + "usage": { + "anyOf": [ + { + "$ref": "#/components/schemas/TokenUsage" + }, + { + "type": "null" + } + ], + "description": "Token usage metrics for LLM calls during fact extraction (only present for synchronous operations)" + } + }, + "type": "object", + "required": [ + "success", + "bank_id", + "items_count", + "async" + ], + "title": "RetainResponse", + "description": "Response model for retain endpoint.", + "example": { + "async": false, + "bank_id": "user123", + "items_count": 2, + "success": true, + "usage": { + "input_tokens": 500, + "output_tokens": 100, + "total_tokens": 600 + } + } + }, + "RetryOperationResponse": { + "properties": { + "success": { + "type": "boolean", + "title": "Success" + }, + "message": { + "type": "string", + "title": "Message" + }, + "operation_id": { + "type": "string", + "title": "Operation Id" + } + }, + "type": "object", + "required": [ + "success", + "message", + "operation_id" + ], + "title": "RetryOperationResponse", + "description": "Response model for retry operation endpoint.", + "example": { + "message": "Operation 550e8400-e29b-41d4-a716-446655440000 queued for retry", + "operation_id": "550e8400-e29b-41d4-a716-446655440000", + "success": true + } + }, + "SourceFactsIncludeOptions": { + "properties": { + "max_tokens": { + "type": "integer", + "title": "Max Tokens", + "description": "Maximum total tokens for source facts across all observations (-1 = unlimited)", + "default": 4096 + }, + "max_tokens_per_observation": { + "type": "integer", + "title": "Max Tokens Per Observation", + "description": "Maximum tokens of source facts per observation (-1 = unlimited)", + "default": -1 + } + }, + "type": "object", + "title": "SourceFactsIncludeOptions", + "description": "Options for including source facts for observation-type results." + }, + "TagGroupAnd": { + "properties": { + "and": { + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/TagGroupLeaf" + }, + { + "$ref": "#/components/schemas/TagGroupAnd" + }, + { + "$ref": "#/components/schemas/TagGroupOr" + }, + { + "$ref": "#/components/schemas/TagGroupNot" + } + ] + }, + "type": "array", + "title": "And" + } + }, + "type": "object", + "required": [ + "and" + ], + "title": "TagGroupAnd", + "description": "Compound AND group: all child filters must match." + }, + "TagGroupLeaf": { + "properties": { + "tags": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Tags" + }, + "match": { + "type": "string", + "enum": [ + "any", + "all", + "any_strict", + "all_strict" + ], + "title": "Match", + "default": "any_strict" + } + }, + "type": "object", + "required": [ + "tags" + ], + "title": "TagGroupLeaf", + "description": "A leaf tag filter: matches memories by tag list and match mode." + }, + "TagGroupNot": { + "properties": { + "not": { + "anyOf": [ + { + "$ref": "#/components/schemas/TagGroupLeaf" + }, + { + "$ref": "#/components/schemas/TagGroupAnd" + }, + { + "$ref": "#/components/schemas/TagGroupOr" + }, + { + "$ref": "#/components/schemas/TagGroupNot" + } + ], + "title": "Not" + } + }, + "type": "object", + "required": [ + "not" + ], + "title": "TagGroupNot", + "description": "Compound NOT group: child filter must NOT match." + }, + "TagGroupOr": { + "properties": { + "or": { + "items": { + "anyOf": [ + { + "$ref": "#/components/schemas/TagGroupLeaf" + }, + { + "$ref": "#/components/schemas/TagGroupAnd" + }, + { + "$ref": "#/components/schemas/TagGroupOr" + }, + { + "$ref": "#/components/schemas/TagGroupNot" + } + ] + }, + "type": "array", + "title": "Or" + } + }, + "type": "object", + "required": [ + "or" + ], + "title": "TagGroupOr", + "description": "Compound OR group: at least one child filter must match." + }, + "TagItem": { + "properties": { + "tag": { + "type": "string", + "title": "Tag", + "description": "The tag value" + }, + "count": { + "type": "integer", + "title": "Count", + "description": "Number of memories with this tag" + } + }, + "type": "object", + "required": [ + "tag", + "count" + ], + "title": "TagItem", + "description": "Single tag with usage count." + }, + "TokenUsage": { + "properties": { + "input_tokens": { + "type": "integer", + "title": "Input Tokens", + "description": "Number of input/prompt tokens consumed", + "default": 0 + }, + "output_tokens": { + "type": "integer", + "title": "Output Tokens", + "description": "Number of output/completion tokens generated", + "default": 0 + }, + "total_tokens": { + "type": "integer", + "title": "Total Tokens", + "description": "Total tokens (input + output)", + "default": 0 + } + }, + "type": "object", + "title": "TokenUsage", + "description": "Token usage metrics for LLM calls.\n\nTracks input/output tokens for a single request to enable\nper-request cost tracking and monitoring.", + "example": { + "input_tokens": 1500, + "output_tokens": 500, + "total_tokens": 2000 + } + }, + "ToolCallsIncludeOptions": { + "properties": { + "output": { + "type": "boolean", + "title": "Output", + "description": "Include tool outputs in the trace. Set to false to only include inputs (smaller payload).", + "default": true + } + }, + "type": "object", + "title": "ToolCallsIncludeOptions", + "description": "Options for including tool calls in reflect results." + }, + "UpdateDirectiveRequest": { + "properties": { + "name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Name", + "description": "New name" + }, + "content": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Content", + "description": "New content" + }, + "priority": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Priority", + "description": "New priority" + }, + "is_active": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "null" + } + ], + "title": "Is Active", + "description": "New active status" + }, + "tags": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Tags", + "description": "New tags" + } + }, + "type": "object", + "title": "UpdateDirectiveRequest", + "description": "Request model for updating a directive." + }, + "UpdateDispositionRequest": { + "properties": { + "disposition": { + "$ref": "#/components/schemas/DispositionTraits" + } + }, + "type": "object", + "required": [ + "disposition" + ], + "title": "UpdateDispositionRequest", + "description": "Request model for updating disposition traits." + }, + "UpdateDocumentRequest": { + "properties": { + "tags": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Tags", + "description": "New tags for the document and its memory units. Triggers observation invalidation and re-consolidation." + } + }, + "type": "object", + "title": "UpdateDocumentRequest", + "description": "Request model for updating a document's mutable fields.", + "example": { + "tags": [ + "team-a", + "team-b" + ] + } + }, + "UpdateDocumentResponse": { + "properties": { + "success": { + "type": "boolean", + "title": "Success", + "default": true + } + }, + "type": "object", + "title": "UpdateDocumentResponse", + "description": "Response model for update document endpoint." + }, + "UpdateMentalModelRequest": { + "properties": { + "name": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Name", + "description": "New name for the mental model" + }, + "source_query": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Source Query", + "description": "New source query for the mental model" + }, + "max_tokens": { + "anyOf": [ + { + "type": "integer", + "maximum": 8192.0, + "minimum": 256.0 + }, + { + "type": "null" + } + ], + "title": "Max Tokens", + "description": "Maximum tokens for generated content" + }, + "tags": { + "anyOf": [ + { + "items": { + "type": "string" + }, + "type": "array" + }, + { + "type": "null" + } + ], + "title": "Tags", + "description": "Tags for scoped visibility" + }, + "trigger": { + "anyOf": [ + { + "$ref": "#/components/schemas/MentalModelTrigger" + }, + { + "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." + } + } + } +} \ No newline at end of file From 2fda409e3ac06c510002777995bc088f843a6719 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Thu, 19 Mar 2026 10:51:54 +0100 Subject: [PATCH 2/6] ci: run generate-docs-skill in verify-generated-files job --- .github/workflows/test.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml index cb1f875c..40d834ad 100644 --- a/.github/workflows/test.yml +++ b/.github/workflows/test.yml @@ -1775,6 +1775,9 @@ jobs: - name: Run generate-clients run: ./scripts/generate-clients.sh + - name: Run generate-docs-skill + run: ./scripts/generate-docs-skill.sh + - name: Run lint run: ./scripts/hooks/lint.sh @@ -1789,6 +1792,7 @@ jobs: echo "Please run the following commands locally and commit the changes:" echo " ./scripts/generate-openapi.sh" echo " ./scripts/generate-clients.sh" + echo " ./scripts/generate-docs-skill.sh" echo " ./scripts/hooks/lint.sh" echo "" git diff --stat From 3e29d82bbc2c092b859bd20484a3c1d9c86fbcd2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Thu, 19 Mar 2026 11:04:27 +0100 Subject: [PATCH 3/6] fix(skill): strip unresolvable site-root links instead of leaving them broken --- scripts/generate-docs-skill.sh | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/scripts/generate-docs-skill.sh b/scripts/generate-docs-skill.sh index 63f021f2..8a856fcb 100755 --- a/scripts/generate-docs-skill.sh +++ b/scripts/generate-docs-skill.sh @@ -362,10 +362,10 @@ for md_file in refs_dir.rglob("*.md"): url, frag = url.split('#', 1) anchor = '#' + frag if not url or url == '/': - return match.group(0) + return text # strip link, keep text resolved = try_resolve(url, refs_dir) if resolved is None: - return match.group(0) + return text # strip unresolvable link, keep text rel = os.path.relpath(resolved, md_file.parent) return f'[{text}]({rel}{anchor})' From b5f70bdab4782473a8c28b19a19a91dc585faeea Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Thu, 19 Mar 2026 11:12:43 +0100 Subject: [PATCH 4/6] fix(skill): write file when images stripped but no links rewritten --- scripts/generate-docs-skill.sh | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/scripts/generate-docs-skill.sh b/scripts/generate-docs-skill.sh index 8a856fcb..a8a70030 100755 --- a/scripts/generate-docs-skill.sh +++ b/scripts/generate-docs-skill.sh @@ -348,10 +348,10 @@ html_img_pattern = re.compile(r']*/?>', re.IGNORECASE) changed = 0 for md_file in refs_dir.rglob("*.md"): - content = md_file.read_text() + original_content = md_file.read_text() # Strip images (markdown and HTML) - content = image_pattern.sub('', content) + content = image_pattern.sub('', original_content) content = html_img_pattern.sub('', content) def rewrite(match): @@ -370,7 +370,7 @@ for md_file in refs_dir.rglob("*.md"): return f'[{text}]({rel}{anchor})' new_content = link_pattern.sub(rewrite, content) - if new_content != content: + if new_content != original_content: md_file.write_text(new_content) changed += 1 From d7682d328d69455cbc342dd605058098e096973e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Thu, 19 Mar 2026 11:19:17 +0100 Subject: [PATCH 5/6] chore(skill): regenerate with fixed links, stripped images, changelog and openapi --- skills/hindsight-docs/SKILL.md | 2 + skills/hindsight-docs/references/changelog.md | 575 ++++++++++++++++++ .../references/developer/api/memory-banks.md | 8 +- .../references/developer/api/mental-models.md | 2 +- .../references/developer/api/quickstart.md | 4 +- .../references/developer/api/recall.md | 2 +- .../references/developer/api/reflect.md | 2 +- .../references/developer/api/retain.md | 2 +- .../references/developer/configuration.md | 2 +- .../references/developer/index.md | 26 +- .../references/developer/models.md | 2 +- .../references/developer/observations.md | 4 +- .../references/developer/reflect.md | 10 +- .../references/developer/retain.md | 4 +- skills/hindsight-docs/references/faq.md | 26 +- skills/hindsight-docs/references/sdks/cli.md | 2 +- .../hindsight-docs/references/sdks/embed.md | 2 +- .../references/sdks/integrations/local-mcp.md | 4 +- 18 files changed, 628 insertions(+), 51 deletions(-) create mode 100644 skills/hindsight-docs/references/changelog.md diff --git a/skills/hindsight-docs/SKILL.md b/skills/hindsight-docs/SKILL.md index 6f30d490..09b6ae6a 100644 --- a/skills/hindsight-docs/SKILL.md +++ b/skills/hindsight-docs/SKILL.md @@ -28,6 +28,8 @@ All documentation is in `references/` organized by category: references/ ├── best-practices.md # START HERE — missions, tags, formats, anti-patterns ├── faq.md # Common questions and decisions +├── changelog.md # Release history and version changes +├── openapi.json # Full OpenAPI spec — endpoint schemas, request/response models ├── developer/ │ ├── api/ # Core operations: retain, recall, reflect, memory banks │ └── *.md # Architecture, configuration, deployment, performance diff --git a/skills/hindsight-docs/references/changelog.md b/skills/hindsight-docs/references/changelog.md new file mode 100644 index 00000000..1d7e8730 --- /dev/null +++ b/skills/hindsight-docs/references/changelog.md @@ -0,0 +1,575 @@ +--- +hide_table_of_contents: true +--- + +# Changelog + +This changelog highlights user-facing changes only. Internal maintenance, CI/CD, and infrastructure updates are omitted. + +For full release details, see [GitHub Releases](https://github.com/vectorize-io/hindsight/releases). + +## [0.4.18](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.18) + +**Features** + +- Add compound tag filtering using tag groups. ([`5de793ee`](https://github.com/vectorize-io/hindsight/commit/5de793ee)) +- Publish new slim Python packages (hindsight-api-slim and hindsight-all-slim) for smaller installs. ([`15ea23d5`](https://github.com/vectorize-io/hindsight/commit/15ea23d5)) +- Add MiniMax as a supported LLM provider. ([`2344484f`](https://github.com/vectorize-io/hindsight/commit/2344484f)) +- Add Jina MLX reranker provider optimized for Apple Silicon. ([`1caf5ec9`](https://github.com/vectorize-io/hindsight/commit/1caf5ec9)) + +**Improvements** + +- Allow configuring maximum recall query tokens via an environment variable. ([`66dedb8d`](https://github.com/vectorize-io/hindsight/commit/66dedb8d)) +- Improve retrieval performance by switching to per-bank HNSW indexes. ([`43b3efc4`](https://github.com/vectorize-io/hindsight/commit/43b3efc4)) + +**Bug Fixes** + +- Prevent reranking failures by truncating long documents that exceed LiteLLM reranker context limits. ([`eeb938fc`](https://github.com/vectorize-io/hindsight/commit/eeb938fc)) +- Ensure recalled memories are injected as system context for OpenClaw. ([`b17f338e`](https://github.com/vectorize-io/hindsight/commit/b17f338e)) +- Ensure embedded profiles are registered in CLI metadata when the daemon starts. ([`06b0f74a`](https://github.com/vectorize-io/hindsight/commit/06b0f74a)) +- Cancel in-flight async operations when a bank is deleted to avoid dangling work. ([`0560f626`](https://github.com/vectorize-io/hindsight/commit/0560f626)) + +## [0.4.17](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.17) + +**Features** + +- Added a manual retry option for failed asynchronous operations. ([`dcaacbe4`](https://github.com/vectorize-io/hindsight/commit/dcaacbe4)) +- You can now change/update tags on an existing document. ([`1b4ad7f4`](https://github.com/vectorize-io/hindsight/commit/1b4ad7f4)) +- Added history tracking and a diff view for mental model changes. ([`e2baca8b`](https://github.com/vectorize-io/hindsight/commit/e2baca8b)) +- Added observation history tracking with a UI diff view to review changes over time. ([`576473b6`](https://github.com/vectorize-io/hindsight/commit/576473b6)) +- File uploads can now choose a parser per request, with configurable fallback chains. ([`99220d05`](https://github.com/vectorize-io/hindsight/commit/99220d05)) +- Added an extension hook that runs after file-to-Markdown conversion completes. ([`1d17dea2`](https://github.com/vectorize-io/hindsight/commit/1d17dea2)) + +**Improvements** + +- Operations view now supports filtering by operation type and has more reliable auto-refresh behavior. ([`f7a60f89`](https://github.com/vectorize-io/hindsight/commit/f7a60f89)) +- Added token limits for “source facts” used during consolidation and recall to better control context usage. ([`5d05962d`](https://github.com/vectorize-io/hindsight/commit/5d05962d)) +- Improved bank selector usability by truncating very long bank names in the dropdown. ([`1e40cd22`](https://github.com/vectorize-io/hindsight/commit/1e40cd22)) + +**Bug Fixes** + +- Fixed webhook schema issues affecting multi-tenant retain webhooks. ([`32a4882a`](https://github.com/vectorize-io/hindsight/commit/32a4882a)) +- Fixed file ingestion failures by stripping null bytes from parsed file content before retaining. ([`cd3a6a22`](https://github.com/vectorize-io/hindsight/commit/cd3a6a22)) +- Fixed tool selection handling for OpenAI-compatible providers when using named tool_choice. ([`1cdfb7c2`](https://github.com/vectorize-io/hindsight/commit/1cdfb7c2)) +- Improved consolidation behavior to prioritize a bank’s mission over an ephemeral-state heuristic. ([`00ccf0b2`](https://github.com/vectorize-io/hindsight/commit/00ccf0b2)) +- Fixed database migrations to correctly handle mental model embedding dimension changes. ([`7accac94`](https://github.com/vectorize-io/hindsight/commit/7accac94)) +- Fixed file upload failures caused by an Iris parser httpx read timeout. ([`fa3501d4`](https://github.com/vectorize-io/hindsight/commit/fa3501d4)) +- Improved reliability of running migrations by serializing Alembic upgrades within the process. ([`f88b50a4`](https://github.com/vectorize-io/hindsight/commit/f88b50a4)) +- Fixed Google Cloud Storage authentication when using Workload Identity Federation credentials. ([`d2504ac5`](https://github.com/vectorize-io/hindsight/commit/d2504ac5)) +- Fixed the bank selector to refresh the bank list when the dropdown is opened. ([`0ad8c2d0`](https://github.com/vectorize-io/hindsight/commit/0ad8c2d0)) + +## [0.4.16](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.16) + +**Features** + +- Added Webhooks with `consolidation.completed` and `retain.completed` events. ([`abbf874d`](https://github.com/vectorize-io/hindsight/commit/abbf874d)) + +**Improvements** + +- Improved OpenClaw recall/retention controls. ([`d425e93c`](https://github.com/vectorize-io/hindsight/commit/d425e93c)) +- Improved search/reranking quality by switching combined scoring to multiplicative boosts. ([`aa8e5475`](https://github.com/vectorize-io/hindsight/commit/aa8e5475)) +- Improved performance of observation recall by 40x on large banks. ([`ad2cf72a`](https://github.com/vectorize-io/hindsight/commit/ad2cf72a)) +- Improved server shutdown behavior by capping graceful shutdown time and allowing a forced kill on a second Ctrl+C. ([`4c058b4b`](https://github.com/vectorize-io/hindsight/commit/4c058b4b)) + +**Bug Fixes** + +- Fixed an async deadlock risk by running database schema migrations in a background thread during startup. ([`e0a2ac63`](https://github.com/vectorize-io/hindsight/commit/e0a2ac63)) +- Fixed webhook delivery/outbox processing so transactions don’t silently roll back due to using the wrong database schema name. ([`75b95106`](https://github.com/vectorize-io/hindsight/commit/75b95106)) +- Fixed observation results to correctly resolve and return related chunks using source_memory_ids. ([`cb6d1c46`](https://github.com/vectorize-io/hindsight/commit/cb6d1c46)) +- Fixed MCP bank-level tool filtering compatibility with FastMCP 3.x. ([`f17406fd`](https://github.com/vectorize-io/hindsight/commit/f17406fd)) +- Fixed crashes when an LLM returns invalid JSON across all retries (now handled cleanly instead of raising a TypeError). ([`66423b85`](https://github.com/vectorize-io/hindsight/commit/66423b85)) +- Fixed observations without source dates to preserve missing (None) temporal fields instead of incorrectly populating them. ([`891c33b1`](https://github.com/vectorize-io/hindsight/commit/891c33b1)) + +## [0.4.15](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.15) + +**Features** + +- Added observation_scopes to control the granularity/visibility of observations. ([`55af4681`](https://github.com/vectorize-io/hindsight/commit/55af4681)) +- List documents API now supports filtering by tags (and fixes the q parameter description). ([`1d70abfe`](https://github.com/vectorize-io/hindsight/commit/1d70abfe)) +- Added PydanticAI integration for persistent agent memory. ([`cab5a40f`](https://github.com/vectorize-io/hindsight/commit/cab5a40f)) +- Added richer entity label support (optional labels, free-form values, multi-value fields, and UI polish). ([`9b96becc`](https://github.com/vectorize-io/hindsight/commit/9b96becc)) +- Added support for timestamp="unset" so content can be retained without a date. ([`f903948a`](https://github.com/vectorize-io/hindsight/commit/f903948a)) +- OpenClaw can now automatically retain the last n+2 turns every n turns (default n=10). ([`ad1660b3`](https://github.com/vectorize-io/hindsight/commit/ad1660b3)) +- Added configurable Gemini/Vertex AI safety settings for LLM calls. ([`73ef99e7`](https://github.com/vectorize-io/hindsight/commit/73ef99e7)) +- Added extension hooks to customize root routing and error headers. ([`e407f4bc`](https://github.com/vectorize-io/hindsight/commit/e407f4bc)) + +**Improvements** + +- Improved recall performance by fetching all recall chunks in a single query. ([`61bf428b`](https://github.com/vectorize-io/hindsight/commit/61bf428b)) +- Improved recall/retain performance and scalability for large memory banks. ([`7942f181`](https://github.com/vectorize-io/hindsight/commit/7942f181)) + +**Bug Fixes** + +- Fixed the TypeScript SDK to send null (not undefined) when includeEntities is false. ([`15f4b876`](https://github.com/vectorize-io/hindsight/commit/15f4b876)) +- Prevented reflect from failing with context_length_exceeded on large memory banks. ([`77defd96`](https://github.com/vectorize-io/hindsight/commit/77defd96)) +- Fixed a consolidation deadlock caused by retrying after zombie processing tasks. ([`c2876490`](https://github.com/vectorize-io/hindsight/commit/c2876490)) +- Fixed observations count in the control plane that always showed 0. ([`eaeaa1f2`](https://github.com/vectorize-io/hindsight/commit/eaeaa1f2)) +- Fixed ZeroEntropy rerank endpoint URL and ensured the MCP retain async_processing parameter is handled correctly. ([`f6f1a7d8`](https://github.com/vectorize-io/hindsight/commit/f6f1a7d8)) +- Fixed JSON serialization issues and logging-related exception propagation when using the claude_code LLM provider. ([`ecb833f4`](https://github.com/vectorize-io/hindsight/commit/ecb833f4)) +- Added bank-scoped request validation to prevent cross-bank/invalid bank operations. ([`5270aa5a`](https://github.com/vectorize-io/hindsight/commit/5270aa5a)) + +## [0.4.14](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.14) + +**Features** + +- Add Chat SDK integration to give chatbots persistent memory. ([`fed987f9`](https://github.com/vectorize-io/hindsight/commit/fed987f9)) +- Allow configuring which MCP tools are exposed per memory bank, and expand the MCP tool set with additional tools and parameters. ([`3ffec650`](https://github.com/vectorize-io/hindsight/commit/3ffec650)) +- Enable the bank configuration API by default. ([`4d030707`](https://github.com/vectorize-io/hindsight/commit/4d030707)) +- Support filtering graph-based memory retrieval by tags. ([`0bb5ca4c`](https://github.com/vectorize-io/hindsight/commit/0bb5ca4c)) +- Add batch observations consolidation to process multiple observations more efficiently. ([`0aa7c2b3`](https://github.com/vectorize-io/hindsight/commit/0aa7c2b3)) +- Add OpenClaw options to toggle autoRecall and exclude specific providers. ([`3f9eb27c`](https://github.com/vectorize-io/hindsight/commit/3f9eb27c)) +- Add a ZeroEntropy reranker provider option. ([`17259675`](https://github.com/vectorize-io/hindsight/commit/17259675)) + +**Improvements** + +- Increase customization options for reflect, retain, and consolidation behavior. ([`2a322732`](https://github.com/vectorize-io/hindsight/commit/2a322732)) +- Include source document metadata in fact extraction results. ([`87219b73`](https://github.com/vectorize-io/hindsight/commit/87219b73)) + +**Bug Fixes** + +- Raise a clear error when embedding dimensions exceed pgvector HNSW limits (instead of failing later at runtime). ([`8cd65b98`](https://github.com/vectorize-io/hindsight/commit/8cd65b98)) +- Fix multi-tenant schema isolation issues in storage and the bank config API. ([`b180b3ad`](https://github.com/vectorize-io/hindsight/commit/b180b3ad)) +- Ensure LiteLLM embedding calls use the correct float encoding format to prevent embedding failures. ([`58f2de70`](https://github.com/vectorize-io/hindsight/commit/58f2de70)) +- Improve recall performance by reducing memory usage during retrieval. ([`9f0c031d`](https://github.com/vectorize-io/hindsight/commit/9f0c031d)) +- Handle observation regeneration correctly when underlying memories are deleted. ([`ac9a94ad`](https://github.com/vectorize-io/hindsight/commit/ac9a94ad)) +- Fix reflect retrieval to correctly populate dependencies and enforce full hierarchical retrieval. ([`8b1a4658`](https://github.com/vectorize-io/hindsight/commit/8b1a4658)) +- Fix OpenClaw health checks by passing the auth token to the health endpoint. ([`40b02645`](https://github.com/vectorize-io/hindsight/commit/40b02645)) + +## [0.4.13](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.13) + +**Features** + +- Switched the default OpenAI LLM to gpt-4o-mini. ([`325b5cc1`](https://github.com/vectorize-io/hindsight/commit/325b5cc1)) +- Observation recall now includes the source facts behind recalled observations. ([`5569d4ad`](https://github.com/vectorize-io/hindsight/commit/5569d4ad)) +- Added CrewAI integration to enable persistent memory. ([`41db2960`](https://github.com/vectorize-io/hindsight/commit/41db2960)) + +**Bug Fixes** + +- Fixed npx hindsight-control-plane failing to run. ([`0758827d`](https://github.com/vectorize-io/hindsight/commit/0758827d)) +- Improved MCP compatibility by aligning the local MCP implementation with the server and removing the deprecated stateless parameter. ([`ea8163c5`](https://github.com/vectorize-io/hindsight/commit/ea8163c5)) +- Fixed Docker startup failures when using named Docker volumes. ([`ac739487`](https://github.com/vectorize-io/hindsight/commit/ac739487)) +- Prevented reranker crashes when an upstream provider returns an error. ([`58c4d657`](https://github.com/vectorize-io/hindsight/commit/58c4d657)) +- Improved accuracy of fact temporal ordering by reducing per-fact time offsets. ([`c3ef1555`](https://github.com/vectorize-io/hindsight/commit/c3ef1555)) +- Client timeout settings are now properly respected. ([`dcaa9f14`](https://github.com/vectorize-io/hindsight/commit/dcaa9f14)) +- Fixed documents not being tracked when fact extraction returns zero facts. ([`f78278ea`](https://github.com/vectorize-io/hindsight/commit/f78278ea)) + +## [0.4.12](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.12) + +**Features** + +- Accept and ingest PDFs, images, and common Office documents as inputs. ([`224b7b74`](https://github.com/vectorize-io/hindsight/commit/224b7b74)) +- Add the Iris file parser for improved document parsing support. ([`7eafba66`](https://github.com/vectorize-io/hindsight/commit/7eafba66)) +- Add async Retain support via provider Batch APIs (e.g., OpenAI and Groq) for higher-throughput ingestion. ([`40d42c58`](https://github.com/vectorize-io/hindsight/commit/40d42c58)) +- Allow Recall to return chunks only (no memories) by setting max_tokens=0. ([`7dad9da0`](https://github.com/vectorize-io/hindsight/commit/7dad9da0)) +- Add a Go client SDK for the Hindsight API. ([`2a47389f`](https://github.com/vectorize-io/hindsight/commit/2a47389f)) +- Add support for the pgvectorscale (DiskANN) vector index backend. ([`95c42204`](https://github.com/vectorize-io/hindsight/commit/95c42204)) +- Add support for Azure pg_diskann vector indexing. ([`476726c2`](https://github.com/vectorize-io/hindsight/commit/476726c2)) + +**Improvements** + +- Improve reliability of async batch Retain when ingesting large payloads. ([`aefb3fcf`](https://github.com/vectorize-io/hindsight/commit/aefb3fcf)) +- Improve AI SDK tooling to make it easier to work with Hindsight programmatically. ([`d06a0259`](https://github.com/vectorize-io/hindsight/commit/d06a0259)) + +**Bug Fixes** + +- Ensure document tags are preserved when using the async Retain flow. ([`b4b5c44a`](https://github.com/vectorize-io/hindsight/commit/b4b5c44a)) +- Fix OpenClaw ingestion failures for very large content (E2BIG). ([`6bad6673`](https://github.com/vectorize-io/hindsight/commit/6bad6673)) +- Harden OpenClaw behavior (safer shell usage, better HTTP mode handling, and more reliable initialization), including per-user banks support. ([`c4610130`](https://github.com/vectorize-io/hindsight/commit/c4610130)) +- Improve Python client async API consistency and reduce connection drop issues via keepalive timeout fixes. ([`8114ef44`](https://github.com/vectorize-io/hindsight/commit/8114ef44)) + +## [0.4.11](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.11) + +**Features** + +- Added support for LiteLLM SDK as an embeddings and reranking provider. ([`e408b7e`](https://github.com/vectorize-io/hindsight/commit/e408b7e)) +- Expanded Postgres search support with additional text/vector extensions, including TimescaleDB pg_textsearch and vchord/pgvector options. ([`d871c30`](https://github.com/vectorize-io/hindsight/commit/d871c30)) +- Added hierarchical configuration scopes (system, tenant, bank) for more flexible multi-tenant setup and overrides. ([`8d731f2`](https://github.com/vectorize-io/hindsight/commit/8d731f2)) +- Added reverse proxy/base-path support for running Hindsight behind a proxy. ([`93ddd41`](https://github.com/vectorize-io/hindsight/commit/93ddd41)) +- Added MCP tools to create, read, update, and delete mental models. ([`f641b30`](https://github.com/vectorize-io/hindsight/commit/f641b30)) +- Added a "docs" skill for agents/tools to access documentation-oriented capabilities. ([`dd1e098`](https://github.com/vectorize-io/hindsight/commit/dd1e098)) +- Added an OpenClaw configuration option to skip recall/retain for specific providers. ([`fb7be3e`](https://github.com/vectorize-io/hindsight/commit/fb7be3e)) + +**Improvements** + +- Improved LiteLLM gateway model configuration for more reliable provider/model selection. ([`7d95a00`](https://github.com/vectorize-io/hindsight/commit/7d95a00)) +- Exposed actual LLM token usage in retain results to improve cost/usage visibility. ([`83ca669`](https://github.com/vectorize-io/hindsight/commit/83ca669)) +- Added user-initiated attribution to request context to improve async task and usage attribution. ([`90be7c6`](https://github.com/vectorize-io/hindsight/commit/90be7c6)) +- Added OpenTelemetry tracing for improved request traceability and observability. ([`69dec8e`](https://github.com/vectorize-io/hindsight/commit/69dec8e)) +- Helm chart: split TEI embedding and reranker into separate deployments for independent scaling and rollout. ([`43f9a8b`](https://github.com/vectorize-io/hindsight/commit/43f9a8b)) +- Helm chart: added PodDisruptionBudgets and per-component affinity controls for more resilient scheduling. ([`9943957`](https://github.com/vectorize-io/hindsight/commit/9943957)) + +**Bug Fixes** + +- Fixed a recursion issue in memory retention that could cause failures or runaway memory usage. ([`4f11210`](https://github.com/vectorize-io/hindsight/commit/4f11210)) +- Fixed Reflect API serialization/schema issues for "based_on" so reflections are returned and stored correctly. ([`f9a8a8e`](https://github.com/vectorize-io/hindsight/commit/f9a8a8e)) +- Improved MCP server compatibility by allowing extra tool arguments when appropriate and fixing bank ID resolution priority. ([`7ee229b`](https://github.com/vectorize-io/hindsight/commit/7ee229b)) +- Added missing trust_code environment configuration support. ([`60574ee`](https://github.com/vectorize-io/hindsight/commit/60574ee)) +- Hardened the MCP server with fixes to routing/validation and more accurate usage metering. ([`e798979`](https://github.com/vectorize-io/hindsight/commit/e798979)) +- Fixed the slim Docker image to include tiktoken to prevent runtime tokenization errors. ([`6eec83b`](https://github.com/vectorize-io/hindsight/commit/6eec83b)) +- Fixed MCP operations not being tracked correctly for usage metering. ([`888b50d`](https://github.com/vectorize-io/hindsight/commit/888b50d)) +- Helm chart: fixed GKE deployments overriding the configured HINDSIGHT_API_PORT. ([`03f47e2`](https://github.com/vectorize-io/hindsight/commit/03f47e2)) + +## [0.4.10](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.10) + +**Features** + +- Provided a slimmer Docker distribution to reduce image size and speed up pulls. ([`f648178`](https://github.com/vectorize-io/hindsight/commit/f648178)) +- Added Markdown support in Reflect and Mental Models content. ([`c4ef090`](https://github.com/vectorize-io/hindsight/commit/c4ef090)) +- Added built-in Supabase tenant extension for running Hindsight with Supabase-backed multi-tenancy. ([`e99ee0f`](https://github.com/vectorize-io/hindsight/commit/e99ee0f)) +- Added TenantExtension authentication support to the MCP endpoint. ([`fedfb49`](https://github.com/vectorize-io/hindsight/commit/fedfb49)) + +**Improvements** + +- Improved MCP tool availability/routing based on the endpoint being used. ([`d90588b`](https://github.com/vectorize-io/hindsight/commit/d90588b)) + +**Bug Fixes** + +- Stopped logging database usernames and passwords to prevent credential leaks in logs. ([`c568094`](https://github.com/vectorize-io/hindsight/commit/c568094)) +- Fixed OpenClaw sessions wiping memory on each new session. ([`981cf60`](https://github.com/vectorize-io/hindsight/commit/981cf60)) +- Fixed hindsight-embed profiles not loading correctly. ([`0430588`](https://github.com/vectorize-io/hindsight/commit/0430588)) +- Fixed tagged directives so they correctly apply to tagged mental models. ([`278718d`](https://github.com/vectorize-io/hindsight/commit/278718d)) +- Fixed a cast error that could cause failures at runtime. ([`093ecff`](https://github.com/vectorize-io/hindsight/commit/093ecff)) + +**Other** + +- Added a docker-compose example to simplify local deployment and testing. ([`5179d5f`](https://github.com/vectorize-io/hindsight/commit/5179d5f)) + +## [0.4.9](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.9) + +**Features** + +- New AI SDK integration. ([`7e339e1`](https://github.com/vectorize-io/hindsight/commit/7e339e1)) +- Add a Python SDK for running Hindsight in embedded mode (HindsightEmbedded). ([`d3302c9`](https://github.com/vectorize-io/hindsight/commit/d3302c9)) +- Add streaming support to the hindsight-litellm wrappers. ([`665877b`](https://github.com/vectorize-io/hindsight/commit/665877b)) +- Add OpenClaw support for connecting to an external Hindsight API and using dynamic per-channel memory banks. ([`6b34692`](https://github.com/vectorize-io/hindsight/commit/6b34692)) + +**Improvements** + +- Improve the mental models experience in the control plane UI. ([`7097716`](https://github.com/vectorize-io/hindsight/commit/7097716)) +- Reduce noisy Hugging Face logging output. ([`34d9188`](https://github.com/vectorize-io/hindsight/commit/34d9188)) + +**Bug Fixes** + +- Improve recall endpoint reliability by handling timeouts correctly and rejecting overly long queries. ([`dd621a6`](https://github.com/vectorize-io/hindsight/commit/dd621a6)) +- Improve /reflect behavior with Claude Code and Codex providers. ([`a43d208`](https://github.com/vectorize-io/hindsight/commit/a43d208)) +- Fix OpenClaw shell argument escaping for more reliable command execution. ([`63e2964`](https://github.com/vectorize-io/hindsight/commit/63e2964)) + +## [0.4.8](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.8) + +**Features** + +- Added profile support for `hindsight-embed`, enabling separate embedding configurations/workspaces. ([`6c7f057`](https://github.com/vectorize-io/hindsight/commit/6c7f057)) +- Added support for additional LLM backends, including OpenAI Codex and Claude Code. ([`539190b`](https://github.com/vectorize-io/hindsight/commit/539190b)) + +**Improvements** + +- Enhanced OpenClaw and `hindsight-embed` parameter/config options for easier configuration and better defaults. ([`749478d`](https://github.com/vectorize-io/hindsight/commit/749478d)) +- Added OpenClaw plugin configuration options to select LLM provider and model. ([`8564135`](https://github.com/vectorize-io/hindsight/commit/8564135)) +- Server now prints its version during startup to simplify debugging and support requests. ([`1499ce5`](https://github.com/vectorize-io/hindsight/commit/1499ce5)) +- Improved tracing/debuggability by propagating request context through asynchronous background tasks. ([`44d9125`](https://github.com/vectorize-io/hindsight/commit/44d9125)) +- Added stronger validation and context for mental model create/refresh operations to prevent invalid requests. ([`35127d5`](https://github.com/vectorize-io/hindsight/commit/35127d5)) + +**Bug Fixes** + +- Improved embedding CLI experience with richer logs and isolated profiles to avoid cross-contamination between runs. ([`794a743`](https://github.com/vectorize-io/hindsight/commit/794a743)) +- Operation validation now runs correctly in the worker process, preventing invalid background operations from slipping through. ([`96f0e54`](https://github.com/vectorize-io/hindsight/commit/96f0e54)) +- Fixed unreliable behavior when using a custom PostgreSQL schema. ([`3825506`](https://github.com/vectorize-io/hindsight/commit/3825506)) + +## [0.4.7](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.7) + +**Features** + +- Add extension hooks to validate and customize mental model operations. ([`9c3fda7`](https://github.com/vectorize-io/hindsight/commit/9c3fda7)) +- Add support for using an external embedding API provider in OpenClaw plugin (with additional OpenClaw compatibility fixes). ([`4b57b82`](https://github.com/vectorize-io/hindsight/commit/4b57b82)) + +**Improvements** + +- Speed up container startup by preloading the tiktoken encoding during Docker image builds. ([`039944c`](https://github.com/vectorize-io/hindsight/commit/039944c)) + +**Bug Fixes** + +- Prevent PostgreSQL insert failures by stripping null bytes from text fields before saving. ([`ef9d3a1`](https://github.com/vectorize-io/hindsight/commit/ef9d3a1)) +- Fix worker schema selection so it uses the correct default database schema. ([`d788a55`](https://github.com/vectorize-io/hindsight/commit/d788a55)) +- Honor an already-set HINDSIGHT_API_DATABASE_URL instead of overwriting it in the hindsight-embed workflow. ([`f0cb192`](https://github.com/vectorize-io/hindsight/commit/f0cb192)) + +## [0.4.6](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.6) + +**Improvements** + +- Improved OpenClaw configuration setup to make embedding integration easier to configure. ([`27498f9`](https://github.com/vectorize-io/hindsight/commit/27498f9)) + +**Bug Fixes** + +- Fixed OpenClaw embedding version binding/versioning to prevent mismatches when using the embed integration. ([`1163b1f`](https://github.com/vectorize-io/hindsight/commit/1163b1f)) + +## [0.4.5](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.5) + +**Bug Fixes** + +- Fixed occasional failures when retaining memories asynchronously with timestamps. ([`cbb8fc6`](https://github.com/vectorize-io/hindsight/commit/cbb8fc6)) + +## [0.4.4](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.4) + +**Bug Fixes** + +- Fixed async “retain” operations failing when a timestamp is provided. ([`35f0984`](https://github.com/vectorize-io/hindsight/commit/35f0984)) +- Corrected the OpenClaw daemon integration name to “openclaw” (previously “openclawd”). ([`b364bc3`](https://github.com/vectorize-io/hindsight/commit/b364bc3)) + +## [0.4.3](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.3) + +**Features** + +- Add Vertex AI as a supported LLM provider. ([`c2ac7d0`](https://github.com/vectorize-io/hindsight/commit/c2ac7d0), [`49ae55a`](https://github.com/vectorize-io/hindsight/commit/49ae55a)) +- Add Bearer token authentication for MCP and propagate tenant authentication across MCP requests. ([`0da77ce`](https://github.com/vectorize-io/hindsight/commit/0da77ce)) + +**Improvements** + +- CLI: add a --wait flag for consolidate and a --date filter for listing documents. ([`ff20bf9`](https://github.com/vectorize-io/hindsight/commit/ff20bf9)) + +**Bug Fixes** + +- Fix worker polling deadlocks to prevent background processing from stalling. ([`f4f86e3`](https://github.com/vectorize-io/hindsight/commit/f4f86e3)) +- Improve reliability of Docker builds by retrying ML model downloads. ([`ecc590c`](https://github.com/vectorize-io/hindsight/commit/ecc590c)) +- Fix tenant authentication handling for internal background tasks and ensure the control-plane forwards required auth to the dataplane. ([`03bf13e`](https://github.com/vectorize-io/hindsight/commit/03bf13e)) +- Ensure tenant database migrations run at startup and workers use the correct tenant schema context. ([`657fe02`](https://github.com/vectorize-io/hindsight/commit/657fe02)) +- Fix control-plane graph endpoint errors when upstream data is missing. ([`751f99a`](https://github.com/vectorize-io/hindsight/commit/751f99a)) + +**Other** + +- Rename the default bot/user identity from "moltbot" to "openclaw". ([`728ce13`](https://github.com/vectorize-io/hindsight/commit/728ce13)) + +## [0.4.2](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.2) + +**Features** + +- Added Clawdbot/Moltbot/OpenClaw integration. ([`12e9a3d`](https://github.com/vectorize-io/hindsight/commit/12e9a3d)) + +**Improvements** + +- Added additional configuration options to control LLM retry behavior. ([`3f211f0`](https://github.com/vectorize-io/hindsight/commit/3f211f0)) +- Added real-time logs showing a detailed timing breakdown during consolidation runs. ([`8781c9f`](https://github.com/vectorize-io/hindsight/commit/8781c9f)) + +**Bug Fixes** + +- Fixed hindsight-embed crashing on macOS. ([`c16ccc2`](https://github.com/vectorize-io/hindsight/commit/c16ccc2)) + +## [0.4.1](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.1) + +**Features** + +- Added support for using a non-default PostgreSQL schema by default. ([`2b72e1f`](https://github.com/vectorize-io/hindsight/commit/2b72e1f)) + +**Improvements** + +- Improved memory consolidation performance (benchmarking and optimizations). ([`b43ef98`](https://github.com/vectorize-io/hindsight/commit/b43ef98)) + +**Bug Fixes** + +- Fixed the /version endpoint returning an incorrect version. ([`cfcc23c`](https://github.com/vectorize-io/hindsight/commit/cfcc23c)) +- Fixed mental model search failing due to UUID type mismatch after text-ID migration. ([`94cc0a1`](https://github.com/vectorize-io/hindsight/commit/94cc0a1)) +- Added safer PyTorch device detection to prevent crashes on some environments. ([`67c4788`](https://github.com/vectorize-io/hindsight/commit/67c4788)) +- Fixed Python packages exposing an incorrect __version__ value. ([`fccbdfe`](https://github.com/vectorize-io/hindsight/commit/fccbdfe)) + +## [0.4.0](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.0) + +**Observations**, **Mental Models**, new **Agentic Reflect** and Directives, read the announcement. + +**Features** + +- Added support for providing a custom prompt for memory extraction. ([`3172e99`](https://github.com/vectorize-io/hindsight/commit/3172e99)) +- Expanded the LiteLLM integration with async retain/reflect support, cleaner API, and support for tags/mission (including passing API keys correctly). ([`1d4879a`](https://github.com/vectorize-io/hindsight/commit/1d4879a)) +- Added a new worker service to run background tasks at scale. ([`4c79240`](https://github.com/vectorize-io/hindsight/commit/4c79240)) +- MCP retain now supports timestamps. ([`b378f68`](https://github.com/vectorize-io/hindsight/commit/b378f68)) +- Added support for installing skills via `npx add-skill`. ([`ec22317`](https://github.com/vectorize-io/hindsight/commit/ec22317)) + +**Improvements** + +- CLI retain-files now accepts more file types. ([`1eeced3`](https://github.com/vectorize-io/hindsight/commit/1eeced3)) + +**Bug Fixes** + +- Fixed a macOS crash in the embed daemon caused by an XPC connection issue. ([`e5fc6ee`](https://github.com/vectorize-io/hindsight/commit/e5fc6ee)) +- Fixed occasional extraction in the wrong language. ([`87d4a36`](https://github.com/vectorize-io/hindsight/commit/87d4a36)) +- Fixed PyTorch model initialization issues that could cause startup failures (meta tensor/init problems). ([`ddaa5f5`](https://github.com/vectorize-io/hindsight/commit/ddaa5f5)) + + +**Features** + +- Add memory tags so you can label and filter memories during recall/reflect. ([`20c8f8b`](https://github.com/vectorize-io/hindsight/commit/20c8f8b)) +- Allow choosing different AI providers/models per operation. ([`e6709d5`](https://github.com/vectorize-io/hindsight/commit/e6709d5)) +- Add Cohere support for embeddings and reranking. ([`4de0730`](https://github.com/vectorize-io/hindsight/commit/4de0730)) +- Add configurable embedding dimensions and OpenAI embeddings support. ([`70de23e`](https://github.com/vectorize-io/hindsight/commit/70de23e)) +- Support custom base URLs for OpenAI-style embeddings and Cohere endpoints. ([`fa53917`](https://github.com/vectorize-io/hindsight/commit/fa53917)) +- Add LiteLLM gateway support for routing LLM/embedding requests. ([`d47c8a2`](https://github.com/vectorize-io/hindsight/commit/d47c8a2)) +- Add multilingual content support to improve handling and retrieval across languages. ([`c65c6a9`](https://github.com/vectorize-io/hindsight/commit/c65c6a9)) +- Add delete memory bank capability. ([`4b82d2d`](https://github.com/vectorize-io/hindsight/commit/4b82d2d)) +- Add backup/restore tooling for memory banks. ([`67b273d`](https://github.com/vectorize-io/hindsight/commit/67b273d)) + +**Improvements** + +- Add retention modes to control how memories are extracted and stored. ([`fb31a35`](https://github.com/vectorize-io/hindsight/commit/fb31a35)) +- Add offline (optional) database migrations to support restricted/air-gapped deployments. ([`233bd2e`](https://github.com/vectorize-io/hindsight/commit/233bd2e)) +- Add database connection configuration options for more flexible deployments. ([`33fac2c`](https://github.com/vectorize-io/hindsight/commit/33fac2c)) +- Load .env automatically on startup to simplify configuration. ([`c06d9b4`](https://github.com/vectorize-io/hindsight/commit/c06d9b4)) +- Expose an operation ID from retain requests so async/background processing can be tracked. ([`1dacd0e`](https://github.com/vectorize-io/hindsight/commit/1dacd0e)) +- Add per-request LLM token usage metrics for monitoring and cost tracking. ([`29a542d`](https://github.com/vectorize-io/hindsight/commit/29a542d)) +- Add LLM call latency metrics for performance monitoring. ([`5e1f13e`](https://github.com/vectorize-io/hindsight/commit/5e1f13e)) +- Include tenant in metrics labels for better multi-tenant observability. ([`1ffc2a4`](https://github.com/vectorize-io/hindsight/commit/1ffc2a4)) +- Add async processing option to MCP retain tool for background retention workflows. ([`37fc7fb`](https://github.com/vectorize-io/hindsight/commit/37fc7fb)) + +**Bug Fixes** + +- Fix extension loading in multi-worker deployments so all workers load extensions correctly. ([`f5f3fca`](https://github.com/vectorize-io/hindsight/commit/f5f3fca)) +- Improve recall performance by batching recall queries. ([`5991308`](https://github.com/vectorize-io/hindsight/commit/5991308)) +- Improve retrieval quality and stability for large memory banks (graph/MPFP retrieval fixes). ([`6232e69`](https://github.com/vectorize-io/hindsight/commit/6232e69)) +- Fix entities list being limited to 100 entities. ([`26bf571`](https://github.com/vectorize-io/hindsight/commit/26bf571)) +- Fix UI only showing the first 1000 memories. ([`67c1a42`](https://github.com/vectorize-io/hindsight/commit/67c1a42)) +- Fix duplicated causal relationships and improve token usage during processing. ([`49e233c`](https://github.com/vectorize-io/hindsight/commit/49e233c)) +- Improve causal link detection accuracy. ([`2a00df0`](https://github.com/vectorize-io/hindsight/commit/2a00df0)) +- Make retain max completion tokens configurable to prevent truncation issues. ([`7715a51`](https://github.com/vectorize-io/hindsight/commit/7715a51)) +- Fix Python SDK not sending the Authorization header, preventing authenticated requests. ([`39e3f7c`](https://github.com/vectorize-io/hindsight/commit/39e3f7c)) +- Fix stats endpoint missing tenant authentication in multi-tenant setups. ([`d6ff191`](https://github.com/vectorize-io/hindsight/commit/d6ff191)) +- Fix embedding dimension handling for tenant schemas in multi-tenant databases. ([`6fe9314`](https://github.com/vectorize-io/hindsight/commit/6fe9314)) +- Fix Groq free-tier compatibility so requests work correctly. ([`d899d18`](https://github.com/vectorize-io/hindsight/commit/d899d18)) +- Fix security vulnerability (qs / CVE-2025-15284). ([`b3becb6`](https://github.com/vectorize-io/hindsight/commit/b3becb6)) +- Restore MCP tools for listing and creating memory banks. ([`9fd5679`](https://github.com/vectorize-io/hindsight/commit/9fd5679)) + +## [0.2.0](https://github.com/vectorize-io/hindsight/releases/tag/v0.2.0) + +**Features** + +- Add additional model provider support, including Anthropic Claude and LM Studio. ([`787ed60`](https://github.com/vectorize-io/hindsight/commit/787ed60)) +- Add multi-bank access and new MCP tools for interacting with multiple memory banks via MCP. ([`6b5f593`](https://github.com/vectorize-io/hindsight/commit/6b5f593)) +- Allow supplying custom entities when retaining memories via the retain endpoint. ([`dd59bc8`](https://github.com/vectorize-io/hindsight/commit/dd59bc8)) +- Enhance the /reflect endpoint with max_tokens control and optional structured output responses. ([`d49e820`](https://github.com/vectorize-io/hindsight/commit/d49e820)) + + +**Improvements** + +- Improve local LLM support for reasoning-capable models and streamline Docker startup for local deployments. ([`eea0f27`](https://github.com/vectorize-io/hindsight/commit/eea0f27)) +- Support operation validator extensions and return proper HTTP errors when validation fails. ([`ce45d30`](https://github.com/vectorize-io/hindsight/commit/ce45d30)) +- Add configurable observation thresholds to control when observations are created/updated. ([`54e2df0`](https://github.com/vectorize-io/hindsight/commit/54e2df0)) +- Improve graph visualization to the control plane for exploring memory relationships. ([`1a62069`](https://github.com/vectorize-io/hindsight/commit/1a62069)) + +**Bug Fixes** + +- Fix MCP server lifecycle handling so MCP lifespan is correctly tied to the FastAPI app lifespan. ([`6b78f7d`](https://github.com/vectorize-io/hindsight/commit/6b78f7d)) + +## [0.1.15](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.15) + +**Features** + +- Add the ability to delete documents from the web UI. ([`f7ff32d`](https://github.com/vectorize-io/hindsight/commit/f7ff32d)) + +**Improvements** + +- Improve the API health check endpoint and update the generated client APIs/types accordingly. ([`e06a612`](https://github.com/vectorize-io/hindsight/commit/e06a612)) + +## [0.1.14](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.14) + +**Bug Fixes** + +- Fixes the embedded “get-skill” installer so installing skills works correctly. ([`0b352d1`](https://github.com/vectorize-io/hindsight/commit/0b352d1)) + +## [0.1.13](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.13) + +**Improvements** + +- Improve reliability by surfacing task handler failures so retries can occur when processing fails. ([`904ea4d`](https://github.com/vectorize-io/hindsight/commit/904ea4d)) +- Revamp the hindsight-embed component architecture, including a new daemon/client model and CLI updates for embedding workflows. ([`e6511e7`](https://github.com/vectorize-io/hindsight/commit/e6511e7)) + +**Bug Fixes** + +- Fix memory retention so timestamps are correctly taken into account. ([`234d426`](https://github.com/vectorize-io/hindsight/commit/234d426)) + +## [0.1.12](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.12) + +**Features** + +- Added an extensions system for plugging in new operations/skills (including built-in tenant support). ([`2a0c490`](https://github.com/vectorize-io/hindsight/commit/2a0c490)) +- Introduced the hindsight-embed tool and a native agentic skill for embedding/agent workflows. ([`da44a5e`](https://github.com/vectorize-io/hindsight/commit/da44a5e)) + +**Improvements** + +- Improved reliability when parsing LLM JSON by retrying on parse errors and adding clearer diagnostics. ([`a831a7b`](https://github.com/vectorize-io/hindsight/commit/a831a7b)) + +**Bug Fixes** + +- Fixed structured-output support for Ollama-based LLM providers. ([`32bca12`](https://github.com/vectorize-io/hindsight/commit/32bca12)) +- Adjusted LLM validation to cap max completion tokens at 100 to prevent validation failures. ([`b94b5cf`](https://github.com/vectorize-io/hindsight/commit/b94b5cf)) + +## [0.1.11](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.11) + +**Bug Fixes** + +- Fixed the standalone Docker image and control plane standalone build process so standalone deployments build correctly. ([`2948cb6`](https://github.com/vectorize-io/hindsight/commit/2948cb6)) + +## [0.1.10](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.10) + +*This release contains internal maintenance and infrastructure changes only.* + + +## [0.1.9](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.9) + +**Features** + +- Simplified local MCP installation and added a standalone UI option for easier setup. ([`1c6acc3`](https://github.com/vectorize-io/hindsight/commit/1c6acc3)) + +**Bug Fixes** + +- Fixed the standalone Docker image so it builds and starts reliably. ([`b52eb90`](https://github.com/vectorize-io/hindsight/commit/b52eb90)) +- Improved Docker runtime reliability by adding required system utilities (procps). ([`ae80876`](https://github.com/vectorize-io/hindsight/commit/ae80876)) + +## [0.1.8](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.8) + +**Bug Fixes** + +- Fix bank list responses when a bank has no name. ([`04f01ab`](https://github.com/vectorize-io/hindsight/commit/04f01ab)) +- Fix failures when retaining memories asynchronously. ([`63f5138`](https://github.com/vectorize-io/hindsight/commit/63f5138)) +- Fix a race condition in the bank selector when switching banks. ([`e468a4e`](https://github.com/vectorize-io/hindsight/commit/e468a4e)) + +## [0.1.7](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.7) + +*This release contains internal maintenance and infrastructure changes only.* + +## [0.1.6](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.6) + +**Features** + +- Added support for the Gemini 3 Pro and GPT-5.2 models. ([`bb1f9cb`](https://github.com/vectorize-io/hindsight/commit/bb1f9cb)) +- Added a local MCP server option for running/connecting to Hindsight via MCP without a separate remote service. ([`7dd6853`](https://github.com/vectorize-io/hindsight/commit/7dd6853)) + +**Improvements** + +- Updated the Postgres/pg0 dependency to a newer 0.11.x series for improved compatibility and stability. ([`47be07f`](https://github.com/vectorize-io/hindsight/commit/47be07f)) + +## [0.1.5](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.5) + +**Features** + +- Added LiteLLM integration so Hindsight can capture and manage memories from LiteLLM-based LLM calls. ([`dfccbf2`](https://github.com/vectorize-io/hindsight/commit/dfccbf2)) +- Added an optional graph-based retriever (MPFP) to improve recall by leveraging relationships between memories. ([`7445cef`](https://github.com/vectorize-io/hindsight/commit/7445cef)) + +**Improvements** + +- Switched the embedded Postgres layer to pg0-embedded for a smoother local/standalone experience. ([`94c2b85`](https://github.com/vectorize-io/hindsight/commit/94c2b85)) + +**Bug Fixes** + +- Fixed repeated retries on 400 errors from the LLM, preventing unnecessary request loops and failures. ([`70983f5`](https://github.com/vectorize-io/hindsight/commit/70983f5)) +- Fixed recall trace visualization in the control plane so search/recall debugging displays correctly. ([`922164e`](https://github.com/vectorize-io/hindsight/commit/922164e)) +- Fixed the CLI installer to make installation more reliable. ([`158a6aa`](https://github.com/vectorize-io/hindsight/commit/158a6aa)) +- Updated Next.js to patch security vulnerabilities (CVE-2025-55184, CVE-2025-55183). ([`f018cc5`](https://github.com/vectorize-io/hindsight/commit/f018cc5)) + +## [0.1.3](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.3) + +**Improvements** + +- Improved CLI and UI branding/polish, including new banner/logo assets and updated interface styling. ([`fa554b8`](https://github.com/vectorize-io/hindsight/commit/fa554b8)) + + +## [0.1.2](https://github.com/vectorize-io/hindsight/releases/tag/v0.1.2) + +**Bug Fixes** + +- Fixed the standalone Docker image so it builds/runs correctly. ([`1056a20`](https://github.com/vectorize-io/hindsight/commit/1056a20)) diff --git a/skills/hindsight-docs/references/developer/api/memory-banks.md b/skills/hindsight-docs/references/developer/api/memory-banks.md index 8f9fee68..01c3f7dd 100644 --- a/skills/hindsight-docs/references/developer/api/memory-banks.md +++ b/skills/hindsight-docs/references/developer/api/memory-banks.md @@ -44,7 +44,7 @@ hindsight bank create my-bank ## Bank Configuration -Each memory bank can be configured independently per operation. Configuration can be set via the [bank config API](#updating-configuration), the [Control Plane UI](/), or [server-wide environment variables](/developer/configuration). +Each memory bank can be configured independently per operation. Configuration can be set via the [bank config API](#updating-configuration), the Control Plane UI, or [server-wide environment variables](../configuration.md). ### retain_mission {#retain-configuration} @@ -77,7 +77,7 @@ Maximum number of characters per chunk when splitting content for fact extractio Default: `3000` -See [Retain configuration](/developer/configuration#retain) for environment variable names and defaults. +See [Retain configuration](../configuration.md#retain) for environment variable names and defaults. ### entity_labels {#entity-labels} @@ -172,7 +172,7 @@ Total token budget for source facts included with observations in the consolidat Per-observation token cap for source facts in the consolidation prompt. Each observation independently gets at most this many tokens of source facts, preventing a single observation with many source facts from consuming the entire budget. `-1` = unlimited. Leave unset to use the server default (`256`). -See [Observations configuration](/developer/configuration#observations) for environment variable names and defaults. +See [Observations configuration](../configuration.md#observations) for environment variable names and defaults. ### reflect_mission @@ -344,7 +344,7 @@ await client.resetBankConfig('my-bank'); This removes all bank-level overrides. The bank reverts to server-wide defaults (set via environment variables). -You can also update configuration directly from the [Control Plane UI](/) — navigate to a bank and open the **Configuration** tab. +You can also update configuration directly from the Control Plane UI — navigate to a bank and open the **Configuration** tab. --- diff --git a/skills/hindsight-docs/references/developer/api/mental-models.md b/skills/hindsight-docs/references/developer/api/mental-models.md index bdbaee44..a2535bb5 100644 --- a/skills/hindsight-docs/references/developer/api/mental-models.md +++ b/skills/hindsight-docs/references/developer/api/mental-models.md @@ -316,5 +316,5 @@ History tracking is enabled by default. Set `HINDSIGHT_API_ENABLE_MENTAL_MODEL_H ## Next Steps - [**Reflect**](./reflect) — How the agentic loop uses mental models -- [**Observations**](/developer/observations) — How knowledge is consolidated +- [**Observations**](../observations.md) — How knowledge is consolidated - [**Operations**](./operations) — Track async mental model creation diff --git a/skills/hindsight-docs/references/developer/api/quickstart.md b/skills/hindsight-docs/references/developer/api/quickstart.md index dea9e3c8..92f91ede 100644 --- a/skills/hindsight-docs/references/developer/api/quickstart.md +++ b/skills/hindsight-docs/references/developer/api/quickstart.md @@ -41,7 +41,7 @@ docker run --rm -it --pull always -p 8888:8888 -p 9999:9999 \ > **💡 LLM Provider** > Hindsight requires an LLM with structured output support. Recommended: **Groq** with `gpt-oss-20b` for fast, cost-effective inference. -See [LLM Providers](/developer/models#llm) for more details. +See [LLM Providers](../models.md#llm) for more details. --- ## Use the Client @@ -127,4 +127,4 @@ hindsight memory reflect my-bank "Tell me about Alice" - [**Recall**](./recall) — Search and retrieval strategies - [**Reflect**](./reflect) — Disposition-aware reasoning - [**Memory Banks**](./memory-banks) — Configure disposition and mission -- [**Server Deployment**](/developer/installation) — Docker Compose, Helm, and production setup +- [**Server Deployment**](../installation.md) — Docker Compose, Helm, and production setup diff --git a/skills/hindsight-docs/references/developer/api/recall.md b/skills/hindsight-docs/references/developer/api/recall.md index d7ec1027..8c9065dd 100644 --- a/skills/hindsight-docs/references/developer/api/recall.md +++ b/skills/hindsight-docs/references/developer/api/recall.md @@ -8,7 +8,7 @@ When you **recall**, Hindsight runs four retrieval strategies in parallel — se {/* Import raw source files */} :::info How Recall Works -Learn about the four retrieval strategies (semantic, keyword, graph, temporal) and RRF fusion in the [Recall Architecture](/developer/retrieval) guide. +Learn about the four retrieval strategies (semantic, keyword, graph, temporal) and RRF fusion in the [Recall Architecture](../retrieval.md) guide. > **💡 Prerequisites** > Make sure you've completed the [Quick Start](./quickstart) to install the client and start the server. diff --git a/skills/hindsight-docs/references/developer/api/reflect.md b/skills/hindsight-docs/references/developer/api/reflect.md index 110b5c8b..d82af8de 100644 --- a/skills/hindsight-docs/references/developer/api/reflect.md +++ b/skills/hindsight-docs/references/developer/api/reflect.md @@ -8,7 +8,7 @@ When you call **reflect**, Hindsight runs an agentic loop that autonomously sear {/* Import raw source files */} :::info How Reflect Works -Learn about disposition-driven reasoning in the [Reflect Architecture](/developer/reflect) guide. +Learn about disposition-driven reasoning in the [Reflect Architecture](../reflect.md) guide. > **💡 Prerequisites** > Make sure you've completed the [Quick Start](./quickstart) to install the client and start the server. diff --git a/skills/hindsight-docs/references/developer/api/retain.md b/skills/hindsight-docs/references/developer/api/retain.md index 84d095fa..189a0b94 100644 --- a/skills/hindsight-docs/references/developer/api/retain.md +++ b/skills/hindsight-docs/references/developer/api/retain.md @@ -8,7 +8,7 @@ When you **retain** content, Hindsight doesn't just store the raw text—it inte {/* Import raw source files */} :::info How Retain Works -Learn about fact extraction, entity resolution, and graph construction in the [Retain Architecture](/developer/retain) guide. +Learn about fact extraction, entity resolution, and graph construction in the [Retain Architecture](../retain.md) guide. > **💡 Prerequisites** > Make sure you've completed the [Quick Start](./quickstart) to install the client and start the server. diff --git a/skills/hindsight-docs/references/developer/configuration.md b/skills/hindsight-docs/references/developer/configuration.md index 89640614..3e371327 100644 --- a/skills/hindsight-docs/references/developer/configuration.md +++ b/skills/hindsight-docs/references/developer/configuration.md @@ -574,7 +574,7 @@ Controls the retain (memory ingestion) pipeline. | `HINDSIGHT_API_RETAIN_BATCH_ENABLED` | Use LLM Batch API for fact extraction (50% cost savings, only with async operations) | `false` | | `HINDSIGHT_API_RETAIN_BATCH_POLL_INTERVAL_SECONDS` | Batch API polling interval in seconds | `60` | -> **Entity labels** (`entity_labels`) and **free-form entity extraction** (`entities_allow_free_form`) are configured per bank via the [bank config API](/developer/api/memory-banks#retain-configuration), not as global environment variables — each bank can have its own controlled vocabulary. See [Entity Labels](/developer/retain#entity-labels) for details. +> **Entity labels** (`entity_labels`) and **free-form entity extraction** (`entities_allow_free_form`) are configured per bank via the [bank config API](api/memory-banks.md#retain-configuration), not as global environment variables — each bank can have its own controlled vocabulary. See [Entity Labels](retain.md#entity-labels) for details. #### Customizing retain: when to use what diff --git a/skills/hindsight-docs/references/developer/index.md b/skills/hindsight-docs/references/developer/index.md index 9191df56..468a8117 100644 --- a/skills/hindsight-docs/references/developer/index.md +++ b/skills/hindsight-docs/references/developer/index.md @@ -122,22 +122,22 @@ These settings only affect the `reflect` operation, not `recall`. ## Next Steps ### Getting Started -- [**Quick Start**](/developer/api/quickstart) — Install and get up and running in 60 seconds -- [**RAG vs Hindsight**](/developer/rag-vs-hindsight) — See how Hindsight differs from traditional RAG with real examples +- [**Quick Start**](api/quickstart.md) — Install and get up and running in 60 seconds +- [**RAG vs Hindsight**](rag-vs-hindsight.md) — See how Hindsight differs from traditional RAG with real examples ### Core Concepts -- [**Retain**](/developer/retain) — How memories are stored with multi-dimensional facts -- [**Recall**](/developer/retrieval) — How TEMPR's 4-way search retrieves memories -- [**Reflect**](/developer/reflect) — How mission, directives, and disposition shape reasoning +- [**Retain**](retain.md) — How memories are stored with multi-dimensional facts +- [**Recall**](retrieval.md) — How TEMPR's 4-way search retrieves memories +- [**Reflect**](reflect.md) — How mission, directives, and disposition shape reasoning ### API Methods -- [**Retain**](/developer/api/retain) — Store information in memory banks -- [**Recall**](/developer/api/recall) — Search and retrieve memories -- [**Reflect**](/developer/api/reflect) — Agentic reasoning with memory -- [**Mental Models**](/developer/api/mental-models) — User-curated summaries for common queries -- [**Memory Banks**](/developer/api/memory-banks) — Configure mission, directives, and disposition -- [**Documents**](/developer/api/documents) — Manage document sources -- [**Operations**](/developer/api/operations) — Monitor async tasks +- [**Retain**](api/retain.md) — Store information in memory banks +- [**Recall**](api/recall.md) — Search and retrieve memories +- [**Reflect**](api/reflect.md) — Agentic reasoning with memory +- [**Mental Models**](api/mental-models.md) — User-curated summaries for common queries +- [**Memory Banks**](api/memory-banks.md) — Configure mission, directives, and disposition +- [**Documents**](api/documents.md) — Manage document sources +- [**Operations**](api/operations.md) — Monitor async tasks ### Deployment -- [**Server Setup**](/developer/installation) — Deploy with Docker Compose, Helm, or pip +- [**Server Setup**](installation.md) — Deploy with Docker Compose, Helm, or pip diff --git a/skills/hindsight-docs/references/developer/models.md b/skills/hindsight-docs/references/developer/models.md index cc124052..98e2d01d 100644 --- a/skills/hindsight-docs/references/developer/models.md +++ b/skills/hindsight-docs/references/developer/models.md @@ -32,7 +32,7 @@ See [Configuration](./configuration#llm-provider) for setup examples. Not sure which model to use? The **[Model Leaderboard](https://benchmarks.hindsight.vectorize.io/)** benchmarks models across accuracy, speed, cost, and reliability for retain, reflect, and observation consolidation so you can pick the right trade-off for your use case. -[![Model Leaderboard](/img/leaderboard.png)](https://benchmarks.hindsight.vectorize.io/) +[](https://benchmarks.hindsight.vectorize.io/) ### Tested Models diff --git a/skills/hindsight-docs/references/developer/observations.md b/skills/hindsight-docs/references/developer/observations.md index 5a02d3f4..f3c1a3a1 100644 --- a/skills/hindsight-docs/references/developer/observations.md +++ b/skills/hindsight-docs/references/developer/observations.md @@ -120,7 +120,7 @@ observations = client.recall( The reflect agent uses **hierarchical retrieval**: -1. **[Mental Models](/developer/api/mental-models)** — User-curated summaries (highest priority) +1. **[Mental Models](api/mental-models.md)** — User-curated summaries (highest priority) 2. **Observations** — Consolidated knowledge with freshness awareness 3. **Raw Facts** — Ground truth for verification @@ -168,7 +168,7 @@ Leave it blank to use the server default — durable, specific facts that stay t | *"Observations are stable facts about named individuals only"* | Person-centric knowledge, tied to specific people | | *"Observations are recurring patterns in customer support interactions"* | Failure modes, common requests, pain points | -Set `observations_mission` via the [bank config API](/developer/api/memory-banks#observations-configuration) or the [`HINDSIGHT_API_OBSERVATIONS_MISSION`](/developer/configuration#observations) environment variable. +Set `observations_mission` via the [bank config API](api/memory-banks.md#observations-configuration) or the [`HINDSIGHT_API_OBSERVATIONS_MISSION`](configuration.md#observations) environment variable. --- diff --git a/skills/hindsight-docs/references/developer/reflect.md b/skills/hindsight-docs/references/developer/reflect.md index 1acbe04c..5e800cd4 100644 --- a/skills/hindsight-docs/references/developer/reflect.md +++ b/skills/hindsight-docs/references/developer/reflect.md @@ -55,11 +55,11 @@ The agent: The agent uses a smart retrieval hierarchy: -1. **[Mental Models](/developer/api/mental-models)** — User-curated summaries you've pre-computed for common queries -2. **[Observations](/developer/observations)** — Consolidated knowledge with freshness awareness +1. **[Mental Models](api/mental-models.md)** — User-curated summaries you've pre-computed for common queries +2. **[Observations](observations.md)** — Consolidated knowledge with freshness awareness 3. **Raw Facts** — Ground truth for verification when observations are stale -**Mental models** are saved reflect responses that you create for frequently asked questions. They're checked first because they represent explicitly curated knowledge. See the [Mental Models API](/developer/api/mental-models) for how to create and manage them. +**Mental models** are saved reflect responses that you create for frequently asked questions. They're checked first because they represent explicitly curated knowledge. See the [Mental Models API](api/mental-models.md) for how to create and manage them. If an observation is marked as **stale**, the agent automatically verifies it against current facts. @@ -132,7 +132,7 @@ The reflect mission frames how the agent reasons and responds: - Keeps reasoning consistent across conversations :::info Per-operation missions -The reflect mission only affects `reflect()`. To steer what gets extracted during `retain()`, use [`retain_mission`](/developer/api/memory-banks#retain-configuration). To control what gets synthesised into observations, use [`observations_mission`](/developer/api/memory-banks#observations-configuration). +The reflect mission only affects `reflect()`. To steer what gets extracted during `retain()`, use [`retain_mission`](api/memory-banks.md#retain-configuration). To control what gets synthesised into observations, use [`observations_mission`](api/memory-banks.md#observations-configuration). --- ## Disposition Shapes Reasoning @@ -187,7 +187,7 @@ Use directives for constraints that must never be violated: :::tip Use disposition for personality and character. Use directives for compliance and guardrails. -See [Memory Banks: Directives](/developer/api/memory-banks#directives) for how to create and manage directives. +See [Memory Banks: Directives](api/memory-banks.md#directives) for how to create and manage directives. --- diff --git a/skills/hindsight-docs/references/developer/retain.md b/skills/hindsight-docs/references/developer/retain.md index 4966ef6f..78f845dd 100644 --- a/skills/hindsight-docs/references/developer/retain.md +++ b/skills/hindsight-docs/references/developer/retain.md @@ -94,7 +94,7 @@ If "Alice" appears with "Google" and "Stanford" multiple times, a new "Alice" me You can define a controlled vocabulary of `key:value` classification labels (e.g. `pedagogy:scaffolding`, `engagement:active`) that are extracted at retain time and stored as entities. Because labels become entities, they automatically link related memories in the knowledge graph and improve both semantic and keyword retrieval. Labels can optionally also write to the memory unit's tags, enabling standard tag-based filtering during recall and reflect. -See [entity_labels in the bank config](/developer/api/memory-banks#entity-labels) for full configuration details. +See [entity_labels in the bank config](api/memory-banks.md#entity-labels) for full configuration details. --- @@ -201,7 +201,7 @@ For finer control, you can also change the **extraction mode**: | `verbose` | When you need richer facts with full context and relationships | | `custom` | When you want to write your own extraction rules entirely | -Set `retain_mission` and `retain_extraction_mode` via the [bank config API](/developer/api/memory-banks#retain-configuration) or the [`HINDSIGHT_API_RETAIN_MISSION`](/developer/configuration#retain) environment variable. +Set `retain_mission` and `retain_extraction_mode` via the [bank config API](api/memory-banks.md#retain-configuration) or the [`HINDSIGHT_API_RETAIN_MISSION`](configuration.md#retain) environment variable. --- diff --git a/skills/hindsight-docs/references/faq.md b/skills/hindsight-docs/references/faq.md index af272f57..2bcc3a29 100644 --- a/skills/hindsight-docs/references/faq.md +++ b/skills/hindsight-docs/references/faq.md @@ -28,7 +28,7 @@ Hindsight is an agent memory system that provides long-term memory for AI agents - **Supports temporal reasoning** with time-aware retrieval - **Enables disposition-aware reflection** for nuanced reasoning -For a detailed comparison, see [RAG vs Memory](/developer/rag-vs-hindsight). +For a detailed comparison, see [RAG vs Memory](developer/rag-vs-hindsight.md). --- @@ -65,7 +65,7 @@ Unlike vector databases (just search) or RAG systems (document retrieval), Hinds -See [Models](/developer/models) for the full list of supported providers, recommended models, and configuration examples. +See [Models](developer/models.md) for the full list of supported providers, recommended models, and configuration examples. --- @@ -73,9 +73,9 @@ See [Models](/developer/models) for the full list of supported providers, recomm The **[Model Leaderboard](https://benchmarks.hindsight.vectorize.io/)** benchmarks models across accuracy, speed, cost, and reliability for retain, reflect, and observation consolidation — it's the best place to find the right trade-off for your use case. -[![Model Leaderboard](/img/leaderboard.png)](https://benchmarks.hindsight.vectorize.io/) +[](https://benchmarks.hindsight.vectorize.io/) -See [Models](/developer/models) for the full list of supported and tested models, provider defaults, and configuration examples. +See [Models](developer/models.md) for the full list of supported and tested models, provider defaults, and configuration examples. --- @@ -86,7 +86,7 @@ No! You have two options: 1. **Hindsight Cloud** - Fully managed service at [ui.hindsight.vectorize.io](https://ui.hindsight.vectorize.io) 2. **Self-hosted** - Deploy on your own infrastructure using Docker or direct installation -See [Installation](/developer/installation) for self-hosting instructions. +See [Installation](developer/installation.md) for self-hosting instructions. --- @@ -97,7 +97,7 @@ For running the Hindsight API server locally: - 4GB RAM minimum (8GB recommended for production) - LLM API key (OpenAI, Anthropic, etc.) or local LLM setup -See [Installation](/developer/installation) for setup instructions. +See [Installation](developer/installation.md) for setup instructions. --- @@ -120,7 +120,7 @@ There are two approaches for multi-user applications: - Filter by tags during recall/reflect for per-user queries - **Advantage**: Enables both per-user AND cross-user queries (e.g., analyze specific users or aggregate across all users) -Choose per-user banks for simplicity and privacy, or single bank with tags if you need holistic reasoning across users. See [Memory Banks](/developer/api/memory-banks) for management details. +Choose per-user banks for simplicity and privacy, or single bank with tags if you need holistic reasoning across users. See [Memory Banks](developer/api/memory-banks.md) for management details. --- @@ -132,7 +132,7 @@ Hindsight has three core operations: - **Recall**: Search and retrieve raw memory data based on a query - **Reflect**: Use an AI agent to answer a query using retrieved memories -See [Operations](/developer/api/operations) for API details. +See [Operations](developer/api/operations.md) for API details. --- @@ -162,7 +162,7 @@ reflect("What should I order for Alice?") → "I'd recommend a vegetarian sushi platter — Alice loves sushi and prefers vegetarian options." # grounded answer ``` -See [Recall](/developer/api/recall) and [Reflect](/developer/reflect) for full API details. +See [Recall](developer/api/recall.md) and [Reflect](developer/reflect.md) for full API details. --- @@ -174,7 +174,7 @@ See [Recall](/developer/api/recall) and [Reflect](/developer/reflect) for full A - Long-term behavioral patterns (e.g., "Customer is price-sensitive but values quality") - Context for AI agent reasoning during **reflect** operations -Mental models are automatically built during retain and used by reflect to provide richer, more contextual responses. See [Mental Models](/developer/api/mental-models). +Mental models are automatically built during retain and used by reflect to provide richer, more contextual responses. See [Mental Models](developer/api/mental-models.md). --- @@ -184,7 +184,7 @@ Typical latencies: - **Without reranking**: 50-100ms - **With reranking**: 200-500ms (depends on reranker model and installation) -See [Performance](/developer/performance) for tuning options. +See [Performance](developer/performance.md) for tuning options. --- @@ -203,7 +203,7 @@ client.retain(bank_id="my-bank", items=[{ client.recall(bank_id="my-bank", query="...", tags=["user:alice"]) ``` -See [Tags](/developer/api/retain#tags-and-document_tags) for full details including document-level tagging. +See [Tags](developer/api/retain.md#tags-and-document_tags) for full details including document-level tagging. **What about filtering by entities?** @@ -227,7 +227,7 @@ If you need explicit tag-based filtering on entity-like values, use **entity lab client.recall(bank_id="my-bank", query="...", tags=["user:alice"]) ``` -See [Entity Labels](/developer/retain#entity-labels) for configuration details. +See [Entity Labels](developer/retain.md#entity-labels) for configuration details. **What about document `metadata`?** diff --git a/skills/hindsight-docs/references/sdks/cli.md b/skills/hindsight-docs/references/sdks/cli.md index 36380ff6..29bd93f8 100644 --- a/skills/hindsight-docs/references/sdks/cli.md +++ b/skills/hindsight-docs/references/sdks/cli.md @@ -4,7 +4,7 @@ sidebar_position: 4 # CLI Reference -The Hindsight CLI provides command-line access to memory operations and bank management. All commands follow the [OpenAPI specification](/api-reference), so you can use `--help` on any command to see all available options. +The Hindsight CLI provides command-line access to memory operations and bank management. All commands follow the [OpenAPI specification](../openapi.json), so you can use `--help` on any command to see all available options. ## Installation diff --git a/skills/hindsight-docs/references/sdks/embed.md b/skills/hindsight-docs/references/sdks/embed.md index 7b1ba402..9c56338f 100644 --- a/skills/hindsight-docs/references/sdks/embed.md +++ b/skills/hindsight-docs/references/sdks/embed.md @@ -244,4 +244,4 @@ hindsight-embed configure - High-availability requirements - Multi-tenant applications -For production deployments, use the [API Service](/developer/services) with external PostgreSQL instead. +For production deployments, use the [API Service](../developer/services.md) with external PostgreSQL instead. diff --git a/skills/hindsight-docs/references/sdks/integrations/local-mcp.md b/skills/hindsight-docs/references/sdks/integrations/local-mcp.md index 524b2b2f..05dd4bfd 100644 --- a/skills/hindsight-docs/references/sdks/integrations/local-mcp.md +++ b/skills/hindsight-docs/references/sdks/integrations/local-mcp.md @@ -132,11 +132,11 @@ The local server exposes the full tool set (29 tools in multi-bank mode, 26 in s | `list_banks` | List all memory banks (multi-bank only) | | `create_bank` | Create or configure a memory bank (multi-bank only) | -For detailed parameter documentation, see the [MCP Server reference](/developer/mcp-server#available-tools). +For detailed parameter documentation, see the [MCP Server reference](../../developer/mcp-server.md#available-tools). ## Environment Variables -All standard [Hindsight configuration variables](/developer/configuration) are supported. Key ones for local use: +All standard [Hindsight configuration variables](../../developer/configuration.md) are supported. Key ones for local use: | Variable | Required | Default | Description | |----------|----------|---------|-------------| From 14e1cd267ec9322a59359dca5dfce7b8debabb5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Nicol=C3=B2=20Boschi?= Date: Thu, 19 Mar 2026 11:33:32 +0100 Subject: [PATCH 6/6] fix(skill): handle changelog as directory, add agno/hermes integrations, rebase on main --- scripts/generate-docs-skill.sh | 36 ++- skills/hindsight-docs/SKILL.md | 2 +- .../{changelog.md => changelog/index.md} | 33 +++ .../changelog/integrations/ai-sdk.md | 11 + .../references/changelog/integrations/chat.md | 11 + .../changelog/integrations/crewai.md | 11 + .../changelog/integrations/litellm.md | 11 + .../changelog/integrations/openclaw.md | 11 + .../changelog/integrations/pydantic-ai.md | 11 + .../references/developer/api/documents.md | 36 +++ .../references/developer/api/main-methods.md | 41 ++- .../references/developer/api/memory-banks.md | 121 +++++++++ .../references/developer/api/mental-models.md | 237 ++++++++++++++++-- .../references/developer/api/quickstart.md | 10 + .../references/developer/api/recall.md | 182 ++++++++++++++ .../references/developer/api/reflect.md | 73 ++++++ .../references/developer/api/retain.md | 137 ++++++++-- .../references/developer/configuration.md | 2 - .../references/sdks/integrations/agno.md | 186 ++++++++++++++ .../references/sdks/integrations/hermes.md | 219 ++++++++++++++++ 20 files changed, 1317 insertions(+), 64 deletions(-) rename skills/hindsight-docs/references/{changelog.md => changelog/index.md} (94%) create mode 100644 skills/hindsight-docs/references/changelog/integrations/ai-sdk.md create mode 100644 skills/hindsight-docs/references/changelog/integrations/chat.md create mode 100644 skills/hindsight-docs/references/changelog/integrations/crewai.md create mode 100644 skills/hindsight-docs/references/changelog/integrations/litellm.md create mode 100644 skills/hindsight-docs/references/changelog/integrations/openclaw.md create mode 100644 skills/hindsight-docs/references/changelog/integrations/pydantic-ai.md create mode 100644 skills/hindsight-docs/references/sdks/integrations/agno.md create mode 100644 skills/hindsight-docs/references/sdks/integrations/hermes.md diff --git a/scripts/generate-docs-skill.sh b/scripts/generate-docs-skill.sh index a8a70030..19b7d223 100755 --- a/scripts/generate-docs-skill.sh +++ b/scripts/generate-docs-skill.sh @@ -159,7 +159,7 @@ done # Process standalone pages (e.g. best-practices, faq) from src/pages/ print_info "Processing standalone pages..." -for page in best-practices faq changelog; do +for page in best-practices faq; do for ext in md mdx; do src="$PAGES_DIR/$page.$ext" if [ -f "$src" ]; then @@ -175,6 +175,38 @@ for page in best-practices faq changelog; do done done +# Process changelog — may be a single file or a directory +if [ -f "$PAGES_DIR/changelog.md" ] || [ -f "$PAGES_DIR/changelog.mdx" ]; then + for ext in md mdx; do + src="$PAGES_DIR/changelog.$ext" + if [ -f "$src" ]; then + dest="$REFS_DIR/changelog.md" + mkdir -p "$(dirname "$dest")" + if [[ "$src" == *.mdx ]]; then + convert_mdx_to_md "$src" "$dest" + else + cp "$src" "$dest" + fi + print_info "Included page: changelog.$ext" + fi + done +elif [ -d "$PAGES_DIR/changelog" ]; then + find "$PAGES_DIR/changelog" -type f \( -name "*.md" -o -name "*.mdx" \) | while read -r file; do + rel="${file#$PAGES_DIR/}" + dest="$REFS_DIR/$rel" + if [[ "$file" == *.mdx ]]; then + dest="${dest%.mdx}.md" + fi + mkdir -p "$(dirname "$dest")" + if [[ "$file" == *.mdx ]]; then + convert_mdx_to_md "$file" "$dest" + else + cp "$file" "$dest" + fi + print_info "Included changelog: ${file#$PAGES_DIR/changelog/}" + done +fi + # Copy OpenAPI spec into the skill OPENAPI_SRC="$ROOT_DIR/hindsight-docs/static/openapi.json" if [ -f "$OPENAPI_SRC" ]; then @@ -217,7 +249,7 @@ All documentation is in `references/` organized by category: references/ ├── best-practices.md # START HERE — missions, tags, formats, anti-patterns ├── faq.md # Common questions and decisions -├── changelog.md # Release history and version changes +├── changelog/ # Release history and version changes (index.md + integrations/) ├── openapi.json # Full OpenAPI spec — endpoint schemas, request/response models ├── developer/ │ ├── api/ # Core operations: retain, recall, reflect, memory banks diff --git a/skills/hindsight-docs/SKILL.md b/skills/hindsight-docs/SKILL.md index 09b6ae6a..6ffad3ea 100644 --- a/skills/hindsight-docs/SKILL.md +++ b/skills/hindsight-docs/SKILL.md @@ -28,7 +28,7 @@ All documentation is in `references/` organized by category: references/ ├── best-practices.md # START HERE — missions, tags, formats, anti-patterns ├── faq.md # Common questions and decisions -├── changelog.md # Release history and version changes +├── changelog/ # Release history and version changes (index.md + integrations/) ├── openapi.json # Full OpenAPI spec — endpoint schemas, request/response models ├── developer/ │ ├── api/ # Core operations: retain, recall, reflect, memory banks diff --git a/skills/hindsight-docs/references/changelog.md b/skills/hindsight-docs/references/changelog/index.md similarity index 94% rename from skills/hindsight-docs/references/changelog.md rename to skills/hindsight-docs/references/changelog/index.md index 1d7e8730..3371b96b 100644 --- a/skills/hindsight-docs/references/changelog.md +++ b/skills/hindsight-docs/references/changelog/index.md @@ -8,6 +8,39 @@ This changelog highlights user-facing changes only. Internal maintenance, CI/CD, For full release details, see [GitHub Releases](https://github.com/vectorize-io/hindsight/releases). +## Integration Changelogs + +| Integration | Package | Description | +|---|---|---| +| [LiteLLM](integrations/litellm.md) | `hindsight-litellm` | Universal LLM memory via LiteLLM (100+ providers) | +| [Pydantic AI](integrations/pydantic-ai.md) | `hindsight-pydantic-ai` | Persistent memory tools for Pydantic AI agents | +| [CrewAI](integrations/crewai.md) | `hindsight-crewai` | Persistent memory for CrewAI agents | +| [AI SDK](integrations/ai-sdk.md) | `@vectorize-io/hindsight-ai-sdk` | Memory integration for Vercel AI SDK | +| [Chat SDK](integrations/chat.md) | `@vectorize-io/hindsight-chat` | Memory integration for Vercel Chat SDK | +| [OpenClaw](integrations/openclaw.md) | `@vectorize-io/hindsight-openclaw` | Hindsight memory plugin for OpenClaw | + +## [0.4.19](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.19) + +**Features** + +- TypeScript client now works in Deno environments. ([`72c25c97`](https://github.com/vectorize-io/hindsight/commit/72c25c97)) +- Added Agno integration to use Hindsight as a memory toolkit. ([`8c378b98`](https://github.com/vectorize-io/hindsight/commit/8c378b98)) +- Added Hermes Agent integration (hindsight-hermes) for persistent memory. ([`ef90842f`](https://github.com/vectorize-io/hindsight/commit/ef90842f)) +- Expanded retain behavior with new `verbatim` and `chunks` extraction modes and named retain strategies. ([`e4f8a157`](https://github.com/vectorize-io/hindsight/commit/e4f8a157)) + +**Improvements** + +- Improved local reranker performance/efficiency with FP16 and bucketed batching, plus compatibility with Transformers 5.x. ([`e7da7d0e`](https://github.com/vectorize-io/hindsight/commit/e7da7d0e)) + +**Bug Fixes** + +- Prevented silent memory loss when consolidation fails (failed consolidations are tracked and can be recovered). ([`28dac7c7`](https://github.com/vectorize-io/hindsight/commit/28dac7c7)) +- Fixed Docker control-plane startup to respect the configured control-plane hostname. ([`8a64dc8d`](https://github.com/vectorize-io/hindsight/commit/8a64dc8d)) +- Database cleanup migration now removes orphaned observation memory units to avoid inconsistent memory state. ([`f09ad9de`](https://github.com/vectorize-io/hindsight/commit/f09ad9de)) +- Deleting a document now also deletes linked memory units to prevent leftover/stale memory entries. ([`f27bd953`](https://github.com/vectorize-io/hindsight/commit/f27bd953)) +- Fixed MCP middleware to send an Accept header, preventing 406 response errors in some setups. ([`836fd81e`](https://github.com/vectorize-io/hindsight/commit/836fd81e)) +- Improved compatibility with Gemini tool-calling by preserving thought signature metadata to avoid failures on gemini-3.1-flash-lite-preview. ([`21f9f46c`](https://github.com/vectorize-io/hindsight/commit/21f9f46c)) + ## [0.4.18](https://github.com/vectorize-io/hindsight/releases/tag/v0.4.18) **Features** diff --git a/skills/hindsight-docs/references/changelog/integrations/ai-sdk.md b/skills/hindsight-docs/references/changelog/integrations/ai-sdk.md new file mode 100644 index 00000000..88904c38 --- /dev/null +++ b/skills/hindsight-docs/references/changelog/integrations/ai-sdk.md @@ -0,0 +1,11 @@ +--- +hide_table_of_contents: true +--- + +# AI SDK Integration Changelog + +Changelog for [`@vectorize-io/hindsight-ai-sdk`](https://www.npmjs.com/package/@vectorize-io/hindsight-ai-sdk) — memory integration for Vercel AI SDK. + +For the source code, see [`hindsight-integrations/ai-sdk`](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/ai-sdk). + +← [Back to main changelog](../index.md) diff --git a/skills/hindsight-docs/references/changelog/integrations/chat.md b/skills/hindsight-docs/references/changelog/integrations/chat.md new file mode 100644 index 00000000..bf146550 --- /dev/null +++ b/skills/hindsight-docs/references/changelog/integrations/chat.md @@ -0,0 +1,11 @@ +--- +hide_table_of_contents: true +--- + +# Chat SDK Integration Changelog + +Changelog for [`@vectorize-io/hindsight-chat`](https://www.npmjs.com/package/@vectorize-io/hindsight-chat) — memory integration for Vercel Chat SDK. + +For the source code, see [`hindsight-integrations/chat`](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/chat). + +← [Back to main changelog](../index.md) diff --git a/skills/hindsight-docs/references/changelog/integrations/crewai.md b/skills/hindsight-docs/references/changelog/integrations/crewai.md new file mode 100644 index 00000000..0a5a08cc --- /dev/null +++ b/skills/hindsight-docs/references/changelog/integrations/crewai.md @@ -0,0 +1,11 @@ +--- +hide_table_of_contents: true +--- + +# CrewAI Integration Changelog + +Changelog for [`hindsight-crewai`](https://pypi.org/project/hindsight-crewai/) — persistent memory for CrewAI agents. + +For the source code, see [`hindsight-integrations/crewai`](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/crewai). + +← [Back to main changelog](../index.md) diff --git a/skills/hindsight-docs/references/changelog/integrations/litellm.md b/skills/hindsight-docs/references/changelog/integrations/litellm.md new file mode 100644 index 00000000..f5d18623 --- /dev/null +++ b/skills/hindsight-docs/references/changelog/integrations/litellm.md @@ -0,0 +1,11 @@ +--- +hide_table_of_contents: true +--- + +# LiteLLM Integration Changelog + +Changelog for [`hindsight-litellm`](https://pypi.org/project/hindsight-litellm/) — universal LLM memory integration via LiteLLM. + +For the source code, see [`hindsight-integrations/litellm`](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/litellm). + +← [Back to main changelog](../index.md) diff --git a/skills/hindsight-docs/references/changelog/integrations/openclaw.md b/skills/hindsight-docs/references/changelog/integrations/openclaw.md new file mode 100644 index 00000000..c6f1a779 --- /dev/null +++ b/skills/hindsight-docs/references/changelog/integrations/openclaw.md @@ -0,0 +1,11 @@ +--- +hide_table_of_contents: true +--- + +# OpenClaw Integration Changelog + +Changelog for [`@vectorize-io/hindsight-openclaw`](https://www.npmjs.com/package/@vectorize-io/hindsight-openclaw) — Hindsight memory plugin for OpenClaw. + +For the source code, see [`hindsight-integrations/openclaw`](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/openclaw). + +← [Back to main changelog](../index.md) diff --git a/skills/hindsight-docs/references/changelog/integrations/pydantic-ai.md b/skills/hindsight-docs/references/changelog/integrations/pydantic-ai.md new file mode 100644 index 00000000..e23f751f --- /dev/null +++ b/skills/hindsight-docs/references/changelog/integrations/pydantic-ai.md @@ -0,0 +1,11 @@ +--- +hide_table_of_contents: true +--- + +# Pydantic AI Integration Changelog + +Changelog for [`hindsight-pydantic-ai`](https://pypi.org/project/hindsight-pydantic-ai/) — persistent memory tools for Pydantic AI agents. + +For the source code, see [`hindsight-integrations/pydantic-ai`](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/pydantic-ai). + +← [Back to main changelog](../index.md) diff --git a/skills/hindsight-docs/references/developer/api/documents.md b/skills/hindsight-docs/references/developer/api/documents.md index 09a44334..a32aebec 100644 --- a/skills/hindsight-docs/references/developer/api/documents.md +++ b/skills/hindsight-docs/references/developer/api/documents.md @@ -79,6 +79,12 @@ hindsight memory retain my-bank "Meeting notes content..." --doc-id notes-2024-0 hindsight memory retain-files my-bank docs/ ``` +### Go + +```go +# Section 'document-retain' not found in api/documents.go +``` + ## Update Documents Re-retaining with the same document_id **replaces** the old content: @@ -125,6 +131,12 @@ hindsight memory retain my-bank "Project deadline: March 31" --doc-id project-pl hindsight memory retain my-bank "Project deadline: April 15 (extended)" --doc-id project-plan ``` +### Go + +```go +# Section 'document-update' not found in api/documents.go +``` + ## Get Document Retrieve a document's original text and metadata. This is useful for expanding document context after a recall operation returns memories with document references. @@ -179,6 +191,12 @@ console.log(`Created: ${doc.created_at}`); hindsight document get my-bank meeting-2024-03-15 ``` +### Go + +```go +# Section 'document-get' not found in api/documents.go +``` + ## Update Document Update mutable fields on an existing document without re-processing the content. Currently supports updating `tags`. @@ -225,6 +243,12 @@ hindsight document update-tags my-bank meeting-2024-03-15 --tags team-a --tags t hindsight document update-tags my-bank meeting-2024-03-15 ``` +### Go + +```go +# Section 'document-update' not found in api/documents.go +``` + :::info Observations are re-consolidated When tags change, any consolidated observations derived from the document's memories are invalidated and queued for re-consolidation under the new tags. Co-source memories from other documents that shared those observations are also reset. ## Delete Document @@ -271,6 +295,12 @@ console.log(`Deleted ${deleteResult.memory_units_deleted} memories`); hindsight document delete my-bank meeting-2024-03-15 ``` +### Go + +```go +# Section 'document-delete' not found in api/documents.go +``` + :::warning Deleting a document permanently removes all memories extracted from it. This action cannot be undone. ## List Documents @@ -373,6 +403,12 @@ hindsight document list my-bank --q report hindsight document list my-bank --tags team-a --tags team-b ``` +### Go + +```go +# Section 'document-list' not found in api/documents.go +``` + ### Filtering Options | Parameter | Description | diff --git a/skills/hindsight-docs/references/developer/api/main-methods.md b/skills/hindsight-docs/references/developer/api/main-methods.md index 941e1d1f..03ad0bff 100644 --- a/skills/hindsight-docs/references/developer/api/main-methods.md +++ b/skills/hindsight-docs/references/developer/api/main-methods.md @@ -76,13 +76,19 @@ await client.retainBatch('my-bank', [ ```bash # Store a single fact -hindsight retain my-bank "Alice joined Google in March 2024 as a Senior ML Engineer" +hindsight memory retain my-bank "Alice joined Google in March 2024 as a Senior ML Engineer" # Store from a file -hindsight retain my-bank --file conversation.txt --context "Daily standup" +hindsight memory retain-files my-bank conversation.txt --context "Daily standup" # Store multiple files -hindsight retain my-bank --files docs/*.md +hindsight memory retain-files my-bank docs/ +``` + +### Go + +```go +# Section 'main-retain' not found in api/main-methods.go ``` **What happens:** Content is processed by an LLM to extract rich facts, identify entities, and build connections in a knowledge graph. @@ -166,16 +172,22 @@ for (const [entityId, entity] of Object.entries(entityResults.entities || {})) { ```bash # Basic search -hindsight recall my-bank "What does Alice do at Google?" +hindsight memory recall my-bank "What does Alice do at Google?" # Search with options -hindsight recall my-bank "What happened last spring?" \ +hindsight memory recall my-bank "What happened last spring?" \ --budget high \ --max-tokens 8192 \ - --fact-type world + --fact-type world,experience + +# Verbose output +hindsight memory recall my-bank "Tell me about Alice" -v +``` -# Verbose output (shows weights and sources) -hindsight recall my-bank "Tell me about Alice" -v +### Go + +```go +# Section 'main-recall' not found in api/main-methods.go ``` **What happens:** Four search strategies (semantic, keyword, graph, temporal) run in parallel, results are fused and reranked. @@ -238,13 +250,16 @@ for (const fact of detailedResponse.based_on || []) { ```bash # Basic reflect -hindsight reflect my-bank "Should we adopt TypeScript for our backend?" - -# Verbose output (shows sources and observations) -hindsight reflect my-bank "What are Alice's strengths for the team lead role?" -v +hindsight memory reflect my-bank "Should we adopt TypeScript for our backend?" # With higher reasoning budget -hindsight reflect my-bank "Analyze our tech stack" --budget high +hindsight memory reflect my-bank "Analyze our tech stack" --budget high +``` + +### Go + +```go +# Section 'main-reflect' not found in api/main-methods.go ``` **What happens:** Memories and observations are recalled, bank disposition is applied, and the LLM reasons through the evidence to generate a response. diff --git a/skills/hindsight-docs/references/developer/api/memory-banks.md b/skills/hindsight-docs/references/developer/api/memory-banks.md index 01c3f7dd..30f32a20 100644 --- a/skills/hindsight-docs/references/developer/api/memory-banks.md +++ b/skills/hindsight-docs/references/developer/api/memory-banks.md @@ -42,6 +42,12 @@ await client.createBank('my-bank'); hindsight bank create my-bank ``` +### Go + +```go +# Section 'create-bank' not found in api/memory-banks.go +``` + ## Bank Configuration Each memory bank can be configured independently per operation. Configuration can be set via the [bank config API](#updating-configuration), the Control Plane UI, or [server-wide environment variables](../configuration.md). @@ -214,6 +220,22 @@ await client.updateBankConfig('architect-bank', { }); ``` +### CLI + +```bash +hindsight bank create architect-bank \ + --mission "You're a senior software architect - keep track of system designs, technology decisions, and architectural patterns. Prefer simplicity over cutting-edge." \ + --skepticism 4 \ + --literalism 4 \ + --empathy 2 +``` + +### Go + +```go +# Section 'bank-with-disposition' not found in api/memory-banks.go +``` + | Value | Behaviour | |-------|-----------| | `1` | Trusting — accepts information at face value | @@ -300,6 +322,24 @@ await client.updateBankConfig('my-bank', { }); ``` +### CLI + +```bash +hindsight bank set-config my-bank \ + --retain-mission "Always include technical decisions, API design choices, and architectural trade-offs. Ignore meeting logistics and social exchanges." \ + --retain-extraction-mode verbose \ + --observations-mission "Observations are stable facts about people and projects. Always include preferences, skills, and recurring patterns. Ignore one-off events." \ + --disposition-skepticism 4 \ + --disposition-literalism 4 \ + --disposition-empathy 2 +``` + +### Go + +```go +# Section 'update-bank-config' not found in api/memory-banks.go +``` + You can update any subset of fields — only the keys you provide are changed. ### Reading the Current Configuration @@ -322,6 +362,22 @@ const { config, overrides } = await client.getBankConfig('my-bank'); // overrides — only fields overridden at the bank level ``` +### CLI + +```bash +# Returns resolved config (server defaults merged with bank overrides) +hindsight bank config my-bank + +# Show only bank-specific overrides +hindsight bank config my-bank --overrides-only +``` + +### Go + +```go +# Section 'get-bank-config' not found in api/memory-banks.go +``` + The response distinguishes: - **`config`** — the fully resolved configuration (server defaults merged with bank overrides) - **`overrides`** — only the fields explicitly overridden for this bank @@ -342,6 +398,19 @@ client.reset_bank_config("my-bank") await client.resetBankConfig('my-bank'); ``` +### CLI + +```bash +# Remove all bank-level overrides, reverting to server defaults +hindsight bank reset-config my-bank -y +``` + +### Go + +```go +# Section 'reset-bank-config' not found in api/memory-banks.go +``` + This removes all bank-level overrides. The bank reverts to server-wide defaults (set via environment variables). You can also update configuration directly from the Control Plane UI — navigate to a bank and open the **Configuration** tab. @@ -391,6 +460,21 @@ const directive = await client.createDirective( console.log(`Created directive: ${directive.id}`); ``` +### CLI + +```bash +# Create a directive (hard rule for reflect) +hindsight directive create "$BANK_ID" \ + "Formal Language" \ + "Always respond in formal English, avoiding slang and colloquialisms." +``` + +### Go + +```go +# Section 'create-directive' not found in api/directives.go +``` + ### Listing Directives ### Python @@ -414,6 +498,19 @@ for (const d of directives.items) { } ``` +### CLI + +```bash +# List all directives in a bank +hindsight directive list "$BANK_ID" +``` + +### Go + +```go +# Section 'list-directives' not found in api/directives.go +``` + ### Updating Directives ### Python @@ -440,6 +537,18 @@ const updated = await client.updateDirective(BANK_ID, directiveId, { console.log(`Directive active: ${updated.is_active}`); ``` +### CLI + +```bash +# Section 'update-directive' not found in api/directives.sh +``` + +### Go + +```go +# Section 'update-directive' not found in api/directives.go +``` + ### Deleting Directives ### Python @@ -459,6 +568,18 @@ client.delete_directive( await client.deleteDirective(BANK_ID, directiveId); ``` +### CLI + +```bash +# Section 'delete-directive' not found in api/directives.sh +``` + +### Go + +```go +# Section 'delete-directive' not found in api/directives.go +``` + ### Directives vs Disposition | Aspect | Directives | Disposition | diff --git a/skills/hindsight-docs/references/developer/api/mental-models.md b/skills/hindsight-docs/references/developer/api/mental-models.md index a2535bb5..d7eccb8c 100644 --- a/skills/hindsight-docs/references/developer/api/mental-models.md +++ b/skills/hindsight-docs/references/developer/api/mental-models.md @@ -59,20 +59,34 @@ result = client.create_mental_model( print(f"Operation ID: {result.operation_id}") ``` +### Node.js + +```javascript +// Create a mental model (runs reflect in background) +const result = await client.createMentalModel( + BANK_ID, + 'Team Communication Preferences', + 'How does the team prefer to communicate?', + { tags: ['team', 'communication'] }, +); + +// Returns an operation_id — check operations endpoint for completion +console.log(`Operation ID: ${result.operation_id}`); +``` + ### CLI ```bash -# Create a mental model (async operation) -curl -X POST "http://localhost:8888/v1/default/banks/my-bank/mental-models" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Team Communication Preferences", - "source_query": "How does the team prefer to communicate?", - "tags": ["team"] - }' +# Create a mental model (runs reflect in background) +hindsight mental-model create "$BANK_ID" \ + "Team Communication Preferences" \ + "How does the team prefer to communicate?" +``` + +### Go -# Response: {"operation_id": "op-123"} -# Use the operations endpoint to check completion +```go +# Section 'create-mental-model' not found in api/mental-models.go ``` ### Parameters @@ -81,12 +95,65 @@ curl -X POST "http://localhost:8888/v1/default/banks/my-bank/mental-models" \ |-----------|------|----------|-------------| | `name` | string | Yes | Human-readable name for the mental model | | `source_query` | string | Yes | The query to run to generate content | +| `id` | string | No | Custom ID for the mental model (alphanumeric lowercase with hyphens). Auto-generated if omitted. | | `tags` | list | No | Tags for filtering during retrieval | | `max_tokens` | int | No | Maximum tokens for the mental model content | | `trigger` | object | No | Trigger settings (see [Automatic Refresh](#automatic-refresh)) | --- +## Create with Custom ID + +Assign a stable, human-readable ID to a mental model so you can retrieve or update it by name instead of relying on the auto-generated UUID: + +### Python + +```python +# Create a mental model with a specific custom ID +result_with_id = client.create_mental_model( + bank_id=BANK_ID, + name="Communication Policy", + source_query="What are the team's communication guidelines?", + id="communication-policy" +) + +print(f"Created with custom ID: {result_with_id.operation_id}") +``` + +### Node.js + +```javascript +// Create a mental model with a specific custom ID +const resultWithId = await client.createMentalModel( + BANK_ID, + 'Communication Policy', + "What are the team's communication guidelines?", + { id: 'communication-policy' }, +); + +console.log(`Created with custom ID: ${resultWithId.operation_id}`); +``` + +### CLI + +```bash +# Create a mental model with a specific custom ID +hindsight mental-model create "$BANK_ID" \ + "Communication Policy" \ + "What are the team's communication guidelines?" \ + --id communication-policy +``` + +### Go + +```go +# Section 'create-mental-model-with-id' not found in api/mental-models.go +``` + +:::tip +Custom IDs must be lowercase alphanumeric and may contain hyphens (e.g. `team-policies`, `q4-status`). If a mental model with that ID already exists, the request is rejected. +--- + ## Automatic Refresh Mental models can be configured to **automatically refresh** when observations are updated. This keeps them in sync with the latest knowledge without manual intervention. @@ -114,17 +181,34 @@ result = client.create_mental_model( print(f"Operation ID: {result.operation_id}") ``` +### Node.js + +```javascript +// Create a mental model with automatic refresh enabled +const result2 = await client.createMentalModel( + BANK_ID, + 'Project Status', + 'What is the current project status?', + { trigger: { refreshAfterConsolidation: true } }, +); + +// This mental model will automatically refresh when observations are updated +console.log(`Operation ID: ${result2.operation_id}`); +``` + ### CLI ```bash -# Create a mental model with automatic refresh enabled -curl -X POST "http://localhost:8888/v1/default/banks/my-bank/mental-models" \ - -H "Content-Type: application/json" \ - -d '{ - "name": "Project Status", - "source_query": "What is the current project status?", - "trigger": {"refresh_after_consolidation": true} - }' +# Create a mental model and get its ID for subsequent operations +hindsight mental-model create "$BANK_ID" \ + "Project Status" \ + "What is the current project status?" +``` + +### Go + +```go +# Section 'create-mental-model-with-trigger' not found in api/mental-models.go ``` ### When to Use Automatic Refresh @@ -152,10 +236,28 @@ for mental_model in mental_models.items: print(f"- {mental_model.name}: {mental_model.source_query}") ``` +### Node.js + +```javascript +// List all mental models in a bank +const mentalModels = await client.listMentalModels(BANK_ID); + +for (const mm of mentalModels.items) { + console.log(`- ${mm.name}: ${mm.source_query}`); +} +``` + ### CLI ```bash -curl "http://localhost:8888/v1/default/banks/my-bank/mental-models" +# List all mental models in a bank +hindsight mental-model list "$BANK_ID" +``` + +### Go + +```go +# Section 'list-mental-models' not found in api/mental-models.go ``` --- @@ -168,10 +270,27 @@ curl "http://localhost:8888/v1/default/banks/my-bank/mental-models" # Section 'get-mental-model' not found in api/mental-models.py ``` +### Node.js + +```javascript +// Get a specific mental model +const mentalModel = await client.getMentalModel(BANK_ID, mentalModelId); + +console.log(`Name: ${mentalModel.name}`); +console.log(`Content: ${mentalModel.content}`); +console.log(`Last refreshed: ${mentalModel.last_refreshed_at}`); +``` + ### CLI ```bash -curl "http://localhost:8888/v1/default/banks/my-bank/mental-models/{mental_model_id}" +# Section 'get-mental-model' not found in api/mental-models.sh +``` + +### Go + +```go +# Section 'get-mental-model' not found in api/mental-models.go ``` ### Response Fields @@ -200,10 +319,25 @@ Re-run the source query to update the mental model with current knowledge: # Section 'refresh-mental-model' not found in api/mental-models.py ``` +### Node.js + +```javascript +// Refresh a mental model to update with current knowledge +const refreshResult = await client.refreshMentalModel(BANK_ID, mentalModelId); + +console.log(`Refresh operation ID: ${refreshResult.operation_id}`); +``` + ### CLI ```bash -curl -X POST "http://localhost:8888/v1/default/banks/my-bank/mental-models/{mental_model_id}/refresh" +# Section 'refresh-mental-model' not found in api/mental-models.sh +``` + +### Go + +```go +# Section 'refresh-mental-model' not found in api/mental-models.go ``` Refreshing is useful when: @@ -223,12 +357,28 @@ Update the mental model's name: # Section 'update-mental-model' not found in api/mental-models.py ``` +### Node.js + +```javascript +// Update a mental model's metadata +const updated = await client.updateMentalModel(BANK_ID, mentalModelId, { + name: 'Updated Team Communication Preferences', + trigger: { refresh_after_consolidation: true }, +}); + +console.log(`Updated name: ${updated.name}`); +``` + ### CLI ```bash -curl -X PATCH "http://localhost:8888/v1/default/banks/my-bank/mental-models/{mental_model_id}" \ - -H "Content-Type: application/json" \ - -d '{"name": "Updated Team Communication Preferences"}' +# Section 'update-mental-model' not found in api/mental-models.sh +``` + +### Go + +```go +# Section 'update-mental-model' not found in api/mental-models.go ``` --- @@ -241,10 +391,23 @@ curl -X PATCH "http://localhost:8888/v1/default/banks/my-bank/mental-models/{men # Section 'delete-mental-model' not found in api/mental-models.py ``` +### Node.js + +```javascript +// Delete a mental model +await client.deleteMentalModel(BANK_ID, mentalModelId); +``` + ### CLI ```bash -curl -X DELETE "http://localhost:8888/v1/default/banks/my-bank/mental-models/{mental_model_id}" +# Section 'delete-mental-model' not found in api/mental-models.sh +``` + +### Go + +```go +# Section 'delete-mental-model' not found in api/mental-models.go ``` --- @@ -287,6 +450,30 @@ Every time a mental model's content changes (via refresh or manual update), the # Section 'get-mental-model-history' not found in api/mental-models.py ``` +### Node.js + +```javascript +// Get the change history of a mental model +const history = await client.getMentalModelHistory(BANK_ID, mentalModelId); + +for (const entry of history) { + console.log(`Changed at: ${entry.changed_at}`); + console.log(`Previous content: ${entry.previous_content}`); +} +``` + +### CLI + +```bash +# Section 'get-mental-model-history' not found in api/mental-models.sh +``` + +### Go + +```go +# Section 'get-mental-model-history' not found in api/mental-models.go +``` + ### Response The endpoint returns a list of history entries, most recent first: diff --git a/skills/hindsight-docs/references/developer/api/quickstart.md b/skills/hindsight-docs/references/developer/api/quickstart.md index 92f91ede..7616341e 100644 --- a/skills/hindsight-docs/references/developer/api/quickstart.md +++ b/skills/hindsight-docs/references/developer/api/quickstart.md @@ -105,6 +105,16 @@ hindsight memory recall my-bank "What does Alice do?" hindsight memory reflect my-bank "Tell me about Alice" ``` +### Go + +```bash +go get github.com/vectorize-io/hindsight/hindsight-clients/go +``` + +```go +# Section 'quickstart-full' not found in api/quickstart.go +``` + --- ## What's Happening diff --git a/skills/hindsight-docs/references/developer/api/recall.md b/skills/hindsight-docs/references/developer/api/recall.md index 8c9065dd..405ed623 100644 --- a/skills/hindsight-docs/references/developer/api/recall.md +++ b/skills/hindsight-docs/references/developer/api/recall.md @@ -72,6 +72,12 @@ const response = await client.recall('my-bank', 'What does Alice do?'); hindsight memory recall my-bank "What does Alice do?" ``` +### Go + +```go +# Section 'recall-basic' not found in api/recall.go +``` + --- ## Parameters @@ -113,12 +119,36 @@ observations = client.recall( ) ``` +### Node.js + +```javascript +await client.recall('my-bank', 'query', { types: ['world'] }); +``` +```javascript +await client.recall('my-bank', 'query', { types: ['experience'] }); +``` +```javascript +await client.recall('my-bank', 'query', { types: ['observation'] }); +``` + ### CLI ```bash hindsight memory recall my-bank "query" --fact-type world,observation ``` +### Go + +```go +# Section 'recall-world-only' not found in api/recall.go +``` +```go +# Section 'recall-experience-only' not found in api/recall.go +``` +```go +# Section 'recall-observations-only' not found in api/recall.go +``` + > **💡 About Observations** > Observations are consolidated knowledge synthesized from multiple facts over time — patterns, preferences, and learnings the memory bank has built up. They are created automatically in the background after retain operations. @@ -146,6 +176,22 @@ const quickResults = await client.recall('my-bank', "Alice's email", { budget: ' const deepResults = await client.recall('my-bank', 'How are Alice and Bob connected?', { budget: 'high' }); ``` +### CLI + +```bash +# Quick lookup +hindsight memory recall my-bank "Alice's email" --budget low + +# Deep exploration +hindsight memory recall my-bank "How are Alice and Bob connected?" --budget high +``` + +### Go + +```go +# Section 'recall-budget-levels' not found in api/recall.go +``` + ### max_tokens The maximum number of tokens the returned facts can collectively occupy. Defaults to `4096`. Only the `text` field of each fact is counted toward this budget — metadata, tags, entities, and other fields are not included. After reranking, facts are included in relevance order until this budget is exhausted — so you always get the most relevant memories that fit. Hindsight is designed for agents, which think in tokens rather than result counts: set `max_tokens` to however much of your context window you want to allocate to memories. @@ -160,6 +206,32 @@ results = client.recall(bank_id="my-bank", query="What do I know about Alice?", results = client.recall(bank_id="my-bank", query="Alice's email", max_tokens=500) ``` +### Node.js + +```javascript +// Fill up to 4K tokens of context with relevant memories +await client.recall('my-bank', 'What do I know about Alice?', { maxTokens: 4096 }); + +// Smaller budget for quick lookups +await client.recall('my-bank', "Alice's email", { maxTokens: 500 }); +``` + +### CLI + +```bash +# Fill up to 4K tokens of context with relevant memories +hindsight memory recall my-bank "What do I know about Alice?" --max-tokens 4096 + +# Smaller budget for quick lookups +hindsight memory recall my-bank "Alice's email" --max-tokens 500 +``` + +### Go + +```go +# Section 'recall-token-budget' not found in api/recall.go +``` + ### query_timestamp An ISO 8601 datetime representing when the query is being asked, from the user's perspective. When provided, it is used as the anchor for resolving relative temporal expressions in the query — for example, if the query says "last month" and `query_timestamp` is `2023-05-30`, the temporal search window becomes approximately April 2023. Without it, the server's current time is used as the anchor. This field matters most for replaying historical conversations or building agents that need time-anchored recall. @@ -222,6 +294,20 @@ for (const obs of obsResponse.results) { } ``` +### CLI + +```bash +# Recall observations with source facts +hindsight memory recall my-bank "What patterns have I learned about Alice?" \ + --fact-type observation +``` + +### Go + +```go +# Section 'recall-source-facts' not found in api/recall.go +``` + #### entities Enabled by default. When active, each returned fact includes the canonical names of entities associated with it. Set to `null` to skip the entity JOIN query and reduce response size. The `max_tokens` sub-option (default `500`) is a future-facing guard for entity data. @@ -254,6 +340,8 @@ Consider a bank with these four memories: Returns memories that have **at least one** matching tag, plus untagged memories. +### Python + ```python response = client.recall( bank_id="my-bank", @@ -268,12 +356,36 @@ response = client.recall( # [match] "Company policy: no meetings on Fridays" — untagged, included by default ``` +### Node.js + +```javascript +await client.recall('my-bank', 'communication preferences', { + tags: ['user:alice'], + tagsMatch: 'any' +}); +``` + +### CLI + +```bash +hindsight memory recall my-bank "communication preferences" \ + --tags "user:alice" --tags-match any +``` + +### Go + +```go +# Section 'recall-with-tags' not found in api/recall.go +``` + Use this for **shared global knowledge + user-specific** patterns, where untagged memories represent information everyone should see. #### `any_strict` — OR matching, excludes untagged Same as `any` but untagged memories are excluded. +### Python + ```python response = client.recall( bank_id="my-bank", @@ -288,12 +400,36 @@ response = client.recall( # [no match] "Company policy: no meetings on Fridays" — untagged, excluded ``` +### Node.js + +```javascript +await client.recall('my-bank', 'communication preferences', { + tags: ['user:alice'], + tagsMatch: 'any_strict' +}); +``` + +### CLI + +```bash +hindsight memory recall my-bank "communication preferences" \ + --tags "user:alice" --tags-match any_strict +``` + +### Go + +```go +# Section 'recall-tags-strict' not found in api/recall.go +``` + Use this when memories are **fully partitioned by tags** and untagged memories should never be visible. #### `all` — AND matching, includes untagged Returns memories that have **every** specified tag, plus untagged memories. +### Python + ```python response = client.recall( bank_id="my-bank", @@ -308,12 +444,36 @@ response = client.recall( # [match] "Company policy: no meetings on Fridays" — untagged, included by default ``` +### Node.js + +```javascript +await client.recall('my-bank', 'communication tools', { + tags: ['user:alice', 'team'], + tagsMatch: 'all' +}); +``` + +### CLI + +```bash +hindsight memory recall my-bank "communication tools" \ + --tags "user:alice,team" --tags-match all +``` + +### Go + +```go +# Section 'recall-tags-all-mode' not found in api/recall.go +``` + Use this when memories must belong to a **specific intersection** of scopes (e.g., only memories relevant to both a user and a project), while still surfacing shared global knowledge. #### `all_strict` — AND matching, excludes untagged Returns memories that have **every** specified tag, and excludes untagged memories. +### Python + ```python response = client.recall( bank_id="my-bank", @@ -328,6 +488,28 @@ response = client.recall( # [no match] "Company policy: no meetings on Fridays" — untagged, excluded ``` +### Node.js + +```javascript +await client.recall('my-bank', 'communication tools', { + tags: ['user:alice', 'team'], + tagsMatch: 'all_strict' +}); +``` + +### CLI + +```bash +hindsight memory recall my-bank "communication tools" \ + --tags "user:alice,team" --tags-match all_strict +``` + +### Go + +```go +# Section 'recall-tags-all' not found in api/recall.go +``` + Use this for strict scope enforcement where a memory must explicitly belong to **all** specified contexts. > **💡 Extra tags are fine** diff --git a/skills/hindsight-docs/references/developer/api/reflect.md b/skills/hindsight-docs/references/developer/api/reflect.md index d82af8de..a5100e1b 100644 --- a/skills/hindsight-docs/references/developer/api/reflect.md +++ b/skills/hindsight-docs/references/developer/api/reflect.md @@ -32,6 +32,12 @@ await client.reflect('my-bank', 'What should I know about Alice?'); hindsight memory reflect my-bank "What do you know about Alice?" ``` +### Go + +```go +# Section 'reflect-basic' not found in api/reflect.go +``` + --- ## Parameters @@ -63,6 +69,18 @@ const response = await client.reflect('my-bank', 'What do you think about remote }); ``` +### CLI + +```bash +hindsight memory reflect my-bank "Summarize my week" --budget high --max-tokens 8192 +``` + +### Go + +```go +# Section 'reflect-with-params' not found in api/reflect.go +``` + ### max_tokens Limits the length of the final generated response. Defaults to `4096`. This does not affect how much the agent can retrieve during the agentic loop — only the final answer length. @@ -147,6 +165,12 @@ hindsight memory reflect hiring-team \ rm -f schema.json ``` +### Go + +```go +# Section 'reflect-structured-output' not found in api/reflect.go +``` + ### tags Filters which memories the agent can access during reflection. Works identically to [recall tags](./recall#tags) — only memories matching the specified tags are considered. The `tags_match` parameter controls the matching logic (`any`, `all`, `any_strict`, `all_strict`) with the same semantics as recall. @@ -163,6 +187,29 @@ response = client.reflect( ) ``` +### Node.js + +```javascript +// Filter reflect to only use memories tagged for a specific user +await client.reflect('my-bank', 'What feedback did the user give?', { + tags: ['user:alice'], + tagsMatch: 'any_strict' +}); +``` + +### CLI + +```bash +hindsight memory reflect my-bank "What feedback did the user give?" \ + --tags "user:alice" --tags-match any_strict +``` + +### Go + +```go +# Section 'reflect-with-tags' not found in api/reflect.go +``` + ### include Controls optional supplementary data returned alongside the main response. @@ -187,6 +234,32 @@ for fact in (response.based_on.memories if response.based_on else []): print(f" - [{fact.type}] {fact.text}") ``` +### Node.js + +```javascript +const sourcesResponse = await client.reflect('my-bank', 'Tell me about Alice', { + includeFacts: true +}); + +console.log('Response:', sourcesResponse.text); +console.log('\nBased on:'); +for (const fact of (sourcesResponse.based_on?.memories || [])) { + console.log(` - [${fact.type}] ${fact.text}`); +} +``` + +### CLI + +```bash +hindsight memory reflect my-bank "Tell me about Alice" --include-facts +``` + +### Go + +```go +# Section 'reflect-sources' not found in api/reflect.go +``` + #### include.tool_calls When enabled, the response includes a `trace` object with the full execution log of every tool call and LLM call made during the agentic loop, including inputs, outputs, and durations. Set `output: false` to include only tool inputs for a smaller payload. Useful for debugging why the agent reached a particular conclusion. diff --git a/skills/hindsight-docs/references/developer/api/retain.md b/skills/hindsight-docs/references/developer/api/retain.md index 189a0b94..084eee96 100644 --- a/skills/hindsight-docs/references/developer/api/retain.md +++ b/skills/hindsight-docs/references/developer/api/retain.md @@ -37,6 +37,12 @@ await client.retain('my-bank', 'Alice works at Google as a software engineer'); hindsight memory retain my-bank "Alice works at Google as a software engineer" ``` +### Go + +```go +# Section 'retain-basic' not found in api/retain.go +``` + ### Retaining a Conversation A full conversation should be retained as a single item. The LLM can parse any format — plain text, JSON, Markdown, or any structured representation — as long as it clearly conveys who said what and when. The example below uses a simple `Name (timestamp): text` format. @@ -85,6 +91,27 @@ await client.retain('my-bank', conversation, { }); ``` +### CLI + +```bash +# Retain an entire conversation as a single document. +CONVERSATION="Alice (2024-03-15T09:00:00Z): Hi Bob! Did you end up going to the doctor last week? +Bob (2024-03-15T09:01:00Z): Yes, finally. Turns out I have a mild peanut allergy. +Alice (2024-03-15T09:02:00Z): Oh no! Are you okay? +Bob (2024-03-15T09:03:00Z): Yeah, nothing serious. Just need to carry an antihistamine. +Alice (2024-03-15T09:04:00Z): Good to know. We'll avoid peanuts at the team lunch." + +hindsight memory retain my-bank "$CONVERSATION" \ + --context "team chat" \ + --doc-id "chat-2024-03-15-alice-bob" +``` + +### Go + +```go +# Section 'retain-conversation' not found in api/retain.go +``` + When the conversation grows — a new message arrives — just retain again with the full updated content and the same `document_id`. Hindsight will delete the previous version and reprocess from scratch, so memories always reflect the latest state of the conversation. --- @@ -140,6 +167,12 @@ hindsight memory retain my-bank "Alice got promoted" \ --context "career update" ``` +### Go + +```go +# Section 'retain-with-context' not found in api/retain.go +``` + ### metadata Arbitrary key-value string pairs that provide context about this item. For example: `{"source": "slack", "channel": "engineering", "thread_id": "T123"}`. Metadata is included in the fact extraction prompt, so the LLM can use it as additional context when extracting facts — for instance, knowing the document title or source can improve accuracy. It is also stored on each memory unit and returned with every recalled memory, letting you do client-side filtering or static enrichment without extra lookups — for example, linking a memory back to its source URL, thread ID, or any application-specific identifier. @@ -263,35 +296,31 @@ await client.retainBatch('my-bank', [ ]); ``` ---- - -## Files - -Upload files directly — Hindsight converts them to text and extracts memories automatically. File processing always runs asynchronously and returns operation IDs for tracking. - -**Supported formats:** PDF, DOCX, DOC, PPTX, PPT, XLSX, XLS, images (JPG, PNG, GIF, etc. — OCR), audio (MP3, WAV, FLAC, etc. — transcription), HTML, and plain text formats (TXT, MD, CSV, JSON, YAML, etc.) - ### CLI ```bash -# Upload a single file (PDF, DOCX, PPTX, XLSX, images, audio, and more) -hindsight memory retain-files my-bank "$SAMPLE_FILE" +# Batch ingestion via individual retain calls (CLI processes items one at a time) +hindsight memory retain my-bank "Alice works at Google" \ + --context "career" --doc-id "conversation_001_msg_1" +hindsight memory retain my-bank "Bob is a data scientist at Meta" \ + --context "career" --doc-id "conversation_001_msg_2" +hindsight memory retain my-bank "Alice and Bob are friends" \ + --context "relationship" --doc-id "conversation_001_msg_3" +``` -# Upload a directory of files -hindsight memory retain-files my-bank "$SCRIPT_DIR/" +### Go -# Queue files for background processing (returns immediately) -hindsight memory retain-files my-bank "$SCRIPT_DIR/" --async +```go +# Section 'retain-batch' not found in api/retain.go ``` -### HTTP +--- -```bash -# Via HTTP API (multipart/form-data) -curl -X POST "${HINDSIGHT_URL}/v1/default/banks/my-bank/files/retain" \ - -F "files=@${SAMPLE_FILE};type=application/octet-stream" \ - -F "request={\"files_metadata\": [{\"context\": \"quarterly report\"}]}" -``` +## Files + +Upload files directly — Hindsight converts them to text and extracts memories automatically. File processing always runs asynchronously and returns operation IDs for tracking. + +**Supported formats:** PDF, DOCX, DOC, PPTX, PPT, XLSX, XLS, images (JPG, PNG, GIF, etc. — OCR), audio (MP3, WAV, FLAC, etc. — transcription), HTML, and plain text formats (TXT, MD, CSV, JSON, YAML, etc.) ### Python @@ -324,6 +353,25 @@ const result = await client.retainFiles('my-bank', [ console.log(result.operation_ids); // Track processing via the operations endpoint ``` +### CLI + +```bash +# Upload a single file (PDF, DOCX, PPTX, XLSX, images, audio, and more) +hindsight memory retain-files my-bank "$SAMPLE_FILE" + +# Upload a directory of files +hindsight memory retain-files my-bank "$SCRIPT_DIR/" + +# Queue files for background processing (returns immediately) +hindsight memory retain-files my-bank "$SCRIPT_DIR/" --async +``` + +### Go + +```go +# Section 'retain-files' not found in api/retain.go +``` + The file retain endpoint always returns asynchronously. The response contains `operation_ids` — one per uploaded file — which you can poll via `GET /v1/default/banks/{bank_id}/operations` to track progress. Upload up to 10 files per request (max 100 MB total). Each file becomes a separate document with optional per-file metadata: @@ -347,6 +395,41 @@ result = client.retain_files( print(result.operation_ids) # One operation ID per file ``` +### Node.js + +```javascript +// Upload multiple files with per-file metadata (up to 10 files per request) +const batchResult = await client.retainFiles('my-bank', [ + new File([pdfBytes], 'report.pdf'), + new File([pdfBytes], 'notes.pdf'), +], { + filesMetadata: [ + { context: 'quarterly report', document_id: 'q1-report', tags: ['project:alpha'] }, + { context: 'meeting notes', document_id: 'q1-notes', tags: ['project:alpha'] }, + ] +}); +console.log(batchResult.operation_ids); // One operation ID per file +``` + +### CLI + +```bash +# Upload a single file (PDF, DOCX, PPTX, XLSX, images, audio, and more) +hindsight memory retain-files my-bank "$SAMPLE_FILE" + +# Upload a directory of files +hindsight memory retain-files my-bank "$SCRIPT_DIR/" + +# Queue files for background processing (returns immediately) +hindsight memory retain-files my-bank "$SCRIPT_DIR/" --async +``` + +### Go + +```go +# Section 'retain-files' not found in api/retain.go +``` + :::info File Storage Uploaded files are stored server-side (PostgreSQL by default, or S3/GCS/Azure for production). Configure storage via `HINDSIGHT_API_FILE_STORAGE_TYPE`. See [Configuration](../configuration#file-processing) for details. --- @@ -384,6 +467,18 @@ await client.retainBatch('my-bank', [ }); ``` +### CLI + +```bash +hindsight memory retain my-bank "Meeting notes" --async +``` + +### Go + +```go +# Section 'retain-async' not found in api/retain.go +``` + When `async: true`, the call returns immediately with an `operation_id`. Processing runs in the background via the worker service. No `usage` metrics are returned for async operations. ### Cut Costs 50% with Provider Batch APIs diff --git a/skills/hindsight-docs/references/developer/configuration.md b/skills/hindsight-docs/references/developer/configuration.md index 3e371327..2ecc4b3f 100644 --- a/skills/hindsight-docs/references/developer/configuration.md +++ b/skills/hindsight-docs/references/developer/configuration.md @@ -646,8 +646,6 @@ client.retain(bank_id, items=[{"content": "...document text..."}], strategy="doc If no `strategy` is specified in a retain call, `retain_default_strategy` is used. If neither is set, the bank/global config applies directly. -> **Note on chunk size and retrieval fairness**: When mixing strategies with very different chunk sizes in the same bank, `chunks` and `verbatim` memories participate only in semantic retrieval (not entity graph or temporal paths). Smaller chunk sizes (e.g., 800 chars) produce more targeted embeddings and are recommended for document strategies to keep scores comparable with LLM-extracted facts. - **`HINDSIGHT_API_RETAIN_EXTRACTION_MODE=chunks` — zero LLM cost** Each chunk is stored as-is with no LLM call whatsoever. No entity extraction, no temporal indexing — only embeddings are generated for semantic search. User-provided entities passed via `RetainContent.entities` are the sole source of entity data. Use when ingestion speed and cost matter more than structured metadata. diff --git a/skills/hindsight-docs/references/sdks/integrations/agno.md b/skills/hindsight-docs/references/sdks/integrations/agno.md new file mode 100644 index 00000000..00a92788 --- /dev/null +++ b/skills/hindsight-docs/references/sdks/integrations/agno.md @@ -0,0 +1,186 @@ +--- +sidebar_position: 9 +--- + +# Agno + +Persistent memory tools for [Agno](https://github.com/agno-agi/agno) agents via Hindsight. Give your agents long-term memory with retain, recall, and reflect — using Agno's native Toolkit pattern. + +## Features + +- **Native Toolkit** - Extends Agno's `Toolkit` base class, just like `Mem0Tools` +- **Memory Instructions** - Pre-recall memories for injection into `Agent(instructions=[...])` +- **Three Memory Tools** - Retain (store), Recall (search), Reflect (synthesize) — include any combination +- **Flexible Bank Resolution** - Static bank ID, `RunContext.user_id`, or custom resolver +- **Simple Configuration** - Configure once globally, or pass a client directly + +## Installation + +```bash +pip install hindsight-agno +``` + +## Quick Start + +```python +from agno.agent import Agent +from agno.models.openai import OpenAIChat +from hindsight_agno import HindsightTools + +agent = Agent( + model=OpenAIChat(id="gpt-4o-mini"), + tools=[HindsightTools( + bank_id="user-123", + hindsight_api_url="http://localhost:8888", + )], +) + +agent.print_response("Remember that I prefer dark mode") +agent.print_response("What are my preferences?") +``` + +The agent now has three tools it can call: + +- **`retain_memory`** — Store information to long-term memory +- **`recall_memory`** — Search long-term memory for relevant facts +- **`reflect_on_memory`** — Synthesize a reasoned answer from memories + +## With Memory Instructions + +Pre-recall relevant memories and inject them into the system prompt: + +```python +from hindsight_agno import HindsightTools, memory_instructions + +agent = Agent( + model=OpenAIChat(id="gpt-4o-mini"), + tools=[HindsightTools( + bank_id="user-123", + hindsight_api_url="http://localhost:8888", + )], + instructions=[memory_instructions( + bank_id="user-123", + hindsight_api_url="http://localhost:8888", + )], +) +``` + +## Selecting Tools + +Include only the tools you need: + +```python +tools = [HindsightTools( + bank_id="user-123", + hindsight_api_url="http://localhost:8888", + enable_retain=True, + enable_recall=True, + enable_reflect=False, # Omit reflect +)] +``` + +## Bank Resolution + +The bank ID is resolved in order: + +1. **`bank_resolver`** — Custom callable `(RunContext) -> str` +2. **`bank_id`** — Static bank ID passed to constructor +3. **`run_context.user_id`** — Automatic per-user banks + +```python +# Per-user banks from RunContext +agent = Agent( + model=OpenAIChat(id="gpt-4o-mini"), + tools=[HindsightTools(hindsight_api_url="http://localhost:8888")], + user_id="user-123", # Used as bank_id +) + +# Custom resolver +def resolve_bank(ctx): + return f"team-{ctx.user_id}" + +agent = Agent( + model=OpenAIChat(id="gpt-4o-mini"), + tools=[HindsightTools( + bank_resolver=resolve_bank, + hindsight_api_url="http://localhost:8888", + )], +) +``` + +## Global Configuration + +Instead of passing connection details to every toolkit, configure once: + +```python +from hindsight_agno import configure, HindsightTools + +configure( + hindsight_api_url="http://localhost:8888", + api_key="your-api-key", # Or set HINDSIGHT_API_KEY env var + budget="mid", # Recall budget: low/mid/high + max_tokens=4096, # Max tokens for recall results + tags=["env:prod"], # Tags for stored memories + recall_tags=["scope:global"], # Tags to filter recall + recall_tags_match="any", # Tag match mode: any/all/any_strict/all_strict +) + +# Now create toolkit without passing connection details +tools = [HindsightTools(bank_id="user-123")] +``` + +## Configuration Reference + +### `HindsightTools()` + +| Parameter | Default | Description | +|---|---|---| +| `bank_id` | `None` | Static Hindsight memory bank ID | +| `bank_resolver` | `None` | Callable `(RunContext) -> str` for dynamic bank ID | +| `client` | `None` | Pre-configured Hindsight client | +| `hindsight_api_url` | `None` | API URL (used if no client provided) | +| `api_key` | `None` | API key (used if no client provided) | +| `budget` | `"mid"` | Recall/reflect budget level (low/mid/high) | +| `max_tokens` | `4096` | Maximum tokens for recall results | +| `tags` | `None` | Tags applied when storing memories | +| `recall_tags` | `None` | Tags to filter when searching | +| `recall_tags_match` | `"any"` | Tag matching mode | +| `enable_retain` | `True` | Include the retain (store) tool | +| `enable_recall` | `True` | Include the recall (search) tool | +| `enable_reflect` | `True` | Include the reflect (synthesize) tool | + +### `memory_instructions()` + +| Parameter | Default | Description | +|---|---|---| +| `bank_id` | *required* | Hindsight memory bank ID | +| `client` | `None` | Pre-configured Hindsight client | +| `hindsight_api_url` | `None` | API URL (used if no client provided) | +| `api_key` | `None` | API key (used if no client provided) | +| `query` | `"relevant context about the user"` | Recall query for memory injection | +| `budget` | `"low"` | Recall budget level | +| `max_results` | `5` | Maximum memories to inject | +| `max_tokens` | `4096` | Maximum tokens for recall results | +| `prefix` | `"Relevant memories:\n"` | Text prepended before memory list | +| `tags` | `None` | Tags to filter recall results | +| `tags_match` | `"any"` | Tag matching mode | + +### `configure()` + +| Parameter | Default | Description | +|---|---|---| +| `hindsight_api_url` | Production API | Hindsight API URL | +| `api_key` | `HINDSIGHT_API_KEY` env | API key for authentication | +| `budget` | `"mid"` | Default recall budget level | +| `max_tokens` | `4096` | Default max tokens for recall | +| `tags` | `None` | Default tags for retain operations | +| `recall_tags` | `None` | Default tags to filter recall | +| `recall_tags_match` | `"any"` | Default tag matching mode | +| `verbose` | `False` | Enable verbose logging | + +## Requirements + +- Python >= 3.10 +- agno +- hindsight-client >= 0.4.0 +- A running Hindsight API server diff --git a/skills/hindsight-docs/references/sdks/integrations/hermes.md b/skills/hindsight-docs/references/sdks/integrations/hermes.md new file mode 100644 index 00000000..766687de --- /dev/null +++ b/skills/hindsight-docs/references/sdks/integrations/hermes.md @@ -0,0 +1,219 @@ +--- +sidebar_position: 10 +--- + +# Hermes Agent + +Hindsight memory integration for [Hermes Agent](https://github.com/NousResearch/hermes-agent). Gives your Hermes agent persistent long-term memory via retain, recall, and reflect tools. + +## What it does + +This package registers three tools into Hermes via its plugin system: + +- **`hindsight_retain`** — Stores information to long-term memory. Hermes calls this when the user shares facts, preferences, or anything worth remembering. +- **`hindsight_recall`** — Searches long-term memory for relevant information. Returns a numbered list of matching memories. +- **`hindsight_reflect`** — Synthesizes a thoughtful answer from stored memories. Use this when you want Hermes to reason over what it knows rather than return raw facts. + +These tools appear under the `[hindsight]` toolset in Hermes's `/tools` list. + +## Setup + +### 1. Install hindsight-hermes into the Hermes venv + +The package must be installed in the **same Python environment** that Hermes runs in, so the entry point is discoverable. + +```bash +uv pip install hindsight-hermes --python $HOME/.hermes/hermes-agent/venv/bin/python +``` + +### 2. Set environment variables + +The plugin reads its configuration from environment variables. Set these before launching Hermes: + +```bash +# Required — tells the plugin where Hindsight is running +export HINDSIGHT_API_URL=http://localhost:8888 + +# Required — the memory bank to read/write. Think of this as a "brain" for one user or agent. +export HINDSIGHT_BANK_ID=my-agent + +# Optional — only needed if using Hindsight Cloud (https://api.hindsight.vectorize.io) +export HINDSIGHT_API_KEY=your-api-key + +# Optional — recall budget: low (fast), mid (default), high (thorough) +export HINDSIGHT_BUDGET=mid +``` + +If neither `HINDSIGHT_API_URL` nor `HINDSIGHT_API_KEY` is set, the plugin silently skips registration — Hermes starts normally without the Hindsight tools. + +### 3. Disable Hermes's built-in memory tool + +Hermes has its own `memory` tool that saves to local files (`~/.hermes/`). If both are active, the LLM tends to prefer the built-in one since it's familiar. Disable it so the LLM uses Hindsight instead: + +```bash +hermes tools disable memory +``` + +This persists across sessions. You can re-enable it later with `hermes tools enable memory`. + +### 4. Start Hindsight API + +Follow the [Quick Start](../../developer/api/quickstart.md) guide to get the Hindsight API running, then come back here. + +### 5. Launch Hermes + +```bash +hermes +``` + +Verify the plugin loaded by typing `/tools` — you should see: + +``` +[hindsight] + * hindsight_recall - Search long-term memory for relevant information. + * hindsight_reflect - Synthesize a thoughtful answer from long-term memories. + * hindsight_retain - Store information to long-term memory for later retrieval. +``` + +### 6. Test it + +**Store a memory:** +> Remember that my favourite colour is red + +You should see `⚡ hindsight` in the response, confirming it called `hindsight_retain`. + +**Recall a memory:** +> What's my favourite colour? + +**Reflect on memories:** +> Based on what you know about me, suggest a colour scheme for my IDE + +This calls `hindsight_reflect`, which synthesizes a response from all stored memories. + +**Verify via API:** + +```bash +curl -s http://localhost:8888/v1/default/banks/my-agent/memories/recall \ + -H "Content-Type: application/json" \ + -d '{"query": "favourite colour", "budget": "low"}' | python3 -m json.tool +``` + +## Troubleshooting + +### Tools don't appear in `/tools` + +1. **Check the plugin is installed in the right venv.** Run this from the Hermes venv: + ```bash + python -c "from hindsight_hermes import register; print('OK')" + ``` + +2. **Check the entry point is registered:** + ```bash + python -c " + import importlib.metadata + eps = importlib.metadata.entry_points(group='hermes_agent.plugins') + print(list(eps)) + " + ``` + You should see `EntryPoint(name='hindsight', value='hindsight_hermes', group='hermes_agent.plugins')`. + +3. **Check env vars are set.** The plugin skips registration silently if `HINDSIGHT_API_URL` and `HINDSIGHT_API_KEY` are both unset. + +### Hermes uses built-in memory instead of Hindsight + +Run `hermes tools disable memory` and restart. The built-in `memory` tool and Hindsight tools have overlapping purposes — the LLM will prefer whichever it's more familiar with, which is usually the built-in one. + +### Bank not found errors + +The plugin auto-creates banks on first use. If you see bank errors, check that the Hindsight API is running and `HINDSIGHT_API_URL` is correct. + +### Connection refused + +Make sure the Hindsight API is running and listening on the URL you configured. Test with: +```bash +curl http://localhost:8888/health +``` + +## Manual registration (advanced) + +If you don't want to use the plugin system, you can register tools directly in a Hermes startup script or custom agent: + +```python +from hindsight_hermes import register_tools + +register_tools( + bank_id="my-agent", + hindsight_api_url="http://localhost:8888", + budget="mid", + tags=["hermes"], # applied to all retained memories + recall_tags=["hermes"], # filter recall to only these tags +) +``` + +This imports `tools.registry` from Hermes at call time and registers the three tools directly. This approach gives you more control over parameters but requires Hermes to be importable. + +## Memory instructions (system prompt injection) + +Pre-recall memories at startup and inject them into the system prompt, so the agent starts every conversation with relevant context: + +```python +from hindsight_hermes import memory_instructions + +context = memory_instructions( + bank_id="my-agent", + hindsight_api_url="http://localhost:8888", + query="user preferences and important context", + budget="low", + max_results=5, +) +# Returns: +# Relevant memories: +# 1. User's favourite colour is red +# 2. User prefers dark mode +``` + +This never raises — if the API is down or no memories exist, it returns an empty string. + +## Global configuration (advanced) + +Instead of passing parameters to every call, configure once: + +```python +from hindsight_hermes import configure + +configure( + hindsight_api_url="http://localhost:8888", + api_key="your-key", + budget="mid", + tags=["hermes"], +) +``` + +Subsequent calls to `register_tools()` or `memory_instructions()` will use these defaults if no explicit values are provided. + +## MCP alternative + +Hermes also supports MCP servers natively. You can use Hindsight's MCP server directly instead of this plugin — no `hindsight-hermes` package needed: + +```yaml +# In your Hermes config +mcp_servers: + - name: hindsight + url: http://localhost:8888/mcp +``` + +This exposes the same retain/recall/reflect operations through Hermes's MCP integration. The tradeoff is that MCP tools may have different naming and the LLM needs to discover them, whereas the plugin registers tools with Hermes-native schemas. + +## Configuration reference + +| Parameter | Env Var | Default | Description | +|-----------|---------|---------|-------------| +| `hindsight_api_url` | `HINDSIGHT_API_URL` | `https://api.hindsight.vectorize.io` | Hindsight API URL | +| `api_key` | `HINDSIGHT_API_KEY` | — | API key for authentication | +| `bank_id` | `HINDSIGHT_BANK_ID` | — | Memory bank ID | +| `budget` | `HINDSIGHT_BUDGET` | `mid` | Recall budget (low/mid/high) | +| `max_tokens` | — | `4096` | Max tokens for recall results | +| `tags` | — | — | Tags applied when storing memories | +| `recall_tags` | — | — | Tags to filter recall results | +| `recall_tags_match` | — | `any` | Tag matching mode (any/all/any_strict/all_strict) | +| `toolset` | — | `hindsight` | Hermes toolset group name |