Release v0.4.11

- Update version to 0.4.11 in all components - Regenerate OpenAPI spec and client SDKs - Python packages: hindsight-api, hindsight-dev, hindsight-all, hindsight-litellm, hindsight-embed - Python client: hindsight-clients/python - TypeScript client: hindsight-clients/typescript - Rust CLI: hindsight-cli - Control Plane: hindsight-control-plane - OpenClaw integration: hindsight-integrations/openclaw - AI SDK integration: hindsight-integrations/ai-sdk - Helm chart - Sync documentation to version-0.4
2026-02-13 10:52:14 +01:00 · 2026-02-13 10:52:14 +01:00 · b3b541fc53
commit b3b541fc53
parent 4f112101ac
110 changed files with 1284 additions and 210 deletions
--- a/helm/hindsight/Chart.yaml
+++ b/helm/hindsight/Chart.yaml
@ -2,8 +2,8 @@ apiVersion: v2
 name: hindsight
 description: Hindsight helm chart
 type: application
-version: 0.4.10
-appVersion: "0.4.10"
+version: 0.4.11
+appVersion: "0.4.11"
 keywords:
  - ai
  - memory
--- a/hindsight-api/hindsight_api/init.py
+++ b/hindsight-api/hindsight_api/init.py
@ -46,4 +46,4 @@ __all__ = [
    "RemoteTEICrossEncoder",
    "LLMConfig",
 ]
-__version__ = "0.4.10"
+__version__ = "0.4.11"
--- a/hindsight-api/pyproject.toml
+++ b/hindsight-api/pyproject.toml
@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "hindsight-api"
-version = "0.4.10"
+version = "0.4.11"
 description = "Hindsight: Agent Memory That Works Like Human Memory"
 readme = "README.md"
 requires-python = ">=3.11"
--- a/hindsight-cli/Cargo.toml
+++ b/hindsight-cli/Cargo.toml
@ -1,6 +1,6 @@
 [package]
 name = "hindsight-cli"
-version = "0.4.10"
+version = "0.4.11"
 edition = "2021"
 authors = ["Hindsight Team"]
 description = "A beautiful CLI for Hindsight - semantic memory system"
--- a/hindsight-clients/python/hindsight_client_api/init.py
+++ b/hindsight-clients/python/hindsight_client_api/init.py
@ -7,7 +7,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/api/banks_api.py
+++ b/hindsight-clients/python/hindsight_client_api/api/banks_api.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/api/directives_api.py
+++ b/hindsight-clients/python/hindsight_client_api/api/directives_api.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/api/documents_api.py
+++ b/hindsight-clients/python/hindsight_client_api/api/documents_api.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/api/entities_api.py
+++ b/hindsight-clients/python/hindsight_client_api/api/entities_api.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/api/memory_api.py
+++ b/hindsight-clients/python/hindsight_client_api/api/memory_api.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/api/mental_models_api.py
+++ b/hindsight-clients/python/hindsight_client_api/api/mental_models_api.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/api/monitoring_api.py
+++ b/hindsight-clients/python/hindsight_client_api/api/monitoring_api.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/api/operations_api.py
+++ b/hindsight-clients/python/hindsight_client_api/api/operations_api.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/api_client.py
+++ b/hindsight-clients/python/hindsight_client_api/api_client.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/configuration.py
+++ b/hindsight-clients/python/hindsight_client_api/configuration.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
@ -489,7 +489,7 @@ class Configuration:
        return "Python SDK Debug Report:\n"\
               "OS: {env}\n"\
               "Python Version: {pyversion}\n"\
-               "Version of the API: 0.4.10\n"\
+               "Version of the API: 0.4.11\n"\
               "SDK Package Version: 0.0.7".\
               format(env=sys.platform, pyversion=sys.version)

