feat: support for pgvectorscale (DiskANN)

- Remove unused `fs` and `execSync` imports from `embed-manager.ts`
- Remove unused `join` import from `index.ts`
- Add retry logic to external API health check (3 attempts, 2s delay) —
  container DNS may not be ready on first boot
- Use ES2022 `{ cause: error }` for better error chain preservation
- Add `.catch(() => {})` to `initPromise` to suppress Node.js unhandled
  rejection warnings (error is properly handled later in `service.start()`)

Co-authored-by: Claude Opus 4.6 <[email protected]>

.env.example

@@ -31,6 +31,12 @@ HINDSIGHT_API_HOST=0.0.0.0
 HINDSIGHT_API_PORT=8888
 HINDSIGHT_API_LOG_LEVEL=info
 
+# Base Path / Reverse Proxy Support (Optional)
+# Set these when deploying behind a reverse proxy with path-based routing
+# Example: To deploy at example.com/hindsight/, set both to "/hindsight"
+# HINDSIGHT_API_BASE_PATH=/hindsight
+# NEXT_PUBLIC_BASE_PATH=/hindsight
+
 # Database (Optional - uses embedded pg0 by default)
 # HINDSIGHT_API_DATABASE_URL=postgresql://user:pass@host:5432/db
 # HINDSIGHT_API_DATABASE_SCHEMA=public  # PostgreSQL schema name (default: public)
@@ -50,3 +56,18 @@ HINDSIGHT_API_LOG_LEVEL=info
 # HINDSIGHT_API_RERANKER_LOCAL_MODEL=cross-encoder/ms-marco-MiniLM-L-6-v2
 # For TEI provider:
 # HINDSIGHT_API_RERANKER_TEI_URL=http://localhost:8081
+
+# Observability & Tracing (Optional - disabled by default)
+# Enable OpenTelemetry tracing for LLM calls (GenAI semantic conventions)
+# HINDSIGHT_API_OTEL_TRACES_ENABLED=true
+#
+# Local development with Grafana LGTM stack (recommended - see scripts/dev/grafana/README.md)
+# HINDSIGHT_API_OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
+#
+# Cloud backends (Grafana Cloud, Langfuse, DataDog, etc.)
+# HINDSIGHT_API_OTEL_EXPORTER_OTLP_ENDPOINT=https://your-backend-url
+# HINDSIGHT_API_OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer your-token"
+#
+# Custom service name and environment (optional, defaults: hindsight-api, development)
+# HINDSIGHT_API_OTEL_SERVICE_NAME=hindsight-production
+# HINDSIGHT_API_OTEL_DEPLOYMENT_ENVIRONMENT=production

.github/workflows/release.yml

@@ -340,6 +340,7 @@ jobs:
         retention-days: 1
 
   release-docker-images:
+    name: Release Docker (${{ matrix.image_name }}${{ matrix.tag_suffix }})
     runs-on: ubuntu-latest
     permissions:
       contents: read
@@ -349,10 +350,28 @@ jobs:
         include:
           - target: api-only
             image_name: hindsight-api
+            tag_suffix: ""
+            build_args: ""
+          - target: api-only
+            image_name: hindsight-api
+            tag_suffix: "-slim"
+            build_args: |
+              INCLUDE_LOCAL_MODELS=false
+              PRELOAD_ML_MODELS=false
           - target: cp-only
             image_name: hindsight-control-plane
+            tag_suffix: ""
+            build_args: ""
           - target: standalone
             image_name: hindsight
+            tag_suffix: ""
+            build_args: ""
+          - target: standalone
+            image_name: hindsight
+            tag_suffix: "-slim"
+            build_args: |
+              INCLUDE_LOCAL_MODELS=false
+              PRELOAD_ML_MODELS=false
 
     steps:
     - uses: actions/checkout@v4
@@ -390,6 +409,9 @@ jobs:
       uses: docker/metadata-action@v5
       with:
         images: ghcr.io/${{ github.repository_owner }}/${{ matrix.image_name }}
+        flavor: |
+          latest=auto
+          suffix=${{ matrix.tag_suffix }}
         tags: |
           type=semver,pattern={{version}},value=${{ steps.get_version.outputs.VERSION }}
           type=semver,pattern={{major}}.{{minor}},value=${{ steps.get_version.outputs.VERSION }}
@@ -415,7 +437,7 @@ jobs:
     # - name: Smoke test - verify container starts
     #   env:
     #     GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
-    #   run: ./scripts/docker-smoke-test.sh "${{ matrix.image_name }}:test" "${{ matrix.target }}"
+    #   run: ./docker/test-image.sh "${{ matrix.image_name }}:test" "${{ matrix.target }}"
 
     # Build multi-platform and push to release tags
     - name: Build and push release images
@@ -424,6 +446,7 @@ jobs:
         context: .
         file: docker/standalone/Dockerfile
         target: ${{ matrix.target }}
+        build-args: ${{ matrix.build_args }}
         push: true
         platforms: linux/amd64,linux/arm64
         tags: ${{ steps.meta.outputs.tags }}

.github/workflows/test.yml

@@ -13,7 +13,7 @@ jobs:
     runs-on: ubuntu-latest
     strategy:
       matrix:
-        python-version: ['3.11', '3.12', '3.13']
+        python-version: ['3.11', '3.12', '3.13', '3.14']
 
     steps:
     - uses: actions/checkout@v4
@@ -277,16 +277,35 @@ jobs:
       run: helm lint helm/hindsight
 
   build-docker-images:
+    name: Build Docker (${{ matrix.name }})
     runs-on: ubuntu-latest
     strategy:
       matrix:
         include:
           - target: api-only
             name: api
+            variant: full
+            build_args: ""
+          - target: api-only
+            name: api-slim
+            variant: slim
+            build_args: |
+              INCLUDE_LOCAL_MODELS=false
+              PRELOAD_ML_MODELS=false
           - target: cp-only
             name: control-plane
+            variant: full
+            build_args: ""
           - target: standalone
             name: standalone
+            variant: full
+            build_args: ""
+          - target: standalone
+            name: standalone-slim
+            variant: slim
+            build_args: |
+              INCLUDE_LOCAL_MODELS=false
+              PRELOAD_ML_MODELS=false
 
     steps:
     - uses: actions/checkout@v4
@@ -305,20 +324,31 @@ jobs:
     - name: Set up Docker Buildx
       uses: docker/setup-buildx-action@v3
 
-    - name: Build ${{ matrix.name }} image
+    - name: Build ${{ matrix.name }} image (${{ matrix.variant }})
       uses: docker/build-push-action@v6
       with:
         context: .
         file: docker/standalone/Dockerfile
         target: ${{ matrix.target }}
+        build-args: ${{ matrix.build_args }}
         push: false
-        load: false
+        load: ${{ matrix.variant == 'slim' }}
+        tags: hindsight-${{ matrix.name }}:test
+        # Removed GitHub Actions cache (type=gha) - it frequently returns 502 errors
+        # causing buildx to fail with "failed to parse error response 502"
+        # Build will be slower but more reliable
 
-    # TODO: Re-enable smoke test when disk space issue is resolved
-    # - name: Smoke test - verify container starts
-    #   env:
-    #     GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
-    #   run: ./scripts/docker-smoke-test.sh "hindsight-${{ matrix.name }}:test" "${{ matrix.target }}"
+    # Only test slim variants to save disk space (they're much smaller)
+    # Slim variants require external embedding providers
+    - name: Smoke test - verify container starts
+      if: matrix.variant == 'slim'
+      env:
+        GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
+        HINDSIGHT_API_EMBEDDINGS_PROVIDER: openai
+        HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        HINDSIGHT_API_RERANKER_PROVIDER: cohere
+        HINDSIGHT_API_COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}
+      run: ./docker/test-image.sh "hindsight-${{ matrix.name }}:test" "${{ matrix.target }}"
 
   test-api:
     runs-on: ubuntu-latest

.gitignore

@@ -53,4 +53,6 @@ hindsight-clients/rust/target
 whats-next.md
 TASK.md
 # Changelog is now tracked in hindsight-docs/src/pages/changelog.md
-# CHANGELOG.md
+# CHANGELOG.md
+
+blog-post*

CLAUDE.md

@@ -45,6 +45,7 @@ cd hindsight-control-plane && npm run dev
 ./scripts/dev/start-docs.sh
 ```
 
+
 ### Generating Clients/OpenAPI
 ```bash
 # Regenerate OpenAPI spec after API changes (REQUIRED after changing endpoints)
@@ -237,26 +238,61 @@ def process(data: UserData) -> str:
 
 ### Adding New API Configuration Flags
 
-When adding a new environment variable configuration:
+Configuration follows a hierarchical system: **Global (env vars) → Tenant (via extension) → Bank (database)**.
+
+Fields must be categorized as either **hierarchical** (can be overridden per-tenant/bank) or **static** (server-level only).
+
+#### Adding a New Configuration Field
 
 1. **config.py** (`hindsight-api/hindsight_api/config.py`):
-   - Add `ENV_*` constant for the environment variable name
+   - Add `ENV_*` constant for the environment variable name (e.g., `ENV_MY_SETTING = "HINDSIGHT_API_MY_SETTING"`)
    - Add `DEFAULT_*` constant for the default value
-   - Add field to `HindsightConfig` dataclass
+   - Add field to `HindsightConfig` dataclass with type annotation
+   - **Mark as hierarchical or static** by adding to `_HIERARCHICAL_FIELDS` set (hierarchical) or leaving it out (static)
    - Add initialization in `from_env()` method
 
+   ```python
+   # Hierarchical field (can be overridden per-bank)
+   _HIERARCHICAL_FIELDS = {
+       ...,
+       "my_setting",  # Add here for hierarchical
+   }
+
+   # Static field - just don't add to _HIERARCHICAL_FIELDS
+   ```
+
 2. **main.py** (`hindsight-api/hindsight_api/main.py`):
    - Add field to the manual `HindsightConfig()` constructor call (search for "CLI override")
 
-3. **Use the config** in code:
+3. **Use hierarchical config in MemoryEngine**:
+   ```python
+   # Config is resolved automatically per bank via ConfigResolver
+   config_dict = await self._config_resolver.get_bank_config(bank_id, context)
+   value = config_dict["my_setting"]
+   ```
+
+4. **Use static config** (non-hierarchical):
    ```python
    from ...config import get_config
    config = get_config()
-   value = config.your_new_field
+   value = config.my_static_field
    ```
 
-4. **Documentation** (`hindsight-docs/docs/developer/configuration.md`):
+5. **Documentation** (`hindsight-docs/docs/developer/configuration.md`):
    - Add to appropriate section table with Variable, Description, Default
+   - Mark if it's hierarchical (can be overridden per-bank)
+
+#### Hierarchical vs Static Guidelines
+
+**Hierarchical** (per-bank overridable):
+- LLM settings (provider, model, API key, base URL)
+- Operation-specific settings (retain mode, chunk size, etc.)
+- Feature flags that vary by customer/bank
+
+**Static** (server-level only):
+- Infrastructure settings (database URL, port, host)
+- Global limits (max concurrent operations)
+- System-wide feature flags
 
 ## Environment Setup
 
@@ -280,3 +316,4 @@ Optional (uses local models by default):
 - `HINDSIGHT_API_EMBEDDINGS_PROVIDER`: local (default) or tei
 - `HINDSIGHT_API_RERANKER_PROVIDER`: local (default) or tei
 - `HINDSIGHT_API_DATABASE_URL`: External PostgreSQL (uses embedded pg0 by default)
+- `HINDSIGHT_API_ENABLE_BANK_CONFIG_API`: Enable per-bank config API (default: false, disabled for security)

README.md

@@ -2,7 +2,7 @@
 
 ![Hindsight Banner](./hindsight-docs/static/img/hindsight-github-banner.png)
 
-[Documentation](https://hindsight.vectorize.io) • [Paper](https://arxiv.org/abs/2512.12818) • [Cookbook](https://hindsight.vectorize.io/cookbook) • [Hindsight Cloud](https://vectorize.io/hindsight/cloud)
+[Documentation](https://hindsight.vectorize.io) • [Paper](https://arxiv.org/abs/2512.12818) • [Cookbook](https://hindsight.vectorize.io/cookbook) • [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup)
 
 [![CI](https://github.com/vectorize-io/hindsight/actions/workflows/release.yml/badge.svg)](https://github.com/vectorize-io/hindsight/actions/workflows/release.yml)
 [![Slack Community](https://img.shields.io/badge/Slack-Join%20Community-4A154B?logo=slack)](https://join.slack.com/t/hindsight-space/shared_invite/zt-3nhbm4w29-LeSJ5Ixi6j8PdiYOCPlOgg)
@@ -42,27 +42,51 @@ If you need more control over how and when your agent stores and recalls memorie
 
 ![Hindsight Banner](./hindsight-docs/static/img/migration-code.png)
 
+---
+
+> 🤖 **Using a coding agent?** Install the Hindsight documentation skill for instant access to docs while you code:
+> ```bash
+> npx skills add https://github.com/vectorize-io/hindsight --skill hindsight-docs
+> ```
+> Works with Claude Code, Cursor, and other AI coding assistants.
+
+---
+
 
 ## Quick Start
 
 ### Docker (recommended)
 
 ```bash
-export OPENAI_API_KEY=your-key
+export OPENAI_API_KEY=sk-xxx
 
 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=o3-mini \
   -v $HOME/.hindsight-docker:/home/hindsight/.pg0 \
   ghcr.io/vectorize-io/hindsight:latest
 ```
 
+>API: http://localhost:8888
+>UI: http://localhost:9999
+
 You can modify the LLM provider by setting `HINDSIGHT_API_LLM_PROVIDER`. Valid options are `openai`, `anthropic`, `gemini`, `groq`, `ollama`, and `lmstudio`. The documentation provides more details on [supported models](https://hindsight.vectorize.io/developer/models).
 
-API: http://localhost:8888  
-UI: http://localhost:9999
 
-Install client:
+
+### Docker (external PostgreSQL)
+
+```bash
+export OPENAI_API_KEY=sk-xxx
+export HINDSIGHT_DB_PASSWORD=choose-a-password
+cd docker/docker-compose
+docker compose up 
+```
+
+
+>API: http://localhost:8888
+>UI: http://localhost:9999
+
+### Client
 
 ```bash
 pip install hindsight-client -U
@@ -70,7 +94,7 @@ pip install hindsight-client -U
 npm install @vectorize-io/hindsight-client
 ```
 
-Python example:
+#### Python
 
 ```python
 from hindsight_client import Hindsight
@@ -87,7 +111,29 @@ client.recall(bank_id="my-bank", query="What does Alice do?")
 client.reflect(bank_id="my-bank", query="Tell me about Alice")
 ```
 
-### Python (embedded, no Docker)
+#### Node.js / TypeScript
+
+```bash
+npm install @vectorize-io/hindsight-client
+```
+
+```javascript
+const { HindsightClient } = require('@vectorize-io/hindsight-client');
+
+const main = async () => {
+  const client = new HindsightClient({ baseUrl: 'http://localhost:8888' });
+
+  await client.retain('my-bank', 'Alice loves hiking in Yosemite');
+
+  const results = await client.recall('my-bank', 'What does Alice like?');
+  console.log(results);
+}
+
+main();
+```
+
+
+### Python Embedded (no server required)
 
 ```bash
 pip install hindsight-all -U
@@ -107,20 +153,6 @@ with HindsightServer(
     results = client.recall(bank_id="my-bank", query="Where does Alice work?")
 ```
 
-### Node.js / TypeScript
-
-```bash
-npm install @vectorize-io/hindsight-client
-```
-
-```javascript
-const { HindsightClient } = require('@vectorize-io/hindsight-client');
-
-const client = new HindsightClient({ baseUrl: 'http://localhost:8888' });
-
-await client.retain('my-bank', 'Alice loves hiking in Yosemite');
-await client.recall('my-bank', 'What does Alice like?');
-```
 
 ---
 

docker/docker-compose/external-pg/docker-compose.yaml

@@ -0,0 +1,54 @@
+# Docker Compose file for Hindsight with PostgreSQL and pgvector
+#
+# Make sure to set the required environment variables before running:
+# - HINDSIGHT_DB_PASSWORD: Password for the PostgreSQL user
+# - Configure LLM provider variables as needed (see below in the hindsight service)
+#
+# Usage:
+# docker compose up -d
+#
+# Optional environment variables with defaults:
+# - HINDSIGHT_VERSION: Hindsight application version (default: latest)
+# - HINDSIGHT_DB_USER: PostgreSQL user (default: hindsight_user)
+# - HINDSIGHT_DB_NAME: PostgreSQL database name (default: hindsight_db)
+# - HINDSIGHT_DB_VERSION: PostgreSQL version (default: 18)
+
+services:
+  db:
+    # Use a PostgreSQL-Image with pgvector extension pre-installed
+    # see https://hub.docker.com/r/pgvector/pgvector 
+    image: pgvector/pgvector:pg${HINDSIGHT_DB_VERSION:-18}
+    container_name: hindsight-db
+    restart: always
+    # Expose PostgreSQL port
+    # ports:
+      # - "5432:5432"
+    environment:
+      POSTGRES_USER: ${HINDSIGHT_DB_USER:-hindsight_user}
+      POSTGRES_PASSWORD: ${HINDSIGHT_DB_PASSWORD:?Please set the HINDSIGHT_DB_PASSWORD env variable}
+      POSTGRES_DB: ${HINDSIGHT_DB_NAME:-hindsight_db}
+    volumes:
+      - pg_data:/var/lib/postgresql/${HINDSIGHT_DB_VERSION:-18}/docker
+    networks:
+      - hindsight-net
+
+  hindsight:
+    image: ghcr.io/vectorize-io/hindsight:${HINDSIGHT_VERSION:-latest}
+    container_name: hindsight-app
+    ports:
+      - "8888:8888"
+      - "9999:9999"
+    environment:
+      - HINDSIGHT_API_LLM_API_KEY=${OPENAI_API_KEY?Please set the OPENAI_API_KEY env variable}
+      - HINDSIGHT_API_DATABASE_URL=postgresql://${HINDSIGHT_DB_USER:-hindsight_user}:${HINDSIGHT_DB_PASSWORD:?Please set the HINDSIGHT_DB_PASSWORD env variable}@db:5432/${HINDSIGHT_DB_NAME:-hindsight_db}
+    depends_on:
+      - db
+    networks:
+      - hindsight-net
+
+networks:
+  hindsight-net:
+    driver: bridge
+
+volumes:
+  pg_data:

docker/docker-compose/nginx/README.md

@@ -0,0 +1,96 @@
+# Nginx Reverse Proxy with Custom Base Path
+
+Deploy Hindsight API under `/hindsight` (or any custom path) using Nginx reverse proxy.
+
+## Quick Start (Published Image - API Only)
+
+```bash
+docker-compose up
+```
+
+- **API:** http://localhost:8080/hindsight/docs
+- **Control Plane:** http://localhost:9999 (direct access, not proxied)
+
+## Full Stack with Custom Base Path (Requires Build)
+
+**Important:** You cannot rebuild from the published image with build args. You must build from source.
+
+### Build from Source with Custom Base Path
+
+1. **Clone the repository** (if you haven't):
+```bash
+git clone https://github.com/vectorize-io/hindsight.git
+cd hindsight
+```
+
+2. **Build with base path**:
+```bash
+docker build \
+  --build-arg NEXT_PUBLIC_BASE_PATH=/hindsight \
+  -f docker/standalone/Dockerfile \
+  -t hindsight:custom \
+  .
+```
+
+3. **Update docker-compose.yml** to use your built image:
+```yaml
+services:
+  hindsight:
+    image: hindsight:custom  # ← Change this
+    environment:
+      HINDSIGHT_API_BASE_PATH: /hindsight
+      NEXT_PUBLIC_BASE_PATH: /hindsight
+```
+
+4. **Update nginx.conf** to handle Control Plane routes (see below)
+
+5. **Run**:
+```bash
+docker-compose up
+```
+
+### Required nginx.conf for Full Stack
+
+Replace the current `nginx.conf` with this to proxy both API and Control Plane:
+
+```nginx
+events { worker_connections 1024; }
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    upstream hindsight_api { server hindsight:8888; }
+    upstream hindsight_cp { server hindsight:9999; }
+
+    server {
+        listen 80;
+
+        # API
+        location ~ ^/hindsight/(docs|openapi\.json|health|metrics|v1|mcp) {
+            proxy_pass http://hindsight_api;
+            proxy_set_header Host $http_host;
+        }
+
+        # Control Plane static files
+        location ~ ^/hindsight/_next/ {
+            proxy_pass http://hindsight_cp;
+            proxy_set_header Host $http_host;
+        }
+
+        # Control Plane UI
+        location /hindsight {
+            proxy_pass http://hindsight_cp;
+            proxy_set_header Host $http_host;
+        }
+
+        location = / { return 301 /hindsight; }
+    }
+}
+```
+
+### Why Build is Required
+
+Next.js requires `basePath` at **build time**. The published image was built without a custom base path, so you must rebuild from source with the `NEXT_PUBLIC_BASE_PATH` build arg to deploy the Control Plane under a subpath.
+
+The API works without rebuild because `HINDSIGHT_API_BASE_PATH` is a runtime environment variable.

docker/docker-compose/nginx/docker-compose.yml

@@ -0,0 +1,88 @@
+# Hindsight API deployment with Nginx reverse proxy (API-only)
+#
+# This example deploys Hindsight API under the path /hindsight with:
+# - Hindsight standalone image (API + Control Plane + embedded pg0)
+# - Nginx reverse proxy (API only)
+#
+# Quick Start:
+#   docker-compose -f docker/docker-compose/nginx/docker-compose.yml up
+#
+# Access:
+#   API (via nginx):         http://localhost:8080/hindsight/docs
+#   Control Plane (direct):  http://localhost:9999
+#
+# For full stack deployment (API + Control Plane both under /hindsight):
+#   See README.md in this directory for instructions on building with basePath.
+#
+# Note: This configuration uses the published image (no build required).
+#       Control Plane is served directly because Next.js basePath requires
+#       build-time configuration. See README.md for the full stack option.
+
+services:
+  # Hindsight (API + Control Plane + embedded pg0)
+  hindsight:
+    image: ghcr.io/vectorize-io/hindsight:latest
+    ports:
+      - "9999:9999"  # Control Plane (direct access, not proxied)
+    environment:
+      # API base path for reverse proxy
+      HINDSIGHT_API_BASE_PATH: /hindsight
+
+      # LLM configuration
+      # Using mock provider for testing (no API key needed)
+      # For production, set OPENAI_API_KEY or ANTHROPIC_API_KEY and use a real provider
+      HINDSIGHT_API_LLM_PROVIDER: ${HINDSIGHT_API_LLM_PROVIDER:-mock}
+      HINDSIGHT_API_LLM_API_KEY: ${OPENAI_API_KEY:-not-needed-for-mock}
+      HINDSIGHT_API_LLM_MODEL: ${HINDSIGHT_API_LLM_MODEL:-mock-model}
+
+      # Production examples (uncomment and set appropriate API key):
+      # HINDSIGHT_API_LLM_PROVIDER: openai
+      # HINDSIGHT_API_LLM_API_KEY: ${OPENAI_API_KEY}
+      # HINDSIGHT_API_LLM_MODEL: gpt-4o-mini
+
+      # HINDSIGHT_API_LLM_PROVIDER: anthropic
+      # HINDSIGHT_API_LLM_API_KEY: ${ANTHROPIC_API_KEY}
+      # HINDSIGHT_API_LLM_MODEL: claude-sonnet-4-20250514
+
+      # Server config
+      HINDSIGHT_API_HOST: 0.0.0.0
+      HINDSIGHT_API_PORT: 8888
+      HINDSIGHT_API_LOG_LEVEL: info
+
+      # Control Plane config
+      HINDSIGHT_CP_DATAPLANE_API_URL: http://localhost:8888
+    volumes:
+      # Persist embedded pg0 database
+      - hindsight_data:/app/data
+    # Note: Ports not exposed - access via Nginx at localhost:8080/hindsight/
+    # To debug directly, uncomment these ports:
+    # ports:
+    #   - "8888:8888"  # API
+    #   - "9999:9999"  # Control Plane
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8888/hindsight/health"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+      start_period: 30s
+    networks:
+      - hindsight
+
+  # Nginx reverse proxy
+  nginx:
+    image: nginx:alpine
+    ports:
+      - "8080:80"
+    volumes:
+      - ./nginx.conf:/etc/nginx/nginx.conf:ro
+    depends_on:
+      hindsight:
+        condition: service_healthy
+    networks:
+      - hindsight
+
+volumes:
+  hindsight_data:
+
+networks:
+  hindsight:

docker/docker-compose/nginx/nginx.conf

@@ -0,0 +1,40 @@
+# Nginx configuration for API-only reverse proxy
+# Control Plane accessed directly (not through nginx)
+
+events {
+    worker_connections 1024;
+}
+
+http {
+    include /etc/nginx/mime.types;
+    default_type application/octet-stream;
+
+    # Logging
+    access_log /var/log/nginx/access.log;
+    error_log /var/log/nginx/error.log;
+
+    # Upstream - Hindsight API
+    upstream hindsight_api {
+        server hindsight:8888;
+    }
+
+    server {
+        listen 80;
+        server_name _;
+
+        # API endpoints - forward with /hindsight prefix
+        location /hindsight/ {
+            proxy_pass http://hindsight_api;
+
+            proxy_set_header Host $http_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;
+        }
+
+        # Redirect root to API docs
+        location = / {
+            return 301 /hindsight/docs;
+        }
+    }
+}

docker/docker-compose/pg_textsearch/Dockerfile

@@ -0,0 +1,32 @@
+# PostgreSQL with pgvector and pg_textsearch extensions
+# Note: pg_textsearch requires PostgreSQL 17+
+FROM postgres:17
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    git \
+    postgresql-server-dev-17 \
+    libpq-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install pgvector
+RUN cd /tmp && \
+    git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git && \
+    cd pgvector && \
+    make && \
+    make install
+
+# Install pg_textsearch
+RUN cd /tmp && \
+    git clone https://github.com/timescale/pg_textsearch.git && \
+    cd pg_textsearch && \
+    make && \
+    make install
+
+# Clean up source files and build dependencies
+RUN rm -rf /tmp/pgvector /tmp/pg_textsearch && \
+    apt-get purge -y --auto-remove build-essential git postgresql-server-dev-17
+
+# Ensure extensions are preloaded
+RUN echo "shared_preload_libraries = 'pg_textsearch'" >> /usr/share/postgresql/postgresql.conf.sample

docker/docker-compose/pg_textsearch/docker-compose.yaml

@@ -0,0 +1,91 @@
+name: hindsight
+# Docker Compose file for Hindsight with PostgreSQL and Timescale pg_textsearch
+# docker compose -f docker/docker-compose/pg_textsearch/docker-compose.yaml down && sleep 2 && docker compose -f docker/docker-compose/pg_textsearch/docker-compose.yaml up -d
+# Make sure to set the required environment variables before running:
+# - HINDSIGHT_DB_PASSWORD: Password for the PostgreSQL user
+# - Configure LLM provider variables as needed (see below in the hindsight service)
+#
+# Usage:
+# docker compose up -d
+#
+# Optional environment variables with defaults:
+# - HINDSIGHT_VERSION: Hindsight application version (default: latest)
+# - HINDSIGHT_DB_USER: PostgreSQL user (default: hindsight_user)
+# - HINDSIGHT_DB_NAME: PostgreSQL database name (default: hindsight_db)
+
+services:
+  db:
+    # Use custom PostgreSQL image with pgvector and pg_textsearch extensions
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: hindsight-db
+    restart: always
+    # Expose PostgreSQL port
+    ports:
+      - "5437:5432"
+    environment:
+      POSTGRES_USER: ${HINDSIGHT_DB_USER:-hindsight_user}
+      POSTGRES_PASSWORD: ${HINDSIGHT_DB_PASSWORD:-hindsight_password}
+      POSTGRES_DB: ${HINDSIGHT_DB_NAME:-hindsight_db}
+    volumes:
+      - pg_data:/var/lib/postgresql/data
+    networks:
+      - hindsight-net
+
+  pg-textsearch-init:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    depends_on:
+      - db
+    environment:
+      - PGPASSWORD=${HINDSIGHT_DB_PASSWORD:-hindsight_password}
+    command: >
+      bash -c "
+        echo 'Waiting for PostgreSQL to be ready...';
+        until pg_isready -h hindsight-db -p 5432 -U hindsight_user; do
+          echo 'PostgreSQL is unavailable - sleeping';
+          sleep 2;
+        done;
+        echo 'PostgreSQL is ready - creating hindsight_db database';
+        psql -h hindsight-db -p 5432 -U hindsight_user -c 'CREATE DATABASE hindsight_db;' 2>/dev/null || echo 'Database already exists';
+        echo 'Creating extensions in hindsight_db database';
+        psql -h hindsight-db -p 5432 -U hindsight_user -d hindsight_db -c 'CREATE EXTENSION IF NOT EXISTS vector CASCADE;';
+        psql -h hindsight-db -p 5432 -U hindsight_user -d hindsight_db -c 'CREATE EXTENSION IF NOT EXISTS pg_textsearch CASCADE;';
+        echo 'Database and extensions created successfully';
+      "
+    restart: "no"
+    networks:
+      - hindsight-net
+
+  hindsight:
+    image: ghcr.io/vectorize-io/hindsight:${HINDSIGHT_VERSION:-latest}
+    container_name: hindsight-app
+    ports:
+      - "8888:8888"
+      - "9999:9999"
+    environment:
+      # LLM Configuration
+      HINDSIGHT_API_LLM_PROVIDER: ${HINDSIGHT_API_LLM_PROVIDER:-openai}
+      HINDSIGHT_API_LLM_API_KEY: ${OPENAI_API_KEY:-your-api-key}
+
+      # Database Configuration
+      HINDSIGHT_API_DATABASE_URL: postgresql://${HINDSIGHT_DB_USER:-hindsight_user}:${HINDSIGHT_DB_PASSWORD:-hindsight_password}@db:5432/${HINDSIGHT_DB_NAME:-hindsight_db}
+
+      # Vector and Text Search Extensions
+      HINDSIGHT_API_VECTOR_EXTENSION: pgvector
+      HINDSIGHT_API_TEXT_SEARCH_EXTENSION: pg_textsearch
+
+    depends_on:
+      - db
+    networks:
+      - hindsight-net
+
+
+networks:
+  hindsight-net:
+    driver: bridge
+
+volumes:
+  pg_data:

docker/docker-compose/timescale/.dockerignore

@@ -0,0 +1,16 @@
+# Git
+.git
+.gitignore
+.gitattributes
+
+# Docker
+docker-compose.yaml
+.dockerignore
+
+# Documentation
+README.md
+*.md
+
+# Environment
+.env
+.env.example

docker/docker-compose/timescale/.env.example

@@ -0,0 +1,25 @@
+# PostgreSQL Configuration
+HINDSIGHT_DB_USER=hindsight_user
+HINDSIGHT_DB_PASSWORD=change-me-to-secure-password
+HINDSIGHT_DB_NAME=hindsight_db
+
+# Hindsight Version
+HINDSIGHT_VERSION=latest
+
+# LLM Configuration
+HINDSIGHT_API_LLM_PROVIDER=openai
+OPENAI_API_KEY=your-openai-api-key-here
+
+# Alternative LLM providers (uncomment and configure as needed):
+# HINDSIGHT_API_LLM_PROVIDER=anthropic
+# ANTHROPIC_API_KEY=your-anthropic-api-key
+
+# HINDSIGHT_API_LLM_PROVIDER=gemini
+# GEMINI_API_KEY=your-gemini-api-key
+
+# HINDSIGHT_API_LLM_PROVIDER=groq
+# GROQ_API_KEY=your-groq-api-key
+
+# Vector and Text Search (already configured in docker-compose.yaml)
+# HINDSIGHT_API_VECTOR_EXTENSION=pgvectorscale
+# HINDSIGHT_API_TEXT_SEARCH_EXTENSION=pg_textsearch

docker/docker-compose/timescale/Dockerfile

@@ -0,0 +1,55 @@
+# PostgreSQL with pgvector, pgvectorscale, and pg_textsearch extensions
+# All three extensions from Timescale/pgvector for high-performance vector and text search
+# Note: Requires PostgreSQL 16+
+FROM postgres:17
+
+# Install build dependencies and Rust toolchain
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    git \
+    postgresql-server-dev-17 \
+    libpq-dev \
+    cmake \
+    curl \
+    pkg-config \
+    libssl-dev \
+    && rm -rf /var/lib/apt/lists/*
+
+# Install Rust toolchain (required for pgvectorscale)
+RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
+ENV PATH="/root/.cargo/bin:${PATH}"
+
+# Install pgvector (required by pgvectorscale)
+RUN cd /tmp && \
+    git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git && \
+    cd pgvector && \
+    make && \
+    make install && \
+    rm -rf /tmp/pgvector
+
+# Install cargo-pgrx (PostgreSQL extension framework for Rust)
+RUN cargo install cargo-pgrx --version 0.12.5 --locked && \
+    cargo pgrx init --pg17 /usr/bin/pg_config
+
+# Install pgvectorscale (DiskANN index support)
+RUN cd /tmp && \
+    git clone --branch 0.5.1 https://github.com/timescale/pgvectorscale.git && \
+    cd pgvectorscale/pgvectorscale && \
+    cargo pgrx install --release && \
+    rm -rf /tmp/pgvectorscale
+
+# Install pg_textsearch (BM25 text search)
+RUN cd /tmp && \
+    git clone https://github.com/timescale/pg_textsearch.git && \
+    cd pg_textsearch && \
+    make && \
+    make install && \
+    rm -rf /tmp/pg_textsearch
+
+# Clean up build dependencies (keep runtime dependencies)
+RUN apt-get purge -y --auto-remove git cmake curl && \
+    rm -rf /root/.cargo/registry /root/.cargo/git
+
+# Ensure extensions are preloaded (pg_textsearch requires preloading)
+RUN echo "shared_preload_libraries = 'pg_textsearch'" >> /usr/share/postgresql/postgresql.conf.sample
+

docker/docker-compose/timescale/README.md

@@ -0,0 +1,101 @@
+# Hindsight with Timescale Extensions
+
+This Docker Compose setup provides a complete Hindsight deployment with **Timescale extensions**:
+- **pgvectorscale** - DiskANN algorithm for disk-based scalable vector search  
+- **pg_textsearch** - High-performance BM25 text search
+
+Both extensions are from [Timescale](https://github.com/timescale) and provide production-grade performance.
+
+## Prerequisites
+
+- Docker and Docker Compose installed
+- OpenAI API key (or another LLM provider)
+
+## Quick Start
+
+```bash
+# Set environment variables
+export HINDSIGHT_DB_PASSWORD="your-secure-password"
+export OPENAI_API_KEY="your-openai-api-key"
+
+# Build and start
+docker compose -f docker/docker-compose/timescale/docker-compose.yaml up -d --build
+
+# Check logs
+
+docker compose -f docker/docker-compose/timescale/docker-compose.yaml logs -f
+```
+
+**Access:**
+- API: http://localhost:8888
+- Control Plane: http://localhost:9999
+
+## Stop and Clean Up
+
+```bash
+# Stop services
+docker compose -f docker/docker-compose/timescale/docker-compose.yaml down
+
+# Remove volumes (deletes all data)
+docker compose -f docker/docker-compose/timescale/docker-compose.yaml down -v
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HINDSIGHT_DB_PASSWORD` | PostgreSQL password | `hindsight_password` |
+| `HINDSIGHT_DB_USER` | PostgreSQL username | `hindsight_user` |
+| `HINDSIGHT_DB_NAME` | Database name | `hindsight_db` |
+| `HINDSIGHT_VERSION` | Hindsight Docker image version | `latest` |
+| `OPENAI_API_KEY` | OpenAI API key | (required) |
+| `HINDSIGHT_API_LLM_PROVIDER` | LLM provider | `openai` |
+
+### Why Timescale Extensions?
+
+**pgvectorscale (DiskANN):**
+- 28x lower p95 latency vs dedicated vector databases
+- 16x higher query throughput at 99% recall
+- 60-75% cost reduction (disk is cheaper than RAM)
+- Best for large datasets (10M+ vectors)
+
+**pg_textsearch (BM25):**
+- High-performance keyword retrieval
+- Native BM25 ranking algorithm
+- Optimized for full-text search
+
+## Troubleshooting
+
+### Extensions not installed
+
+Check if extensions are available:
+
+```bash
+docker exec -it hindsight-db-timescale psql -U hindsight_user -d hindsight_db -c "\dx"
+```
+
+You should see:
+- `vector` (pgvector)
+- `vectorscale` (pgvectorscale/DiskANN)
+- `pg_textsearch` (BM25 search)
+
+### Build fails
+
+If the Docker build fails during pgvectorscale compilation:
+
+1. Ensure you have sufficient memory (recommended: 4GB+)
+2. Check Docker build logs for Rust compilation errors
+3. Try building with more resources: `docker compose build --no-cache --memory 4g`
+
+### Port conflicts
+
+If port 5438 is already in use, modify the `ports` section in docker-compose.yaml.
+
+## Learn More
+
+- [pgvectorscale GitHub](https://github.com/timescale/pgvectorscale)
+- [pg_textsearch GitHub](https://github.com/timescale/pg_textsearch)
+- [HNSW vs DiskANN](https://www.tigerdata.com/learn/hnsw-vs-diskann)
+- [Hindsight Documentation](https://hindsight.dev)

docker/docker-compose/timescale/docker-compose.yaml

@@ -0,0 +1,108 @@
+name: hindsight
+# Docker Compose file for Hindsight with Timescale extensions
+# - pgvectorscale: DiskANN vector search (disk-based, scalable)
+# - pg_textsearch: BM25 text search (high-performance keyword retrieval)
+#
+# Quick start:
+# docker compose -f docker/docker-compose/timescale/docker-compose.yaml up -d --build
+#
+# Required environment variables:
+# - HINDSIGHT_DB_PASSWORD: Password for the PostgreSQL user
+# - OPENAI_API_KEY (or configure another LLM provider)
+#
+# Optional environment variables with defaults:
+# - HINDSIGHT_VERSION: Hindsight application version (default: latest)
+# - HINDSIGHT_DB_USER: PostgreSQL user (default: hindsight_user)
+# - HINDSIGHT_DB_NAME: PostgreSQL database name (default: hindsight_db)
+
+services:
+  db:
+    # Custom PostgreSQL image with Timescale extensions (pgvectorscale + pg_textsearch)
+    build:
+      context: .
+      dockerfile: Dockerfile
+    container_name: hindsight-db-timescale
+    restart: always
+    # Expose PostgreSQL port (using 5438 to avoid conflicts with other setups)
+    ports:
+      - "5438:5432"
+    environment:
+      POSTGRES_USER: ${HINDSIGHT_DB_USER:-hindsight_user}
+      POSTGRES_PASSWORD: ${HINDSIGHT_DB_PASSWORD:-hindsight_password}
+      POSTGRES_DB: ${HINDSIGHT_DB_NAME:-hindsight_db}
+    volumes:
+      - pg_data:/var/lib/postgresql/data
+    networks:
+      - hindsight-net
+    # Health check to ensure database is ready
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U hindsight_user"]
+      interval: 5s
+      timeout: 5s
+      retries: 5
+
+  timescale-init:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    depends_on:
+      db:
+        condition: service_healthy
+    environment:
+      - PGPASSWORD=${HINDSIGHT_DB_PASSWORD:-hindsight_password}
+    command: >
+      bash -c "
+        echo 'PostgreSQL is ready - creating hindsight_db database';
+        psql -h hindsight-db-timescale -p 5432 -U hindsight_user -c 'CREATE DATABASE hindsight_db;' 2>/dev/null || echo 'Database already exists';
+        echo 'Installing Timescale extensions...';
+        echo '1/3: Installing pgvector (required by pgvectorscale)...';
+        psql -h hindsight-db-timescale -p 5432 -U hindsight_user -d hindsight_db -c 'CREATE EXTENSION IF NOT EXISTS vector CASCADE;';
+        echo '2/3: Installing pgvectorscale (DiskANN vector search)...';
+        psql -h hindsight-db-timescale -p 5432 -U hindsight_user -d hindsight_db -c 'CREATE EXTENSION IF NOT EXISTS vectorscale CASCADE;';
+        echo '3/3: Installing pg_textsearch (BM25 text search)...';
+        psql -h hindsight-db-timescale -p 5432 -U hindsight_user -d hindsight_db -c 'CREATE EXTENSION IF NOT EXISTS pg_textsearch CASCADE;';
+        echo '';
+        echo '✅ Timescale extensions installed successfully';
+        echo '';
+        echo 'Installed extensions:';
+        psql -h hindsight-db-timescale -p 5432 -U hindsight_user -d hindsight_db -c \"\\dx\" | grep -E '(vector|vectorscale|pg_textsearch)';
+      "
+    restart: "no"
+    networks:
+      - hindsight-net
+
+  hindsight:
+    image: ghcr.io/vectorize-io/hindsight:${HINDSIGHT_VERSION:-latest}
+    container_name: hindsight-app-timescale
+    ports:
+      - "8888:8888"
+      - "9999:9999"
+    environment:
+      # LLM Configuration
+      HINDSIGHT_API_LLM_PROVIDER: ${HINDSIGHT_API_LLM_PROVIDER:-openai}
+      HINDSIGHT_API_LLM_API_KEY: ${OPENAI_API_KEY:-your-api-key}
+
+      # Database Configuration
+      HINDSIGHT_API_DATABASE_URL: postgresql://${HINDSIGHT_DB_USER:-hindsight_user}:${HINDSIGHT_DB_PASSWORD:-hindsight_password}@db:5432/${HINDSIGHT_DB_NAME:-hindsight_db}
+
+      # Timescale Extensions
+      # pgvectorscale: DiskANN algorithm for disk-based scalable vector search
+      HINDSIGHT_API_VECTOR_EXTENSION: pgvectorscale
+      # pg_textsearch: High-performance BM25 text search
+      HINDSIGHT_API_TEXT_SEARCH_EXTENSION: pg_textsearch
+
+    depends_on:
+      db:
+        condition: service_healthy
+      timescale-init:
+        condition: service_completed_successfully
+    networks:
+      - hindsight-net
+
+
+networks:
+  hindsight-net:
+    driver: bridge
+
+volumes:
+  pg_data:

docker/docker-compose/vchord/docker-compose.yaml

@@ -0,0 +1,93 @@
+name: hindsight
+# Docker Compose file for Hindsight with PostgreSQL and vectorchord
+# docker compose -f docker/docker-compose/docker-compose.yaml down && sleep 2 && docker compose -f docker/docker-compose/docker-compose.yaml up -d
+# Make sure to set the required environment variables before running:
+# - HINDSIGHT_DB_PASSWORD: Password for the PostgreSQL user
+# - Configure LLM provider variables as needed (see below in the hindsight service)
+#
+# Usage:
+# docker compose up -d
+#
+# Optional environment variables with defaults:
+# - HINDSIGHT_VERSION: Hindsight application version (default: latest)
+# - HINDSIGHT_DB_USER: PostgreSQL user (default: hindsight_user)
+# - HINDSIGHT_DB_NAME: PostgreSQL database name (default: hindsight_db)
+# - HINDSIGHT_DB_VERSION: PostgreSQL version (default: 18)
+
+services:
+  db:
+    # Use a PostgreSQL-Image with vectorchord extension pre-installed
+    image: tensorchord/vchord-suite:pg${HINDSIGHT_DB_VERSION:-18-latest}
+    container_name: hindsight-db
+    restart: always
+    # Expose PostgreSQL port
+    ports:
+      - "5436:5432"
+    environment:
+      POSTGRES_USER: ${HINDSIGHT_DB_USER:-hindsight_user}
+      POSTGRES_PASSWORD: ${HINDSIGHT_DB_PASSWORD:-hindsight_password}
+      POSTGRES_DB: ${HINDSIGHT_DB_NAME:-hindsight_db}
+    volumes:
+      - pg_data:/var/lib/postgresql/${HINDSIGHT_DB_VERSION:-18}/docker
+    networks:
+      - hindsight-net
+
+  vectorchord-init:
+    image: tensorchord/vchord-suite:pg18-latest
+    #container_name: vectorchord-init
+    depends_on:
+      - db
+    environment:
+      - PGPASSWORD=${HINDSIGHT_DB_PASSWORD:-hindsight_password}
+    command: >
+      bash -c "
+        echo 'Waiting for PostgreSQL to be ready...';
+        until pg_isready -h hindsight-db -p 5432 -U hindsight_user; do
+          echo 'PostgreSQL is unavailable - sleeping';
+          sleep 2;
+        done;
+        echo 'PostgreSQL is ready - creating hindsight_db database';
+        psql -h hindsight-db -p 5432 -U hindsight_user -c 'CREATE DATABASE hindsight_db;' 2>/dev/null || echo 'Database already exists';
+        echo 'Creating extensions in hindsight_db database';
+        psql -h hindsight-db -p 5432 -U hindsight_user -d hindsight_db -c 'CREATE EXTENSION IF NOT EXISTS vchord CASCADE;';
+        psql -h hindsight-db -p 5432 -U hindsight_user -d hindsight_db -c 'CREATE EXTENSION IF NOT EXISTS pg_tokenizer CASCADE;';
+        psql -h hindsight-db -p 5432 -U hindsight_user -d hindsight_db -c 'CREATE EXTENSION IF NOT EXISTS vchord_bm25 CASCADE;';
+        echo 'Creating llmlingua2 tokenizer';
+        psql -h hindsight-db -p 5432 -U hindsight_user -d hindsight_db -c \"SELECT create_tokenizer('llmlingua2', \\$\\$ model = \\\"llmlingua2\\\" \\$\\$);\" 2>/dev/null || echo 'Tokenizer already exists or creation skipped';
+        echo 'Database and extensions created successfully';
+      "
+    restart: "no"
+    networks:
+      - hindsight-net
+
+  hindsight:
+    image: ghcr.io/vectorize-io/hindsight:${HINDSIGHT_VERSION:-latest}
+    container_name: hindsight-app
+    ports:
+      - "8888:8888"
+      - "9999:9999"
+    environment:
+      # LLM Configuration (uses OpenAI for testing vchord)
+      # LLM configuration
+      HINDSIGHT_API_LLM_PROVIDER: ${HINDSIGHT_API_LLM_PROVIDER:-openai}
+      HINDSIGHT_API_LLM_API_KEY: ${OPENAI_API_KEY:-your-api-key}
+
+      # Database Configuration
+      HINDSIGHT_API_DATABASE_URL: postgresql://${HINDSIGHT_DB_USER:-hindsight_user}:${HINDSIGHT_DB_PASSWORD:-hindsight_password}@db:5432/${HINDSIGHT_DB_NAME:-hindsight_db}
+
+      # Vector and Text Search Extensions
+      HINDSIGHT_API_VECTOR_EXTENSION: vchord
+      HINDSIGHT_API_TEXT_SEARCH_EXTENSION: vchord
+
+    depends_on:
+      - db
+    networks:
+      - hindsight-net
+
+
+networks:
+  hindsight-net:
+    driver: bridge
+
+volumes:
+  pg_data:

docker/standalone/Dockerfile

@@ -8,6 +8,7 @@
 #                                     Set to false when using external providers (TEI, OpenAI, Cohere)
 #   PRELOAD_ML_MODELS=true/false   - Pre-download ML models during build (default: true)
 #                                     Only effective when INCLUDE_LOCAL_MODELS=true
+#                                     NOTE: tiktoken encodings are ALWAYS preloaded (required for air-gapped deployments)
 #
 # Examples:
 #   docker build -t hindsight .                                          # Both (standalone)
@@ -111,6 +112,10 @@ RUN rm -f package-lock.json && sed -i '/"@vectorize-io\/hindsight-client":/d' pa
 # Copy built SDK directly into node_modules (more reliable than npm link in Docker)
 COPY --from=sdk-builder /app/hindsight-clients/typescript ./node_modules/@vectorize-io/hindsight-client
 
+# Accept base path as build argument for reverse proxy deployments
+# Usage: docker build --build-arg NEXT_PUBLIC_BASE_PATH=/hindsight ...
+ARG NEXT_PUBLIC_BASE_PATH=""
+
 # Build Control Plane - run next build first, then custom standalone copy
 # (The build:standalone script expects a specific path structure that differs in Docker)
 RUN npm exec -- next build
@@ -167,6 +172,28 @@ USER hindsight
 
 ENV PATH="/app/api/.venv/bin:${PATH}"
 
+# Pre-download tiktoken encoding (ALWAYS - required for token counting even in air-gapped envs)
+# Tiktoken is a core runtime dependency, not an optional ML model
+RUN MAX_RETRIES=3; \
+    RETRY_DELAY=5; \
+    for i in $(seq 1 $MAX_RETRIES); do \
+      echo "Attempt $i/$MAX_RETRIES: Downloading tiktoken encoding..."; \
+      /app/api/.venv/bin/python -c "\
+import tiktoken; \
+print('Downloading cl100k_base encoding...'); \
+tiktoken.get_encoding('cl100k_base'); \
+print('Tiktoken encoding cached successfully')" && break; \
+      if [ $i -lt $MAX_RETRIES ]; then \
+        echo "Attempt $i failed, retrying in ${RETRY_DELAY}s..."; \
+        sleep $RETRY_DELAY; \
+        RETRY_DELAY=$((RETRY_DELAY * 2)); \
+      fi; \
+    done; \
+    if [ $i -eq $MAX_RETRIES ]; then \
+      echo "ERROR: Failed to download tiktoken encoding after $MAX_RETRIES attempts"; \
+      exit 1; \
+    fi
+
 # Pre-download ML models to avoid runtime download (conditional)
 # Only runs if both PRELOAD_ML_MODELS=true AND INCLUDE_LOCAL_MODELS=true
 # Includes retry logic with exponential backoff for transient network failures
@@ -185,7 +212,6 @@ print('Downloading embedding model...'); \
 SentenceTransformer('BAAI/bge-small-en-v1.5'); \
 print('Downloading cross-encoder model...'); \
 CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2'); \
-print('Downloading tiktoken encoding...'); import tiktoken; tiktoken.get_encoding('cl100k_base'); \
 print('Models cached successfully')" && break; \
       if [ $i -lt $MAX_RETRIES ]; then \
         echo "Attempt $i failed, retrying in ${RETRY_DELAY}s..."; \
@@ -297,6 +323,28 @@ USER hindsight
 
 ENV PATH="/app/api/.venv/bin:${PATH}"
 
+# Pre-download tiktoken encoding (ALWAYS - required for token counting even in air-gapped envs)
+# Tiktoken is a core runtime dependency, not an optional ML model
+RUN MAX_RETRIES=3; \
+    RETRY_DELAY=5; \
+    for i in $(seq 1 $MAX_RETRIES); do \
+      echo "Attempt $i/$MAX_RETRIES: Downloading tiktoken encoding..."; \
+      /app/api/.venv/bin/python -c "\
+import tiktoken; \
+print('Downloading cl100k_base encoding...'); \
+tiktoken.get_encoding('cl100k_base'); \
+print('Tiktoken encoding cached successfully')" && break; \
+      if [ $i -lt $MAX_RETRIES ]; then \
+        echo "Attempt $i failed, retrying in ${RETRY_DELAY}s..."; \
+        sleep $RETRY_DELAY; \
+        RETRY_DELAY=$((RETRY_DELAY * 2)); \
+      fi; \
+    done; \
+    if [ $i -eq $MAX_RETRIES ]; then \
+      echo "ERROR: Failed to download tiktoken encoding after $MAX_RETRIES attempts"; \
+      exit 1; \
+    fi
+
 # Pre-download ML models to avoid runtime download (conditional)
 # Only runs if both PRELOAD_ML_MODELS=true AND INCLUDE_LOCAL_MODELS=true
 # Includes retry logic with exponential backoff for transient network failures
@@ -315,7 +363,6 @@ print('Downloading embedding model...'); \
 SentenceTransformer('BAAI/bge-small-en-v1.5'); \
 print('Downloading cross-encoder model...'); \
 CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2'); \
-print('Downloading tiktoken encoding...'); import tiktoken; tiktoken.get_encoding('cl100k_base'); \
 print('Models cached successfully')" && break; \
       if [ $i -lt $MAX_RETRIES ]; then \
         echo "Attempt $i failed, retrying in ${RETRY_DELAY}s..."; \

docker/test-image.sh

@@ -6,28 +6,40 @@
 # Can be run locally or in CI pipelines.
 #
 # Usage:
-#   ./scripts/docker-smoke-test.sh <image> [target]
+#   ./docker/test-image.sh <image> [target]
 #
 # Arguments:
 #   image   - Docker image to test (e.g., hindsight-api:test, ghcr.io/vectorize-io/hindsight:latest)
 #   target  - Optional: 'cp-only' for control plane, otherwise assumes API image (default: api)
 #
 # Environment variables:
-#   GROQ_API_KEY              - Required for API/standalone images (LLM verification)
-#   HINDSIGHT_API_LLM_PROVIDER - LLM provider (default: groq)
-#   HINDSIGHT_API_LLM_MODEL    - LLM model (default: llama-3.3-70b-versatile)
-#   SMOKE_TEST_TIMEOUT        - Timeout in seconds (default: 120)
-#   SMOKE_TEST_CONTAINER_NAME - Container name (default: hindsight-smoke-test)
+#   GROQ_API_KEY                                - Required for API/standalone images (LLM verification)
+#   HINDSIGHT_API_LLM_PROVIDER                  - LLM provider (default: groq)
+#   HINDSIGHT_API_LLM_MODEL                     - LLM model (default: llama-3.3-70b-versatile)
+#   HINDSIGHT_API_EMBEDDINGS_PROVIDER           - Embeddings provider (optional, for slim images: openai, cohere, tei)
+#   HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY     - OpenAI API key for embeddings (optional)
+#   HINDSIGHT_API_RERANKER_PROVIDER             - Reranker provider (optional, for slim images: cohere, tei)
+#   HINDSIGHT_API_COHERE_API_KEY                - Cohere API key for reranking (optional)
+#   SMOKE_TEST_TIMEOUT                          - Timeout in seconds (default: 120)
+#   SMOKE_TEST_CONTAINER_NAME                   - Container name (default: hindsight-smoke-test)
 #
 # Examples:
-#   # Test a locally built image
-#   ./scripts/docker-smoke-test.sh hindsight-api:test
+#   # Test a locally built full image
+#   ./docker/test-image.sh hindsight-api:test
 #
 #   # Test a released image
-#   ./scripts/docker-smoke-test.sh ghcr.io/vectorize-io/hindsight:latest
+#   ./docker/test-image.sh ghcr.io/vectorize-io/hindsight:latest
 #
 #   # Test control plane image
-#   ./scripts/docker-smoke-test.sh hindsight-control-plane:test cp-only
+#   ./docker/test-image.sh hindsight-control-plane:test cp-only
+#
+#   # Test slim image with external providers
+#   export GROQ_API_KEY=gsk_xxx
+#   export HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai
+#   export HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY=sk-xxx
+#   export HINDSIGHT_API_RERANKER_PROVIDER=cohere
+#   export HINDSIGHT_API_COHERE_API_KEY=xxx
+#   ./docker/test-image.sh hindsight-slim:test
 #
 # Exit codes:
 #   0 - Success (container healthy)
@@ -108,12 +120,32 @@ if [ "$TARGET" = "cp-only" ]; then
         -p "${HEALTH_PORT}:${HEALTH_PORT}" \
         "$IMAGE"
 else
-    docker run -d --name "$CONTAINER_NAME" \
-        -e HINDSIGHT_API_LLM_PROVIDER="$LLM_PROVIDER" \
-        -e HINDSIGHT_API_LLM_API_KEY="${GROQ_API_KEY}" \
-        -e HINDSIGHT_API_LLM_MODEL="$LLM_MODEL" \
-        -p "${HEALTH_PORT}:${HEALTH_PORT}" \
-        "$IMAGE"
+    # Build docker run command with required and optional env vars
+    DOCKER_CMD="docker run -d --name $CONTAINER_NAME"
+    DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_LLM_PROVIDER=$LLM_PROVIDER"
+    DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_LLM_API_KEY=${GROQ_API_KEY}"
+    DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_LLM_MODEL=$LLM_MODEL"
+
+    # Add optional embeddings provider config
+    if [ -n "${HINDSIGHT_API_EMBEDDINGS_PROVIDER:-}" ]; then
+        DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_EMBEDDINGS_PROVIDER=${HINDSIGHT_API_EMBEDDINGS_PROVIDER}"
+    fi
+    if [ -n "${HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY:-}" ]; then
+        DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY=${HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY}"
+    fi
+
+    # Add optional reranker provider config
+    if [ -n "${HINDSIGHT_API_RERANKER_PROVIDER:-}" ]; then
+        DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_RERANKER_PROVIDER=${HINDSIGHT_API_RERANKER_PROVIDER}"
+    fi
+    if [ -n "${HINDSIGHT_API_COHERE_API_KEY:-}" ]; then
+        DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_COHERE_API_KEY=${HINDSIGHT_API_COHERE_API_KEY}"
+    fi
+
+    DOCKER_CMD="$DOCKER_CMD -p ${HEALTH_PORT}:${HEALTH_PORT}"
+    DOCKER_CMD="$DOCKER_CMD $IMAGE"
+
+    eval $DOCKER_CMD
 fi
 
 # Wait for health endpoint

docker/test-slim-local.sh

@@ -0,0 +1,51 @@
+#!/bin/bash
+#
+# Local Test Script for Slim Docker Images
+#
+# This script makes it easy to test slim images locally with external providers.
+# It expects API keys to be set in environment variables.
+#
+# Usage:
+#   export GROQ_API_KEY=gsk_xxx
+#   export OPENAI_API_KEY=sk-xxx
+#   export COHERE_API_KEY=xxx
+#   ./docker/test-slim-local.sh
+#
+# Or inline:
+#   GROQ_API_KEY=gsk_xxx OPENAI_API_KEY=sk_xxx COHERE_API_KEY=xxx ./docker/test-slim-local.sh
+#
+
+set -euo pipefail
+
+# Check for required API keys
+if [ -z "${GROQ_API_KEY:-}" ]; then
+    echo "❌ Error: GROQ_API_KEY environment variable is required"
+    echo "Set it with: export GROQ_API_KEY=gsk_xxx"
+    exit 1
+fi
+
+if [ -z "${OPENAI_API_KEY:-}" ]; then
+    echo "❌ Error: OPENAI_API_KEY environment variable is required"
+    echo "Set it with: export OPENAI_API_KEY=sk-xxx"
+    exit 1
+fi
+
+if [ -z "${COHERE_API_KEY:-}" ]; then
+    echo "❌ Error: COHERE_API_KEY environment variable is required"
+    echo "Set it with: export COHERE_API_KEY=xxx"
+    exit 1
+fi
+
+# Configuration
+IMAGE="${1:-hindsight-slim:test}"
+echo "Testing image: $IMAGE"
+echo ""
+
+# Set up external providers
+export HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai
+export HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY=$OPENAI_API_KEY
+export HINDSIGHT_API_RERANKER_PROVIDER=cohere
+export HINDSIGHT_API_COHERE_API_KEY=$COHERE_API_KEY
+
+# Run the test
+exec "$(dirname "$0")/test-image.sh" "$IMAGE" standalone

helm/hindsight/Chart.yaml

@@ -2,8 +2,8 @@ apiVersion: v2
 name: hindsight
 description: Hindsight helm chart
 type: application
-version: 0.4.9
-appVersion: "0.4.9"
+version: 0.4.11
+appVersion: "0.4.11"
 keywords:
   - ai
   - memory

helm/hindsight/templates/_helpers.tpl

@@ -127,6 +127,38 @@ API URL for control plane
 {{- printf "http://%s-api:%d" (include "hindsight.fullname" .) (.Values.api.service.port | int) }}
 {{- end }}
 
+{{/*
+TEI reranker labels
+*/}}
+{{- define "hindsight.tei.reranker.labels" -}}
+{{ include "hindsight.labels" . }}
+app.kubernetes.io/component: tei-reranker
+{{- end }}
+
+{{/*
+TEI reranker selector labels
+*/}}
+{{- define "hindsight.tei.reranker.selectorLabels" -}}
+{{ include "hindsight.selectorLabels" . }}
+app.kubernetes.io/component: tei-reranker
+{{- end }}
+
+{{/*
+TEI embedding labels
+*/}}
+{{- define "hindsight.tei.embedding.labels" -}}
+{{ include "hindsight.labels" . }}
+app.kubernetes.io/component: tei-embedding
+{{- end }}
+
+{{/*
+TEI embedding selector labels
+*/}}
+{{- define "hindsight.tei.embedding.selectorLabels" -}}
+{{ include "hindsight.selectorLabels" . }}
+app.kubernetes.io/component: tei-embedding
+{{- end }}
+
 {{/*
 Get the name of the secret to use
 */}}

helm/hindsight/templates/api-deployment.yaml

@@ -33,7 +33,7 @@ spec:
       - name: api
         securityContext:
           {{- toYaml .Values.securityContext | nindent 10 }}
-        image: "{{ .Values.api.image.repository }}:{{ .Values.api.image.tag | default .Values.version }}"
+        image: "{{ .Values.api.image.repository }}:{{ .Values.api.image.tag | default .Values.version | default .Chart.AppVersion }}"
         imagePullPolicy: {{ .Values.api.image.pullPolicy }}
         ports:
         - name: http
@@ -60,10 +60,25 @@ spec:
         - name: HINDSIGHT_API_WORKER_ENABLED
           value: "false"
         {{- end }}
+        {{- /* Explicitly set port to override K8s service discovery env var (HINDSIGHT_API_PORT) */}}
+        - name: HINDSIGHT_API_PORT
+          value: {{ .Values.api.service.targetPort | quote }}
         {{- range $key, $value := .Values.api.env }}
         - name: {{ $key }}
           value: {{ $value | quote }}
         {{- end }}
+        {{- if .Values.tei.reranker.enabled }}
+        - name: HINDSIGHT_API_RERANKER_PROVIDER
+          value: "tei"
+        - name: HINDSIGHT_API_RERANKER_TEI_URL
+          value: "http://{{ include "hindsight.fullname" . }}-tei-reranker:{{ .Values.tei.reranker.port }}"
+        {{- end }}
+        {{- if .Values.tei.embedding.enabled }}
+        - name: HINDSIGHT_API_EMBEDDINGS_PROVIDER
+          value: "tei"
+        - name: HINDSIGHT_API_EMBEDDINGS_TEI_URL
+          value: "http://{{ include "hindsight.fullname" . }}-tei-embedding:{{ .Values.tei.embedding.port }}"
+        {{- end }}
         {{- /* Only use api.secrets when not using existingSecret (for chart-managed secrets) */}}
         {{- if not .Values.existingSecret }}
         {{- range $key, $value := .Values.api.secrets }}
@@ -84,7 +99,7 @@ spec:
       nodeSelector:
         {{- toYaml . | nindent 8 }}
       {{- end }}
-      {{- with .Values.affinity }}
+      {{- with (.Values.api.affinity | default .Values.affinity) }}
       affinity:
         {{- toYaml . | nindent 8 }}
       {{- end }}

helm/hindsight/templates/controlplane-deployment.yaml

@@ -33,7 +33,7 @@ spec:
       - name: control-plane
         securityContext:
           {{- toYaml .Values.securityContext | nindent 10 }}
-        image: "{{ .Values.controlPlane.image.repository }}:{{ .Values.controlPlane.image.tag | default .Values.version }}"
+        image: "{{ .Values.controlPlane.image.repository }}:{{ .Values.controlPlane.image.tag | default .Values.version | default .Chart.AppVersion }}"
         imagePullPolicy: {{ .Values.controlPlane.image.pullPolicy }}
         ports:
         - name: http
@@ -71,7 +71,7 @@ spec:
       nodeSelector:
         {{- toYaml . | nindent 8 }}
       {{- end }}
-      {{- with .Values.affinity }}
+      {{- with (.Values.controlPlane.affinity | default .Values.affinity) }}
       affinity:
         {{- toYaml . | nindent 8 }}
       {{- end }}

helm/hindsight/templates/pdb.yaml

@@ -0,0 +1,56 @@
+{{- if and .Values.api.enabled .Values.api.podDisruptionBudget.enabled }}
+apiVersion: policy/v1
+kind: PodDisruptionBudget
+metadata:
+  name: {{ include "hindsight.fullname" . }}-api
+  labels:
+    {{- include "hindsight.api.labels" . | nindent 4 }}
+spec:
+  {{- if .Values.api.podDisruptionBudget.minAvailable }}
+  minAvailable: {{ .Values.api.podDisruptionBudget.minAvailable }}
+  {{- end }}
+  {{- if .Values.api.podDisruptionBudget.maxUnavailable }}
+  maxUnavailable: {{ .Values.api.podDisruptionBudget.maxUnavailable }}
+  {{- end }}
+  selector:
+    matchLabels:
+      {{- include "hindsight.api.selectorLabels" . | nindent 6 }}
+{{- end }}
+---
+{{- if and .Values.controlPlane.enabled .Values.controlPlane.podDisruptionBudget.enabled }}
+apiVersion: policy/v1
+kind: PodDisruptionBudget
+metadata:
+  name: {{ include "hindsight.fullname" . }}-control-plane
+  labels:
+    {{- include "hindsight.controlPlane.labels" . | nindent 4 }}
+spec:
+  {{- if .Values.controlPlane.podDisruptionBudget.minAvailable }}
+  minAvailable: {{ .Values.controlPlane.podDisruptionBudget.minAvailable }}
+  {{- end }}
+  {{- if .Values.controlPlane.podDisruptionBudget.maxUnavailable }}
+  maxUnavailable: {{ .Values.controlPlane.podDisruptionBudget.maxUnavailable }}
+  {{- end }}
+  selector:
+    matchLabels:
+      {{- include "hindsight.controlPlane.selectorLabels" . | nindent 6 }}
+{{- end }}
+---
+{{- if and .Values.worker.enabled .Values.worker.podDisruptionBudget.enabled }}
+apiVersion: policy/v1
+kind: PodDisruptionBudget
+metadata:
+  name: {{ include "hindsight.fullname" . }}-worker
+  labels:
+    {{- include "hindsight.worker.labels" . | nindent 4 }}
+spec:
+  {{- if .Values.worker.podDisruptionBudget.minAvailable }}
+  minAvailable: {{ .Values.worker.podDisruptionBudget.minAvailable }}
+  {{- end }}
+  {{- if .Values.worker.podDisruptionBudget.maxUnavailable }}
+  maxUnavailable: {{ .Values.worker.podDisruptionBudget.maxUnavailable }}
+  {{- end }}
+  selector:
+    matchLabels:
+      {{- include "hindsight.worker.selectorLabels" . | nindent 6 }}
+{{- end }}

helm/hindsight/templates/tei-embedding-deployment.yaml

@@ -0,0 +1,76 @@
+{{- if .Values.tei.embedding.enabled }}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "hindsight.fullname" . }}-tei-embedding
+  labels:
+    {{- include "hindsight.tei.embedding.labels" . | nindent 4 }}
+spec:
+  replicas: {{ .Values.tei.embedding.replicaCount }}
+  selector:
+    matchLabels:
+      {{- include "hindsight.tei.embedding.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      {{- with .Values.podAnnotations }}
+      annotations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      labels:
+        {{- include "hindsight.tei.embedding.selectorLabels" . | nindent 8 }}
+    spec:
+      {{- if .Values.serviceAccount.create }}
+      serviceAccountName: {{ include "hindsight.serviceAccountName" . }}
+      {{- end }}
+      securityContext:
+        {{- toYaml .Values.podSecurityContext | nindent 8 }}
+      containers:
+      - name: tei-embedding
+        securityContext:
+          {{- toYaml .Values.securityContext | nindent 10 }}
+        image: "{{ .Values.tei.embedding.image.repository }}:{{ .Values.tei.embedding.image.tag }}"
+        imagePullPolicy: {{ .Values.tei.embedding.image.pullPolicy }}
+        args:
+          - "--model-id"
+          - {{ .Values.tei.embedding.model | quote }}
+          - "--hostname"
+          - "0.0.0.0"
+          {{- range .Values.tei.embedding.args }}
+          - {{ . | quote }}
+          {{- end }}
+        ports:
+        - name: http
+          containerPort: {{ .Values.tei.embedding.port }}
+          protocol: TCP
+        env:
+        - name: PORT
+          value: {{ .Values.tei.embedding.port | quote }}
+        {{- range $key, $value := .Values.tei.embedding.env }}
+        - name: {{ $key }}
+          value: {{ $value | quote }}
+        {{- end }}
+        livenessProbe:
+          {{- toYaml .Values.tei.embedding.livenessProbe | nindent 10 }}
+        readinessProbe:
+          {{- toYaml .Values.tei.embedding.readinessProbe | nindent 10 }}
+        resources:
+          {{- toYaml .Values.tei.embedding.resources | nindent 10 }}
+        volumeMounts:
+        - name: model-cache
+          mountPath: /data
+      volumes:
+      - name: model-cache
+        emptyDir: {}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+{{- end }}

helm/hindsight/templates/tei-embedding-service.yaml

@@ -0,0 +1,17 @@
+{{- if .Values.tei.embedding.enabled }}
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "hindsight.fullname" . }}-tei-embedding
+  labels:
+    {{- include "hindsight.tei.embedding.labels" . | nindent 4 }}
+spec:
+  type: ClusterIP
+  ports:
+  - port: {{ .Values.tei.embedding.port }}
+    targetPort: http
+    protocol: TCP
+    name: http
+  selector:
+    {{- include "hindsight.tei.embedding.selectorLabels" . | nindent 4 }}
+{{- end }}

helm/hindsight/templates/tei-reranker-deployment.yaml

@@ -0,0 +1,76 @@
+{{- if .Values.tei.reranker.enabled }}
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "hindsight.fullname" . }}-tei-reranker
+  labels:
+    {{- include "hindsight.tei.reranker.labels" . | nindent 4 }}
+spec:
+  replicas: {{ .Values.tei.reranker.replicaCount }}
+  selector:
+    matchLabels:
+      {{- include "hindsight.tei.reranker.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      {{- with .Values.podAnnotations }}
+      annotations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      labels:
+        {{- include "hindsight.tei.reranker.selectorLabels" . | nindent 8 }}
+    spec:
+      {{- if .Values.serviceAccount.create }}
+      serviceAccountName: {{ include "hindsight.serviceAccountName" . }}
+      {{- end }}
+      securityContext:
+        {{- toYaml .Values.podSecurityContext | nindent 8 }}
+      containers:
+      - name: tei-reranker
+        securityContext:
+          {{- toYaml .Values.securityContext | nindent 10 }}
+        image: "{{ .Values.tei.reranker.image.repository }}:{{ .Values.tei.reranker.image.tag }}"
+        imagePullPolicy: {{ .Values.tei.reranker.image.pullPolicy }}
+        args:
+          - "--model-id"
+          - {{ .Values.tei.reranker.model | quote }}
+          - "--hostname"
+          - "0.0.0.0"
+          {{- range .Values.tei.reranker.args }}
+          - {{ . | quote }}
+          {{- end }}
+        ports:
+        - name: http
+          containerPort: {{ .Values.tei.reranker.port }}
+          protocol: TCP
+        env:
+        - name: PORT
+          value: {{ .Values.tei.reranker.port | quote }}
+        {{- range $key, $value := .Values.tei.reranker.env }}
+        - name: {{ $key }}
+          value: {{ $value | quote }}
+        {{- end }}
+        livenessProbe:
+          {{- toYaml .Values.tei.reranker.livenessProbe | nindent 10 }}
+        readinessProbe:
+          {{- toYaml .Values.tei.reranker.readinessProbe | nindent 10 }}
+        resources:
+          {{- toYaml .Values.tei.reranker.resources | nindent 10 }}
+        volumeMounts:
+        - name: model-cache
+          mountPath: /data
+      volumes:
+      - name: model-cache
+        emptyDir: {}
+      {{- with .Values.nodeSelector }}
+      nodeSelector:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.affinity }}
+      affinity:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+      {{- with .Values.tolerations }}
+      tolerations:
+        {{- toYaml . | nindent 8 }}
+      {{- end }}
+{{- end }}

helm/hindsight/templates/tei-reranker-service.yaml

@@ -0,0 +1,17 @@
+{{- if .Values.tei.reranker.enabled }}
+apiVersion: v1
+kind: Service
+metadata:
+  name: {{ include "hindsight.fullname" . }}-tei-reranker
+  labels:
+    {{- include "hindsight.tei.reranker.labels" . | nindent 4 }}
+spec:
+  type: ClusterIP
+  ports:
+  - port: {{ .Values.tei.reranker.port }}
+    targetPort: http
+    protocol: TCP
+    name: http
+  selector:
+    {{- include "hindsight.tei.reranker.selectorLabels" . | nindent 4 }}
+{{- end }}

helm/hindsight/templates/worker-statefulset.yaml

@@ -32,7 +32,7 @@ spec:
       - name: worker
         securityContext:
           {{- toYaml .Values.securityContext | nindent 10 }}
-        image: "{{ .Values.worker.image.repository }}:{{ .Values.worker.image.tag | default .Values.version }}"
+        image: "{{ .Values.worker.image.repository }}:{{ .Values.worker.image.tag | default .Values.version | default .Chart.AppVersion }}"
         imagePullPolicy: {{ .Values.worker.image.pullPolicy }}
         command: ["hindsight-worker"]
         ports:
@@ -99,7 +99,7 @@ spec:
       nodeSelector:
         {{- toYaml . | nindent 8 }}
       {{- end }}
-      {{- with .Values.affinity }}
+      {{- with (.Values.worker.affinity | default .Values.affinity) }}
       affinity:
         {{- toYaml . | nindent 8 }}
       {{- end }}

helm/hindsight/values.yaml

@@ -1,7 +1,8 @@
 # Default values for hindsight
 
-# Chart version - use this to set a consistent image tag across all components
-version: "0.1.1"
+# Global version override - use this to set a consistent image tag across all components
+# If not set, defaults to Chart.appVersion from Chart.yaml
+# version: ""
 
 # Use an existing secret instead of creating one from values
 # When set, all keys from this secret are injected as environment variables via envFrom
@@ -57,6 +58,15 @@ api:
     timeoutSeconds: 3
     failureThreshold: 3
 
+  # Pod disruption budget
+  podDisruptionBudget:
+    enabled: false
+    minAvailable: 1
+    # maxUnavailable: 1
+
+  # Pod affinity/anti-affinity (overrides global affinity for this component)
+  # affinity: {}
+
   # Environment variables
   env:
     #HINDSIGHT_API_LLM_PROVIDER: "groq"
@@ -75,7 +85,7 @@ worker:
   image:
     repository: ghcr.io/vectorize-io/hindsight-api
     pullPolicy: IfNotPresent
-    # tag defaults to .Values.version if not specified
+    # tag: ""  # defaults to .Values.version, then Chart.appVersion if not specified
 
   service:
     # Service for metrics scraping (headless for StatefulSet)
@@ -121,6 +131,15 @@ worker:
     # HTTP port for metrics/health (matches service.targetPort)
     HINDSIGHT_API_WORKER_HTTP_PORT: "8889"
 
+  # Pod disruption budget
+  podDisruptionBudget:
+    enabled: false
+    minAvailable: 1
+    # maxUnavailable: 1
+
+  # Pod affinity/anti-affinity (overrides global affinity for this component)
+  # affinity: {}
+
   # Secret environment variables (inherited from api.secrets if not specified)
   secrets: {}
 
@@ -164,6 +183,15 @@ controlPlane:
     timeoutSeconds: 3
     failureThreshold: 3
 
+  # Pod disruption budget
+  podDisruptionBudget:
+    enabled: false
+    minAvailable: 1
+    # maxUnavailable: 1
+
+  # Pod affinity/anti-affinity (overrides global affinity for this component)
+  # affinity: {}
+
   # Environment variables
   env:
     NODE_ENV: "production"
@@ -262,9 +290,87 @@ nodeSelector: {}
 # Tolerations
 tolerations: []
 
-# Affinity
+# Affinity (applied to all components unless overridden per-component)
 affinity: {}
 
+# TEI (Text Embeddings Inference) - optional standalone deployments
+# for reranking and/or embedding models
+tei:
+  reranker:
+    enabled: false
+    replicaCount: 1
+    image:
+      repository: ghcr.io/huggingface/text-embeddings-inference
+      tag: cpu-1.8.3
+      pullPolicy: IfNotPresent
+    model: "cross-encoder/ms-marco-MiniLM-L-6-v2"
+    port: 8090
+    args:
+      - "--auto-truncate"
+    env:
+      PAYLOAD_LIMIT: "10000000"
+      MAX_CLIENT_BATCH_SIZE: "256"
+    resources:
+      limits:
+        cpu: 2000m
+        memory: 2Gi
+      requests:
+        cpu: 500m
+        memory: 1Gi
+    livenessProbe:
+      httpGet:
+        path: /health
+        port: 8090
+      initialDelaySeconds: 30
+      periodSeconds: 10
+      timeoutSeconds: 5
+      failureThreshold: 6
+    readinessProbe:
+      httpGet:
+        path: /health
+        port: 8090
+      initialDelaySeconds: 15
+      periodSeconds: 5
+      timeoutSeconds: 3
+      failureThreshold: 3
+
+  embedding:
+    enabled: false
+    replicaCount: 1
+    image:
+      repository: ghcr.io/huggingface/text-embeddings-inference
+      tag: cpu-1.8.3
+      pullPolicy: IfNotPresent
+    model: "sentence-transformers/all-MiniLM-L6-v2"
+    port: 8091
+    args: []
+    env:
+      PAYLOAD_LIMIT: "10000000"
+      MAX_CLIENT_BATCH_SIZE: "256"
+    resources:
+      limits:
+        cpu: 2000m
+        memory: 2Gi
+      requests:
+        cpu: 500m
+        memory: 1Gi
+    livenessProbe:
+      httpGet:
+        path: /health
+        port: 8091
+      initialDelaySeconds: 30
+      periodSeconds: 10
+      timeoutSeconds: 5
+      failureThreshold: 6
+    readinessProbe:
+      httpGet:
+        path: /health
+        port: 8091
+      initialDelaySeconds: 15
+      periodSeconds: 5
+      timeoutSeconds: 3
+      failureThreshold: 3
+
 # Autoscaling
 autoscaling:
   enabled: false

hindsight-api/hindsight_api/__init__.py

@@ -46,4 +46,4 @@ __all__ = [
     "RemoteTEICrossEncoder",
     "LLMConfig",
 ]
-__version__ = "0.4.9"
+__version__ = "0.4.11"

hindsight-api/hindsight_api/alembic/versions/5a366d414dce_initial_schema.py

@@ -6,6 +6,7 @@ Create Date: 2025-11-27 11:54:19.228030
 
 """
 
+import os
 from collections.abc import Sequence
 
 import sqlalchemy as sa
@@ -21,6 +22,88 @@ branch_labels: str | Sequence[str] | None = None
 depends_on: str | Sequence[str] | None = None
 
 
+def _detect_vector_extension() -> str:
+    """
+    Detect or validate vector extension: 'pgvector', 'vchord', or 'pgvectorscale'.
+    Respects HINDSIGHT_API_VECTOR_EXTENSION env var if set.
+    """
+    conn = op.get_bind()
+    vector_extension = os.getenv("HINDSIGHT_API_VECTOR_EXTENSION", "pgvector").lower()
+
+    # Validate configured extension is installed
+    if vector_extension == "pgvectorscale":
+        # pgvectorscale requires pgvector
+        pgvector_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vector'")).scalar()
+        if not pgvector_check:
+            raise RuntimeError(
+                "pgvectorscale requires pgvector. Install with: CREATE EXTENSION vector; CREATE EXTENSION vectorscale CASCADE;"
+            )
+        vectorscale_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vectorscale'")).scalar()
+        if not vectorscale_check:
+            raise RuntimeError(
+                "Configured vector extension 'pgvectorscale' not found. Install it with: CREATE EXTENSION vectorscale CASCADE;"
+            )
+        return "pgvectorscale"
+    elif vector_extension == "vchord":
+        vchord_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vchord'")).scalar()
+        if not vchord_check:
+            raise RuntimeError(
+                "Configured vector extension 'vchord' not found. Install it with: CREATE EXTENSION vchord CASCADE;"
+            )
+        return "vchord"
+    elif vector_extension == "pgvector":
+        pgvector_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vector'")).scalar()
+        if not pgvector_check:
+            raise RuntimeError(
+                "Configured vector extension 'pgvector' not found. Install it with: CREATE EXTENSION vector;"
+            )
+        return "pgvector"
+    else:
+        raise ValueError(
+            f"Invalid HINDSIGHT_API_VECTOR_EXTENSION: {vector_extension}. Must be 'pgvector', 'vchord', or 'pgvectorscale'"
+        )
+
+
+def _detect_text_search_extension() -> str:
+    """
+    Detect or validate text search extension: 'native', 'vchord', or 'pg_textsearch'.
+    Respects HINDSIGHT_API_TEXT_SEARCH_EXTENSION env var.
+    Creates the extension if needed.
+    """
+    text_search_extension = os.getenv("HINDSIGHT_API_TEXT_SEARCH_EXTENSION", "native").lower()
+
+    if text_search_extension == "vchord":
+        # Create vchord_bm25 extension if not exists
+        try:
+            op.execute("CREATE EXTENSION IF NOT EXISTS vchord_bm25 CASCADE")
+        except Exception:
+            # Extension might already exist or user lacks permissions - verify it exists
+            conn = op.get_bind()
+            result = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vchord_bm25'")).fetchone()
+            if not result:
+                # Extension truly doesn't exist - re-raise the error
+                raise
+        return "vchord"
+    elif text_search_extension == "pg_textsearch":
+        # Create pg_textsearch extension if not exists
+        try:
+            op.execute("CREATE EXTENSION IF NOT EXISTS pg_textsearch CASCADE")
+        except Exception:
+            # Extension might already exist or user lacks permissions - verify it exists
+            conn = op.get_bind()
+            result = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'pg_textsearch'")).fetchone()
+            if not result:
+                # Extension truly doesn't exist - re-raise the error
+                raise
+        return "pg_textsearch"
+    elif text_search_extension == "native":
+        return "native"
+    else:
+        raise ValueError(
+            f"Invalid HINDSIGHT_API_TEXT_SEARCH_EXTENSION: {text_search_extension}. Must be 'native', 'vchord', or 'pg_textsearch'"
+        )
+
+
 def upgrade() -> None:
     """Upgrade schema - create all tables from scratch."""
 
@@ -166,11 +249,29 @@ def upgrade() -> None:
     )
 
     # Add search_vector column for full-text search
-    op.execute("""
-        ALTER TABLE memory_units
-        ADD COLUMN search_vector tsvector
-        GENERATED ALWAYS AS (to_tsvector('english', COALESCE(text, '') || ' ' || COALESCE(context, ''))) STORED
-    """)
+    # Type depends on configured text search backend
+    text_search_ext = _detect_text_search_extension()
+
+    if text_search_ext == "vchord":
+        # VectorChord BM25: bm25vector type (no GENERATED - tokenization happens on INSERT)
+        # Note: vchord_bm25 extension creates types in bm25_catalog schema
+        op.execute("""
+            ALTER TABLE memory_units
+            ADD COLUMN search_vector bm25_catalog.bm25vector
+        """)
+    elif text_search_ext == "pg_textsearch":
+        # Timescale pg_textsearch: dummy TEXT column for consistency (indexes operate on base columns directly)
+        op.execute("""
+            ALTER TABLE memory_units
+            ADD COLUMN search_vector TEXT
+        """)
+    else:  # native
+        # Native PostgreSQL: tsvector with automatic generation
+        op.execute("""
+            ALTER TABLE memory_units
+            ADD COLUMN search_vector tsvector
+            GENERATED ALWAYS AS (to_tsvector('english', COALESCE(text, '') || ' ' || COALESCE(context, ''))) STORED
+        """)
 
     op.create_index("idx_memory_units_bank_id", "memory_units", ["bank_id"])
     op.create_index("idx_memory_units_document_id", "memory_units", ["document_id"])
@@ -200,19 +301,54 @@ def upgrade() -> None:
         ["bank_id", sa.text("event_date DESC")],
         postgresql_where=sa.text("fact_type = 'observation'"),
     )
-    op.create_index(
-        "idx_memory_units_embedding",
-        "memory_units",
-        ["embedding"],
-        postgresql_using="hnsw",
-        postgresql_ops={"embedding": "vector_cosine_ops"},
-    )
+    # Create vector index - conditional based on available extension
+    vector_ext = _detect_vector_extension()
 
-    # Create BM25 full-text search index on search_vector
-    op.execute("""
-        CREATE INDEX idx_memory_units_text_search ON memory_units
-        USING gin(search_vector)
-    """)
+    if vector_ext == "pgvectorscale":
+        # Use DiskANN index for pgvectorscale (disk-based, scalable)
+        op.execute("""
+            CREATE INDEX idx_memory_units_embedding ON memory_units
+            USING diskann (embedding vector_cosine_ops)
+            WITH (num_neighbors = 50)
+        """)
+    elif vector_ext == "vchord":
+        # Use vchordrq index for vchord (supports high-dimensional embeddings)
+        op.execute("""
+            CREATE INDEX idx_memory_units_embedding ON memory_units
+            USING vchordrq (embedding vector_l2_ops)
+        """)
+    else:  # pgvector
+        # Use HNSW index for pgvector
+        op.create_index(
+            "idx_memory_units_embedding",
+            "memory_units",
+            ["embedding"],
+            postgresql_using="hnsw",
+            postgresql_ops={"embedding": "vector_cosine_ops"},
+        )
+
+    # Create full-text search index on search_vector
+    # Index type depends on text search backend
+    if text_search_ext == "vchord":
+        # VectorChord BM25 index
+        op.execute("""
+            CREATE INDEX idx_memory_units_text_search ON memory_units
+            USING bm25 (search_vector bm25_catalog.bm25_ops)
+        """)
+    elif text_search_ext == "pg_textsearch":
+        # Timescale pg_textsearch BM25 index on text column
+        # Note: pg_textsearch doesn't support expressions, so we index the main text column
+        op.execute("""
+            CREATE INDEX idx_memory_units_text_search ON memory_units
+            USING bm25(text)
+            WITH (text_config='english')
+        """)
+    else:  # native
+        # Native PostgreSQL GIN index
+        op.execute("""
+            CREATE INDEX idx_memory_units_text_search ON memory_units
+            USING gin(search_vector)
+        """)
 
     op.execute("""
         CREATE MATERIALIZED VIEW memory_units_bm25 AS

hindsight-api/hindsight_api/alembic/versions/n9i0j1k2l3m4_learnings_and_pinned_reflections.py

@@ -10,9 +10,11 @@ This migration:
 3. Adds consolidation tracking columns to the 'banks' table
 """
 
+import os
 from collections.abc import Sequence
 
 from alembic import context, op
+from sqlalchemy import text
 
 # revision identifiers, used by Alembic.
 revision: str = "n9i0j1k2l3m4"
@@ -27,10 +29,98 @@ def _get_schema_prefix() -> str:
     return f'"{schema}".' if schema else ""
 
 
+def _detect_vector_extension() -> str:
+    """
+    Detect or validate vector extension: 'pgvector', 'vchord', or 'pgvectorscale'.
+    Respects HINDSIGHT_API_VECTOR_EXTENSION env var if set.
+    """
+    conn = op.get_bind()
+    vector_extension = os.getenv("HINDSIGHT_API_VECTOR_EXTENSION", "pgvector").lower()
+
+    # Validate configured extension is installed
+    if vector_extension == "pgvectorscale":
+        # pgvectorscale requires pgvector
+        pgvector_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vector'")).scalar()
+        if not pgvector_check:
+            raise RuntimeError(
+                "pgvectorscale requires pgvector. Install with: CREATE EXTENSION vector; CREATE EXTENSION vectorscale CASCADE;"
+            )
+        vectorscale_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vectorscale'")).scalar()
+        if not vectorscale_check:
+            raise RuntimeError(
+                "Configured vector extension 'pgvectorscale' not found. Install it with: CREATE EXTENSION vectorscale CASCADE;"
+            )
+        return "pgvectorscale"
+    elif vector_extension == "vchord":
+        vchord_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vchord'")).scalar()
+        if not vchord_check:
+            raise RuntimeError(
+                "Configured vector extension 'vchord' not found. Install it with: CREATE EXTENSION vchord CASCADE;"
+            )
+        return "vchord"
+    elif vector_extension == "pgvector":
+        pgvector_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vector'")).scalar()
+        if not pgvector_check:
+            raise RuntimeError(
+                "Configured vector extension 'pgvector' not found. Install it with: CREATE EXTENSION vector;"
+            )
+        return "pgvector"
+    else:
+        raise ValueError(
+            f"Invalid HINDSIGHT_API_VECTOR_EXTENSION: {vector_extension}. Must be 'pgvector', 'vchord', or 'pgvectorscale'"
+        )
+
+
+def _detect_text_search_extension() -> str:
+    """
+    Detect or validate text search extension: 'native', 'vchord', or 'pg_textsearch'.
+    Respects HINDSIGHT_API_TEXT_SEARCH_EXTENSION env var.
+    Creates the extension if needed.
+    """
+    text_search_extension = os.getenv("HINDSIGHT_API_TEXT_SEARCH_EXTENSION", "native").lower()
+
+    if text_search_extension == "vchord":
+        # Create vchord_bm25 extension if not exists
+        try:
+            op.execute("CREATE EXTENSION IF NOT EXISTS vchord_bm25 CASCADE")
+        except Exception:
+            # Extension might already exist or user lacks permissions - verify it exists
+            conn = op.get_bind()
+            result = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vchord_bm25'")).fetchone()
+            if not result:
+                # Extension truly doesn't exist - re-raise the error
+                raise
+        return "vchord"
+    elif text_search_extension == "pg_textsearch":
+        # Create pg_textsearch extension if not exists
+        try:
+            op.execute("CREATE EXTENSION IF NOT EXISTS pg_textsearch CASCADE")
+        except Exception:
+            # Extension might already exist or user lacks permissions - verify it exists
+            conn = op.get_bind()
+            result = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'pg_textsearch'")).fetchone()
+            if not result:
+                # Extension truly doesn't exist - re-raise the error
+                raise
+        return "pg_textsearch"
+    elif text_search_extension == "native":
+        return "native"
+    else:
+        raise ValueError(
+            f"Invalid HINDSIGHT_API_TEXT_SEARCH_EXTENSION: {text_search_extension}. Must be 'native', 'vchord', or 'pg_textsearch'"
+        )
+
+
 def upgrade() -> None:
     """Create learnings and pinned_reflections tables."""
     schema = _get_schema_prefix()
 
+    # Detect which vector extension is available
+    vector_ext = _detect_vector_extension()
+
+    # Detect which text search extension to use
+    text_search_ext = _detect_text_search_extension()
+
     # 1. Create learnings table
     op.execute(f"""
         CREATE TABLE {schema}learnings (
@@ -57,18 +147,54 @@ def upgrade() -> None:
 
     # Indexes for learnings
     op.execute(f"CREATE INDEX idx_learnings_bank_id ON {schema}learnings(bank_id)")
-    op.execute(f"""
-        CREATE INDEX idx_learnings_embedding ON {schema}learnings
-        USING hnsw (embedding vector_cosine_ops)
-    """)
+
+    # Create vector index based on detected extension
+    if vector_ext == "pgvectorscale":
+        op.execute(f"""
+            CREATE INDEX idx_learnings_embedding ON {schema}learnings
+            USING diskann (embedding vector_cosine_ops)
+            WITH (num_neighbors = 50)
+        """)
+    elif vector_ext == "vchord":
+        op.execute(f"""
+            CREATE INDEX idx_learnings_embedding ON {schema}learnings
+            USING vchordrq (embedding vector_l2_ops)
+        """)
+    else:  # pgvector
+        op.execute(f"""
+            CREATE INDEX idx_learnings_embedding ON {schema}learnings
+            USING hnsw (embedding vector_cosine_ops)
+        """)
+
     op.execute(f"CREATE INDEX idx_learnings_tags ON {schema}learnings USING GIN(tags)")
 
     # Full-text search for learnings
-    op.execute(f"""
-        ALTER TABLE {schema}learnings ADD COLUMN search_vector tsvector
-        GENERATED ALWAYS AS (to_tsvector('english', text)) STORED
-    """)
-    op.execute(f"CREATE INDEX idx_learnings_text_search ON {schema}learnings USING gin(search_vector)")
+    if text_search_ext == "vchord":
+        # VectorChord BM25: bm25vector type (no GENERATED - tokenization happens on INSERT)
+        # Note: vchord_bm25 extension creates types in bm25_catalog schema
+        op.execute(f"""
+            ALTER TABLE {schema}learnings ADD COLUMN search_vector bm25_catalog.bm25vector
+        """)
+        op.execute(f"""
+            CREATE INDEX idx_learnings_text_search ON {schema}learnings
+            USING bm25 (search_vector bm25_catalog.bm25_ops)
+        """)
+    elif text_search_ext == "pg_textsearch":
+        # Timescale pg_textsearch: dummy TEXT column for consistency (indexes operate on base columns directly)
+        op.execute(f"""
+            ALTER TABLE {schema}learnings ADD COLUMN search_vector TEXT
+        """)
+        op.execute(f"""
+            CREATE INDEX idx_learnings_text_search ON {schema}learnings
+            USING bm25(text) WITH (text_config='english')
+        """)
+    else:  # native
+        # Native PostgreSQL: tsvector with automatic generation
+        op.execute(f"""
+            ALTER TABLE {schema}learnings ADD COLUMN search_vector tsvector
+            GENERATED ALWAYS AS (to_tsvector('english', text)) STORED
+        """)
+        op.execute(f"CREATE INDEX idx_learnings_text_search ON {schema}learnings USING gin(search_vector)")
 
     # 2. Create pinned_reflections table
     op.execute(f"""
@@ -94,21 +220,58 @@ def upgrade() -> None:
 
     # Indexes for pinned_reflections
     op.execute(f"CREATE INDEX idx_pinned_reflections_bank_id ON {schema}pinned_reflections(bank_id)")
-    op.execute(f"""
-        CREATE INDEX idx_pinned_reflections_embedding ON {schema}pinned_reflections
-        USING hnsw (embedding vector_cosine_ops)
-    """)
+
+    # Create vector index based on detected extension
+    if vector_ext == "pgvectorscale":
+        op.execute(f"""
+            CREATE INDEX idx_pinned_reflections_embedding ON {schema}pinned_reflections
+            USING diskann (embedding vector_cosine_ops)
+            WITH (num_neighbors = 50)
+        """)
+    elif vector_ext == "vchord":
+        op.execute(f"""
+            CREATE INDEX idx_pinned_reflections_embedding ON {schema}pinned_reflections
+            USING vchordrq (embedding vector_l2_ops)
+        """)
+    else:  # pgvector
+        op.execute(f"""
+            CREATE INDEX idx_pinned_reflections_embedding ON {schema}pinned_reflections
+            USING hnsw (embedding vector_cosine_ops)
+        """)
+
     op.execute(f"CREATE INDEX idx_pinned_reflections_tags ON {schema}pinned_reflections USING GIN(tags)")
 
     # Full-text search for pinned_reflections
-    op.execute(f"""
-        ALTER TABLE {schema}pinned_reflections ADD COLUMN search_vector tsvector
-        GENERATED ALWAYS AS (to_tsvector('english', COALESCE(name, '') || ' ' || content)) STORED
-    """)
-    op.execute(f"""
-        CREATE INDEX idx_pinned_reflections_text_search ON {schema}pinned_reflections
-        USING gin(search_vector)
-    """)
+    if text_search_ext == "vchord":
+        # VectorChord BM25: bm25vector type (no GENERATED - tokenization happens on INSERT/UPDATE)
+        # Note: vchord_bm25 extension creates types in bm25_catalog schema
+        op.execute(f"""
+            ALTER TABLE {schema}pinned_reflections ADD COLUMN search_vector bm25_catalog.bm25vector
+        """)
+        op.execute(f"""
+            CREATE INDEX idx_pinned_reflections_text_search ON {schema}pinned_reflections
+            USING bm25 (search_vector bm25_catalog.bm25_ops)
+        """)
+    elif text_search_ext == "pg_textsearch":
+        # Timescale pg_textsearch: dummy TEXT column for consistency (indexes operate on base columns directly)
+        op.execute(f"""
+            ALTER TABLE {schema}pinned_reflections ADD COLUMN search_vector TEXT
+        """)
+        op.execute(f"""
+            CREATE INDEX idx_pinned_reflections_text_search ON {schema}pinned_reflections
+            USING bm25(content)
+            WITH (text_config='english')
+        """)
+    else:  # native
+        # Native PostgreSQL: tsvector with automatic generation
+        op.execute(f"""
+            ALTER TABLE {schema}pinned_reflections ADD COLUMN search_vector tsvector
+            GENERATED ALWAYS AS (to_tsvector('english', COALESCE(name, '') || ' ' || content)) STORED
+        """)
+        op.execute(f"""
+            CREATE INDEX idx_pinned_reflections_text_search ON {schema}pinned_reflections
+            USING gin(search_vector)
+        """)
 
     # 3. Add consolidation tracking columns to banks table
     op.execute(f"""

hindsight-api/hindsight_api/alembic/versions/w8r9s0t1u2v3_fix_mental_models_pk_isolation.py

@@ -0,0 +1,60 @@
+"""Fix mental_models primary key to be scoped per bank
+
+Revision ID: w8r9s0t1u2v3
+Revises: v7q8r9s0t1u2
+Create Date: 2026-02-05
+
+This migration fixes a critical bank isolation bug where mental_models.id was
+globally unique across all banks instead of being scoped per bank. This caused
+conflicts when different banks tried to use the same custom ID.
+
+CRITICAL FIX: Changes primary key from (id) to (bank_id, id) to ensure proper isolation.
+"""
+
+from collections.abc import Sequence
+
+from alembic import context, op
+
+revision: str = "w8r9s0t1u2v3"
+down_revision: str | Sequence[str] | None = "v7q8r9s0t1u2"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def _get_schema_prefix() -> str:
+    """Get schema prefix for table names (required for multi-tenant support)."""
+    schema = context.config.get_main_option("target_schema")
+    return f'"{schema}".' if schema else ""
+
+
+def upgrade() -> None:
+    """Change mental_models primary key from (id) to (bank_id, id) for proper bank isolation."""
+    schema = _get_schema_prefix()
+
+    # Drop the old primary key constraint (just id)
+    # Note: The constraint might be named differently on different DBs
+    # Try both old names (pinned_reflections_pkey from original, mental_models_pkey from rename)
+    op.execute(f"ALTER TABLE {schema}mental_models DROP CONSTRAINT IF EXISTS pinned_reflections_pkey")
+    op.execute(f"ALTER TABLE {schema}mental_models DROP CONSTRAINT IF EXISTS mental_models_pkey")
+
+    # Create the new composite primary key (bank_id, id)
+    # This ensures IDs are scoped per bank, not globally
+    op.execute(f"""
+        ALTER TABLE {schema}mental_models
+        ADD CONSTRAINT mental_models_pkey PRIMARY KEY (bank_id, id)
+    """)
+
+
+def downgrade() -> None:
+    """Revert mental_models primary key from (bank_id, id) to (id)."""
+    schema = _get_schema_prefix()
+
+    # Drop the composite primary key
+    op.execute(f"ALTER TABLE {schema}mental_models DROP CONSTRAINT IF EXISTS mental_models_pkey")
+
+    # Restore the old primary key (just id)
+    # WARNING: This downgrade will fail if there are duplicate IDs across banks
+    op.execute(f"""
+        ALTER TABLE {schema}mental_models
+        ADD CONSTRAINT mental_models_pkey PRIMARY KEY (id)
+    """)

hindsight-api/hindsight_api/alembic/versions/x9s0t1u2v3w4_add_bank_config_column.py

@@ -0,0 +1,64 @@
+"""Add config JSONB column to banks table for hierarchical configuration
+
+Revision ID: x9s0t1u2v3w4
+Revises: w8r9s0t1u2v3
+Create Date: 2026-02-09
+
+This migration adds a `config` JSONB column to the banks table to support
+per-bank configuration overrides. This enables hierarchical configuration where:
+- Global config is loaded from environment variables
+- Tenant config is provided via TenantExtension
+- Bank config overrides are stored in banks.config JSONB column
+
+The config column stores overrides for hierarchical fields (LLM settings,
+retention parameters, retrieval settings, etc.) in Python field name format.
+"""
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import context, op
+from sqlalchemy.dialects.postgresql import JSONB
+
+revision: str = "x9s0t1u2v3w4"
+down_revision: str | Sequence[str] | None = "w8r9s0t1u2v3"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def _get_schema_prefix() -> str:
+    """Get schema prefix for table names (required for multi-tenant support)."""
+    schema = context.config.get_main_option("target_schema")
+    return f'"{schema}".' if schema else ""
+
+
+def upgrade() -> None:
+    """Add config JSONB column to banks table with GIN index."""
+    schema = _get_schema_prefix()
+
+    # Add config column to banks table
+    op.execute(f"""
+        ALTER TABLE {schema}banks
+        ADD COLUMN config JSONB NOT NULL DEFAULT '{{}}'::jsonb
+    """)
+
+    # Add GIN index for efficient JSONB queries
+    op.execute(f"""
+        CREATE INDEX idx_banks_config
+        ON {schema}banks
+        USING gin(config)
+    """)
+
+
+def downgrade() -> None:
+    """Remove config column and index from banks table."""
+    schema = _get_schema_prefix()
+
+    # Drop index first
+    op.execute(f"DROP INDEX IF EXISTS {schema}idx_banks_config")
+
+    # Drop column
+    op.execute(f"""
+        ALTER TABLE {schema}banks
+        DROP COLUMN IF EXISTS config
+    """)

hindsight-api/hindsight_api/api/__init__.py

@@ -6,7 +6,6 @@ Provides both HTTP REST API and MCP (Model Context Protocol) server.
 
 import logging
 from contextlib import asynccontextmanager
-from typing import Optional
 
 from fastapi import FastAPI
 
@@ -46,14 +45,14 @@ def create_app(
         # Both HTTP and MCP
         app = create_app(memory, mcp_api_enabled=True)
     """
-    mcp_app = None
+    mcp_servers = None
 
-    # Create MCP app first if enabled (we need its lifespan for chaining)
+    # Create MCP servers first if enabled (we need their lifespans for chaining)
     if mcp_api_enabled:
         try:
-            from .mcp import create_mcp_app
+            from .mcp import MCPMiddleware, create_mcp_servers
 
-            mcp_app = create_mcp_app(memory=memory)
+            mcp_servers = create_mcp_servers(memory=memory)
         except ImportError as e:
             logger.error(f"MCP server requested but dependencies not available: {e}")
             logger.error("Install with: pip install hindsight-api[mcp]")
@@ -70,30 +69,41 @@ def create_app(
         app = FastAPI(title="Hindsight API", version="0.0.7")
         logger.info("HTTP REST API disabled")
 
-    # Mount MCP server and chain its lifespan if enabled
-    if mcp_app is not None:
-        # Get the MCP app's underlying Starlette app for lifespan access
-        mcp_starlette_app = mcp_app.mcp_app
+    # Add MCP middleware and chain its lifespan if enabled
+    if mcp_servers is not None:
+        multi_bank_server, single_bank_server, multi_bank_starlette_app, single_bank_starlette_app = mcp_servers
 
         # Store the original lifespan
         original_lifespan = app.router.lifespan_context
 
         @asynccontextmanager
         async def chained_lifespan(app_instance: FastAPI):
-            """Chain the MCP lifespan with the main app lifespan."""
-            # Start MCP lifespan first
-            async with mcp_starlette_app.router.lifespan_context(mcp_starlette_app):
-                logger.info("MCP lifespan started")
-                # Then start the original app lifespan
-                async with original_lifespan(app_instance):
-                    yield
-            logger.info("MCP lifespan stopped")
+            """Chain both MCP lifespans with the main app lifespan."""
+            # Start both MCP lifespans (multi-bank and single-bank)
+            async with multi_bank_starlette_app.router.lifespan_context(multi_bank_starlette_app):
+                async with single_bank_starlette_app.router.lifespan_context(single_bank_starlette_app):
+                    logger.info("MCP lifespans started (multi-bank and single-bank)")
+                    # Then start the original app lifespan
+                    async with original_lifespan(app_instance):
+                        yield
+                logger.info("MCP lifespans stopped")
 
         # Replace the app's lifespan with the chained version
         app.router.lifespan_context = chained_lifespan
 
-        # Mount the MCP middleware
-        app.mount(mcp_mount_path, mcp_app)
+        # Add MCP as a wrapping middleware — intercepts /mcp* requests directly,
+        # passes everything else through to the FastAPI app. No Starlette Mount
+        # means no 307 redirect for /mcp (no trailing slash).
+        app.add_middleware(
+            MCPMiddleware,
+            memory=memory,
+            prefix=mcp_mount_path,
+            multi_bank_app=multi_bank_starlette_app,
+            single_bank_app=single_bank_starlette_app,
+            multi_bank_server=multi_bank_server,
+            single_bank_server=single_bank_server,
+        )
+
         logger.info(f"MCP server enabled at {mcp_mount_path}/")
 
     return app

hindsight-api/hindsight_api/api/http.py

@@ -32,9 +32,45 @@ def _parse_metadata(metadata: Any) -> dict[str, Any]:
     return {}
 
 
+from typing import Callable
+
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from hindsight_api import MemoryEngine
+
+
+def FieldWithDefault(default_factory: Callable, **kwargs) -> Any:
+    """
+    Field wrapper that ensures default_factory values appear in OpenAPI schema.
+
+    Pydantic doesn't include default_factory in OpenAPI schemas, causing OpenAPI
+    Generator to make fields Optional with default=None instead of non-optional
+    with the correct default value.
+
+    This wrapper adds json_schema_extra to include the default in the schema.
+    """
+    # Determine the default value for the schema based on the factory
+    if default_factory is list:
+        schema_default = []
+    elif default_factory is dict:
+        schema_default = {}
+    else:
+        # For custom factories (like IncludeOptions), use empty dict as placeholder
+        schema_default = {}
+
+    # Add or merge json_schema_extra
+    json_extra = kwargs.pop("json_schema_extra", {})
+    if isinstance(json_extra, dict):
+        json_extra["default"] = schema_default
+    else:
+        # If json_schema_extra was a function, we can't merge easily
+        # Fall back to just setting default
+        json_extra = {"default": schema_default}
+
+    return Field(default_factory=default_factory, json_schema_extra=json_extra, **kwargs)
+
+
+from hindsight_api.config import get_config
 from hindsight_api.engine.db_utils import acquire_with_retry
 from hindsight_api.engine.memory_engine import Budget, _get_tiktoken_encoding, fq_table
 from hindsight_api.engine.reflect.observations import Observation
@@ -103,8 +139,8 @@ class RecallRequest(BaseModel):
     query_timestamp: str | None = Field(
         default=None, description="ISO format date string (e.g., '2023-05-30T23:40:00')"
     )
-    include: IncludeOptions = Field(
-        default_factory=IncludeOptions,
+    include: IncludeOptions = FieldWithDefault(
+        IncludeOptions,
         description="Options for including additional data (entities are included by default)",
     )
     tags: list[str] | None = Field(
@@ -523,7 +559,9 @@ class ReflectFact(BaseModel):
     )
 
     id: str | None = None
-    text: str
+    text: str = Field(
+        description="Fact text. When type='observation', this contains markdown-formatted consolidated knowledge"
+    )
     type: str | None = None  # fact type: world, experience, observation
     context: str | None = None
     occurred_start: str | None = None
@@ -568,18 +606,16 @@ class ReflectLLMCall(BaseModel):
 class ReflectBasedOn(BaseModel):
     """Evidence the response is based on: memories, mental models, and directives."""
 
-    memories: list[ReflectFact] = Field(default_factory=list, description="Memory facts used to generate the response")
-    mental_models: list[ReflectMentalModel] = Field(
-        default_factory=list, description="Mental models used during reflection"
-    )
-    directives: list[ReflectDirective] = Field(default_factory=list, description="Directives applied during reflection")
+    memories: list[ReflectFact] = FieldWithDefault(list, description="Memory facts used to generate the response")
+    mental_models: list[ReflectMentalModel] = FieldWithDefault(list, description="Mental models used during reflection")
+    directives: list[ReflectDirective] = FieldWithDefault(list, description="Directives applied during reflection")
 
 
 class ReflectTrace(BaseModel):
     """Execution trace of LLM and tool calls during reflection."""
 
-    tool_calls: list[ReflectToolCall] = Field(default_factory=list, description="Tool calls made during reflection")
-    llm_calls: list[ReflectLLMCall] = Field(default_factory=list, description="LLM calls made during reflection")
+    tool_calls: list[ReflectToolCall] = FieldWithDefault(list, description="Tool calls made during reflection")
+    llm_calls: list[ReflectLLMCall] = FieldWithDefault(list, description="LLM calls made during reflection")
 
 
 class ReflectResponse(BaseModel):
@@ -588,7 +624,7 @@ class ReflectResponse(BaseModel):
     model_config = ConfigDict(
         json_schema_extra={
             "example": {
-                "text": "Based on my understanding, AI is a transformative technology...",
+                "text": "## AI Overview\n\nBased on my understanding, AI is a **transformative technology**:\n\n- Used extensively in healthcare\n- Discussed in recent conversations\n- Continues to evolve rapidly",
                 "based_on": {
                     "memories": [
                         {"id": "123", "text": "AI is used in healthcare", "type": "world"},
@@ -616,7 +652,9 @@ class ReflectResponse(BaseModel):
         }
     )
 
-    text: str
+    text: str = Field(
+        description="The reflect response as well-formatted markdown (headers, lists, bold/italic, code blocks, etc.)"
+    )
     based_on: ReflectBasedOn | None = Field(
         default=None,
         description="Evidence used to generate the response. Only present when include.facts is set.",
@@ -789,6 +827,55 @@ class CreateBankRequest(BaseModel):
     background: str | None = Field(default=None, description="Deprecated: use mission instead")
 
 
+class BankConfigUpdate(BaseModel):
+    """Request model for updating bank configuration."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "updates": {
+                    "llm_model": "claude-sonnet-4-5",
+                    "retain_extraction_mode": "verbose",
+                    "retain_custom_instructions": "Extract technical details carefully",
+                }
+            }
+        }
+    )
+
+    updates: dict[str, Any] = Field(
+        description="Configuration overrides. Keys can be in Python field format (llm_provider) "
+        "or environment variable format (HINDSIGHT_API_LLM_PROVIDER). "
+        "Only hierarchical fields can be overridden per-bank."
+    )
+
+
+class BankConfigResponse(BaseModel):
+    """Response model for bank configuration."""
+
+    model_config = ConfigDict(
+        json_schema_extra={
+            "example": {
+                "bank_id": "my-bank",
+                "config": {
+                    "llm_provider": "openai",
+                    "llm_model": "gpt-4",
+                    "retain_extraction_mode": "verbose",
+                },
+                "overrides": {
+                    "llm_model": "gpt-4",
+                    "retain_extraction_mode": "verbose",
+                },
+            }
+        }
+    )
+
+    bank_id: str = Field(description="Bank identifier")
+    config: dict[str, Any] = Field(
+        description="Fully resolved configuration with all hierarchical overrides applied (Python field names)"
+    )
+    overrides: dict[str, Any] = Field(description="Bank-specific configuration overrides only (Python field names)")
+
+
 class GraphDataResponse(BaseModel):
     """Response model for graph data endpoint."""
 
@@ -938,7 +1025,7 @@ class DocumentResponse(BaseModel):
     created_at: str
     updated_at: str
     memory_unit_count: int
-    tags: list[str] = Field(default_factory=list, description="Tags associated with this document")
+    tags: list[str] = FieldWithDefault(list, description="Tags associated with this document")
 
 
 class DeleteDocumentResponse(BaseModel):
@@ -1062,7 +1149,7 @@ class DirectiveResponse(BaseModel):
     content: str
     priority: int = 0
     is_active: bool = True
-    tags: list[str] = Field(default_factory=list)
+    tags: list[str] = FieldWithDefault(list)
     created_at: str | None = None
     updated_at: str | None = None
 
@@ -1080,7 +1167,7 @@ class CreateDirectiveRequest(BaseModel):
     content: str = Field(description="The directive text to inject into prompts")
     priority: int = Field(default=0, description="Higher priority directives are injected first")
     is_active: bool = Field(default=True, description="Whether this directive is active")
-    tags: list[str] = Field(default_factory=list, description="Tags for filtering")
+    tags: list[str] = FieldWithDefault(list, description="Tags for filtering")
 
 
 class UpdateDirectiveRequest(BaseModel):
@@ -1114,10 +1201,12 @@ class MentalModelResponse(BaseModel):
     bank_id: str
     name: str
     source_query: str
-    content: str
-    tags: list[str] = Field(default_factory=list)
+    content: str = Field(
+        description="The mental model content as well-formatted markdown (auto-generated from reflect endpoint)"
+    )
+    tags: list[str] = FieldWithDefault(list)
     max_tokens: int = Field(default=2048)
-    trigger: MentalModelTrigger = Field(default_factory=MentalModelTrigger)
+    trigger: MentalModelTrigger = FieldWithDefault(MentalModelTrigger)
     last_refreshed_at: str | None = None
     created_at: str | None = None
     reflect_response: dict | None = Field(
@@ -1153,9 +1242,9 @@ class CreateMentalModelRequest(BaseModel):
     )
     name: str = Field(description="Human-readable name for the mental model")
     source_query: str = Field(description="The query to run to generate content")
-    tags: list[str] = Field(default_factory=list, description="Tags for scoped visibility")
+    tags: list[str] = FieldWithDefault(list, description="Tags for scoped visibility")
     max_tokens: int = Field(default=2048, ge=256, le=8192, description="Maximum tokens for generated content")
-    trigger: MentalModelTrigger = Field(default_factory=MentalModelTrigger, description="Trigger settings")
+    trigger: MentalModelTrigger = FieldWithDefault(MentalModelTrigger, description="Trigger settings")
 
 
 class CreateMentalModelResponse(BaseModel):
@@ -1316,6 +1405,7 @@ class FeaturesInfo(BaseModel):
     observations: bool = Field(description="Whether observations (auto-consolidation) are enabled")
     mcp: bool = Field(description="Whether MCP (Model Context Protocol) server is enabled")
     worker: bool = Field(description="Whether the background worker is enabled")
+    bank_config_api: bool = Field(description="Whether per-bank configuration API is enabled")
 
 
 class VersionResponse(BaseModel):
@@ -1329,6 +1419,7 @@ class VersionResponse(BaseModel):
                     "observations": False,
                     "mcp": True,
                     "worker": True,
+                    "bank_config_api": False,
                 },
             }
         }
@@ -1394,6 +1485,26 @@ def create_app(
             app.state.prometheus_reader = None
             # Metrics collector is already initialized as no-op by default
 
+        # Initialize OpenTelemetry tracing if enabled
+        if config.otel_traces_enabled:
+            if not config.otel_exporter_otlp_endpoint:
+                logging.warning("OTEL tracing enabled but no endpoint configured. Tracing disabled.")
+            else:
+                from hindsight_api.tracing import create_span_recorder, initialize_tracing
+
+                try:
+                    initialize_tracing(
+                        service_name=config.otel_service_name,
+                        endpoint=config.otel_exporter_otlp_endpoint,
+                        headers=config.otel_exporter_otlp_headers,
+                        deployment_environment=config.otel_deployment_environment,
+                    )
+                    create_span_recorder()
+                    logging.info("OpenTelemetry tracing enabled and configured")
+                except Exception as e:
+                    logging.error(f"Failed to initialize tracing: {e}")
+                    logging.warning("Continuing without tracing")
+
         # Startup: Initialize database and memory system (migrations run inside initialize if enabled)
         if initialize_memory:
             await memory.initialize()
@@ -1426,6 +1537,12 @@ def create_app(
             poller_task = asyncio.create_task(poller.run())
             logging.info(f"Worker poller started (worker_id={worker_id})")
 
+        # Call tenant extension startup hook (e.g. JWKS fetch for Supabase)
+        tenant_extension = memory.tenant_extension
+        if tenant_extension:
+            await tenant_extension.on_startup()
+            logging.info("Tenant extension started")
+
         # Call HTTP extension startup hook
         if http_extension:
             await http_extension.on_startup()
@@ -1444,6 +1561,11 @@ def create_app(
                     pass
             logging.info("Worker poller stopped")
 
+        # Call tenant extension shutdown hook
+        if tenant_extension:
+            await tenant_extension.on_shutdown()
+            logging.info("Tenant extension stopped")
+
         # Call HTTP extension shutdown hook
         if http_extension:
             await http_extension.on_shutdown()
@@ -1454,6 +1576,9 @@ def create_app(
         logging.info("Memory system closed")
 
     from hindsight_api import __version__
+    from hindsight_api.config import get_config
+
+    config = get_config()
 
     app = FastAPI(
         title="Hindsight HTTP API",
@@ -1467,6 +1592,7 @@ def create_app(
             "url": "https://www.apache.org/licenses/LICENSE-2.0.html",
         },
         lifespan=lifespan,
+        root_path=config.base_path,
     )
 
     # IMPORTANT: Set memory on app.state immediately, don't wait for lifespan
@@ -1573,17 +1699,21 @@ def _register_routes(app: FastAPI):
 
         Returns version info and feature flags that can be used by clients
         to determine which capabilities are available.
+
+        Note: observations flag shows the global default. Individual banks
+        may override this setting via bank-specific configuration.
         """
         from hindsight_api import __version__
-        from hindsight_api.config import get_config
+        from hindsight_api.config import _get_raw_config
 
-        config = get_config()
+        config = _get_raw_config()
         return VersionResponse(
             api_version=__version__,
             features=FeaturesInfo(
                 observations=config.enable_observations,
                 mcp=config.mcp_enabled,
                 worker=config.worker_enabled,
+                bank_config_api=config.enable_bank_config_api,
             ),
         )
 
@@ -2317,23 +2447,6 @@ def _register_routes(app: FastAPI):
     ):
         """Get a mental model by ID."""
         try:
-            # Pre-operation validation hook
-            validator = app.state.memory._operation_validator
-            if validator:
-                from hindsight_api.extensions.operation_validator import MentalModelGetContext
-
-                ctx = MentalModelGetContext(
-                    bank_id=bank_id,
-                    mental_model_id=mental_model_id,
-                    request_context=request_context,
-                )
-                validation = await validator.validate_mental_model_get(ctx)
-                if not validation.allowed:
-                    raise OperationValidationError(
-                        validation.reason or "Operation not allowed",
-                        status_code=validation.status_code,
-                    )
-
             mental_model = await app.state.memory.get_mental_model(
                 bank_id=bank_id,
                 mental_model_id=mental_model_id,
@@ -2342,25 +2455,6 @@ def _register_routes(app: FastAPI):
             if mental_model is None:
                 raise HTTPException(status_code=404, detail=f"Mental model '{mental_model_id}' not found")
 
-            # Post-operation hook
-            if validator:
-                from hindsight_api.extensions.operation_validator import MentalModelGetResult
-
-                content = mental_model.get("content", "")
-                output_tokens = len(content) // 4 if content else 0
-
-                result_ctx = MentalModelGetResult(
-                    bank_id=bank_id,
-                    mental_model_id=mental_model_id,
-                    request_context=request_context,
-                    output_tokens=output_tokens,
-                    success=True,
-                )
-                try:
-                    await validator.on_mental_model_get_complete(result_ctx)
-                except Exception as hook_err:
-                    logger.warning(f"Post-mental-model-get hook error (non-fatal): {hook_err}")
-
             return MentalModelResponse(**mental_model)
         except (AuthenticationError, HTTPException):
             raise
@@ -2390,23 +2484,6 @@ def _register_routes(app: FastAPI):
     ):
         """Create a mental model (async - returns operation_id)."""
         try:
-            # Pre-operation validation hook
-            validator = app.state.memory._operation_validator
-            if validator:
-                from hindsight_api.extensions.operation_validator import MentalModelRefreshContext
-
-                ctx = MentalModelRefreshContext(
-                    bank_id=bank_id,
-                    mental_model_id=None,  # Not yet created
-                    request_context=request_context,
-                )
-                validation = await validator.validate_mental_model_refresh(ctx)
-                if not validation.allowed:
-                    raise OperationValidationError(
-                        validation.reason or "Operation not allowed",
-                        status_code=validation.status_code,
-                    )
-
             # 1. Create the mental model with placeholder content
             mental_model = await app.state.memory.create_mental_model(
                 bank_id=bank_id,
@@ -2454,23 +2531,6 @@ def _register_routes(app: FastAPI):
     ):
         """Refresh a mental model by re-running its source query (async)."""
         try:
-            # Pre-operation validation hook
-            validator = app.state.memory._operation_validator
-            if validator:
-                from hindsight_api.extensions.operation_validator import MentalModelRefreshContext
-
-                ctx = MentalModelRefreshContext(
-                    bank_id=bank_id,
-                    mental_model_id=mental_model_id,
-                    request_context=request_context,
-                )
-                validation = await validator.validate_mental_model_refresh(ctx)
-                if not validation.allowed:
-                    raise OperationValidationError(
-                        validation.reason or "Operation not allowed",
-                        status_code=validation.status_code,
-                    )
-
             result = await app.state.memory.submit_async_refresh_mental_model(
                 bank_id=bank_id,
                 mental_model_id=mental_model_id,
@@ -3307,6 +3367,112 @@ def _register_routes(app: FastAPI):
             logger.error(f"Error in DELETE /v1/default/banks/{bank_id}/observations: {error_detail}")
             raise HTTPException(status_code=500, detail=str(e))
 
+    @app.get(
+        "/v1/default/banks/{bank_id}/config",
+        response_model=BankConfigResponse,
+        summary="Get bank configuration",
+        description="Get fully resolved configuration for a bank including all hierarchical overrides (global → tenant → bank). "
+        "The 'config' field contains all resolved config values. The 'overrides' field shows only bank-specific overrides.",
+        operation_id="get_bank_config",
+        tags=["Banks"],
+    )
+    async def api_get_bank_config(bank_id: str, request_context: RequestContext = Depends(get_request_context)):
+        """Get configuration for a bank with all hierarchical overrides applied."""
+        if not get_config().enable_bank_config_api:
+            raise HTTPException(
+                status_code=404,
+                detail="Bank configuration API is disabled. Set HINDSIGHT_API_ENABLE_BANK_CONFIG_API=true to enable.",
+            )
+        try:
+            # Get resolved config from config resolver
+            config_dict = await app.state.memory._config_resolver.get_bank_config(bank_id, request_context)
+
+            # Get bank-specific overrides only
+            bank_overrides = await app.state.memory._config_resolver._load_bank_config(bank_id)
+
+            return BankConfigResponse(bank_id=bank_id, config=config_dict, overrides=bank_overrides)
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in GET /v1/default/banks/{bank_id}/config: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+    @app.patch(
+        "/v1/default/banks/{bank_id}/config",
+        response_model=BankConfigResponse,
+        summary="Update bank configuration",
+        description="Update configuration overrides for a bank. Only hierarchical fields can be overridden (LLM settings, retention parameters, etc.). "
+        "Keys can be provided in Python field format (llm_provider) or environment variable format (HINDSIGHT_API_LLM_PROVIDER).",
+        operation_id="update_bank_config",
+        tags=["Banks"],
+    )
+    async def api_update_bank_config(
+        bank_id: str, request: BankConfigUpdate, request_context: RequestContext = Depends(get_request_context)
+    ):
+        """Update configuration overrides for a bank."""
+        if not get_config().enable_bank_config_api:
+            raise HTTPException(
+                status_code=404,
+                detail="Bank configuration API is disabled. Set HINDSIGHT_API_ENABLE_BANK_CONFIG_API=true to enable.",
+            )
+        try:
+            # Update config via config resolver (validates configurable fields and permissions)
+            await app.state.memory._config_resolver.update_bank_config(bank_id, request.updates, request_context)
+
+            # Return updated config
+            config_dict = await app.state.memory._config_resolver.get_bank_config(bank_id, request_context)
+            bank_overrides = await app.state.memory._config_resolver._load_bank_config(bank_id)
+
+            return BankConfigResponse(bank_id=bank_id, config=config_dict, overrides=bank_overrides)
+        except ValueError as e:
+            # Validation error (e.g., trying to override static field)
+            raise HTTPException(status_code=400, detail=str(e))
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in PATCH /v1/default/banks/{bank_id}/config: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
+    @app.delete(
+        "/v1/default/banks/{bank_id}/config",
+        response_model=BankConfigResponse,
+        summary="Reset bank configuration",
+        description="Reset bank configuration to defaults by removing all bank-specific overrides. "
+        "The bank will then use global and tenant-level configuration only.",
+        operation_id="reset_bank_config",
+        tags=["Banks"],
+    )
+    async def api_reset_bank_config(bank_id: str, request_context: RequestContext = Depends(get_request_context)):
+        """Reset bank configuration to defaults (remove all overrides)."""
+        if not get_config().enable_bank_config_api:
+            raise HTTPException(
+                status_code=404,
+                detail="Bank configuration API is disabled. Set HINDSIGHT_API_ENABLE_BANK_CONFIG_API=true to enable.",
+            )
+        try:
+            # Reset config via config resolver
+            await app.state.memory._config_resolver.reset_bank_config(bank_id)
+
+            # Return updated config (should match defaults now)
+            config_dict = await app.state.memory._config_resolver.get_bank_config(bank_id, request_context)
+            bank_overrides = await app.state.memory._config_resolver._load_bank_config(bank_id)
+
+            return BankConfigResponse(bank_id=bank_id, config=config_dict, overrides=bank_overrides)
+        except (AuthenticationError, HTTPException):
+            raise
+        except Exception as e:
+            import traceback
+
+            error_detail = f"{str(e)}\n\nTraceback:\n{traceback.format_exc()}"
+            logger.error(f"Error in DELETE /v1/default/banks/{bank_id}/config: {error_detail}")
+            raise HTTPException(status_code=500, detail=str(e))
+
     @app.post(
         "/v1/default/banks/{bank_id}/consolidate",
         response_model=ConsolidationResponse,

hindsight-api/hindsight_api/api/mcp.py

@@ -8,7 +8,11 @@ from contextvars import ContextVar
 from fastmcp import FastMCP
 
 from hindsight_api import MemoryEngine
+from hindsight_api.engine.memory_engine import _current_schema
+from hindsight_api.extensions import MCPExtension, load_extension
+from hindsight_api.extensions.tenant import AuthenticationError
 from hindsight_api.mcp_tools import MCPToolsConfig, register_mcp_tools
+from hindsight_api.models import RequestContext
 
 # Configure logging from HINDSIGHT_API_LOG_LEVEL environment variable
 _log_level_str = os.environ.get("HINDSIGHT_API_LOG_LEVEL", "info").lower()
@@ -29,7 +33,8 @@ logger = logging.getLogger(__name__)
 # Default bank_id from environment variable
 DEFAULT_BANK_ID = os.environ.get("HINDSIGHT_MCP_BANK_ID", "default")
 
-# MCP authentication token (optional - if set, Bearer token auth is required)
+# Legacy MCP authentication token (for backwards compatibility)
+# If set, this token is checked first before TenantExtension auth
 MCP_AUTH_TOKEN = os.environ.get("HINDSIGHT_API_MCP_AUTH_TOKEN")
 
 # Context variable to hold the current bank_id
@@ -38,6 +43,10 @@ _current_bank_id: ContextVar[str | None] = ContextVar("current_bank_id", default
 # Context variable to hold the current API key (for tenant auth propagation)
 _current_api_key: ContextVar[str | None] = ContextVar("current_api_key", default=None)
 
+# Context variables for tenant_id and api_key_id (set by authenticate, used by usage metering)
+_current_tenant_id: ContextVar[str | None] = ContextVar("current_tenant_id", default=None)
+_current_api_key_id: ContextVar[str | None] = ContextVar("current_api_key_id", default=None)
+
 
 def get_current_bank_id() -> str | None:
     """Get the current bank_id from context."""
@@ -49,12 +58,24 @@ def get_current_api_key() -> str | None:
     return _current_api_key.get()
 
 
-def create_mcp_server(memory: MemoryEngine) -> FastMCP:
+def get_current_tenant_id() -> str | None:
+    """Get the current tenant_id from context."""
+    return _current_tenant_id.get()
+
+
+def get_current_api_key_id() -> str | None:
+    """Get the current api_key_id from context."""
+    return _current_api_key_id.get()
+
+
+def create_mcp_server(memory: MemoryEngine, multi_bank: bool = True) -> FastMCP:
     """
     Create and configure the Hindsight MCP server.
 
     Args:
         memory: MemoryEngine instance (required)
+        multi_bank: If True, expose all tools with bank_id parameters (default).
+                   If False, only expose bank-scoped tools without bank_id parameters.
 
     Returns:
         Configured FastMCP server instance with stateless_http enabled
@@ -66,40 +87,133 @@ def create_mcp_server(memory: MemoryEngine) -> FastMCP:
     config = MCPToolsConfig(
         bank_id_resolver=get_current_bank_id,
         api_key_resolver=get_current_api_key,  # Propagate API key for tenant auth
-        include_bank_id_param=True,  # HTTP MCP supports multi-bank via parameter
-        tools=None,  # All tools
+        tenant_id_resolver=get_current_tenant_id,  # Propagate tenant_id for usage metering
+        api_key_id_resolver=get_current_api_key_id,  # Propagate api_key_id for usage metering
+        include_bank_id_param=multi_bank,
+        tools=None
+        if multi_bank
+        else {
+            "retain",
+            "recall",
+            "reflect",
+            "list_mental_models",
+            "get_mental_model",
+            "create_mental_model",
+            "update_mental_model",
+            "delete_mental_model",
+            "refresh_mental_model",
+        },  # Scoped tools for single-bank mode (excludes bank management: list_banks, create_bank)
         retain_fire_and_forget=False,  # HTTP MCP supports sync/async modes
     )
 
     register_mcp_tools(mcp, memory, config)
 
+    # Load and register additional tools from MCP extension if configured
+    mcp_extension = load_extension("MCP", MCPExtension)
+    if mcp_extension:
+        logger.info(f"Loading MCP extension: {mcp_extension.__class__.__name__}")
+        mcp_extension.register_tools(mcp, memory)
+
+    # Make all tools tolerant of extra arguments from LLMs (e.g., "explanation")
+    _make_tools_tolerant(mcp)
+
     return mcp
 
 
+def _make_tools_tolerant(mcp: FastMCP) -> None:
+    """Wrap all tool run methods to strip unknown arguments before validation.
+
+    LLMs frequently add extra fields like "explanation" or "reasoning" to tool calls.
+    FastMCP's Pydantic TypeAdapter rejects these with "Unexpected keyword argument".
+    This wraps each tool's run() to filter arguments to only known parameters.
+    """
+    try:
+        for name, tool in mcp._tool_manager._tools.items():
+            if hasattr(tool, "parameters") and tool.parameters:
+                allowed = set(tool.parameters.get("properties", {}).keys())
+                original_run = tool.run
+
+                async def _tolerant_run(arguments, _allowed=allowed, _orig=original_run):
+                    extra_keys = set(arguments.keys()) - _allowed
+                    if extra_keys:
+                        logger.debug(f"Stripping unknown arguments from tool call: {extra_keys}")
+                        arguments = {k: v for k, v in arguments.items() if k in _allowed}
+                    return await _orig(arguments)
+
+                # FunctionTool is a Pydantic model with extra='forbid', so use
+                # object.__setattr__ to bypass Pydantic's setter validation.
+                object.__setattr__(tool, "run", _tolerant_run)
+    except (AttributeError, KeyError) as e:
+        logger.warning(f"Could not make tools tolerant of extra arguments: {e}")
+
+
 class MCPMiddleware:
-    """ASGI middleware that handles authentication and extracts bank_id from header or path.
+    """ASGI middleware that intercepts MCP requests and routes to appropriate MCP server.
+
+    This middleware wraps the main FastAPI app and intercepts requests matching the
+    configured prefix (default: /mcp). Non-MCP requests pass through to the inner app.
 
     Authentication:
-        If HINDSIGHT_API_MCP_AUTH_TOKEN is set, all requests must include a valid
-        Authorization header with Bearer token or direct token matching the configured value.
+        1. If HINDSIGHT_API_MCP_AUTH_TOKEN is set (legacy), validates against that token
+        2. Otherwise, uses TenantExtension.authenticate_mcp() from the MemoryEngine
+           - DefaultTenantExtension: no auth required (local dev)
+           - ApiKeyTenantExtension: validates against env var
 
-    Bank ID can be provided via:
-    1. X-Bank-Id header (recommended for Claude Code)
-    2. URL path: /mcp/{bank_id}/
-    3. Environment variable HINDSIGHT_MCP_BANK_ID (fallback default)
+    Two modes based on URL structure:
 
-    For Claude Code, configure with:
+    1. Multi-bank mode (for /mcp/ root endpoint):
+       - Exposes all tools: retain, recall, reflect, list_banks, create_bank
+       - All tools include optional bank_id parameter for cross-bank operations
+       - Bank ID from: X-Bank-Id header or HINDSIGHT_MCP_BANK_ID env var
+
+    2. Single-bank mode (for /mcp/{bank_id}/ endpoints):
+       - Exposes bank-scoped tools only: retain, recall, reflect
+       - No bank_id parameter (comes from URL)
+       - No bank management tools (list_banks, create_bank)
+       - Recommended for agent isolation
+
+    Bank ID resolution priority:
+        1. URL path (e.g., /mcp/{bank_id}/) → single-bank mode
+        2. X-Bank-Id header → multi-bank mode
+        3. HINDSIGHT_MCP_BANK_ID env var → multi-bank mode (default: "default")
+
+    Examples:
+        # Single-bank mode (recommended for agent isolation)
+        claude mcp add --transport http my-agent http://localhost:8888/mcp/my-agent-bank/ \\
+            --header "Authorization: Bearer <token>"
+
+        # Multi-bank mode (for cross-bank operations)
         claude mcp add --transport http hindsight http://localhost:8888/mcp \\
             --header "X-Bank-Id: my-bank" --header "Authorization: Bearer <token>"
     """
 
-    def __init__(self, app, memory: MemoryEngine):
+    def __init__(
+        self,
+        app,
+        memory: MemoryEngine,
+        prefix: str = "/mcp",
+        multi_bank_app=None,
+        single_bank_app=None,
+        multi_bank_server=None,
+        single_bank_server=None,
+    ):
         self.app = app
+        self.prefix = prefix
         self.memory = memory
-        self.mcp_server = create_mcp_server(memory)
-        self.mcp_app = self.mcp_server.http_app(path="/")
-        # Expose the lifespan for the parent app to chain
-        self.lifespan = self.mcp_app.lifespan_handler if hasattr(self.mcp_app, "lifespan_handler") else None
+        self.tenant_extension = memory._tenant_extension
+
+        if multi_bank_app and single_bank_app:
+            # Pre-created servers (used when called via add_middleware from create_app)
+            self.multi_bank_app = multi_bank_app
+            self.single_bank_app = single_bank_app
+            self.multi_bank_server = multi_bank_server
+            self.single_bank_server = single_bank_server
+        else:
+            # Create servers internally (for direct construction / tests)
+            self.multi_bank_server = create_mcp_server(memory, multi_bank=True)
+            self.multi_bank_app = self.multi_bank_server.http_app(path="/")
+            self.single_bank_server = create_mcp_server(memory, multi_bank=False)
+            self.single_bank_app = self.single_bank_server.http_app(path="/")
 
     def _get_header(self, scope: dict, name: str) -> str | None:
         """Extract a header value from ASGI scope."""
@@ -111,9 +225,20 @@ class MCPMiddleware:
 
     async def __call__(self, scope, receive, send):
         if scope["type"] != "http":
-            await self.mcp_app(scope, receive, send)
+            await self.app(scope, receive, send)
             return
 
+        path = scope.get("path", "")
+
+        # Check if this is an MCP request (matches prefix)
+        if not (path == self.prefix or path.startswith(self.prefix + "/")):
+            # Not an MCP request — pass through to the inner app
+            await self.app(scope, receive, send)
+            return
+
+        # Strip prefix from path
+        path = path[len(self.prefix) :] or "/"
+
         # Extract auth token from header (for tenant auth propagation)
         auth_header = self._get_header(scope, "Authorization")
         auth_token: str | None = None
@@ -121,62 +246,92 @@ class MCPMiddleware:
             # Support both "Bearer <token>" and direct token
             auth_token = auth_header[7:].strip() if auth_header.startswith("Bearer ") else auth_header.strip()
 
-        # Authenticate if MCP_AUTH_TOKEN is configured
+        # Authenticate: check legacy MCP_AUTH_TOKEN first, then TenantExtension
+        tenant_context = None
+        auth_tenant_id: str | None = None
+        auth_api_key_id: str | None = None
         if MCP_AUTH_TOKEN:
+            # Legacy authentication mode - validate against static token
             if not auth_token:
                 await self._send_error(send, 401, "Authorization header required")
                 return
             if auth_token != MCP_AUTH_TOKEN:
                 await self._send_error(send, 401, "Invalid authentication token")
                 return
+            # Legacy mode doesn't use tenant schemas
+            tenant_context = None
+        else:
+            # Use TenantExtension.authenticate_mcp() for auth
+            try:
+                auth_context = RequestContext(api_key=auth_token)
+                tenant_context = await self.tenant_extension.authenticate_mcp(auth_context)
+                # Capture tenant_id and api_key_id set by authenticate() for usage metering
+                auth_tenant_id = auth_context.tenant_id
+                auth_api_key_id = auth_context.api_key_id
+            except AuthenticationError as e:
+                await self._send_error(send, 401, str(e))
+                return
 
-        path = scope.get("path", "")
+        # Set schema from tenant context so downstream DB queries use the correct schema
+        schema_token = (
+            _current_schema.set(tenant_context.schema_name) if tenant_context and tenant_context.schema_name else None
+        )
 
-        # Strip any mount prefix (e.g., /mcp) that FastAPI might not have stripped
-        root_path = scope.get("root_path", "")
-        if root_path and path.startswith(root_path):
-            path = path[len(root_path) :] or "/"
-
-        # Also handle case where mount path wasn't stripped (e.g., /mcp/...)
-        if path.startswith("/mcp/"):
-            path = path[4:]  # Remove /mcp prefix
-        elif path == "/mcp":
-            path = "/"
-
-        # Try to get bank_id from header first (for Claude Code compatibility)
-        bank_id = self._get_header(scope, "X-Bank-Id")
-
-        # MCP endpoint paths that should not be treated as bank_ids
-        MCP_ENDPOINTS = {"sse", "messages"}
-
-        # If no header, try to extract from path: /{bank_id}/...
+        # Resolve bank_id: path takes priority over header.
+        # Path = user's explicit connection endpoint (e.g., /mcp/my-bank/).
+        # X-Bank-Id header = per-request override for multi-bank mode only.
+        bank_id = None
+        bank_id_from_path = False
         new_path = path
-        if not bank_id and path.startswith("/") and len(path) > 1:
+
+        # First, try to extract from path: /{bank_id}/...
+        if path.startswith("/") and len(path) > 1:
             parts = path[1:].split("/", 1)
-            # Don't treat MCP endpoints as bank_ids
-            if parts[0] and parts[0] not in MCP_ENDPOINTS:
-                # First segment looks like a bank_id
+            if parts[0]:
                 bank_id = parts[0]
+                bank_id_from_path = True
                 new_path = "/" + parts[1] if len(parts) > 1 else "/"
 
+        # If no path-based bank_id, try X-Bank-Id header (multi-bank mode)
+        if not bank_id:
+            bank_id = self._get_header(scope, "X-Bank-Id")
+
         # Fall back to default bank_id
         if not bank_id:
             bank_id = DEFAULT_BANK_ID
             logger.debug(f"Using default bank_id: {bank_id}")
 
-        # Set bank_id and api_key context
+        # Select the appropriate MCP app based on how bank_id was provided:
+        # - Path-based bank_id → single-bank app (no bank_id param, scoped tools)
+        # - Header/env bank_id → multi-bank app (bank_id param, all tools)
+        target_app = self.single_bank_app if bank_id_from_path else self.multi_bank_app
+
+        # Set bank_id, api_key, tenant_id, and api_key_id context
         bank_id_token = _current_bank_id.set(bank_id)
         # Store the auth token for tenant extension to validate
         api_key_token = _current_api_key.set(auth_token) if auth_token else None
+        # Store tenant_id and api_key_id from authentication for usage metering
+        tenant_id_token = _current_tenant_id.set(auth_tenant_id) if auth_tenant_id else None
+        api_key_id_token = _current_api_key_id.set(auth_api_key_id) if auth_api_key_id else None
         try:
             new_scope = scope.copy()
             new_scope["path"] = new_path
             # Clear root_path since we're passing directly to the app
             new_scope["root_path"] = ""
 
-            # Wrap send to rewrite the SSE endpoint URL to include bank_id if using path-based routing
+            # Wrap send to rewrite the SSE endpoint URL to include bank_id if using path-based routing.
+            # Only rewrite SSE (text/event-stream) responses to avoid corrupting tool results
+            # that might contain the literal string "data: /messages".
+            is_sse_response = False
+
             async def send_wrapper(message):
-                if message["type"] == "http.response.body":
+                nonlocal is_sse_response
+                if message["type"] == "http.response.start":
+                    for header_name, header_value in message.get("headers", []):
+                        if header_name == b"content-type" and b"text/event-stream" in header_value:
+                            is_sse_response = True
+                            break
+                if message["type"] == "http.response.body" and bank_id_from_path and is_sse_response:
                     body = message.get("body", b"")
                     if body and b"/messages" in body:
                         # Rewrite /messages to /{bank_id}/messages in SSE endpoint event
@@ -184,11 +339,17 @@ class MCPMiddleware:
                         message = {**message, "body": body}
                 await send(message)
 
-            await self.mcp_app(new_scope, receive, send_wrapper)
+            await target_app(new_scope, receive, send_wrapper)
         finally:
             _current_bank_id.reset(bank_id_token)
             if api_key_token is not None:
                 _current_api_key.reset(api_key_token)
+            if tenant_id_token is not None:
+                _current_tenant_id.reset(tenant_id_token)
+            if api_key_id_token is not None:
+                _current_api_key_id.reset(api_key_id_token)
+            if schema_token is not None:
+                _current_schema.reset(schema_token)
 
     async def _send_error(self, send, status: int, message: str):
         """Send an error response."""
@@ -208,23 +369,19 @@ class MCPMiddleware:
         )
 
 
-def create_mcp_app(memory: MemoryEngine):
-    """
-    Create an ASGI app that handles MCP requests.
+def create_mcp_servers(memory: MemoryEngine):
+    """Create multi-bank and single-bank MCP servers and their Starlette apps.
 
-    Authentication:
-        Set HINDSIGHT_API_MCP_AUTH_TOKEN to require Bearer token authentication.
-        If not set, MCP endpoint is open (for local development).
-
-    Bank ID can be provided via:
-    1. X-Bank-Id header: claude mcp add --transport http hindsight http://localhost:8888/mcp --header "X-Bank-Id: my-bank"
-    2. URL path: /mcp/{bank_id}/
-    3. Environment variable HINDSIGHT_MCP_BANK_ID (fallback, default: "default")
-
-    Args:
-        memory: MemoryEngine instance
+    Returns the servers and apps separately so lifespans can be chained before
+    the middleware wraps the main app.
 
     Returns:
-        ASGI application
+        Tuple of (multi_bank_server, single_bank_server, multi_bank_app, single_bank_app)
     """
-    return MCPMiddleware(None, memory)
+    multi_bank_server = create_mcp_server(memory, multi_bank=True)
+    multi_bank_app = multi_bank_server.http_app(path="/")
+
+    single_bank_server = create_mcp_server(memory, multi_bank=False)
+    single_bank_app = single_bank_server.http_app(path="/")
+
+    return multi_bank_server, single_bank_server, multi_bank_app, single_bank_app

hindsight-api/hindsight_api/banner.py

@@ -4,6 +4,8 @@ Banner display for Hindsight API startup.
 Shows the logo and tagline with gradient colors.
 """
 
+from .utils import mask_network_location
+
 # Gradient colors: #0074d9 -> #009296
 GRADIENT_START = (0, 116, 217)  # #0074d9
 GRADIENT_END = (0, 146, 150)  # #009296
@@ -84,16 +86,20 @@ def print_startup_info(
     reranker_provider: str,
     mcp_enabled: bool = False,
     version: str | None = None,
+    vector_extension: str | None = None,
+    text_search_extension: str | None = None,
 ):
     """Print styled startup information."""
     print(color_start("Starting Hindsight API..."))
     if version:
         print(f"  {dim('Version:')} {color(f'v{version}', 0.1)}")
     print(f"  {dim('URL:')} {color(f'http://{host}:{port}', 0.2)}")
-    print(f"  {dim('Database:')} {color(database_url, 0.4)}")
+    print(f"  {dim('Database:')} {color(mask_network_location(database_url), 0.4)}")
     print(f"  {dim('LLM:')} {color(f'{llm_provider} / {llm_model}', 0.6)}")
     print(f"  {dim('Embeddings:')} {color(embeddings_provider, 0.8)}")
     print(f"  {dim('Reranker:')} {color(reranker_provider, 1.0)}")
+    extensions = f"{vector_extension or 'default'} (vector) / {text_search_extension or 'default'} (text)"
+    print(f"  {dim('Extensions:')} {color(extensions, 0.4)}")
     if mcp_enabled:
         print(f"  {dim('MCP:')} {color_end('enabled at /mcp')}")
     print()

hindsight-api/hindsight_api/config.py

@@ -8,8 +8,9 @@ import json
 import logging
 import os
 import sys
-from dataclasses import dataclass
+from dataclasses import dataclass, field, fields
 from datetime import datetime, timezone
+from typing import Any
 
 from dotenv import find_dotenv, load_dotenv
 
@@ -18,6 +19,103 @@ load_dotenv(find_dotenv(usecwd=True), override=True)
 
 logger = logging.getLogger(__name__)
 
+
+class ConfigFieldAccessError(AttributeError):
+    """Raised when trying to access a bank-configurable field from global config."""
+
+    pass
+
+
+class StaticConfigProxy:
+    """
+    Proxy that wraps HindsightConfig and only allows access to static (non-configurable) fields.
+
+    Raises ConfigFieldAccessError when trying to access configurable fields that vary per-bank.
+    Forces developers to use get_resolved_config(bank_id, context) for bank-specific settings.
+    """
+
+    def __init__(self, config: "HindsightConfig"):
+        object.__setattr__(self, "_config", config)
+        object.__setattr__(self, "_configurable_fields", HindsightConfig.get_configurable_fields())
+
+    def __getattribute__(self, name: str):
+        if name.startswith("_"):
+            return object.__getattribute__(self, name)
+
+        configurable_fields = object.__getattribute__(self, "_configurable_fields")
+        if name in configurable_fields:
+            raise ConfigFieldAccessError(
+                f"Field '{name}' is bank-configurable and cannot be accessed from global config. "
+                f"Use ConfigResolver.resolve_full_config(bank_id, context) to get bank-specific config. "
+                f"This prevents accidentally using global defaults when bank-specific overrides exist."
+            )
+
+        config = object.__getattribute__(self, "_config")
+        return getattr(config, name)
+
+    def __setattr__(self, name: str, value):
+        raise AttributeError("Config is read-only. Modifications must go through ConfigResolver.")
+
+
+# Configuration field markers for hierarchical configuration
+def hierarchical(default_value):
+    """
+    Mark a config field as hierarchical (can be overridden per-tenant/bank).
+
+    Hierarchical fields can be customized at the tenant or bank level via database
+    configuration. Examples: LLM settings, retention parameters, retrieval settings.
+    """
+    return field(default=default_value, metadata={"hierarchical": True})
+
+
+def static(default_value):
+    """
+    Mark a config field as static (server-level only, cannot be overridden).
+
+    Static fields are infrastructure-level settings that affect the entire server
+    and cannot vary per tenant or bank. Examples: database URL, API port, worker settings.
+    """
+    return field(default=default_value, metadata={"hierarchical": False})
+
+
+# Configuration key normalization utilities
+def normalize_config_key(key: str) -> str:
+    """
+    Convert environment variable format to Python field name format.
+
+    Examples:
+        HINDSIGHT_API_LLM_PROVIDER -> llm_provider
+        LLM_MODEL -> llm_model
+        llm_model -> llm_model (already normalized)
+
+    Args:
+        key: Environment variable name or Python field name
+
+    Returns:
+        Normalized Python field name (lowercase snake_case)
+    """
+    if key.startswith("HINDSIGHT_API_"):
+        key = key[len("HINDSIGHT_API_") :]
+    return key.lower()
+
+
+def normalize_config_dict(config: dict[str, Any]) -> dict[str, Any]:
+    """
+    Normalize all keys in a config dict to Python field names.
+
+    Allows users to provide config overrides in either format:
+    - Python field format: {"llm_provider": "openai"}
+    - Env var format: {"HINDSIGHT_API_LLM_PROVIDER": "openai"}
+
+    Args:
+        config: Dict with env var or Python field names as keys
+
+    Returns:
+        Dict with all keys normalized to Python field names
+    """
+    return {normalize_config_key(k): v for k, v in config.items()}
+
+
 # Environment variable names
 ENV_DATABASE_URL = "HINDSIGHT_API_DATABASE_URL"
 ENV_DATABASE_SCHEMA = "HINDSIGHT_API_DATABASE_SCHEMA"
@@ -66,27 +164,48 @@ ENV_CONSOLIDATION_LLM_TIMEOUT = "HINDSIGHT_API_CONSOLIDATION_LLM_TIMEOUT"
 ENV_EMBEDDINGS_PROVIDER = "HINDSIGHT_API_EMBEDDINGS_PROVIDER"
 ENV_EMBEDDINGS_LOCAL_MODEL = "HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL"
 ENV_EMBEDDINGS_LOCAL_FORCE_CPU = "HINDSIGHT_API_EMBEDDINGS_LOCAL_FORCE_CPU"
+ENV_EMBEDDINGS_LOCAL_TRUST_REMOTE_CODE = "HINDSIGHT_API_EMBEDDINGS_LOCAL_TRUST_REMOTE_CODE"
 ENV_EMBEDDINGS_TEI_URL = "HINDSIGHT_API_EMBEDDINGS_TEI_URL"
 ENV_EMBEDDINGS_OPENAI_API_KEY = "HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY"
 ENV_EMBEDDINGS_OPENAI_MODEL = "HINDSIGHT_API_EMBEDDINGS_OPENAI_MODEL"
 ENV_EMBEDDINGS_OPENAI_BASE_URL = "HINDSIGHT_API_EMBEDDINGS_OPENAI_BASE_URL"
 
-ENV_COHERE_API_KEY = "HINDSIGHT_API_COHERE_API_KEY"
+# Cohere configuration (separate for embeddings and reranker)
+ENV_EMBEDDINGS_COHERE_API_KEY = "HINDSIGHT_API_EMBEDDINGS_COHERE_API_KEY"
 ENV_EMBEDDINGS_COHERE_MODEL = "HINDSIGHT_API_EMBEDDINGS_COHERE_MODEL"
 ENV_EMBEDDINGS_COHERE_BASE_URL = "HINDSIGHT_API_EMBEDDINGS_COHERE_BASE_URL"
+ENV_RERANKER_COHERE_API_KEY = "HINDSIGHT_API_RERANKER_COHERE_API_KEY"
 ENV_RERANKER_COHERE_MODEL = "HINDSIGHT_API_RERANKER_COHERE_MODEL"
 ENV_RERANKER_COHERE_BASE_URL = "HINDSIGHT_API_RERANKER_COHERE_BASE_URL"
 
-# LiteLLM gateway configuration (for embeddings and reranker via LiteLLM proxy)
+# Deprecated: Legacy shared Cohere API key (for backward compatibility)
+ENV_COHERE_API_KEY = "HINDSIGHT_API_COHERE_API_KEY"
+
+# LiteLLM configuration (separate for embeddings and reranker)
+ENV_EMBEDDINGS_LITELLM_API_BASE = "HINDSIGHT_API_EMBEDDINGS_LITELLM_API_BASE"
+ENV_EMBEDDINGS_LITELLM_API_KEY = "HINDSIGHT_API_EMBEDDINGS_LITELLM_API_KEY"
+ENV_EMBEDDINGS_LITELLM_MODEL = "HINDSIGHT_API_EMBEDDINGS_LITELLM_MODEL"
+ENV_RERANKER_LITELLM_API_BASE = "HINDSIGHT_API_RERANKER_LITELLM_API_BASE"
+ENV_RERANKER_LITELLM_API_KEY = "HINDSIGHT_API_RERANKER_LITELLM_API_KEY"
+ENV_RERANKER_LITELLM_MODEL = "HINDSIGHT_API_RERANKER_LITELLM_MODEL"
+
+# LiteLLM SDK configuration (direct API access, no proxy needed)
+ENV_EMBEDDINGS_LITELLM_SDK_API_KEY = "HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_API_KEY"
+ENV_EMBEDDINGS_LITELLM_SDK_MODEL = "HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_MODEL"
+ENV_EMBEDDINGS_LITELLM_SDK_API_BASE = "HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_API_BASE"
+ENV_RERANKER_LITELLM_SDK_API_KEY = "HINDSIGHT_API_RERANKER_LITELLM_SDK_API_KEY"
+ENV_RERANKER_LITELLM_SDK_MODEL = "HINDSIGHT_API_RERANKER_LITELLM_SDK_MODEL"
+ENV_RERANKER_LITELLM_SDK_API_BASE = "HINDSIGHT_API_RERANKER_LITELLM_SDK_API_BASE"
+
+# Deprecated: Legacy shared LiteLLM config (for backward compatibility)
 ENV_LITELLM_API_BASE = "HINDSIGHT_API_LITELLM_API_BASE"
 ENV_LITELLM_API_KEY = "HINDSIGHT_API_LITELLM_API_KEY"
-ENV_EMBEDDINGS_LITELLM_MODEL = "HINDSIGHT_API_EMBEDDINGS_LITELLM_MODEL"
-ENV_RERANKER_LITELLM_MODEL = "HINDSIGHT_API_RERANKER_LITELLM_MODEL"
 
 ENV_RERANKER_PROVIDER = "HINDSIGHT_API_RERANKER_PROVIDER"
 ENV_RERANKER_LOCAL_MODEL = "HINDSIGHT_API_RERANKER_LOCAL_MODEL"
 ENV_RERANKER_LOCAL_FORCE_CPU = "HINDSIGHT_API_RERANKER_LOCAL_FORCE_CPU"
 ENV_RERANKER_LOCAL_MAX_CONCURRENT = "HINDSIGHT_API_RERANKER_LOCAL_MAX_CONCURRENT"
+ENV_RERANKER_LOCAL_TRUST_REMOTE_CODE = "HINDSIGHT_API_RERANKER_LOCAL_TRUST_REMOTE_CODE"
 ENV_RERANKER_TEI_URL = "HINDSIGHT_API_RERANKER_TEI_URL"
 ENV_RERANKER_TEI_BATCH_SIZE = "HINDSIGHT_API_RERANKER_TEI_BATCH_SIZE"
 ENV_RERANKER_TEI_MAX_CONCURRENT = "HINDSIGHT_API_RERANKER_TEI_MAX_CONCURRENT"
@@ -94,12 +213,17 @@ ENV_RERANKER_MAX_CANDIDATES = "HINDSIGHT_API_RERANKER_MAX_CANDIDATES"
 ENV_RERANKER_FLASHRANK_MODEL = "HINDSIGHT_API_RERANKER_FLASHRANK_MODEL"
 ENV_RERANKER_FLASHRANK_CACHE_DIR = "HINDSIGHT_API_RERANKER_FLASHRANK_CACHE_DIR"
 
+ENV_VECTOR_EXTENSION = "HINDSIGHT_API_VECTOR_EXTENSION"
+ENV_TEXT_SEARCH_EXTENSION = "HINDSIGHT_API_TEXT_SEARCH_EXTENSION"
+
 ENV_HOST = "HINDSIGHT_API_HOST"
 ENV_PORT = "HINDSIGHT_API_PORT"
+ENV_BASE_PATH = "HINDSIGHT_API_BASE_PATH"
 ENV_LOG_LEVEL = "HINDSIGHT_API_LOG_LEVEL"
 ENV_LOG_FORMAT = "HINDSIGHT_API_LOG_FORMAT"
 ENV_WORKERS = "HINDSIGHT_API_WORKERS"
 ENV_MCP_ENABLED = "HINDSIGHT_API_MCP_ENABLED"
+ENV_ENABLE_BANK_CONFIG_API = "HINDSIGHT_API_ENABLE_BANK_CONFIG_API"
 ENV_GRAPH_RETRIEVER = "HINDSIGHT_API_GRAPH_RETRIEVER"
 ENV_MPFP_TOP_K_NEIGHBORS = "HINDSIGHT_API_MPFP_TOP_K_NEIGHBORS"
 ENV_RECALL_MAX_CONCURRENT = "HINDSIGHT_API_RECALL_MAX_CONCURRENT"
@@ -108,6 +232,13 @@ ENV_MCP_LOCAL_BANK_ID = "HINDSIGHT_API_MCP_LOCAL_BANK_ID"
 ENV_MCP_INSTRUCTIONS = "HINDSIGHT_API_MCP_INSTRUCTIONS"
 ENV_MENTAL_MODEL_REFRESH_CONCURRENCY = "HINDSIGHT_API_MENTAL_MODEL_REFRESH_CONCURRENCY"
 
+# OpenTelemetry tracing configuration
+ENV_OTEL_TRACES_ENABLED = "HINDSIGHT_API_OTEL_TRACES_ENABLED"
+ENV_OTEL_EXPORTER_OTLP_ENDPOINT = "HINDSIGHT_API_OTEL_EXPORTER_OTLP_ENDPOINT"
+ENV_OTEL_EXPORTER_OTLP_HEADERS = "HINDSIGHT_API_OTEL_EXPORTER_OTLP_HEADERS"
+ENV_OTEL_SERVICE_NAME = "HINDSIGHT_API_OTEL_SERVICE_NAME"
+ENV_OTEL_DEPLOYMENT_ENVIRONMENT = "HINDSIGHT_API_OTEL_DEPLOYMENT_ENVIRONMENT"
+
 # Vertex AI configuration
 ENV_LLM_VERTEXAI_PROJECT_ID = "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID"
 ENV_LLM_VERTEXAI_REGION = "HINDSIGHT_API_LLM_VERTEXAI_REGION"
@@ -183,6 +314,7 @@ DEFAULT_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY = None  # Optional, uses ADC if not set
 DEFAULT_EMBEDDINGS_PROVIDER = "local"
 DEFAULT_EMBEDDINGS_LOCAL_MODEL = "BAAI/bge-small-en-v1.5"
 DEFAULT_EMBEDDINGS_LOCAL_FORCE_CPU = False  # Force CPU mode for local embeddings (avoids MPS/XPC issues on macOS)
+DEFAULT_EMBEDDINGS_LOCAL_TRUST_REMOTE_CODE = False  # Security: disabled by default, required for some models
 DEFAULT_EMBEDDINGS_OPENAI_MODEL = "text-embedding-3-small"
 DEFAULT_EMBEDDING_DIMENSION = 384
 
@@ -190,6 +322,9 @@ DEFAULT_RERANKER_PROVIDER = "local"
 DEFAULT_RERANKER_LOCAL_MODEL = "cross-encoder/ms-marco-MiniLM-L-6-v2"
 DEFAULT_RERANKER_LOCAL_FORCE_CPU = False  # Force CPU mode for local reranker (avoids MPS/XPC issues on macOS)
 DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT = 4  # Limit concurrent CPU-bound reranking to prevent thrashing
+DEFAULT_RERANKER_LOCAL_TRUST_REMOTE_CODE = (
+    False  # Security: disabled by default, required for some models like jina-reranker-v2
+)
 DEFAULT_RERANKER_TEI_BATCH_SIZE = 128
 DEFAULT_RERANKER_TEI_MAX_CONCURRENT = 8
 DEFAULT_RERANKER_MAX_CANDIDATES = 300
@@ -199,17 +334,29 @@ DEFAULT_RERANKER_FLASHRANK_CACHE_DIR = None  # Use default cache directory
 DEFAULT_EMBEDDINGS_COHERE_MODEL = "embed-english-v3.0"
 DEFAULT_RERANKER_COHERE_MODEL = "rerank-english-v3.0"
 
+# Vector extension (pgvector, vchord, or pgvectorscale)
+DEFAULT_VECTOR_EXTENSION = "pgvector"  # Options: "pgvector", "vchord", "pgvectorscale"
+
+# Text search extension (native PostgreSQL, vchord BM25, or Timescale pg_textsearch)
+DEFAULT_TEXT_SEARCH_EXTENSION = "native"  # Options: "native", "vchord", "pg_textsearch"
+
 # LiteLLM defaults
 DEFAULT_LITELLM_API_BASE = "http://localhost:4000"
 DEFAULT_EMBEDDINGS_LITELLM_MODEL = "text-embedding-3-small"
 DEFAULT_RERANKER_LITELLM_MODEL = "cohere/rerank-english-v3.0"
 
+# LiteLLM SDK defaults
+DEFAULT_EMBEDDINGS_LITELLM_SDK_MODEL = "cohere/embed-english-v3.0"
+DEFAULT_RERANKER_LITELLM_SDK_MODEL = "cohere/rerank-english-v3.0"
+
 DEFAULT_HOST = "0.0.0.0"
 DEFAULT_PORT = 8888
+DEFAULT_BASE_PATH = ""  # Empty string = root path
 DEFAULT_LOG_LEVEL = "info"
 DEFAULT_LOG_FORMAT = "text"  # Options: "text", "json"
 DEFAULT_WORKERS = 1
 DEFAULT_MCP_ENABLED = True
+DEFAULT_ENABLE_BANK_CONFIG_API = False  # Disabled by default for security
 DEFAULT_GRAPH_RETRIEVER = "link_expansion"  # Options: "link_expansion", "mpfp", "bfs"
 DEFAULT_MPFP_TOP_K_NEIGHBORS = 20  # Fan-out limit per node in MPFP graph traversal
 DEFAULT_RECALL_MAX_CONCURRENT = 32  # Max concurrent recall operations per worker
@@ -251,6 +398,11 @@ DEFAULT_WORKER_CONSOLIDATION_MAX_SLOTS = 2  # Max concurrent consolidation tasks
 # Reflect agent settings
 DEFAULT_REFLECT_MAX_ITERATIONS = 10  # Max tool call iterations before forcing response
 
+# OpenTelemetry tracing configuration
+DEFAULT_OTEL_TRACES_ENABLED = False  # Disabled by default for backward compatibility
+DEFAULT_OTEL_SERVICE_NAME = "hindsight-api"
+DEFAULT_OTEL_DEPLOYMENT_ENVIRONMENT = "development"
+
 # Default MCP tool descriptions (can be customized via env vars)
 DEFAULT_MCP_RETAIN_DESCRIPTION = """Store important information to long-term memory.
 
@@ -329,6 +481,8 @@ class HindsightConfig:
     # Database
     database_url: str
     database_schema: str
+    vector_extension: str  # "pgvector" or "vchord"
+    text_search_extension: str  # "native" or "vchord"
 
     # LLM (default, used as fallback for per-operation config)
     llm_provider: str
@@ -381,27 +535,47 @@ class HindsightConfig:
     embeddings_provider: str
     embeddings_local_model: str
     embeddings_local_force_cpu: bool
+    embeddings_local_trust_remote_code: bool
     embeddings_tei_url: str | None
     embeddings_openai_base_url: str | None
+    embeddings_cohere_api_key: str | None
+    embeddings_cohere_model: str
     embeddings_cohere_base_url: str | None
+    embeddings_litellm_api_base: str
+    embeddings_litellm_api_key: str | None
+    embeddings_litellm_model: str
+    embeddings_litellm_sdk_api_key: str | None
+    embeddings_litellm_sdk_model: str
+    embeddings_litellm_sdk_api_base: str | None
 
     # Reranker
     reranker_provider: str
     reranker_local_model: str
     reranker_local_force_cpu: bool
     reranker_local_max_concurrent: int
+    reranker_local_trust_remote_code: bool
     reranker_tei_url: str | None
     reranker_tei_batch_size: int
     reranker_tei_max_concurrent: int
     reranker_max_candidates: int
+    reranker_cohere_api_key: str | None
+    reranker_cohere_model: str
     reranker_cohere_base_url: str | None
+    reranker_litellm_api_base: str
+    reranker_litellm_api_key: str | None
+    reranker_litellm_model: str
+    reranker_litellm_sdk_api_key: str | None
+    reranker_litellm_sdk_model: str
+    reranker_litellm_sdk_api_base: str | None
 
     # Server
     host: str
     port: int
+    base_path: str
     log_level: str
     log_format: str
     mcp_enabled: bool
+    enable_bank_config_api: bool
 
     # Recall
     graph_retriever: str
@@ -447,6 +621,129 @@ class HindsightConfig:
     # Reflect agent settings
     reflect_max_iterations: int
 
+    # OpenTelemetry tracing configuration
+    otel_traces_enabled: bool
+    otel_exporter_otlp_endpoint: str | None
+    otel_exporter_otlp_headers: str | None
+    otel_service_name: str
+    otel_deployment_environment: str
+
+    # Class-level sets for configuration categorization
+
+    # CREDENTIAL_FIELDS: Never exposed via API, never configurable per-tenant/bank
+    _CREDENTIAL_FIELDS = {
+        # API Keys
+        "llm_api_key",
+        "retain_llm_api_key",
+        "reflect_llm_api_key",
+        "consolidation_llm_api_key",
+        # Base URLs (could expose infrastructure)
+        "llm_base_url",
+        "retain_llm_base_url",
+        "reflect_llm_base_url",
+        "consolidation_llm_base_url",
+        "embeddings_tei_base_url",
+        "reranker_tei_base_url",
+        "reranker_cohere_base_url",
+        # Service Account Keys
+        "llm_vertexai_service_account_key",
+    }
+
+    # CONFIGURABLE_FIELDS: Safe behavioral settings that can be customized per-tenant/bank
+    # These fields are manually tagged as safe to expose and modify.
+    # Excludes credentials, infrastructure config, provider/model selection, and performance tuning.
+    _CONFIGURABLE_FIELDS = {
+        # Retention settings (behavioral)
+        "retain_chunk_size",
+        "retain_extraction_mode",
+        "retain_custom_instructions",
+        # Consolidation settings
+        "enable_observations",
+    }
+
+    @classmethod
+    def get_configurable_fields(cls) -> set[str]:
+        """
+        Get set of field names that are configurable per-tenant/bank via API.
+
+        Configurable fields are manually tagged behavioral settings that are safe
+        to expose and modify (e.g., retain_chunk_size, custom_instructions).
+        Excludes credentials, infrastructure config, and provider/model selection.
+
+        Returns:
+            Set of configurable field names
+        """
+        return cls._CONFIGURABLE_FIELDS.copy()
+
+    @classmethod
+    def get_credential_fields(cls) -> set[str]:
+        """
+        Get set of field names that are credentials (NEVER exposed via API).
+
+        Credential fields include API keys, base URLs, and service account keys.
+        These must never be returned in API responses or accepted in updates.
+
+        Returns:
+            Set of credential field names
+        """
+        return cls._CREDENTIAL_FIELDS.copy()
+
+    @classmethod
+    def get_hierarchical_fields(cls) -> set[str]:
+        """
+        DEPRECATED: Use get_configurable_fields() instead.
+
+        Kept for backward compatibility during migration.
+        """
+        return cls.get_configurable_fields()
+
+    @classmethod
+    def get_static_fields(cls) -> set[str]:
+        """
+        Get set of field names that are static (server-level only).
+
+        Static fields are infrastructure-level settings that cannot vary
+        per tenant or bank. These include database config, API port, worker settings, etc.
+        Also includes credential fields which are never configurable.
+
+        Returns:
+            Set of static field names
+        """
+        # Get all field names from dataclass
+        all_fields = {f.name for f in fields(cls)}
+        # Static fields = all fields - configurable fields
+        return all_fields - cls._CONFIGURABLE_FIELDS
+
+    def validate(self) -> None:
+        """Validate configuration values and raise errors for invalid combinations."""
+        # Validate vector_extension
+        valid_extensions = ("pgvector", "vchord", "pgvectorscale")
+        if self.vector_extension not in valid_extensions:
+            raise ValueError(
+                f"Invalid vector_extension: {self.vector_extension}. Must be one of: {', '.join(valid_extensions)}"
+            )
+
+        # Validate text_search_extension
+        valid_text_search = ("native", "vchord", "pg_textsearch")
+        if self.text_search_extension not in valid_text_search:
+            raise ValueError(
+                f"Invalid text_search_extension: {self.text_search_extension}. Must be one of: {', '.join(valid_text_search)}"
+            )
+
+        # RETAIN_MAX_COMPLETION_TOKENS must be greater than RETAIN_CHUNK_SIZE
+        # to ensure the LLM has enough output capacity to extract facts from chunks
+        if self.retain_max_completion_tokens <= self.retain_chunk_size:
+            raise ValueError(
+                f"Invalid configuration: HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS "
+                f"({self.retain_max_completion_tokens}) must be greater than "
+                f"HINDSIGHT_API_RETAIN_CHUNK_SIZE ({self.retain_chunk_size}). "
+                f"\n\nYou have two options to fix this:"
+                f"\n  1. Increase HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS to a value > {self.retain_chunk_size}"
+                f"\n  2. Use a model that supports at least {self.retain_max_completion_tokens} output tokens"
+                f"\n     (current model: {self.retain_llm_model or self.llm_model}, "
+                f"provider: {self.retain_llm_provider or self.llm_provider})"
+            )
+
     @classmethod
     def from_env(cls) -> "HindsightConfig":
         """Create configuration from environment variables."""
@@ -454,10 +751,12 @@ class HindsightConfig:
         llm_provider = os.getenv(ENV_LLM_PROVIDER, DEFAULT_LLM_PROVIDER)
         llm_model = os.getenv(ENV_LLM_MODEL) or _get_default_model_for_provider(llm_provider)
 
-        return cls(
+        config = cls(
             # Database
             database_url=os.getenv(ENV_DATABASE_URL, DEFAULT_DATABASE_URL),
             database_schema=os.getenv(ENV_DATABASE_SCHEMA, DEFAULT_DATABASE_SCHEMA),
+            vector_extension=os.getenv(ENV_VECTOR_EXTENSION, DEFAULT_VECTOR_EXTENSION).lower(),
+            text_search_extension=os.getenv(ENV_TEXT_SEARCH_EXTENSION, DEFAULT_TEXT_SEARCH_EXTENSION).lower(),
             # LLM
             llm_provider=llm_provider,
             llm_api_key=os.getenv(ENV_LLM_API_KEY),
@@ -551,9 +850,27 @@ class HindsightConfig:
                 ENV_EMBEDDINGS_LOCAL_FORCE_CPU, str(DEFAULT_EMBEDDINGS_LOCAL_FORCE_CPU)
             ).lower()
             in ("true", "1"),
+            embeddings_local_trust_remote_code=os.getenv(
+                ENV_EMBEDDINGS_LOCAL_TRUST_REMOTE_CODE, str(DEFAULT_EMBEDDINGS_LOCAL_TRUST_REMOTE_CODE)
+            ).lower()
+            in ("true", "1"),
             embeddings_tei_url=os.getenv(ENV_EMBEDDINGS_TEI_URL),
             embeddings_openai_base_url=os.getenv(ENV_EMBEDDINGS_OPENAI_BASE_URL) or None,
+            # Cohere embeddings (with backward-compatible fallback to shared API key)
+            embeddings_cohere_api_key=os.getenv(ENV_EMBEDDINGS_COHERE_API_KEY) or os.getenv(ENV_COHERE_API_KEY),
+            embeddings_cohere_model=os.getenv(ENV_EMBEDDINGS_COHERE_MODEL, DEFAULT_EMBEDDINGS_COHERE_MODEL),
             embeddings_cohere_base_url=os.getenv(ENV_EMBEDDINGS_COHERE_BASE_URL) or None,
+            # LiteLLM embeddings (with backward-compatible fallback to shared config)
+            embeddings_litellm_api_base=os.getenv(ENV_EMBEDDINGS_LITELLM_API_BASE)
+            or os.getenv(ENV_LITELLM_API_BASE, DEFAULT_LITELLM_API_BASE),
+            embeddings_litellm_api_key=os.getenv(ENV_EMBEDDINGS_LITELLM_API_KEY) or os.getenv(ENV_LITELLM_API_KEY),
+            embeddings_litellm_model=os.getenv(ENV_EMBEDDINGS_LITELLM_MODEL, DEFAULT_EMBEDDINGS_LITELLM_MODEL),
+            # LiteLLM SDK embeddings (direct API access)
+            embeddings_litellm_sdk_api_key=os.getenv(ENV_EMBEDDINGS_LITELLM_SDK_API_KEY),
+            embeddings_litellm_sdk_model=os.getenv(
+                ENV_EMBEDDINGS_LITELLM_SDK_MODEL, DEFAULT_EMBEDDINGS_LITELLM_SDK_MODEL
+            ),
+            embeddings_litellm_sdk_api_base=os.getenv(ENV_EMBEDDINGS_LITELLM_SDK_API_BASE) or None,
             # Reranker
             reranker_provider=os.getenv(ENV_RERANKER_PROVIDER, DEFAULT_RERANKER_PROVIDER),
             reranker_local_model=os.getenv(ENV_RERANKER_LOCAL_MODEL, DEFAULT_RERANKER_LOCAL_MODEL),
@@ -564,19 +881,38 @@ class HindsightConfig:
             reranker_local_max_concurrent=int(
                 os.getenv(ENV_RERANKER_LOCAL_MAX_CONCURRENT, str(DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT))
             ),
+            reranker_local_trust_remote_code=os.getenv(
+                ENV_RERANKER_LOCAL_TRUST_REMOTE_CODE, str(DEFAULT_RERANKER_LOCAL_TRUST_REMOTE_CODE)
+            ).lower()
+            in ("true", "1"),
             reranker_tei_url=os.getenv(ENV_RERANKER_TEI_URL),
             reranker_tei_batch_size=int(os.getenv(ENV_RERANKER_TEI_BATCH_SIZE, str(DEFAULT_RERANKER_TEI_BATCH_SIZE))),
             reranker_tei_max_concurrent=int(
                 os.getenv(ENV_RERANKER_TEI_MAX_CONCURRENT, str(DEFAULT_RERANKER_TEI_MAX_CONCURRENT))
             ),
             reranker_max_candidates=int(os.getenv(ENV_RERANKER_MAX_CANDIDATES, str(DEFAULT_RERANKER_MAX_CANDIDATES))),
+            # Cohere reranker (with backward-compatible fallback to shared API key)
+            reranker_cohere_api_key=os.getenv(ENV_RERANKER_COHERE_API_KEY) or os.getenv(ENV_COHERE_API_KEY),
+            reranker_cohere_model=os.getenv(ENV_RERANKER_COHERE_MODEL, DEFAULT_RERANKER_COHERE_MODEL),
             reranker_cohere_base_url=os.getenv(ENV_RERANKER_COHERE_BASE_URL) or None,
+            # LiteLLM reranker (with backward-compatible fallback to shared config)
+            reranker_litellm_api_base=os.getenv(ENV_RERANKER_LITELLM_API_BASE)
+            or os.getenv(ENV_LITELLM_API_BASE, DEFAULT_LITELLM_API_BASE),
+            reranker_litellm_api_key=os.getenv(ENV_RERANKER_LITELLM_API_KEY) or os.getenv(ENV_LITELLM_API_KEY),
+            reranker_litellm_model=os.getenv(ENV_RERANKER_LITELLM_MODEL, DEFAULT_RERANKER_LITELLM_MODEL),
+            # LiteLLM SDK reranker (direct API access)
+            reranker_litellm_sdk_api_key=os.getenv(ENV_RERANKER_LITELLM_SDK_API_KEY),
+            reranker_litellm_sdk_model=os.getenv(ENV_RERANKER_LITELLM_SDK_MODEL, DEFAULT_RERANKER_LITELLM_SDK_MODEL),
+            reranker_litellm_sdk_api_base=os.getenv(ENV_RERANKER_LITELLM_SDK_API_BASE) or None,
             # Server
             host=os.getenv(ENV_HOST, DEFAULT_HOST),
             port=int(os.getenv(ENV_PORT, DEFAULT_PORT)),
+            base_path=os.getenv(ENV_BASE_PATH, DEFAULT_BASE_PATH),
             log_level=os.getenv(ENV_LOG_LEVEL, DEFAULT_LOG_LEVEL),
             log_format=os.getenv(ENV_LOG_FORMAT, DEFAULT_LOG_FORMAT).lower(),
             mcp_enabled=os.getenv(ENV_MCP_ENABLED, str(DEFAULT_MCP_ENABLED)).lower() == "true",
+            enable_bank_config_api=os.getenv(ENV_ENABLE_BANK_CONFIG_API, str(DEFAULT_ENABLE_BANK_CONFIG_API)).lower()
+            == "true",
             # Recall
             graph_retriever=os.getenv(ENV_GRAPH_RETRIEVER, DEFAULT_GRAPH_RETRIEVER),
             mpfp_top_k_neighbors=int(os.getenv(ENV_MPFP_TOP_K_NEIGHBORS, str(DEFAULT_MPFP_TOP_K_NEIGHBORS))),
@@ -630,7 +966,16 @@ class HindsightConfig:
             ),
             # Reflect agent settings
             reflect_max_iterations=int(os.getenv(ENV_REFLECT_MAX_ITERATIONS, str(DEFAULT_REFLECT_MAX_ITERATIONS))),
+            # OpenTelemetry tracing configuration
+            otel_traces_enabled=os.getenv(ENV_OTEL_TRACES_ENABLED, str(DEFAULT_OTEL_TRACES_ENABLED)).lower()
+            in ("true", "1", "yes"),
+            otel_exporter_otlp_endpoint=os.getenv(ENV_OTEL_EXPORTER_OTLP_ENDPOINT) or None,
+            otel_exporter_otlp_headers=os.getenv(ENV_OTEL_EXPORTER_OTLP_HEADERS) or None,
+            otel_service_name=os.getenv(ENV_OTEL_SERVICE_NAME, DEFAULT_OTEL_SERVICE_NAME),
+            otel_deployment_environment=os.getenv(ENV_OTEL_DEPLOYMENT_ENVIRONMENT, DEFAULT_OTEL_DEPLOYMENT_ENVIRONMENT),
         )
+        config.validate()
+        return config
 
     def get_llm_base_url(self) -> str:
         """Get the LLM base URL, with provider-specific defaults."""
@@ -708,8 +1053,35 @@ class HindsightConfig:
 _config_cache: HindsightConfig | None = None
 
 
-def get_config() -> HindsightConfig:
-    """Get the cached configuration, loading from environment on first call."""
+def get_config() -> StaticConfigProxy:
+    """
+    Get global configuration with ONLY static (non-configurable) fields accessible.
+
+    This returns a proxy that prevents access to bank-configurable fields
+    (like enable_observations, retain_chunk_size, etc.).
+
+    For bank-specific configuration, use:
+        config_resolver.resolve_full_config(bank_id, context)
+
+    This design prevents accidentally using global defaults when bank-specific
+    overrides exist.
+
+    Returns:
+        StaticConfigProxy that only exposes static infrastructure fields
+
+    Raises:
+        ConfigFieldAccessError: If you try to access a bank-configurable field
+    """
+    return StaticConfigProxy(_get_raw_config())
+
+
+def _get_raw_config() -> HindsightConfig:
+    """
+    Get raw config (internal use only).
+
+    INTERNAL USE ONLY. Do not use this directly in application code.
+    Use get_config() for static fields or ConfigResolver.resolve_full_config() for bank-specific config.
+    """
     global _config_cache
     if _config_cache is None:
         _config_cache = HindsightConfig.from_env()

hindsight-api/hindsight_api/config_resolver.py

@@ -0,0 +1,274 @@
+"""
+Configuration resolution with hierarchical overrides.
+
+Resolves config values through the hierarchy:
+  Global (env vars) → Tenant config (via extension) → Bank config (database)
+
+Config values are resolved on every request to ensure consistency across
+multiple API servers.
+"""
+
+import json
+import logging
+from dataclasses import asdict
+from typing import Any
+
+import asyncpg
+
+from hindsight_api.config import HindsightConfig, _get_raw_config, normalize_config_dict
+from hindsight_api.extensions.tenant import TenantExtension
+from hindsight_api.models import RequestContext
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigResolver:
+    """Resolves hierarchical configuration with tenant/bank overrides."""
+
+    def __init__(self, pool: asyncpg.Pool, tenant_extension: TenantExtension | None = None):
+        """
+        Initialize config resolver.
+
+        Args:
+            pool: Database connection pool
+            tenant_extension: Optional tenant extension for tenant-level config and permissions
+        """
+        self.pool = pool
+        self.tenant_extension = tenant_extension
+        self._global_config = _get_raw_config()
+        self._configurable_fields = HindsightConfig.get_configurable_fields()
+        self._credential_fields = HindsightConfig.get_credential_fields()
+
+    async def resolve_full_config(self, bank_id: str, context: RequestContext | None = None) -> HindsightConfig:
+        """
+        Resolve full HindsightConfig for a bank with hierarchical overrides applied.
+
+        This is for INTERNAL USE ONLY. Returns the complete config object with all fields
+        including credentials and static fields. Use get_bank_config() for API responses.
+
+        Resolution order:
+        1. Global config (from environment variables)
+        2. Tenant config overrides (from TenantExtension.get_tenant_config())
+        3. Bank config overrides (from banks.config JSONB)
+
+        Args:
+            bank_id: Bank identifier
+            context: Request context for tenant config resolution
+
+        Returns:
+            Complete HindsightConfig with hierarchical overrides applied
+        """
+        # Start with global config (all fields)
+        config_dict = asdict(self._global_config)
+
+        # Load tenant config overrides (if tenant extension available)
+        if self.tenant_extension and context:
+            try:
+                tenant_overrides = await self.tenant_extension.get_tenant_config(context)
+                if tenant_overrides:
+                    # Normalize keys and filter to configurable fields only
+                    normalized_tenant = normalize_config_dict(tenant_overrides)
+                    configurable_tenant = {k: v for k, v in normalized_tenant.items() if k in self._configurable_fields}
+                    config_dict.update(configurable_tenant)
+                    logger.debug(
+                        f"Applied tenant config overrides for bank {bank_id}: {list(configurable_tenant.keys())}"
+                    )
+            except Exception as e:
+                logger.warning(f"Failed to load tenant config for bank {bank_id}: {e}")
+
+        # Load bank config overrides
+        bank_overrides = await self._load_bank_config(bank_id)
+        if bank_overrides:
+            config_dict.update(bank_overrides)
+            logger.debug(f"Applied bank config overrides for bank {bank_id}: {list(bank_overrides.keys())}")
+
+        # Return full config object (dataclass doesn't have __init__ that accepts kwargs, so we update the object)
+        # Create a new config instance by copying the global config and updating fields
+        resolved_config = HindsightConfig(**config_dict)
+        return resolved_config
+
+    async def get_bank_config(self, bank_id: str, context: RequestContext | None = None) -> dict[str, Any]:
+        """
+        Get fully resolved config for a bank (filtered by permissions).
+
+        Resolution order:
+        1. Global config (from environment variables)
+        2. Tenant config overrides (from TenantExtension.get_tenant_config())
+        3. Bank config overrides (from banks.config JSONB)
+
+        Note: Config is resolved on every call (not cached) to ensure consistency
+        across multiple API servers.
+
+        SECURITY:
+        - Only returns configurable fields (excludes static/infrastructure fields)
+        - Filters out ALL credential fields (API keys, base URLs, etc.)
+        - Further filtered by tenant/bank permissions if extension provides them
+
+        Args:
+            bank_id: Bank identifier
+            context: Request context for tenant config resolution and permissions
+
+        Returns:
+            Dict of allowed configurable fields only (never includes credentials or static fields)
+        """
+        # Resolve full config with all hierarchical overrides
+        resolved_config = await self.resolve_full_config(bank_id, context)
+        config_dict = asdict(resolved_config)
+
+        # SECURITY: Filter to only configurable fields (exclude static/infrastructure)
+        filtered = {k: v for k, v in config_dict.items() if k in self._configurable_fields}
+
+        # SECURITY: Remove ALL credential fields (API keys, base URLs, etc.)
+        filtered = {k: v for k, v in filtered.items() if k not in self._credential_fields}
+
+        # PERMISSIONS: Further filter based on tenant/bank permissions
+        if self.tenant_extension and context:
+            try:
+                allowed_fields = await self.tenant_extension.get_allowed_config_fields(context, bank_id)
+                if allowed_fields is not None:  # None means "allow all"
+                    filtered = {k: v for k, v in filtered.items() if k in allowed_fields}
+                    logger.debug(
+                        f"Applied permission filter for bank {bank_id}: allowed={len(allowed_fields)} fields, "
+                        f"returned={len(filtered)} fields"
+                    )
+            except Exception as e:
+                logger.warning(f"Failed to load permissions for bank {bank_id}: {e}")
+
+        return filtered
+
+    async def _load_bank_config(self, bank_id: str) -> dict[str, Any]:
+        """
+        Load bank config overrides from banks.config JSONB column.
+
+        Args:
+            bank_id: Bank identifier
+
+        Returns:
+            Dict of config overrides (only configurable fields, normalized keys)
+        """
+        try:
+            async with self.pool.acquire() as conn:
+                row = await conn.fetchrow(
+                    """
+                    SELECT config FROM banks WHERE bank_id = $1
+                    """,
+                    bank_id,
+                )
+
+                if row and row["config"]:
+                    config_data = row["config"]
+
+                    # Handle case where JSONB is returned as JSON string
+                    if isinstance(config_data, str):
+                        config_data = json.loads(config_data)
+
+                    # Normalize keys (handle both env var format and Python field format)
+                    normalized = normalize_config_dict(config_data)
+
+                    # Only return overrides for configurable fields
+                    return {k: v for k, v in normalized.items() if k in self._configurable_fields}
+        except Exception as e:
+            logger.error(f"Failed to load bank config for {bank_id}: {e}")
+
+        return {}
+
+    async def update_bank_config(
+        self, bank_id: str, updates: dict[str, Any], context: RequestContext | None = None
+    ) -> None:
+        """
+        Update bank configuration overrides (with permission checking).
+
+        Args:
+            bank_id: Bank identifier
+            updates: Dict of config field names to new values.
+                    Keys can be in env var format (HINDSIGHT_API_LLM_PROVIDER)
+                    or Python field format (llm_provider).
+                    Only configurable fields are allowed.
+            context: Request context for permission checking
+
+        Raises:
+            ValueError: If attempting to override invalid/disallowed fields
+        """
+        # Normalize keys
+        normalized_updates = normalize_config_dict(updates)
+
+        # SECURITY: Reject credential fields explicitly
+        credential_attempts = set(normalized_updates.keys()) & self._credential_fields
+        if credential_attempts:
+            raise ValueError(
+                f"Cannot set credential fields via API: {sorted(credential_attempts)}. "
+                f"Credentials (API keys, base URLs) must be set at server level only."
+            )
+
+        # Validate all fields are configurable
+        invalid_fields = set(normalized_updates.keys()) - self._configurable_fields
+        if invalid_fields:
+            static_fields = HindsightConfig.get_static_fields()
+            invalid_static = invalid_fields & static_fields
+            if invalid_static:
+                raise ValueError(
+                    f"Cannot override static (server-level) fields: {sorted(invalid_static)}. "
+                    f"Only configurable fields can be overridden per-bank. "
+                    f"Configurable fields include: {sorted(list(self._configurable_fields)[:10])}... "
+                    f"(total: {len(self._configurable_fields)} fields)"
+                )
+            else:
+                raise ValueError(
+                    f"Unknown configuration fields: {sorted(invalid_fields)}. "
+                    f"Valid configurable fields: {sorted(list(self._configurable_fields)[:10])}..."
+                )
+
+        # PERMISSIONS: Check tenant/bank permissions
+        if self.tenant_extension and context:
+            try:
+                allowed_fields = await self.tenant_extension.get_allowed_config_fields(context, bank_id)
+                if allowed_fields is not None:  # None means "allow all"
+                    disallowed = set(normalized_updates.keys()) - allowed_fields
+                    if disallowed:
+                        raise ValueError(
+                            f"Not allowed to modify fields: {sorted(disallowed)}. "
+                            f"Your permissions allow: {sorted(list(allowed_fields)[:10])}..."
+                            if allowed_fields
+                            else "Not allowed to modify fields: {sorted(disallowed)}. "
+                            "Your permissions do not allow any config modifications."
+                        )
+            except ValueError:
+                raise  # Re-raise permission errors
+            except Exception as e:
+                logger.warning(f"Failed to check permissions for bank {bank_id}: {e}")
+                # Continue without permission check (fail open for backward compatibility)
+
+        # Merge with existing config (JSONB || operator)
+        async with self.pool.acquire() as conn:
+            await conn.execute(
+                """
+                UPDATE banks
+                SET config = config || $1::jsonb,
+                    updated_at = now()
+                WHERE bank_id = $2
+                """,
+                json.dumps(normalized_updates),
+                bank_id,
+            )
+
+        logger.info(f"Updated bank config for {bank_id}: {list(normalized_updates.keys())}")
+
+    async def reset_bank_config(self, bank_id: str) -> None:
+        """
+        Reset bank configuration to defaults (remove all overrides).
+
+        Args:
+            bank_id: Bank identifier
+        """
+        async with self.pool.acquire() as conn:
+            await conn.execute(
+                """
+                UPDATE banks
+                SET config = '{}'::jsonb,
+                    updated_at = now()
+                WHERE bank_id = $1
+                """,
+                bank_id,
+            )
+
+        logger.info(f"Reset bank config for {bank_id} to defaults")

hindsight-api/hindsight_api/engine/consolidation/consolidator.py

@@ -18,6 +18,7 @@ import uuid
 from datetime import datetime, timezone
 from typing import TYPE_CHECKING, Any
 
+from ...config import get_config
 from ..memory_engine import fq_table
 from ..retain import embedding_utils
 from .prompts import (
@@ -82,9 +83,8 @@ async def run_consolidation_job(
     Returns:
         Dict with consolidation results
     """
-    from ...config import get_config
-
-    config = get_config()
+    # Resolve bank-specific config with hierarchical overrides
+    config = await memory_engine._config_resolver.resolve_full_config(bank_id, request_context)
     perf = ConsolidationPerfLog(bank_id)
     max_memories_per_batch = config.consolidation_batch_size
 
@@ -426,94 +426,109 @@ async def _process_memory(
     Returns:
         Dict with action summary: created/updated/merged counts
     """
+    from ...tracing import get_tracer, is_tracing_enabled
+
     fact_text = memory["text"]
     memory_id = memory["id"]
     fact_tags = memory.get("tags") or []
 
-    # Find related observations using the full recall system
-    # SECURITY: Pass tags to ensure observations don't leak across security boundaries
-    t0 = time.time()
-    related_observations = await _find_related_observations(
-        conn=conn,
-        memory_engine=memory_engine,
-        bank_id=bank_id,
-        query=fact_text,
-        request_context=request_context,
-        tags=fact_tags,  # Pass source memory's tags for security
-    )
-    if perf:
-        perf.record_timing("recall", time.time() - t0)
+    # Create parent span for this memory's consolidation
+    tracer = get_tracer()
+    if is_tracing_enabled():
+        consolidation_span = tracer.start_span("hindsight.consolidation")
+        consolidation_span.set_attribute("hindsight.memory_id", str(memory_id))
+        consolidation_span.set_attribute("hindsight.bank_id", bank_id)
+    else:
+        consolidation_span = None
 
-    # Single LLM call handles ALL cases (with or without existing observations)
-    # Note: Tags are NOT passed to LLM - they are handled algorithmically
-    t0 = time.time()
-    actions = await _consolidate_with_llm(
-        memory_engine=memory_engine,
-        fact_text=fact_text,
-        observations=related_observations,  # Can be empty list
-        mission=mission,
-    )
-    if perf:
-        perf.record_timing("llm", time.time() - t0)
+    try:
+        # Find related observations using the full recall system
+        # SECURITY: Pass tags to ensure observations don't leak across security boundaries
+        t0 = time.time()
+        related_observations = await _find_related_observations(
+            conn=conn,
+            memory_engine=memory_engine,
+            bank_id=bank_id,
+            query=fact_text,
+            request_context=request_context,
+            tags=fact_tags,  # Pass source memory's tags for security
+        )
+        if perf:
+            perf.record_timing("recall", time.time() - t0)
 
-    if not actions:
-        # LLM returned empty array - fact is purely ephemeral, skip
-        return {"action": "skipped", "reason": "no_durable_knowledge"}
+        # Single LLM call handles ALL cases (with or without existing observations)
+        # Note: Tags are NOT passed to LLM - they are handled algorithmically
+        t0 = time.time()
+        actions = await _consolidate_with_llm(
+            memory_engine=memory_engine,
+            fact_text=fact_text,
+            observations=related_observations,  # Can be empty list
+            mission=mission,
+        )
+        if perf:
+            perf.record_timing("llm", time.time() - t0)
 
-    # Execute all actions and collect results
-    results = []
-    for action in actions:
-        action_type = action.get("action")
-        if action_type == "update":
-            result = await _execute_update_action(
-                conn=conn,
-                memory_engine=memory_engine,
-                bank_id=bank_id,
-                memory_id=memory_id,
-                action=action,
-                observations=related_observations,
-                source_fact_tags=fact_tags,  # Pass source fact's tags for security
-                source_occurred_start=memory.get("occurred_start"),
-                source_occurred_end=memory.get("occurred_end"),
-                source_mentioned_at=memory.get("mentioned_at"),
-                perf=perf,
-            )
-            results.append(result)
-        elif action_type == "create":
-            result = await _execute_create_action(
-                conn=conn,
-                memory_engine=memory_engine,
-                bank_id=bank_id,
-                memory_id=memory_id,
-                action=action,
-                source_fact_tags=fact_tags,  # Pass source fact's tags for security
-                event_date=memory.get("event_date"),
-                occurred_start=memory.get("occurred_start"),
-                occurred_end=memory.get("occurred_end"),
-                mentioned_at=memory.get("mentioned_at"),
-                perf=perf,
-            )
-            results.append(result)
+        if not actions:
+            # LLM returned empty array - fact is purely ephemeral, skip
+            return {"action": "skipped", "reason": "no_durable_knowledge"}
 
-    if not results:
-        # No valid actions executed
-        return {"action": "skipped", "reason": "no_valid_actions"}
+        # Execute all actions and collect results
+        results = []
+        for action in actions:
+            action_type = action.get("action")
+            if action_type == "update":
+                result = await _execute_update_action(
+                    conn=conn,
+                    memory_engine=memory_engine,
+                    bank_id=bank_id,
+                    memory_id=memory_id,
+                    action=action,
+                    observations=related_observations,
+                    source_fact_tags=fact_tags,  # Pass source fact's tags for security
+                    source_occurred_start=memory.get("occurred_start"),
+                    source_occurred_end=memory.get("occurred_end"),
+                    source_mentioned_at=memory.get("mentioned_at"),
+                    perf=perf,
+                )
+                results.append(result)
+            elif action_type == "create":
+                result = await _execute_create_action(
+                    conn=conn,
+                    memory_engine=memory_engine,
+                    bank_id=bank_id,
+                    memory_id=memory_id,
+                    action=action,
+                    source_fact_tags=fact_tags,  # Pass source fact's tags for security
+                    event_date=memory.get("event_date"),
+                    occurred_start=memory.get("occurred_start"),
+                    occurred_end=memory.get("occurred_end"),
+                    mentioned_at=memory.get("mentioned_at"),
+                    perf=perf,
+                )
+                results.append(result)
 
-    # Summarize results
-    created = sum(1 for r in results if r.get("action") == "created")
-    updated = sum(1 for r in results if r.get("action") == "updated")
-    merged = sum(1 for r in results if r.get("action") == "merged")
+        if not results:
+            # No valid actions executed
+            return {"action": "skipped", "reason": "no_valid_actions"}
 
-    if len(results) == 1:
-        return results[0]
+        # Summarize results
+        created = sum(1 for r in results if r.get("action") == "created")
+        updated = sum(1 for r in results if r.get("action") == "updated")
+        merged = sum(1 for r in results if r.get("action") == "merged")
 
-    return {
-        "action": "multiple",
-        "created": created,
-        "updated": updated,
-        "merged": merged,
-        "total_actions": len(results),
-    }
+        if len(results) == 1:
+            return results[0]
+
+        return {
+            "action": "multiple",
+            "created": created,
+            "updated": updated,
+            "merged": merged,
+            "total_actions": len(results),
+        }
+    finally:
+        if consolidation_span:
+            consolidation_span.end()
 
 
 async def _execute_update_action(
@@ -733,22 +748,37 @@ async def _find_related_observations(
     # Use recall to find related observations with token budget
     # max_tokens naturally limits how many observations are returned
     from ...config import get_config
+    from ...tracing import get_tracer, is_tracing_enabled
 
     config = get_config()
 
     # SECURITY: Use all_strict matching if tags provided to prevent cross-scope consolidation
     tags_match = "all_strict" if tags else "any"
 
-    recall_result = await memory_engine.recall_async(
-        bank_id=bank_id,
-        query=query,
-        max_tokens=config.consolidation_max_tokens,  # Token budget for observations (configurable)
-        fact_type=["observation"],  # Only retrieve observations
-        request_context=request_context,
-        tags=tags,  # Filter by source memory's tags
-        tags_match=tags_match,  # Use strict matching for security
-        _quiet=True,  # Suppress logging
-    )
+    # Create span for recall operation within consolidation
+    tracer = get_tracer()
+    if is_tracing_enabled():
+        recall_span = tracer.start_span("hindsight.consolidation_recall")
+        recall_span.set_attribute("hindsight.bank_id", bank_id)
+        recall_span.set_attribute("hindsight.query", query[:100])  # Truncate for brevity
+        recall_span.set_attribute("hindsight.fact_type", "observation")
+    else:
+        recall_span = None
+
+    try:
+        recall_result = await memory_engine.recall_async(
+            bank_id=bank_id,
+            query=query,
+            max_tokens=config.consolidation_max_tokens,  # Token budget for observations (configurable)
+            fact_type=["observation"],  # Only retrieve observations
+            request_context=request_context,
+            tags=tags,  # Filter by source memory's tags
+            tags_match=tags_match,  # Use strict matching for security
+            _quiet=True,  # Suppress logging
+        )
+    finally:
+        if recall_span:
+            recall_span.end()
 
     # If no observations returned, return empty list
     if not recall_result.results:
@@ -986,15 +1016,34 @@ async def _create_observation_directly(
 
     t0 = time.time()
     observation_id = uuid.uuid4()
+
+    # Query varies based on text search backend
+    config = get_config()
+    if config.text_search_extension == "vchord":
+        # VectorChord: manually tokenize and insert search_vector
+        query = f"""
+            INSERT INTO {fq_table("memory_units")} (
+                id, bank_id, text, fact_type, embedding, proof_count, source_memory_ids, history,
+                tags, event_date, occurred_start, occurred_end, mentioned_at, search_vector
+            )
+            VALUES ($1, $2, $3, 'observation', $4::vector, 1, $5, '[]'::jsonb, $6, $7, $8, $9, $10,
+                    tokenize($3, 'llmlingua2')::bm25_catalog.bm25vector)
+            RETURNING id
+        """
+    else:  # native or pg_textsearch
+        # Native PostgreSQL: search_vector is GENERATED ALWAYS, don't include it
+        # pg_textsearch: indexes operate on base columns directly, don't populate search_vector
+        query = f"""
+            INSERT INTO {fq_table("memory_units")} (
+                id, bank_id, text, fact_type, embedding, proof_count, source_memory_ids, history,
+                tags, event_date, occurred_start, occurred_end, mentioned_at
+            )
+            VALUES ($1, $2, $3, 'observation', $4::vector, 1, $5, '[]'::jsonb, $6, $7, $8, $9, $10)
+            RETURNING id
+        """
+
     row = await conn.fetchrow(
-        f"""
-        INSERT INTO {fq_table("memory_units")} (
-            id, bank_id, text, fact_type, embedding, proof_count, source_memory_ids, history,
-            tags, event_date, occurred_start, occurred_end, mentioned_at
-        )
-        VALUES ($1, $2, $3, 'observation', $4::vector, 1, $5, '[]'::jsonb, $6, $7, $8, $9, $10)
-        RETURNING id
-        """,
+        query,
         observation_id,
         bank_id,
         observation_text,

hindsight-api/hindsight_api/engine/consolidation/prompts.py

@@ -2,7 +2,7 @@
 
 CONSOLIDATION_SYSTEM_PROMPT = """You are a memory consolidation system. Your job is to convert facts into durable knowledge (observations) and merge with existing knowledge when appropriate.
 
-You must output ONLY valid JSON with no markdown formatting, no code blocks, and no additional text.
+You must output ONLY valid JSON with no markdown code blocks or additional text. However, the "text" field within each observation should use markdown formatting (headers, lists, bold, etc.) for clarity and readability.
 
 ## EXTRACT DURABLE KNOWLEDGE, NOT EPHEMERAL STATE
 Facts often describe events or actions. Extract the DURABLE KNOWLEDGE implied by the fact, not the transient state.
@@ -71,10 +71,15 @@ Instructions:
    - New topic → CREATE new observation
    - Purely ephemeral → return []
 
-Output JSON array of actions:
+Output JSON array of actions (the "text" field should use markdown formatting for structure):
 [
-  {{"action": "update", "learning_id": "uuid-from-observations", "text": "updated knowledge", "reason": "..."}},
-  {{"action": "create", "text": "new durable knowledge", "reason": "..."}}
+  {{"action": "update", "learning_id": "uuid-from-observations", "text": "## Updated Knowledge\n\n**Key point**: details here\n\n- Supporting detail 1\n- Supporting detail 2", "reason": "..."}},
+  {{"action": "create", "text": "## New Durable Knowledge\n\nDescription with **emphasis** and proper structure", "reason": "..."}}
 ]
 
-Return [] if fact contains no durable knowledge."""
+Return [] if fact contains no durable knowledge.
+
+IMPORTANT: Format the "text" field with markdown for better readability:
+- Use headers, lists, bold/italic, tables where appropriate
+- CRITICAL: Add blank lines before and after block elements (tables, code blocks, lists)
+- Ensure proper spacing for markdown to render correctly"""

hindsight-api/hindsight_api/engine/cross_encoder.py

@@ -21,23 +21,23 @@ from ..config import (
     DEFAULT_RERANKER_FLASHRANK_CACHE_DIR,
     DEFAULT_RERANKER_FLASHRANK_MODEL,
     DEFAULT_RERANKER_LITELLM_MODEL,
+    DEFAULT_RERANKER_LITELLM_SDK_MODEL,
     DEFAULT_RERANKER_LOCAL_FORCE_CPU,
     DEFAULT_RERANKER_LOCAL_MAX_CONCURRENT,
     DEFAULT_RERANKER_LOCAL_MODEL,
+    DEFAULT_RERANKER_LOCAL_TRUST_REMOTE_CODE,
     DEFAULT_RERANKER_PROVIDER,
     DEFAULT_RERANKER_TEI_BATCH_SIZE,
     DEFAULT_RERANKER_TEI_MAX_CONCURRENT,
-    ENV_COHERE_API_KEY,
-    ENV_LITELLM_API_BASE,
-    ENV_LITELLM_API_KEY,
-    ENV_RERANKER_COHERE_BASE_URL,
+    ENV_RERANKER_COHERE_API_KEY,
     ENV_RERANKER_COHERE_MODEL,
     ENV_RERANKER_FLASHRANK_CACHE_DIR,
     ENV_RERANKER_FLASHRANK_MODEL,
-    ENV_RERANKER_LITELLM_MODEL,
+    ENV_RERANKER_LITELLM_SDK_API_KEY,
     ENV_RERANKER_LOCAL_FORCE_CPU,
     ENV_RERANKER_LOCAL_MAX_CONCURRENT,
     ENV_RERANKER_LOCAL_MODEL,
+    ENV_RERANKER_LOCAL_TRUST_REMOTE_CODE,
     ENV_RERANKER_PROVIDER,
     ENV_RERANKER_TEI_BATCH_SIZE,
     ENV_RERANKER_TEI_MAX_CONCURRENT,
@@ -102,7 +102,13 @@ class LocalSTCrossEncoder(CrossEncoderModel):
     _executor: ThreadPoolExecutor | None = None
     _max_concurrent: int = 4  # Limit concurrent CPU-bound reranking calls
 
-    def __init__(self, model_name: str | None = None, max_concurrent: int = 4, force_cpu: bool = False):
+    def __init__(
+        self,
+        model_name: str | None = None,
+        max_concurrent: int = 4,
+        force_cpu: bool = False,
+        trust_remote_code: bool = False,
+    ):
         """
         Initialize local SentenceTransformers cross-encoder.
 
@@ -113,9 +119,13 @@ class LocalSTCrossEncoder(CrossEncoderModel):
                            Higher values may cause CPU thrashing under load.
             force_cpu: Force CPU mode (avoids MPS/XPC issues on macOS in daemon mode).
                       Default: False
+            trust_remote_code: Allow loading models with custom code (security risk).
+                              Required for some models like jina-reranker-v2-base-multilingual.
+                              Default: False (disabled for security)
         """
         self.model_name = model_name or DEFAULT_RERANKER_LOCAL_MODEL
         self.force_cpu = force_cpu
+        self.trust_remote_code = trust_remote_code
         self._model = None
         LocalSTCrossEncoder._max_concurrent = max_concurrent
 
@@ -181,6 +191,7 @@ class LocalSTCrossEncoder(CrossEncoderModel):
                     self.model_name,
                     device=device,
                     model_kwargs={"low_cpu_mem_usage": False},
+                    trust_remote_code=self.trust_remote_code,
                 )
             finally:
                 # Restore original logging level
@@ -819,6 +830,126 @@ class LiteLLMCrossEncoder(CrossEncoderModel):
         return all_scores
 
 
+class LiteLLMSDKCrossEncoder(CrossEncoderModel):
+    """
+    LiteLLM SDK cross-encoder for direct API integration.
+
+    Supports reranking via LiteLLM SDK without requiring a proxy server.
+    Supported providers: Cohere, DeepInfra, Together AI, HuggingFace, Jina AI, Voyage AI, AWS Bedrock.
+
+    Example model names:
+    - cohere/rerank-english-v3.0
+    - deepinfra/Qwen3-reranker-8B
+    - together_ai/Salesforce/Llama-Rank-V1
+    - huggingface/BAAI/bge-reranker-v2-m3
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str = DEFAULT_RERANKER_LITELLM_SDK_MODEL,
+        api_base: str | None = None,
+        timeout: float = 60.0,
+    ):
+        """
+        Initialize LiteLLM SDK cross-encoder client.
+
+        Args:
+            api_key: API key for the reranking provider
+            model: Model name with provider prefix (e.g., "deepinfra/Qwen3-reranker-8B")
+            api_base: Custom base URL for API (optional)
+            timeout: Request timeout in seconds (default: 60.0)
+        """
+        self.api_key = api_key
+        self.model = model
+        self.api_base = api_base
+        self.timeout = timeout
+        self._initialized = False
+        self._litellm = None  # Will be set during initialization
+
+    @property
+    def provider_name(self) -> str:
+        return "litellm-sdk"
+
+    async def initialize(self) -> None:
+        """Initialize the LiteLLM SDK client."""
+        if self._initialized:
+            return
+
+        try:
+            import litellm
+
+            self._litellm = litellm  # Store reference
+        except ImportError:
+            raise ImportError("litellm is required for LiteLLMSDKCrossEncoder. Install it with: pip install litellm")
+
+        api_base_msg = f" at {self.api_base}" if self.api_base else ""
+        logger.info(f"Reranker: initializing LiteLLM SDK provider with model {self.model}{api_base_msg}")
+
+        self._initialized = True
+        logger.info("Reranker: LiteLLM SDK provider initialized")
+
+    async def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
+        """
+        Score query-document pairs using the LiteLLM SDK.
+
+        Args:
+            pairs: List of (query, document) tuples to score
+
+        Returns:
+            List of relevance scores
+        """
+        if not self._initialized:
+            raise RuntimeError("Reranker not initialized. Call initialize() first.")
+
+        if not pairs:
+            return []
+
+        # Group pairs by query for efficient batching
+        # LiteLLM rerank expects one query with multiple documents
+        query_groups: dict[str, list[tuple[int, str]]] = {}
+        for idx, (query, text) in enumerate(pairs):
+            if query not in query_groups:
+                query_groups[query] = []
+            query_groups[query].append((idx, text))
+
+        all_scores = [0.0] * len(pairs)
+
+        for query, indexed_texts in query_groups.items():
+            texts = [text for _, text in indexed_texts]
+            indices = [idx for idx, _ in indexed_texts]
+
+            # Build kwargs for rerank call
+            rerank_kwargs = {
+                "model": self.model,
+                "query": query,
+                "documents": texts,
+                "api_key": self.api_key,
+            }
+            if self.api_base:
+                rerank_kwargs["api_base"] = self.api_base
+
+            response = await self._litellm.arerank(**rerank_kwargs)
+
+            # Map scores back to original positions
+            # Response format: RerankResponse with results list
+            # Each result is a TypedDict with "index" and "relevance_score"
+            if hasattr(response, "results") and response.results:
+                for result in response.results:
+                    # Results are TypedDicts, use dict-style access
+                    original_idx = result["index"]
+                    score = result.get("relevance_score", result.get("score", 0.0))
+                    all_scores[indices[original_idx]] = score
+            elif isinstance(response, list):
+                # Direct list of scores (unlikely but defensive)
+                for i, score in enumerate(response):
+                    all_scores[indices[i]] = score
+            else:
+                logger.warning(f"Unexpected response format from LiteLLM rerank: {type(response)}")
+
+        return all_scores
+
+
 def create_cross_encoder_from_env() -> CrossEncoderModel:
     """
     Create a CrossEncoderModel instance based on configuration.
@@ -847,26 +978,41 @@ def create_cross_encoder_from_env() -> CrossEncoderModel:
             model_name=config.reranker_local_model,
             max_concurrent=config.reranker_local_max_concurrent,
             force_cpu=config.reranker_local_force_cpu,
+            trust_remote_code=config.reranker_local_trust_remote_code,
         )
     elif provider == "cohere":
-        api_key = os.environ.get(ENV_COHERE_API_KEY)
+        api_key = config.reranker_cohere_api_key
         if not api_key:
-            raise ValueError(f"{ENV_COHERE_API_KEY} is required when {ENV_RERANKER_PROVIDER} is 'cohere'")
-        model = os.environ.get(ENV_RERANKER_COHERE_MODEL, DEFAULT_RERANKER_COHERE_MODEL)
-        base_url = os.environ.get(ENV_RERANKER_COHERE_BASE_URL) or None
-        return CohereCrossEncoder(api_key=api_key, model=model, base_url=base_url)
+            raise ValueError(f"{ENV_RERANKER_COHERE_API_KEY} is required when {ENV_RERANKER_PROVIDER} is 'cohere'")
+        return CohereCrossEncoder(
+            api_key=api_key,
+            model=config.reranker_cohere_model,
+            base_url=config.reranker_cohere_base_url,
+        )
     elif provider == "flashrank":
         model = os.environ.get(ENV_RERANKER_FLASHRANK_MODEL, DEFAULT_RERANKER_FLASHRANK_MODEL)
         cache_dir = os.environ.get(ENV_RERANKER_FLASHRANK_CACHE_DIR, DEFAULT_RERANKER_FLASHRANK_CACHE_DIR)
         return FlashRankCrossEncoder(model_name=model, cache_dir=cache_dir)
     elif provider == "litellm":
-        api_base = os.environ.get(ENV_LITELLM_API_BASE, DEFAULT_LITELLM_API_BASE)
-        api_key = os.environ.get(ENV_LITELLM_API_KEY)
-        model = os.environ.get(ENV_RERANKER_LITELLM_MODEL, DEFAULT_RERANKER_LITELLM_MODEL)
-        return LiteLLMCrossEncoder(api_base=api_base, api_key=api_key, model=model)
+        return LiteLLMCrossEncoder(
+            api_base=config.reranker_litellm_api_base,
+            api_key=config.reranker_litellm_api_key,
+            model=config.reranker_litellm_model,
+        )
+    elif provider == "litellm-sdk":
+        api_key = config.reranker_litellm_sdk_api_key
+        if not api_key:
+            raise ValueError(
+                f"{ENV_RERANKER_LITELLM_SDK_API_KEY} is required when {ENV_RERANKER_PROVIDER} is 'litellm-sdk'"
+            )
+        return LiteLLMSDKCrossEncoder(
+            api_key=api_key,
+            model=config.reranker_litellm_sdk_model,
+            api_base=config.reranker_litellm_sdk_api_base,
+        )
     elif provider == "rrf":
         return RRFPassthroughCrossEncoder()
     else:
         raise ValueError(
-            f"Unknown reranker provider: {provider}. Supported: 'local', 'tei', 'cohere', 'flashrank', 'litellm', 'rrf'"
+            f"Unknown reranker provider: {provider}. Supported: 'local', 'tei', 'cohere', 'flashrank', 'litellm', 'litellm-sdk', 'rrf'"
         )

hindsight-api/hindsight_api/engine/embeddings.py

@@ -19,24 +19,23 @@ import httpx
 from ..config import (
     DEFAULT_EMBEDDINGS_COHERE_MODEL,
     DEFAULT_EMBEDDINGS_LITELLM_MODEL,
+    DEFAULT_EMBEDDINGS_LITELLM_SDK_MODEL,
     DEFAULT_EMBEDDINGS_LOCAL_FORCE_CPU,
     DEFAULT_EMBEDDINGS_LOCAL_MODEL,
+    DEFAULT_EMBEDDINGS_LOCAL_TRUST_REMOTE_CODE,
     DEFAULT_EMBEDDINGS_OPENAI_MODEL,
     DEFAULT_EMBEDDINGS_PROVIDER,
     DEFAULT_LITELLM_API_BASE,
-    ENV_COHERE_API_KEY,
-    ENV_EMBEDDINGS_COHERE_BASE_URL,
-    ENV_EMBEDDINGS_COHERE_MODEL,
-    ENV_EMBEDDINGS_LITELLM_MODEL,
+    ENV_EMBEDDINGS_COHERE_API_KEY,
+    ENV_EMBEDDINGS_LITELLM_SDK_API_KEY,
     ENV_EMBEDDINGS_LOCAL_FORCE_CPU,
     ENV_EMBEDDINGS_LOCAL_MODEL,
+    ENV_EMBEDDINGS_LOCAL_TRUST_REMOTE_CODE,
     ENV_EMBEDDINGS_OPENAI_API_KEY,
     ENV_EMBEDDINGS_OPENAI_BASE_URL,
     ENV_EMBEDDINGS_OPENAI_MODEL,
     ENV_EMBEDDINGS_PROVIDER,
     ENV_EMBEDDINGS_TEI_URL,
-    ENV_LITELLM_API_BASE,
-    ENV_LITELLM_API_KEY,
     ENV_LLM_API_KEY,
 )
 
@@ -95,7 +94,7 @@ class LocalSTEmbeddings(Embeddings):
     The embedding dimension is auto-detected from the model.
     """
 
-    def __init__(self, model_name: str | None = None, force_cpu: bool = False):
+    def __init__(self, model_name: str | None = None, force_cpu: bool = False, trust_remote_code: bool = False):
         """
         Initialize local SentenceTransformers embeddings.
 
@@ -104,9 +103,13 @@ class LocalSTEmbeddings(Embeddings):
                        Default: BAAI/bge-small-en-v1.5
             force_cpu: Force CPU mode (avoids MPS/XPC issues on macOS in daemon mode).
                       Default: False
+            trust_remote_code: Allow loading models with custom code (security risk).
+                              Required for some models with custom architectures.
+                              Default: False (disabled for security)
         """
         self.model_name = model_name or DEFAULT_EMBEDDINGS_LOCAL_MODEL
         self.force_cpu = force_cpu
+        self.trust_remote_code = trust_remote_code
         self._model = None
         self._dimension: int | None = None
 
@@ -176,6 +179,7 @@ class LocalSTEmbeddings(Embeddings):
                     self.model_name,
                     device=device,
                     model_kwargs={"low_cpu_mem_usage": False},
+                    trust_remote_code=self.trust_remote_code,
                 )
             finally:
                 # Restore original logging level
@@ -718,6 +722,148 @@ class LiteLLMEmbeddings(Embeddings):
         return all_embeddings
 
 
+class LiteLLMSDKEmbeddings(Embeddings):
+    """
+    LiteLLM SDK embeddings for direct API integration.
+
+    Supports embeddings via LiteLLM SDK without requiring a proxy server.
+    Supported providers: Cohere, OpenAI, Azure OpenAI, HuggingFace, Voyage AI, Together AI, etc.
+
+    Example model names:
+    - cohere/embed-english-v3.0
+    - openai/text-embedding-3-small
+    - together_ai/togethercomputer/m2-bert-80M-8k-retrieval
+    - voyage/voyage-2
+    """
+
+    def __init__(
+        self,
+        api_key: str,
+        model: str = DEFAULT_EMBEDDINGS_LITELLM_SDK_MODEL,
+        api_base: str | None = None,
+        batch_size: int = 100,
+        timeout: float = 60.0,
+    ):
+        """
+        Initialize LiteLLM SDK embeddings client.
+
+        Args:
+            api_key: API key for the embedding provider
+            model: Model name with provider prefix (e.g., "cohere/embed-english-v3.0")
+            api_base: Custom base URL for API (optional)
+            batch_size: Maximum batch size for embedding requests (default: 100)
+            timeout: Request timeout in seconds (default: 60.0)
+        """
+        self.api_key = api_key
+        self.model = model
+        self.api_base = api_base
+        self.batch_size = batch_size
+        self.timeout = timeout
+        self._litellm = None  # Will be set during initialization
+        self._dimension: int | None = None
+
+    @property
+    def provider_name(self) -> str:
+        return "litellm-sdk"
+
+    @property
+    def dimension(self) -> int:
+        if self._dimension is None:
+            raise RuntimeError("Embeddings not initialized. Call initialize() first.")
+        return self._dimension
+
+    async def initialize(self) -> None:
+        """Initialize the LiteLLM SDK client and detect dimension."""
+        if self._litellm is not None:
+            return
+
+        try:
+            import litellm
+
+            self._litellm = litellm  # Store reference
+        except ImportError:
+            raise ImportError("litellm is required for LiteLLMSDKEmbeddings. Install it with: pip install litellm")
+
+        api_base_msg = f" at {self.api_base}" if self.api_base else ""
+        logger.info(f"Embeddings: initializing LiteLLM SDK provider with model {self.model}{api_base_msg}")
+
+        # Do a test embedding to detect dimension
+        try:
+            # Build kwargs for embedding call
+            embed_kwargs = {
+                "model": self.model,
+                "input": ["test"],
+                "api_key": self.api_key,
+            }
+            if self.api_base:
+                embed_kwargs["api_base"] = self.api_base
+
+            # Use async embedding method (standard in litellm)
+            response = await self._litellm.aembedding(**embed_kwargs)
+
+            # Extract dimension from response
+            if response.data and len(response.data) > 0:
+                self._dimension = len(response.data[0]["embedding"])
+            else:
+                raise RuntimeError(f"Unable to detect embedding dimension for model {self.model}")
+
+        except Exception as e:
+            raise RuntimeError(f"Failed to initialize LiteLLM SDK embeddings: {e}")
+
+        logger.info(f"Embeddings: LiteLLM SDK provider initialized (model: {self.model}, dim: {self._dimension})")
+
+    def encode(self, texts: list[str]) -> list[list[float]]:
+        """
+        Generate embeddings using the LiteLLM SDK.
+
+        Args:
+            texts: List of text strings to encode
+
+        Returns:
+            List of embedding vectors (one per input text)
+        """
+        if self._litellm is None:
+            raise RuntimeError("Embeddings not initialized. Call initialize() first.")
+
+        if not texts:
+            return []
+
+        all_embeddings = []
+
+        # Process in batches
+        for i in range(0, len(texts), self.batch_size):
+            batch = texts[i : i + self.batch_size]
+
+            try:
+                # Build kwargs for embedding call
+                embed_kwargs = {
+                    "model": self.model,
+                    "input": batch,
+                    "api_key": self.api_key,
+                }
+                if self.api_base:
+                    embed_kwargs["api_base"] = self.api_base
+
+                # Use sync embedding (litellm doesn't have async in thread-safe way)
+                response = self._litellm.embedding(**embed_kwargs)
+
+                # Extract embeddings from response
+                # Sort by index to ensure correct order
+                batch_embeddings = sorted(response.data, key=lambda x: x.get("index", 0))
+                all_embeddings.extend([e["embedding"] for e in batch_embeddings])
+
+            except Exception as e:
+                import traceback
+
+                logger.error(
+                    f"Error in LiteLLM embedding for batch starting at index {i}: {e}\n"
+                    f"Traceback: {traceback.format_exc()}"
+                )
+                raise
+
+        return all_embeddings
+
+
 def create_embeddings_from_env() -> Embeddings:
     """
     Create an Embeddings instance based on configuration.
@@ -741,6 +887,7 @@ def create_embeddings_from_env() -> Embeddings:
         return LocalSTEmbeddings(
             model_name=config.embeddings_local_model,
             force_cpu=config.embeddings_local_force_cpu,
+            trust_remote_code=config.embeddings_local_trust_remote_code,
         )
     elif provider == "openai":
         # Use dedicated embeddings API key, or fall back to LLM API key
@@ -754,18 +901,33 @@ def create_embeddings_from_env() -> Embeddings:
         base_url = os.environ.get(ENV_EMBEDDINGS_OPENAI_BASE_URL) or None
         return OpenAIEmbeddings(api_key=api_key, model=model, base_url=base_url)
     elif provider == "cohere":
-        api_key = os.environ.get(ENV_COHERE_API_KEY)
+        api_key = config.embeddings_cohere_api_key
         if not api_key:
-            raise ValueError(f"{ENV_COHERE_API_KEY} is required when {ENV_EMBEDDINGS_PROVIDER} is 'cohere'")
-        model = os.environ.get(ENV_EMBEDDINGS_COHERE_MODEL, DEFAULT_EMBEDDINGS_COHERE_MODEL)
-        base_url = os.environ.get(ENV_EMBEDDINGS_COHERE_BASE_URL) or None
-        return CohereEmbeddings(api_key=api_key, model=model, base_url=base_url)
+            raise ValueError(f"{ENV_EMBEDDINGS_COHERE_API_KEY} is required when {ENV_EMBEDDINGS_PROVIDER} is 'cohere'")
+        return CohereEmbeddings(
+            api_key=api_key,
+            model=config.embeddings_cohere_model,
+            base_url=config.embeddings_cohere_base_url,
+        )
     elif provider == "litellm":
-        api_base = os.environ.get(ENV_LITELLM_API_BASE, DEFAULT_LITELLM_API_BASE)
-        api_key = os.environ.get(ENV_LITELLM_API_KEY)
-        model = os.environ.get(ENV_EMBEDDINGS_LITELLM_MODEL, DEFAULT_EMBEDDINGS_LITELLM_MODEL)
-        return LiteLLMEmbeddings(api_base=api_base, api_key=api_key, model=model)
+        return LiteLLMEmbeddings(
+            api_base=config.embeddings_litellm_api_base,
+            api_key=config.embeddings_litellm_api_key,
+            model=config.embeddings_litellm_model,
+        )
+    elif provider == "litellm-sdk":
+        api_key = config.embeddings_litellm_sdk_api_key
+        if not api_key:
+            raise ValueError(
+                f"{ENV_EMBEDDINGS_LITELLM_SDK_API_KEY} is required when {ENV_EMBEDDINGS_PROVIDER} is 'litellm-sdk'"
+            )
+        return LiteLLMSDKEmbeddings(
+            api_key=api_key,
+            model=config.embeddings_litellm_sdk_model,
+            api_base=config.embeddings_litellm_sdk_api_base,
+        )
     else:
         raise ValueError(
-            f"Unknown embeddings provider: {provider}. Supported: 'local', 'tei', 'openai', 'cohere', 'litellm'"
+            f"Unknown embeddings provider: {provider}. "
+            f"Supported: 'local', 'tei', 'openai', 'cohere', 'litellm', 'litellm-sdk'"
         )

hindsight-api/hindsight_api/engine/interface.py

@@ -48,6 +48,7 @@ class MemoryEngineInterface(ABC):
         contents: list[dict[str, Any]],
         *,
         request_context: "RequestContext",
+        document_tags: list[str] | None = None,
     ) -> dict[str, Any]:
         """
         Retain a batch of memory items.
@@ -55,8 +56,9 @@ class MemoryEngineInterface(ABC):
         Args:
             bank_id: The memory bank ID.
             contents: List of content dicts with 'content', optional 'event_date',
-                     'context', 'metadata', 'document_id'.
+                     'context', 'metadata', 'document_id', and per-item 'tags'.
             request_context: Request context for authentication.
+            document_tags: Optional tags applied to all items in the batch.
 
         Returns:
             Dict with processing results.
@@ -561,6 +563,7 @@ class MemoryEngineInterface(ABC):
         contents: list[dict[str, Any]],
         *,
         request_context: "RequestContext",
+        document_tags: list[str] | None = None,
     ) -> dict[str, Any]:
         """
         Submit a batch retain operation to run asynchronously.
@@ -569,6 +572,7 @@ class MemoryEngineInterface(ABC):
             bank_id: The memory bank ID.
             contents: List of content dicts to retain.
             request_context: Request context for authentication.
+            document_tags: Optional tags applied to all items in the async batch.
 
         Returns:
             Dict with operation_id and items_count.

hindsight-api/hindsight_api/engine/providers/anthropic_llm.py

@@ -84,7 +84,7 @@ class AnthropicLLM(LLMInterface):
                 messages=test_messages,
                 max_completion_tokens=10,
                 temperature=0.0,
-                scope="test",
+                scope="verification",
                 max_retries=0,
             )
             logger.info("Anthropic connection verified successfully")
@@ -223,6 +223,24 @@ class AnthropicLLM(LLMInterface):
                     success=True,
                 )
 
+                # Record trace span
+                from hindsight_api.tracing import _serialize_for_span, get_span_recorder
+
+                finish_reason = response.stop_reason if hasattr(response, "stop_reason") else None
+                span_recorder = get_span_recorder()
+                span_recorder.record_llm_call(
+                    provider=self.provider,
+                    model=self.model,
+                    scope=scope,
+                    messages=messages,
+                    response_content=_serialize_for_span(result),
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                    duration=duration,
+                    finish_reason=finish_reason,
+                    error=None,
+                )
+
                 # Log slow calls
                 if duration > 10.0:
                     logger.info(
@@ -397,16 +415,41 @@ class AnthropicLLM(LLMInterface):
 
                 # Record metrics
                 metrics = get_metrics_collector()
+                duration = time.time() - start_time
                 metrics.record_llm_call(
                     provider=self.provider,
                     model=self.model,
                     scope=scope,
-                    duration=time.time() - start_time,
+                    duration=duration,
                     input_tokens=input_tokens,
                     output_tokens=output_tokens,
                     success=True,
                 )
 
+                # Record OpenTelemetry span
+                from hindsight_api.tracing import get_span_recorder
+
+                span_recorder = get_span_recorder()
+                # Convert LLMToolCall objects to dicts for span recording
+                tool_calls_dict = (
+                    [{"id": tc.id, "name": tc.name, "arguments": tc.arguments} for tc in tool_calls]
+                    if tool_calls
+                    else None
+                )
+                span_recorder.record_llm_call(
+                    provider=self.provider,
+                    model=self.model,
+                    scope=scope,
+                    messages=messages,
+                    response_content=content,
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                    duration=duration,
+                    finish_reason=finish_reason,
+                    error=None,
+                    tool_calls=tool_calls_dict,
+                )
+
                 return LLMToolCallResult(
                     content=content,
                     tool_calls=tool_calls,

hindsight-api/hindsight_api/engine/providers/claude_code_llm.py

@@ -95,7 +95,7 @@ class ClaudeCodeLLM(LLMInterface):
                 messages=test_messages,
                 max_completion_tokens=10,
                 temperature=0.0,
-                scope="test",
+                scope="verification",
                 max_retries=0,
             )
             logger.info("Claude Code connection verified successfully")
@@ -237,6 +237,23 @@ class ClaudeCodeLLM(LLMInterface):
                     success=True,
                 )
 
+                # Record trace span
+                from hindsight_api.tracing import get_span_recorder
+
+                span_recorder = get_span_recorder()
+                span_recorder.record_llm_call(
+                    provider=self.provider,
+                    model=self.model,
+                    scope=scope,
+                    messages=messages,
+                    response_content=result if isinstance(result, str) else json.dumps(result),
+                    input_tokens=estimated_input,
+                    output_tokens=estimated_output,
+                    duration=duration,
+                    finish_reason=None,
+                    error=None,
+                )
+
                 # Log slow calls
                 if duration > 10.0:
                     logger.info(

hindsight-api/hindsight_api/engine/providers/codex_llm.py

@@ -136,6 +136,7 @@ class CodexLLM(LLMInterface):
                 max_retries=2,
                 initial_backoff=0.5,
                 max_backoff=2.0,
+                scope="verification",
             )
             logger.info(f"Codex LLM verified: {self.model}")
         except Exception as e:
@@ -261,6 +262,26 @@ class CodexLLM(LLMInterface):
                     success=True,
                 )
 
+                # Record trace span
+                from hindsight_api.tracing import get_span_recorder
+
+                # Estimate tokens for tracing
+                estimated_input = sum(len(m.get("content", "")) for m in messages) // 4
+                estimated_output = len(content) // 4
+                span_recorder = get_span_recorder()
+                span_recorder.record_llm_call(
+                    provider=self.provider,
+                    model=self.model,
+                    scope=scope,
+                    messages=messages,
+                    response_content=result if isinstance(result, str) else json.dumps(result),
+                    input_tokens=estimated_input,
+                    output_tokens=estimated_output,
+                    duration=duration,
+                    finish_reason=None,
+                    error=None,
+                )
+
                 if return_usage:
                     # Codex doesn't provide token counts, estimate based on content
                     estimated_input = sum(len(m.get("content", "")) for m in messages) // 4
@@ -504,6 +525,28 @@ class CodexLLM(LLMInterface):
                 success=True,
             )
 
+            # Record OpenTelemetry span
+            from hindsight_api.tracing import get_span_recorder
+
+            span_recorder = get_span_recorder()
+            # Convert LLMToolCall objects to dicts for span recording
+            tool_calls_dict = (
+                [{"id": tc.id, "name": tc.name, "arguments": tc.arguments} for tc in tool_calls] if tool_calls else None
+            )
+            span_recorder.record_llm_call(
+                provider=self.provider,
+                model=self.model,
+                scope=scope,
+                messages=messages,
+                response_content=content,
+                input_tokens=0,  # Codex doesn't provide token counts
+                output_tokens=0,
+                duration=duration,
+                finish_reason="tool_calls" if tool_calls else "stop",
+                error=None,
+                tool_calls=tool_calls_dict,
+            )
+
             return LLMToolCallResult(
                 content=content,
                 tool_calls=tool_calls,

hindsight-api/hindsight_api/engine/providers/gemini_llm.py

@@ -136,6 +136,7 @@ class GeminiLLM(LLMInterface):
                 max_retries=2,
                 initial_backoff=0.5,
                 max_backoff=2.0,
+                scope="verification",
             )
             logger.info(f"{self.provider.upper()} connection verified successfully")
         except Exception as e:
@@ -275,6 +276,29 @@ class GeminiLLM(LLMInterface):
                     success=True,
                 )
 
+                # Record trace span
+                from hindsight_api.tracing import get_span_recorder
+
+                finish_reason = None
+                if hasattr(response, "candidates") and response.candidates:
+                    if hasattr(response.candidates[0], "finish_reason"):
+                        finish_reason = str(response.candidates[0].finish_reason)
+                span_recorder = get_span_recorder()
+                from hindsight_api.tracing import _serialize_for_span
+
+                span_recorder.record_llm_call(
+                    provider=self.provider,
+                    model=self.model,
+                    scope=scope,
+                    messages=messages,
+                    response_content=_serialize_for_span(result),
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                    duration=duration,
+                    finish_reason=finish_reason,
+                    error=None,
+                )
+
                 # Log slow calls
                 if duration > 10.0 and input_tokens > 0:
                     logger.info(
@@ -466,6 +490,30 @@ class GeminiLLM(LLMInterface):
                     success=True,
                 )
 
+                # Record OpenTelemetry span
+                from hindsight_api.tracing import get_span_recorder
+
+                span_recorder = get_span_recorder()
+                # Convert LLMToolCall objects to dicts for span recording
+                tool_calls_dict = (
+                    [{"id": tc.id, "name": tc.name, "arguments": tc.arguments} for tc in tool_calls]
+                    if tool_calls
+                    else None
+                )
+                span_recorder.record_llm_call(
+                    provider=self.provider,
+                    model=self.model,
+                    scope=scope,
+                    messages=messages,
+                    response_content=content,
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                    duration=duration,
+                    finish_reason=finish_reason,
+                    error=None,
+                    tool_calls=tool_calls_dict,
+                )
+
                 return LLMToolCallResult(
                     content=content,
                     tool_calls=tool_calls,

hindsight-api/hindsight_api/engine/providers/mock_llm.py

@@ -65,6 +65,7 @@ class MockLLM(LLMInterface):
         # Storage for test verification
         self._mock_calls: list[dict] = []
         self._mock_response: Any = None
+        self._mock_exception: Exception | None = None
 
     async def verify_connection(self) -> None:
         """
@@ -124,6 +125,27 @@ class MockLLM(LLMInterface):
         self._mock_calls.append(call_record)
         logger.debug(f"Mock LLM call recorded: scope={scope}, model={self.model}")
 
+        # Raise mock exception if configured
+        if self._mock_exception is not None:
+            raise self._mock_exception
+
+        # Record trace span (minimal for mock provider)
+        from hindsight_api.tracing import get_span_recorder
+
+        span_recorder = get_span_recorder()
+        span_recorder.record_llm_call(
+            provider=self.provider,
+            model=self.model,
+            scope=scope,
+            messages=messages,
+            response_content="mock response",
+            input_tokens=10,
+            output_tokens=5,
+            duration=0.001,  # Mock calls are instant
+            finish_reason="stop",
+            error=None,
+        )
+
         # Return mock response
         if self._mock_response is not None:
             result = self._mock_response
@@ -183,20 +205,54 @@ class MockLLM(LLMInterface):
         }
         self._mock_calls.append(call_record)
 
+        # Raise mock exception if configured
+        if self._mock_exception is not None:
+            raise self._mock_exception
+
+        # Record OpenTelemetry span
+        from hindsight_api.tracing import get_span_recorder
+
+        span_recorder = get_span_recorder()
+
         if self._mock_response is not None:
             if isinstance(self._mock_response, LLMToolCallResult):
-                return self._mock_response
-            # Allow setting just tool calls as a list
-            if isinstance(self._mock_response, list):
-                return LLMToolCallResult(
+                result = self._mock_response
+            elif isinstance(self._mock_response, list):
+                # Allow setting just tool calls as a list
+                result = LLMToolCallResult(
                     tool_calls=[
                         LLMToolCall(id=f"mock_{i}", name=tc["name"], arguments=tc.get("arguments", {}))
                         for i, tc in enumerate(self._mock_response)
                     ],
                     finish_reason="tool_calls",
                 )
+            else:
+                result = LLMToolCallResult(content="mock response", finish_reason="stop")
+        else:
+            result = LLMToolCallResult(content="mock response", finish_reason="stop")
 
-        return LLMToolCallResult(content="mock response", finish_reason="stop")
+        # Record span with mock values
+        # Convert LLMToolCall objects to dicts for span recording
+        tool_calls_dict = (
+            [{"id": tc.id, "name": tc.name, "arguments": tc.arguments} for tc in result.tool_calls]
+            if result.tool_calls
+            else None
+        )
+        span_recorder.record_llm_call(
+            provider=self.provider,
+            model=self.model,
+            scope=scope,
+            messages=messages,
+            response_content=result.content,
+            input_tokens=10,  # Mock value
+            output_tokens=5,  # Mock value
+            duration=0.1,  # Mock value
+            finish_reason=result.finish_reason,
+            error=None,
+            tool_calls=tool_calls_dict,
+        )
+
+        return result
 
     async def cleanup(self) -> None:
         """Clean up resources (no-op for mock provider)."""
@@ -215,6 +271,16 @@ class MockLLM(LLMInterface):
         """
         self._mock_response = response
 
+    def set_mock_exception(self, exception: Exception) -> None:
+        """
+        Set an exception to raise from mock calls.
+
+        Args:
+            exception: The exception to raise on the next call.
+                      After raising, the exception is cleared.
+        """
+        self._mock_exception = exception
+
     def get_mock_calls(self) -> list[dict]:
         """
         Get the list of recorded mock calls.
@@ -230,5 +296,6 @@ class MockLLM(LLMInterface):
         return self._mock_calls
 
     def clear_mock_calls(self) -> None:
-        """Clear the recorded mock calls."""
+        """Clear the recorded mock calls and any set exception."""
         self._mock_calls = []
+        self._mock_exception = None

hindsight-api/hindsight_api/engine/providers/openai_compatible_llm.py

@@ -130,6 +130,7 @@ class OpenAICompatibleLLM(LLMInterface):
                 max_retries=2,
                 initial_backoff=0.5,
                 max_backoff=2.0,
+                scope="verification",
             )
             logger.info(f"Connection verified: {self.provider}/{self.model}")
         except Exception as e:
@@ -368,6 +369,24 @@ class OpenAICompatibleLLM(LLMInterface):
                     success=True,
                 )
 
+                # Record trace span
+                from hindsight_api.tracing import _serialize_for_span, get_span_recorder
+
+                finish_reason = response.choices[0].finish_reason if response.choices else None
+                span_recorder = get_span_recorder()
+                span_recorder.record_llm_call(
+                    provider=self.provider,
+                    model=self.model,
+                    scope=scope,
+                    messages=messages,
+                    response_content=_serialize_for_span(result),
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                    duration=duration,
+                    finish_reason=finish_reason,
+                    error=None,
+                )
+
                 # Log slow calls
                 if duration > 10.0 and usage:
                     ratio = max(1, output_tokens) / max(1, input_tokens)
@@ -556,6 +575,30 @@ class OpenAICompatibleLLM(LLMInterface):
                     success=True,
                 )
 
+                # Record OpenTelemetry span
+                from hindsight_api.tracing import get_span_recorder
+
+                span_recorder = get_span_recorder()
+                # Convert LLMToolCall objects to dicts for span recording
+                tool_calls_dict = (
+                    [{"id": tc.id, "name": tc.name, "arguments": tc.arguments} for tc in tool_calls]
+                    if tool_calls
+                    else None
+                )
+                span_recorder.record_llm_call(
+                    provider=self.provider,
+                    model=self.model,
+                    scope=scope,
+                    messages=messages,
+                    response_content=content,
+                    input_tokens=input_tokens,
+                    output_tokens=output_tokens,
+                    duration=duration,
+                    finish_reason=finish_reason,
+                    error=None,
+                    tool_calls=tool_calls_dict,
+                )
+
                 return LLMToolCallResult(
                     content=content,
                     tool_calls=tool_calls,

hindsight-api/hindsight_api/engine/reflect/agent.py

@@ -402,7 +402,7 @@ async def run_reflect_agent(
                     {"role": "system", "content": FINAL_SYSTEM_PROMPT},
                     {"role": "user", "content": prompt},
                 ],
-                scope="reflect_agent_final",
+                scope="reflect",
                 max_completion_tokens=max_tokens,
                 return_usage=True,
             )
@@ -447,7 +447,7 @@ async def run_reflect_agent(
             result = await llm_config.call_with_tools(
                 messages=messages,
                 tools=tools,
-                scope="reflect_agent",
+                scope="reflect_tool_call",
                 tool_choice="required" if iteration == 0 else "auto",  # Force tool use on first iteration
             )
             llm_duration = int((time.time() - llm_start) * 1000)
@@ -479,7 +479,7 @@ async def run_reflect_agent(
                     {"role": "system", "content": FINAL_SYSTEM_PROMPT},
                     {"role": "user", "content": prompt},
                 ],
-                scope="reflect_agent_final",
+                scope="reflect",
                 max_completion_tokens=max_tokens,
                 return_usage=True,
             )
@@ -550,7 +550,7 @@ async def run_reflect_agent(
                     {"role": "system", "content": FINAL_SYSTEM_PROMPT},
                     {"role": "user", "content": prompt},
                 ],
-                scope="reflect_agent_final",
+                scope="reflect",
                 max_completion_tokens=max_tokens,
                 return_usage=True,
             )
@@ -617,23 +617,30 @@ async def run_reflect_agent(
                 )
                 continue
 
-            # Process done tool
-            return await _process_done_tool(
-                done_call,
-                available_memory_ids,
-                available_mental_model_ids,
-                available_observation_ids,
-                iteration + 1,
-                total_tools_called,
-                tool_trace,
-                _get_llm_trace(),
-                _get_usage(),
-                _log_completion,
-                reflect_id,
-                directives_applied=directives_applied,
-                llm_config=llm_config,
-                response_schema=response_schema,
-            )
+            # Process done tool - wrap with tool call span
+            from hindsight_api.tracing import get_tracer
+
+            tracer = get_tracer()
+            span_name = "hindsight.reflect_tool_call"
+            with tracer.start_as_current_span(span_name) as span:
+                span.set_attribute("hindsight.scope", "reflect_tool_call")
+                span.set_attribute("hindsight.operation", "reflect_tool_call")
+                return await _process_done_tool(
+                    done_call,
+                    available_memory_ids,
+                    available_mental_model_ids,
+                    available_observation_ids,
+                    iteration + 1,
+                    total_tools_called,
+                    tool_trace,
+                    _get_llm_trace(),
+                    _get_usage(),
+                    _log_completion,
+                    reflect_id,
+                    directives_applied=directives_applied,
+                    llm_config=llm_config,
+                    response_schema=response_schema,
+                )
 
         # Execute other tools in parallel (exclude done tool in all its format variants)
         other_tools = [tc for tc in result.tool_calls if not _is_done_tool(tc.name)]
@@ -842,17 +849,67 @@ async def _execute_tool_with_timing(
     expand_fn: Callable[[list[str], str], Awaitable[dict[str, Any]]],
 ) -> tuple[dict[str, Any], int]:
     """Execute a tool call and return result with timing."""
-    start = time.time()
-    result = await _execute_tool(
-        tc.name,
-        tc.arguments,
-        search_mental_models_fn,
-        search_observations_fn,
-        recall_fn,
-        expand_fn,
-    )
-    duration_ms = int((time.time() - start) * 1000)
-    return result, duration_ms
+    from hindsight_api.tracing import get_tracer
+
+    start_time = time.time()
+
+    # Create span for tool execution
+    tracer = get_tracer()
+    # Normalize tool name for span
+    normalized_name = _normalize_tool_name(tc.name)
+    span_name = f"hindsight.reflect_tool_exec.{normalized_name}"
+
+    # Calculate timestamps
+    start_time_ns = time.time_ns()
+
+    with tracer.start_as_current_span(
+        span_name,
+        start_time=start_time_ns,
+        end_on_exit=False,
+    ) as span:
+        # Set attributes
+        span.set_attribute("hindsight.tool.name", normalized_name)
+        span.set_attribute("hindsight.tool.id", tc.id)
+        span.set_attribute("hindsight.tool.arguments", json.dumps(tc.arguments))
+
+        try:
+            result = await _execute_tool(
+                tc.name,
+                tc.arguments,
+                search_mental_models_fn,
+                search_observations_fn,
+                recall_fn,
+                expand_fn,
+            )
+
+            # Set success attributes
+            if isinstance(result, dict) and "error" in result:
+                from opentelemetry.trace import Status, StatusCode
+
+                span.set_status(Status(StatusCode.ERROR, result["error"]))
+            else:
+                from opentelemetry.trace import Status, StatusCode
+
+                span.set_status(Status(StatusCode.OK))
+
+            duration_ms = int((time.time() - start_time) * 1000)
+            span.set_attribute("hindsight.tool.duration_ms", duration_ms)
+
+            # End span with correct timestamp
+            end_time_ns = time.time_ns()
+            span.end(end_time=end_time_ns)
+
+            return result, duration_ms
+        except Exception as e:
+            from opentelemetry.trace import Status, StatusCode
+
+            span.set_status(Status(StatusCode.ERROR, str(e)))
+            span.record_exception(e)
+            duration_ms = int((time.time() - start_time) * 1000)
+            span.set_attribute("hindsight.tool.duration_ms", duration_ms)
+            end_time_ns = time.time_ns()
+            span.end(end_time=end_time_ns)
+            raise
 
 
 async def _execute_tool(

hindsight-api/hindsight_api/engine/reflect/models.py

@@ -31,7 +31,7 @@ class ReflectAction(BaseModel):
         default=None, description="Observation sections for done action (when output_mode=observations)"
     )
     # Plain text answer fields (for output_mode=answer)
-    answer: str | None = Field(default=None, description="Plain text answer for done action (no markdown)")
+    answer: str | None = Field(default=None, description="Well-formatted markdown answer for done action")
     answer_memory_ids: list[str] | None = Field(
         default=None, description="Memory IDs supporting the answer", alias="memory_ids"
     )

hindsight-api/hindsight_api/engine/reflect/prompts.py

@@ -148,7 +148,15 @@ def build_system_prompt_for_tools(
 
     parts = []
 
-    # Inject directives at the VERY START for maximum prominence
+    # Anti-hallucination rule at the very top
+    parts.extend(
+        [
+            "CRITICAL: You MUST ONLY use information from retrieved tool results. NEVER make up names, people, events, or entities.",
+            "",
+        ]
+    )
+
+    # Inject directives after anti-hallucination rule
     if directives:
         parts.append(build_directives_section(directives))
 
@@ -162,7 +170,7 @@ def build_system_prompt_for_tools(
     parts.extend(
         [
             "## CRITICAL RULES",
-            "- You must NEVER fabricate information that has no basis in retrieved data",
+            "- ONLY use information from tool results - no external knowledge or guessing",
             "- You SHOULD synthesize, infer, and reason from the retrieved memories",
             "- You MUST search before saying you don't have information",
             "",
@@ -300,9 +308,11 @@ def build_system_prompt_for_tools(
     parts.extend(
         [
             "",
-            "## Output Format: Plain Text Answer",
-            "Call done() with a plain text 'answer' field.",
-            "- Do NOT use markdown formatting",
+            "## Output Format: Well-Formatted Markdown Answer",
+            "Call done() with a well-formatted markdown 'answer' field.",
+            "- USE markdown formatting for structure (headers, lists, bold, italic, code blocks, tables, etc.)",
+            "- CRITICAL: Add blank lines before and after block elements (tables, code blocks, lists)",
+            "- Format for clarity and readability with proper spacing and hierarchy",
             "- NEVER include memory IDs, UUIDs, or 'Memory references' in the answer text",
             "- Put IDs ONLY in the memory_ids/mental_model_ids/observation_ids arrays, not in the answer",
         ]
@@ -474,19 +484,30 @@ def build_final_prompt(
     return "\n".join(parts)
 
 
-FINAL_SYSTEM_PROMPT = """You are a thoughtful assistant that synthesizes answers from retrieved memories.
+FINAL_SYSTEM_PROMPT = """CRITICAL: You MUST ONLY use information from retrieved tool results. NEVER make up names, people, events, or entities.
+
+You are a thoughtful assistant that synthesizes answers from retrieved memories.
 
 Your approach:
 - Reason over the retrieved memories to answer the question
 - Make reasonable inferences when the exact answer isn't explicitly stated
 - Connect related memories to form a complete picture
 - Be helpful - if you have related information, use it to give the best possible answer
+- ONLY use information from tool results - no external knowledge or guessing
 
 Only say "I don't have information" if the retrieved data is truly unrelated to the question.
-Do NOT fabricate information that has no basis in the retrieved data.
+
+FORMATTING: Use proper markdown formatting in your answer:
+- Headers (##, ###) for sections
+- Lists (bullet or numbered) for enumerations
+- Bold/italic for emphasis
+- Tables with proper syntax (ensure blank line before and after)
+- Code blocks where appropriate
+- CRITICAL: Always add blank lines before and after block elements (tables, code blocks, lists)
+- Proper spacing between sections
 
 CRITICAL: Output ONLY the final synthesized answer. Do NOT include:
 - Meta-commentary about what you're doing ("I'll search...", "Let me analyze...")
 - Explanations of your reasoning process
 - Descriptions of your approach
-Just provide the direct answer."""
+Just provide the direct answer with proper markdown formatting."""

hindsight-api/hindsight_api/engine/reflect/tools_schema.py

@@ -139,7 +139,7 @@ TOOL_DONE_ANSWER = {
             "properties": {
                 "answer": {
                     "type": "string",
-                    "description": "Your response as plain text. Do NOT use markdown formatting. NEVER include memory IDs, UUIDs, or 'Memory references' in this text - put IDs only in memory_ids array.",
+                    "description": "Your response as well-formatted markdown. Use headers, lists, bold/italic, and code blocks for clarity. NEVER include memory IDs, UUIDs, or 'Memory references' in this text - put IDs only in memory_ids array.",
                 },
                 "memory_ids": {
                     "type": "array",
@@ -190,7 +190,7 @@ def _build_done_tool_with_directives(directive_rules: list[str]) -> dict:
                 "properties": {
                     "answer": {
                         "type": "string",
-                        "description": "Your response as plain text. Do NOT use markdown formatting. NEVER include memory IDs, UUIDs, or 'Memory references' in this text - put IDs only in memory_ids array.",
+                        "description": "Your response as well-formatted markdown. Use headers, lists, bold/italic, and code blocks for clarity. NEVER include memory IDs, UUIDs, or 'Memory references' in this text - put IDs only in memory_ids array.",
                     },
                     "memory_ids": {
                         "type": "array",

hindsight-api/hindsight_api/engine/retain/fact_extraction.py

@@ -542,7 +542,12 @@ Output: ONLY 2 facts (skip coffee preference - too trivial):
 QUALITY OVER QUANTITY
 ══════════════════════════════════════════════════════════════════════════
 
-Ask: "Would this be useful to recall in 6 months?" If no, skip it."""
+Ask: "Would this be useful to recall in 6 months?" If no, skip it.
+
+IMPORTANT: Sensory/emotional details and observations that provide meaningful context
+about experiences ARE important to remember, even if they seem small (e.g., how food
+tasted, how someone looked, how loud music was). Extract these if they characterize
+an experience or person."""
 
 # Assembled concise prompt (backward compatible - exact same output as before)
 CONCISE_FACT_EXTRACTION_PROMPT = _BASE_FACT_EXTRACTION_PROMPT.format(
@@ -641,6 +646,7 @@ For EVENTS (fact_kind="event") - MUST SET BOTH occurred_start AND occurred_end:
 - Convert relative dates → absolute using Event Date as reference
 - If Event Date is "Saturday, March 15, 2020", then "yesterday" = Friday, March 14, 2020
 - Dates mentioned in text (e.g., "in March 2020") should use THAT year, not current year
+- CRITICAL: If the content mentions an absolute date (e.g., "March 15, 2024", "2024-03-15"), you MUST extract it and set occurred_start in ISO format
 - Always include the day name (Monday, Tuesday, etc.) in the 'when' field
 - Set occurred_start AND occurred_end to WHEN IT HAPPENED (not when mentioned)
 - For single-day/point events: set occurred_end = occurred_start (same timestamp)
@@ -696,6 +702,7 @@ async def _extract_facts_from_chunk(
     event_date: datetime,
     context: str,
     llm_config: "LLMConfig",
+    config,
     agent_name: str = None,
 ) -> tuple[list[dict[str, str]], TokenUsage]:
     """
@@ -715,7 +722,6 @@ async def _extract_facts_from_chunk(
     fact_types_instruction = "Extract ONLY 'world' and 'assistant' type facts."
 
     # Check config for extraction mode and causal link extraction
-    config = get_config()
     extraction_mode = config.retain_extraction_mode
     extract_causal_links = config.retain_extract_causal_links
 
@@ -796,7 +802,7 @@ Text:
             extraction_response_json, call_usage = await llm_config.call(
                 messages=[{"role": "system", "content": prompt}, {"role": "user", "content": user_message}],
                 response_format=response_schema,
-                scope="memory_extract_facts",
+                scope="retain_extract_facts",
                 temperature=0.1,
                 max_completion_tokens=config.retain_max_completion_tokens,
                 max_retries=max_retries,
@@ -1005,6 +1011,29 @@ Text:
 
         except BadRequestError as e:
             last_error = e
+            error_str = str(e).lower()
+
+            # Check if error is related to max_tokens/completion_tokens not being supported
+            if any(
+                keyword in error_str
+                for keyword in [
+                    "max_tokens",
+                    "max_completion_tokens",
+                    "maximum context",
+                    "token limit",
+                    "context length",
+                ]
+            ):
+                # Provide helpful error message with configuration suggestions
+                raise ValueError(
+                    f"Model does not support the required output token limit.\n\n"
+                    f"The model '{llm_config.model}' (provider: {llm_config.provider}) failed with: {e}\n\n"
+                    f"You have two options to fix this:\n"
+                    f"  1. Use a different model that supports at least {config.retain_max_completion_tokens} output tokens\n"
+                    f"  2. Decrease HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS to a value your model supports\n"
+                    f"     (current value: {config.retain_max_completion_tokens}, must be > RETAIN_CHUNK_SIZE={config.retain_chunk_size})"
+                ) from e
+
             if "json_validate_failed" in str(e):
                 logger.warning(
                     f"          [1.3.{chunk_index + 1}] Attempt {attempt + 1}/{max_retries} failed with JSON validation error: {e}"
@@ -1026,6 +1055,7 @@ async def _extract_facts_with_auto_split(
     event_date: datetime,
     context: str,
     llm_config: LLMConfig,
+    config,
     agent_name: str = None,
 ) -> tuple[list[dict[str, str]], TokenUsage]:
     """
@@ -1041,6 +1071,7 @@ async def _extract_facts_with_auto_split(
         event_date: Reference date for temporal information
         context: Context about the conversation/document
         llm_config: LLM configuration to use
+        config: Resolved HindsightConfig for this bank
         agent_name: Optional agent name (memory owner)
 
     Returns:
@@ -1059,6 +1090,7 @@ async def _extract_facts_with_auto_split(
             event_date=event_date,
             context=context,
             llm_config=llm_config,
+            config=config,
             agent_name=agent_name,
         )
     except OutputTooLongError:
@@ -1103,6 +1135,7 @@ async def _extract_facts_with_auto_split(
                 event_date=event_date,
                 context=context,
                 llm_config=llm_config,
+                config=config,
                 agent_name=agent_name,
             ),
             _extract_facts_with_auto_split(
@@ -1112,6 +1145,7 @@ async def _extract_facts_with_auto_split(
                 event_date=event_date,
                 context=context,
                 llm_config=llm_config,
+                config=config,
                 agent_name=agent_name,
             ),
         ]
@@ -1135,6 +1169,7 @@ async def extract_facts_from_text(
     event_date: datetime,
     llm_config: LLMConfig,
     agent_name: str,
+    config,
     context: str = "",
 ) -> tuple[list[Fact], list[tuple[str, int]], TokenUsage]:
     """
@@ -1149,9 +1184,10 @@ async def extract_facts_from_text(
     Args:
         text: Input text (conversation, article, etc.)
         event_date: Reference date for resolving relative times
-        context: Context about the conversation/document
         llm_config: LLM configuration to use
         agent_name: Agent name (memory owner)
+        config: Resolved HindsightConfig for this bank
+        context: Context about the conversation/document
 
     Returns:
         Tuple of (facts, chunks, usage) where:
@@ -1159,7 +1195,6 @@ async def extract_facts_from_text(
         - chunks: List of tuples (chunk_text, fact_count) for each chunk
         - usage: Aggregated token usage across all LLM calls
     """
-    config = get_config()
     chunks = chunk_text(text, max_chars=config.retain_chunk_size)
 
     # Log chunk count before starting LLM requests
@@ -1178,6 +1213,7 @@ async def extract_facts_from_text(
             event_date=event_date,
             context=context,
             llm_config=llm_config,
+            config=config,
             agent_name=agent_name,
         )
         for i, chunk in enumerate(chunks)
@@ -1210,7 +1246,7 @@ SECONDS_PER_FACT = 10
 
 
 async def extract_facts_from_contents(
-    contents: list[RetainContent], llm_config, agent_name: str
+    contents: list[RetainContent], llm_config, agent_name: str, config
 ) -> tuple[list[ExtractedFactType], list[ChunkMetadata], TokenUsage]:
     """
     Extract facts from multiple content items in parallel.
@@ -1225,6 +1261,7 @@ async def extract_facts_from_contents(
         contents: List of RetainContent objects to process
         llm_config: LLM configuration for fact extraction
         agent_name: Name of the agent (for agent-related fact detection)
+        config: Resolved HindsightConfig for this bank
 
     Returns:
         Tuple of (extracted_facts, chunks_metadata, usage)
@@ -1243,6 +1280,7 @@ async def extract_facts_from_contents(
             context=item.context,
             llm_config=llm_config,
             agent_name=agent_name,
+            config=config,
         )
         fact_extraction_tasks.append(task)
 
@@ -1347,28 +1385,21 @@ def _convert_causal_relations(relations_from_llm, fact_start_idx: int) -> list[C
 
 def _add_temporal_offsets(facts: list[ExtractedFactType], contents: list[RetainContent]) -> None:
     """
-    Add time offsets to preserve fact ordering within each content.
+    Add time offsets to preserve fact ordering across all contents.
 
-    This allows retrieval to distinguish between facts that happened earlier vs later
-    in the same conversation, even when the base event_date is the same.
+    This allows retrieval to distinguish between facts from different documents/conversations
+    even when they have the same base event_date, and also between facts within the same
+    conversation.
+
+    Uses absolute position across all facts to ensure unique timestamps.
 
     Modifies facts in place.
     """
     from .orchestrator import parse_datetime_flexible
 
-    # Group facts by content_index
-    current_content_idx = 0
-    content_fact_start = 0
-
     for i, fact in enumerate(facts):
-        if fact.content_index != current_content_idx:
-            # Moved to next content
-            current_content_idx = fact.content_index
-            content_fact_start = i
-
-        # Calculate position within this content
-        fact_position = i - content_fact_start
-        offset = timedelta(seconds=fact_position * SECONDS_PER_FACT)
+        # Use absolute position across all facts to ensure uniqueness across different contents
+        offset = timedelta(seconds=i * SECONDS_PER_FACT)
 
         # Apply offset to all temporal fields (handle both datetime objects and ISO strings)
         if fact.occurred_start:

hindsight-api/hindsight_api/engine/retain/fact_storage.py

@@ -7,6 +7,7 @@ Handles insertion of facts into the database.
 import json
 import logging
 
+from ...config import get_config
 from ..memory_engine import fq_table
 from .fact_extraction import _sanitize_text
 from .types import ProcessedFact
@@ -70,28 +71,59 @@ async def insert_facts_batch(
 
     # Batch insert all facts
     # Note: tags are passed as JSON strings and converted back to varchar[] via jsonb_array_elements_text + array_agg
-    results = await conn.fetch(
-        f"""
-        WITH input_data AS (
-            SELECT * FROM unnest(
-                $2::text[], $3::vector[], $4::timestamptz[], $5::timestamptz[], $6::timestamptz[], $7::timestamptz[],
-                $8::text[], $9::text[], $10::float[], $11::jsonb[], $12::text[], $13::text[], $14::jsonb[]
-            ) AS t(text, embedding, event_date, occurred_start, occurred_end, mentioned_at,
-                   context, fact_type, confidence_score, metadata, chunk_id, document_id, tags_json)
-        )
-        INSERT INTO {fq_table("memory_units")} (bank_id, text, embedding, event_date, occurred_start, occurred_end, mentioned_at,
-                                 context, fact_type, confidence_score, metadata, chunk_id, document_id, tags)
-        SELECT
-            $1,
-            text, embedding, event_date, occurred_start, occurred_end, mentioned_at,
-            context, fact_type, confidence_score, metadata, chunk_id, document_id,
-            COALESCE(
-                (SELECT array_agg(elem) FROM jsonb_array_elements_text(tags_json) AS elem),
-                '{{}}'::varchar[]
+    # Query varies based on text search backend
+    config = get_config()
+    if config.text_search_extension == "vchord":
+        # VectorChord: manually tokenize and insert search_vector
+        query = f"""
+            WITH input_data AS (
+                SELECT * FROM unnest(
+                    $2::text[], $3::vector[], $4::timestamptz[], $5::timestamptz[], $6::timestamptz[], $7::timestamptz[],
+                    $8::text[], $9::text[], $10::float[], $11::jsonb[], $12::text[], $13::text[], $14::jsonb[]
+                ) AS t(text, embedding, event_date, occurred_start, occurred_end, mentioned_at,
+                       context, fact_type, confidence_score, metadata, chunk_id, document_id, tags_json)
             )
-        FROM input_data
-        RETURNING id
-        """,
+            INSERT INTO {fq_table("memory_units")} (bank_id, text, embedding, event_date, occurred_start, occurred_end, mentioned_at,
+                                     context, fact_type, confidence_score, metadata, chunk_id, document_id, tags, search_vector)
+            SELECT
+                $1,
+                text, embedding, event_date, occurred_start, occurred_end, mentioned_at,
+                context, fact_type, confidence_score, metadata, chunk_id, document_id,
+                COALESCE(
+                    (SELECT array_agg(elem) FROM jsonb_array_elements_text(tags_json) AS elem),
+                    '{{}}'::varchar[]
+                ),
+                tokenize(COALESCE(text, '') || ' ' || COALESCE(context, ''), 'llmlingua2')::bm25_catalog.bm25vector
+            FROM input_data
+            RETURNING id
+        """
+    else:  # native or pg_textsearch
+        # Native PostgreSQL: search_vector is GENERATED ALWAYS, don't include it
+        # pg_textsearch: indexes operate on base columns directly, don't populate search_vector
+        query = f"""
+            WITH input_data AS (
+                SELECT * FROM unnest(
+                    $2::text[], $3::vector[], $4::timestamptz[], $5::timestamptz[], $6::timestamptz[], $7::timestamptz[],
+                    $8::text[], $9::text[], $10::float[], $11::jsonb[], $12::text[], $13::text[], $14::jsonb[]
+                ) AS t(text, embedding, event_date, occurred_start, occurred_end, mentioned_at,
+                       context, fact_type, confidence_score, metadata, chunk_id, document_id, tags_json)
+            )
+            INSERT INTO {fq_table("memory_units")} (bank_id, text, embedding, event_date, occurred_start, occurred_end, mentioned_at,
+                                     context, fact_type, confidence_score, metadata, chunk_id, document_id, tags)
+            SELECT
+                $1,
+                text, embedding, event_date, occurred_start, occurred_end, mentioned_at,
+                context, fact_type, confidence_score, metadata, chunk_id, document_id,
+                COALESCE(
+                    (SELECT array_agg(elem) FROM jsonb_array_elements_text(tags_json) AS elem),
+                    '{{}}'::varchar[]
+                )
+            FROM input_data
+            RETURNING id
+        """
+
+    results = await conn.fetch(
+        query,
         bank_id,
         fact_texts,
         embeddings,

hindsight-api/hindsight_api/engine/retain/orchestrator.py

@@ -76,6 +76,7 @@ async def retain_batch(
     duplicate_checker_fn,
     bank_id: str,
     contents_dicts: list[RetainContentDict],
+    config,
     document_id: str | None = None,
     is_first_batch: bool = True,
     fact_type_override: str | None = None,
@@ -94,6 +95,7 @@ async def retain_batch(
         duplicate_checker_fn: Function to check for duplicate facts
         bank_id: Bank identifier
         contents_dicts: List of content dictionaries
+        config: Resolved HindsightConfig for this bank
         document_id: Optional document ID
         is_first_batch: Whether this is the first batch
         fact_type_override: Override fact type for all facts
@@ -144,7 +146,9 @@ async def retain_batch(
     # Step 1: Extract facts from all contents
     step_start = time.time()
 
-    extracted_facts, chunks, usage = await fact_extraction.extract_facts_from_contents(contents, llm_config, agent_name)
+    extracted_facts, chunks, usage = await fact_extraction.extract_facts_from_contents(
+        contents, llm_config, agent_name, config
+    )
     log_buffer.append(
         f"[1] Extract facts: {len(extracted_facts)} facts, {len(chunks)} chunks from {len(contents)} contents in {time.time() - step_start:.3f}s"
     )

hindsight-api/hindsight_api/engine/search/__init__.py

@@ -13,12 +13,10 @@ from .reranking import CrossEncoderReranker
 from .retrieval import (
     ParallelRetrievalResult,
     get_default_graph_retriever,
-    retrieve_parallel,
     set_default_graph_retriever,
 )
 
 __all__ = [
-    "retrieve_parallel",
     "get_default_graph_retriever",
     "set_default_graph_retriever",
     "ParallelRetrievalResult",

hindsight-api/hindsight_api/engine/search/retrieval.py

@@ -85,116 +85,6 @@ def set_default_graph_retriever(retriever: GraphRetriever) -> None:
     _default_graph_retriever = retriever
 
 
-async def retrieve_semantic(
-    conn,
-    query_emb_str: str,
-    bank_id: str,
-    fact_type: str,
-    limit: int,
-    tags: list[str] | None = None,
-) -> list[RetrievalResult]:
-    """
-    Semantic retrieval via vector similarity.
-
-    Args:
-        conn: Database connection
-        query_emb_str: Query embedding as string
-        agent_id: bank ID
-        fact_type: Fact type to filter
-        limit: Maximum results to return
-        tags: Optional list of tags for visibility filtering (OR matching)
-
-    Returns:
-        List of RetrievalResult objects
-    """
-    from .tags import TagsMatch, build_tags_where_clause_simple
-
-    tags_clause = build_tags_where_clause_simple(tags, 5)
-    params = [query_emb_str, bank_id, fact_type, limit]
-    if tags:
-        params.append(tags)
-
-    results = await conn.fetch(
-        f"""
-        SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, embedding, fact_type, document_id, chunk_id, tags,
-               1 - (embedding <=> $1::vector) AS similarity
-        FROM {fq_table("memory_units")}
-        WHERE bank_id = $2
-          AND embedding IS NOT NULL
-          AND fact_type = $3
-          AND (1 - (embedding <=> $1::vector)) >= 0.3
-          {tags_clause}
-        ORDER BY embedding <=> $1::vector
-        LIMIT $4
-        """,
-        *params,
-    )
-    return [RetrievalResult.from_db_row(dict(r)) for r in results]
-
-
-async def retrieve_bm25(
-    conn,
-    query_text: str,
-    bank_id: str,
-    fact_type: str,
-    limit: int,
-    tags: list[str] | None = None,
-) -> list[RetrievalResult]:
-    """
-    BM25 keyword retrieval via full-text search.
-
-    Args:
-        conn: Database connection
-        query_text: Query text
-        agent_id: bank ID
-        fact_type: Fact type to filter
-        limit: Maximum results to return
-        tags: Optional list of tags for visibility filtering (OR matching)
-
-    Returns:
-        List of RetrievalResult objects
-    """
-    import re
-
-    from .tags import TagsMatch, build_tags_where_clause_simple
-
-    # Sanitize query text: remove special characters that have meaning in tsquery
-    # Keep only alphanumeric characters and spaces
-    sanitized_text = re.sub(r"[^\w\s]", " ", query_text.lower())
-
-    # Split and filter empty strings
-    tokens = [token for token in sanitized_text.split() if token]
-
-    if not tokens:
-        # If no valid tokens, return empty results
-        return []
-
-    # Convert query to tsquery using OR for more flexible matching
-    # This prevents empty results when some terms are missing
-    query_tsquery = " | ".join(tokens)
-
-    tags_clause = build_tags_where_clause_simple(tags, 5)
-    params = [query_tsquery, bank_id, fact_type, limit]
-    if tags:
-        params.append(tags)
-
-    results = await conn.fetch(
-        f"""
-        SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, embedding, fact_type, document_id, chunk_id, tags,
-               ts_rank_cd(search_vector, to_tsquery('english', $1)) AS bm25_score
-        FROM {fq_table("memory_units")}
-        WHERE bank_id = $2
-          AND fact_type = $3
-          AND search_vector @@ to_tsquery('english', $1)
-          {tags_clause}
-        ORDER BY bm25_score DESC
-        LIMIT $4
-        """,
-        *params,
-    )
-    return [RetrievalResult.from_db_row(dict(r)) for r in results]
-
-
 async def retrieve_semantic_bm25_combined(
     conn,
     query_emb_str: str,
@@ -268,18 +158,41 @@ async def retrieve_semantic_bm25_combined(
                 result_dict[ft][0].append(RetrievalResult.from_db_row(row))
         return result_dict
 
-    query_tsquery = " | ".join(tokens)
+    # Build BM25 query based on text search backend
+    config = get_config()
 
     # Build tags clause - param 6 if tags provided
     tags_clause = build_tags_where_clause_simple(tags, 6, match=tags_match)
-    params = [query_emb_str, bank_id, fact_types, limit, query_tsquery]
+
+    # Build backend-specific BM25 parts
+    if config.text_search_extension == "vchord":
+        # VectorChord BM25: use <&> operator with to_bm25query and tokenize
+        # Note: VectorChord scores are negative (higher = better, so -1 > -10)
+        bm25_score_expr = "search_vector <&> to_bm25query('idx_memory_units_text_search', tokenize($5, 'llmlingua2'))"
+        bm25_order_by = f"{bm25_score_expr} DESC"
+        bm25_where_filter = ""  # No additional WHERE filter for vchord
+        params = [query_emb_str, bank_id, fact_types, limit, query_text]  # Pass raw query_text for tokenization
+    elif config.text_search_extension == "pg_textsearch":
+        # Timescale pg_textsearch: use <@> operator with to_bm25query
+        # Note: pg_textsearch scores are negative (lower/more negative = better, so -10 > -1)
+        # We negate the score to maintain API consistency (higher = better)
+        bm25_score_expr = "-(text <@> to_bm25query($5, 'idx_memory_units_text_search'))"
+        bm25_order_by = "text <@> to_bm25query($5, 'idx_memory_units_text_search') ASC"
+        bm25_where_filter = ""  # No additional WHERE filter for pg_textsearch
+        params = [query_emb_str, bank_id, fact_types, limit, query_text]
+    else:  # native
+        # Native PostgreSQL: use ts_rank_cd with to_tsquery
+        query_tsquery = " | ".join(tokens)
+        bm25_score_expr = "ts_rank_cd(search_vector, to_tsquery('english', $5))"
+        bm25_order_by = f"{bm25_score_expr} DESC"
+        bm25_where_filter = "AND search_vector @@ to_tsquery('english', $5)"
+        params = [query_emb_str, bank_id, fact_types, limit, query_tsquery]
+
     if tags:
         params.append(tags)
 
-    # Combined CTE query for both semantic and BM25 across all fact types
-    # Uses window functions to limit per fact_type per method
-    results = await conn.fetch(
-        f"""
+    # Single query template with backend-specific parts injected
+    query = f"""
         WITH semantic_ranked AS (
             SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, embedding, fact_type, document_id, chunk_id, tags,
                    1 - (embedding <=> $1::vector) AS similarity,
@@ -296,13 +209,13 @@ async def retrieve_semantic_bm25_combined(
         bm25_ranked AS (
             SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, embedding, fact_type, document_id, chunk_id, tags,
                    NULL::float AS similarity,
-                   ts_rank_cd(search_vector, to_tsquery('english', $5)) AS bm25_score,
+                   {bm25_score_expr} AS bm25_score,
                    'bm25' AS source,
-                   ROW_NUMBER() OVER (PARTITION BY fact_type ORDER BY ts_rank_cd(search_vector, to_tsquery('english', $5)) DESC) AS rn
+                   ROW_NUMBER() OVER (PARTITION BY fact_type ORDER BY {bm25_order_by}) AS rn
             FROM {fq_table("memory_units")}
             WHERE bank_id = $2
               AND fact_type = ANY($3)
-              AND search_vector @@ to_tsquery('english', $5)
+              {bm25_where_filter}
               {tags_clause}
         ),
         semantic AS (
@@ -318,9 +231,11 @@ async def retrieve_semantic_bm25_combined(
         SELECT * FROM semantic
         UNION ALL
         SELECT * FROM bm25
-        """,
-        *params,
-    )
+    """
+
+    # Combined CTE query for both semantic and BM25 across all fact types
+    # Uses window functions to limit per fact_type per method
+    results = await conn.fetch(query, *params)
 
     # Group results by fact_type and source
     result_dict: dict[str, tuple[list[RetrievalResult], list[RetrievalResult]]] = {ft: ([], []) for ft in fact_types}
@@ -561,623 +476,6 @@ async def retrieve_temporal_combined(
     return results_by_ft
 
 
-async def retrieve_temporal(
-    conn,
-    query_emb_str: str,
-    bank_id: str,
-    fact_type: str,
-    start_date: datetime,
-    end_date: datetime,
-    budget: int,
-    semantic_threshold: float = 0.1,
-    tags: list[str] | None = None,
-) -> list[RetrievalResult]:
-    """
-    Temporal retrieval with spreading activation.
-
-    Strategy:
-    1. Find entry points (facts in date range with semantic relevance)
-    2. Spread through temporal links to related facts
-    3. Score by temporal proximity + semantic similarity + link weight
-
-    Args:
-        conn: Database connection
-        query_emb_str: Query embedding as string
-        agent_id: bank ID
-        fact_type: Fact type to filter
-        start_date: Start of time range
-        end_date: End of time range
-        budget: Node budget for spreading
-        semantic_threshold: Minimum semantic similarity to include
-        tags: Optional list of tags for visibility filtering (OR matching)
-
-    Returns:
-        List of RetrievalResult objects with temporal scores
-    """
-
-    # Ensure start_date and end_date are timezone-aware (UTC) to match database datetimes
-    if start_date.tzinfo is None:
-        start_date = start_date.replace(tzinfo=UTC)
-    if end_date.tzinfo is None:
-        end_date = end_date.replace(tzinfo=UTC)
-
-    from .tags import TagsMatch, build_tags_where_clause_simple
-
-    tags_clause = build_tags_where_clause_simple(tags, 7)
-    params = [query_emb_str, bank_id, fact_type, start_date, end_date, semantic_threshold]
-    if tags:
-        params.append(tags)
-
-    entry_points = await conn.fetch(
-        f"""
-        SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, embedding, fact_type, document_id, chunk_id, tags,
-               1 - (embedding <=> $1::vector) AS similarity
-        FROM {fq_table("memory_units")}
-        WHERE bank_id = $2
-          AND fact_type = $3
-          AND embedding IS NOT NULL
-          AND (
-              -- Match if occurred range overlaps with query range
-              (occurred_start IS NOT NULL AND occurred_end IS NOT NULL
-               AND occurred_start <= $5 AND occurred_end >= $4)
-              OR
-              -- Match if mentioned_at falls within query range
-              (mentioned_at IS NOT NULL AND mentioned_at BETWEEN $4 AND $5)
-              OR
-              -- Match if any occurred date is set and overlaps (even if only start or end is set)
-              (occurred_start IS NOT NULL AND occurred_start BETWEEN $4 AND $5)
-              OR
-              (occurred_end IS NOT NULL AND occurred_end BETWEEN $4 AND $5)
-          )
-          AND (1 - (embedding <=> $1::vector)) >= $6
-          {tags_clause}
-        ORDER BY COALESCE(occurred_start, mentioned_at, occurred_end) DESC, (embedding <=> $1::vector) ASC
-        LIMIT 10
-        """,
-        *params,
-    )
-
-    if not entry_points:
-        return []
-
-    # Calculate temporal scores for entry points
-    total_days = (end_date - start_date).total_seconds() / 86400
-    mid_date = start_date + (end_date - start_date) / 2  # Calculate once for all comparisons
-    results = []
-    visited = set()
-
-    for ep in entry_points:
-        unit_id = str(ep["id"])
-        visited.add(unit_id)
-
-        # Calculate temporal proximity using the most relevant date
-        # Priority: occurred_start/end (event time) > mentioned_at (mention time)
-        best_date = None
-        if ep["occurred_start"] is not None and ep["occurred_end"] is not None:
-            # Use midpoint of occurred range
-            best_date = ep["occurred_start"] + (ep["occurred_end"] - ep["occurred_start"]) / 2
-        elif ep["occurred_start"] is not None:
-            best_date = ep["occurred_start"]
-        elif ep["occurred_end"] is not None:
-            best_date = ep["occurred_end"]
-        elif ep["mentioned_at"] is not None:
-            best_date = ep["mentioned_at"]
-
-        # Temporal proximity score (closer to range center = higher score)
-        if best_date:
-            days_from_mid = abs((best_date - mid_date).total_seconds() / 86400)
-            temporal_proximity = 1.0 - min(days_from_mid / (total_days / 2), 1.0) if total_days > 0 else 1.0
-        else:
-            temporal_proximity = 0.5  # Fallback if no dates (shouldn't happen due to WHERE clause)
-
-        # Create RetrievalResult with temporal scores
-        ep_result = RetrievalResult.from_db_row(dict(ep))
-        ep_result.temporal_score = temporal_proximity
-        ep_result.temporal_proximity = temporal_proximity
-        results.append(ep_result)
-
-    # Spread through temporal links using BATCHED neighbor fetching
-    # Map node_id -> (semantic_sim, temporal_score) for propagation
-    node_scores = {str(ep["id"]): (ep["similarity"], 1.0) for ep in entry_points}
-    frontier = list(node_scores.keys())  # Current batch of nodes to expand
-    budget_remaining = budget - len(entry_points)
-    batch_size = 20  # Process this many nodes per DB query
-
-    while frontier and budget_remaining > 0:
-        # Take a batch from frontier
-        batch_ids = frontier[:batch_size]
-        frontier = frontier[batch_size:]
-
-        # Batch fetch all neighbors for this batch of nodes
-        neighbors = await conn.fetch(
-            f"""
-            SELECT mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start, mu.occurred_end, mu.mentioned_at, mu.embedding, mu.fact_type, mu.document_id, mu.chunk_id,
-                   ml.weight, ml.link_type, ml.from_unit_id,
-                   1 - (mu.embedding <=> $1::vector) AS similarity
-            FROM {fq_table("memory_links")} ml
-            JOIN {fq_table("memory_units")} mu ON ml.to_unit_id = mu.id
-            WHERE ml.from_unit_id = ANY($2::uuid[])
-              AND ml.link_type IN ('temporal', 'causes', 'caused_by', 'enables', 'prevents')
-              AND ml.weight >= 0.1
-              AND mu.fact_type = $3
-              AND mu.embedding IS NOT NULL
-              AND (1 - (mu.embedding <=> $1::vector)) >= $4
-            ORDER BY ml.weight DESC
-            LIMIT $5
-            """,
-            query_emb_str,
-            batch_ids,
-            fact_type,
-            semantic_threshold,
-            batch_size * 10,  # Allow up to 10 neighbors per node in batch
-        )
-
-        for n in neighbors:
-            neighbor_id = str(n["id"])
-            if neighbor_id in visited:
-                continue
-
-            visited.add(neighbor_id)
-            budget_remaining -= 1
-
-            # Get parent's scores for propagation
-            parent_id = str(n["from_unit_id"])
-            _, parent_temporal_score = node_scores.get(parent_id, (0.5, 0.5))
-
-            # Calculate temporal score for neighbor using best available date
-            neighbor_best_date = None
-            if n["occurred_start"] is not None and n["occurred_end"] is not None:
-                neighbor_best_date = n["occurred_start"] + (n["occurred_end"] - n["occurred_start"]) / 2
-            elif n["occurred_start"] is not None:
-                neighbor_best_date = n["occurred_start"]
-            elif n["occurred_end"] is not None:
-                neighbor_best_date = n["occurred_end"]
-            elif n["mentioned_at"] is not None:
-                neighbor_best_date = n["mentioned_at"]
-
-            if neighbor_best_date:
-                days_from_mid = abs((neighbor_best_date - mid_date).total_seconds() / 86400)
-                neighbor_temporal_proximity = (
-                    1.0 - min(days_from_mid / (total_days / 2), 1.0) if total_days > 0 else 1.0
-                )
-            else:
-                neighbor_temporal_proximity = 0.3  # Lower score if no temporal data
-
-            # Boost causal links (same as graph retrieval)
-            link_type = n["link_type"]
-            if link_type in ("causes", "caused_by"):
-                causal_boost = 2.0
-            elif link_type in ("enables", "prevents"):
-                causal_boost = 1.5
-            else:
-                causal_boost = 1.0
-
-            # Propagate temporal score through links (decay, with causal boost)
-            propagated_temporal = parent_temporal_score * n["weight"] * causal_boost * 0.7
-
-            # Combined temporal score
-            combined_temporal = max(neighbor_temporal_proximity, propagated_temporal)
-
-            # Create RetrievalResult with temporal scores
-            neighbor_result = RetrievalResult.from_db_row(dict(n))
-            neighbor_result.temporal_score = combined_temporal
-            neighbor_result.temporal_proximity = neighbor_temporal_proximity
-            results.append(neighbor_result)
-
-            # Track scores for propagation and add to frontier
-            if budget_remaining > 0 and combined_temporal > 0.2:
-                node_scores[neighbor_id] = (n["similarity"], combined_temporal)
-                frontier.append(neighbor_id)
-
-            if budget_remaining <= 0:
-                break
-
-    return results
-
-
-async def retrieve_parallel(
-    pool,
-    query_text: str,
-    query_embedding_str: str,
-    bank_id: str,
-    fact_type: str,
-    thinking_budget: int,
-    question_date: datetime | None = None,
-    query_analyzer: Optional["QueryAnalyzer"] = None,
-    graph_retriever: GraphRetriever | None = None,
-    temporal_constraint: tuple | None = None,  # Pre-extracted temporal constraint
-    tags: list[str] | None = None,  # Visibility scope tags for filtering
-) -> ParallelRetrievalResult:
-    """
-    Run 3-way or 4-way parallel retrieval (adds temporal if detected).
-
-    Args:
-        pool: Database connection pool
-        query_text: Query text
-        query_embedding_str: Query embedding as string
-        bank_id: Bank ID
-        fact_type: Fact type to filter
-        thinking_budget: Budget for graph traversal and retrieval limits
-        question_date: Optional date when question was asked (for temporal filtering)
-        query_analyzer: Query analyzer to use (defaults to TransformerQueryAnalyzer)
-        graph_retriever: Graph retrieval strategy (defaults to configured retriever)
-        temporal_constraint: Pre-extracted temporal constraint (optional)
-        tags: Optional list of tags for visibility filtering (OR matching)
-
-    Returns:
-        ParallelRetrievalResult with semantic, bm25, graph, temporal results and timings
-    """
-    retriever = graph_retriever or get_default_graph_retriever()
-
-    # Use optimized parallel path for MPFP and LinkExpansion (runs all methods truly in parallel)
-    # BFS uses legacy path that extracts temporal constraint upfront
-    if retriever.name in ("mpfp", "link_expansion"):
-        return await _retrieve_parallel_mpfp(
-            pool,
-            query_text,
-            query_embedding_str,
-            bank_id,
-            fact_type,
-            thinking_budget,
-            temporal_constraint,
-            retriever,
-            question_date,
-            query_analyzer,
-            tags=tags,
-        )
-    else:
-        # For BFS, extract temporal constraint upfront (legacy path)
-        if temporal_constraint is None:
-            from .temporal_extraction import extract_temporal_constraint
-
-            temporal_constraint = extract_temporal_constraint(
-                query_text, reference_date=question_date, analyzer=query_analyzer
-            )
-        return await _retrieve_parallel_bfs(
-            pool,
-            query_text,
-            query_embedding_str,
-            bank_id,
-            fact_type,
-            thinking_budget,
-            temporal_constraint,
-            retriever,
-            tags=tags,
-        )
-
-
-@dataclass
-class _TimedResult:
-    """Internal result with timing."""
-
-    results: list[RetrievalResult]
-    time: float
-    conn_wait: float = 0.0  # Connection acquisition wait time
-
-
-async def _retrieve_parallel_mpfp(
-    pool,
-    query_text: str,
-    query_embedding_str: str,
-    bank_id: str,
-    fact_type: str,
-    thinking_budget: int,
-    temporal_constraint: tuple | None,
-    retriever: GraphRetriever,
-    question_date: datetime | None = None,
-    query_analyzer=None,
-    tags: list[str] | None = None,
-) -> ParallelRetrievalResult:
-    """
-    MPFP retrieval with true parallelization.
-
-    All methods run independently in parallel:
-    - Semantic: vector similarity search
-    - BM25: keyword search
-    - Graph: MPFP traversal (does its own semantic seeds internally)
-    - Temporal: date extraction (if needed) + date-range search
-
-    Temporal extraction runs IN PARALLEL with other retrievals, so even if
-    dateparser is slow, it doesn't block semantic/BM25/graph.
-    """
-    import time
-
-    async def run_semantic() -> _TimedResult:
-        """Independent semantic retrieval."""
-        start = time.time()
-        acquire_start = time.time()
-        async with acquire_with_retry(pool) as conn:
-            conn_wait = time.time() - acquire_start
-            results = await retrieve_semantic(
-                conn, query_embedding_str, bank_id, fact_type, limit=thinking_budget, tags=tags
-            )
-        return _TimedResult(results, time.time() - start, conn_wait)
-
-    async def run_bm25() -> _TimedResult:
-        """Independent BM25 retrieval."""
-        start = time.time()
-        acquire_start = time.time()
-        async with acquire_with_retry(pool) as conn:
-            conn_wait = time.time() - acquire_start
-            results = await retrieve_bm25(conn, query_text, bank_id, fact_type, limit=thinking_budget, tags=tags)
-        return _TimedResult(results, time.time() - start, conn_wait)
-
-    async def run_graph() -> tuple[list[RetrievalResult], float, MPFPTimings | None]:
-        """Independent graph retrieval - does its own semantic seeds."""
-        start = time.time()
-
-        # MPFP does its own semantic seeds via _find_semantic_seeds
-        # Note: temporal_seeds not used here to avoid dependency on temporal extraction
-        results, mpfp_timing = await retriever.retrieve(
-            pool=pool,
-            query_embedding_str=query_embedding_str,
-            bank_id=bank_id,
-            fact_type=fact_type,
-            budget=thinking_budget,
-            query_text=query_text,
-            semantic_seeds=None,  # Let MPFP find its own seeds
-            temporal_seeds=None,  # Don't wait for temporal extraction
-            tags=tags,
-        )
-        return results, time.time() - start, mpfp_timing
-
-    @dataclass
-    class _TemporalWithConstraint:
-        """Temporal results with the extracted constraint."""
-
-        results: list[RetrievalResult]
-        time: float
-        constraint: tuple | None
-        extraction_time: float  # Time spent in query analyzer (dateparser)
-        conn_wait: float = 0.0  # Connection acquisition wait time
-
-    async def run_temporal_with_extraction() -> _TemporalWithConstraint:
-        """
-        Extract temporal constraint AND run temporal retrieval.
-
-        This runs in parallel with semantic/BM25/graph, so dateparser
-        latency doesn't block other retrievals.
-        """
-        start = time.time()
-
-        # Use pre-provided constraint if available
-        tc = temporal_constraint
-        extraction_time = 0.0
-
-        # Otherwise extract from query (this is the potentially slow dateparser call)
-        if tc is None:
-            from .temporal_extraction import extract_temporal_constraint
-
-            extraction_start = time.time()
-            tc = extract_temporal_constraint(query_text, reference_date=question_date, analyzer=query_analyzer)
-            extraction_time = time.time() - extraction_start
-
-        # If no temporal constraint found, return empty (but still report extraction time)
-        if tc is None:
-            return _TemporalWithConstraint([], time.time() - start, None, extraction_time, 0.0)
-
-        # Run temporal retrieval with the extracted constraint
-        tc_start, tc_end = tc
-        acquire_start = time.time()
-        async with acquire_with_retry(pool) as conn:
-            conn_wait = time.time() - acquire_start
-            results = await retrieve_temporal(
-                conn,
-                query_embedding_str,
-                bank_id,
-                fact_type,
-                tc_start,
-                tc_end,
-                budget=thinking_budget,
-                semantic_threshold=0.1,
-            )
-        return _TemporalWithConstraint(results, time.time() - start, tc, extraction_time, conn_wait)
-
-    # Run ALL methods in parallel (including temporal extraction!)
-    semantic_result, bm25_result, graph_result, temporal_result = await asyncio.gather(
-        run_semantic(),
-        run_bm25(),
-        run_graph(),
-        run_temporal_with_extraction(),
-    )
-    graph_results, graph_time, mpfp_timing = graph_result
-
-    # Compute max connection wait across all methods (graph handles its own connections)
-    max_conn_wait = max(semantic_result.conn_wait, bm25_result.conn_wait, temporal_result.conn_wait)
-
-    return ParallelRetrievalResult(
-        semantic=semantic_result.results,
-        bm25=bm25_result.results,
-        graph=graph_results,
-        temporal=temporal_result.results if temporal_result.results else None,
-        timings={
-            "semantic": semantic_result.time,
-            "bm25": bm25_result.time,
-            "graph": graph_time,
-            "temporal": temporal_result.time,
-            "temporal_extraction": temporal_result.extraction_time,
-        },
-        temporal_constraint=temporal_result.constraint,
-        mpfp_timings=[mpfp_timing] if mpfp_timing else [],
-        max_conn_wait=max_conn_wait,
-    )
-
-
-async def _get_temporal_entry_points(
-    conn,
-    query_embedding_str: str,
-    bank_id: str,
-    fact_type: str,
-    start_date: datetime,
-    end_date: datetime,
-    limit: int = 20,
-    semantic_threshold: float = 0.1,
-) -> list[RetrievalResult]:
-    """Get temporal entry points (facts in date range with semantic relevance)."""
-
-    if start_date.tzinfo is None:
-        start_date = start_date.replace(tzinfo=UTC)
-    if end_date.tzinfo is None:
-        end_date = end_date.replace(tzinfo=UTC)
-
-    rows = await conn.fetch(
-        f"""
-        SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at,
-               embedding, fact_type, document_id, chunk_id,
-               1 - (embedding <=> $1::vector) AS similarity
-        FROM {fq_table("memory_units")}
-        WHERE bank_id = $2
-          AND fact_type = $3
-          AND embedding IS NOT NULL
-          AND (
-              (occurred_start IS NOT NULL AND occurred_end IS NOT NULL
-               AND occurred_start <= $5 AND occurred_end >= $4)
-              OR (mentioned_at IS NOT NULL AND mentioned_at BETWEEN $4 AND $5)
-              OR (occurred_start IS NOT NULL AND occurred_start BETWEEN $4 AND $5)
-              OR (occurred_end IS NOT NULL AND occurred_end BETWEEN $4 AND $5)
-          )
-          AND (1 - (embedding <=> $1::vector)) >= $6
-        ORDER BY COALESCE(occurred_start, mentioned_at, occurred_end) DESC,
-                 (embedding <=> $1::vector) ASC
-        LIMIT $7
-        """,
-        query_embedding_str,
-        bank_id,
-        fact_type,
-        start_date,
-        end_date,
-        semantic_threshold,
-        limit,
-    )
-
-    results = []
-    total_days = max((end_date - start_date).total_seconds() / 86400, 1)
-    mid_date = start_date + (end_date - start_date) / 2
-
-    for row in rows:
-        result = RetrievalResult.from_db_row(dict(row))
-
-        # Calculate temporal proximity score
-        best_date = None
-        if row["occurred_start"] and row["occurred_end"]:
-            best_date = row["occurred_start"] + (row["occurred_end"] - row["occurred_start"]) / 2
-        elif row["occurred_start"]:
-            best_date = row["occurred_start"]
-        elif row["occurred_end"]:
-            best_date = row["occurred_end"]
-        elif row["mentioned_at"]:
-            best_date = row["mentioned_at"]
-
-        if best_date:
-            days_from_mid = abs((best_date - mid_date).total_seconds() / 86400)
-            result.temporal_proximity = 1.0 - min(days_from_mid / (total_days / 2), 1.0)
-        else:
-            result.temporal_proximity = 0.5
-
-        result.temporal_score = result.temporal_proximity
-        results.append(result)
-
-    return results
-
-
-async def _retrieve_parallel_bfs(
-    pool,
-    query_text: str,
-    query_embedding_str: str,
-    bank_id: str,
-    fact_type: str,
-    thinking_budget: int,
-    temporal_constraint: tuple | None,
-    retriever: GraphRetriever,
-    tags: list[str] | None = None,
-) -> ParallelRetrievalResult:
-    """BFS retrieval: all methods run in parallel (original behavior)."""
-    import time
-
-    async def run_semantic() -> _TimedResult:
-        start = time.time()
-        async with acquire_with_retry(pool) as conn:
-            results = await retrieve_semantic(
-                conn, query_embedding_str, bank_id, fact_type, limit=thinking_budget, tags=tags
-            )
-        return _TimedResult(results, time.time() - start)
-
-    async def run_bm25() -> _TimedResult:
-        start = time.time()
-        async with acquire_with_retry(pool) as conn:
-            results = await retrieve_bm25(conn, query_text, bank_id, fact_type, limit=thinking_budget, tags=tags)
-        return _TimedResult(results, time.time() - start)
-
-    async def run_graph() -> _TimedResult:
-        start = time.time()
-        results, _ = await retriever.retrieve(
-            pool=pool,
-            query_embedding_str=query_embedding_str,
-            bank_id=bank_id,
-            fact_type=fact_type,
-            budget=thinking_budget,
-            query_text=query_text,
-            tags=tags,
-        )
-        return _TimedResult(results, time.time() - start)
-
-    async def run_temporal(tc_start, tc_end) -> _TimedResult:
-        start = time.time()
-        async with acquire_with_retry(pool) as conn:
-            results = await retrieve_temporal(
-                conn,
-                query_embedding_str,
-                bank_id,
-                fact_type,
-                tc_start,
-                tc_end,
-                budget=thinking_budget,
-                semantic_threshold=0.1,
-                tags=tags,
-            )
-        return _TimedResult(results, time.time() - start)
-
-    if temporal_constraint:
-        tc_start, tc_end = temporal_constraint
-        semantic_r, bm25_r, graph_r, temporal_r = await asyncio.gather(
-            run_semantic(),
-            run_bm25(),
-            run_graph(),
-            run_temporal(tc_start, tc_end),
-        )
-        return ParallelRetrievalResult(
-            semantic=semantic_r.results,
-            bm25=bm25_r.results,
-            graph=graph_r.results,
-            temporal=temporal_r.results,
-            timings={
-                "semantic": semantic_r.time,
-                "bm25": bm25_r.time,
-                "graph": graph_r.time,
-                "temporal": temporal_r.time,
-            },
-            temporal_constraint=temporal_constraint,
-        )
-    else:
-        semantic_r, bm25_r, graph_r = await asyncio.gather(
-            run_semantic(),
-            run_bm25(),
-            run_graph(),
-        )
-        return ParallelRetrievalResult(
-            semantic=semantic_r.results,
-            bm25=bm25_r.results,
-            graph=graph_r.results,
-            temporal=None,
-            timings={
-                "semantic": semantic_r.time,
-                "bm25": bm25_r.time,
-                "graph": graph_r.time,
-            },
-            temporal_constraint=None,
-        )
-
-
 async def retrieve_all_fact_types_parallel(
     pool,
     query_text: str,

hindsight-api/hindsight_api/engine/search/think_utils.py

@@ -188,7 +188,7 @@ def get_system_message(disposition: DispositionTraits) -> str:
         " ".join(instructions) if instructions else "Balance your disposition traits when interpreting information."
     )
 
-    return f"You are a person with your own thoughts, experiences, opinions, and disposition. When asked a question, respond naturally like a human would - share what you genuinely think based on what you know and have experienced. {disposition_instruction} Be direct, express your views confidently, and use 'I think', 'I believe', 'in my view', etc. Respond in plain text without markdown formatting. IMPORTANT: Detect the language of the question and respond in the SAME language. Do not translate to English if the question is in another language."
+    return f"You are a person with your own thoughts, experiences, opinions, and disposition. When asked a question, respond naturally like a human would - share what you genuinely think based on what you know and have experienced. {disposition_instruction} Be direct, express your views confidently, and use 'I think', 'I believe', 'in my view', etc. Respond in plain text without markdown formatting. CRITICAL: ONLY use the facts and information provided in the prompt - do not make up names, events, or information that weren't mentioned. If you don't have enough information to answer, say so. IMPORTANT: Detect the language of the question and respond in the SAME language. Do not translate to English if the question is in another language."
 
 
 async def reflect(

hindsight-api/hindsight_api/engine/utils.py

@@ -19,6 +19,7 @@ async def extract_facts(
     context: str = "",
     llm_config: "LLMConfig" = None,
     agent_name: str = None,
+    config=None,
 ) -> tuple[list["Fact"], list[tuple[str, int]]]:
     """
     Extract semantic facts from text using LLM.
@@ -35,6 +36,7 @@ async def extract_facts(
         context: Context about the conversation/document
         llm_config: LLM configuration to use
         agent_name: Optional agent name to help identify agent-related facts
+        config: HindsightConfig to use (defaults to global config if not provided)
 
     Returns:
         Tuple of (facts, chunks) where:
@@ -47,12 +49,19 @@ async def extract_facts(
     if not text or not text.strip():
         return [], []
 
+    # Use provided config or fall back to global config
+    if config is None:
+        from ..config import _get_raw_config
+
+        config = _get_raw_config()
+
     facts, chunks, _ = await extract_facts_from_text(
         text,
         event_date,
-        context=context,
         llm_config=llm_config,
         agent_name=agent_name,
+        config=config,
+        context=context,
     )
 
     if not facts:

hindsight-api/hindsight_api/extensions/__init__.py

@@ -16,10 +16,11 @@ with the system (e.g., running migrations for tenant schemas).
 """
 
 from hindsight_api.extensions.base import Extension
-from hindsight_api.extensions.builtin import ApiKeyTenantExtension
+from hindsight_api.extensions.builtin import ApiKeyTenantExtension, SupabaseTenantExtension
 from hindsight_api.extensions.context import DefaultExtensionContext, ExtensionContext
 from hindsight_api.extensions.http import HttpExtension
 from hindsight_api.extensions.loader import load_extension
+from hindsight_api.extensions.mcp import MCPExtension
 from hindsight_api.extensions.operation_validator import (
     # Consolidation operation
     ConsolidateContext,
@@ -57,6 +58,8 @@ __all__ = [
     "DefaultExtensionContext",
     # HTTP Extension
     "HttpExtension",
+    # MCP Extension
+    "MCPExtension",
     # Operation Validator - Core
     "OperationValidationError",
     "OperationValidatorExtension",
@@ -77,6 +80,7 @@ __all__ = [
     "MentalModelRefreshResult",
     # Tenant/Auth
     "ApiKeyTenantExtension",
+    "SupabaseTenantExtension",
     "AuthenticationError",
     "RequestContext",
     "Tenant",

hindsight-api/hindsight_api/extensions/builtin/__init__.py

@@ -6,13 +6,17 @@ They can be used directly or serve as examples for custom implementations.
 
 Available built-in extensions:
     - ApiKeyTenantExtension: Simple API key validation with public schema
+    - SupabaseTenantExtension: Supabase JWT validation with per-user schema isolation
 
 Example usage:
     HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.tenant:ApiKeyTenantExtension
+    HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.supabase_tenant:SupabaseTenantExtension
 """
 
+from hindsight_api.extensions.builtin.supabase_tenant import SupabaseTenantExtension
 from hindsight_api.extensions.builtin.tenant import ApiKeyTenantExtension
 
 __all__ = [
     "ApiKeyTenantExtension",
+    "SupabaseTenantExtension",
 ]

hindsight-api/hindsight_api/extensions/builtin/supabase_tenant.py

@@ -0,0 +1,433 @@
+"""
+Supabase Tenant Extension for Hindsight
+
+Validates Supabase JWTs and maps authenticated users to isolated memory banks.
+Each user gets their own PostgreSQL schema based on their Supabase user ID.
+
+This extension enables multi-tenant memory isolation for applications using
+Supabase Auth - each authenticated user's memories are stored in a separate
+schema, ensuring complete data isolation.
+
+Features:
+    - Local JWT Verification: Validates tokens locally using JWKS public keys
+      (no network call per request)
+    - Automatic Schema Isolation: Each user gets {prefix}_{user_id} schema
+    - Zero User Management: Leverages your existing Supabase Auth setup
+    - Production Ready: Includes health checks, timeouts, key rotation handling,
+      and error handling
+    - Built-in: Ships with Hindsight, no extra installation needed
+    - Legacy Support: Falls back to /auth/v1/user endpoint for HS256 projects
+
+JWT Verification Strategy:
+    By default, JWTs are verified locally using public keys from the Supabase
+    JWKS endpoint (/auth/v1/.well-known/jwks.json). This is the Supabase-recommended
+    approach: no network call per request, fast, and secure.
+
+    If JWKS keys are unavailable (e.g., legacy HS256 projects), the extension
+    falls back to calling /auth/v1/user per request for validation. This requires
+    the service_role key to be configured.
+
+Configuration via environment variables:
+    HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.supabase_tenant:SupabaseTenantExtension
+    HINDSIGHT_API_TENANT_SUPABASE_URL=https://your-project.supabase.co
+
+    # Optional - only required for legacy HS256 projects or health checks
+    HINDSIGHT_API_TENANT_SUPABASE_SERVICE_KEY=your-service-role-key
+
+    # Optional
+    HINDSIGHT_API_TENANT_SCHEMA_PREFIX=user  # Default: "user" (creates user_<uuid> schemas)
+
+Usage:
+    Clients pass their Supabase JWT in the Authorization header:
+
+    curl -H "Authorization: Bearer <supabase_jwt>" \\
+        https://your-hindsight-server/v1/default/banks/my-bank/memories/recall
+
+Author: BrighterBalance (https://brighterbalance.app)
+License: MIT
+"""
+
+from __future__ import annotations
+
+import logging
+import re
+import time
+
+import httpx
+import jwt as pyjwt
+from jwt import PyJWK
+
+from hindsight_api.extensions.tenant import AuthenticationError, Tenant, TenantContext, TenantExtension
+from hindsight_api.models import RequestContext
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["SupabaseTenantExtension"]
+
+# Minimum expected JWT length (JWTs are typically 100+ characters)
+MIN_TOKEN_LENGTH = 20
+
+# Timeout for Supabase API calls
+REQUEST_TIMEOUT_SECONDS = 10.0
+
+# JWKS cache TTL — Supabase Edge caches JWKS for 10 minutes, so we match that
+JWKS_CACHE_TTL_SECONDS = 600
+
+# Minimum interval between JWKS refreshes to avoid hammering the endpoint
+JWKS_MIN_REFRESH_INTERVAL_SECONDS = 30
+
+# Algorithms supported by Supabase Auth for asymmetric JWT signing
+SUPPORTED_ALGORITHMS = ["RS256", "ES256"]
+
+# Supabase user IDs are UUIDs — validate before using in schema names
+_UUID_RE = re.compile(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", re.IGNORECASE)
+
+# Schema prefix must be a valid Postgres identifier component (letters, digits, underscores)
+_SCHEMA_PREFIX_RE = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+
+
+class SupabaseTenantExtension(TenantExtension):
+    """
+    TenantExtension that validates Supabase JWTs for multi-tenant isolation.
+
+    Each authenticated user gets their own PostgreSQL schema, ensuring complete
+    memory isolation between users. The schema name is derived from the user's
+    Supabase user ID (the ``sub`` claim in the JWT).
+
+    JWT verification uses JWKS (local, no network call per request) when
+    asymmetric keys are configured in Supabase, and falls back to the
+    ``/auth/v1/user`` endpoint for legacy HS256 projects.
+
+    Example:
+        User with ID "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
+        gets schema "user_a1b2c3d4_e5f6_7890_abcd_ef1234567890"
+    """
+
+    def __init__(self, config: dict[str, str]) -> None:
+        """
+        Initialize with configuration from environment variables.
+
+        Config keys are derived from HINDSIGHT_API_TENANT_* env vars:
+        - HINDSIGHT_API_TENANT_SUPABASE_URL -> config["supabase_url"] (required)
+        - HINDSIGHT_API_TENANT_SUPABASE_SERVICE_KEY -> config["supabase_service_key"] (optional)
+        - HINDSIGHT_API_TENANT_SCHEMA_PREFIX -> config["schema_prefix"] (optional)
+
+        Args:
+            config: Dictionary of configuration values from environment
+
+        Raises:
+            ValueError: If required configuration is missing
+        """
+        super().__init__(config)
+
+        self.supabase_url = (config.get("supabase_url") or "").rstrip("/")
+        self.supabase_service_key = config.get("supabase_service_key")
+        self.schema_prefix = config.get("schema_prefix", "user")
+
+        # Track initialized schemas to avoid redundant migrations
+        self._initialized_schemas: set[str] = set()
+
+        # Reusable HTTP client (created on startup)
+        self._http_client: httpx.AsyncClient | None = None
+
+        # JWKS state
+        self._jwks_keys: dict[str, PyJWK] = {}
+        self._jwks_last_fetched: float = 0
+        self._use_jwks: bool = False
+
+        if not self.supabase_url:
+            raise ValueError(
+                "HINDSIGHT_API_TENANT_SUPABASE_URL is required. "
+                "Set it to your Supabase project URL (e.g., https://xxx.supabase.co)"
+            )
+
+        if not _SCHEMA_PREFIX_RE.match(self.schema_prefix):
+            raise ValueError(
+                f"Invalid schema_prefix '{self.schema_prefix}'. "
+                "Must be a valid Postgres identifier (letters, digits, underscores, starting with a letter or underscore)."
+            )
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    async def on_startup(self) -> None:
+        """
+        Called when Hindsight starts.
+
+        Creates a reusable HTTP client, fetches JWKS for local JWT verification,
+        and optionally verifies connectivity to Supabase.
+        """
+        logger.info("Initializing Supabase tenant extension")
+        logger.info("Supabase URL: %s", self.supabase_url)
+        logger.info("Schema prefix: %s_", self.schema_prefix)
+
+        self._http_client = httpx.AsyncClient(timeout=REQUEST_TIMEOUT_SECONDS)
+
+        # Attempt to fetch JWKS for fast local JWT verification
+        await self._try_init_jwks()
+
+        # Optional health check using service key
+        if self.supabase_service_key:
+            await self._health_check()
+
+    async def on_shutdown(self) -> None:
+        """Called when Hindsight shuts down. Closes the HTTP client."""
+        logger.info("Shutting down Supabase tenant extension")
+        if self._http_client:
+            await self._http_client.aclose()
+            self._http_client = None
+
+    # ------------------------------------------------------------------
+    # JWKS management
+    # ------------------------------------------------------------------
+
+    async def _try_init_jwks(self) -> None:
+        """Fetch JWKS and decide verification mode (local JWKS vs legacy endpoint)."""
+        try:
+            await self._fetch_jwks()
+            if self._jwks_keys:
+                self._use_jwks = True
+                logger.info(
+                    "JWKS loaded — using local JWT verification with %d key(s)",
+                    len(self._jwks_keys),
+                )
+                return
+
+            # JWKS endpoint returned no keys — project likely uses legacy HS256
+            logger.warning(
+                "JWKS endpoint returned no signing keys. "
+                "Falling back to /auth/v1/user endpoint for JWT verification. "
+                "For better performance, enable asymmetric JWT signing in your "
+                "Supabase dashboard (Project Settings → Auth → JWT Algorithm)."
+            )
+        except Exception as e:
+            logger.warning(
+                "Could not fetch JWKS (%s). Falling back to /auth/v1/user endpoint for JWT verification.",
+                e,
+            )
+
+        # Legacy mode requires service key
+        if not self.supabase_service_key:
+            raise ValueError(
+                "HINDSIGHT_API_TENANT_SUPABASE_SERVICE_KEY is required when JWKS "
+                "is not available. Either enable asymmetric JWT signing in your "
+                "Supabase project or provide the service_role key."
+            )
+        self._use_jwks = False
+
+    async def _fetch_jwks(self) -> None:
+        """Fetch public signing keys from the Supabase JWKS endpoint."""
+        if self._http_client is None:
+            raise RuntimeError("HTTP client not initialized")
+
+        url = f"{self.supabase_url}/auth/v1/.well-known/jwks.json"
+        response = await self._http_client.get(url)
+        response.raise_for_status()
+
+        jwks_data = response.json()
+        keys: dict[str, PyJWK] = {}
+        for key_data in jwks_data.get("keys", []):
+            kid = key_data.get("kid")
+            if kid:
+                keys[kid] = PyJWK(key_data)
+
+        self._jwks_keys = keys
+        self._jwks_last_fetched = time.monotonic()
+
+    async def _get_signing_key(self, token: str) -> PyJWK:
+        """
+        Resolve the signing key for a token from the JWKS cache.
+
+        If the key ID (``kid``) is not in the cache, triggers one JWKS refresh
+        to handle key rotation before raising an error.
+        """
+        header = pyjwt.get_unverified_header(token)
+        kid = header.get("kid")
+        if not kid:
+            raise AuthenticationError("Token missing key ID (kid) header")
+
+        # Refresh cache if stale
+        now = time.monotonic()
+        if now - self._jwks_last_fetched > JWKS_CACHE_TTL_SECONDS:
+            logger.debug("JWKS cache expired, refreshing")
+            await self._fetch_jwks()
+
+        if kid in self._jwks_keys:
+            return self._jwks_keys[kid]
+
+        # Key not found — try one forced refresh to handle key rotation,
+        # but only if we haven't just refreshed
+        if now - self._jwks_last_fetched > JWKS_MIN_REFRESH_INTERVAL_SECONDS:
+            logger.info("Signing key %s not in cache, refreshing JWKS for possible key rotation", kid)
+            await self._fetch_jwks()
+            if kid in self._jwks_keys:
+                return self._jwks_keys[kid]
+
+        raise AuthenticationError("Unable to find signing key for token")
+
+    # ------------------------------------------------------------------
+    # Authentication
+    # ------------------------------------------------------------------
+
+    async def authenticate(self, context: RequestContext) -> TenantContext:
+        """
+        Validate a Supabase JWT and return tenant context.
+
+        Uses local JWKS verification when available (no network call per
+        request), falling back to the ``/auth/v1/user`` endpoint for legacy
+        HS256 projects.
+
+        Args:
+            context: Request context containing the API key (JWT)
+
+        Returns:
+            TenantContext with schema_name set to ``{prefix}_{user_uuid}``
+
+        Raises:
+            AuthenticationError: If token is missing, invalid, or expired
+        """
+        token = context.api_key
+
+        if not token:
+            raise AuthenticationError("Missing Authorization header. Expected: Bearer <supabase_jwt>")
+
+        if len(token) < MIN_TOKEN_LENGTH:
+            raise AuthenticationError("Invalid token format")
+
+        if self._http_client is None:
+            raise AuthenticationError("Extension not initialized")
+
+        # Verify the JWT and extract user ID
+        if self._use_jwks:
+            user_id = await self._verify_token_jwks(token)
+        else:
+            user_id = await self._verify_token_legacy(token)
+
+        # Validate user ID format before using in schema name
+        if not _UUID_RE.match(user_id):
+            raise AuthenticationError("Invalid user ID format in token")
+
+        # Build isolated schema name — hyphens to underscores for Postgres compatibility
+        safe_user_id = user_id.replace("-", "_")
+        schema_name = f"{self.schema_prefix}_{safe_user_id}"
+
+        # Initialize schema on first access
+        if schema_name not in self._initialized_schemas:
+            await self._initialize_schema(schema_name)
+
+        return TenantContext(schema_name=schema_name)
+
+    async def _verify_token_jwks(self, token: str) -> str:
+        """
+        Verify a JWT locally using cached JWKS public keys.
+
+        Validates signature, expiration, issuer, and audience. Returns the
+        user ID from the ``sub`` claim.
+
+        Raises:
+            AuthenticationError: If the token is invalid or expired.
+        """
+        try:
+            signing_key = await self._get_signing_key(token)
+            payload = pyjwt.decode(
+                token,
+                signing_key.key,
+                algorithms=SUPPORTED_ALGORITHMS,
+                audience="authenticated",
+                issuer=f"{self.supabase_url}/auth/v1",
+            )
+        except pyjwt.ExpiredSignatureError:
+            raise AuthenticationError("Token has expired")
+        except pyjwt.InvalidAudienceError:
+            raise AuthenticationError("Invalid token audience")
+        except pyjwt.InvalidIssuerError:
+            raise AuthenticationError("Invalid token issuer")
+        except pyjwt.DecodeError:
+            raise AuthenticationError("Invalid token")
+        except AuthenticationError:
+            raise
+        except Exception as e:
+            raise AuthenticationError(f"Token verification failed: {e!s}")
+
+        user_id = payload.get("sub")
+        if not user_id:
+            raise AuthenticationError("Token valid but missing subject (sub) claim")
+        return user_id
+
+    async def _verify_token_legacy(self, token: str) -> str:
+        """
+        Verify a JWT by calling the Supabase ``/auth/v1/user`` endpoint.
+
+        This is the fallback for projects using legacy HS256 JWT signing.
+        Adds a network round-trip per request.
+
+        Raises:
+            AuthenticationError: If the token is invalid or the request fails.
+        """
+        try:
+            response = await self._http_client.get(
+                f"{self.supabase_url}/auth/v1/user",
+                headers={
+                    "Authorization": f"Bearer {token}",
+                    "apikey": self.supabase_service_key,
+                },
+            )
+
+            if response.status_code == 401:
+                raise AuthenticationError("Invalid or expired token")
+
+            if response.status_code != 200:
+                raise AuthenticationError(f"Authentication failed: {response.status_code}")
+
+            user_data = response.json()
+            user_id = user_data.get("id")
+
+            if not user_id:
+                raise AuthenticationError("Token valid but no user ID found")
+
+            return user_id
+
+        except AuthenticationError:
+            raise
+        except httpx.TimeoutException:
+            raise AuthenticationError("Authentication timeout - please retry")
+        except httpx.RequestError as e:
+            raise AuthenticationError(f"Connection error: {e!s}")
+
+    # ------------------------------------------------------------------
+    # Schema management
+    # ------------------------------------------------------------------
+
+    async def _initialize_schema(self, schema_name: str) -> None:
+        """Run migrations for a new tenant schema and cache the result."""
+        logger.info("Initializing schema: %s", schema_name)
+        try:
+            await self.context.run_migration(schema_name)
+            self._initialized_schemas.add(schema_name)
+            logger.info("Schema ready: %s", schema_name)
+        except Exception as e:
+            logger.error("Schema initialization failed for %s: %s", schema_name, e)
+            raise AuthenticationError(f"Failed to initialize tenant: {e!s}")
+
+    async def list_tenants(self) -> list[Tenant]:
+        """Return all tenant schemas that have been initialized."""
+        return [Tenant(schema=schema) for schema in self._initialized_schemas]
+
+    # ------------------------------------------------------------------
+    # Health check
+    # ------------------------------------------------------------------
+
+    async def _health_check(self) -> None:
+        """Verify connectivity to Supabase using the auth health endpoint."""
+        try:
+            response = await self._http_client.get(
+                f"{self.supabase_url}/auth/v1/health",
+                headers={"apikey": self.supabase_service_key},
+            )
+            if response.status_code == 200:
+                logger.info("Supabase connection verified")
+            else:
+                logger.warning("Supabase health check returned %d", response.status_code)
+        except Exception as e:
+            logger.warning("Could not verify Supabase connection: %s", e)

hindsight-api/hindsight_api/extensions/builtin/tenant.py

@@ -54,6 +54,7 @@ class ApiKeyTenantExtension(TenantExtension):
         HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.tenant:ApiKeyTenantExtension
         HINDSIGHT_API_TENANT_API_KEY=your-secret-key
         HINDSIGHT_API_DATABASE_SCHEMA=your-schema (optional, defaults to 'public')
+        HINDSIGHT_API_TENANT_MCP_AUTH_DISABLED=true (optional, disable auth for MCP endpoints)
 
     For multi-tenant setups with separate schemas per tenant, implement a custom
     TenantExtension that looks up the schema based on the API key or token claims.
@@ -64,6 +65,8 @@ class ApiKeyTenantExtension(TenantExtension):
         self.expected_api_key = config.get("api_key")
         if not self.expected_api_key:
             raise ValueError("HINDSIGHT_API_TENANT_API_KEY is required when using ApiKeyTenantExtension")
+        # Allow disabling MCP auth for backwards compatibility
+        self.mcp_auth_disabled = config.get("mcp_auth_disabled", "").lower() in ("true", "1", "yes")
 
     async def authenticate(self, context: RequestContext) -> TenantContext:
         """Validate API key and return configured schema context."""
@@ -74,3 +77,14 @@ class ApiKeyTenantExtension(TenantExtension):
     async def list_tenants(self) -> list[Tenant]:
         """Return configured schema for single-tenant setup."""
         return [Tenant(schema=get_config().database_schema)]
+
+    async def authenticate_mcp(self, context: RequestContext) -> TenantContext:
+        """
+        Authenticate MCP requests.
+
+        If mcp_auth_disabled is set, skip authentication for backwards compatibility.
+        Otherwise, delegate to authenticate().
+        """
+        if self.mcp_auth_disabled:
+            return TenantContext(schema_name=get_config().database_schema)
+        return await self.authenticate(context)

hindsight-api/hindsight_api/extensions/context.py

@@ -96,7 +96,13 @@ class DefaultExtensionContext(ExtensionContext):
 
     async def run_migration(self, schema: str) -> None:
         """Run migrations for a specific schema."""
-        from hindsight_api.migrations import ensure_embedding_dimension, run_migrations
+        from hindsight_api.config import get_config
+        from hindsight_api.migrations import (
+            ensure_embedding_dimension,
+            ensure_text_search_extension,
+            ensure_vector_extension,
+            run_migrations,
+        )
 
         # Prefer getting URL from memory engine (handles pg0 case where URL is set after init)
         db_url = self._database_url
@@ -107,6 +113,9 @@ class DefaultExtensionContext(ExtensionContext):
 
         run_migrations(db_url, schema=schema)
 
+        # Get config for vector extension setting
+        config = get_config()
+
         # Ensure embedding column dimension matches the model's dimension
         # This is needed because migrations create columns with default dimension
         if self._memory_engine is not None:
@@ -114,7 +123,15 @@ class DefaultExtensionContext(ExtensionContext):
             if embeddings is not None:
                 dimension = getattr(embeddings, "dimension", None)
                 if dimension is not None:
-                    ensure_embedding_dimension(db_url, dimension, schema=schema)
+                    ensure_embedding_dimension(
+                        db_url, dimension, schema=schema, vector_extension=config.vector_extension
+                    )
+
+        # Ensure vector indexes match the configured extension
+        ensure_vector_extension(db_url, vector_extension=config.vector_extension, schema=schema)
+
+        # Ensure text search columns/indexes match the configured extension
+        ensure_text_search_extension(db_url, text_search_extension=config.text_search_extension, schema=schema)
 
     def get_memory_engine(self) -> "MemoryEngineInterface":
         """Get the memory engine interface."""

hindsight-api/hindsight_api/extensions/mcp.py

@@ -0,0 +1,42 @@
+"""MCP Extension for registering additional MCP tools.
+
+This extension allows external packages (like hindsight-cloud) to register
+additional MCP tools on the Hindsight MCP server.
+
+Example:
+    HINDSIGHT_API_MCP_EXTENSION=hindsight_cloud.extensions:CloudMCPExtension
+"""
+
+import logging
+from abc import abstractmethod
+
+from fastmcp import FastMCP
+
+from hindsight_api import MemoryEngine
+from hindsight_api.extensions.base import Extension
+
+logger = logging.getLogger(__name__)
+
+
+class MCPExtension(Extension):
+    """Base class for MCP extensions that register additional tools.
+
+    Subclass this to add MCP tools in extension packages.
+
+    Example:
+        class CloudMCPExtension(MCPExtension):
+            def register_tools(self, mcp: FastMCP, memory: MemoryEngine) -> None:
+                @mcp.tool()
+                async def my_custom_tool(query: str) -> str:
+                    return "result"
+    """
+
+    @abstractmethod
+    def register_tools(self, mcp: FastMCP, memory: MemoryEngine) -> None:
+        """Register additional MCP tools.
+
+        Args:
+            mcp: FastMCP server instance to register tools on
+            memory: MemoryEngine instance for accessing memory operations
+        """
+        pass

hindsight-api/hindsight_api/extensions/operation_validator.py

@@ -132,6 +132,10 @@ class RetainResult:
     unit_ids: list[list[str]]  # List of unit IDs per content item
     success: bool = True
     error: str | None = None
+    # Actual LLM token usage (populated by engine when available)
+    llm_input_tokens: int | None = None
+    llm_output_tokens: int | None = None
+    llm_total_tokens: int | None = None
 
 
 @dataclass

hindsight-api/hindsight_api/extensions/tenant.py

@@ -2,6 +2,7 @@
 
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
+from typing import Any
 
 from hindsight_api.extensions.base import Extension
 from hindsight_api.models import RequestContext
@@ -87,3 +88,70 @@ class TenantExtension(Extension, ABC):
             For single-tenant setups, return [Tenant(schema="public")].
         """
         ...
+
+    async def get_tenant_config(self, context: RequestContext) -> dict[str, Any]:
+        """
+        Get tenant-specific configuration overrides.
+
+        This method is called during hierarchical configuration resolution to get
+        tenant-level config overrides. The returned dict should contain Python field
+        names (lowercase snake_case) as keys, not environment variable names.
+
+        Example:
+            {"llm_model": "gpt-4", "retain_extraction_mode": "verbose"}
+
+        The default implementation returns an empty dict (no tenant-specific config).
+        Override this method in custom extensions to provide tenant-specific configuration.
+
+        Args:
+            context: The request context containing tenant information.
+
+        Returns:
+            Dict of config field names to values (only configurable fields).
+            Empty dict if no tenant-specific config.
+        """
+        return {}
+
+    async def get_allowed_config_fields(self, context: RequestContext, bank_id: str) -> set[str] | None:
+        """
+        Get set of config fields that this tenant/bank is allowed to modify.
+
+        This method controls which configurable fields can be modified via the bank config API.
+        It enables fine-grained permission control per tenant or per bank.
+
+        Examples:
+            - Return None: Allow all configurable fields (default)
+            - Return {"retain_chunk_size", "retain_custom_instructions"}: Allow only these fields
+            - Return set(): Allow no modifications (read-only)
+
+        The default implementation returns None (all configurable fields allowed).
+        Override this method in custom extensions to implement custom permission logic.
+
+        Args:
+            context: The request context containing tenant information.
+            bank_id: The bank identifier for per-bank permissions.
+
+        Returns:
+            Set of allowed field names, or None to allow all configurable fields.
+            Returned fields must be a subset of HindsightConfig.get_configurable_fields().
+        """
+        return None
+
+    async def authenticate_mcp(self, context: RequestContext) -> TenantContext:
+        """
+        Authenticate MCP requests.
+
+        By default, this calls authenticate(). Override this method to provide
+        different authentication behavior for MCP endpoints (e.g., to disable
+        auth for backwards compatibility with existing MCP servers).
+
+        Args:
+            context: The action context containing API key and other auth data.
+
+        Returns:
+            TenantContext with the schema_name for database operations.
+
+        Raises:
+            AuthenticationError: If authentication fails.
+        """
+        return await self.authenticate(context)

hindsight-api/hindsight_api/main.py

@@ -23,7 +23,7 @@ import uvicorn
 from . import MemoryEngine, __version__
 from .api import create_app
 from .banner import print_banner
-from .config import DEFAULT_WORKERS, ENV_WORKERS, HindsightConfig, get_config
+from .config import DEFAULT_WORKERS, ENV_WORKERS, HindsightConfig, _get_raw_config
 from .daemon import (
     DEFAULT_DAEMON_PORT,
     DEFAULT_IDLE_TIMEOUT,
@@ -68,7 +68,7 @@ def main():
     global _memory
 
     # Load configuration from environment (for CLI args defaults)
-    config = get_config()
+    config = _get_raw_config()
 
     parser = argparse.ArgumentParser(
         prog="hindsight-api",
@@ -155,6 +155,8 @@ def main():
         config = HindsightConfig(
             database_url=config.database_url,
             database_schema=config.database_schema,
+            vector_extension=config.vector_extension,
+            text_search_extension=config.text_search_extension,
             llm_provider=config.llm_provider,
             llm_api_key=config.llm_api_key,
             llm_model=config.llm_model,
@@ -197,23 +199,43 @@ def main():
             embeddings_provider=config.embeddings_provider,
             embeddings_local_model=config.embeddings_local_model,
             embeddings_local_force_cpu=config.embeddings_local_force_cpu,
+            embeddings_local_trust_remote_code=config.embeddings_local_trust_remote_code,
             embeddings_tei_url=config.embeddings_tei_url,
             embeddings_openai_base_url=config.embeddings_openai_base_url,
+            embeddings_cohere_api_key=config.embeddings_cohere_api_key,
+            embeddings_cohere_model=config.embeddings_cohere_model,
             embeddings_cohere_base_url=config.embeddings_cohere_base_url,
+            embeddings_litellm_api_base=config.embeddings_litellm_api_base,
+            embeddings_litellm_api_key=config.embeddings_litellm_api_key,
+            embeddings_litellm_model=config.embeddings_litellm_model,
+            embeddings_litellm_sdk_api_key=config.embeddings_litellm_sdk_api_key,
+            embeddings_litellm_sdk_model=config.embeddings_litellm_sdk_model,
+            embeddings_litellm_sdk_api_base=config.embeddings_litellm_sdk_api_base,
             reranker_provider=config.reranker_provider,
             reranker_local_model=config.reranker_local_model,
             reranker_local_force_cpu=config.reranker_local_force_cpu,
             reranker_local_max_concurrent=config.reranker_local_max_concurrent,
+            reranker_local_trust_remote_code=config.reranker_local_trust_remote_code,
             reranker_tei_url=config.reranker_tei_url,
             reranker_tei_batch_size=config.reranker_tei_batch_size,
             reranker_tei_max_concurrent=config.reranker_tei_max_concurrent,
             reranker_max_candidates=config.reranker_max_candidates,
+            reranker_cohere_api_key=config.reranker_cohere_api_key,
+            reranker_cohere_model=config.reranker_cohere_model,
             reranker_cohere_base_url=config.reranker_cohere_base_url,
+            reranker_litellm_api_base=config.reranker_litellm_api_base,
+            reranker_litellm_api_key=config.reranker_litellm_api_key,
+            reranker_litellm_model=config.reranker_litellm_model,
+            reranker_litellm_sdk_api_key=config.reranker_litellm_sdk_api_key,
+            reranker_litellm_sdk_model=config.reranker_litellm_sdk_model,
+            reranker_litellm_sdk_api_base=config.reranker_litellm_sdk_api_base,
             host=args.host,
             port=args.port,
+            base_path=config.base_path,
             log_level=args.log_level,
             log_format=config.log_format,
             mcp_enabled=config.mcp_enabled,
+            enable_bank_config_api=config.enable_bank_config_api,
             graph_retriever=config.graph_retriever,
             mpfp_top_k_neighbors=config.mpfp_top_k_neighbors,
             recall_max_concurrent=config.recall_max_concurrent,
@@ -242,6 +264,11 @@ def main():
             worker_consolidation_max_slots=config.worker_consolidation_max_slots,
             reflect_max_iterations=config.reflect_max_iterations,
             mental_model_refresh_concurrency=config.mental_model_refresh_concurrency,
+            otel_traces_enabled=config.otel_traces_enabled,
+            otel_exporter_otlp_endpoint=config.otel_exporter_otlp_endpoint,
+            otel_exporter_otlp_headers=config.otel_exporter_otlp_headers,
+            otel_service_name=config.otel_service_name,
+            otel_deployment_environment=config.otel_deployment_environment,
         )
     config.configure_logging()
     if not args.daemon:
@@ -347,6 +374,8 @@ def main():
             reranker_provider=config.reranker_provider,
             mcp_enabled=config.mcp_enabled,
             version=__version__,
+            vector_extension=config.vector_extension,
+            text_search_extension=config.text_search_extension,
         )
 
     # Start idle checker in daemon mode

hindsight-api/hindsight_api/mcp_tools.py

@@ -35,6 +35,12 @@ class MCPToolsConfig:
     # How to resolve API key for tenant auth (optional)
     api_key_resolver: Callable[[], str | None] | None = None
 
+    # How to resolve tenant_id for usage metering (set by MCP middleware after auth)
+    tenant_id_resolver: Callable[[], str | None] | None = None
+
+    # How to resolve api_key_id for usage metering (set by MCP middleware after auth)
+    api_key_id_resolver: Callable[[], str | None] | None = None
+
     # Whether to include bank_id as a parameter on tools (for multi-bank support)
     include_bank_id_param: bool = False
 
@@ -50,13 +56,15 @@ class MCPToolsConfig:
 
 
 def _get_request_context(config: MCPToolsConfig) -> RequestContext:
-    """Create RequestContext with API key from resolver if available.
+    """Create RequestContext with auth details from resolvers.
 
-    This enables tenant auth to work with MCP tools by propagating
-    the Bearer token from the MCP middleware to the memory engine.
+    This enables tenant auth and usage metering to work with MCP tools by propagating
+    the authentication results from the MCP middleware to the memory engine.
     """
     api_key = config.api_key_resolver() if config.api_key_resolver else None
-    return RequestContext(api_key=api_key)
+    tenant_id = config.tenant_id_resolver() if config.tenant_id_resolver else None
+    api_key_id = config.api_key_id_resolver() if config.api_key_id_resolver else None
+    return RequestContext(api_key=api_key, tenant_id=tenant_id, api_key_id=api_key_id)
 
 
 def parse_timestamp(timestamp: str) -> datetime | None:
@@ -119,7 +127,19 @@ def register_mcp_tools(
         memory: MemoryEngine instance
         config: Tool configuration
     """
-    tools_to_register = config.tools or {"retain", "recall", "reflect", "list_banks", "create_bank"}
+    tools_to_register = config.tools or {
+        "retain",
+        "recall",
+        "reflect",
+        "list_banks",
+        "create_bank",
+        "list_mental_models",
+        "get_mental_model",
+        "create_mental_model",
+        "update_mental_model",
+        "delete_mental_model",
+        "refresh_mental_model",
+    }
 
     if "retain" in tools_to_register:
         _register_retain(mcp, memory, config)
@@ -136,6 +156,25 @@ def register_mcp_tools(
     if "create_bank" in tools_to_register:
         _register_create_bank(mcp, memory, config)
 
+    # Mental model tools
+    if "list_mental_models" in tools_to_register:
+        _register_list_mental_models(mcp, memory, config)
+
+    if "get_mental_model" in tools_to_register:
+        _register_get_mental_model(mcp, memory, config)
+
+    if "create_mental_model" in tools_to_register:
+        _register_create_mental_model(mcp, memory, config)
+
+    if "update_mental_model" in tools_to_register:
+        _register_update_mental_model(mcp, memory, config)
+
+    if "delete_mental_model" in tools_to_register:
+        _register_delete_mental_model(mcp, memory, config)
+
+    if "refresh_mental_model" in tools_to_register:
+        _register_refresh_mental_model(mcp, memory, config)
+
 
 def _register_retain(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig) -> None:
     """Register the retain tool."""
@@ -511,3 +550,567 @@ def _register_create_bank(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsCo
         except Exception as e:
             logger.error(f"Error creating bank: {e}", exc_info=True)
             return f'{{"error": "{e}"}}'
+
+
+def _validate_mental_model_inputs(
+    name: str | None = None, source_query: str | None = None, max_tokens: int | None = None
+) -> str | None:
+    """Validate mental model inputs, returning an error message or None if valid."""
+    if name is not None and not name.strip():
+        return "name cannot be empty"
+    if source_query is not None and not source_query.strip():
+        return "source_query cannot be empty"
+    if max_tokens is not None and (max_tokens < 256 or max_tokens > 8192):
+        return f"max_tokens must be between 256 and 8192, got {max_tokens}"
+    return None
+
+
+# =========================================================================
+# MENTAL MODEL TOOLS
+# =========================================================================
+
+
+def _register_list_mental_models(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig) -> None:
+    """Register the list_mental_models tool."""
+
+    if config.include_bank_id_param:
+
+        @mcp.tool()
+        async def list_mental_models(
+            tags: list[str] | None = None,
+            bank_id: str | None = None,
+        ) -> str:
+            """
+            List mental models (pinned reflections) for a memory bank.
+
+            Mental models are living documents that stay current by periodically re-running
+            a source query through reflect. Use them to maintain up-to-date summaries,
+            preferences, or synthesized knowledge.
+
+            Args:
+                tags: Optional tags to filter by (returns models matching any tag)
+                bank_id: Optional bank to list from (defaults to session bank). Use for cross-bank operations.
+            """
+            try:
+                target_bank = bank_id or config.bank_id_resolver()
+                if target_bank is None:
+                    return '{"error": "No bank_id configured", "items": []}'
+
+                models = await memory.list_mental_models(
+                    bank_id=target_bank,
+                    tags=tags,
+                    request_context=_get_request_context(config),
+                )
+                return json.dumps({"items": models}, indent=2, default=str)
+            except Exception as e:
+                logger.error(f"Error listing mental models: {e}", exc_info=True)
+                return f'{{"error": "{e}", "items": []}}'
+
+    else:
+
+        @mcp.tool()
+        async def list_mental_models(
+            tags: list[str] | None = None,
+        ) -> dict:
+            """
+            List mental models (pinned reflections) for this memory bank.
+
+            Mental models are living documents that stay current by periodically re-running
+            a source query through reflect. Use them to maintain up-to-date summaries,
+            preferences, or synthesized knowledge.
+
+            Args:
+                tags: Optional tags to filter by (returns models matching any tag)
+            """
+            try:
+                target_bank = config.bank_id_resolver()
+                if target_bank is None:
+                    return {"error": "No bank_id configured", "items": []}
+
+                models = await memory.list_mental_models(
+                    bank_id=target_bank,
+                    tags=tags,
+                    request_context=_get_request_context(config),
+                )
+                return {"items": models}
+            except Exception as e:
+                logger.error(f"Error listing mental models: {e}", exc_info=True)
+                return {"error": str(e), "items": []}
+
+
+def _register_get_mental_model(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig) -> None:
+    """Register the get_mental_model tool."""
+
+    if config.include_bank_id_param:
+
+        @mcp.tool()
+        async def get_mental_model(
+            mental_model_id: str,
+            bank_id: str | None = None,
+        ) -> str:
+            """
+            Get a specific mental model by ID.
+
+            Returns the full mental model including its generated content, source query,
+            and metadata. Use list_mental_models first to discover available model IDs.
+
+            Args:
+                mental_model_id: The ID of the mental model to retrieve
+                bank_id: Optional bank (defaults to session bank). Use for cross-bank operations.
+            """
+            try:
+                target_bank = bank_id or config.bank_id_resolver()
+                if target_bank is None:
+                    return '{"error": "No bank_id configured"}'
+
+                model = await memory.get_mental_model(
+                    bank_id=target_bank,
+                    mental_model_id=mental_model_id,
+                    request_context=_get_request_context(config),
+                )
+                if model is None:
+                    return json.dumps({"error": f"Mental model '{mental_model_id}' not found in bank '{target_bank}'"})
+                return json.dumps(model, indent=2, default=str)
+            except Exception as e:
+                logger.error(f"Error getting mental model: {e}", exc_info=True)
+                return f'{{"error": "{e}"}}'
+
+    else:
+
+        @mcp.tool()
+        async def get_mental_model(
+            mental_model_id: str,
+        ) -> dict:
+            """
+            Get a specific mental model by ID.
+
+            Returns the full mental model including its generated content, source query,
+            and metadata. Use list_mental_models first to discover available model IDs.
+
+            Args:
+                mental_model_id: The ID of the mental model to retrieve
+            """
+            try:
+                target_bank = config.bank_id_resolver()
+                if target_bank is None:
+                    return {"error": "No bank_id configured"}
+
+                model = await memory.get_mental_model(
+                    bank_id=target_bank,
+                    mental_model_id=mental_model_id,
+                    request_context=_get_request_context(config),
+                )
+                if model is None:
+                    return {"error": f"Mental model '{mental_model_id}' not found in bank '{target_bank}'"}
+                return model
+            except Exception as e:
+                logger.error(f"Error getting mental model: {e}", exc_info=True)
+                return {"error": str(e)}
+
+
+def _register_create_mental_model(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig) -> None:
+    """Register the create_mental_model tool."""
+
+    if config.include_bank_id_param:
+
+        @mcp.tool()
+        async def create_mental_model(
+            name: str,
+            source_query: str,
+            mental_model_id: str | None = None,
+            tags: list[str] | None = None,
+            max_tokens: int = 2048,
+            bank_id: str | None = None,
+        ) -> str:
+            """
+            Create a new mental model (pinned reflection).
+
+            A mental model is a living document generated by running the source_query through
+            reflect. The content is auto-generated asynchronously - use the returned operation_id
+            to track progress.
+
+            EXAMPLES:
+            - name="Coding Preferences", source_query="What coding patterns and tools does the user prefer?"
+            - name="Project Goals", source_query="What are the user's current project goals and priorities?"
+            - name="Communication Style", source_query="How does the user prefer to communicate?"
+
+            Args:
+                name: Human-readable name for the mental model
+                source_query: The query to run through reflect to generate content
+                mental_model_id: Optional custom ID (alphanumeric lowercase with hyphens). Auto-generated if not provided.
+                tags: Optional tags for scoped visibility filtering
+                max_tokens: Maximum tokens for generated content (256-8192, default: 2048)
+                bank_id: Optional bank (defaults to session bank). Use for cross-bank operations.
+            """
+            try:
+                target_bank = bank_id or config.bank_id_resolver()
+                if target_bank is None:
+                    return '{"error": "No bank_id configured"}'
+
+                validation_error = _validate_mental_model_inputs(
+                    name=name, source_query=source_query, max_tokens=max_tokens
+                )
+                if validation_error:
+                    return json.dumps({"error": validation_error})
+
+                request_context = _get_request_context(config)
+
+                # Create with placeholder content
+                model = await memory.create_mental_model(
+                    bank_id=target_bank,
+                    name=name,
+                    source_query=source_query,
+                    content="Generating content...",
+                    mental_model_id=mental_model_id,
+                    tags=tags,
+                    max_tokens=max_tokens,
+                    request_context=request_context,
+                )
+
+                # Schedule async refresh to generate actual content
+                result = await memory.submit_async_refresh_mental_model(
+                    bank_id=target_bank,
+                    mental_model_id=model["id"],
+                    request_context=request_context,
+                )
+
+                return json.dumps(
+                    {
+                        "mental_model_id": model["id"],
+                        "operation_id": result["operation_id"],
+                        "status": "created",
+                        "message": f"Mental model '{name}' created. Content is being generated asynchronously.",
+                    }
+                )
+            except ValueError as e:
+                return json.dumps({"error": str(e)})
+            except Exception as e:
+                logger.error(f"Error creating mental model: {e}", exc_info=True)
+                return f'{{"error": "{e}"}}'
+
+    else:
+
+        @mcp.tool()
+        async def create_mental_model(
+            name: str,
+            source_query: str,
+            mental_model_id: str | None = None,
+            tags: list[str] | None = None,
+            max_tokens: int = 2048,
+        ) -> dict:
+            """
+            Create a new mental model (pinned reflection).
+
+            A mental model is a living document generated by running the source_query through
+            reflect. The content is auto-generated asynchronously - use the returned operation_id
+            to track progress.
+
+            EXAMPLES:
+            - name="Coding Preferences", source_query="What coding patterns and tools does the user prefer?"
+            - name="Project Goals", source_query="What are the user's current project goals and priorities?"
+            - name="Communication Style", source_query="How does the user prefer to communicate?"
+
+            Args:
+                name: Human-readable name for the mental model
+                source_query: The query to run through reflect to generate content
+                mental_model_id: Optional custom ID (alphanumeric lowercase with hyphens). Auto-generated if not provided.
+                tags: Optional tags for scoped visibility filtering
+                max_tokens: Maximum tokens for generated content (256-8192, default: 2048)
+            """
+            try:
+                target_bank = config.bank_id_resolver()
+                if target_bank is None:
+                    return {"error": "No bank_id configured"}
+
+                validation_error = _validate_mental_model_inputs(
+                    name=name, source_query=source_query, max_tokens=max_tokens
+                )
+                if validation_error:
+                    return {"error": validation_error}
+
+                request_context = _get_request_context(config)
+
+                model = await memory.create_mental_model(
+                    bank_id=target_bank,
+                    name=name,
+                    source_query=source_query,
+                    content="Generating content...",
+                    mental_model_id=mental_model_id,
+                    tags=tags,
+                    max_tokens=max_tokens,
+                    request_context=request_context,
+                )
+
+                result = await memory.submit_async_refresh_mental_model(
+                    bank_id=target_bank,
+                    mental_model_id=model["id"],
+                    request_context=request_context,
+                )
+
+                return {
+                    "mental_model_id": model["id"],
+                    "operation_id": result["operation_id"],
+                    "status": "created",
+                    "message": f"Mental model '{name}' created. Content is being generated asynchronously.",
+                }
+            except ValueError as e:
+                return {"error": str(e)}
+            except Exception as e:
+                logger.error(f"Error creating mental model: {e}", exc_info=True)
+                return {"error": str(e)}
+
+
+def _register_update_mental_model(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig) -> None:
+    """Register the update_mental_model tool."""
+
+    if config.include_bank_id_param:
+
+        @mcp.tool()
+        async def update_mental_model(
+            mental_model_id: str,
+            name: str | None = None,
+            source_query: str | None = None,
+            max_tokens: int | None = None,
+            tags: list[str] | None = None,
+            bank_id: str | None = None,
+        ) -> str:
+            """
+            Update a mental model's metadata.
+
+            Changes the name, source query, or tags of an existing mental model.
+            To regenerate the content, use refresh_mental_model after updating the source query.
+
+            Args:
+                mental_model_id: The ID of the mental model to update
+                name: New name (leave None to keep current)
+                source_query: New source query (leave None to keep current)
+                max_tokens: New max tokens for content generation (256-8192, leave None to keep current)
+                tags: New tags (leave None to keep current)
+                bank_id: Optional bank (defaults to session bank). Use for cross-bank operations.
+            """
+            try:
+                target_bank = bank_id or config.bank_id_resolver()
+                if target_bank is None:
+                    return '{"error": "No bank_id configured"}'
+
+                validation_error = _validate_mental_model_inputs(
+                    name=name, source_query=source_query, max_tokens=max_tokens
+                )
+                if validation_error:
+                    return json.dumps({"error": validation_error})
+
+                model = await memory.update_mental_model(
+                    bank_id=target_bank,
+                    mental_model_id=mental_model_id,
+                    name=name,
+                    source_query=source_query,
+                    max_tokens=max_tokens,
+                    tags=tags,
+                    request_context=_get_request_context(config),
+                )
+                if model is None:
+                    return json.dumps({"error": f"Mental model '{mental_model_id}' not found in bank '{target_bank}'"})
+                return json.dumps(model, indent=2, default=str)
+            except Exception as e:
+                logger.error(f"Error updating mental model: {e}", exc_info=True)
+                return f'{{"error": "{e}"}}'
+
+    else:
+
+        @mcp.tool()
+        async def update_mental_model(
+            mental_model_id: str,
+            name: str | None = None,
+            source_query: str | None = None,
+            max_tokens: int | None = None,
+            tags: list[str] | None = None,
+        ) -> dict:
+            """
+            Update a mental model's metadata.
+
+            Changes the name, source query, or tags of an existing mental model.
+            To regenerate the content, use refresh_mental_model after updating the source query.
+
+            Args:
+                mental_model_id: The ID of the mental model to update
+                name: New name (leave None to keep current)
+                source_query: New source query (leave None to keep current)
+                max_tokens: New max tokens for content generation (256-8192, leave None to keep current)
+                tags: New tags (leave None to keep current)
+            """
+            try:
+                target_bank = config.bank_id_resolver()
+                if target_bank is None:
+                    return {"error": "No bank_id configured"}
+
+                validation_error = _validate_mental_model_inputs(
+                    name=name, source_query=source_query, max_tokens=max_tokens
+                )
+                if validation_error:
+                    return {"error": validation_error}
+
+                model = await memory.update_mental_model(
+                    bank_id=target_bank,
+                    mental_model_id=mental_model_id,
+                    name=name,
+                    source_query=source_query,
+                    max_tokens=max_tokens,
+                    tags=tags,
+                    request_context=_get_request_context(config),
+                )
+                if model is None:
+                    return {"error": f"Mental model '{mental_model_id}' not found in bank '{target_bank}'"}
+                return model
+            except Exception as e:
+                logger.error(f"Error updating mental model: {e}", exc_info=True)
+                return {"error": str(e)}
+
+
+def _register_delete_mental_model(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig) -> None:
+    """Register the delete_mental_model tool."""
+
+    if config.include_bank_id_param:
+
+        @mcp.tool()
+        async def delete_mental_model(
+            mental_model_id: str,
+            bank_id: str | None = None,
+        ) -> str:
+            """
+            Delete a mental model.
+
+            Permanently removes a mental model and its generated content.
+
+            Args:
+                mental_model_id: The ID of the mental model to delete
+                bank_id: Optional bank (defaults to session bank). Use for cross-bank operations.
+            """
+            try:
+                target_bank = bank_id or config.bank_id_resolver()
+                if target_bank is None:
+                    return '{"error": "No bank_id configured"}'
+
+                deleted = await memory.delete_mental_model(
+                    bank_id=target_bank,
+                    mental_model_id=mental_model_id,
+                    request_context=_get_request_context(config),
+                )
+                if not deleted:
+                    return json.dumps({"error": f"Mental model '{mental_model_id}' not found in bank '{target_bank}'"})
+                return json.dumps({"status": "deleted", "mental_model_id": mental_model_id})
+            except Exception as e:
+                logger.error(f"Error deleting mental model: {e}", exc_info=True)
+                return f'{{"error": "{e}"}}'
+
+    else:
+
+        @mcp.tool()
+        async def delete_mental_model(
+            mental_model_id: str,
+        ) -> dict:
+            """
+            Delete a mental model.
+
+            Permanently removes a mental model and its generated content.
+
+            Args:
+                mental_model_id: The ID of the mental model to delete
+            """
+            try:
+                target_bank = config.bank_id_resolver()
+                if target_bank is None:
+                    return {"error": "No bank_id configured"}
+
+                deleted = await memory.delete_mental_model(
+                    bank_id=target_bank,
+                    mental_model_id=mental_model_id,
+                    request_context=_get_request_context(config),
+                )
+                if not deleted:
+                    return {"error": f"Mental model '{mental_model_id}' not found in bank '{target_bank}'"}
+                return {"status": "deleted", "mental_model_id": mental_model_id}
+            except Exception as e:
+                logger.error(f"Error deleting mental model: {e}", exc_info=True)
+                return {"error": str(e)}
+
+
+def _register_refresh_mental_model(mcp: FastMCP, memory: MemoryEngine, config: MCPToolsConfig) -> None:
+    """Register the refresh_mental_model tool."""
+
+    if config.include_bank_id_param:
+
+        @mcp.tool()
+        async def refresh_mental_model(
+            mental_model_id: str,
+            bank_id: str | None = None,
+        ) -> str:
+            """
+            Refresh a mental model by re-running its source query.
+
+            Schedules an async task to re-run the source query through reflect and update the
+            mental model's content with fresh results. Use this after adding new memories or
+            when the mental model's content may be stale.
+
+            Args:
+                mental_model_id: The ID of the mental model to refresh
+                bank_id: Optional bank (defaults to session bank). Use for cross-bank operations.
+            """
+            try:
+                target_bank = bank_id or config.bank_id_resolver()
+                if target_bank is None:
+                    return '{"error": "No bank_id configured"}'
+
+                result = await memory.submit_async_refresh_mental_model(
+                    bank_id=target_bank,
+                    mental_model_id=mental_model_id,
+                    request_context=_get_request_context(config),
+                )
+                return json.dumps(
+                    {
+                        "operation_id": result["operation_id"],
+                        "status": "queued",
+                        "message": f"Refresh queued for mental model '{mental_model_id}'.",
+                    }
+                )
+            except ValueError as e:
+                return json.dumps({"error": str(e)})
+            except Exception as e:
+                logger.error(f"Error refreshing mental model: {e}", exc_info=True)
+                return f'{{"error": "{e}"}}'
+
+    else:
+
+        @mcp.tool()
+        async def refresh_mental_model(
+            mental_model_id: str,
+        ) -> dict:
+            """
+            Refresh a mental model by re-running its source query.
+
+            Schedules an async task to re-run the source query through reflect and update the
+            mental model's content with fresh results. Use this after adding new memories or
+            when the mental model's content may be stale.
+
+            Args:
+                mental_model_id: The ID of the mental model to refresh
+            """
+            try:
+                target_bank = config.bank_id_resolver()
+                if target_bank is None:
+                    return {"error": "No bank_id configured"}
+
+                result = await memory.submit_async_refresh_mental_model(
+                    bank_id=target_bank,
+                    mental_model_id=mental_model_id,
+                    request_context=_get_request_context(config),
+                )
+                return {
+                    "operation_id": result["operation_id"],
+                    "status": "queued",
+                    "message": f"Refresh queued for mental model '{mental_model_id}'.",
+                }
+            except ValueError as e:
+                return {"error": str(e)}
+            except Exception as e:
+                logger.error(f"Error refreshing mental model: {e}", exc_info=True)
+                return {"error": str(e)}

hindsight-api/hindsight_api/migrations.py

@@ -25,12 +25,69 @@ from alembic.config import Config
 from alembic.script.revision import ResolutionError
 from sqlalchemy import create_engine, text
 
+from .utils import mask_network_location
+
 logger = logging.getLogger(__name__)
 
 # Advisory lock ID for migrations (arbitrary unique number)
 MIGRATION_LOCK_ID = 123456789
 
 
+def _detect_vector_extension(conn, vector_extension: str = "pgvector") -> str:
+    """
+    Validate vector extension: 'pgvector', 'vchord', or 'pgvectorscale'.
+
+    Args:
+        conn: SQLAlchemy connection object
+        vector_extension: Configured extension ("pgvector", "vchord", or "pgvectorscale")
+
+    Returns:
+        "pgvector", "vchord", or "pgvectorscale"
+
+    Raises:
+        RuntimeError: If configured extension is not installed
+    """
+    # Verify the configured extension is installed
+    if vector_extension == "pgvectorscale":
+        # pgvectorscale requires pgvector to be installed first
+        pgvector_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vector'")).scalar()
+        if not pgvector_check:
+            raise RuntimeError(
+                "pgvectorscale requires pgvector to be installed. "
+                "Install it with: CREATE EXTENSION vector; CREATE EXTENSION vectorscale CASCADE;"
+            )
+
+        # Check for vectorscale extension
+        vectorscale_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vectorscale'")).scalar()
+        if not vectorscale_check:
+            raise RuntimeError(
+                "Configured vector extension 'pgvectorscale' not found. "
+                "Install it with: CREATE EXTENSION vectorscale CASCADE;"
+            )
+        logger.debug("Using configured vector extension: pgvectorscale (DiskANN)")
+        return "pgvectorscale"
+    elif vector_extension == "vchord":
+        vchord_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vchord'")).scalar()
+        if not vchord_check:
+            raise RuntimeError(
+                "Configured vector extension 'vchord' not found. Install it with: CREATE EXTENSION vchord CASCADE;"
+            )
+        logger.debug("Using configured vector extension: vchord")
+        return "vchord"
+    elif vector_extension == "pgvector":
+        pgvector_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vector'")).scalar()
+        if not pgvector_check:
+            raise RuntimeError(
+                "Configured vector extension 'pgvector' not found. Install it with: CREATE EXTENSION vector;"
+            )
+        logger.debug("Using configured vector extension: pgvector")
+        return "pgvector"
+    else:
+        raise ValueError(
+            f"Invalid vector_extension: {vector_extension}. Must be 'pgvector', 'vchord', or 'pgvectorscale'"
+        )
+
+
 def _get_schema_lock_id(schema: str) -> int:
     """
     Generate a unique advisory lock ID for a schema.
@@ -54,7 +111,7 @@ def _run_migrations_internal(database_url: str, script_location: str, schema: st
     """
     schema_name = schema or "public"
     logger.info(f"Running database migrations to head for schema '{schema_name}'...")
-    logger.info(f"Database URL: {database_url}")
+    logger.info(f"Database URL: {mask_network_location(database_url)}")
     logger.info(f"Script location: {script_location}")
 
     # Create Alembic configuration programmatically (no alembic.ini needed)
@@ -240,6 +297,48 @@ def run_migrations(
                                 "Please install it with: CREATE EXTENSION vector;"
                             ) from e
 
+                # If using pgvectorscale, ensure vectorscale extension is also installed
+                vector_extension = os.getenv("HINDSIGHT_API_VECTOR_EXTENSION", "pgvector").lower()
+                if vector_extension == "pgvectorscale":
+                    logger.debug("Checking pgvectorscale (vectorscale) extension availability...")
+
+                    vectorscale_check = conn.execute(
+                        text("SELECT 1 FROM pg_extension WHERE extname = 'vectorscale'")
+                    ).scalar()
+
+                    if vectorscale_check:
+                        logger.info("pgvectorscale extension already installed")
+                    else:
+                        # Extension doesn't exist - try to install
+                        logger.info("pgvectorscale extension not found, attempting to install...")
+                        try:
+                            conn.execute(text("CREATE EXTENSION vectorscale CASCADE"))
+                            conn.commit()
+                            logger.info("pgvectorscale extension installed successfully")
+                        except Exception as e:
+                            # Installation failed - check one more time in case another process installed it
+                            conn.rollback()
+                            vectorscale_recheck = conn.execute(
+                                text("SELECT 1 FROM pg_extension WHERE extname = 'vectorscale'")
+                            ).fetchone()
+
+                            if vectorscale_recheck:
+                                logger.warning(
+                                    "Could not install pgvectorscale extension (permission denied?), "
+                                    "but extension exists. Continuing..."
+                                )
+                            else:
+                                # Extension truly doesn't exist and we can't install it
+                                logger.error(
+                                    f"pgvectorscale extension is not installed and cannot be installed: {e}. "
+                                    f"Please ensure pgvectorscale is installed by a database administrator. "
+                                    f"See: https://github.com/timescale/pgvectorscale#installation"
+                                )
+                                raise RuntimeError(
+                                    "pgvectorscale extension is required but not installed. "
+                                    "Please install it with: CREATE EXTENSION vectorscale CASCADE;"
+                                ) from e
+
                 # Run migrations while holding the lock
                 _run_migrations_internal(database_url, script_location, schema=schema)
             finally:
@@ -322,6 +421,7 @@ def ensure_embedding_dimension(
     database_url: str,
     required_dimension: int,
     schema: str | None = None,
+    vector_extension: str = "pgvector",
 ) -> None:
     """
     Ensure the embedding column dimension matches the model's dimension.
@@ -336,6 +436,7 @@ def ensure_embedding_dimension(
         database_url: SQLAlchemy database URL
         required_dimension: The embedding dimension required by the model
         schema: Target PostgreSQL schema name (None for public)
+        vector_extension: Configured vector extension ("pgvector" or "vchord")
 
     Raises:
         RuntimeError: If dimension mismatch with existing data
@@ -359,6 +460,10 @@ def ensure_embedding_dimension(
             logger.debug(f"memory_units table does not exist in schema '{schema_name}', skipping dimension check")
             return
 
+        # Detect which vector extension is available
+        vector_ext = _detect_vector_extension(conn, vector_extension)
+        logger.info(f"Using vector extension: {vector_ext}")
+
         # Get current column dimension from pg_attribute
         # pgvector stores dimension in atttypmod
         current_dim = conn.execute(
@@ -406,8 +511,7 @@ def ensure_embedding_dimension(
         # Table is empty, safe to alter column
         logger.info(f"Altering embedding column dimension from {current_dimension} to {required_dimension}")
 
-        # Drop the HNSW index on embedding column if it exists
-        # Only drop indexes that use 'hnsw' and reference the 'embedding' column
+        # Drop existing vector index (works for both HNSW and vchordrq)
         conn.execute(
             text(f"""
                 DO $$
@@ -417,7 +521,7 @@ def ensure_embedding_dimension(
                         SELECT indexname FROM pg_indexes
                         WHERE schemaname = '{schema_name}'
                           AND tablename = 'memory_units'
-                          AND indexdef LIKE '%hnsw%'
+                          AND (indexdef LIKE '%hnsw%' OR indexdef LIKE '%vchordrq%')
                           AND indexdef LIKE '%embedding%'
                     LOOP
                         EXECUTE 'DROP INDEX IF EXISTS {schema_name}.' || idx_name;
@@ -432,15 +536,442 @@ def ensure_embedding_dimension(
         )
         conn.commit()
 
-        # Recreate the HNSW index
-        conn.execute(
-            text(f"""
-                CREATE INDEX IF NOT EXISTS idx_memory_units_embedding_hnsw
-                ON {schema_name}.memory_units
-                USING hnsw (embedding vector_cosine_ops)
-                WITH (m = 16, ef_construction = 64)
-            """)
-        )
+        # Recreate index with appropriate type based on detected extension
+        if vector_ext == "pgvectorscale":
+            conn.execute(
+                text(f"""
+                    CREATE INDEX IF NOT EXISTS idx_memory_units_embedding_diskann
+                    ON {schema_name}.memory_units
+                    USING diskann (embedding vector_cosine_ops)
+                    WITH (num_neighbors = 50)
+                """)
+            )
+            logger.info(f"Created DiskANN index for {required_dimension}-dimensional embeddings")
+        elif vector_ext == "vchord":
+            conn.execute(
+                text(f"""
+                    CREATE INDEX IF NOT EXISTS idx_memory_units_embedding_vchordrq
+                    ON {schema_name}.memory_units
+                    USING vchordrq (embedding vector_l2_ops)
+                """)
+            )
+            logger.info(f"Created vchordrq index for {required_dimension}-dimensional embeddings")
+        else:  # pgvector
+            conn.execute(
+                text(f"""
+                    CREATE INDEX IF NOT EXISTS idx_memory_units_embedding_hnsw
+                    ON {schema_name}.memory_units
+                    USING hnsw (embedding vector_cosine_ops)
+                    WITH (m = 16, ef_construction = 64)
+                """)
+            )
+            logger.info(f"Created HNSW index for {required_dimension}-dimensional embeddings")
         conn.commit()
 
         logger.info(f"Successfully changed embedding dimension to {required_dimension}")
+
+
+def ensure_vector_extension(
+    database_url: str,
+    vector_extension: str = "pgvector",
+    schema: str | None = None,
+) -> None:
+    """
+    Ensure the vector indexes match the configured vector extension.
+
+    This function checks the current vector index type in the database
+    and adjusts it if necessary:
+    - If index type matches configured extension: no action needed
+    - If they differ and tables are empty: drop old indexes, recreate with new type
+    - If they differ and tables have data: raise error with migration guidance
+
+    Args:
+        database_url: SQLAlchemy database URL
+        vector_extension: Configured vector extension ("pgvector" or "vchord")
+        schema: Target PostgreSQL schema name (None for public)
+
+    Raises:
+        RuntimeError: If extension mismatch with existing data
+    """
+    schema_name = schema or "public"
+
+    engine = create_engine(database_url)
+    with engine.connect() as conn:
+        # Detect which vector extension should be used
+        target_ext = _detect_vector_extension(conn, vector_extension)
+        logger.info(f"Target vector extension: {target_ext}")
+
+        # Tables with vector indexes to check
+        tables_to_check = [
+            ("memory_units", "idx_memory_units_embedding"),
+            ("learnings", "idx_learnings_embedding"),
+            ("pinned_reflections", "idx_pinned_reflections_embedding"),
+        ]
+
+        # Determine target index type
+        if target_ext == "pgvectorscale":
+            target_index_type = "diskann"
+        elif target_ext == "vchord":
+            target_index_type = "vchordrq"
+        else:
+            target_index_type = "hnsw"
+
+        mismatched_tables = []
+        tables_with_data = []
+
+        for table_name, index_name in tables_to_check:
+            # Check if table exists
+            table_exists = conn.execute(
+                text("""
+                    SELECT EXISTS (
+                        SELECT 1 FROM information_schema.tables
+                        WHERE table_schema = :schema AND table_name = :table_name
+                    )
+                """),
+                {"schema": schema_name, "table_name": table_name},
+            ).scalar()
+
+            if not table_exists:
+                logger.debug(f"Table {table_name} does not exist in schema '{schema_name}', skipping")
+                continue
+
+            # Check current index type by querying pg_indexes
+            current_index_info = conn.execute(
+                text("""
+                    SELECT indexdef
+                    FROM pg_indexes
+                    WHERE schemaname = :schema
+                      AND tablename = :table_name
+                      AND indexname LIKE :index_pattern
+                """),
+                {"schema": schema_name, "table_name": table_name, "index_pattern": "%embedding%"},
+            ).fetchone()
+
+            if not current_index_info:
+                logger.warning(f"No embedding index found for {table_name}, will create it")
+                mismatched_tables.append((table_name, index_name, None))
+                continue
+
+            indexdef = current_index_info[0].lower()
+            if "diskann" in indexdef:
+                current_index_type = "diskann"
+            elif "vchordrq" in indexdef:
+                current_index_type = "vchordrq"
+            elif "hnsw" in indexdef:
+                current_index_type = "hnsw"
+            else:
+                logger.warning(f"Unknown index type for {table_name}: {indexdef}")
+                continue
+
+            # Check if index type matches target
+            if current_index_type != target_index_type:
+                logger.info(
+                    f"Index type mismatch on {table_name}: current={current_index_type}, target={target_index_type}"
+                )
+                mismatched_tables.append((table_name, index_name, current_index_type))
+
+                # Check if table has data
+                row_count = conn.execute(
+                    text(f"SELECT COUNT(*) FROM {schema_name}.{table_name} WHERE embedding IS NOT NULL")
+                ).scalar()
+
+                if row_count > 0:
+                    tables_with_data.append((table_name, row_count))
+            else:
+                logger.debug(f"Index type OK for {table_name}: {current_index_type}")
+
+        # If no mismatches, we're done
+        if not mismatched_tables:
+            logger.debug(f"All vector indexes match configured extension: {target_ext}")
+            return
+
+        # If there's data in any mismatched table, raise error
+        if tables_with_data:
+            table_list = ", ".join([f"{table}({count} rows)" for table, count in tables_with_data])
+            # Map index type back to extension name for error message
+            current_ext_name = {"diskann": "pgvectorscale", "vchordrq": "vchord", "hnsw": "pgvector"}.get(
+                current_index_type, current_index_type
+            )
+
+            raise RuntimeError(
+                f"Cannot change vector extension from {current_index_type} to {target_index_type}: "
+                f"the following tables contain data: {table_list}. "
+                f"To change vector extension, you must either:\n"
+                f"  1. Re-embed all data: DELETE FROM {schema_name}.memory_units; "
+                f"DELETE FROM {schema_name}.learnings; DELETE FROM {schema_name}.pinned_reflections; then restart\n"
+                f"  2. Use the current vector extension (set HINDSIGHT_API_VECTOR_EXTENSION='{current_ext_name}')"
+            )
+
+        # Tables are empty, safe to recreate indexes
+        logger.info(f"Recreating vector indexes for {target_ext}")
+
+        for table_name, index_name, current_type in mismatched_tables:
+            # Drop existing index if it exists
+            if current_type:
+                logger.info(f"Dropping {current_type} index on {table_name}")
+                conn.execute(text(f"DROP INDEX IF EXISTS {schema_name}.{index_name}"))
+
+            # Create new index with appropriate type
+            if target_ext == "pgvectorscale":
+                logger.info(f"Creating DiskANN index on {table_name}")
+                conn.execute(
+                    text(f"""
+                        CREATE INDEX IF NOT EXISTS {index_name}
+                        ON {schema_name}.{table_name}
+                        USING diskann (embedding vector_cosine_ops)
+                        WITH (num_neighbors = 50)
+                    """)
+                )
+            elif target_ext == "vchord":
+                logger.info(f"Creating vchordrq index on {table_name}")
+                conn.execute(
+                    text(f"""
+                        CREATE INDEX IF NOT EXISTS {index_name}
+                        ON {schema_name}.{table_name}
+                        USING vchordrq (embedding vector_l2_ops)
+                    """)
+                )
+            else:  # pgvector
+                logger.info(f"Creating HNSW index on {table_name}")
+                conn.execute(
+                    text(f"""
+                        CREATE INDEX IF NOT EXISTS {index_name}
+                        ON {schema_name}.{table_name}
+                        USING hnsw (embedding vector_cosine_ops)
+                        WITH (m = 16, ef_construction = 64)
+                    """)
+                )
+
+        conn.commit()
+        logger.info(f"Successfully migrated vector indexes to {target_ext}")
+
+
+def ensure_text_search_extension(
+    database_url: str,
+    text_search_extension: str = "native",
+    schema: str | None = None,
+) -> None:
+    """
+    Ensure the text search columns and indexes match the configured extension.
+
+    This function checks the current search_vector column type and index type
+    in the database and adjusts them if necessary:
+    - If they match configured extension: no action needed
+    - If they differ and tables are empty: drop old column/index, recreate with new type
+    - If they differ and tables have data: raise error with migration guidance
+
+    Args:
+        database_url: SQLAlchemy database URL
+        text_search_extension: Configured text search extension ("native" or "vchord")
+        schema: Target PostgreSQL schema name (None for public)
+
+    Raises:
+        RuntimeError: If extension mismatch with existing data
+    """
+    schema_name = schema or "public"
+
+    engine = create_engine(database_url)
+    with engine.connect() as conn:
+        # Tables with search_vector columns to check
+        tables_to_check = [
+            "memory_units",
+            "reflections",  # Renamed from pinned_reflections in p1k2l3m4n5o6 migration
+        ]
+
+        # Determine target column type and index type
+        if text_search_extension == "vchord":
+            target_column_type = "bm25vector"
+            target_index_type = "bm25"
+        elif text_search_extension == "pg_textsearch":
+            target_column_type = "text"
+            target_index_type = "bm25"
+        else:  # native
+            target_column_type = "tsvector"
+            target_index_type = "gin"
+
+        mismatched_tables = []
+        tables_with_data = []
+
+        for table_name in tables_to_check:
+            # Check if table exists
+            table_exists = conn.execute(
+                text("""
+                    SELECT EXISTS (
+                        SELECT 1 FROM information_schema.tables
+                        WHERE table_schema = :schema AND table_name = :table_name
+                    )
+                """),
+                {"schema": schema_name, "table_name": table_name},
+            ).scalar()
+
+            if not table_exists:
+                logger.debug(f"Table {table_name} does not exist in schema '{schema_name}', skipping")
+                continue
+
+            # Get current column type from information_schema
+            current_column_info = conn.execute(
+                text("""
+                    SELECT data_type, udt_name
+                    FROM information_schema.columns
+                    WHERE table_schema = :schema
+                      AND table_name = :table_name
+                      AND column_name = 'search_vector'
+                """),
+                {"schema": schema_name, "table_name": table_name},
+            ).fetchone()
+
+            if not current_column_info:
+                logger.warning(f"No search_vector column found for {table_name}, will create it")
+                mismatched_tables.append((table_name, None, None))
+                continue
+
+            # Check column type (udt_name contains the actual type: tsvector, bm25vector, etc.)
+            current_column_type = current_column_info[1]  # udt_name
+
+            # Get current index type
+            current_index_info = conn.execute(
+                text("""
+                    SELECT am.amname
+                    FROM pg_indexes pi
+                    JOIN pg_class c ON c.relname = pi.indexname
+                    JOIN pg_am am ON am.oid = c.relam
+                    WHERE pi.schemaname = :schema
+                      AND pi.tablename = :table_name
+                      AND pi.indexname LIKE '%text_search%'
+                """),
+                {"schema": schema_name, "table_name": table_name},
+            ).fetchone()
+
+            current_index_type = current_index_info[0] if current_index_info else None
+
+            # Check if column and index types match target
+            column_matches = current_column_type == target_column_type
+            index_matches = current_index_type == target_index_type if current_index_type else False
+
+            if not (column_matches and index_matches):
+                logger.info(
+                    f"Text search mismatch on {table_name}: "
+                    f"column={current_column_type} (want {target_column_type}), "
+                    f"index={current_index_type} (want {target_index_type})"
+                )
+                mismatched_tables.append((table_name, current_column_type, current_index_type))
+
+                # Check if table has data
+                row_count = conn.execute(text(f"SELECT COUNT(*) FROM {schema_name}.{table_name}")).scalar()
+
+                if row_count > 0:
+                    tables_with_data.append((table_name, row_count))
+            else:
+                logger.debug(f"Text search OK for {table_name}: {current_column_type}/{current_index_type}")
+
+        # If no mismatches, we're done
+        if not mismatched_tables:
+            logger.debug(f"All text search columns/indexes match configured extension: {text_search_extension}")
+            return
+
+        # If there's data in any mismatched table, raise error
+        if tables_with_data:
+            table_list = ", ".join([f"{table}({count} rows)" for table, count in tables_with_data])
+            # Detect current extension from column type
+            current_col_type = mismatched_tables[0][1]
+            if current_col_type == "tsvector":
+                current_ext = "native"
+            elif current_col_type == "bm25vector":
+                current_ext = "vchord"
+            elif current_col_type == "text":
+                current_ext = "pg_textsearch"
+            else:
+                current_ext = "unknown"
+            raise RuntimeError(
+                f"Cannot change text search extension from {current_ext} to {text_search_extension}: "
+                f"the following tables contain data: {table_list}. "
+                f"To change text search extension, you must either:\n"
+                f"  1. Clear all data: DELETE FROM {schema_name}.memory_units; "
+                f"DELETE FROM {schema_name}.reflections; then restart\n"
+                f"  2. Use the current text search extension (set HINDSIGHT_API_TEXT_SEARCH_EXTENSION='{current_ext}')"
+            )
+
+        # Tables are empty, safe to recreate columns/indexes
+        logger.info(f"Recreating text search columns/indexes for {text_search_extension}")
+
+        for table_name, current_col_type, current_idx_type in mismatched_tables:
+            # Drop existing index if it exists
+            if current_idx_type:
+                logger.info(f"Dropping {current_idx_type} index on {table_name}")
+                conn.execute(
+                    text(f"""
+                        DROP INDEX IF EXISTS {schema_name}.idx_{table_name.replace(".", "_")}_text_search
+                    """)
+                )
+
+            # Drop existing column if it exists
+            if current_col_type:
+                logger.info(f"Dropping {current_col_type} column on {table_name}")
+                conn.execute(text(f"ALTER TABLE {schema_name}.{table_name} DROP COLUMN IF EXISTS search_vector"))
+
+            # Create new column with appropriate type
+            if text_search_extension == "vchord":
+                logger.info(f"Creating bm25vector column on {table_name}")
+                # Note: vchord_bm25 extension creates types in bm25_catalog schema
+                conn.execute(
+                    text(f"ALTER TABLE {schema_name}.{table_name} ADD COLUMN search_vector bm25_catalog.bm25vector")
+                )
+
+                # Create BM25 index
+                logger.info(f"Creating BM25 index on {table_name}")
+                conn.execute(
+                    text(f"""
+                        CREATE INDEX idx_{table_name.replace(".", "_")}_text_search
+                        ON {schema_name}.{table_name}
+                        USING bm25 (search_vector bm25_catalog.bm25_ops)
+                    """)
+                )
+            elif text_search_extension == "pg_textsearch":
+                logger.info(f"Creating TEXT column on {table_name}")
+                # Dummy TEXT column for consistency (indexes operate on base columns)
+                conn.execute(text(f"ALTER TABLE {schema_name}.{table_name} ADD COLUMN search_vector TEXT"))
+
+                # Create BM25 index on expression
+                logger.info(f"Creating BM25 index on {table_name}")
+                # Different expression for each table
+                if table_name == "memory_units":
+                    index_expr = "(COALESCE(text, '') || ' ' || COALESCE(context, ''))"
+                else:  # reflections
+                    index_expr = "(COALESCE(name, '') || ' ' || content)"
+
+                conn.execute(
+                    text(f"""
+                        CREATE INDEX idx_{table_name.replace(".", "_")}_text_search
+                        ON {schema_name}.{table_name}
+                        USING bm25({index_expr})
+                        WITH (text_config='english')
+                    """)
+                )
+            else:  # native
+                logger.info(f"Creating tsvector column on {table_name}")
+                # Different GENERATED expression for each table
+                if table_name == "memory_units":
+                    generated_expr = "to_tsvector('english', COALESCE(text, '') || ' ' || COALESCE(context, ''))"
+                else:  # reflections
+                    generated_expr = "to_tsvector('english', COALESCE(name, '') || ' ' || content)"
+
+                conn.execute(
+                    text(f"""
+                        ALTER TABLE {schema_name}.{table_name}
+                        ADD COLUMN search_vector tsvector
+                        GENERATED ALWAYS AS ({generated_expr}) STORED
+                    """)
+                )
+
+                # Create GIN index
+                logger.info(f"Creating GIN index on {table_name}")
+                conn.execute(
+                    text(f"""
+                        CREATE INDEX idx_{table_name.replace(".", "_")}_text_search
+                        ON {schema_name}.{table_name}
+                        USING gin(search_vector)
+                    """)
+                )
+
+        conn.commit()
+        logger.info(f"Successfully migrated text search to {text_search_extension}")

hindsight-api/hindsight_api/models.py

@@ -20,7 +20,8 @@ class RequestContext:
     api_key: str | None = None
     api_key_id: str | None = None  # UUID of the API key used for authentication
     tenant_id: str | None = None  # Tenant identifier (set by extension after auth)
-    internal: bool = False  # True for background/internal operations (not user-visible)
+    internal: bool = False  # True for background/internal operations (skips extension auth)
+    user_initiated: bool = False  # True for async operations that originated from a user request
 
 
 from pgvector.sqlalchemy import Vector

hindsight-api/hindsight_api/tracing.py

@@ -0,0 +1,480 @@
+"""
+OpenTelemetry distributed tracing instrumentation for Hindsight API.
+
+This module provides tracing for:
+- LLM API calls with full prompts/completions following GenAI semantic conventions
+- Token usage and model information
+- Error tracking and finish reasons
+
+Tracing is conditional and disabled by default. When enabled, traces are exported
+to Langfuse (or any OTLP-compatible backend) via OTLP HTTP protocol.
+"""
+
+import json
+import logging
+import time
+from typing import Any, Optional
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+from opentelemetry.trace import Status, StatusCode
+
+logger = logging.getLogger(__name__)
+
+
+def _serialize_for_span(obj: Any) -> str:
+    """Serialize an object for span recording, handling Pydantic models."""
+    if isinstance(obj, str):
+        return obj
+    if hasattr(obj, "model_dump_json"):
+        # Pydantic v2 model
+        return obj.model_dump_json()
+    if hasattr(obj, "json"):
+        # Pydantic v1 model
+        return obj.json()
+    if hasattr(obj, "model_dump"):
+        # Pydantic v2 model - convert to dict then json
+        return json.dumps(obj.model_dump())
+    if hasattr(obj, "dict"):
+        # Pydantic v1 model - convert to dict then json
+        return json.dumps(obj.dict())
+    # Fallback to json.dumps for dicts and other types
+    return json.dumps(obj)
+
+
+# No-op tracer for when tracing is disabled
+class NoOpTracer:
+    """No-op tracer that provides the same interface as OpenTelemetry Tracer but does nothing."""
+
+    def start_as_current_span(self, name: str, **kwargs):
+        """Return a no-op context manager that yields a NoOpSpan."""
+        from contextlib import contextmanager
+
+        @contextmanager
+        def noop_span_context():
+            yield NoOpSpan()
+
+        return noop_span_context()
+
+    def start_span(self, name: str, **kwargs):
+        """Return a no-op span."""
+        return NoOpSpan()
+
+
+class NoOpSpan:
+    """No-op span that provides the same interface as OpenTelemetry Span but does nothing."""
+
+    def set_attribute(self, key: str, value: Any) -> None:
+        """No-op."""
+        pass
+
+    def set_status(self, status: Any) -> None:
+        """No-op."""
+        pass
+
+    def record_exception(self, exception: Exception) -> None:
+        """No-op."""
+        pass
+
+    def add_event(self, name: str, attributes: dict | None = None) -> None:
+        """No-op."""
+        pass
+
+    def end(self, end_time: int | None = None) -> None:
+        """No-op."""
+        pass
+
+
+# Global tracer instance
+_tracer: trace.Tracer | NoOpTracer = NoOpTracer()
+_tracing_enabled: bool = False
+
+
+# GenAI semantic convention attribute names (based on v1.37 spec)
+class GenAIAttributes:
+    """GenAI semantic convention attribute names."""
+
+    # Operation and provider
+    OPERATION_NAME = "gen_ai.operation.name"
+    PROVIDER_NAME = "gen_ai.provider.name"
+
+    # Model information
+    REQUEST_MODEL = "gen_ai.request.model"
+    RESPONSE_MODEL = "gen_ai.response.model"
+
+    # Token usage
+    USAGE_INPUT_TOKENS = "gen_ai.usage.input_tokens"
+    USAGE_OUTPUT_TOKENS = "gen_ai.usage.output_tokens"
+
+    # Messages and prompts
+    SYSTEM_INSTRUCTIONS = "gen_ai.system_instructions"
+    INPUT_MESSAGES = "gen_ai.input.messages"
+    OUTPUT_MESSAGES = "gen_ai.output.messages"
+
+    # Response metadata
+    FINISH_REASONS = "gen_ai.response.finish_reasons"
+
+    # Error tracking
+    ERROR_TYPE = "error.type"
+
+
+# Provider name mapping (Hindsight internal -> GenAI semantic convention)
+PROVIDER_NAME_MAPPING = {
+    "openai": "openai",
+    "anthropic": "anthropic",
+    "gemini": "google",
+    "vertexai": "google",
+    "groq": "groq",
+    "ollama": "ollama",
+    "lmstudio": "lmstudio",
+    "openai-codex": "openai",
+    "claude-code": "anthropic",
+    "mock": "mock",
+}
+
+
+def initialize_tracing(
+    service_name: str,
+    endpoint: str,
+    headers: Optional[str] = None,
+    deployment_environment: str = "development",
+) -> None:
+    """
+    Initialize OpenTelemetry tracing with OTLP exporter.
+
+    Args:
+        service_name: Name of the service for resource attributes
+        endpoint: OTLP endpoint URL (e.g., https://cloud.langfuse.com/api/public/otel)
+        headers: Optional headers in format "key1=value1,key2=value2"
+        deployment_environment: Deployment environment (e.g., development, staging, production)
+    """
+    global _tracer, _tracing_enabled
+
+    # Create resource with service information
+    resource = Resource.create(
+        {
+            "service.name": service_name,
+            "service.version": "0.4.8",  # Could import from __version__
+            "deployment.environment.name": deployment_environment,
+        }
+    )
+
+    # Parse headers
+    headers_dict = {}
+    if headers:
+        for pair in headers.split(","):
+            if "=" in pair:
+                key, value = pair.split("=", 1)
+                headers_dict[key.strip()] = value.strip()
+
+    # Create OTLP HTTP exporter
+    # Note: Langfuse expects /v1/traces path appended to base endpoint
+    otlp_endpoint = endpoint if endpoint.endswith("/v1/traces") else f"{endpoint}/v1/traces"
+    otlp_exporter = OTLPSpanExporter(
+        endpoint=otlp_endpoint,
+        headers=headers_dict,
+    )
+
+    # Create tracer provider with batch processor
+    provider = TracerProvider(resource=resource)
+    provider.add_span_processor(BatchSpanProcessor(otlp_exporter))
+
+    # Set global tracer provider
+    trace.set_tracer_provider(provider)
+
+    # Get tracer for this application
+    _tracer = trace.get_tracer(__name__)
+    _tracing_enabled = True
+
+    logger.info(f"Tracing initialized: endpoint={otlp_endpoint}, service={service_name}")
+
+
+def get_tracer() -> trace.Tracer | NoOpTracer:
+    """
+    Get the global tracer instance.
+
+    Returns a no-op tracer if tracing is disabled, so callers don't need to check for None.
+    This improves code readability by allowing direct use without null checks.
+    """
+    return _tracer
+
+
+def create_operation_span(operation: str, bank_id: str | None = None):
+    """
+    Create a parent span for a Hindsight operation (retain, reflect, consolidation, etc.).
+
+    This creates the span hierarchy:
+    - hindsight.{operation} (parent)
+      - chat {model} (child LLM calls)
+
+    Args:
+        operation: Operation name (retain, reflect, consolidation, mental_model_refresh)
+        bank_id: Optional bank ID for context
+
+    Returns:
+        Span context manager
+    """
+    if not _tracing_enabled or _tracer is None:
+        # Return a no-op context manager
+        from contextlib import nullcontext
+
+        return nullcontext()
+
+    span_name = f"hindsight.{operation}"
+    span = _tracer.start_as_current_span(span_name)
+
+    # Add operation-specific attributes
+    if span and hasattr(span, "set_attribute"):
+        span.set_attribute("hindsight.operation", operation)
+        if bank_id:
+            span.set_attribute("hindsight.bank_id", bank_id)
+
+    return span
+
+
+def is_tracing_enabled() -> bool:
+    """Check if tracing is enabled."""
+    return _tracing_enabled
+
+
+# Maximum content length before truncation (to stay within span size limits)
+MAX_CONTENT_LENGTH = 100_000  # characters
+
+
+def _truncate_content(content: str) -> str:
+    """Truncate content if too large for span."""
+    if len(content) > MAX_CONTENT_LENGTH:
+        return content[:MAX_CONTENT_LENGTH] + f"\n\n[TRUNCATED: {len(content) - MAX_CONTENT_LENGTH} chars omitted]"
+    return content
+
+
+class LLMSpanRecorder:
+    """
+    Records OpenTelemetry spans for LLM calls following GenAI semantic conventions.
+    """
+
+    def __init__(self, tracer: trace.Tracer):
+        self.tracer = tracer
+
+    def record_llm_call(
+        self,
+        provider: str,
+        model: str,
+        scope: str,
+        messages: list[dict[str, str]],
+        response_content: Optional[str],
+        input_tokens: int,
+        output_tokens: int,
+        duration: float,
+        finish_reason: Optional[str] = None,
+        error: Optional[Exception] = None,
+        tool_calls: Optional[list[dict[str, Any]]] = None,
+    ) -> None:
+        """
+        Record a completed LLM call as a span with GenAI semantic conventions.
+
+        This creates a span AFTER the call completes, using timestamps to
+        set the correct start/end times. This approach works better with
+        the existing sync metrics recording pattern.
+
+        Args:
+            provider: Hindsight provider name
+            model: Model name
+            scope: Scope identifier (memory, reflect, consolidation, etc.)
+            messages: Input messages (chat history)
+            response_content: Response text from LLM
+            input_tokens: Input token count
+            output_tokens: Output token count
+            duration: Call duration in seconds
+            finish_reason: Reason the model stopped (stop, length, tool_calls, etc.)
+            error: Exception if call failed
+            tool_calls: List of tool calls made (for function calling)
+        """
+        try:
+            # Map provider name to GenAI semantic convention
+            genai_provider = PROVIDER_NAME_MAPPING.get(provider.lower(), provider.lower())
+
+            # Determine operation name based on scope/context
+            operation_name = "chat"  # Default for GenAI semantic conventions
+
+            # Create span name: "hindsight.{scope}" for consistency with parent spans
+            # Model info is available in span attributes (gen_ai.request.model)
+            if scope:
+                span_name = f"hindsight.{scope}"
+            else:
+                # Fallback to chat {model} if no scope provided
+                span_name = f"{operation_name} {model}"
+
+            # Calculate timestamps
+            end_time_ns = time.time_ns()
+            start_time_ns = end_time_ns - int(duration * 1_000_000_000)
+
+            # Create span with explicit timestamps
+            with self.tracer.start_as_current_span(
+                span_name,
+                start_time=start_time_ns,
+                end_on_exit=False,  # We'll set end time manually
+            ) as span:
+                # Set required attributes
+                span.set_attribute(GenAIAttributes.OPERATION_NAME, operation_name)
+                span.set_attribute(GenAIAttributes.PROVIDER_NAME, genai_provider)
+                span.set_attribute(GenAIAttributes.REQUEST_MODEL, model)
+                span.set_attribute(GenAIAttributes.RESPONSE_MODEL, model)
+                span.set_attribute(GenAIAttributes.USAGE_INPUT_TOKENS, input_tokens)
+                span.set_attribute(GenAIAttributes.USAGE_OUTPUT_TOKENS, output_tokens)
+
+                # Add custom attributes for Hindsight context
+                span.set_attribute("hindsight.scope", scope)
+                span.set_attribute("hindsight.provider.internal", provider)
+
+                # Add tool call information if present
+                if tool_calls:
+                    span.set_attribute("gen_ai.tool_calls.count", len(tool_calls))
+                    # Add tool names as comma-separated list
+                    tool_names = [tc.get("name", "") for tc in tool_calls]
+                    span.set_attribute("gen_ai.tool_calls.names", ",".join(tool_names))
+
+                # Format messages for GenAI conventions (as JSON)
+                input_messages_json = self._format_messages(messages)
+                output_messages_json = self._format_output(response_content, finish_reason)
+
+                # Extract system instructions if present
+                system_instructions = self._extract_system_instructions(messages)
+
+                # Add event with prompts/completions following v1.37 conventions
+                event_attrs = {}
+                if input_messages_json:
+                    event_attrs[GenAIAttributes.INPUT_MESSAGES] = input_messages_json
+                if output_messages_json:
+                    event_attrs[GenAIAttributes.OUTPUT_MESSAGES] = output_messages_json
+                if system_instructions:
+                    event_attrs[GenAIAttributes.SYSTEM_INSTRUCTIONS] = system_instructions
+                if finish_reason:
+                    event_attrs[GenAIAttributes.FINISH_REASONS] = json.dumps([finish_reason])
+
+                span.add_event(
+                    "gen_ai.client.inference.operation.details",
+                    attributes=event_attrs,
+                )
+
+                # Add individual tool call events with details
+                if tool_calls:
+                    for i, tc in enumerate(tool_calls):
+                        tool_event_attrs = {
+                            "tool.name": tc.get("name", ""),
+                            "tool.id": tc.get("id", ""),
+                            "tool.arguments": json.dumps(tc.get("arguments", {})),
+                        }
+                        span.add_event(f"gen_ai.tool_call.{i}", attributes=tool_event_attrs)
+
+                # Handle errors
+                if error:
+                    span.set_status(Status(StatusCode.ERROR, str(error)))
+                    span.set_attribute(GenAIAttributes.ERROR_TYPE, type(error).__name__)
+                    span.record_exception(error)
+                else:
+                    span.set_status(Status(StatusCode.OK))
+
+                # Set end time
+                span.end(end_time=end_time_ns)
+
+        except Exception as e:
+            # Don't let tracing errors break LLM calls
+            logger.error(f"Failed to record LLM span: {e}", exc_info=True)
+
+    def _format_messages(self, messages: list[dict[str, str]]) -> str:
+        """
+        Format messages into GenAI semantic convention format (JSON array).
+
+        Returns JSON string representation of message array.
+        """
+        try:
+            formatted = []
+            for msg in messages:
+                content = msg.get("content", "")
+                # Truncate if needed
+                if isinstance(content, str):
+                    content = _truncate_content(content)
+
+                formatted.append(
+                    {
+                        "role": msg.get("role", "user"),
+                        "content": content,
+                    }
+                )
+
+            return json.dumps(formatted)
+        except Exception as e:
+            logger.warning(f"Failed to format input messages: {e}")
+            return "[]"
+
+    def _format_output(
+        self,
+        content: Optional[str],
+        finish_reason: Optional[str],
+    ) -> str:
+        """Format output message into GenAI semantic convention format."""
+        try:
+            if content is None:
+                return "[]"
+
+            # Truncate if needed
+            if isinstance(content, str):
+                content = _truncate_content(content)
+
+            return json.dumps(
+                [
+                    {
+                        "role": "assistant",
+                        "content": content,
+                    }
+                ]
+            )
+        except Exception as e:
+            logger.warning(f"Failed to format output message: {e}")
+            return "[]"
+
+    def _extract_system_instructions(self, messages: list[dict[str, str]]) -> Optional[str]:
+        """Extract system instructions from messages if present."""
+        try:
+            for msg in messages:
+                if msg.get("role") == "system":
+                    content = msg.get("content", "")
+                    if isinstance(content, str):
+                        return _truncate_content(content)
+                    return str(content)
+        except Exception as e:
+            logger.warning(f"Failed to extract system instructions: {e}")
+        return None
+
+
+class NoOpLLMSpanRecorder:
+    """No-op span recorder for when tracing is disabled."""
+
+    def record_llm_call(self, **kwargs) -> None:
+        """No-op."""
+        pass
+
+
+# Global span recorder instance
+_span_recorder: Optional[LLMSpanRecorder] = None
+
+
+def get_span_recorder() -> LLMSpanRecorder | NoOpLLMSpanRecorder:
+    """Get the global span recorder (NoOp if tracing disabled)."""
+    if _span_recorder is None:
+        return NoOpLLMSpanRecorder()
+    return _span_recorder
+
+
+def create_span_recorder() -> LLMSpanRecorder:
+    """Create and set the global span recorder."""
+    global _span_recorder
+    tracer = get_tracer()
+    if tracer is None:
+        raise RuntimeError("Tracing not initialized. Call initialize_tracing() first.")
+    _span_recorder = LLMSpanRecorder(tracer)
+    return _span_recorder

hindsight-api/hindsight_api/utils.py

@@ -0,0 +1,13 @@
+from urllib.parse import urlparse, urlunparse
+
+
+def mask_network_location(url):
+    if not url:
+        return url
+    parsed_url = urlparse(url)
+    masked_network_location = parsed_url.hostname or ""
+    if parsed_url.port:
+        masked_network_location += f":{parsed_url.port}"
+    if parsed_url.username or parsed_url.password:
+        masked_network_location = f"***:***@{masked_network_location}"
+    return urlunparse(parsed_url._replace(netloc=masked_network_location))

hindsight-api/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hindsight-api"
-version = "0.4.9"
+version = "0.4.11"
 description = "Hindsight: Agent Memory That Works Like Human Memory"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -25,6 +25,7 @@ dependencies = [
     "psycopg2-binary>=2.9.11",
     "tiktoken>=0.12.0",
     "httpx>=0.27.0",
+    "PyJWT[crypto]>=2.8.0",
     "fastmcp>=2.14.0", # CVE-2025-66416
     "pg0-embedded>=0.11.0",
     "python-dateutil>=2.8.0",
@@ -32,6 +33,8 @@ dependencies = [
     "opentelemetry-sdk>=1.20.0",
     "opentelemetry-instrumentation-fastapi>=0.41b0",
     "opentelemetry-exporter-prometheus>=0.41b0",
+    "opentelemetry-exporter-otlp-proto-http>=1.20.0",
+    "opentelemetry-semantic-conventions>=0.41b0",
     "dateparser>=1.2.2",
     "google-genai>=1.0.0",
     "google-auth>=2.0.0",
@@ -39,6 +42,7 @@ dependencies = [
     "typer>=0.9.0",
     "cohere>=5.0.0",
     "flashrank>=0.2.0",
+    "litellm>=1.0.0",
     # Local ML models for embeddings/reranking - can be excluded in Docker with INCLUDE_LOCAL_MODELS=false
     "sentence-transformers>=3.3.0",
     "transformers>=4.53.0", # Security fixes for ReDoS vulnerabilities

hindsight-api/tests/test_async_retain_tags.py

@@ -0,0 +1,70 @@
+"""Unit tests for async retain tag propagation."""
+
+from unittest.mock import AsyncMock
+
+import pytest
+
+from hindsight_api.engine.memory_engine import MemoryEngine
+from hindsight_api.models import RequestContext
+
+
+@pytest.mark.asyncio
+async def test_submit_async_retain_includes_document_tags_in_task_payload():
+    """submit_async_retain should include document_tags in queued task payload."""
+    engine = MemoryEngine.__new__(MemoryEngine)
+    engine._authenticate_tenant = AsyncMock()
+    engine._submit_async_operation = AsyncMock(return_value={"operation_id": "op-1"})
+
+    request_context = RequestContext(tenant_id="tenant-a", api_key_id="key-a")
+    contents = [{"content": "Async retain payload test."}]
+    document_tags = ["scope:tools", "user:alice"]
+
+    result = await MemoryEngine.submit_async_retain(
+        engine,
+        bank_id="bank-1",
+        contents=contents,
+        document_tags=document_tags,
+        request_context=request_context,
+    )
+
+    assert result == {"operation_id": "op-1", "items_count": 1}
+    engine._authenticate_tenant.assert_awaited_once_with(request_context)
+    engine._submit_async_operation.assert_awaited_once()
+
+    kwargs = engine._submit_async_operation.await_args.kwargs
+    assert kwargs["bank_id"] == "bank-1"
+    assert kwargs["operation_type"] == "retain"
+    assert kwargs["task_type"] == "batch_retain"
+    assert kwargs["task_payload"]["contents"] == contents
+    assert kwargs["task_payload"]["document_tags"] == document_tags
+    assert kwargs["task_payload"]["_tenant_id"] == "tenant-a"
+    assert kwargs["task_payload"]["_api_key_id"] == "key-a"
+
+
+@pytest.mark.asyncio
+async def test_handle_batch_retain_forwards_document_tags_to_retain_batch_async():
+    """Worker handler should forward document_tags from task payload."""
+    engine = MemoryEngine.__new__(MemoryEngine)
+    engine.retain_batch_async = AsyncMock(return_value={"items_count": 1})
+
+    task_dict = {
+        "bank_id": "bank-1",
+        "contents": [{"content": "Forward tags test."}],
+        "document_tags": ["scope:client"],
+        "_tenant_id": "tenant-a",
+        "_api_key_id": "key-a",
+    }
+
+    await MemoryEngine._handle_batch_retain(engine, task_dict)
+
+    engine.retain_batch_async.assert_awaited_once()
+    kwargs = engine.retain_batch_async.await_args.kwargs
+    assert kwargs["bank_id"] == "bank-1"
+    assert kwargs["contents"] == task_dict["contents"]
+    assert kwargs["document_tags"] == ["scope:client"]
+
+    request_context = kwargs["request_context"]
+    assert request_context.internal is True
+    assert request_context.user_initiated is True
+    assert request_context.tenant_id == "tenant-a"
+    assert request_context.api_key_id == "key-a"

hindsight-api/tests/test_base_path.py

@@ -0,0 +1,189 @@
+"""
+Integration test for API base path support.
+
+Tests that the API works correctly when deployed with a base path (e.g., /hindsight)
+for reverse proxy deployments.
+"""
+import os
+import pytest
+import pytest_asyncio
+import httpx
+from hindsight_api.api import create_app
+from hindsight_api.config import clear_config_cache
+
+
+@pytest_asyncio.fixture
+async def api_client_with_base_path(memory):
+    """Create an async test client for the FastAPI app with a base path."""
+    # Set base path in environment
+    base_path = "/hindsight"
+    os.environ["HINDSIGHT_API_BASE_PATH"] = base_path
+
+    # Clear config cache to force reload with new base_path
+    clear_config_cache()
+
+    # Memory is already initialized by the conftest fixture (with migrations)
+    app = create_app(memory, initialize_memory=False)
+
+    # Use base_url with base path
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(
+        transport=transport,
+        base_url=f"http://test{base_path}"
+    ) as client:
+        yield client
+
+    # Cleanup: unset base path
+    os.environ.pop("HINDSIGHT_API_BASE_PATH", None)
+    clear_config_cache()
+
+
+@pytest_asyncio.fixture
+async def api_client_without_base_path(memory):
+    """Create an async test client for the FastAPI app without a base path (root)."""
+    # Ensure no base path is set
+    os.environ.pop("HINDSIGHT_API_BASE_PATH", None)
+    clear_config_cache()
+
+    app = create_app(memory, initialize_memory=False)
+    transport = httpx.ASGITransport(app=app)
+    async with httpx.AsyncClient(transport=transport, base_url="http://test") as client:
+        yield client
+
+
+@pytest.mark.asyncio
+async def test_base_path_health_endpoint(api_client_with_base_path):
+    """Test that health endpoint works with base path."""
+    # With base path set to /hindsight, health should be at /hindsight/health
+    # But since our client base_url is already http://test/hindsight, we request /health
+    response = await api_client_with_base_path.get("/health")
+    assert response.status_code == 200
+    data = response.json()
+    assert "status" in data
+    assert data["status"] in ["ok", "healthy"]  # Accept both formats
+
+
+@pytest.mark.asyncio
+async def test_base_path_banks_endpoint(api_client_with_base_path):
+    """Test that banks endpoint works with base path."""
+    response = await api_client_with_base_path.get("/v1/default/banks")
+    assert response.status_code == 200
+    data = response.json()
+    assert "banks" in data
+
+
+@pytest.mark.asyncio
+async def test_base_path_openapi_schema(api_client_with_base_path):
+    """Test that OpenAPI schema includes correct base path in servers."""
+    response = await api_client_with_base_path.get("/openapi.json")
+    assert response.status_code == 200
+    openapi_schema = response.json()
+
+    # Check that servers array includes base path
+    assert "servers" in openapi_schema
+    servers = openapi_schema["servers"]
+    assert len(servers) > 0
+    # FastAPI should set server URL to the root_path
+    assert servers[0]["url"] == "/hindsight"
+
+
+@pytest.mark.asyncio
+async def test_base_path_docs_redirect(api_client_with_base_path):
+    """Test that /docs redirects correctly with base path."""
+    # FastAPI docs endpoint should work
+    response = await api_client_with_base_path.get("/docs", follow_redirects=False)
+    # Should either return 200 (direct) or 307 (redirect to trailing slash)
+    assert response.status_code in [200, 307]
+
+
+@pytest.mark.asyncio
+async def test_base_path_metrics(api_client_with_base_path):
+    """Test that metrics endpoint works with base path."""
+    response = await api_client_with_base_path.get("/metrics")
+    assert response.status_code == 200
+    # Metrics should be in Prometheus format
+    assert "# HELP" in response.text or "# TYPE" in response.text
+
+
+@pytest.mark.asyncio
+async def test_base_path_full_workflow(api_client_with_base_path):
+    """
+    Test a full retain/recall workflow with base path.
+
+    This ensures that all memory operations work correctly when the API
+    is deployed with a base path.
+    """
+    bank_id = "test_base_path_bank"
+
+    # 1. Create/get bank
+    response = await api_client_with_base_path.get(f"/v1/default/banks/{bank_id}/profile")
+    assert response.status_code == 200
+
+    # 2. Store a memory
+    response = await api_client_with_base_path.post(
+        f"/v1/default/banks/{bank_id}/memories",
+        json={
+            "items": [
+                {
+                    "content": "The API supports base path deployment for reverse proxy use cases.",
+                    "context": "testing base path feature"
+                }
+            ]
+        }
+    )
+    assert response.status_code == 200
+    result = response.json()
+    assert result["success"] is True
+
+    # 3. Recall the memory
+    response = await api_client_with_base_path.post(
+        f"/v1/default/banks/{bank_id}/memories/recall",
+        json={
+            "query": "base path support"
+        }
+    )
+    assert response.status_code == 200
+    recall_result = response.json()
+    # API returns "results" not "memories"
+    assert "results" in recall_result
+    assert len(recall_result["results"]) > 0
+
+
+@pytest.mark.asyncio
+async def test_without_base_path_still_works(api_client_without_base_path):
+    """
+    Regression test: ensure default behavior (no base path) still works.
+
+    This test verifies that when HINDSIGHT_API_BASE_PATH is not set,
+    the API works at the root path as before.
+    """
+    # Health check at root
+    response = await api_client_without_base_path.get("/health")
+    assert response.status_code == 200
+
+    # Banks endpoint at root
+    response = await api_client_without_base_path.get("/v1/default/banks")
+    assert response.status_code == 200
+
+    # OpenAPI schema should have empty or "/" server path
+    response = await api_client_without_base_path.get("/openapi.json")
+    assert response.status_code == 200
+    openapi_schema = response.json()
+    servers = openapi_schema.get("servers", [])
+    if servers:
+        # Server URL should be empty string (root) or "/"
+        assert servers[0]["url"] in ["", "/"]
+
+
+@pytest.mark.skip(reason="MCP endpoint routing with base path needs investigation")
+@pytest.mark.asyncio
+async def test_base_path_mcp_endpoint(api_client_with_base_path):
+    """Test that MCP endpoint is accessible with base path."""
+    bank_id = "test_mcp_bank"
+
+    # MCP endpoint should be mounted at /mcp/{bank_id}/
+    # The MCP server uses a different protocol, so just check the root exists
+    response = await api_client_with_base_path.get(f"/mcp/{bank_id}/")
+    # MCP may return various status codes, but should not be 404 (not found)
+    # Accept 405 (method not allowed), 400 (bad request), etc.
+    assert response.status_code != 404, "MCP endpoint should exist"

hindsight-api/tests/test_causal_relations.py

@@ -12,6 +12,7 @@ from datetime import datetime
 import pytest
 
 from hindsight_api import LLMConfig
+from hindsight_api.config import _get_raw_config
 from hindsight_api.engine.retain.fact_extraction import extract_facts_from_text
 
 
@@ -44,6 +45,7 @@ class TestCausalRelationsValidation:
             context=context,
             llm_config=llm_config,
             agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -88,6 +90,7 @@ class TestCausalRelationsValidation:
             context=context,
             llm_config=llm_config,
             agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -124,6 +127,7 @@ class TestCausalRelationsValidation:
             context=context,
             llm_config=llm_config,
             agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract facts about the causal chain"
@@ -173,6 +177,7 @@ class TestCausalRelationsValidation:
             context=context,
             llm_config=llm_config,
             agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract facts"
@@ -209,6 +214,7 @@ class TestCausalRelationsValidation:
             context=context,
             llm_config=llm_config,
             agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         # Verify relation types are all backward-looking

hindsight-api/tests/test_causal_relationships.py

@@ -10,6 +10,7 @@ from datetime import datetime
 import pytest
 
 from hindsight_api import LLMConfig
+from hindsight_api.config import _get_raw_config
 from hindsight_api.engine.retain.fact_extraction import extract_facts_from_text
 
 
@@ -37,7 +38,8 @@ After searching for weeks, I finally found a cheaper apartment in Brooklyn.
         llm_config = LLMConfig.for_memory()
 
         facts, _, _ = await extract_facts_from_text(
-            text=text, event_date=datetime(2024, 3, 15), context=context, llm_config=llm_config, agent_name="TestUser"
+            text=text, event_date=datetime(2024, 3, 15), context=context, llm_config=llm_config, agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) >= 3, f"Should extract at least 3 facts from the causal chain. Got {len(facts)}"
@@ -106,7 +108,8 @@ The renovation took three months and cost $15,000.
         llm_config = LLMConfig.for_memory()
 
         facts, _, _ = await extract_facts_from_text(
-            text=text, event_date=datetime(2024, 6, 1), context=context, llm_config=llm_config, agent_name="TestUser"
+            text=text, event_date=datetime(2024, 6, 1), context=context, llm_config=llm_config, agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) >= 4, f"Should extract at least 4 facts. Got {len(facts)}"
@@ -136,7 +139,8 @@ Machine learning fascinated me so much that I changed my career to data science.
         llm_config = LLMConfig.for_memory()
 
         facts, _, _ = await extract_facts_from_text(
-            text=text, event_date=datetime(2024, 1, 1), context=context, llm_config=llm_config, agent_name="TestUser"
+            text=text, event_date=datetime(2024, 1, 1), context=context, llm_config=llm_config, agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         # Check no fact references itself
@@ -163,7 +167,8 @@ The new role enabled me to lead a team of engineers.
         llm_config = LLMConfig.for_memory()
 
         facts, _, _ = await extract_facts_from_text(
-            text=text, event_date=datetime(2024, 2, 15), context=context, llm_config=llm_config, agent_name="TestUser"
+            text=text, event_date=datetime(2024, 2, 15), context=context, llm_config=llm_config, agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         # Validate all indices (must reference PREVIOUS facts only)
@@ -190,7 +195,8 @@ Reduced spending somewhat affected local businesses.
         llm_config = LLMConfig.for_memory()
 
         facts, _, _ = await extract_facts_from_text(
-            text=text, event_date=datetime(2024, 4, 1), context=context, llm_config=llm_config, agent_name="TestUser"
+            text=text, event_date=datetime(2024, 4, 1), context=context, llm_config=llm_config, agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         for i, fact in enumerate(facts):

hindsight-api/tests/test_config_validation.py

@@ -0,0 +1,109 @@
+"""
+Tests for configuration validation.
+
+Verifies that config validation catches invalid parameter combinations.
+"""
+
+import os
+
+import pytest
+
+
+@pytest.fixture(autouse=True)
+def setup_test_env():
+    """Set up environment for each test, restoring original values after."""
+    from hindsight_api.config import clear_config_cache
+
+    # Save original environment values
+    env_vars_to_save = [
+        "HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS",
+        "HINDSIGHT_API_RETAIN_CHUNK_SIZE",
+        "HINDSIGHT_API_LLM_PROVIDER",
+        "HINDSIGHT_API_LLM_MODEL",
+    ]
+
+    # Save original values
+    original_values = {}
+    for key in env_vars_to_save:
+        original_values[key] = os.environ.get(key)
+
+    clear_config_cache()
+
+    yield
+
+    # Restore original environment
+    for key, original_value in original_values.items():
+        if original_value is None:
+            os.environ.pop(key, None)
+        else:
+            os.environ[key] = original_value
+
+    clear_config_cache()
+
+
+def test_retain_max_completion_tokens_must_be_greater_than_chunk_size():
+    """Test that RETAIN_MAX_COMPLETION_TOKENS > RETAIN_CHUNK_SIZE validation works."""
+    from hindsight_api.config import HindsightConfig
+
+    # Set invalid config: max_completion_tokens <= chunk_size
+    os.environ["HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS"] = "1000"
+    os.environ["HINDSIGHT_API_RETAIN_CHUNK_SIZE"] = "2000"
+    os.environ["HINDSIGHT_API_LLM_PROVIDER"] = "mock"
+
+    # Should raise ValueError with helpful message
+    with pytest.raises(ValueError) as exc_info:
+        HindsightConfig.from_env()
+
+    error_message = str(exc_info.value)
+
+    # Verify error message contains helpful information
+    assert "HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS" in error_message
+    assert "1000" in error_message
+    assert "HINDSIGHT_API_RETAIN_CHUNK_SIZE" in error_message
+    assert "2000" in error_message
+    assert "must be greater than" in error_message
+    assert "You have two options to fix this:" in error_message
+    assert "Increase HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS" in error_message
+    assert "Use a model that supports" in error_message
+
+
+def test_retain_max_completion_tokens_equal_to_chunk_size_fails():
+    """Test that RETAIN_MAX_COMPLETION_TOKENS == RETAIN_CHUNK_SIZE also fails."""
+    from hindsight_api.config import HindsightConfig
+
+    # Set invalid config: max_completion_tokens == chunk_size
+    os.environ["HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS"] = "3000"
+    os.environ["HINDSIGHT_API_RETAIN_CHUNK_SIZE"] = "3000"
+    os.environ["HINDSIGHT_API_LLM_PROVIDER"] = "mock"
+
+    # Should raise ValueError
+    with pytest.raises(ValueError) as exc_info:
+        HindsightConfig.from_env()
+
+    error_message = str(exc_info.value)
+    assert "must be greater than" in error_message
+
+
+def test_valid_retain_config_succeeds():
+    """Test that valid config with max_completion_tokens > chunk_size works."""
+    from hindsight_api.config import HindsightConfig
+
+    # Set valid config: max_completion_tokens > chunk_size
+    os.environ["HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS"] = "64000"
+    os.environ["HINDSIGHT_API_RETAIN_CHUNK_SIZE"] = "3000"
+    os.environ["HINDSIGHT_API_LLM_PROVIDER"] = "mock"
+
+    # Should not raise
+    config = HindsightConfig.from_env()
+    assert config.retain_max_completion_tokens == 64000
+    assert config.retain_chunk_size == 3000
+
+
+# Note: The BadRequestError wrapping is implemented in fact_extraction.py
+# but requires a complex integration test setup. The functionality is
+# straightforward: when a BadRequestError containing keywords like
+# "max_tokens", "max_completion_tokens", or "maximum context" is caught,
+# it's wrapped in a ValueError with helpful guidance.
+#
+# The config validation tests above ensure users get early feedback
+# about invalid configurations before runtime errors occur.

hindsight-api/tests/test_consolidation.py

@@ -21,9 +21,9 @@ from hindsight_api.engine.reflect.tools import (
 @pytest.fixture(autouse=True)
 def enable_observations():
     """Enable observations for all tests in this module."""
-    from hindsight_api.config import get_config
+    from hindsight_api.config import _get_raw_config
 
-    config = get_config()
+    config = _get_raw_config()
     original_value = config.enable_observations
     config.enable_observations = True
     yield
@@ -563,25 +563,26 @@ class TestConsolidationDisabled:
         self, memory: MemoryEngine, request_context
     ):
         """Test that consolidation returns disabled status when enable_observations is False."""
-        from unittest.mock import patch
-
         bank_id = f"test-consolidation-disabled-{uuid.uuid4().hex[:8]}"
 
         # Create the bank
         await memory.get_bank_profile(bank_id=bank_id, request_context=request_context)
 
-        # Disable observations via config
-        with patch("hindsight_api.config.get_config") as mock_config:
-            mock_config.return_value.enable_observations = False
+        # Disable observations for this bank via bank config
+        await memory._config_resolver.update_bank_config(
+            bank_id=bank_id,
+            updates={"enable_observations": False},
+            context=request_context,
+        )
 
-            result = await run_consolidation_job(
-                memory_engine=memory,
-                bank_id=bank_id,
-                request_context=request_context,
-            )
+        result = await run_consolidation_job(
+            memory_engine=memory,
+            bank_id=bank_id,
+            request_context=request_context,
+        )
 
-            assert result["status"] == "disabled"
-            assert result["bank_id"] == bank_id
+        assert result["status"] == "disabled"
+        assert result["bank_id"] == bank_id
 
         # Cleanup
         await memory.delete_bank(bank_id, request_context=request_context)

hindsight-api/tests/test_extensions.py

@@ -353,6 +353,14 @@ class TestOperationHooksParameters:
         assert post_result.error is None
         assert post_result.unit_ids == result  # Should match the return value
 
+        # Verify actual LLM token usage is populated
+        assert post_result.llm_input_tokens is not None
+        assert post_result.llm_input_tokens > 0
+        assert post_result.llm_output_tokens is not None
+        assert post_result.llm_output_tokens > 0
+        assert post_result.llm_total_tokens is not None
+        assert post_result.llm_total_tokens == post_result.llm_input_tokens + post_result.llm_output_tokens
+
     @pytest.mark.asyncio
     async def test_recall_pre_hook_receives_all_parameters(self, memory_with_tracking_validator):
         """Pre-recall hook receives all user-provided parameters."""

hindsight-api/tests/test_fact_extraction_analysis.py

@@ -8,7 +8,7 @@ from datetime import datetime
 
 import pytest
 
-from hindsight_api.config import get_config, clear_config_cache
+from hindsight_api.config import get_config, clear_config_cache, _get_raw_config
 from hindsight_api.engine.llm_wrapper import LLMConfig
 from hindsight_api.engine.retain.fact_extraction import extract_facts_from_text
 
@@ -58,6 +58,7 @@ async def test_fact_extraction_basic_analysis(llm_config):
         llm_config=llm_config,
         agent_name="test-agent",
         context="Friday Standup meeting",
+        config=_get_raw_config(),
     )
 
     duration = time.time() - start_time

hindsight-api/tests/test_fact_extraction_output_ratio.py

@@ -11,6 +11,7 @@ from datetime import datetime
 import pytest
 
 from hindsight_api import LLMConfig
+from hindsight_api.config import _get_raw_config
 from hindsight_api.engine.retain.fact_extraction import extract_facts_from_text
 
 
@@ -44,7 +45,8 @@ I ran into my neighbor Sarah who mentioned she's planning a trip to Italy next m
             event_date=datetime(2024, 6, 15),
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         input_length = len(text)
@@ -88,7 +90,8 @@ User: Perfect, I'll make a reservation for Saturday at 7pm.
             event_date=datetime(2024, 6, 15),
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         input_length = len(text)
@@ -144,7 +147,8 @@ I edited about 20 photos from my recent trip to the mountains.
             event_date=datetime(2024, 4, 15),
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         input_length = len(text)
@@ -208,7 +212,8 @@ I edited about 20 photos from my recent trip to the mountains.
             event_date=datetime(2023, 5, 8),  # Date from locomo dataset
             context=context,
             llm_config=llm_config,
-            agent_name=data["conversation"]["speaker_a"]
+            agent_name=data["conversation"]["speaker_a"],
+            config=_get_raw_config(),
         )
 
         # Calculate ratios
@@ -269,7 +274,8 @@ I'm planning to visit Japan next year.
             event_date=datetime(2024, 6, 15),
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         # Count approximate number of statements (sentences)

hindsight-api/tests/test_fact_extraction_quality.py

@@ -17,6 +17,7 @@ from datetime import UTC, datetime
 import pytest
 
 from hindsight_api import LLMConfig
+from hindsight_api.config import _get_raw_config
 from hindsight_api.engine.retain.fact_extraction import extract_facts_from_text
 
 # =============================================================================
@@ -48,7 +49,8 @@ Marcus felt anxious about the upcoming interview.
             event_date=datetime(2024, 11, 13),
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -80,7 +82,8 @@ The music was so loud I could barely hear myself think.
             event_date=datetime(2024, 11, 13),
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -113,7 +116,8 @@ Maybe we should reconsider the timeline.
             event_date=datetime(2024, 11, 13),
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -146,7 +150,8 @@ I'm unable to attend the conference due to scheduling conflicts.
             event_date=datetime(2024, 11, 13),
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -178,7 +183,8 @@ Unlike last year, we're ahead of schedule.
             event_date=datetime(2024, 11, 13),
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -211,7 +217,8 @@ She's enthusiastic about the opportunity.
             event_date=datetime(2024, 11, 13),
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -244,7 +251,8 @@ I'm planning to switch careers because I'm not fulfilled in my current role.
             event_date=datetime(2024, 11, 13),
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -281,7 +289,8 @@ Family is the most important thing to her.
             event_date=datetime(2024, 11, 13),
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -315,7 +324,8 @@ I prefer presenting in person rather than virtually because I can read the room
             event_date=event_date,
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -372,7 +382,8 @@ I'm planning to visit Tokyo next month.
             event_date=event_date,
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -423,7 +434,8 @@ with a concert surrounded by music, joy and the warm summer breeze.
                     event_date=event_date,
                     context=context,
                     llm_config=llm_config,
-                    agent_name="Melanie"
+                    agent_name="Melanie",
+                    config=_get_raw_config(),
                 )
 
                 assert len(facts) > 0, "Should extract at least one fact"
@@ -493,7 +505,8 @@ It was a beautiful day and I plan to make this a regular habit.
             event_date=event_date,
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -547,7 +560,8 @@ It was a beautiful day and I plan to make this a regular habit.
             event_date=reference_date,
             llm_config=llm_config,
             agent_name="TestUser",
-            context="Personal diary"
+            context="Personal diary",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -577,7 +591,8 @@ It was a beautiful day and I plan to make this a regular habit.
             event_date=reference_date,
             llm_config=llm_config,
             agent_name="TestUser",
-            context="General info"
+            context="General info",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -604,7 +619,8 @@ It was a beautiful day and I plan to make this a regular habit.
             event_date=reference_date,
             llm_config=llm_config,
             agent_name="TestUser",
-            context="Calendar events"
+            context="Calendar events",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -655,7 +671,8 @@ great time! Every time I see it, I can't help but smile.
             event_date=event_date,
             context=context,
             llm_config=llm_config,
-            agent_name="Deborah"
+            agent_name="Deborah",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -705,7 +722,8 @@ I've learned so much from it.
             event_date=datetime(2024, 11, 13),
             context=context,
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -774,7 +792,8 @@ Jamie: Congratulations! I'd love to read it.
             event_date=datetime(2024, 11, 13),
             llm_config=llm_config,
             agent_name="Marcus",
-            context=context
+            context=context,
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact from the transcript"
@@ -819,7 +838,8 @@ We presented our findings to the team yesterday.
             event_date=datetime(2024, 11, 13),
             llm_config=llm_config,
             agent_name="TestUser",
-            context=context
+            context=context,
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract facts"
@@ -854,7 +874,8 @@ Jamie: [teasing] We'll see who's right, my Niners pick is solid.
             event_date=datetime(2024, 11, 14),
             context=context,
             llm_config=llm_config,
-            agent_name=agent_name
+            agent_name=agent_name,
+            config=_get_raw_config(),
         )
 
         assert len(facts) > 0, "Should extract at least one fact"
@@ -920,7 +941,8 @@ so the algorithm learns to box out. See you next week!
                     event_date=datetime(2024, 11, 13),
                     llm_config=llm_config,
                     agent_name="Marcus",
-                    context=context
+                    context=context,
+                    config=_get_raw_config(),
                 )
 
                 assert len(facts) > 0, "Should extract at least one fact"

hindsight-api/tests/test_hierarchical_config.py

@@ -0,0 +1,491 @@
+"""
+Tests for hierarchical configuration system.
+
+Tests config resolution hierarchy (global → tenant → bank),
+key normalization, API endpoints, validation, and caching.
+"""
+
+import os
+
+import pytest
+
+from hindsight_api import MemoryEngine
+from hindsight_api.config import HindsightConfig, normalize_config_dict, normalize_config_key
+from hindsight_api.config_resolver import ConfigResolver
+from hindsight_api.extensions.tenant import TenantExtension
+from hindsight_api.models import RequestContext
+
+# Enable bank config API for all tests in this module
+os.environ["HINDSIGHT_API_ENABLE_BANK_CONFIG_API"] = "true"
+
+
+class MockTenantExtension(TenantExtension):
+    """Mock tenant extension for testing tenant-level config."""
+
+    def __init__(self, tenant_config: dict):
+        self.tenant_config = tenant_config
+
+    async def authenticate(self, context):
+        from hindsight_api.extensions.tenant import TenantContext
+
+        return TenantContext(schema_name="public")
+
+    async def list_tenants(self):
+        from hindsight_api.extensions.tenant import Tenant
+
+        return [Tenant(schema="public")]
+
+    async def get_tenant_config(self, context):
+        """Return mock tenant config."""
+        return self.tenant_config
+
+
+@pytest.mark.asyncio
+async def test_config_key_normalization():
+    """Test that env var keys are normalized to Python field names."""
+    # Test basic normalization
+    assert normalize_config_key("HINDSIGHT_API_LLM_PROVIDER") == "llm_provider"
+    assert normalize_config_key("HINDSIGHT_API_LLM_MODEL") == "llm_model"
+    assert normalize_config_key("HINDSIGHT_API_RETAIN_LLM_PROVIDER") == "retain_llm_provider"
+
+    # Test already normalized keys
+    assert normalize_config_key("llm_provider") == "llm_provider"
+    assert normalize_config_key("llm_model") == "llm_model"
+
+    # Test dict normalization
+    input_dict = {
+        "HINDSIGHT_API_LLM_PROVIDER": "openai",
+        "HINDSIGHT_API_LLM_MODEL": "gpt-4",
+        "llm_base_url": "https://api.openai.com",
+    }
+    expected = {"llm_provider": "openai", "llm_model": "gpt-4", "llm_base_url": "https://api.openai.com"}
+    assert normalize_config_dict(input_dict) == expected
+
+
+@pytest.mark.asyncio
+async def test_hierarchical_fields_categorization():
+    """Test that fields are correctly categorized as configurable, credentials, or static."""
+    configurable = HindsightConfig.get_configurable_fields()
+    credentials = HindsightConfig.get_credential_fields()
+    static = HindsightConfig.get_static_fields()
+
+    # Verify no overlap between configurable and credentials
+    assert len(configurable & credentials) == 0, "Configurable fields should not include credentials"
+
+    # Verify configurable fields include behavioral settings (safe to modify)
+    assert "retain_extraction_mode" in configurable
+    assert "enable_observations" in configurable
+    assert "retain_chunk_size" in configurable
+    assert "retain_custom_instructions" in configurable
+
+    # Verify count is correct (only 4 fields)
+    assert len(configurable) == 4
+
+    # Verify credential fields (NEVER exposed)
+    assert "llm_api_key" in credentials
+    assert "llm_base_url" in credentials
+    assert "retain_llm_api_key" in credentials
+    assert "reflect_llm_api_key" in credentials
+
+    # Verify static fields include server settings AND non-configurable LLM fields
+    assert "database_url" in static
+    assert "port" in static
+    assert "host" in static
+    assert "embeddings_provider" in static
+    assert "reranker_provider" in static
+    assert "worker_enabled" in static
+    assert "llm_provider" in static  # Not configurable (needs presets)
+    assert "llm_model" in static  # Not configurable (needs presets)
+    assert "graph_retriever" in static  # Performance tuning, not configurable
+    assert "llm_max_concurrent" in static  # Performance tuning, not configurable
+
+
+@pytest.mark.asyncio
+async def test_config_hierarchy_resolution(memory, request_context):
+    """Test that config resolution follows global → tenant → bank hierarchy."""
+    bank_id = "test-hierarchy-bank"
+
+    try:
+        # Ensure bank exists in database
+        await memory.get_bank_profile(bank_id, request_context=request_context)
+
+        # Set up mock tenant extension with tenant-level config (use configurable fields only)
+        tenant_config = {"retain_chunk_size": 5000, "retain_extraction_mode": "tenant-mode"}
+        mock_tenant = MockTenantExtension(tenant_config)
+
+        # Create config resolver with mock tenant extension
+        resolver = ConfigResolver(pool=memory._pool, tenant_extension=mock_tenant)
+
+        # Test 1: Global config only (no overrides)
+        context = RequestContext(api_key=None, api_key_id=None, tenant_id=None, internal=False)
+        config = await resolver.get_bank_config(bank_id, context)
+
+        # Should have configurable fields from global config (NOT credentials or llm_provider/model)
+        assert "retain_chunk_size" in config  # Configurable field
+        assert "llm_api_key" not in config  # Credential - never exposed
+        assert "llm_provider" not in config  # Not configurable (needs presets)
+
+        # Test 2: Add tenant-level overrides
+        config = await resolver.get_bank_config(bank_id, context)
+
+        # Should apply tenant overrides (only configurable fields)
+        assert config["retain_chunk_size"] == 5000  # Tenant override
+        assert config["retain_extraction_mode"] == "tenant-mode"  # Tenant override
+
+        # Test 3: Add bank-level overrides (should take precedence)
+        await resolver.update_bank_config(
+            bank_id,
+            {"retain_chunk_size": 2000, "retain_extraction_mode": "bank-mode"},  # Override tenant settings
+            context,
+        )
+
+        # Config should reflect changes immediately (no caching)
+        config = await resolver.get_bank_config(bank_id, context)
+
+        # Bank overrides should take precedence over tenant
+        assert config["retain_chunk_size"] == 2000  # Bank override wins
+        assert config["retain_extraction_mode"] == "bank-mode"  # Bank override wins
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_config_validation_rejects_static_fields(memory, request_context):
+    """Test that attempting to override static fields raises ValueError."""
+    bank_id = "test-validation-bank"
+
+    try:
+        # Ensure bank exists in database
+        await memory.get_bank_profile(bank_id, request_context=request_context)
+
+        resolver = ConfigResolver(pool=memory._pool)
+
+        # Test 1: Configurable fields should work
+        await resolver.update_bank_config(bank_id, {"retain_chunk_size": 4000, "retain_extraction_mode": "verbose"})
+
+        # Test 2: Static fields should raise ValueError
+        with pytest.raises(ValueError, match="Cannot override static"):
+            await resolver.update_bank_config(bank_id, {"port": 9000})
+
+        with pytest.raises(ValueError, match="Cannot override static"):
+            await resolver.update_bank_config(bank_id, {"database_url": "postgresql://fake"})
+
+        with pytest.raises(ValueError, match="Cannot override static"):
+            await resolver.update_bank_config(bank_id, {"embeddings_provider": "openai"})
+
+        # Test 3: Credential fields should raise ValueError
+        with pytest.raises(ValueError, match="Cannot set credential fields"):
+            await resolver.update_bank_config(bank_id, {"llm_api_key": "sk-fake"})
+
+        # Test 4: Non-configurable LLM fields should raise ValueError (need presets)
+        with pytest.raises(ValueError, match="Cannot override static"):
+            await resolver.update_bank_config(bank_id, {"llm_model": "gpt-4"})
+
+        # Test 5: Mix of configurable and static should fail
+        with pytest.raises(ValueError, match="Cannot override static"):
+            await resolver.update_bank_config(bank_id, {"retain_chunk_size": 4000, "port": 9000})
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_config_freshness_across_updates(memory, request_context):
+    """Test that config changes are immediately visible (no stale cache)."""
+    bank1 = "freshness-test-1"
+
+    try:
+        # Ensure bank exists in database
+        await memory.get_bank_profile(bank1, request_context=request_context)
+
+        resolver = ConfigResolver(pool=memory._pool)
+
+        # Test 1: Initial config reflects global defaults
+        config1 = await resolver.get_bank_config(bank1, None)
+        initial_chunk_size = config1["retain_chunk_size"]
+
+        # Test 2: Update config
+        await resolver.update_bank_config(bank1, {"retain_chunk_size": 4000})
+
+        # Test 3: Next call should see updated value immediately (no stale cache)
+        config2 = await resolver.get_bank_config(bank1, None)
+        assert config2["retain_chunk_size"] == 4000
+
+        # Test 4: Multiple updates are all immediately visible
+        await resolver.update_bank_config(bank1, {"retain_chunk_size": 4500})
+        config3 = await resolver.get_bank_config(bank1, None)
+        assert config3["retain_chunk_size"] == 4500
+
+        # Test 5: Reset restores global defaults immediately
+        await resolver.reset_bank_config(bank1)
+        config4 = await resolver.get_bank_config(bank1, None)
+        assert config4["retain_chunk_size"] == initial_chunk_size  # Back to global default
+
+        # Test 6: Each call returns a fresh config dict (not a cached reference)
+        config5 = await resolver.get_bank_config(bank1, None)
+        config6 = await resolver.get_bank_config(bank1, None)
+        assert config5 is not config6  # Different object instances
+
+    finally:
+        await memory.delete_bank(bank1, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_config_reset_to_defaults(memory, request_context):
+    """Test that resetting config removes all bank-specific overrides."""
+    bank_id = "test-reset-bank"
+
+    try:
+        # Ensure bank exists in database
+        await memory.get_bank_profile(bank_id, request_context=request_context)
+
+        resolver = ConfigResolver(pool=memory._pool)
+
+        # Add bank-specific overrides
+        await resolver.update_bank_config(
+            bank_id,
+            {
+                "retain_chunk_size": 5500,
+                "retain_extraction_mode": "custom",
+                "retain_custom_instructions": "Custom instructions",
+            },
+        )
+
+        # Verify overrides applied
+        config = await resolver.get_bank_config(bank_id, None)
+        assert config["retain_chunk_size"] == 5500
+        assert config["retain_extraction_mode"] == "custom"
+        assert config["retain_custom_instructions"] == "Custom instructions"
+
+        # Reset to defaults
+        await resolver.reset_bank_config(bank_id)
+
+        # Verify overrides removed (back to global defaults)
+        config_reset = await resolver.get_bank_config(bank_id, None)
+        assert config_reset["retain_chunk_size"] != 5500  # Should be global default
+        assert config_reset["retain_extraction_mode"] != "custom"  # Should be global default
+
+        # Verify bank_config is empty
+        bank_overrides = await resolver._load_bank_config(bank_id)
+        assert bank_overrides == {}
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_config_supports_both_key_formats(memory, request_context):
+    """Test that API accepts both env var and Python field formats."""
+    bank_id = "test-key-format-bank"
+
+    try:
+        # Ensure bank exists in database
+        await memory.get_bank_profile(bank_id, request_context=request_context)
+
+        resolver = ConfigResolver(pool=memory._pool)
+
+        # Test 1: Python field format
+        await resolver.update_bank_config(bank_id, {"retain_chunk_size": 7000})
+
+        config = await resolver.get_bank_config(bank_id, None)
+        assert config["retain_chunk_size"] == 7000
+
+        # Test 2: Env var format (should be normalized)
+        await resolver.update_bank_config(bank_id, {"HINDSIGHT_API_RETAIN_CHUNK_SIZE": 8000})
+
+        config = await resolver.get_bank_config(bank_id, None)
+        assert config["retain_chunk_size"] == 8000
+
+        # Test 3: Mixed format in same request
+        await resolver.update_bank_config(
+            bank_id,
+            {
+                "retain_chunk_size": 9000,  # Python format
+                "HINDSIGHT_API_RETAIN_EXTRACTION_MODE": "verbose",  # Env format
+            },
+        )
+
+        config = await resolver.get_bank_config(bank_id, None)
+        assert config["retain_chunk_size"] == 9000
+        assert config["retain_extraction_mode"] == "verbose"
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_config_only_configurable_fields_stored(memory, request_context):
+    """Test that only configurable fields are stored in bank config."""
+    bank_id = "test-filter-bank"
+
+    try:
+        # Ensure bank exists in database
+        await memory.get_bank_profile(bank_id, request_context=request_context)
+
+        resolver = ConfigResolver(pool=memory._pool)
+
+        # Add valid configurable field
+        await resolver.update_bank_config(bank_id, {"retain_chunk_size": 3500})
+
+        # Load bank config and verify only configurable fields present
+        bank_overrides = await resolver._load_bank_config(bank_id)
+
+        for key in bank_overrides.keys():
+            assert key in HindsightConfig.get_configurable_fields(), f"Non-configurable field {key} in bank config"
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_config_get_bank_config_no_static_or_credential_fields_leak(memory, request_context):
+    """
+    SECURITY TEST: Verify get_bank_config() only returns configurable fields (no static/credentials).
+
+    This prevents leaking sensitive system configuration like database URLs,
+    API keys, LLM providers/models, worker counts, etc. when retrieving bank configuration.
+    """
+    bank_id = "test-security-bank"
+
+    try:
+        # Ensure bank exists in database
+        await memory.get_bank_profile(bank_id, request_context=request_context)
+
+        resolver = ConfigResolver(pool=memory._pool)
+
+        # Get bank config
+        config = await resolver.get_bank_config(bank_id, None)
+
+        # Get field categorizations
+        configurable_fields = HindsightConfig.get_configurable_fields()
+        credential_fields = HindsightConfig.get_credential_fields()
+        static_fields = HindsightConfig.get_static_fields()
+
+        # SECURITY: Verify ONLY configurable fields are returned (NO static, NO credentials)
+        for key in config.keys():
+            assert key in configurable_fields, (
+                f"SECURITY VIOLATION: Non-configurable field '{key}' returned by get_bank_config(). "
+                f"Only configurable fields should be returned to prevent leaking system config."
+            )
+            assert key not in credential_fields, (
+                f"SECURITY VIOLATION: Credential field '{key}' returned by get_bank_config(). "
+                f"Credentials must NEVER be exposed via API."
+            )
+
+        # SECURITY: Verify specific sensitive fields are NOT present
+        sensitive_fields = [
+            "database_url", "api_port", "host", "worker_count",  # Infrastructure
+            "llm_api_key", "llm_base_url",  # Credentials
+            "retain_llm_api_key", "reflect_llm_api_key",  # More credentials
+            "llm_provider", "llm_model",  # Not configurable (need presets)
+        ]
+        for field in sensitive_fields:
+            assert field not in config, (
+                f"SECURITY VIOLATION: Sensitive field '{field}' returned by get_bank_config(). "
+                f"Must not be exposed via bank config API."
+            )
+
+        # Verify we have the expected configurable fields (small set)
+        expected_configurable = ["retain_chunk_size", "retain_extraction_mode", "enable_observations"]
+        for field in expected_configurable:
+            assert field in config, f"Expected configurable field '{field}' missing from config"
+
+        # Should have a small number of configurable fields (not hundreds)
+        assert len(config) < 20, f"Too many fields returned: {len(config)}"
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_config_permissions_system(memory, request_context):
+    """
+    Test that tenant extension can control which fields banks are allowed to modify.
+
+    Tests get_allowed_config_fields() permission system.
+    """
+    bank_id = "test-permissions-bank"
+
+    class PermissionTenantExtension(TenantExtension):
+        """Mock tenant extension with configurable permissions."""
+
+        def __init__(self, allowed_fields: set[str] | None):
+            self.allowed_fields = allowed_fields
+
+        async def authenticate(self, context):
+            from hindsight_api.extensions.tenant import TenantContext
+
+            return TenantContext(schema_name="public")
+
+        async def list_tenants(self):
+            from hindsight_api.extensions.tenant import Tenant
+
+            return [Tenant(schema="public")]
+
+        async def get_allowed_config_fields(self, context, bank_id):
+            """Return configured allowed fields."""
+            return self.allowed_fields
+
+    try:
+        # Ensure bank exists in database
+        await memory.get_bank_profile(bank_id, request_context=request_context)
+
+        # Test 1: None = allow all configurable fields
+        extension = PermissionTenantExtension(allowed_fields=None)
+        resolver = ConfigResolver(pool=memory._pool, tenant_extension=extension)
+
+        await resolver.update_bank_config(
+            bank_id, {"retain_chunk_size": 4000, "retain_extraction_mode": "verbose"}, request_context
+        )
+        config = await resolver.get_bank_config(bank_id, request_context)
+        assert config["retain_chunk_size"] == 4000
+        assert config["retain_extraction_mode"] == "verbose"
+
+        # Reset for next test
+        await resolver.reset_bank_config(bank_id)
+
+        # Test 2: Specific set = only those fields allowed
+        extension = PermissionTenantExtension(allowed_fields={"retain_chunk_size"})
+        resolver = ConfigResolver(pool=memory._pool, tenant_extension=extension)
+
+        # Should allow retain_chunk_size
+        await resolver.update_bank_config(bank_id, {"retain_chunk_size": 5000}, request_context)
+        config = await resolver.get_bank_config(bank_id, request_context)
+        assert config["retain_chunk_size"] == 5000
+
+        # Should reject retain_extraction_mode (not in allowed list)
+        with pytest.raises(ValueError, match="Not allowed to modify fields"):
+            await resolver.update_bank_config(bank_id, {"retain_extraction_mode": "verbose"}, request_context)
+
+        # Should reject mix of allowed and disallowed
+        with pytest.raises(ValueError, match="Not allowed to modify fields"):
+            await resolver.update_bank_config(
+                bank_id, {"retain_chunk_size": 6000, "retain_extraction_mode": "verbose"}, request_context
+            )
+
+        # Reset for next test
+        await resolver.reset_bank_config(bank_id)
+
+        # Test 3: Empty set = no modifications allowed (read-only)
+        extension = PermissionTenantExtension(allowed_fields=set())
+        resolver = ConfigResolver(pool=memory._pool, tenant_extension=extension)
+
+        with pytest.raises(ValueError, match="Not allowed to modify fields"):
+            await resolver.update_bank_config(bank_id, {"retain_chunk_size": 7000}, request_context)
+
+        # Test 4: get_bank_config should filter response based on permissions
+        extension = PermissionTenantExtension(allowed_fields={"retain_chunk_size", "enable_observations"})
+        resolver = ConfigResolver(pool=memory._pool, tenant_extension=extension)
+
+        config = await resolver.get_bank_config(bank_id, request_context)
+
+        # Should only return allowed fields
+        assert "retain_chunk_size" in config
+        assert "enable_observations" in config
+        # Other configurable fields should be filtered out
+        assert "retain_extraction_mode" not in config
+        assert "retain_custom_instructions" not in config
+
+    finally:
+        await memory.delete_bank(bank_id, request_context=request_context)

hindsight-api/tests/test_link_expansion_retrieval.py

@@ -12,9 +12,9 @@ import pytest
 @pytest.fixture(autouse=True)
 def enable_observations():
     """Enable observations for all tests in this module."""
-    from hindsight_api.config import get_config
+    from hindsight_api.config import _get_raw_config
 
-    config = get_config()
+    config = _get_raw_config()
     original_value = config.enable_observations
     config.enable_observations = True
     yield

hindsight-api/tests/test_litellm_sdk_cross_encoder.py

@@ -0,0 +1,392 @@
+"""
+Tests for LiteLLMSDKCrossEncoder.
+
+Tests the LiteLLM SDK-based cross-encoder implementation for reranking.
+"""
+
+import os
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from hindsight_api.engine.cross_encoder import LiteLLMSDKCrossEncoder, create_cross_encoder_from_env
+
+
+class TestLiteLLMSDKCrossEncoder:
+    """Test suite for LiteLLMSDKCrossEncoder class."""
+
+    @pytest.mark.asyncio
+    async def test_initialization_success(self):
+        """Test successful initialization with valid config."""
+        encoder = LiteLLMSDKCrossEncoder(
+            api_key="test_key",
+            model="deepinfra/Qwen3-reranker-8B",
+        )
+
+        assert encoder.provider_name == "litellm-sdk"
+        assert encoder.api_key == "test_key"
+        assert encoder.model == "deepinfra/Qwen3-reranker-8B"
+        assert encoder._initialized is False
+
+        # Mock the litellm import
+        mock_litellm = MagicMock()
+        with patch.dict("sys.modules", {"litellm": mock_litellm}):
+            await encoder.initialize()
+            assert encoder._initialized is True
+
+    @pytest.mark.asyncio
+    async def test_initialization_missing_package(self):
+        """Test initialization fails when litellm package is missing."""
+        encoder = LiteLLMSDKCrossEncoder(
+            api_key="test_key",
+            model="cohere/rerank-english-v3.0",
+        )
+
+        with patch.dict("sys.modules", {"litellm": None}):
+            with pytest.raises(ImportError, match="litellm is required"):
+                await encoder.initialize()
+
+    @pytest.mark.asyncio
+    async def test_initialization_idempotent(self):
+        """Test that calling initialize() multiple times is safe."""
+        encoder = LiteLLMSDKCrossEncoder(
+            api_key="test_key",
+            model="cohere/rerank-english-v3.0",
+        )
+
+        mock_litellm = MagicMock()
+        with patch.dict("sys.modules", {"litellm": mock_litellm}):
+            await encoder.initialize()
+            assert encoder._initialized is True
+
+            # Second call should be no-op
+            await encoder.initialize()
+            assert encoder._initialized is True
+
+    @pytest.mark.asyncio
+    async def test_predict_single_query(self):
+        """Test prediction with a single query and multiple documents."""
+        encoder = LiteLLMSDKCrossEncoder(
+            api_key="test_key",
+            model="deepinfra/Qwen3-reranker-8B",
+        )
+
+        # Create mock response with results as TypedDicts
+        mock_response = MagicMock()
+        mock_response.results = [
+            {"index": 0, "relevance_score": 0.9},
+            {"index": 1, "relevance_score": 0.7},
+            {"index": 2, "relevance_score": 0.5},
+        ]
+
+        mock_litellm = MagicMock()
+        mock_litellm.arerank = AsyncMock(return_value=mock_response)
+
+        with patch.dict("sys.modules", {"litellm": mock_litellm}):
+            await encoder.initialize()
+
+            pairs = [
+                ("What is Python?", "Python is a programming language"),
+                ("What is Python?", "Python is a snake"),
+                ("What is Python?", "Python is a British comedy group"),
+            ]
+
+            scores = await encoder.predict(pairs)
+
+            assert len(scores) == 3
+            assert scores == [0.9, 0.7, 0.5]
+
+            # Verify arerank was called correctly
+            mock_litellm.arerank.assert_called_once()
+            call_args = mock_litellm.arerank.call_args
+            assert call_args.kwargs["model"] == "deepinfra/Qwen3-reranker-8B"
+            assert call_args.kwargs["query"] == "What is Python?"
+            assert len(call_args.kwargs["documents"]) == 3
+            assert call_args.kwargs["api_key"] == "test_key"
+
+    @pytest.mark.asyncio
+    async def test_predict_multiple_queries(self):
+        """Test prediction with multiple different queries (grouped efficiently)."""
+        encoder = LiteLLMSDKCrossEncoder(
+            api_key="test_key",
+            model="cohere/rerank-english-v3.0",
+        )
+
+        # First query response
+        mock_response1 = MagicMock()
+        mock_response1.results = [
+            {"index": 0, "relevance_score": 0.9},
+            {"index": 1, "relevance_score": 0.7},
+        ]
+
+        # Second query response
+        mock_response2 = MagicMock()
+        mock_response2.results = [
+            {"index": 0, "relevance_score": 0.8},
+        ]
+
+        mock_litellm = MagicMock()
+        mock_litellm.arerank = AsyncMock(side_effect=[mock_response1, mock_response2])
+
+        with patch.dict("sys.modules", {"litellm": mock_litellm}):
+            await encoder.initialize()
+
+            pairs = [
+                ("What is Python?", "Python is a programming language"),
+                ("What is Python?", "Python is a snake"),
+                ("What is Java?", "Java is a programming language"),
+            ]
+
+            scores = await encoder.predict(pairs)
+
+            assert len(scores) == 3
+            assert scores[0] == 0.9  # First query, first doc
+            assert scores[1] == 0.7  # First query, second doc
+            assert scores[2] == 0.8  # Second query, first doc
+
+            # Verify arerank was called twice (once per unique query)
+            assert mock_litellm.arerank.call_count == 2
+
+    @pytest.mark.asyncio
+    async def test_predict_empty_pairs(self):
+        """Test prediction with empty input."""
+        encoder = LiteLLMSDKCrossEncoder(
+            api_key="test_key",
+            model="cohere/rerank-english-v3.0",
+        )
+
+        mock_litellm = MagicMock()
+        with patch.dict("sys.modules", {"litellm": mock_litellm}):
+            await encoder.initialize()
+            scores = await encoder.predict([])
+            assert scores == []
+
+    @pytest.mark.asyncio
+    async def test_predict_not_initialized(self):
+        """Test that predict fails if encoder not initialized."""
+        encoder = LiteLLMSDKCrossEncoder(
+            api_key="test_key",
+            model="cohere/rerank-english-v3.0",
+        )
+
+        pairs = [("query", "document")]
+
+        with pytest.raises(RuntimeError, match="not initialized"):
+            await encoder.predict(pairs)
+
+    @pytest.mark.asyncio
+    async def test_predict_error_handling(self):
+        """Test that errors during prediction are raised."""
+        encoder = LiteLLMSDKCrossEncoder(
+            api_key="test_key",
+            model="cohere/rerank-english-v3.0",
+        )
+
+        # Mock litellm to raise an error
+        mock_litellm = MagicMock()
+        mock_litellm.arerank = AsyncMock(side_effect=Exception("API Error"))
+
+        with patch.dict("sys.modules", {"litellm": mock_litellm}):
+            await encoder.initialize()
+
+            pairs = [
+                ("What is Python?", "Python is a programming language"),
+            ]
+
+            # Should raise the exception
+            with pytest.raises(Exception, match="API Error"):
+                await encoder.predict(pairs)
+
+    @pytest.mark.asyncio
+    async def test_custom_api_base(self):
+        """Test that custom API base URL is passed to rerank calls."""
+        encoder = LiteLLMSDKCrossEncoder(
+            api_key="test_key",
+            model="cohere/rerank-english-v3.0",
+            api_base="https://custom.api.example.com",
+        )
+
+        mock_response = MagicMock()
+        mock_response.results = [
+            {"index": 0, "relevance_score": 0.9},
+        ]
+
+        mock_litellm = MagicMock()
+        mock_litellm.arerank = AsyncMock(return_value=mock_response)
+
+        with patch.dict("sys.modules", {"litellm": mock_litellm}):
+            await encoder.initialize()
+
+            # Test that api_base is passed to arerank
+            pairs = [("query", "document")]
+            scores = await encoder.predict(pairs)
+
+            assert scores == [0.9]
+            mock_litellm.arerank.assert_called_once()
+            call_args = mock_litellm.arerank.call_args
+            assert call_args.kwargs["api_base"] == "https://custom.api.example.com"
+
+    @pytest.mark.asyncio
+    async def test_response_with_direct_score_list(self):
+        """Test handling of response format with direct score list."""
+        encoder = LiteLLMSDKCrossEncoder(
+            api_key="test_key",
+            model="some-provider/model",
+        )
+
+        # Mock litellm to return direct list of scores
+        mock_litellm = MagicMock()
+        mock_litellm.arerank = AsyncMock(return_value=[0.9, 0.7, 0.5])
+
+        with patch.dict("sys.modules", {"litellm": mock_litellm}):
+            await encoder.initialize()
+
+            pairs = [
+                ("query", "doc1"),
+                ("query", "doc2"),
+                ("query", "doc3"),
+            ]
+
+            scores = await encoder.predict(pairs)
+
+            assert scores == [0.9, 0.7, 0.5]
+
+
+class TestFactoryFunction:
+    """Test suite for create_cross_encoder_from_env factory function."""
+
+    @pytest.mark.asyncio
+    async def test_create_litellm_sdk_from_env(self):
+        """Test creating LiteLLM SDK cross-encoder from environment variables."""
+        env_vars = {
+            "HINDSIGHT_API_RERANKER_PROVIDER": "litellm-sdk",
+            "HINDSIGHT_API_RERANKER_LITELLM_SDK_API_KEY": "test_key",
+            "HINDSIGHT_API_RERANKER_LITELLM_SDK_MODEL": "deepinfra/Qwen3-reranker-8B",
+        }
+
+        with patch.dict(os.environ, env_vars, clear=False):
+            # Need to reload config to pick up env vars
+            from hindsight_api.config import HindsightConfig
+
+            config = HindsightConfig.from_env()
+
+            with patch("hindsight_api.config.get_config", return_value=config):
+                encoder = create_cross_encoder_from_env()
+
+                assert isinstance(encoder, LiteLLMSDKCrossEncoder)
+                assert encoder.api_key == "test_key"
+                assert encoder.model == "deepinfra/Qwen3-reranker-8B"
+
+    @pytest.mark.asyncio
+    async def test_create_litellm_sdk_missing_api_key(self):
+        """Test that factory raises error when API key is missing."""
+        env_vars = {
+            "HINDSIGHT_API_RERANKER_PROVIDER": "litellm-sdk",
+            "HINDSIGHT_API_RERANKER_LITELLM_SDK_MODEL": "deepinfra/Qwen3-reranker-8B",
+        }
+
+        with patch.dict(os.environ, env_vars, clear=False):
+            # Remove API key if set
+            if "HINDSIGHT_API_RERANKER_LITELLM_SDK_API_KEY" in os.environ:
+                del os.environ["HINDSIGHT_API_RERANKER_LITELLM_SDK_API_KEY"]
+
+            from hindsight_api.config import HindsightConfig
+
+            config = HindsightConfig.from_env()
+
+            with patch("hindsight_api.config.get_config", return_value=config):
+                with pytest.raises(ValueError, match="HINDSIGHT_API_RERANKER_LITELLM_SDK_API_KEY is required"):
+                    create_cross_encoder_from_env()
+
+    @pytest.mark.asyncio
+    async def test_create_litellm_sdk_with_custom_api_base(self):
+        """Test creating LiteLLM SDK cross-encoder with custom API base."""
+        env_vars = {
+            "HINDSIGHT_API_RERANKER_PROVIDER": "litellm-sdk",
+            "HINDSIGHT_API_RERANKER_LITELLM_SDK_API_KEY": "test_key",
+            "HINDSIGHT_API_RERANKER_LITELLM_SDK_MODEL": "cohere/rerank-english-v3.0",
+            "HINDSIGHT_API_RERANKER_LITELLM_SDK_API_BASE": "https://custom.api.example.com",
+        }
+
+        with patch.dict(os.environ, env_vars, clear=False):
+            from hindsight_api.config import HindsightConfig
+
+            config = HindsightConfig.from_env()
+
+            with patch("hindsight_api.config.get_config", return_value=config):
+                encoder = create_cross_encoder_from_env()
+
+                assert isinstance(encoder, LiteLLMSDKCrossEncoder)
+                assert encoder.api_base == "https://custom.api.example.com"
+
+
+class TestLiteLLMSDKCohereCrossEncoder:
+    """Tests for LiteLLM SDK calling Cohere (runs in CI with COHERE_API_KEY)."""
+
+    @pytest.fixture
+    async def litellm_cohere_cross_encoder(self):
+        """Create LiteLLM SDK cross-encoder instance for Cohere."""
+        if not os.environ.get("COHERE_API_KEY"):
+            pytest.skip("Cohere API key not available (set COHERE_API_KEY)")
+
+        encoder = LiteLLMSDKCrossEncoder(
+            api_key=os.environ["COHERE_API_KEY"],
+            model="cohere/rerank-english-v3.0",
+        )
+        await encoder.initialize()
+        return encoder
+
+    @pytest.mark.asyncio
+    async def test_litellm_sdk_cohere_initialization(self, litellm_cohere_cross_encoder):
+        """Test that LiteLLM SDK Cohere cross-encoder initializes correctly."""
+        assert litellm_cohere_cross_encoder.provider_name == "litellm-sdk"
+        assert litellm_cohere_cross_encoder.model == "cohere/rerank-english-v3.0"
+
+    @pytest.mark.asyncio
+    async def test_litellm_sdk_cohere_predict(self, litellm_cohere_cross_encoder):
+        """Test that LiteLLM SDK can call Cohere rerank API."""
+        pairs = [
+            ("What is the capital of France?", "Paris is the capital of France."),
+            ("What is the capital of France?", "The Eiffel Tower is in Paris."),
+            ("What is the capital of France?", "Python is a programming language."),
+        ]
+        scores = await litellm_cohere_cross_encoder.predict(pairs)
+
+        assert len(scores) == 3
+        assert all(isinstance(s, float) for s in scores)
+        # The first result should be most relevant
+        assert scores[0] > scores[2], "Direct answer should score higher than unrelated text"
+        # All scores should be in valid range
+        assert all(0.0 <= score <= 1.0 for score in scores)
+
+
+class TestIntegration:
+    """Integration tests with real API (optional - requires API keys)."""
+
+    @pytest.mark.skipif(
+        not os.environ.get("DEEPINFRA_API_KEY"),
+        reason="DEEPINFRA_API_KEY not set - skipping integration test",
+    )
+    @pytest.mark.asyncio
+    async def test_real_deepinfra_api(self):
+        """Test with real DeepInfra API (requires DEEPINFRA_API_KEY env var)."""
+        encoder = LiteLLMSDKCrossEncoder(
+            api_key=os.environ["DEEPINFRA_API_KEY"],
+            model="deepinfra/Qwen3-reranker-8B",
+        )
+
+        await encoder.initialize()
+
+        pairs = [
+            ("What is Python?", "Python is a high-level programming language"),
+            ("What is Python?", "Python is a species of snake"),
+            ("What is Python?", "Python is unrelated text about cars"),
+        ]
+
+        scores = await encoder.predict(pairs)
+
+        # First doc should have highest score (most relevant)
+        assert len(scores) == 3
+        assert scores[0] > scores[1]
+        assert scores[1] > scores[2]
+        assert all(0.0 <= score <= 1.0 for score in scores)

hindsight-api/tests/test_litellm_sdk_embeddings.py

@@ -0,0 +1,387 @@
+"""
+Tests for LiteLLM SDK embeddings implementation.
+
+These tests cover:
+1. Initialization (success, missing package, missing API key, idempotent)
+2. Encode (single text, multiple texts, batching, error handling)
+3. Provider-specific configuration (Cohere, OpenAI, etc.)
+4. Factory function (create from env, validation errors)
+5. Dimension detection
+"""
+
+import os
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from hindsight_api.config import (
+    ENV_EMBEDDINGS_LITELLM_SDK_API_KEY,
+    ENV_EMBEDDINGS_LITELLM_SDK_MODEL,
+    ENV_EMBEDDINGS_PROVIDER,
+    HindsightConfig,
+)
+from hindsight_api.engine.embeddings import LiteLLMSDKEmbeddings, create_embeddings_from_env
+
+
+class TestLiteLLMSDKEmbeddings:
+    """Unit tests for LiteLLMSDKEmbeddings with mocked litellm responses."""
+
+    @pytest.fixture
+    def mock_litellm(self):
+        """Mock litellm module."""
+        mock = MagicMock()
+
+        # Mock aembedding (async) for initialization
+        mock_response = MagicMock()
+        mock_response.data = [{"embedding": [0.1] * 768, "index": 0}]
+        mock.aembedding = AsyncMock(return_value=mock_response)
+
+        # Mock embedding (sync) for encode
+        mock_sync_response = MagicMock()
+        mock_sync_response.data = [
+            {"embedding": [0.1] * 768, "index": 0},
+            {"embedding": [0.2] * 768, "index": 1},
+        ]
+        mock.embedding = MagicMock(return_value=mock_sync_response)
+
+        return mock
+
+    @pytest.fixture
+    async def embeddings(self, mock_litellm):
+        """Create initialized LiteLLMSDKEmbeddings instance."""
+        emb = LiteLLMSDKEmbeddings(
+            api_key="test_key",
+            model="cohere/embed-english-v3.0",
+            api_base=None,
+            batch_size=100,
+            timeout=60.0,
+        )
+        # Manually set the mock (simulating successful initialization)
+        emb._litellm = mock_litellm
+        emb._dimension = 768
+        return emb
+
+    async def test_initialization_success(self, mock_litellm):
+        """Test successful initialization."""
+        with patch("builtins.__import__", side_effect=lambda name, *args: mock_litellm if name == "litellm" else __import__(name, *args)):
+            emb = LiteLLMSDKEmbeddings(
+                api_key="test_key",
+                model="cohere/embed-english-v3.0",
+                api_base=None,
+                batch_size=100,
+                timeout=60.0,
+            )
+
+            assert emb._litellm is None
+            assert emb._dimension is None
+
+            await emb.initialize()
+
+            assert emb._litellm is not None
+            assert emb._dimension == 768
+
+            # Verify test embedding was called
+            mock_litellm.aembedding.assert_called_once_with(
+                model="cohere/embed-english-v3.0",
+                input=["test"],
+                api_key="test_key",
+            )
+
+    async def test_initialization_missing_package(self):
+        """Test initialization fails gracefully when litellm is not installed."""
+        def mock_import(name, *args):
+            if name == "litellm":
+                raise ImportError("No module named 'litellm'")
+            return __import__(name, *args)
+
+        with patch("builtins.__import__", side_effect=mock_import):
+            emb = LiteLLMSDKEmbeddings(
+                api_key="test_key",
+                model="cohere/embed-english-v3.0",
+                api_base=None,
+                batch_size=100,
+                timeout=60.0,
+            )
+
+            with pytest.raises(ImportError, match="litellm is required"):
+                await emb.initialize()
+
+    async def test_initialization_idempotent(self, embeddings, mock_litellm):
+        """Test that calling initialize() multiple times is safe."""
+        # embeddings._litellm is already set in fixture
+        assert embeddings._litellm is not None
+
+        # Call again
+        await embeddings.initialize()
+
+        # Should still have same litellm instance
+        assert embeddings._litellm is not None
+
+    async def test_encode_single_text(self, embeddings, mock_litellm):
+        """Test encoding a single text."""
+        # Set up mock response
+        mock_litellm.embedding.return_value.data = [
+            {"embedding": [0.5] * 768, "index": 0},
+        ]
+
+        result = embeddings.encode(["Hello world"])
+
+        assert isinstance(result, list)
+        assert len(result) == 1
+        assert len(result[0]) == 768
+        assert all(isinstance(x, float) for x in result[0])
+        assert all(abs(x - 0.5) < 0.001 for x in result[0])
+
+        # Verify call
+        mock_litellm.embedding.assert_called_once_with(
+            model="cohere/embed-english-v3.0",
+            input=["Hello world"],
+            api_key="test_key",
+        )
+
+    async def test_encode_multiple_texts(self, embeddings, mock_litellm):
+        """Test encoding multiple texts."""
+        # Set up mock response
+        mock_litellm.embedding.return_value.data = [
+            {"embedding": [0.1] * 768, "index": 0},
+            {"embedding": [0.2] * 768, "index": 1},
+            {"embedding": [0.3] * 768, "index": 2},
+        ]
+
+        texts = ["First text", "Second text", "Third text"]
+        result = embeddings.encode(texts)
+
+        assert isinstance(result, list)
+        assert len(result) == 3
+        assert len(result[0]) == 768
+        assert len(result[1]) == 768
+        assert len(result[2]) == 768
+        assert all(abs(x - 0.1) < 0.001 for x in result[0])
+        assert all(abs(x - 0.2) < 0.001 for x in result[1])
+        assert all(abs(x - 0.3) < 0.001 for x in result[2])
+
+    async def test_encode_batching(self, embeddings, mock_litellm):
+        """Test that large inputs are batched correctly."""
+        # Create embeddings with small batch size
+        emb = LiteLLMSDKEmbeddings(
+            api_key="test_key",
+            model="cohere/embed-english-v3.0",
+            api_base=None,
+            batch_size=2,  # Small batch for testing
+            timeout=60.0,
+        )
+        emb._litellm = mock_litellm
+        emb._initialized = True
+        emb._dimension = 768
+
+        # Mock responses for each batch
+        def mock_embedding_side_effect(model, input, **kwargs):
+            mock_response = MagicMock()
+            mock_response.data = [
+                {"embedding": [float(i)] * 768, "index": i} for i in range(len(input))
+            ]
+            return mock_response
+
+        mock_litellm.embedding.side_effect = mock_embedding_side_effect
+
+        # Encode 5 texts (should create 3 batches: 2, 2, 1)
+        texts = [f"Text {i}" for i in range(5)]
+        result = emb.encode(texts)
+
+        assert isinstance(result, list)
+        assert len(result) == 5
+        assert all(len(embedding) == 768 for embedding in result)
+
+        # Verify batching: should be called 3 times
+        assert mock_litellm.embedding.call_count == 3
+
+        # Verify batch sizes
+        calls = mock_litellm.embedding.call_args_list
+        assert len(calls[0][1]["input"]) == 2  # First batch
+        assert len(calls[1][1]["input"]) == 2  # Second batch
+        assert len(calls[2][1]["input"]) == 1  # Third batch
+
+    async def test_encode_empty_list(self, embeddings):
+        """Test encoding empty list returns empty list."""
+        result = embeddings.encode([])
+
+        assert isinstance(result, list)
+        assert len(result) == 0
+
+    async def test_encode_before_initialization(self, mock_litellm):
+        """Test that encode raises error if not initialized."""
+        emb = LiteLLMSDKEmbeddings(
+            api_key="test_key",
+            model="cohere/embed-english-v3.0",
+            api_base=None,
+            batch_size=100,
+            timeout=60.0,
+        )
+
+        with pytest.raises(RuntimeError, match="not initialized"):
+            emb.encode(["test"])
+
+    async def test_encode_error_handling(self, embeddings, mock_litellm):
+        """Test error handling during encoding."""
+        # Make embedding raise an error
+        mock_litellm.embedding.side_effect = Exception("API Error")
+
+        with pytest.raises(Exception, match="API Error"):
+            embeddings.encode(["test"])
+
+    async def test_dimension_property(self, embeddings):
+        """Test dimension property."""
+        assert embeddings.dimension == 768
+
+    async def test_dimension_before_initialization(self, mock_litellm):
+        """Test dimension raises error if not initialized."""
+        emb = LiteLLMSDKEmbeddings(
+            api_key="test_key",
+            model="cohere/embed-english-v3.0",
+            api_base=None,
+            batch_size=100,
+            timeout=60.0,
+        )
+
+        with pytest.raises(RuntimeError, match="not initialized"):
+            _ = emb.dimension
+
+    async def test_custom_api_base(self, mock_litellm):
+        """Test custom API base URL is passed to embedding calls."""
+        with patch("builtins.__import__", side_effect=lambda name, *args: mock_litellm if name == "litellm" else __import__(name, *args)):
+            emb = LiteLLMSDKEmbeddings(
+                api_key="test_key",
+                model="cohere/embed-english-v3.0",
+                api_base="https://custom.api.com",
+                batch_size=100,
+                timeout=60.0,
+            )
+
+            await emb.initialize()
+
+            # Verify api_base is set
+            assert emb.api_base == "https://custom.api.com"
+
+            # Verify api_base is passed to aembedding
+            mock_litellm.aembedding.assert_called_once()
+            call_args = mock_litellm.aembedding.call_args
+            assert call_args.kwargs["api_base"] == "https://custom.api.com"
+
+            # Test encode also passes api_base
+            mock_litellm.embedding.return_value.data = [{"embedding": [0.1] * 768, "index": 0}]
+            emb.encode(["test"])
+
+            mock_litellm.embedding.assert_called_once()
+            call_args = mock_litellm.embedding.call_args
+            assert call_args.kwargs["api_base"] == "https://custom.api.com"
+
+
+class TestLiteLLMSDKEmbeddingsFactory:
+    """Test the factory function for creating LiteLLM SDK embeddings."""
+
+    def test_create_from_env_success(self, monkeypatch):
+        """Test creating embeddings from environment variables."""
+        # Mock get_config() to return configured HindsightConfig
+        mock_config = MagicMock()
+        mock_config.embeddings_provider = "litellm-sdk"
+        mock_config.embeddings_litellm_sdk_api_key = "test_key"
+        mock_config.embeddings_litellm_sdk_model = "cohere/embed-english-v3.0"
+        mock_config.embeddings_litellm_sdk_api_base = None
+
+        with patch("hindsight_api.config.get_config", return_value=mock_config):
+            embeddings = create_embeddings_from_env()
+
+            assert isinstance(embeddings, LiteLLMSDKEmbeddings)
+            assert embeddings.api_key == "test_key"
+            assert embeddings.model == "cohere/embed-english-v3.0"
+
+    def test_create_from_env_missing_api_key(self, monkeypatch):
+        """Test that missing API key raises error."""
+        # Mock get_config() with missing API key
+        mock_config = MagicMock()
+        mock_config.embeddings_provider = "litellm-sdk"
+        mock_config.embeddings_litellm_sdk_api_key = None  # Missing key
+        mock_config.embeddings_litellm_sdk_model = "cohere/embed-english-v3.0"
+
+        with patch("hindsight_api.config.get_config", return_value=mock_config):
+            with pytest.raises(ValueError, match=ENV_EMBEDDINGS_LITELLM_SDK_API_KEY):
+                create_embeddings_from_env()
+
+    def test_create_from_env_with_api_base(self, monkeypatch):
+        """Test creating embeddings with custom API base."""
+        # Mock get_config() with custom API base
+        mock_config = MagicMock()
+        mock_config.embeddings_provider = "litellm-sdk"
+        mock_config.embeddings_litellm_sdk_api_key = "test_key"
+        mock_config.embeddings_litellm_sdk_model = "cohere/embed-english-v3.0"
+        mock_config.embeddings_litellm_sdk_api_base = "https://custom.api.com"
+
+        with patch("hindsight_api.config.get_config", return_value=mock_config):
+            embeddings = create_embeddings_from_env()
+
+            assert isinstance(embeddings, LiteLLMSDKEmbeddings)
+            assert embeddings.api_base == "https://custom.api.com"
+
+
+class TestLiteLLMSDKCohereEmbeddings:
+    """Integration tests calling real Cohere API (matches CI pattern)."""
+
+    @pytest.fixture
+    async def litellm_cohere_embeddings(self):
+        """Create embeddings instance with real Cohere API key."""
+        if not os.environ.get("COHERE_API_KEY"):
+            pytest.skip("Cohere API key not available")
+
+        emb = LiteLLMSDKEmbeddings(
+            api_key=os.environ["COHERE_API_KEY"],
+            model="cohere/embed-english-v3.0",
+            api_base=None,
+            batch_size=100,
+            timeout=60.0,
+        )
+        await emb.initialize()
+        return emb
+
+    @pytest.mark.asyncio
+    async def test_litellm_sdk_cohere_encode(self, litellm_cohere_embeddings):
+        """Test real Cohere API call for embeddings."""
+        texts = [
+            "The quick brown fox jumps over the lazy dog",
+            "Machine learning is a subset of artificial intelligence",
+            "Python is a popular programming language",
+        ]
+
+        result = litellm_cohere_embeddings.encode(texts)
+
+        # Verify result type and shape
+        assert isinstance(result, list)
+        assert len(result) == 3
+        assert all(len(embedding) > 0 for embedding in result)
+        assert all(isinstance(x, float) for x in result[0])
+
+        # Verify embeddings are not zeros (common API failure mode)
+        for i, embedding in enumerate(result):
+            assert not all(abs(x) < 0.0001 for x in embedding), f"Embedding {i} is all zeros"
+
+        # Verify embeddings are normalized (Cohere returns normalized vectors)
+        for i, embedding in enumerate(result):
+            norm = sum(x * x for x in embedding) ** 0.5
+            assert 0.9 < norm < 1.1, f"Embedding {i} norm {norm} is not close to 1.0"
+
+    @pytest.mark.asyncio
+    async def test_litellm_sdk_cohere_dimension(self, litellm_cohere_embeddings):
+        """Test dimension detection with real Cohere API."""
+        dimension = litellm_cohere_embeddings.dimension
+
+        # Cohere embed-english-v3.0 has 1024 dimensions
+        assert dimension == 1024
+
+    @pytest.mark.asyncio
+    async def test_litellm_sdk_cohere_single_text(self, litellm_cohere_embeddings):
+        """Test encoding single text with real Cohere API."""
+        result = litellm_cohere_embeddings.encode(["Hello world"])
+
+        assert isinstance(result, list)
+        assert len(result) == 1
+        assert len(result[0]) == 1024
+        assert not all(abs(x) < 0.0001 for x in result[0])

hindsight-api/tests/test_llm_provider.py

@@ -88,6 +88,7 @@ def should_skip_provider(provider: str, model: str = "") -> tuple[bool, str]:
 
 @pytest.mark.parametrize("provider,model", MODEL_MATRIX)
 @pytest.mark.asyncio
+@pytest.mark.timeout(300)  # Increase timeout for slow models like groq gpt-oss-120b
 async def test_llm_provider_api_methods(provider: str, model: str):
     """
     Test all LLM API methods used by Hindsight at runtime.
@@ -141,27 +142,32 @@ async def test_llm_provider_api_methods(provider: str, model: str):
         pytest.fail(f"{provider}/{model} call() plain text failed: {e}")
 
     # Test 3: call() with response_format (structured output)
-    try:
-        from pydantic import BaseModel
+    # Skip for models that don't support structured output
+    skip_structured_output = (provider == "groq" and "gpt-oss-120b" in model.lower())
+    if skip_structured_output:
+        print(f"  ⊘ call() structured output: skipped (model doesn't support response_format)")
+    else:
+        try:
+            from pydantic import BaseModel
 
-        class TestResponse(BaseModel):
-            answer: str
-            confidence: str
+            class TestResponse(BaseModel):
+                answer: str
+                confidence: str
 
-        response = await llm.call(
-            messages=[
-                {"role": "system", "content": "You are a math assistant."},
-                {"role": "user", "content": "What is the capital of France?"},
-            ],
-            response_format=TestResponse,
-            max_completion_tokens=100,
-        )
-        assert isinstance(response, TestResponse), f"Expected TestResponse, got {type(response)}"
-        assert hasattr(response, "answer"), "Structured output missing 'answer' field"
-        assert hasattr(response, "confidence"), "Structured output missing 'confidence' field"
-        print(f"  ✓ call() structured output: answer={response.answer}, confidence={response.confidence}")
-    except Exception as e:
-        pytest.fail(f"{provider}/{model} call() structured output failed: {e}")
+            response = await llm.call(
+                messages=[
+                    {"role": "system", "content": "You are a math assistant."},
+                    {"role": "user", "content": "What is the capital of France?"},
+                ],
+                response_format=TestResponse,
+                max_completion_tokens=100,
+            )
+            assert isinstance(response, TestResponse), f"Expected TestResponse, got {type(response)}"
+            assert hasattr(response, "answer"), "Structured output missing 'answer' field"
+            assert hasattr(response, "confidence"), "Structured output missing 'confidence' field"
+            print(f"  ✓ call() structured output: answer={response.answer}, confidence={response.confidence}")
+        except Exception as e:
+            pytest.fail(f"{provider}/{model} call() structured output failed: {e}")
 
     # Test 4: call_with_tools() (tool calling)
     try:
@@ -189,7 +195,7 @@ async def test_llm_provider_api_methods(provider: str, model: str):
                 {"role": "user", "content": "What's the weather like in Paris?"},
             ],
             tools=tools,
-            max_completion_tokens=200,
+            max_completion_tokens=500,  # Increased from 200 to give models enough space for tool calls
         )
 
         assert result is not None, "call_with_tools() returned None"

hindsight-api/tests/test_load_large_batch.py

@@ -209,7 +209,7 @@ class TestLargeBatchRetain:
                 raise
 
     @pytest.mark.asyncio
-    @pytest.mark.timeout(120)
+    @pytest.mark.timeout(240)  # Increased timeout for VectorChord BM25 tokenization
     async def test_batch_chunking_behavior(self, memory_with_mock_llm, request_context):
         """
         Test that large batches are properly chunked into sub-batches.

hindsight-api/tests/test_main_module.py

@@ -45,7 +45,7 @@ class TestMainModuleExtensionLoading:
 
         with patch("hindsight_api.main.MemoryEngine") as mock_engine, \
              patch("hindsight_api.main.create_app") as mock_create_app, \
-             patch("hindsight_api.main.get_config") as mock_get_config, \
+             patch("hindsight_api.main._get_raw_config") as mock_get_config, \
              patch("hindsight_api.main.load_extension", side_effect=tracking_load_extension), \
              patch("hindsight_api.main.DefaultExtensionContext"), \
              patch("hindsight_api.main.print_banner"), \
@@ -96,7 +96,7 @@ class TestMainModuleExtensionLoading:
 
         with patch("hindsight_api.main.MemoryEngine") as mock_engine, \
              patch("hindsight_api.main.create_app") as mock_create_app, \
-             patch("hindsight_api.main.get_config") as mock_get_config, \
+             patch("hindsight_api.main._get_raw_config") as mock_get_config, \
              patch("hindsight_api.main.load_extension", side_effect=tracking_load_extension), \
              patch("hindsight_api.main.DefaultExtensionContext"), \
              patch("hindsight_api.main.print_banner"), \
@@ -143,7 +143,7 @@ class TestMainModuleExtensionLoading:
 
         with patch("hindsight_api.main.MemoryEngine", side_effect=capture_memory_engine), \
              patch("hindsight_api.main.create_app") as mock_create_app, \
-             patch("hindsight_api.main.get_config") as mock_get_config, \
+             patch("hindsight_api.main._get_raw_config") as mock_get_config, \
              patch("hindsight_api.main.DefaultExtensionContext"), \
              patch("hindsight_api.main.print_banner"), \
              patch("uvicorn.run"):
@@ -200,7 +200,7 @@ class TestMainModuleExtensionLoading:
 
         with patch("hindsight_api.main.MemoryEngine", side_effect=capture_memory_engine), \
              patch("hindsight_api.main.create_app") as mock_create_app, \
-             patch("hindsight_api.main.get_config") as mock_get_config, \
+             patch("hindsight_api.main._get_raw_config") as mock_get_config, \
              patch("hindsight_api.main.DefaultExtensionContext", side_effect=capture_context), \
              patch("hindsight_api.main.print_banner"), \
              patch("uvicorn.run"):
@@ -242,7 +242,7 @@ class TestMainModuleExtensionLoading:
 
         with patch("hindsight_api.main.MemoryEngine", side_effect=capture_memory_engine), \
              patch("hindsight_api.main.create_app") as mock_create_app, \
-             patch("hindsight_api.main.get_config") as mock_get_config, \
+             patch("hindsight_api.main._get_raw_config") as mock_get_config, \
              patch("hindsight_api.main.print_banner"), \
              patch("uvicorn.run"):
 
@@ -287,7 +287,7 @@ class TestMainModuleExtensionLoading:
 
         with patch("hindsight_api.main.MemoryEngine") as mock_engine, \
              patch("hindsight_api.main.create_app", return_value=mock_app), \
-             patch("hindsight_api.main.get_config") as mock_get_config, \
+             patch("hindsight_api.main._get_raw_config") as mock_get_config, \
              patch("hindsight_api.main.print_banner"), \
              patch("uvicorn.run", side_effect=capture_uvicorn_run):
 
@@ -327,7 +327,7 @@ class TestMainModuleExtensionLoading:
 
         with patch("hindsight_api.main.MemoryEngine") as mock_engine, \
              patch("hindsight_api.main.create_app") as mock_create_app, \
-             patch("hindsight_api.main.get_config") as mock_get_config, \
+             patch("hindsight_api.main._get_raw_config") as mock_get_config, \
              patch("hindsight_api.main.print_banner"), \
              patch("uvicorn.run", side_effect=capture_uvicorn_run):
 

hindsight-api/tests/test_mcp_endpoint_routing.py

@@ -0,0 +1,280 @@
+"""Integration test for MCP endpoint routing.
+
+This test verifies that /mcp/ and /mcp/{bank_id}/ expose different tool sets,
+and that URLs with or without trailing slashes both work (no 307 redirect).
+"""
+
+import httpx
+import pytest
+from mcp.client.session import ClientSession
+from mcp.client.streamable_http import streamable_http_client
+
+
+@pytest.mark.asyncio
+async def test_mcp_endpoint_routing_integration(memory):
+    """Test that multi-bank and single-bank endpoints expose different tools using StreamableHTTP.
+
+    This is a regression test for issue #317 where /mcp/{bank_id}/ was incorrectly
+    exposing all tools (including list_banks) and bank_id parameters.
+    """
+    from hindsight_api.api import create_app
+
+    # Create app with MCP enabled
+    app = create_app(memory, mcp_api_enabled=True, initialize_memory=False)
+
+    # Use the app's lifespan context to properly initialize MCP servers
+    async with app.router.lifespan_context(app):
+        # Create an HTTPX client that routes to our ASGI app
+        from httpx import ASGITransport
+
+        async with httpx.AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as http_client:
+            # Test 1: Multi-bank endpoint /mcp/
+            async with streamable_http_client("http://test/mcp/", http_client=http_client) as (
+                read_stream,
+                write_stream,
+                _,
+            ):
+                async with ClientSession(read_stream, write_stream) as session:
+                    await session.initialize()
+                    multi_result = await session.list_tools()
+
+                    multi_tools = {t.name for t in multi_result.tools}
+
+                    # Multi-bank should have all tools including bank management and mental models
+                    assert "retain" in multi_tools
+                    assert "recall" in multi_tools
+                    assert "reflect" in multi_tools
+                    assert "list_banks" in multi_tools, "Multi-bank should expose list_banks"
+                    assert "create_bank" in multi_tools, "Multi-bank should expose create_bank"
+                    assert "list_mental_models" in multi_tools, "Multi-bank should expose list_mental_models"
+                    assert "create_mental_model" in multi_tools, "Multi-bank should expose create_mental_model"
+                    assert "get_mental_model" in multi_tools, "Multi-bank should expose get_mental_model"
+                    assert "update_mental_model" in multi_tools, "Multi-bank should expose update_mental_model"
+                    assert "delete_mental_model" in multi_tools, "Multi-bank should expose delete_mental_model"
+                    assert "refresh_mental_model" in multi_tools, "Multi-bank should expose refresh_mental_model"
+
+                    # Multi-bank retain should have bank_id parameter
+                    retain_tool = next((t for t in multi_result.tools if t.name == "retain"), None)
+                    assert retain_tool is not None
+                    multi_params = set(retain_tool.inputSchema.get("properties", {}).keys())
+                    assert "bank_id" in multi_params, "Multi-bank retain should have bank_id parameter"
+
+            # Test 2: Single-bank endpoint /mcp/test-bank/
+            async with streamable_http_client("http://test/mcp/test-bank/", http_client=http_client) as (
+                read_stream,
+                write_stream,
+                _,
+            ):
+                async with ClientSession(read_stream, write_stream) as session:
+                    await session.initialize()
+                    single_result = await session.list_tools()
+
+                    single_tools = {t.name for t in single_result.tools}
+
+                    # Single-bank should have scoped tools including mental models (no bank management)
+                    assert "retain" in single_tools
+                    assert "recall" in single_tools
+                    assert "reflect" in single_tools
+                    assert "list_mental_models" in single_tools, "Single-bank should expose list_mental_models"
+                    assert "create_mental_model" in single_tools, "Single-bank should expose create_mental_model"
+                    assert "list_banks" not in single_tools, "Single-bank should NOT expose list_banks"
+                    assert "create_bank" not in single_tools, "Single-bank should NOT expose create_bank"
+
+                    # Single-bank retain should NOT have bank_id parameter
+                    retain_tool = next((t for t in single_result.tools if t.name == "retain"), None)
+                    assert retain_tool is not None
+                    single_params = set(retain_tool.inputSchema.get("properties", {}).keys())
+                    assert "bank_id" not in single_params, "Single-bank retain should NOT have bank_id parameter"
+
+
+@pytest.mark.asyncio
+async def test_mcp_no_trailing_slash_works(memory):
+    """Test that /mcp (no trailing slash) discovers tools without 307 redirect.
+
+    Starlette's Mount class redirects /mcp to /mcp/ with a 307 Temporary Redirect.
+    Many MCP clients don't follow POST redirects, causing 0 tools to be discovered.
+    MCPMiddleware wraps the app directly (no Mount), so the redirect never happens.
+    """
+    from hindsight_api.api import create_app
+
+    app = create_app(memory, mcp_api_enabled=True, initialize_memory=False)
+
+    async with app.router.lifespan_context(app):
+        from httpx import ASGITransport
+
+        async with httpx.AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as http_client:
+            # /mcp (no slash) should work the same as /mcp/
+            async with streamable_http_client("http://test/mcp", http_client=http_client) as (
+                read_stream,
+                write_stream,
+                _,
+            ):
+                async with ClientSession(read_stream, write_stream) as session:
+                    await session.initialize()
+                    result = await session.list_tools()
+
+                    tools = {t.name for t in result.tools}
+                    assert len(tools) >= 11, f"Expected at least 11 tools from /mcp, got {len(tools)}: {tools}"
+                    assert "retain" in tools
+                    assert "recall" in tools
+                    assert "list_banks" in tools
+
+            # /mcp/my-bank (single-bank, no slash) should also work
+            async with streamable_http_client("http://test/mcp/my-bank", http_client=http_client) as (
+                read_stream,
+                write_stream,
+                _,
+            ):
+                async with ClientSession(read_stream, write_stream) as session:
+                    await session.initialize()
+                    result = await session.list_tools()
+
+                    tools = {t.name for t in result.tools}
+                    assert "retain" in tools
+                    assert "list_banks" not in tools, "Single-bank /mcp/my-bank should NOT expose list_banks"
+
+
+@pytest.mark.asyncio
+async def test_mcp_tool_execution_through_client(memory):
+    """Test that tools can be called (not just discovered) through the MCP client.
+
+    This verifies the full pipeline: HTTP → middleware → FastMCP → tool → engine → response.
+    Previous tests only checked tool discovery (list_tools), not actual execution.
+    """
+    from httpx import ASGITransport
+
+    from hindsight_api.api import create_app
+
+    app = create_app(memory, mcp_api_enabled=True, initialize_memory=False)
+
+    async with app.router.lifespan_context(app):
+        async with httpx.AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as http_client:
+            async with streamable_http_client("http://test/mcp/", http_client=http_client) as (
+                read_stream,
+                write_stream,
+                _,
+            ):
+                async with ClientSession(read_stream, write_stream) as session:
+                    await session.initialize()
+
+                    # Execute list_banks tool
+                    result = await session.call_tool("list_banks", arguments={})
+                    assert result is not None
+                    assert len(result.content) > 0
+                    # The result text should be valid JSON with a "banks" key
+                    import json
+
+                    response_text = result.content[0].text
+                    parsed = json.loads(response_text)
+                    assert "banks" in parsed
+
+
+@pytest.mark.asyncio
+async def test_mcp_mental_model_validation_through_client(memory):
+    """Test that input validation works through the real MCP transport.
+
+    Verifies that invalid inputs return error messages without crashing,
+    and that the engine is never called with invalid data.
+    """
+    from httpx import ASGITransport
+
+    from hindsight_api.api import create_app
+
+    app = create_app(memory, mcp_api_enabled=True, initialize_memory=False)
+
+    async with app.router.lifespan_context(app):
+        async with httpx.AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as http_client:
+            async with streamable_http_client("http://test/mcp/", http_client=http_client) as (
+                read_stream,
+                write_stream,
+                _,
+            ):
+                async with ClientSession(read_stream, write_stream) as session:
+                    await session.initialize()
+
+                    # Test: empty name should return validation error
+                    import json
+
+                    result = await session.call_tool(
+                        "create_mental_model",
+                        arguments={"name": "", "source_query": "test query"},
+                    )
+                    assert result is not None
+                    parsed = json.loads(result.content[0].text)
+                    assert "error" in parsed
+                    assert "name cannot be empty" in parsed["error"]
+
+                    # Test: max_tokens out of range should return validation error
+                    result = await session.call_tool(
+                        "create_mental_model",
+                        arguments={"name": "Test", "source_query": "test query", "max_tokens": 0},
+                    )
+                    parsed = json.loads(result.content[0].text)
+                    assert "error" in parsed
+                    assert "max_tokens must be between 256 and 8192" in parsed["error"]
+
+
+@pytest.mark.asyncio
+async def test_mcp_bank_named_sse_routes_to_single_bank(memory):
+    """Test that a bank named 'sse' routes to single-bank mode.
+
+    Regression test: the old MCP_ENDPOINTS blocklist prevented banks named 'sse'
+    or 'messages' from being accessed via path routing. They fell through to
+    multi-bank mode instead.
+    """
+    from httpx import ASGITransport
+
+    from hindsight_api.api import create_app
+
+    app = create_app(memory, mcp_api_enabled=True, initialize_memory=False)
+
+    async with app.router.lifespan_context(app):
+        async with httpx.AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as http_client:
+            async with streamable_http_client("http://test/mcp/sse/", http_client=http_client) as (
+                read_stream,
+                write_stream,
+                _,
+            ):
+                async with ClientSession(read_stream, write_stream) as session:
+                    await session.initialize()
+                    result = await session.list_tools()
+                    tools = {t.name for t in result.tools}
+
+                    # Should be single-bank mode (no bank management tools)
+                    assert "retain" in tools
+                    assert "recall" in tools
+                    assert "list_banks" not in tools, "Bank 'sse' should route to single-bank mode"
+                    assert "create_bank" not in tools
+
+                    # retain should NOT have bank_id parameter (single-bank mode)
+                    retain_tool = next(t for t in result.tools if t.name == "retain")
+                    params = set(retain_tool.inputSchema.get("properties", {}).keys())
+                    assert "bank_id" not in params
+
+
+@pytest.mark.asyncio
+async def test_mcp_bank_named_messages_routes_to_single_bank(memory):
+    """Test that a bank named 'messages' routes to single-bank mode.
+
+    Same regression test as test_mcp_bank_named_sse_routes_to_single_bank but for 'messages'.
+    """
+    from httpx import ASGITransport
+
+    from hindsight_api.api import create_app
+
+    app = create_app(memory, mcp_api_enabled=True, initialize_memory=False)
+
+    async with app.router.lifespan_context(app):
+        async with httpx.AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as http_client:
+            async with streamable_http_client("http://test/mcp/messages/", http_client=http_client) as (
+                read_stream,
+                write_stream,
+                _,
+            ):
+                async with ClientSession(read_stream, write_stream) as session:
+                    await session.initialize()
+                    result = await session.list_tools()
+                    tools = {t.name for t in result.tools}
+
+                    assert "retain" in tools
+                    assert "list_banks" not in tools, "Bank 'messages' should route to single-bank mode"

hindsight-api/tests/test_mcp_extension.py

@@ -0,0 +1,169 @@
+"""Tests for MCPExtension loading and tool registration."""
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+from fastmcp import FastMCP
+
+from hindsight_api import MemoryEngine
+from hindsight_api.extensions.mcp import MCPExtension
+
+
+class MockMCPExtension(MCPExtension):
+    """Test extension that registers a custom tool."""
+
+    def __init__(self, config=None):
+        super().__init__(config)
+        self.register_tools_called = False
+        self.registered_mcp = None
+        self.registered_memory = None
+
+    def register_tools(self, mcp: FastMCP, memory: MemoryEngine) -> None:
+        """Register a test tool to verify extension was called."""
+        self.register_tools_called = True
+        self.registered_mcp = mcp
+        self.registered_memory = memory
+
+        @mcp.tool()
+        async def test_extension_tool(query: str) -> str:
+            """A test tool registered by the extension."""
+            return f"Extension tool received: {query}"
+
+
+class TestMCPExtensionBase:
+    """Tests for MCPExtension base class."""
+
+    def test_mcp_extension_is_abstract(self):
+        """MCPExtension.register_tools is abstract and must be implemented."""
+        with pytest.raises(TypeError, match="abstract method"):
+            MCPExtension()
+
+    def test_subclass_can_be_instantiated(self):
+        """Subclass implementing register_tools can be instantiated."""
+        ext = MockMCPExtension()
+        assert ext is not None
+        assert ext.register_tools_called is False
+
+    def test_register_tools_receives_mcp_and_memory(self):
+        """register_tools receives FastMCP and MemoryEngine instances."""
+        ext = MockMCPExtension()
+        mcp = FastMCP("test")
+        memory = MagicMock(spec=MemoryEngine)
+
+        ext.register_tools(mcp, memory)
+
+        assert ext.register_tools_called is True
+        assert ext.registered_mcp is mcp
+        assert ext.registered_memory is memory
+
+
+class TestMCPExtensionLoading:
+    """Tests for MCPExtension loading in create_mcp_server."""
+
+    @pytest.fixture
+    def mock_memory(self):
+        """Create a mock MemoryEngine."""
+        memory = MagicMock()
+        memory._tenant_extension = MagicMock()
+        memory._tenant_extension.authenticate_mcp = MagicMock()
+        return memory
+
+    def test_create_mcp_server_without_extension(self, mock_memory):
+        """create_mcp_server works without MCPExtension configured."""
+        from hindsight_api.api.mcp import create_mcp_server
+
+        with patch("hindsight_api.api.mcp.load_extension", return_value=None):
+            mcp = create_mcp_server(mock_memory)
+
+        # Core tools should be registered
+        tools = mcp._tool_manager._tools
+        assert "retain" in tools
+        assert "recall" in tools
+        assert "reflect" in tools
+        # Extension tool should NOT be present
+        assert "test_extension_tool" not in tools
+
+    def test_create_mcp_server_with_extension(self, mock_memory):
+        """create_mcp_server loads and calls MCPExtension when configured."""
+        from hindsight_api.api.mcp import create_mcp_server
+
+        mock_ext = MockMCPExtension()
+
+        with patch("hindsight_api.api.mcp.load_extension", return_value=mock_ext):
+            mcp = create_mcp_server(mock_memory)
+
+        # Extension should have been called
+        assert mock_ext.register_tools_called is True
+
+        # Core tools should still be registered
+        tools = mcp._tool_manager._tools
+        assert "retain" in tools
+        assert "recall" in tools
+
+        # Extension tool should also be registered
+        assert "test_extension_tool" in tools
+
+    @pytest.mark.asyncio
+    async def test_extension_tool_is_callable(self, mock_memory):
+        """Tool registered by extension can be called."""
+        from hindsight_api.api.mcp import create_mcp_server
+
+        mock_ext = MockMCPExtension()
+
+        with patch("hindsight_api.api.mcp.load_extension", return_value=mock_ext):
+            mcp = create_mcp_server(mock_memory)
+
+        # Get and call the extension tool
+        tools = mcp._tool_manager._tools
+        test_tool = tools["test_extension_tool"]
+        result = await test_tool.fn(query="hello world")
+
+        assert result == "Extension tool received: hello world"
+
+    def test_load_extension_called_with_correct_args(self, mock_memory):
+        """load_extension is called with 'MCP' prefix and MCPExtension class."""
+        from hindsight_api.api.mcp import create_mcp_server
+
+        with patch("hindsight_api.api.mcp.load_extension") as mock_load:
+            mock_load.return_value = None
+            create_mcp_server(mock_memory)
+
+        mock_load.assert_called_once_with("MCP", MCPExtension)
+
+
+class TestMCPExtensionIntegration:
+    """Integration tests verifying extension tools work end-to-end."""
+
+    @pytest.fixture
+    def mock_memory(self):
+        """Create a mock MemoryEngine with required methods."""
+        memory = MagicMock()
+        memory.retain_batch_async = MagicMock()
+        memory.submit_async_retain = MagicMock(return_value={"operation_id": "test-op"})
+        memory.recall_async = MagicMock(return_value=MagicMock(results=[]))
+        memory.reflect_async = MagicMock(return_value=MagicMock(text="reflection"))
+        memory.list_banks = MagicMock(return_value=[])
+        memory.get_bank_profile = MagicMock(return_value={"id": "test"})
+        memory._tenant_extension = MagicMock()
+        return memory
+
+    def test_extension_tools_coexist_with_core_tools(self, mock_memory):
+        """Extension tools are added alongside core tools, not replacing them."""
+        from hindsight_api.api.mcp import create_mcp_server
+
+        mock_ext = MockMCPExtension()
+
+        with patch("hindsight_api.api.mcp.load_extension", return_value=mock_ext):
+            mcp = create_mcp_server(mock_memory)
+
+        tools = mcp._tool_manager._tools
+        # All core tools present
+        assert "retain" in tools
+        assert "recall" in tools
+        assert "reflect" in tools
+        assert "list_banks" in tools
+        assert "create_bank" in tools
+        # Extension tool also present
+        assert "test_extension_tool" in tools
+        # At least 11 core + 1 extension = 12 tools (may grow as new tools are added)
+        assert len(tools) >= 12