fix: hide hf logging

feat(openclaw): add dynamic per-channel memory banks (#290 )
Add support for per-channel memory isolation in OpenClaw plugin. Each channel (Slack, Telegram, Discord, etc.) gets its own memory bank, preventing memory leakage between channels. Changes: - Add deriveBankId() to create channel-specific bank IDs - Bank ID format: {messageProvider}-{channelId} (e.g., slack-C123) - Add getClientForContext() for context-aware client access - Update hook handlers to (event, ctx) signature - Set bank mission on first use per dynamic bank - Add dynamicBankId and bankIdPrefix config options Configuration: - dynamicBankId: true (default) enables per-channel isolation - bankIdPrefix: optional prefix for namespacing (e.g., "prod") Co-authored-by: Claude Opus 4.5 <[email protected]>
2026-02-04 12:57:10 +01:00 · 2026-02-04 11:38:14 +01:00 · 2026-02-04 11:23:30 +01:00 · 2026-02-04 10:24:33 +01:00 · 2026-02-04 10:22:52 +01:00 · 2026-02-03 15:34:41 +01:00
147 changed files with 7628 additions and 557 deletions
@@ -208,6 +208,10 @@ ENV HINDSIGHT_API_LOG_LEVEL=info
 ENV HINDSIGHT_ENABLE_API=true
 ENV HINDSIGHT_ENABLE_CP=false
 ENV PYTHONUNBUFFERED=1
+# Suppress verbose transformers/HuggingFace model loading warnings
+ENV TRANSFORMERS_VERBOSITY=error
+ENV HF_HUB_VERBOSITY=error
+ENV TOKENIZERS_PARALLELISM=false

 CMD ["/app/start-all.sh"]

@@ -336,6 +340,10 @@ ENV HINDSIGHT_CP_DATAPLANE_API_URL=http://localhost:8888
 ENV HINDSIGHT_ENABLE_API=true
 ENV HINDSIGHT_ENABLE_CP=true
 ENV PYTHONUNBUFFERED=1
+# Suppress verbose transformers/HuggingFace model loading warnings
+ENV TRANSFORMERS_VERBOSITY=error
+ENV HF_HUB_VERBOSITY=error
+ENV TOKENIZERS_PARALLELISM=false

 CMD ["/app/start-all.sh"]

@@ -2,8 +2,8 @@ apiVersion: v2
 name: hindsight
 description: Hindsight helm chart
 type: application
-version: 0.4.7
-appVersion: "0.4.7"
+version: 0.4.8
+appVersion: "0.4.8"
 keywords:
  - ai
  - memory
@@ -46,4 +46,4 @@ __all__ = [
    "RemoteTEICrossEncoder",
    "LLMConfig",
 ]
-__version__ = "0.4.7"
+__version__ = "0.4.8"
@@ -9,6 +9,7 @@ Configuration via environment variables - see hindsight_api.config for all env v
 import asyncio
 import logging
 import os
+import warnings
 from abc import ABC, abstractmethod
 from concurrent.futures import ThreadPoolExecutor

@@ -162,11 +163,28 @@ class LocalSTCrossEncoder(CrossEncoderModel):
            except Exception as e:
                logger.warning(f"Failed to detect GPU/MPS, falling back to CPU: {e}")

-        self._model = CrossEncoder(
-            self.model_name,
-            device=device,
-            model_kwargs={"low_cpu_mem_usage": False},
-        )
+        # Suppress verbose transformers warnings during model loading
+        # This suppresses the "UNEXPECTED" warnings from CrossEncoder which are harmless
+        # but look alarming to users (e.g., "embeddings.position_ids | UNEXPECTED")
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=UserWarning)
+            warnings.filterwarnings("ignore", message=".*was not found in model state dict.*")
+            warnings.filterwarnings("ignore", message=".*UNEXPECTED.*")
+
+            # Also suppress transformers library logging temporarily
+            transformers_logger = logging.getLogger("transformers")
+            original_level = transformers_logger.level
+            transformers_logger.setLevel(logging.ERROR)
+
+            try:
+                self._model = CrossEncoder(
+                    self.model_name,
+                    device=device,
+                    model_kwargs={"low_cpu_mem_usage": False},
+                )
+            finally:
+                # Restore original logging level
+                transformers_logger.setLevel(original_level)

        # Initialize shared executor (limited workers naturally limits concurrency)
        if LocalSTCrossEncoder._executor is None:
@@ -11,6 +11,7 @@ Configuration via environment variables - see hindsight_api.config for all env v

 import logging
 import os
+import warnings
 from abc import ABC, abstractmethod

 import httpx
@@ -157,11 +158,28 @@ class LocalSTEmbeddings(Embeddings):
            except Exception as e:
                logger.warning(f"Failed to detect GPU/MPS, falling back to CPU: {e}")

-        self._model = SentenceTransformer(
-            self.model_name,
-            device=device,
-            model_kwargs={"low_cpu_mem_usage": False},
-        )
+        # Suppress verbose transformers warnings during model loading
+        # This suppresses the "UNEXPECTED" warnings from BertModel which are harmless
+        # but look alarming to users (e.g., "embeddings.position_ids | UNEXPECTED")
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", category=UserWarning)
+            warnings.filterwarnings("ignore", message=".*was not found in model state dict.*")
+            warnings.filterwarnings("ignore", message=".*UNEXPECTED.*")
+
+            # Also suppress transformers library logging temporarily
+            transformers_logger = logging.getLogger("transformers")
+            original_level = transformers_logger.level
+            transformers_logger.setLevel(logging.ERROR)
+
+            try:
+                self._model = SentenceTransformer(
+                    self.model_name,
+                    device=device,
+                    model_kwargs={"low_cpu_mem_usage": False},
+                )
+            finally:
+                # Restore original logging level
+                transformers_logger.setLevel(original_level)

        self._dimension = self._model.get_sentence_embedding_dimension()
        logger.info(f"Embeddings: local provider initialized (dim: {self._dimension})")
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "hindsight-api"
-version = "0.4.7"
+version = "0.4.8"
 description = "Hindsight: Agent Memory That Works Like Human Memory"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -1,6 +1,6 @@
 [package]
 name = "hindsight-cli"