--- a/hindsight-clients/python/hindsight_client_api/exceptions.py
+++ b/hindsight-clients/python/hindsight_client_api/exceptions.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/init.py
+++ b/hindsight-clients/python/hindsight_client_api/models/init.py
@ -6,7 +6,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/add_background_request.py
+++ b/hindsight-clients/python/hindsight_client_api/models/add_background_request.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/async_operation_submit_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/async_operation_submit_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/background_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/background_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/bank_config_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/bank_config_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/bank_config_update.py
+++ b/hindsight-clients/python/hindsight_client_api/models/bank_config_update.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/bank_list_item.py
+++ b/hindsight-clients/python/hindsight_client_api/models/bank_list_item.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/bank_list_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/bank_list_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/bank_profile_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/bank_profile_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/bank_stats_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/bank_stats_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/budget.py
+++ b/hindsight-clients/python/hindsight_client_api/models/budget.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/cancel_operation_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/cancel_operation_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/chunk_data.py
+++ b/hindsight-clients/python/hindsight_client_api/models/chunk_data.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/chunk_include_options.py
+++ b/hindsight-clients/python/hindsight_client_api/models/chunk_include_options.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/chunk_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/chunk_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/consolidation_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/consolidation_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/create_bank_request.py
+++ b/hindsight-clients/python/hindsight_client_api/models/create_bank_request.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/create_directive_request.py
+++ b/hindsight-clients/python/hindsight_client_api/models/create_directive_request.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/create_mental_model_request.py
+++ b/hindsight-clients/python/hindsight_client_api/models/create_mental_model_request.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/create_mental_model_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/create_mental_model_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/delete_document_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/delete_document_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/delete_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/delete_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/directive_list_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/directive_list_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/directive_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/directive_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/disposition_traits.py
+++ b/hindsight-clients/python/hindsight_client_api/models/disposition_traits.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/document_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/document_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/entity_detail_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/entity_detail_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/entity_include_options.py
+++ b/hindsight-clients/python/hindsight_client_api/models/entity_include_options.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/entity_input.py
+++ b/hindsight-clients/python/hindsight_client_api/models/entity_input.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/entity_list_item.py
+++ b/hindsight-clients/python/hindsight_client_api/models/entity_list_item.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/entity_list_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/entity_list_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/entity_observation_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/entity_observation_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/entity_state_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/entity_state_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/features_info.py
+++ b/hindsight-clients/python/hindsight_client_api/models/features_info.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/graph_data_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/graph_data_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/http_validation_error.py
+++ b/hindsight-clients/python/hindsight_client_api/models/http_validation_error.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/include_options.py
+++ b/hindsight-clients/python/hindsight_client_api/models/include_options.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/list_documents_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/list_documents_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/list_memory_units_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/list_memory_units_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/list_tags_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/list_tags_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/memory_item.py
+++ b/hindsight-clients/python/hindsight_client_api/models/memory_item.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/mental_model_list_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/mental_model_list_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/mental_model_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/mental_model_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/mental_model_trigger.py
+++ b/hindsight-clients/python/hindsight_client_api/models/mental_model_trigger.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/operation_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/operation_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/operation_status_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/operation_status_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/operations_list_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/operations_list_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/recall_request.py
+++ b/hindsight-clients/python/hindsight_client_api/models/recall_request.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/recall_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/recall_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/recall_result.py
+++ b/hindsight-clients/python/hindsight_client_api/models/recall_result.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/reflect_based_on.py
+++ b/hindsight-clients/python/hindsight_client_api/models/reflect_based_on.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/reflect_directive.py
+++ b/hindsight-clients/python/hindsight_client_api/models/reflect_directive.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/reflect_fact.py
+++ b/hindsight-clients/python/hindsight_client_api/models/reflect_fact.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/reflect_include_options.py
+++ b/hindsight-clients/python/hindsight_client_api/models/reflect_include_options.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/reflect_llm_call.py
+++ b/hindsight-clients/python/hindsight_client_api/models/reflect_llm_call.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/reflect_mental_model.py
+++ b/hindsight-clients/python/hindsight_client_api/models/reflect_mental_model.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/reflect_request.py
+++ b/hindsight-clients/python/hindsight_client_api/models/reflect_request.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/reflect_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/reflect_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/reflect_tool_call.py
+++ b/hindsight-clients/python/hindsight_client_api/models/reflect_tool_call.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/reflect_trace.py
+++ b/hindsight-clients/python/hindsight_client_api/models/reflect_trace.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/retain_request.py
+++ b/hindsight-clients/python/hindsight_client_api/models/retain_request.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/retain_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/retain_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/tag_item.py
+++ b/hindsight-clients/python/hindsight_client_api/models/tag_item.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/token_usage.py
+++ b/hindsight-clients/python/hindsight_client_api/models/token_usage.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/tool_calls_include_options.py
+++ b/hindsight-clients/python/hindsight_client_api/models/tool_calls_include_options.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/update_directive_request.py
+++ b/hindsight-clients/python/hindsight_client_api/models/update_directive_request.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/update_disposition_request.py
+++ b/hindsight-clients/python/hindsight_client_api/models/update_disposition_request.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/update_mental_model_request.py
+++ b/hindsight-clients/python/hindsight_client_api/models/update_mental_model_request.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/validation_error.py
+++ b/hindsight-clients/python/hindsight_client_api/models/validation_error.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/validation_error_loc_inner.py
+++ b/hindsight-clients/python/hindsight_client_api/models/validation_error_loc_inner.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/models/version_response.py
+++ b/hindsight-clients/python/hindsight_client_api/models/version_response.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/hindsight_client_api/rest.py
+++ b/hindsight-clients/python/hindsight_client_api/rest.py
@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.10
+    The version of the OpenAPI document: 0.4.11
    Generated by OpenAPI Generator (https://openapi-generator.tech)

    Do not edit the class manually.
--- a/hindsight-clients/python/pyproject.toml
+++ b/hindsight-clients/python/pyproject.toml
@ -1,6 +1,6 @@
 [project]
 name = "hindsight-client"
-version = "0.4.10"
+version = "0.4.11"
 description = "Python client for Hindsight - Semantic memory system with personality-driven thinking"
 authors = [
    {name = "Hindsight Team"}
--- a/hindsight-clients/typescript/package.json
+++ b/hindsight-clients/typescript/package.json
@ -1,6 +1,6 @@
 {
  "name": "@vectorize-io/hindsight-client",
-  "version": "0.4.10",
+  "version": "0.4.11",
  "description": "TypeScript client for Hindsight - Semantic memory system with personality-driven thinking",
  "main": "./dist/src/index.js",
  "types": "./dist/src/index.d.ts",
--- a/hindsight-control-plane/package.json
+++ b/hindsight-control-plane/package.json
@ -1,6 +1,6 @@
 {
  "name": "@vectorize-io/hindsight-control-plane",
-  "version": "0.4.10",
+  "version": "0.4.11",
  "description": "Control plane for Hindsight - Semantic memory system",
  "bin": {
    "hindsight-control-plane": "./bin/cli.js"
--- a/hindsight-dev/pyproject.toml
+++ b/hindsight-dev/pyproject.toml
@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "hindsight-dev"
-version = "0.4.10"
+version = "0.4.11"
 description = "Development utilities for Hindsight"
 requires-python = ">=3.11"
 dependencies = [
--- a/hindsight-docs/static/openapi.json
+++ b/hindsight-docs/static/openapi.json
@ -10,7 +10,7 @@
      "name": "Apache 2.0",
      "url": "https://www.apache.org/licenses/LICENSE-2.0.html"
    },
-    "version": "0.4.10"
+    "version": "0.4.11"
  },
  "paths": {
    "/health": {
--- a/hindsight-docs/versioned_docs/version-0.4/developer/configuration.md
+++ b/hindsight-docs/versioned_docs/version-0.4/developer/configuration.md
@ -57,6 +57,71 @@ hindsight-admin run-db-migration
 hindsight-admin run-db-migration --schema tenant_acme
 ```

+### Vector Extension
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HINDSIGHT_API_VECTOR_EXTENSION` | Vector extension to use: `auto`, `pgvector`, or `vchord` | `auto` |
+
+Hindsight supports two PostgreSQL vector extensions:
+- **pgvector**: Standard extension, works well for most embeddings (up to ~2000 dimensions)
+- **vchord**: Optimized for high-dimensional embeddings (3000+ dimensions), includes BM25 search
+
+When set to `auto` (default), Hindsight automatically detects which extension is installed, preferring vchord if both are available.
+
+**When to use vchord:**
+- Using high-dimensional embeddings (e.g., `text-embedding-3-large` with 3072 dimensions)
+- Need better performance with large embedding dimensions
+- Want to use vchord's BM25 search capabilities
+
+**When to use pgvector:**
+- Using standard embedding dimensions (384-1536)
+- Prefer the widely-adopted pgvector extension
+- Simpler deployment (pgvector is more commonly available)
+
+**Switching extensions:**
+
+If you need to switch from one extension to another:
+1. Set `HINDSIGHT_API_VECTOR_EXTENSION` to your desired extension (`pgvector` or `vchord`)
+2. If your database has existing data, you'll get an error with migration instructions
+3. For empty databases, indexes will be automatically recreated on startup
+
+### Text Search Extension
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HINDSIGHT_API_TEXT_SEARCH_EXTENSION` | Text search backend: `native`, `vchord`, or `pg_textsearch` | `native` |
+
+Hindsight supports three text search backends for BM25 keyword retrieval:
+- **native**: PostgreSQL's built-in full-text search (`tsvector` + GIN indexes)
+- **vchord**: VectorChord BM25 (`bm25vector` + BM25 indexes) - requires `vchord_bm25` extension
+- **pg_textsearch**: Timescale BM25 (text columns + BM25 indexes) - requires `pg_textsearch` extension
+
+**When to use native:**
+- Standard PostgreSQL deployment (no extra extensions)
+- Simpler setup and wider compatibility
+- Works well for most use cases
+
+**When to use vchord:**
+- Already using vchord for vector search (good integration)
+- Want better BM25 ranking performance
+- Need advanced tokenization (uses `llmlingua2` tokenizer)
+
+**When to use pg_textsearch:**
+- Want industry-standard BM25 ranking with better relevance than native PostgreSQL
+- Need efficient top-K queries with Block-Max WAND optimization
+- Prefer lower memory footprint compared to vchord
+- Already using Timescale or have `pg_textsearch` available
+
+**Switching backends:**
+
+To switch between backends:
+1. Set `HINDSIGHT_API_TEXT_SEARCH_EXTENSION` to your desired backend (`native`, `vchord`, or `pg_textsearch`)
+2. If your database has existing data, you'll get an error with migration instructions
+3. For empty databases, the columns/indexes will be automatically recreated on startup
+
+**Note:** VectorChord uses the `llmlingua2` tokenizer for multilingual support, while native and pg_textsearch use PostgreSQL's English tokenizer.
+
 ### LLM Provider

 | Variable | Description | Default |
@ -267,24 +332,33 @@ export HINDSIGHT_API_RETAIN_LLM_MAX_BACKOFF=120.0    # Cap at 2min instead of 1m

 | Variable | Description | Default |
 |----------|-------------|---------|
-| `HINDSIGHT_API_EMBEDDINGS_PROVIDER` | Provider: `local`, `tei`, `openai`, `cohere`, or `litellm` | `local` |
+| `HINDSIGHT_API_EMBEDDINGS_PROVIDER` | Provider: `local`, `tei`, `openai`, `cohere`, `litellm`, or `litellm-sdk` | `local` |
 | `HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL` | Model for local provider | `BAAI/bge-small-en-v1.5` |
+| `HINDSIGHT_API_EMBEDDINGS_LOCAL_TRUST_REMOTE_CODE` | Allow loading models with custom code (security risk, disabled by default) | `false` |
 | `HINDSIGHT_API_EMBEDDINGS_TEI_URL` | TEI server URL | - |
 | `HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY` | OpenAI API key (falls back to `HINDSIGHT_API_LLM_API_KEY`) | - |
 | `HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL` | OpenAI embedding model | `text-embedding-3-small` |
 | `HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL` | Custom base URL for OpenAI-compatible API (e.g., Azure OpenAI) | - |
-| `HINDSIGHT_API_COHERE_API_KEY` | Cohere API key (shared for embeddings and reranker) | - |
+| `HINDSIGHT_API_EMBEDDINGS_COHERE_API_KEY` | Cohere API key for embeddings | - |
 | `HINDSIGHT_API_EMBEDDINGS_COHERE_MODEL` | Cohere embedding model | `embed-english-v3.0` |
 | `HINDSIGHT_API_EMBEDDINGS_COHERE_BASE_URL` | Custom base URL for Cohere-compatible API (e.g., Azure-hosted) | - |
-| `HINDSIGHT_API_LITELLM_API_BASE` | LiteLLM proxy base URL (shared for embeddings and reranker) | `http://localhost:4000` |
-| `HINDSIGHT_API_LITELLM_API_KEY` | LiteLLM proxy API key (optional, depends on proxy config) | - |
+| `HINDSIGHT_API_EMBEDDINGS_LITELLM_API_BASE` | LiteLLM proxy base URL for embeddings | `http://localhost:4000` |
+| `HINDSIGHT_API_EMBEDDINGS_LITELLM_API_KEY` | LiteLLM proxy API key for embeddings (optional, depends on proxy config) | - |
 | `HINDSIGHT_API_EMBEDDINGS_LITELLM_MODEL` | LiteLLM embedding model (use provider prefix, e.g., `cohere/embed-english-v3.0`) | `text-embedding-3-small` |
+| `HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_API_KEY` | LiteLLM SDK API key for direct embedding provider access | - |
+| `HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_MODEL` | LiteLLM SDK embedding model (use provider prefix, e.g., `cohere/embed-english-v3.0`) | `cohere/embed-english-v3.0` |
+| `HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_API_BASE` | Custom base URL for LiteLLM SDK embeddings (optional) | - |

 ```bash
 # Local (default) - uses SentenceTransformers
 export HINDSIGHT_API_EMBEDDINGS_PROVIDER=local
 export HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL=BAAI/bge-small-en-v1.5

+# Local with custom model requiring trust_remote_code
+# WARNING: Only enable trust_remote_code for models you trust (security risk)
+# export HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL=your-custom-model
+# export HINDSIGHT_API_EMBEDDINGS_LOCAL_TRUST_REMOTE_CODE=true
+
 # OpenAI - cloud-based embeddings
 export HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai
 export HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY=sk-xxxxxxxxxxxx  # or reuses HINDSIGHT_API_LLM_API_KEY
@ -302,20 +376,32 @@ export HINDSIGHT_API_EMBEDDINGS_TEI_URL=http://localhost:8080

 # Cohere - cloud-based embeddings
 export HINDSIGHT_API_EMBEDDINGS_PROVIDER=cohere
-export HINDSIGHT_API_COHERE_API_KEY=your-api-key
+export HINDSIGHT_API_EMBEDDINGS_COHERE_API_KEY=your-api-key
 export HINDSIGHT_API_EMBEDDINGS_COHERE_MODEL=embed-english-v3.0  # 1024 dimensions

 # Azure-hosted Cohere - embeddings via custom endpoint
 export HINDSIGHT_API_EMBEDDINGS_PROVIDER=cohere
-export HINDSIGHT_API_COHERE_API_KEY=your-azure-api-key
+export HINDSIGHT_API_EMBEDDINGS_COHERE_API_KEY=your-azure-api-key
 export HINDSIGHT_API_EMBEDDINGS_COHERE_MODEL=embed-english-v3.0
 export HINDSIGHT_API_EMBEDDINGS_COHERE_BASE_URL=https://your-azure-cohere-endpoint.com

 # LiteLLM proxy - unified gateway for multiple providers
 export HINDSIGHT_API_EMBEDDINGS_PROVIDER=litellm
-export HINDSIGHT_API_LITELLM_API_BASE=http://localhost:4000
-export HINDSIGHT_API_LITELLM_API_KEY=your-litellm-key  # optional
+export HINDSIGHT_API_EMBEDDINGS_LITELLM_API_BASE=http://localhost:4000
+export HINDSIGHT_API_EMBEDDINGS_LITELLM_API_KEY=your-litellm-key  # optional
 export HINDSIGHT_API_EMBEDDINGS_LITELLM_MODEL=text-embedding-3-small  # or cohere/embed-english-v3.0
+
+# LiteLLM SDK - direct API access without proxy server (recommended)
+export HINDSIGHT_API_EMBEDDINGS_PROVIDER=litellm-sdk
+export HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_API_KEY=your-provider-api-key
+export HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_MODEL=cohere/embed-english-v3.0
+
+# Supported LiteLLM SDK embedding providers:
+# - cohere/embed-english-v3.0 (1024 dimensions)
+# - openai/text-embedding-3-small (1536 dimensions)
+# - together_ai/togethercomputer/m2-bert-80M-8k-retrieval
+# - huggingface/sentence-transformers/all-MiniLM-L6-v2
+# - voyage/voyage-2
 ```

 #### Embedding Dimensions
@ -338,15 +424,22 @@ Supported OpenAI embedding dimensions:

 | Variable | Description | Default |
 |----------|-------------|---------|
-| `HINDSIGHT_API_RERANKER_PROVIDER` | Provider: `local`, `tei`, `cohere`, `flashrank`, `litellm`, or `rrf` | `local` |
+| `HINDSIGHT_API_RERANKER_PROVIDER` | Provider: `local`, `tei`, `cohere`, `flashrank`, `litellm`, `litellm-sdk`, or `rrf` | `local` |
 | `HINDSIGHT_API_RERANKER_LOCAL_MODEL` | Model for local provider | `cross-encoder/ms-marco-MiniLM-L-6-v2` |
 | `HINDSIGHT_API_RERANKER_LOCAL_MAX_CONCURRENT` | Max concurrent local reranking (prevents CPU thrashing under load) | `4` |
+| `HINDSIGHT_API_RERANKER_LOCAL_TRUST_REMOTE_CODE` | Allow loading models with custom code (security risk, disabled by default) | `false` |
 | `HINDSIGHT_API_RERANKER_TEI_URL` | TEI server URL | - |
 | `HINDSIGHT_API_RERANKER_TEI_BATCH_SIZE` | Batch size for TEI reranking | `128` |
 | `HINDSIGHT_API_RERANKER_TEI_MAX_CONCURRENT` | Max concurrent TEI reranking requests | `8` |
+| `HINDSIGHT_API_RERANKER_COHERE_API_KEY` | Cohere API key for reranking | - |
 | `HINDSIGHT_API_RERANKER_COHERE_MODEL` | Cohere rerank model | `rerank-english-v3.0` |
 | `HINDSIGHT_API_RERANKER_COHERE_BASE_URL` | Custom base URL for Cohere-compatible API (e.g., Azure-hosted) | - |
-| `HINDSIGHT_API_RERANKER_LITELLM_MODEL` | LiteLLM rerank model (use provider prefix, e.g., `cohere/rerank-english-v3.0`) | `cohere/rerank-english-v3.0` |
+| `HINDSIGHT_API_RERANKER_LITELLM_API_BASE` | LiteLLM proxy base URL for reranking | `http://localhost:4000` |
+| `HINDSIGHT_API_RERANKER_LITELLM_API_KEY` | LiteLLM proxy API key for reranking (optional, depends on proxy config) | - |
+| `HINDSIGHT_API_RERANKER_LITELLM_MODEL` | LiteLLM **proxy** rerank model (use provider prefix, e.g., `cohere/rerank-english-v3.0`) | `cohere/rerank-english-v3.0` |
+| `HINDSIGHT_API_RERANKER_LITELLM_SDK_API_KEY` | LiteLLM **SDK** API key for direct reranking (no proxy needed) | - |
+| `HINDSIGHT_API_RERANKER_LITELLM_SDK_MODEL` | LiteLLM SDK rerank model (e.g., `deepinfra/Qwen3-reranker-8B`) | `cohere/rerank-english-v3.0` |
+| `HINDSIGHT_API_RERANKER_LITELLM_SDK_API_BASE` | Custom API base URL for LiteLLM SDK (optional) | - |
 | `HINDSIGHT_API_RERANKER_FLASHRANK_MODEL` | FlashRank model for fast CPU-based reranking | `ms-marco-MiniLM-L-12-v2` |
 | `HINDSIGHT_API_RERANKER_FLASHRANK_CACHE_DIR` | Cache directory for FlashRank models | System default |

@ -355,34 +448,52 @@ Supported OpenAI embedding dimensions:
 export HINDSIGHT_API_RERANKER_PROVIDER=local
 export HINDSIGHT_API_RERANKER_LOCAL_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2

+# Local with custom model requiring trust_remote_code (e.g., jina-reranker-v2)
+# WARNING: Only enable trust_remote_code for models you trust (security risk)
+export HINDSIGHT_API_RERANKER_PROVIDER=local
+export HINDSIGHT_API_RERANKER_LOCAL_MODEL=jinaai/jina-reranker-v2-base-multilingual
+export HINDSIGHT_API_RERANKER_LOCAL_TRUST_REMOTE_CODE=true
+
 # TEI - for high-performance inference
 export HINDSIGHT_API_RERANKER_PROVIDER=tei
 export HINDSIGHT_API_RERANKER_TEI_URL=http://localhost:8081

 # Cohere - cloud-based reranking
 export HINDSIGHT_API_RERANKER_PROVIDER=cohere
-export HINDSIGHT_API_COHERE_API_KEY=your-api-key  # shared with embeddings
+export HINDSIGHT_API_RERANKER_COHERE_API_KEY=your-api-key
 export HINDSIGHT_API_RERANKER_COHERE_MODEL=rerank-english-v3.0

 # Azure-hosted Cohere - reranking via custom endpoint
 export HINDSIGHT_API_RERANKER_PROVIDER=cohere
-export HINDSIGHT_API_COHERE_API_KEY=your-azure-api-key
+export HINDSIGHT_API_RERANKER_COHERE_API_KEY=your-azure-api-key
 export HINDSIGHT_API_RERANKER_COHERE_MODEL=rerank-english-v3.0
 export HINDSIGHT_API_RERANKER_COHERE_BASE_URL=https://your-azure-cohere-endpoint.com

-# LiteLLM proxy - unified gateway for multiple reranking providers
+# LiteLLM proxy - unified gateway for multiple reranking providers (requires running LiteLLM proxy server)
 export HINDSIGHT_API_RERANKER_PROVIDER=litellm
-export HINDSIGHT_API_LITELLM_API_BASE=http://localhost:4000
-export HINDSIGHT_API_LITELLM_API_KEY=your-litellm-key  # optional
+export HINDSIGHT_API_RERANKER_LITELLM_API_BASE=http://localhost:4000
+export HINDSIGHT_API_RERANKER_LITELLM_API_KEY=your-litellm-key  # optional
 export HINDSIGHT_API_RERANKER_LITELLM_MODEL=cohere/rerank-english-v3.0  # or voyage/rerank-2, together_ai/...
+
+# LiteLLM SDK - direct API access without proxy (recommended for simplicity)
+export HINDSIGHT_API_RERANKER_PROVIDER=litellm-sdk
+export HINDSIGHT_API_RERANKER_LITELLM_SDK_API_KEY=your-deepinfra-api-key
+export HINDSIGHT_API_RERANKER_LITELLM_SDK_MODEL=deepinfra/Qwen3-reranker-8B  # or cohere/rerank-english-v3.0, etc.
 ```

-LiteLLM supports multiple reranking providers via the `/rerank` endpoint:
- Cohere (`cohere/rerank-english-v3.0`, `cohere/rerank-multilingual-v3.0`)
- Together AI (`together_ai/...`)
- Voyage AI (`voyage/rerank-2`)
- Jina AI (`jina_ai/...`)
- AWS Bedrock (`bedrock/...`)
+#### LiteLLM Proxy vs SDK
+
+- **`litellm`**: Requires running a separate LiteLLM proxy server. Good for centralized configuration, rate limiting, and caching.
+- **`litellm-sdk`**: Direct API access without proxy. Simpler setup, lower latency, fewer infrastructure components.
+
+Both support the same providers:
+- **Cohere** (`cohere/rerank-english-v3.0`, `cohere/rerank-multilingual-v3.0`)
+- **DeepInfra** (`deepinfra/Qwen3-reranker-8B`, `deepinfra/bge-reranker-v2-m3`)
+- **Together AI** (`together_ai/Salesforce/Llama-Rank-V1`)
+- **HuggingFace** (`huggingface/BAAI/bge-reranker-v2-m3`)
+- **Voyage AI** (`voyage/rerank-2`)
+- **Jina AI** (`jina_ai/jina-reranker-v2`)
+- **AWS Bedrock** (`bedrock/...`)

 ### Authentication

@ -413,6 +524,7 @@ For advanced authentication (JWT, OAuth, multi-tenant schemas), implement a cust
 |----------|-------------|---------|
 | `HINDSIGHT_API_HOST` | Bind address | `0.0.0.0` |
 | `HINDSIGHT_API_PORT` | Server port | `8888` |
+| `HINDSIGHT_API_BASE_PATH` | Base path for API when behind reverse proxy (e.g., `/hindsight`) | `""` (root) |
 | `HINDSIGHT_API_WORKERS` | Number of uvicorn worker processes | `1` |
 | `HINDSIGHT_API_LOG_LEVEL` | Log level: `debug`, `info`, `warning`, `error` | `info` |
 | `HINDSIGHT_API_LOG_FORMAT` | Log format: `text` or `json` (structured logging for cloud platforms) | `text` |
@ -558,6 +670,74 @@ await memory.initialize()

 ---

+## Observability & Tracing
+
+Hindsight provides OpenTelemetry-based observability for LLM calls, conforming to GenAI semantic conventions.
+
+### OpenTelemetry Tracing
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HINDSIGHT_API_OTEL_TRACES_ENABLED` | Enable distributed tracing for LLM calls | `false` |
+| `HINDSIGHT_API_OTEL_EXPORTER_OTLP_ENDPOINT` | OTLP endpoint URL (e.g., Grafana LGTM, Langfuse, etc.) | - |
+| `HINDSIGHT_API_OTEL_EXPORTER_OTLP_HEADERS` | Headers for OTLP exporter (format: "key1=value1,key2=value2") | - |
+| `HINDSIGHT_API_OTEL_SERVICE_NAME` | Service name for traces | `hindsight-api` |
+| `HINDSIGHT_API_OTEL_DEPLOYMENT_ENVIRONMENT` | Deployment environment name (e.g., development, staging, production) | `development` |
+
+**Features:**
+- Full prompts and completions recorded as events
+- Token usage tracking (input/output)
+- Model and provider information
+- Error tracking with finish reasons
+- Conforms to OpenTelemetry GenAI semantic conventions v1.37+
+
+**OTLP-Compatible Backends:**
+
+The tracing implementation uses standard OTLP HTTP protocol, so it works with any OTLP-compatible backend:
+- **Grafana LGTM** (Recommended for local dev): All-in-one stack with Tempo traces, Loki logs, Mimir metrics, and Grafana UI
+- **Langfuse**: LLM-focused observability and analytics
+- **OpenLIT**: Built-in LLM dashboards, cost tracking
+- **DataDog, New Relic, Honeycomb**: Commercial platforms
+
+**Example Configuration:**
+
+```bash
+# Enable tracing
+export HINDSIGHT_API_OTEL_TRACES_ENABLED=true
+
+# Configure endpoint (example: OpenLIT Cloud)
+export HINDSIGHT_API_OTEL_EXPORTER_OTLP_ENDPOINT=https://otlp.openlit.io
+export HINDSIGHT_API_OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer olit-xxx"
+
+# Optional: Custom service name and environment
+export HINDSIGHT_API_OTEL_SERVICE_NAME=hindsight-production
+export HINDSIGHT_API_OTEL_DEPLOYMENT_ENVIRONMENT=production
+```
+
+**Local Development:**
+
+For local development, we recommend the Grafana LGTM stack which provides traces, metrics, and logs in a single container:
+
+```bash
+./scripts/dev/start-grafana.sh
+```
+
+See `scripts/dev/grafana/README.md` for detailed setup instructions.
+
+Other options: See `scripts/dev/openlit/README.md` for OpenLIT or `scripts/dev/jaeger/README.md` for standalone Jaeger.
+
+### Metrics
+
+Hindsight exposes Prometheus metrics at the `/metrics` endpoint, including:
+- LLM call duration and token usage
+- Operation duration (retain/recall/reflect)
+- HTTP request metrics
+- Database connection pool metrics
+
+Metrics are always enabled and available at `http://localhost:8888/metrics`.
+
+---
+
 ## Control Plane

 The Control Plane is the web UI for managing memory banks.
@ -565,12 +745,198 @@ The Control Plane is the web UI for managing memory banks.
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `HINDSIGHT_CP_DATAPLANE_API_URL` | URL of the API service | `http://localhost:8888` |
+| `NEXT_PUBLIC_BASE_PATH` | Base path for Control Plane UI when behind reverse proxy (e.g., `/hindsight`) | `""` (root) |

 ```bash
 # Point Control Plane to a remote API service
 export HINDSIGHT_CP_DATAPLANE_API_URL=http://api.example.com:8888
 ```

+### Hierarchical Configuration
+
+Hindsight supports per-bank configuration overrides through a hierarchical system: **Global (env vars) → Tenant → Bank**.
+
+#### Type-Safe Config Access
+
+To prevent accidentally using global defaults when bank-specific overrides exist, Hindsight enforces type-safe config access:
+
+**In Application Code:**
+```python
+from hindsight_api.config import get_config
+
+# ✅ Access static (infrastructure) fields
+config = get_config()
+host = config.host  # OK - static field
+port = config.port  # OK - static field
+
+# ❌ Attempting to access bank-configurable fields raises an error
+chunk_size = config.retain_chunk_size  # ConfigFieldAccessError!
+```
+
+**Error Message:**
+```
+ConfigFieldAccessError: Field 'retain_chunk_size' is bank-configurable and cannot
+be accessed from global config. Use ConfigResolver.resolve_full_config(bank_id, context)
+to get bank-specific config.
+```
+
+**For Bank-Specific Config:**
+```python
+# Internal code that needs bank-specific settings
+from hindsight_api.config_resolver import ConfigResolver
+
+# Resolve full config for a specific bank
+config = await config_resolver.resolve_full_config(bank_id, request_context)
+chunk_size = config.retain_chunk_size  # ✅ Uses bank-specific value
+```
+
+This design prevents bugs where global defaults are used instead of bank overrides, making it impossible to make this mistake at compile/development time.
+
+#### Security Model
+
+Configuration fields are categorized for security:
+
+1. **Configurable Fields** - Safe behavioral settings that can be customized per-bank:
+   - Retention: `retain_chunk_size`, `retain_extraction_mode`, `retain_custom_instructions`
+   - Consolidation: `enable_observations`
+
+2. **Credential Fields** - NEVER exposed or configurable via API:
+   - API keys: `*_api_key` (all LLM API keys)
+   - Infrastructure: `*_base_url` (all base URLs)
+
+3. **Static Fields** - Server-level only, cannot be overridden:
+   - Infrastructure: `database_url`, `port`, `host`, `worker_count`
+   - Provider/Model selection: `llm_provider`, `llm_model` (requires presets - not yet implemented)
+   - Performance tuning: `llm_max_concurrent`, `llm_timeout`, retrieval settings, optimization flags
+
+#### Enabling the API
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HINDSIGHT_API_ENABLE_BANK_CONFIG_API` | Enable per-bank config API | `false` |
+
+**Important:** The bank config API is **disabled by default** for security. Enable it explicitly:
+
+```bash
+export HINDSIGHT_API_ENABLE_BANK_CONFIG_API=true
+```
+
+#### API Endpoints
+
+- `GET /v1/default/banks/{bank_id}/config` - View resolved config (filtered by permissions)
+- `PATCH /v1/default/banks/{bank_id}/config` - Update bank overrides (only allowed fields)
+- `DELETE /v1/default/banks/{bank_id}/config` - Reset to defaults
+
+#### Permission System
+
+Tenant extensions can control which fields banks are allowed to modify via `get_allowed_config_fields()`:
+
+```python
+class CustomTenantExtension(TenantExtension):
+    async def get_allowed_config_fields(self, context, bank_id):
+        # Option 1: Allow all configurable fields
+        return None
+
+        # Option 2: Allow specific fields only
+        return {"retain_chunk_size", "retain_custom_instructions"}
+
+        # Option 3: Read-only (no modifications)
+        return set()
+```
+
+#### Examples
+
+```bash
+# Update retention settings for a bank
+curl -X PATCH http://localhost:8888/v1/default/banks/my-bank/config \
+  -H "Content-Type: application/json" \
+  -d '{
+    "updates": {
+      "retain_chunk_size": 4000,
+      "retain_extraction_mode": "custom",
+      "retain_custom_instructions": "Focus on technical details and implementation specifics"
+    }
+  }'
+
+# Note: retain_extraction_mode must be "custom" to use retain_custom_instructions
+
+# View resolved config (respects permissions)
+curl http://localhost:8888/v1/default/banks/my-bank/config
+
+# Reset to defaults
+curl -X DELETE http://localhost:8888/v1/default/banks/my-bank/config
+```
+
+**Security Notes:**
+- Credentials (API keys, base URLs) are never returned in responses
+- Only configurable fields can be modified
+- Responses are filtered by tenant permissions
+- Attempting to set credentials returns 400 error
+
+### Reverse Proxy / Subpath Deployment
+
+To deploy Hindsight under a subpath (e.g., `example.com/hindsight/`):
+
+1. Set both environment variables to the same path:
+   ```bash
+   HINDSIGHT_API_BASE_PATH=/hindsight
+   NEXT_PUBLIC_BASE_PATH=/hindsight
+   ```
+
+2. Configure your reverse proxy to:
+   - Forward `/hindsight/*` requests to Hindsight
+   - Preserve the full path in forwarded requests
+   - Set appropriate proxy headers (X-Forwarded-Proto, X-Forwarded-For)
+
+**Example: Nginx Configuration**
+
+```nginx
+location /hindsight/ {
+    proxy_pass http://localhost:8888/;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+**Example: Traefik Configuration**
+
+```yaml
+http:
+  routers:
+    hindsight:
+      rule: "PathPrefix(`/hindsight`)"
+      service: hindsight
+      middlewares:
+        - hindsight-stripprefix
+
+  middlewares:
+    hindsight-stripprefix:
+      stripPrefix:
+        prefixes:
+          - "/hindsight"
+
+  services:
+    hindsight:
+      loadBalancer:
+        servers:
+          - url: "http://localhost:8888"
+```
+
+**Important Notes:**
+- The base path must start with `/` and should NOT end with `/`
+- Both API and Control Plane should use the same base path
+- After setting environment variables, restart both services
+- OpenAPI docs will be available at `<base-path>/docs` (e.g., `/hindsight/docs`)
+
+**Complete Examples:**
+
+See `docker/compose-examples/` directory for:
+- Nginx configuration files (`simple.conf`, `api-and-control-plane.conf`)
+- Docker Compose setups (`docker-compose.yml`, `reverse-proxy-only.yml`)
+- Traefik and other reverse proxy examples
+- Full deployment documentation
 ---

 ## Example .env File
--- a/hindsight-docs/versioned_docs/version-0.4/developer/mcp-server.md
+++ b/hindsight-docs/versioned_docs/version-0.4/developer/mcp-server.md
@ -71,6 +71,7 @@ curl -X POST http://localhost:8888/mcp \
  -H "Authorization: Bearer your-secret-key" \
  -H "X-Bank-Id: my-bank" \
  -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
 ```

@ -78,10 +79,10 @@ If the key is missing or invalid, requests will receive a `401 Unauthorized` res

 ## Bank Selection

-Specify the memory bank via:
+The memory bank is resolved in this priority order:

-1. **X-Bank-Id header** (recommended): `--header "X-Bank-Id: my-bank"`
-2. **URL path**: `http://localhost:8888/mcp/my-bank/`
+1. **URL path** (highest priority): `http://localhost:8888/mcp/my-bank/`
+2. **X-Bank-Id header**: `--header "X-Bank-Id: my-bank"`
 3. **Default**: Uses `HINDSIGHT_MCP_BANK_ID` env var (default: "default")

 ## Per-Bank Endpoints
@ -93,6 +94,19 @@ This design:
 - **Enforces isolation** — each MCP connection is scoped to a single bank
 - **Enables multi-tenant setups** — connect different users to different endpoints

+## Two Modes
+
+The MCP server operates in two modes depending on the URL:
+
+| Mode | URL | Tools | bank_id |
+|------|-----|-------|---------|
+| **Single-bank** | `/mcp/{bank_id}/` | Memory + mental model tools | Implicit from URL |
+| **Multi-bank** | `/mcp/` | All tools including bank management | Explicit `bank_id` parameter on each tool |
+
+**Single-bank mode** (recommended) scopes all operations to the bank in the URL. Tools don't expose a `bank_id` parameter.
+
+**Multi-bank mode** exposes all tools with an optional `bank_id` parameter, plus bank management tools (`list_banks`, `create_bank`).
+
 ---

 ## Available Tools
@ -105,6 +119,7 @@ Store information to long-term memory.
 |-----------|------|----------|-------------|
 | `content` | string | Yes | The fact or memory to store |
 | `context` | string | No | Category for the memory (default: `general`) |
+| `timestamp` | string | No | ISO 8601 timestamp for when the event occurred |

 **Example:**
 ```json
@ -132,7 +147,7 @@ Search memories to provide personalized responses.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `query` | string | Yes | Natural language search query |
-| `max_results` | integer | No | Maximum results to return (default: 10) |
+| `max_tokens` | integer | No | Maximum tokens to return (default: 4096) |

 **Example:**
 ```json
@ -144,21 +159,6 @@ Search memories to provide personalized responses.
 }
 ```

-**Response:**
-```json
-{
-  "results": [
-    {
-      "id": "fact_abc123",
-      "text": "User prefers Python over JavaScript for backend development",
-      "type": "world",
-      "context": "programming_preferences",
-      "event_date": null
-    }
-  ]
-}
-```
-
 **When to use:**
 - Start of conversation to recall relevant context
 - Before making recommendations
@ -195,10 +195,110 @@ Generate thoughtful analysis by synthesizing stored memories with the bank's per

 ---

+### create_mental_model
+
+Create a mental model — a living document that stays current with your memories. Mental models are pre-computed reflections that get automatically refreshed as new memories are stored.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Human-readable name for the mental model |
+| `source_query` | string | Yes | The query used to generate and refresh the model |
+| `mental_model_id` | string | No | Custom ID (alphanumeric lowercase with hyphens). Auto-generated if not provided |
+| `tags` | list[string] | No | Tags for organizing and filtering models |
+| `max_tokens` | integer | No | Maximum tokens for model content (default: 2048) |
+
+**Example:**
+```json
+{
+  "name": "create_mental_model",
+  "arguments": {
+    "name": "Team Directory",
+    "source_query": "Who works here and what do they do?",
+    "tags": ["team", "people"]
+  }
+}
+```
+
+Content generation runs asynchronously. The response includes an `operation_id` to track progress.
+
+---
+
+### list_mental_models
+
+List all mental models in a bank, optionally filtered by tags.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `tags` | list[string] | No | Filter models by tags |
+
+---
+
+### get_mental_model
+
+Retrieve a specific mental model by ID, including its full content.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `mental_model_id` | string | Yes | The ID of the mental model to retrieve |
+
+---
+
+### update_mental_model
+
+Update a mental model's metadata or settings.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `mental_model_id` | string | Yes | The ID of the mental model to update |
+| `name` | string | No | New name |
+| `source_query` | string | No | New source query |
+| `tags` | list[string] | No | New tags |
+| `max_tokens` | integer | No | New max tokens |
+
+---
+
+### delete_mental_model
+
+Permanently delete a mental model.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `mental_model_id` | string | Yes | The ID of the mental model to delete |
+
+---
+
+### refresh_mental_model
+
+Re-generate a mental model's content from the latest memories. Runs asynchronously.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `mental_model_id` | string | Yes | The ID of the mental model to refresh |
+
+---
+
+### list_banks (multi-bank mode only)
+
+List all available memory banks.
+
+---
+
+### create_bank (multi-bank mode only)
+
+Create a new memory bank or retrieve an existing one.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `bank_id` | string | Yes | The ID for the new bank |
+| `name` | string | No | Human-friendly name for the bank |
+| `mission` | string | No | Mission describing who the agent is and what they're trying to accomplish |
+
+---
+
 ## Integration with AI Assistants

 The MCP server can be used with any MCP-compatible AI assistant. See the [Authentication](#authentication) section above for Claude Code and Claude Desktop configuration examples.

 Each user can have their own configuration pointing to their personal memory bank using either:
- The `X-Bank-Id` header (recommended)
- A bank-specific URL path like `/mcp/alice/`
+- A bank-specific URL path like `/mcp/alice/` (recommended)
+- The `X-Bank-Id` header
--- a/hindsight-docs/versioned_docs/version-0.4/developer/monitoring.md
+++ b/hindsight-docs/versioned_docs/version-0.4/developer/monitoring.md
@ -1,22 +1,30 @@
 # Monitoring

-Hindsight provides comprehensive monitoring through Prometheus metrics and pre-built Grafana dashboards.
+Hindsight provides comprehensive observability through Prometheus metrics, OpenTelemetry distributed tracing, and pre-built Grafana dashboards.

 ## Local Development

-For local metrics visualization, a convenience script downloads and runs Prometheus and Grafana:
+For local observability, use the Grafana LGTM (Loki, Grafana, Tempo, Mimir) all-in-one stack:

 ```bash
 ./scripts/dev/start-monitoring.sh
 ```

-This will start:
- **Grafana**: http://localhost:8890 (anonymous access enabled)
- **Prometheus**: http://localhost:8889
- **API Metrics**: http://localhost:8888/metrics
+This starts a single Docker container providing:
+- **Grafana UI**: http://localhost:3000 (anonymous admin access)
+- **Traces (Tempo)**: OTLP endpoint at http://localhost:4318 (HTTP) and http://localhost:4317 (gRPC)
+- **Metrics (Prometheus/Mimir)**: Scrapes http://localhost:8888/metrics automatically
+- **Logs (Loki)**: Available for log aggregation
+- **Pre-built Dashboards**: Hindsight Operations, LLM Metrics, API Service
+
+**Enable tracing in your API:**
+```bash
+export HINDSIGHT_API_OTEL_TRACES_ENABLED=true
+export HINDSIGHT_API_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+```

 :::note Production Deployment
-The local monitoring script is for development only. In production, you need to install and configure Prometheus and Grafana separately, then point Prometheus to scrape your Hindsight API's `/metrics` endpoint.
+The local monitoring stack is for development only. In production, deploy Grafana LGTM separately or use commercial platforms (Grafana Cloud, DataDog, New Relic, etc.).
 :::

 ## Grafana Dashboards
@ -197,3 +205,66 @@ hindsight_db_pool_size - hindsight_db_pool_idle
 ```promql
 rate(hindsight_process_cpu_seconds{type="user"}[1m])
 ```
+
+---
+
+## Distributed Tracing
+
+Hindsight supports OpenTelemetry distributed tracing for memory operations and LLM calls, following GenAI semantic conventions v1.37+.
+
+### Configuration
+
+See [Configuration - OpenTelemetry Tracing](./configuration#opentelemetry-tracing) for environment variables.
+
+**Quick Start:**
+```bash
+# Enable tracing
+export HINDSIGHT_API_OTEL_TRACES_ENABLED=true
+export HINDSIGHT_API_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+
+# View traces with Grafana LGTM (local dev)
+./scripts/dev/start-monitoring.sh
+# Open http://localhost:3000 → Explore → Tempo
+```
+
+Supports any OTLP-compatible backend (Grafana LGTM, Langfuse, OpenLIT, DataDog, New Relic, Honeycomb, etc.).
+
+### Span Hierarchy
+
+**Parent Spans (Operations):**
+- `hindsight.retain` - Memory ingestion
+- `hindsight.recall` - Memory retrieval
+  - `hindsight.recall_embedding` - Query embedding
+  - `hindsight.recall_retrieval` - Parallel search (semantic, BM25, graph, temporal)
+  - `hindsight.recall_fusion` - Reciprocal Rank Fusion
+  - `hindsight.recall_rerank` - Cross-encoder reranking
+- `hindsight.reflect` - Agentic reasoning
+  - `hindsight.reflect_tool_call` - Tool execution (recall, lookup, etc.)
+- `hindsight.consolidation` - Observation synthesis
+- `hindsight.mental_model_refresh` - Mental model updates
+
+**Child Spans (LLM Calls):**
+- Named by scope (e.g., `hindsight.memory`, `hindsight.reflect`)
+- Contain full prompts/completions as events
+- Follow GenAI semantic conventions for attributes
+
+### Span Attributes
+
+**Operation Spans:**
+- `hindsight.operation` - Operation type
+- `hindsight.bank_id` - Memory bank ID
+- `hindsight.query` - Query text (truncated to 100 chars)
+- `hindsight.fact_types` - Fact types for recall
+- `hindsight.thinking_budget` - Budget allocation
+- `hindsight.max_tokens` - Token limit
+
+**LLM Spans (GenAI Semantic Conventions):**
+- `gen_ai.operation.name` - Always `"chat"`
+- `gen_ai.provider.name` - Provider (`openai`, `anthropic`, `google`, etc.)
+- `gen_ai.request.model` - Model name
+- `gen_ai.usage.input_tokens` - Input tokens
+- `gen_ai.usage.output_tokens` - Output tokens
+- `hindsight.scope` - LLM call purpose (`memory`, `reflect`, `consolidation`, etc.)
+
+**Events:**
+- `gen_ai.client.inference.operation.details` - Full prompts and completions
--- a/hindsight-docs/versioned_docs/version-0.4/sdks/integrations/local-mcp.md
+++ b/hindsight-docs/versioned_docs/version-0.4/sdks/integrations/local-mcp.md
@ -132,7 +132,6 @@ Search memories to provide personalized responses.
 |-----------|------|----------|-------------|
 | `query` | string | Yes | Natural language search query |
 | `max_tokens` | integer | No | Maximum tokens to return (default: 4096) |
-| `budget` | string | No | Search depth: `low`, `mid`, or `high` (default: `low`) |

 **Example:**
 ```json
@ -140,8 +139,7 @@ Search memories to provide personalized responses.
  "name": "recall",
  "arguments": {
    "query": "What are the user's color preferences?",
-    "max_tokens": 2048,
-    "budget": "mid"
+    "max_tokens": 2048
  }
 }
 ```
--- a/hindsight-docs/versioned_docs/version-0.4/sdks/integrations/openclaw.md
+++ b/hindsight-docs/versioned_docs/version-0.4/sdks/integrations/openclaw.md
@ -59,6 +59,8 @@ The plugin will automatically:

 **Auto-Recall:** Before each agent response, relevant memories are automatically injected into the context (up to 1024 tokens). The agent uses past context without needing to call tools.

+**Feedback Loop Prevention:** The plugin automatically strips injected memory tags (`<hindsight_memories>`) before storing conversations. This prevents recalled memories from being re-extracted as new facts, which would cause exponential memory growth and duplicate entries.
+
 Traditional memory systems give agents a `search_memory` tool - but models don't use it consistently. Auto-recall solves this by injecting memories automatically before every turn.

 ## Configuration
--- a/hindsight-embed/hindsight_embed/init.py
+++ b/hindsight-embed/hindsight_embed/init.py
@ -3,7 +3,7 @@
 from .daemon_embed_manager import DaemonEmbedManager
 from .embed_manager import EmbedManager

-__version__ = "0.4.10"
+__version__ = "0.4.11"

 __all__ = [
    "EmbedManager",
--- a/hindsight-embed/pyproject.toml
+++ b/hindsight-embed/pyproject.toml
@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "hindsight-embed"
-version = "0.4.10"
+version = "0.4.11"
 description = "Hindsight embedded CLI - local memory operations without a server"
 readme = "README.md"
 requires-python = ">=3.11"
--- a/Show more
+++ b/Show more