-version = "0.4.7"
+version = "0.4.8"
 edition = "2021"
 authors = ["Hindsight Team"]
 description = "A beautiful CLI for Hindsight - semantic memory system"
@@ -7,7 +7,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

-    The version of the OpenAPI document: 0.4.7
+    The version of the OpenAPI document: 0.4.8
    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.7\n"\
+               "Version of the API: 0.4.8\n"\
               "SDK Package Version: 0.0.7".\
               format(env=sys.platform, pyversion=sys.version)

@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -6,7 +6,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -5,7 +5,7 @@

    HTTP API for Hindsight

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

    Do not edit the class manually.
@@ -1,6 +1,6 @@
 [project]
 name = "hindsight-client"
-version = "0.4.7"
+version = "0.4.8"
 description = "Python client for Hindsight - Semantic memory system with personality-driven thinking"
 authors = [
    {name = "Hindsight Team"}
@@ -1,6 +1,6 @@
 {
  "name": "@vectorize-io/hindsight-client",
-  "version": "0.4.7",
+  "version": "0.4.8",
  "description": "TypeScript client for Hindsight - Semantic memory system with personality-driven thinking",
  "main": "./dist/src/index.js",
  "types": "./dist/src/index.d.ts",
@@ -1,6 +1,6 @@
 {
  "name": "@vectorize-io/hindsight-control-plane",
-  "version": "0.4.7",
+  "version": "0.4.8",
  "description": "Control plane for Hindsight - Semantic memory system",
  "bin": {
    "hindsight-control-plane": "./bin/cli.js"
@@ -4,14 +4,14 @@ Syncs content from the hindsight-cookbook repository.

 - Clones the cookbook repo to a temp directory
 - Converts notebooks/*.ipynb → docs/cookbook/recipes/*.md
- Converts app directories (with README.md) → docs/cookbook/applications/*.md
+- Converts applications/*/ directories (with README.md) → docs/cookbook/applications/*.md
 - Updates sidebars.ts with the new entries

 Usage: sync-cookbook (after installing hindsight-dev)

 Conventions in cookbook repo:
 - notebooks/*.ipynb → Recipes (use cases, tutorials)
- Directories with README.md at root → Applications (complete apps)
+- applications/*/ directories with README.md → Applications (complete apps)
 - Notebook title extracted from first # heading in first markdown cell
 - App title extracted from first # heading in README.md
 """
@@ -236,7 +236,13 @@ def process_applications(cookbook_dir: Path, apps_dir: Path) -> list[dict]:
    """Process application directories with README.md."""
    apps = []

-    for entry in sorted(cookbook_dir.iterdir()):
+    # Applications are now in the applications/ subdirectory
+    applications_dir = cookbook_dir / "applications"
+    if not applications_dir.exists():
+        print("  No applications directory found")
+        return apps
+
+    for entry in sorted(applications_dir.iterdir()):
        if not entry.is_dir() or entry.name in IGNORE_DIRS:
            continue

@@ -253,7 +259,7 @@ def process_applications(cookbook_dir: Path, apps_dir: Path) -> list[dict]:
        readme_content = readme_path.read_text()

        # Create application page with frontmatter
-        app_url = f"https://github.com/vectorize-io/hindsight-cookbook/tree/main/{entry.name}"
+        app_url = f"https://github.com/vectorize-io/hindsight-cookbook/tree/main/applications/{entry.name}"

        frontmatter = f"""---
 sidebar_position: {len(apps) + 1}
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"

 [project]
 name = "hindsight-dev"
-version = "0.4.7"
+version = "0.4.8"
 description = "Development utilities for Hindsight"
 requires-python = ">=3.11"
 dependencies = [
@@ -0,0 +1,120 @@
+---
+sidebar_position: 1
+---
+
+# Chat Memory App
+
+
+:::info Complete Application
+This is a complete, runnable application demonstrating Hindsight integration.
+[**View source on GitHub →**](https://github.com/vectorize-io/hindsight-cookbook/tree/main/applications/chat-memory)
+:::
+
+
+A demo chat application that uses Groq's `qwen/qwen3-32b` model with Hindsight for persistent per-user memory.
+
+## Features
+
+- 🧠 **Persistent Memory**: Each user gets their own memory bank that remembers conversations
+- 🚀 **Fast AI**: Powered by Groq's high-speed inference
+- 🎯 **Per-User Context**: Isolated memory per user with automatic context retrieval
+- 💬 **Real-time Chat**: Instant responses with memory-augmented context
+
+## Setup
+
+### 1. Start Hindsight API
+
+First, start the Hindsight API server using Docker:
+
+```bash
+export GROQ_API_KEY=your_groq_api_key_here
+
+# Start Hindsight with Groq as the LLM provider
+docker run --rm -it --pull always -p 8888:8888 -p 9999:9999 \
+  -e HINDSIGHT_API_LLM_PROVIDER=groq \
+  -e HINDSIGHT_API_LLM_API_KEY=$GROQ_API_KEY \
+  -e HINDSIGHT_API_LLM_MODEL="openai/gpt-oss-20b" \
+  -v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
+  ghcr.io/vectorize-io/hindsight:latest
+```
+
+- **API**: http://localhost:8888
+- **Control Plane UI**: http://localhost:9999
+
+### 2. Configure Environment
+
+Copy your Groq API key to the environment file:
+
+```bash
+# Update .env.local with your Groq API key
+echo "GROQ_API_KEY=your_groq_api_key_here" > .env.local
+echo "HINDSIGHT_API_URL=http://localhost:8888" >> .env.local
+```
+
+If you don't have one, you can get a free Groq API key here: https://console.groq.com/home
+
+### 3. Install Dependencies
+
+```bash
+npm install
+```
+
+### 4. Run the App
+
+```bash
+npm run dev
+```
+
+Open http://localhost:3000 in your browser.
+
+## How It Works
+
+1. **User Identity**: Each browser session gets a unique user ID
+2. **Memory Bank Creation**: First message creates a personal memory bank in Hindsight
+3. **Context Retrieval**: Before responding, relevant memories are retrieved
+4. **Memory Augmented Response**: Groq generates responses with memory context
+5. **Conversation Storage**: Each conversation is stored for future context
+
+## Architecture
+
+```
+User Message
+     ↓
+Next.js API Route (/api/chat)
+     ↓
+Hindsight.recall() → Get relevant memories
+     ↓
+Groq API → Generate response with memory context
+     ↓
+Hindsight.retain() → Store conversation
+     ↓
+Response to User
+```
+
+## Memory Bank Structure
+
+Each user gets their own isolated memory bank with:
+- **Name**: "Chat Memory for [userId]"
+- **Background**: Conversational AI assistant context
+- **Disposition**: Empathetic (4), Low Skepticism (2), Balanced Literalism (3)
+
+## Try It Out
+
+1. **First Conversation**: Tell the assistant about yourself
+   - "Hi! I'm a software engineer from San Francisco. I love Python and machine learning."
+
+2. **Second Conversation**: Ask what it remembers
+   - "What do you know about me?"
+   - "What programming languages do I like?"
+
+3. **Context Building**: Continue sharing preferences
+   - "I prefer VS Code over other editors"
+   - "I'm working on a React project"
+
+4. **Memory Verification**: Visit the Hindsight Control Plane at http://localhost:9999 to see stored memories
+
+## Development
+
+- **Groq Model**: Uses `qwen/qwen3-32b` for fast, high-quality responses
+- **Memory Storage**: Automatic conversation retention with context categorization
+- **Memory Retrieval**: Semantic search with 2048 token budget for relevant context
@@ -0,0 +1,145 @@
+---
+sidebar_position: 2
+---
+
+# Deliveryman Demo
+
+
+:::info Complete Application
+This is a complete, runnable application demonstrating Hindsight integration.
+[**View source on GitHub →**](https://github.com/vectorize-io/hindsight-cookbook/tree/main/applications/deliveryman-demo)
+:::
+
+
+A delivery agent simulation that demonstrates Hindsight's long-term memory capabilities. An AI agent navigates a multi-building office complex to deliver packages, learning employee locations and optimal paths over time through mental models.
+
+## Prerequisites
+
+- Python 3.11+
+- Node.js 18+
+- [uv](https://docs.astral.sh/uv/) (Python package manager)
+
+## Setup (Fresh Environment)
+
+### 1. Clone Repositories
+
+```bash
+# Clone Hindsight (memory engine)
+git clone https://github.com/anthropics/hindsight.git
+
+# Clone the cookbook (contains this demo)
+git clone https://github.com/anthropics/hindsight-cookbook.git
+```
+
+### 2. Start Hindsight API
+
+```bash
+cd hindsight
+cp .env.example .env
+```
+
+Edit `.env` with your LLM configuration:
+
+```bash
+HINDSIGHT_API_LLM_PROVIDER=groq
+HINDSIGHT_API_LLM_API_KEY=<your-groq-api-key>
+HINDSIGHT_API_LLM_MODEL=openai/gpt-oss-120b
+HINDSIGHT_API_HOST=0.0.0.0
+HINDSIGHT_API_PORT=8888
+HINDSIGHT_API_ENABLE_OBSERVATIONS=true
+
+# Retain extraction settings (improves employee/location extraction)
+HINDSIGHT_API_RETAIN_EXTRACTION_MODE=custom
+HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS="Delivery agent. Remember employee locations, building layout, and optimal paths."
+
+# Embedded database storage
+PG0_DATA_DIR=/tmp/hindsight-data
+```
+
+Start the API:
+
+```bash
+./scripts/dev/start-api.sh
+# Runs on http://localhost:8888
+```
+
+### 3. Start Hindsight Control Plane (Optional)
+
+The control plane provides a web UI for inspecting memory banks, facts, and mental models.
+
+```bash
+cd hindsight
+./scripts/dev/start-control-plane.sh
+# Runs on a dynamic port (check terminal output)
+```
+
+### 4. Start Demo Backend
+
+```bash
+cd hindsight-cookbook/deliveryman-demo/backend
+
+# Create virtual environment and install dependencies
+python -m venv .venv
+source .venv/bin/activate
+pip install -r requirements.txt
+```
+
+Create `backend/.env`:
+
+```bash
+OPENAI_API_KEY=<your-openai-api-key>
+GROQ_API_KEY=<your-groq-api-key>
+HINDSIGHT_API_URL=http://localhost:8888
+LLM_MODEL=openai/gpt-4o
+```
+
+Start the backend:
+
+```bash
+./run.sh
+# Or manually:
+python -m uvicorn app.main:app --host 0.0.0.0 --port 8000 --ws wsproto --reload
+```
+
+**Note:** The `--ws wsproto` flag is required for WebSocket support. Without it, connections will fail with error 1006.
+
+### 5. Start Demo Frontend
+
+```bash
+cd hindsight-cookbook/deliveryman-demo/frontend
+npm install
+npm run dev
+# Runs on http://localhost:5173
+```
+
+### 6. Open the Demo
+
+Navigate to http://localhost:5173 in your browser.
+
+## How It Works
+
+1. The agent receives a delivery task (e.g., "Deliver Package #3954 to Victor Huang")
+2. It navigates a multi-building complex with floors, elevators, and sky bridges
+3. Along the way it encounters employees and learns their locations
+4. After each delivery, the conversation is sent to Hindsight via the **retain** API
+5. Hindsight extracts facts (employee locations, building layout) and builds **mental models**
+6. On subsequent deliveries, the agent queries Hindsight to recall what it learned
+
+## Architecture
+
+```
+Browser (5173) → Frontend (React + Phaser)
+                    ↓ WebSocket
+                 Backend (8000) → FastAPI + Delivery Agent
+                    ↓ HTTP
+                 Hindsight API (8888) → Memory Engine + PostgreSQL
+```
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| WebSocket error 1006 | Restart backend with `--ws wsproto` flag |
+| Mental models missing employees | Check `HINDSIGHT_API_RETAIN_EXTRACTION_MODE=custom` is set |
+| Hindsight connection refused | Verify Hindsight API is running on port 8888 |
+| Frontend shows "Disconnected" | Check backend is running on port 8000 |
@@ -0,0 +1,206 @@
+---
+sidebar_position: 3
+---
+
+# Memory Approaches Comparison Demo
+
+
+:::info Complete Application
+This is a complete, runnable application demonstrating Hindsight integration.
+[**View source on GitHub →**](https://github.com/vectorize-io/hindsight-cookbook/tree/main/applications/hindsight-litellm-demo)
+:::
+
+
+Interactive Streamlit app comparing three memory approaches for LLM applications:
+
+1. **No Memory** - Each query is independent (baseline)
+2. **Full Conversation History** - Pass entire conversation (truncated to simulate context limits)
+3. **Hindsight Memory** - Intelligent semantic memory retrieval
+
+This demo showcases how Hindsight's semantic memory outperforms traditional approaches, especially as conversations grow longer.
+
+## Quick Start
+
+```bash
+# 1. Set your OpenAI API key
+export OPENAI_API_KEY=your-key
+
+# 2. Start Hindsight server
+docker run -d -p 8888:8888 -p 9999:9999 \
+  -e HINDSIGHT_API_LLM_PROVIDER=openai \
+  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
+  ghcr.io/vectorize-io/hindsight:latest
+
+# 3. Run the demo
+./run.sh
+```
+
+Then open http://localhost:8501 in your browser.
+
+## What This Demo Shows
+
+### The Problem with Traditional Approaches
+
+| Approach | How it Works | Limitation |
+|----------|--------------|------------|
+| **No Memory** | Each query standalone | Forgets everything between messages |
+| **Full History** | Pass all messages to LLM | Token limits cause truncation - loses early context |
+| **Hindsight** | Semantic retrieval of relevant facts | Retrieves what's relevant regardless of when it was said |
+
+### Key Insight
+
+After 5-10 messages, watch the **Full Conversation History** column start losing early context due to truncation (artificially set to 4 messages to demonstrate this quickly). Meanwhile, **Hindsight Memory** can still recall facts from the beginning because it uses semantic retrieval rather than sequential history.
+
+## Testing the Demo
+
+1. **Introduce yourself**:
+   - "Hi, I'm Sarah, a data scientist at Netflix"
+   - "I prefer Python and love machine learning"
+
+2. **Have several exchanges** about different topics
+
+3. **Test recall**:
+   - "What programming language should I use?"
+   - "What do you know about me?"
+
+Watch how the three columns respond differently as the conversation grows.
+
+## Features
+
+- **Side-by-side comparison** of all three approaches
+- **Debug panels** showing what context each approach uses
+- **Memory explorer** to search Hindsight memories directly
+- **Configurable settings** for history truncation, max memories, etc.
+- **Multi-provider support** via LiteLLM (OpenAI, Anthropic, Groq)
+
+## Prerequisites
+
+- Python 3.10+
+- Hindsight server running (Docker recommended)
+- At least one LLM API key (OpenAI recommended)
+
+## Setup
+
+### Using run.sh (Recommended)
+
+```bash
+# Set API key
+export OPENAI_API_KEY=your-key
+
+# Start Hindsight, then run:
+./run.sh
+```
+
+The script will check and install dependencies automatically.
+
+### Manual Setup
+
+```bash
+# Install dependencies
+pip install streamlit litellm
+
+# Install Hindsight packages
+pip install hindsight-client hindsight-litellm
+
+# Run the app
+streamlit run app.py
+```
+
+### Starting Hindsight Server
+
+```bash
+docker run -d -p 8888:8888 -p 9999:9999 \
+  -e HINDSIGHT_API_LLM_PROVIDER=openai \
+  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
+  ghcr.io/vectorize-io/hindsight:latest
+
+# Verify it's running
+curl http://localhost:8888/health
+```
+
+## Configuration
+
+### Sidebar Options
+
+**Model Selection:**
+- Provider: OpenAI, Anthropic, Groq
+- Model: Various models per provider
+- Custom model ID support
+
+**Full History Config:**
+- Max Messages to Keep (default: 4 to demonstrate truncation)
+
+**Hindsight Config:**
+- API URL (default: http://localhost:8888)
+- Bank ID and Entity ID for memory isolation
+- Max Memories to retrieve
+- Recall Budget (low/mid/high)
+
+**Generation Settings:**
+- Temperature
+- Max Tokens
+- System Prompt
+
+## Supported Models
+
+### OpenAI
+- gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4, gpt-3.5-turbo
+
+### Anthropic
+- claude-3-5-sonnet-20241022, claude-3-5-haiku-20241022
+- claude-3-opus-20240229, claude-3-sonnet-20240229
+
+### Groq
+- groq/llama-3.1-70b-versatile, groq/llama-3.1-8b-instant
+- groq/mixtral-8x7b-32768
+
+## Environment Variables
+
+```bash
+# Required
+export OPENAI_API_KEY=sk-...
+
+# Optional (for other providers)
+export ANTHROPIC_API_KEY=sk-ant-...
+export GROQ_API_KEY=gsk_...
+
+# Optional
+export HINDSIGHT_URL=http://localhost:8888
+```
+
+## Troubleshooting
+
+### Hindsight server not responding
+
+```bash
+# Check if running
+curl http://localhost:8888/health
+
+# Start with Docker
+docker run -d -p 8888:8888 -p 9999:9999 \
+  -e HINDSIGHT_API_LLM_PROVIDER=openai \
+  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
+  ghcr.io/vectorize-io/hindsight:latest
+```
+
+### hindsight-litellm not installed
+
+```bash
+pip install hindsight-litellm
+```
+
+### API key errors
+
+Make sure the appropriate API key is set:
+```bash
+export OPENAI_API_KEY=your-key
+```
+
+## Related
+
+- [Hindsight](https://github.com/vectorize-io/hindsight) - Memory infrastructure for AI applications
+- [hindsight-litellm](https://github.com/vectorize-io/hindsight/tree/main/hindsight-integrations/litellm) - LiteLLM integration package
+
+## License
+
+MIT
@@ -0,0 +1,123 @@
+---
+sidebar_position: 4
+---
+
+# Tool Learning Demo
+
+
+:::info Complete Application
+This is a complete, runnable application demonstrating Hindsight integration.
+[**View source on GitHub →**](https://github.com/vectorize-io/hindsight-cookbook/tree/main/applications/hindsight-tool-learning-demo)
+:::
+
+
+An interactive Streamlit demo showing how Hindsight helps LLMs learn which tool to use when tool names are ambiguous.
+
+## The Problem
+
+When building AI agents with tool/function calling, tool names and descriptions aren't always clear. An LLM might randomly select between similarly-named tools, leading to incorrect behavior.
+
+## The Scenario
+
+This demo simulates a **customer service routing system** with two channels:
+
+| Tool | Description (What the LLM sees) | Actual Purpose (Hidden) |
+|------|--------------------------------|------------------------|
+| `route_to_channel_alpha` | "Routes to channel Alpha for appropriate request types" | Financial issues (refunds, billing, payments) |
+| `route_to_channel_omega` | "Routes to channel Omega for appropriate request types" | Technical issues (bugs, features, errors) |
+
+The descriptions are **intentionally vague**! Without prior knowledge, the LLM must guess which channel handles what.
+
+## The Solution: Learning with Hindsight
+
+With Hindsight memory:
+1. **Store routing feedback** about which channel handles which request type
+2. **Retrieve learned knowledge** when making routing decisions
+3. **Consistently route correctly** based on past experience
+
+## Quick Start
+
+### Prerequisites
+
+1. **Hindsight Server** running (Docker):
+```bash
+docker run -d -p 8888:8888 -p 9999:9999 \
+  -e HINDSIGHT_API_LLM_PROVIDER=openai \
+  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
+  -e HINDSIGHT_API_LLM_MODEL=gpt-4o-mini \
+  ghcr.io/vectorize-io/hindsight:latest
+```
+
+2. **OpenAI API Key**:
+```bash
+export OPENAI_API_KEY=your-key-here
+```
+
+### Run the Demo
+
+```bash
+./run.sh
+```
+
+Or manually:
+```bash
+pip install -r requirements.txt
+streamlit run app.py
+```
+
+## How to Use the Demo
+
+### Step 1: Test Without Memory (Baseline)
+
+1. Select a **Financial Request** (e.g., "I need a refund...")
+2. Click **Route Request**
+3. Observe: The "Without Hindsight" column may route incorrectly
+
+### Step 2: Route First Customer and Learn
+
+1. Route a customer → Both LLMs route simultaneously
+2. Feedback is automatically stored to Hindsight
+3. Wait ~5 seconds for Hindsight to index the memory
+
+### Step 3: Test With Memory
+
+1. Select another request (financial or technical)
+2. Click **Route Request**
+3. Observe: The "With Hindsight" column should now route correctly!
+
+### Step 4: View Statistics
+
+- See accuracy comparison between "Without Memory" vs "With Hindsight"
+- Review test history to see the improvement over time
+
+## Demo Features
+
+- **Side-by-side comparison**: See routing results with and without memory
+- **Pre-defined test requests**: Financial and technical scenarios
+- **Custom requests**: Enter your own customer requests
+- **Memory Explorer**: Query stored routing knowledge directly
+- **Live statistics**: Track accuracy improvement
+
+## Key Insight
+
+> Even when tool names and descriptions don't reveal their purpose, Hindsight allows the LLM to **learn from experience** which tool to use for which type of request.
+
+This is especially valuable for:
+- Enterprise systems with legacy tool names
+- Multi-tenant systems where tools have generic names
+- Agents that need to learn organization-specific workflows
+
+## Configuration
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Model | gpt-4o-mini | LLM model for routing decisions |
+| Temperature (No Memory) | 0.7 | Randomness for baseline tests |
+| Hindsight API URL | http://localhost:8888 | Hindsight server URL |
+
+## Files
+
+- `app.py` - Main Streamlit application
+- `requirements.txt` - Python dependencies
+- `run.sh` - Launch script with dependency checking
+- `README.md` - This file
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 1
+sidebar_position: 5
 ---

 # OpenAI Agent + Hindsight Memory Integration
@@ -7,7 +7,7 @@ sidebar_position: 1

 :::info Complete Application
 This is a complete, runnable application demonstrating Hindsight integration.
-[**View source on GitHub →**](https://github.com/vectorize-io/hindsight-cookbook/tree/main/openai-fitness-coach)
+[**View source on GitHub →**](https://github.com/vectorize-io/hindsight-cookbook/tree/main/applications/openai-fitness-coach)
 :::


@@ -22,7 +22,7 @@ This example showcases:
 - **Function calling** to bridge them together
 - **Streaming responses** for real-time interaction (enabled by default)
 - **Bidirectional memory** - both user data AND coach observations stored
- **System-level post-processing** - automatic knowledge consolidation
+- **System-level post-processing** - automatic opinion storage for reliability
 - **Temporal-semantic memory** queries via function tools
 - **Enhanced preference learning** - coach learns and respects user likes/dislikes
 - **Real-world integration pattern** for adding memory to AI agents
@@ -46,9 +46,9 @@ Hindsight API (returns workouts + preferences)
    |
 OpenAI Assistant (analyzes, gives advice)
    |
-Function Call: store_memory(advice as experience)
+Function Call: store_memory(advice as opinion)
    |
-Hindsight API (stores coach's advice, consolidates into observations)
+Hindsight API (stores coach's observation)
    |
 Personalized Answer
 ```
@@ -57,10 +57,10 @@ Personalized Answer

 | Component | Standard Demo | OpenAI Integration |
 |-----------|---------------|-------------------|
-| **Conversation** | Hindsight `/reflect` endpoint | OpenAI Assistant API |
+| **Conversation** | Hindsight `/think` endpoint | OpenAI Assistant API |
 | **Memory** | Hindsight (built-in) | Hindsight (via function calling) |
 | **LLM** | Configured in Hindsight | OpenAI GPT-4 |
-| **Knowledge Consolidation** | Automatic after retain | Automatic after retain |
+| **Opinion Formation** | Automatic in `/think` | Explicit via `store_memory(type="opinion")` |
 | **Best For** | Hindsight-native apps | Integrating memory into existing OpenAI agents |

 ## Quick Start
@@ -126,7 +126,7 @@ retrieve_memories(query, fact_types, top_k)
 search_workouts(after_date, before_date, workout_type)
 get_nutrition_summary(after_date, before_date)
 get_user_goals()
-get_coach_insights(about)  # Retrieves observations
+get_coach_opinions(about)
 ```

 Each function makes API calls to Hindsight to fetch relevant memories.
@@ -191,8 +191,8 @@ The agent will automatically:
 The OpenAI Agent can retrieve different memory types from Hindsight:

 - **World Facts** (`fact_type: "world"`): Workouts, meals, activities
- **Experience Facts** (`fact_type: "experience"`): Goals, intentions, coach advice
- **Observations** (`fact_type: "observation"`): Consolidated knowledge about user patterns
+- **Agent Facts** (`fact_type: "agent"`): Goals, intentions
+- **Opinions** (`fact_type: "opinion"`): Coach's observations about patterns

 ## Customization

@@ -266,9 +266,9 @@ The key benefit: **Separation of concerns**

 **Use Hindsight directly when:**
 - You want a complete memory-first solution
- You want automatic memory retrieval and observation consolidation
+- You want automatic memory retrieval and opinion formation
 - You want to use different LLM providers (not just OpenAI)
- You want the `/reflect` endpoint's integrated approach
+- You want the `/think` endpoint's integrated approach

 ## Learning Points

@@ -0,0 +1,371 @@
+---
+sidebar_position: 6
+---
+
+# Sanity CMS Blog Memory
+
+
+:::info Complete Application
+This is a complete, runnable application demonstrating Hindsight integration.
+[**View source on GitHub →**](https://github.com/vectorize-io/hindsight-cookbook/tree/main/applications/sanity-blog-memory)
+:::
+
+
+A Hindsight cookbook recipe demonstrating how to sync blog posts from **Sanity CMS** to Hindsight agent memory, enabling semantic search, temporal queries, and AI-powered content insights.
+
+## Features
+
+- **Blog Post Sync**: Automatically sync all blog posts from Sanity to Hindsight
+- **Document-based Upsert**: Idempotent syncing with `document_id` - re-running sync updates existing content
+- **Semantic Search**: Find related content using natural language queries
+- **Temporal Queries**: Ask "What did I write in January 2025?"
+- **Reflect for Insights**: Generate AI-powered analysis of your blog content
+- **Related Content Discovery**: Power "Related Posts" features with semantic similarity
+
+## Architecture
+
+```
+┌─────────────────┐         ┌─────────────────┐         ┌─────────────────┐
+│                 │         │                 │         │                 │
+│   Sanity CMS    │───────▶│    Sync Script  │───────▶│   Hindsight     │
+│   (Content)     │  GROQ   │   (TypeScript)  │  HTTP   │   (Memory)      │
+│                 │         │                 │         │                 │
+└─────────────────┘         └─────────────────┘         └─────────────────┘
+                                                               │
+                                                               ▼
+                                                        ┌─────────────────┐
+                                                        │                 │
+                                                        │   Your App      │
+                                                        │   - Recall      │
+                                                        │   - Reflect     │
+                                                        │                 │
+                                                        └─────────────────┘
+```
+
+## Quick Start
+
+### 1. Start Hindsight
+
+Choose your preferred LLM provider:
+
+**Option A: Using Docker Compose (Recommended)**
+
+```bash
+# Set your API key
+export OPENAI_API_KEY=sk-...
+# OR
+export GOOGLE_API_KEY=...  # Gemini (free tier available)
+# OR
+export GROQ_API_KEY=...    # Groq (free tier available)
+
+# Start Hindsight
+docker compose up -d
+```
+
+**Option B: Using Docker directly**
+
+```bash
+export OPENAI_API_KEY=sk-...
+
+docker run --rm -it --pull always -p 8888:8888 -p 9999:9999 \
+  -e HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY \
+  -e HINDSIGHT_API_LLM_MODEL=gpt-4o-mini \
+  -v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
+  ghcr.io/vectorize-io/hindsight:latest
+```
+
+- **API**: http://localhost:8888
+- **Control Plane UI**: http://localhost:9999
+
+### 2. Configure Environment
+
+```bash
+# Copy example config
+cp .env.example .env
+
+# Edit with your values
+nano .env
+```
+
+Required settings:
+```bash
+# Hindsight
+HINDSIGHT_API_URL=http://localhost:8888
+HINDSIGHT_BANK_ID=blog-memory
+
+# Sanity CMS
+SANITY_PROJECT_ID=your-project-id
+SANITY_DATASET=production
+```
+
+### 3. Install Dependencies
+
+```bash
+npm install
+```
+
+### 4. Sync Your Blog Posts
+
+```bash
+npm run sync
+```
+
+Expected output:
+```
+=======================================
+  Sanity -> Hindsight Blog Sync
+=======================================
+
+Setting up memory bank...
+Memory bank "blog-memory" ready
+
+Fetching posts from Sanity CMS...
+Found 10 posts to sync
+
+Syncing posts to Hindsight...
+  [1/10] "Why I Chose Qwik"... done
+  [2/10] "Building AI Agents"... done
+  ...
+
+=======================================
+  Sync Complete
+=======================================
+  Synced: 10 posts
+```
+
+### 5. Query Your Content
+
+```bash
+npm run query
+```
+
+## Query Examples
+
+### Semantic Search
+
+Find related content using natural language:
+
+```typescript
+import { recallMemory } from './hindsight-client.js';
+
+// Find posts about AI agents
+const result = await recallMemory('AI agents and automation', {
+  budget: 'mid',
+  maxTokens: 2048,
+});
+
+console.log(`Found ${result.results.length} relevant posts`);
+```
+
+### Temporal Queries
+
+Ask about content from specific time periods:
+
+```typescript
+// Posts from January 2025
+const result = await recallMemory('What did I write about in January 2025?', {
+  queryTimestamp: '2025-01-31T23:59:59Z',
+});
+```
+
+### Reflect for Insights
+
+Generate AI-powered analysis of your content:
+
+```typescript
+import { reflectOnMemory } from './hindsight-client.js';
+
+// Analyze blog themes
+const insights = await reflectOnMemory(
+  'What are the main themes of my blog? What topics do I write about most?',
+  { budget: 'high' }
+);
+
+console.log(insights.text);
+```
+
+### Related Content Discovery
+
+Power your "Related Posts" feature:
+
+```typescript
+// Find posts similar to a specific article
+const related = await recallMemory(
+  'Find posts related to "Why I Chose Qwik for My Personal Website"',
+  { budget: 'mid' }
+);
+```
+
+## Memory Structure
+
+Each blog post is stored with rich metadata for optimal recall:
+
+```
+# Blog Post: {title}
+
+**Published:** {date}
+**URL:** {base_url}/blog/{slug}
+**Tags:** {tags}
+**Reading Time:** {reading_time}
+
+## Description
+{description}
+
+## Content
+{full_content}
+```
+
+Key features:
+- **document_id**: `post:{slug}` - Enables upsert on re-sync
+- **context**: `blog-post` - Categorizes the memory type
+- **timestamp**: Post publication date - Enables temporal queries
+
+## Use Cases
+
+### 1. AI-Powered Blog Search
+
+Replace keyword search with semantic understanding:
+
+```typescript
+// Old: keyword matching
+const results = posts.filter(p => p.title.includes('React'));
+
+// New: semantic understanding
+const result = await recallMemory('frontend framework tutorials');
+```
+
+### 2. Content Recommendation Engine
+
+Generate personalized recommendations:
+
+```typescript
+const recommendations = await reflectOnMemory(
+  'Based on a reader interested in "AI automation", recommend related posts'
+);
+```
+
+### 3. Writing Assistant
+
+Get topic suggestions based on your existing content:
+
+```typescript
+const suggestions = await reflectOnMemory(
+  'What topics should I write about next? What gaps exist in my content?'
+);
+```
+
+### 4. Content Analytics
+
+Analyze your blog's evolution:
+
+```typescript
+const analysis = await reflectOnMemory(
+  'How have my writing topics evolved over the past year?'
+);
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HINDSIGHT_API_URL` | Hindsight API endpoint | `http://localhost:8888` |
+| `HINDSIGHT_BANK_ID` | Memory bank identifier | `blog-memory` |
+| `SANITY_PROJECT_ID` | Your Sanity project ID | (required) |
+| `SANITY_DATASET` | Sanity dataset name | `production` |
+| `SANITY_API_TOKEN` | Sanity API token (for private datasets) | (none) |
+| `SANITY_API_VERSION` | Sanity API version | `2024-01-09` |
+| `SITE_URL` | Your blog's base URL | `https://example.com` |
+
+### Memory Bank Disposition
+
+The memory bank is configured with disposition traits optimized for blog content:
+
+```typescript
+{
+  skepticism: 2,   // Trusting - blog content is authoritative
+  literalism: 4,   // Literal - exact content matters
+  empathy: 3,      // Balanced
+}
+```
+
+## Extending for Other CMS Platforms
+
+This pattern can be adapted for any CMS. The key components:
+
+### 1. CMS Client
+
+Replace `sanity-client.ts` with your CMS:
+
+```typescript
+// contentful-client.ts
+import { createClient } from 'contentful';
+
+export async function getAllPosts(): Promise<BlogPost[]> {
+  const client = createClient({...});
+  const entries = await client.getEntries({ content_type: 'blogPost' });
+  return entries.items.map(transformPost);
+}
+```
+
+### 2. Content Transformation
+
+Ensure your content is formatted for semantic search:
+
+```typescript
+function formatPostContent(post: BlogPost): string {
+  return `# ${post.title}
+  
+**Published:** ${post.date}
+...
+${post.content}`;
+}
+```
+
+### 3. Document ID Strategy
+
+Use a consistent document ID for upsert behavior:
+
+```typescript
+await retainBlogPost(content, {
+  documentId: `post:${post.slug}`,  // Unique, stable identifier
+  timestamp: post.date,
+});
+```
+
+## Troubleshooting
+
+### "Connection refused" error
+
+Make sure Hindsight is running:
+```bash
+docker compose up -d
+curl http://localhost:8888/health
+```
+
+### "No posts found" during sync
+
+Check your Sanity configuration:
+```bash
+# Verify project ID
+echo $SANITY_PROJECT_ID
+
+# Test GROQ query
+npx sanity query '*[_type == "post"][0..2]{title}'
+```
+
+### Slow recall/reflect responses
+
+This is normal for the first query as Hindsight builds embeddings. Subsequent queries are faster. Use `budget: 'low'` for faster responses at the cost of recall quality.
+
+## Resources
+
+- [Hindsight Documentation](https://hindsight.vectorize.io/)
+- [Hindsight GitHub](https://github.com/vectorize-io/hindsight)
+- [Sanity CMS Documentation](https://www.sanity.io/docs)
+- [Hindsight Cookbook](https://github.com/vectorize-io/hindsight-cookbook)
+
+## License
+
+MIT
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Nicolò Boschi	6b3365b66a	fix: hide hf logging	2026-02-04 12:57:10 +01:00
Anton EvseevandClaude Opus 4.5	9a776e9f58	feat(openclaw): add dynamic per-channel memory banks (#290 ) Add support for per-channel memory isolation in OpenClaw plugin. Each channel (Slack, Telegram, Discord, etc.) gets its own memory bank, preventing memory leakage between channels. Changes: - Add deriveBankId() to create channel-specific bank IDs - Bank ID format: {messageProvider}-{channelId} (e.g., slack-C123) - Add getClientForContext() for context-aware client access - Update hook handlers to (event, ctx) signature - Set bank mission on first use per dynamic bank - Add dynamicBankId and bankIdPrefix config options Configuration: - dynamicBankId: true (default) enables per-channel isolation - bankIdPrefix: optional prefix for namespacing (e.g., "prod") Co-authored-by: Claude Opus 4.5 <[email protected]>	2026-02-04 11:38:14 +01:00
Anton Evseev	d02affd8f2	docs: expand external API configuration section for OpenClaw (#294 ) - Add plugin configuration example with hindsightApiUrl and hindsightApiToken - Document behavior differences when using external API mode - Add verification steps and log messages to expect - Explain use cases (shared memory, production, team environments)	2026-02-04 11:23:30 +01:00
Anton Evseev	6b346925e2	feat(openclaw): add external Hindsight API support (#289 ) Add support for connecting to an external Hindsight API instead of starting a local daemon. This enables: - Shared memory across multiple OpenClaw instances - Centralized Hindsight deployment (e.g., on GKE) - Reduced resource usage (no local daemon per instance) Configuration: - HINDSIGHT_EMBED_API_URL env var or hindsightApiUrl in plugin config - HINDSIGHT_EMBED_API_TOKEN env var or hindsightApiToken for auth When external API is configured: - Skip local daemon startup - Health check external API on startup - Pass API URL/token to CLI commands via env vars Falls back to local daemon mode when not configured.	2026-02-04 10:24:33 +01:00
Anton Evseev	63e2964a4c	fix(openclaw): improve shell argument escaping (#288 ) Add comprehensive shell argument escaping using POSIX single-quote method. Problem: - Current code only escapes single quotes inline - Other shell metacharacters ($, `, !, etc.) not explicitly handled - Document ID in retain() was not escaped Solution: - Add exported escapeShellArg() function using POSIX single-quote escaping - Replace inline escaping with shared function - Escape document ID in retain() - Add comprehensive tests (17 test cases) covering all shell-special chars The POSIX single-quote method handles ALL shell metacharacters by wrapping in single quotes (which protect everything except single quotes themselves) and escaping any embedded single quotes with '\'' sequence.	2026-02-04 10:22:52 +01:00
Nicolò Boschi	d5403a4b29	doc: update cookbook (#284 ) * fix: sync-cookbook now supports new cookbook repo layout Cookbook repository changed structure: - Applications moved from root to applications/ subdirectory - Notebooks remain in notebooks/ directory (unchanged) Updated sync script to: - Look for apps in applications/* instead of root/* - Update GitHub URLs to include applications/ path - Add safety check if applications/ dir doesn't exist * doc: update cookbook * doc: update cookbook * doc: update cookbook	2026-02-03 15:34:41 +01:00
Nicolò Boschi	a24941f83b	doc: changelog for 0.4.8 (#283 ) * doc: changelog for 0.4.8 * improve docs	2026-02-03 14:04:55 +01:00
Nicolò Boschi	21b25fe8fe	Release v0.4.8 - Update version to 0.4.8 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 - Helm chart - Sync documentation to version-0.4	2026-02-03 13:51:30 +01:00
Nicolò Boschi	794a7435a9	fix: improve embed ux with rich logging and profile isolation (#282 ) * fix: improve embed ux with rich logging and profile isolation * chore: regenerate uv.lock to fix corrupted streamlit RECORD * test: update database URL assertion for profile-specific pg0 * Revert: restore lint.sh to main branch version	2026-02-03 13:50:28 +01:00