refactor: simplify chunk fetching to always use pre-filtering approach

Remove backward compatibility code that fetched chunks after token
filtering. Now chunks are always fetched from top-scored results
before max_tokens filtering, regardless of max_tokens value.

This simplifies the code by:
- Removing duplicate chunk fetching logic
- Eliminating conditional behavior based on max_tokens
- Making chunk fetching behavior consistent and predictable

Chunks are still fetched in batches and respect max_chunk_tokens limit.

.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)

CLAUDE.md

@@ -238,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
 
@@ -281,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)

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/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

@@ -112,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

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,73 @@ branch_labels: str | Sequence[str] | None = None
 depends_on: str | Sequence[str] | None = None
 
 
+def _detect_vector_extension() -> str:
+    """
+    Detect or validate vector extension: 'vchord' or 'pgvector'.
+    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 == "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' or 'vchord'")
+
+
+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 +234,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 +286,47 @@ 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 == "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,83 @@ def _get_schema_prefix() -> str:
     return f'"{schema}".' if schema else ""
 
 
+def _detect_vector_extension() -> str:
+    """
+    Detect or validate vector extension: 'vchord' or 'pgvector'.
+    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 == "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' or 'vchord'")
+
+
+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 +132,48 @@ 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 == "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 +199,52 @@ 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 == "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/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/http.py

@@ -70,6 +70,7 @@ def FieldWithDefault(default_factory: Callable, **kwargs) -> Any:
     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
@@ -826,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."""
 
@@ -1355,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):
@@ -1368,6 +1419,7 @@ class VersionResponse(BaseModel):
                     "observations": False,
                     "mcp": True,
                     "worker": True,
+                    "bank_config_api": False,
                 },
             }
         }
@@ -1524,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",
@@ -1537,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
@@ -1643,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,
             ),
         )
 
@@ -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

@@ -114,9 +114,39 @@ def create_mcp_server(memory: MemoryEngine, multi_bank: bool = True) -> FastMCP:
         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 intercepts MCP requests and routes to appropriate MCP server.
 
@@ -142,6 +172,11 @@ class MCPMiddleware:
        - 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/ \\
@@ -242,20 +277,25 @@ class MCPMiddleware:
             _current_schema.set(tenant_context.schema_name) if tenant_context and tenant_context.schema_name else None
         )
 
-        # Try to get bank_id from header first (for Claude Code compatibility)
-        bank_id = self._get_header(scope, "X-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
-
-        # If no header, try to extract from path: /{bank_id}/...
         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)
             if parts[0]:
-                # First segment looks like a bank_id
                 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

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"
@@ -91,6 +189,14 @@ 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"
@@ -107,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"
@@ -223,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 vs vchord)
+DEFAULT_VECTOR_EXTENSION = "pgvector"  # Options: "pgvector", "vchord"
+
+# 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
@@ -358,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
@@ -419,6 +544,9 @@ class HindsightConfig:
     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
@@ -436,13 +564,18 @@ class HindsightConfig:
     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
@@ -495,8 +628,108 @@ class HindsightConfig:
     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")
+        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:
@@ -522,6 +755,8 @@ class HindsightConfig:
             # 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),
@@ -630,6 +865,12 @@ class HindsightConfig:
             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),
@@ -659,12 +900,19 @@ class HindsightConfig:
             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))),
@@ -805,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
 
@@ -1016,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/cross_encoder.py

@@ -21,6 +21,7 @@ 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,
@@ -32,6 +33,7 @@ from ..config import (
     ENV_RERANKER_COHERE_MODEL,
     ENV_RERANKER_FLASHRANK_CACHE_DIR,
     ENV_RERANKER_FLASHRANK_MODEL,
+    ENV_RERANKER_LITELLM_SDK_API_KEY,
     ENV_RERANKER_LOCAL_FORCE_CPU,
     ENV_RERANKER_LOCAL_MAX_CONCURRENT,
     ENV_RERANKER_LOCAL_MODEL,
@@ -828,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.
@@ -877,9 +999,20 @@ def create_cross_encoder_from_env() -> CrossEncoderModel:
             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,6 +19,7 @@ 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,
@@ -26,6 +27,7 @@ from ..config import (
     DEFAULT_EMBEDDINGS_PROVIDER,
     DEFAULT_LITELLM_API_BASE,
     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,
@@ -720,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.
@@ -771,7 +915,19 @@ def create_embeddings_from_env() -> Embeddings:
             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/memory_engine.py

@@ -968,7 +968,12 @@ class MemoryEngine(MemoryEngineInterface):
 
         # Run database migrations if enabled
         if self._run_migrations:
-            from ..migrations import ensure_embedding_dimension, run_migrations
+            from ..migrations import (
+                ensure_embedding_dimension,
+                ensure_text_search_extension,
+                ensure_vector_extension,
+                run_migrations,
+            )
 
             if not self.db_url:
                 raise ValueError("Database URL is required for migrations")
@@ -976,30 +981,43 @@ class MemoryEngine(MemoryEngineInterface):
             # Migrate all schemas from the tenant extension
             # The tenant extension is the single source of truth for which schemas exist
             logger.info("Running database migrations...")
-            try:
-                tenants = await self._tenant_extension.list_tenants()
-                if tenants:
-                    logger.info(f"Running migrations on {len(tenants)} schema(s)...")
-                    for tenant in tenants:
-                        schema = tenant.schema
-                        if schema:
-                            try:
-                                run_migrations(self.db_url, schema=schema)
-                            except Exception as e:
-                                logger.warning(f"Failed to migrate schema {schema}: {e}")
-                    logger.info("Schema migrations completed")
+            tenants = await self._tenant_extension.list_tenants()
+            if tenants:
+                logger.info(f"Running migrations on {len(tenants)} schema(s)...")
+                for tenant in tenants:
+                    schema = tenant.schema
+                    if schema:
+                        run_migrations(self.db_url, schema=schema)
+                logger.info("Schema migrations completed")
 
-                    # Ensure embedding column dimension matches the model's dimension
-                    # This is done after migrations and after embeddings.initialize()
-                    for tenant in tenants:
-                        schema = tenant.schema
-                        if schema:
-                            try:
-                                ensure_embedding_dimension(self.db_url, self.embeddings.dimension, schema=schema)
-                            except Exception as e:
-                                logger.warning(f"Failed to ensure embedding dimension for schema {schema}: {e}")
-            except Exception as e:
-                logger.warning(f"Failed to run schema migrations: {e}")
+                # Get config for vector extension setting
+                config = get_config()
+
+                # Ensure embedding column dimension matches the model's dimension
+                # This is done after migrations and after embeddings.initialize()
+                for tenant in tenants:
+                    schema = tenant.schema
+                    if schema:
+                        ensure_embedding_dimension(
+                            self.db_url,
+                            self.embeddings.dimension,
+                            schema=schema,
+                            vector_extension=config.vector_extension,
+                        )
+
+                # Ensure vector indexes match the configured extension
+                for tenant in tenants:
+                    schema = tenant.schema
+                    if schema:
+                        ensure_vector_extension(self.db_url, vector_extension=config.vector_extension, schema=schema)
+
+                # Ensure text search columns/indexes match the configured extension
+                for tenant in tenants:
+                    schema = tenant.schema
+                    if schema:
+                        ensure_text_search_extension(
+                            self.db_url, text_search_extension=config.text_search_extension, schema=schema
+                        )
 
         logger.info(f"Connecting to PostgreSQL at {mask_network_location(self.db_url)}")
 
@@ -1018,6 +1036,12 @@ class MemoryEngine(MemoryEngineInterface):
         # Initialize entity resolver with pool
         self.entity_resolver = EntityResolver(self._pool)
 
+        # Initialize config resolver for hierarchical configuration
+        from ..config_resolver import ConfigResolver
+
+        self._config_resolver = ConfigResolver(pool=self._pool, tenant_extension=self._tenant_extension)
+        logger.debug("Config resolver initialized for hierarchical configuration")
+
         # Set executor for task backend and initialize
         self._task_backend.set_executor(self.execute_task)
         await self._task_backend.initialize()
@@ -1447,6 +1471,7 @@ class MemoryEngine(MemoryEngineInterface):
                 sub_results, sub_usage = await self._retain_batch_async_internal(
                     bank_id=bank_id,
                     contents=sub_batch,
+                    request_context=request_context,
                     document_id=document_id,
                     is_first_batch=i == 1,  # Only upsert on first batch
                     fact_type_override=fact_type_override,
@@ -1466,6 +1491,7 @@ class MemoryEngine(MemoryEngineInterface):
             result, total_usage = await self._retain_batch_async_internal(
                 bank_id=bank_id,
                 contents=contents,
+                request_context=request_context,
                 document_id=document_id,
                 is_first_batch=True,
                 fact_type_override=fact_type_override,
@@ -1497,9 +1523,8 @@ class MemoryEngine(MemoryEngineInterface):
                 logger.warning(f"Post-retain hook error (non-fatal): {e}")
 
         # Trigger consolidation as a tracked async operation if enabled
-        from ..config import get_config
-
-        config = get_config()
+        # Resolve bank-specific config to check if observations are enabled for this bank
+        config = await self._config_resolver.resolve_full_config(bank_id, request_context)
         if config.enable_observations:
             try:
                 await self.submit_async_consolidation(bank_id=bank_id, request_context=request_context)
@@ -1515,6 +1540,7 @@ class MemoryEngine(MemoryEngineInterface):
         self,
         bank_id: str,
         contents: list[RetainContentDict],
+        request_context: "RequestContext",
         document_id: str | None = None,
         is_first_batch: bool = True,
         fact_type_override: str | None = None,
@@ -1532,6 +1558,7 @@ class MemoryEngine(MemoryEngineInterface):
         Args:
             bank_id: Unique identifier for the bank
             contents: List of dicts with content, context, event_date
+            request_context: Request context for config resolution
             document_id: Optional document ID (always upserts if exists)
             is_first_batch: Whether this is the first batch (for chunked operations, only delete on first batch)
             fact_type_override: Override fact type for all facts
@@ -1548,6 +1575,9 @@ class MemoryEngine(MemoryEngineInterface):
 
             pool = await self._get_pool()
 
+            # Resolve bank-specific config for this operation
+            resolved_config = await self._config_resolver.resolve_full_config(bank_id, request_context)
+
             # Create parent span for retain operation
             with create_operation_span("retain", bank_id):
                 return await orchestrator.retain_batch(
@@ -1564,6 +1594,7 @@ class MemoryEngine(MemoryEngineInterface):
                     fact_type_override=fact_type_override,
                     confidence_score=confidence_score,
                     document_tags=document_tags,
+                    config=resolved_config,
                 )
 
     def recall(
@@ -1651,15 +1682,21 @@ class MemoryEngine(MemoryEngineInterface):
             max_entity_tokens: Maximum tokens for entity observations (default 500)
             include_chunks: Whether to include raw chunks in the response
             max_chunk_tokens: Maximum tokens for chunks (default 8192)
+                             NOTE: Chunks are fetched independently of max_tokens filtering.
+                             This means setting max_tokens=0 will return 0 facts but can still
+                             return chunks from the top-scored (reranked) results.
+                             Chunks are fetched in batches (estimated as (max_chunk_tokens // retain_chunk_size) * 2)
+                             until the token budget is exhausted or all chunks are fetched.
+                             This handles varying chunk sizes across documents.
             tags: Optional list of tags for visibility filtering (OR matching - returns
                   memories that have at least one matching tag)
 
         Returns:
             RecallResultModel containing:
-            - results: List of MemoryFact objects
+            - results: List of MemoryFact objects (filtered by max_tokens)
             - trace: Optional trace information for debugging
             - entities: Optional dict of entity states (if include_entities=True)
-            - chunks: Optional dict of chunks (if include_chunks=True)
+            - chunks: Optional dict of chunks (if include_chunks=True, independent of max_tokens)
         """
         # Authenticate tenant and set schema in context (for fq_table())
         await self._authenticate_tenant(request_context)
@@ -1887,7 +1924,8 @@ class MemoryEngine(MemoryEngineInterface):
         2. Merge: RRF to combine ranked lists
         3. Reranking: Pluggable strategy (heuristic or cross-encoder)
         4. Diversity: MMR with λ=0.5
-        5. Token Filter: Limit results to max_tokens budget
+        5. Chunks: Fetch chunks from top-scored results (BEFORE token filtering)
+        6. Token Filter: Limit facts to max_tokens budget
 
         Args:
             bank_id: bank IDentifier
@@ -1898,7 +1936,7 @@ class MemoryEngine(MemoryEngineInterface):
             enable_trace: Whether to return search trace (deprecated)
             include_entities: Whether to include entity observations
             max_entity_tokens: Maximum tokens for entity observations
-            include_chunks: Whether to include raw chunks
+            include_chunks: Whether to include raw chunks (fetched before max_tokens filtering)
             max_chunk_tokens: Maximum tokens for chunks
 
         Returns:
@@ -2321,6 +2359,85 @@ class MemoryEngine(MemoryEngineInterface):
             top_scored = scored_results[:rerank_limit]
             log_buffer.append(f"  [5] Truncated to top {len(top_scored)} results")
 
+            # Step 5.5: Fetch chunks from top-scored results (before token filtering)
+            # Chunks are fetched independently of max_tokens filtering
+            chunks_dict = None
+            total_chunk_tokens = 0
+            if include_chunks and top_scored:
+                from .response_models import ChunkInfo
+
+                # Collect chunk_ids in order of fact relevance (preserving order from top_scored)
+                # Use a list to maintain order, but track seen chunks to avoid duplicates
+                chunk_ids_ordered = []
+                seen_chunk_ids = set()
+                for sr in top_scored:
+                    chunk_id = sr.retrieval.chunk_id
+                    if chunk_id and chunk_id not in seen_chunk_ids:
+                        chunk_ids_ordered.append(chunk_id)
+                        seen_chunk_ids.add(chunk_id)
+
+                if chunk_ids_ordered:
+                    # Estimate batch size based on retain_chunk_size * 2 (rough estimate)
+                    # Chunk sizes vary per document, so we fetch in batches until budget is exhausted
+                    bank_config = await self._config_resolver.resolve_full_config(bank_id, request_context)
+                    estimated_batch_size = max(1, (max_chunk_tokens // bank_config.retain_chunk_size) * 2)
+
+                    chunks_dict = {}
+                    encoding = _get_tiktoken_encoding()
+                    chunk_offset = 0
+
+                    # Fetch chunks in batches until we run out of budget or chunks
+                    while chunk_offset < len(chunk_ids_ordered) and total_chunk_tokens < max_chunk_tokens:
+                        # Get next batch of chunk IDs
+                        batch_chunk_ids = chunk_ids_ordered[chunk_offset : chunk_offset + estimated_batch_size]
+                        chunk_offset += estimated_batch_size
+
+                        # Fetch chunk data from database
+                        async with acquire_with_retry(pool) as conn:
+                            chunks_rows = await conn.fetch(
+                                f"""
+                                SELECT chunk_id, chunk_text, chunk_index
+                                FROM {fq_table("chunks")}
+                                WHERE chunk_id = ANY($1::text[])
+                                """,
+                                batch_chunk_ids,
+                            )
+
+                        # Create a lookup dict for fast access (preserves order from batch_chunk_ids)
+                        chunks_lookup = {row["chunk_id"]: row for row in chunks_rows}
+
+                        # Process chunks in order, respecting token budget
+                        for chunk_id in batch_chunk_ids:
+                            if chunk_id not in chunks_lookup:
+                                continue
+
+                            row = chunks_lookup[chunk_id]
+                            chunk_text = row["chunk_text"]
+                            chunk_tokens = len(encoding.encode(chunk_text))
+
+                            # Check if adding this chunk would exceed the limit
+                            if total_chunk_tokens + chunk_tokens > max_chunk_tokens:
+                                # Truncate the chunk to fit within the remaining budget
+                                remaining_tokens = max_chunk_tokens - total_chunk_tokens
+                                if remaining_tokens > 0:
+                                    # Truncate to remaining tokens
+                                    truncated_text = encoding.decode(encoding.encode(chunk_text)[:remaining_tokens])
+                                    chunks_dict[chunk_id] = ChunkInfo(
+                                        chunk_text=truncated_text, chunk_index=row["chunk_index"], truncated=True
+                                    )
+                                    total_chunk_tokens = max_chunk_tokens
+                                # Budget exhausted - stop fetching more batches
+                                break
+                            else:
+                                chunks_dict[chunk_id] = ChunkInfo(
+                                    chunk_text=chunk_text, chunk_index=row["chunk_index"], truncated=False
+                                )
+                                total_chunk_tokens += chunk_tokens
+
+                        # If we hit the budget limit in this batch, stop fetching more batches
+                        if total_chunk_tokens >= max_chunk_tokens:
+                            break
+
             # Step 6: Token budget filtering
             step_start = time.time()
 
@@ -2415,68 +2532,6 @@ class MemoryEngine(MemoryEngineInterface):
             # Entity observations removed - always set to None
             entities_dict = None
 
-            # Fetch chunks if requested
-            chunks_dict = None
-            total_chunk_tokens = 0
-            if include_chunks and top_scored:
-                from .response_models import ChunkInfo
-
-                # Collect chunk_ids in order of fact relevance (preserving order from top_scored)
-                # Use a list to maintain order, but track seen chunks to avoid duplicates
-                chunk_ids_ordered = []
-                seen_chunk_ids = set()
-                for sr in top_scored:
-                    chunk_id = sr.retrieval.chunk_id
-                    if chunk_id and chunk_id not in seen_chunk_ids:
-                        chunk_ids_ordered.append(chunk_id)
-                        seen_chunk_ids.add(chunk_id)
-
-                if chunk_ids_ordered:
-                    # Fetch chunk data from database using chunk_ids (no ORDER BY to preserve input order)
-                    async with acquire_with_retry(pool) as conn:
-                        chunks_rows = await conn.fetch(
-                            f"""
-                            SELECT chunk_id, chunk_text, chunk_index
-                            FROM {fq_table("chunks")}
-                            WHERE chunk_id = ANY($1::text[])
-                            """,
-                            chunk_ids_ordered,
-                        )
-
-                    # Create a lookup dict for fast access
-                    chunks_lookup = {row["chunk_id"]: row for row in chunks_rows}
-
-                    # Apply token limit and build chunks_dict in the order of chunk_ids_ordered
-                    chunks_dict = {}
-                    encoding = _get_tiktoken_encoding()
-
-                    for chunk_id in chunk_ids_ordered:
-                        if chunk_id not in chunks_lookup:
-                            continue
-
-                        row = chunks_lookup[chunk_id]
-                        chunk_text = row["chunk_text"]
-                        chunk_tokens = len(encoding.encode(chunk_text))
-
-                        # Check if adding this chunk would exceed the limit
-                        if total_chunk_tokens + chunk_tokens > max_chunk_tokens:
-                            # Truncate the chunk to fit within the remaining budget
-                            remaining_tokens = max_chunk_tokens - total_chunk_tokens
-                            if remaining_tokens > 0:
-                                # Truncate to remaining tokens
-                                truncated_text = encoding.decode(encoding.encode(chunk_text)[:remaining_tokens])
-                                chunks_dict[chunk_id] = ChunkInfo(
-                                    chunk_text=truncated_text, chunk_index=row["chunk_index"], truncated=True
-                                )
-                                total_chunk_tokens = max_chunk_tokens
-                            # Stop adding more chunks once we hit the limit
-                            break
-                        else:
-                            chunks_dict[chunk_id] = ChunkInfo(
-                                chunk_text=chunk_text, chunk_index=row["chunk_index"], truncated=False
-                            )
-                            total_chunk_tokens += chunk_tokens
-
             # Finalize trace if enabled
             trace_dict = None
             if tracer:

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

@@ -702,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]:
     """
@@ -721,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
 
@@ -1055,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]:
     """
@@ -1070,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:
@@ -1088,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:
@@ -1132,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(
@@ -1141,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,
             ),
         ]
@@ -1164,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]:
     """
@@ -1178,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:
@@ -1188,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
@@ -1207,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)
@@ -1239,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.
@@ -1254,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)
@@ -1272,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)
 

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/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/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/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
@@ -88,6 +89,54 @@ class TenantExtension(Extension, ABC):
         """
         ...
 
+    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.

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,
@@ -206,6 +208,9 @@ def main():
             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,
@@ -221,11 +226,16 @@ def main():
             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,

hindsight-api/hindsight_api/migrations.py

@@ -33,6 +33,41 @@ logger = logging.getLogger(__name__)
 MIGRATION_LOCK_ID = 123456789
 
 
+def _detect_vector_extension(conn, vector_extension: str = "pgvector") -> str:
+    """
+    Validate vector extension: 'vchord' or 'pgvector'.
+
+    Args:
+        conn: SQLAlchemy connection object
+        vector_extension: Configured extension ("pgvector" or "vchord")
+
+    Returns:
+        "vchord" or "pgvector"
+
+    Raises:
+        RuntimeError: If configured extension is not installed
+    """
+    # Verify the configured extension is installed
+    if 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' or 'vchord'")
+
+
 def _get_schema_lock_id(schema: str) -> int:
     """
     Generate a unique advisory lock ID for a schema.
@@ -324,6 +359,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.
@@ -338,6 +374,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
@@ -361,6 +398,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(
@@ -408,8 +449,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 $$
@@ -419,7 +459,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;
@@ -434,15 +474,410 @@ 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 == "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
+        target_index_type = "vchordrq" if target_ext == "vchord" else "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 "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])
+            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_index_type.replace('vchordrq', 'vchord').replace('hnsw', 'pgvector')}')"
+            )
+
+        # 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 == "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/pyproject.toml

@@ -42,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_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_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_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_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_observations.py

@@ -8,14 +8,14 @@ populated from the summary for backwards compatibility.
 import pytest
 from hindsight_api.engine.memory_engine import Budget
 from hindsight_api import RequestContext
-from hindsight_api.config import get_config
+from hindsight_api.config import _get_raw_config
 from datetime import datetime, timezone
 
 
 @pytest.fixture
 def disable_observations():
     """Disable observations for a specific test."""
-    config = get_config()
+    config = _get_raw_config()
     original_value = config.enable_observations
     config.enable_observations = False
     yield

hindsight-api/tests/test_recall_chunks_independence.py

@@ -0,0 +1,274 @@
+"""
+Test that recall chunks are fetched independently of max_tokens filtering.
+
+This test verifies the new behavior where:
+1. Chunks are fetched BEFORE max_tokens filtering
+2. max_tokens=0 returns 0 facts but can still return chunks
+3. Chunks are fetched in batches to handle varying chunk sizes
+"""
+
+import pytest
+import pytest_asyncio
+
+from hindsight_api.engine.memory_engine import Budget
+
+
+@pytest.mark.asyncio
+async def test_recall_chunks_independent_of_max_tokens(memory, request_context):
+    """
+    Test that chunks are fetched independently of max_tokens.
+
+    When max_tokens=0, recall should:
+    - Return 0 memory facts
+    - Still return chunks (up to max_chunk_tokens)
+    - Chunks should come from top-scored results before token filtering
+    """
+    bank_id = "test-chunks-independence"
+
+    try:
+
+        # Retain some test content with substantial size to generate chunks
+        test_content = """
+        The quantum computing research team at MIT has made significant breakthroughs.
+        Dr. Sarah Chen leads the team and focuses on quantum error correction.
+        The team published three papers in Nature Physics this year.
+        Their work on topological qubits shows promise for scalable quantum computers.
+        Collaborators include IBM Research and Google Quantum AI.
+        The research is funded by a $5M NSF grant running through 2026.
+        """ * 10  # Repeat to ensure we get multiple chunks
+
+        await memory.retain_async(
+            bank_id=bank_id,
+            content=test_content,
+            context="research notes",
+            request_context=request_context,
+        )
+
+        # Test 1: Normal recall with both facts and chunks
+        result_normal = await memory.recall_async(
+            bank_id=bank_id,
+            query="quantum computing",
+            max_tokens=4096,  # Normal token budget
+            include_chunks=True,
+            max_chunk_tokens=2000,
+            budget=Budget.MID,
+            request_context=request_context,
+        )
+
+        assert len(result_normal.results) > 0, "Should return memory facts with normal max_tokens"
+        assert result_normal.chunks is not None, "Should include chunks when requested"
+        assert len(result_normal.chunks) > 0, "Should return at least one chunk"
+
+        # Test 2: Recall with max_tokens=0 but chunks enabled
+        result_chunks_only = await memory.recall_async(
+            bank_id=bank_id,
+            query="quantum computing",
+            max_tokens=0,  # Zero token budget for facts
+            include_chunks=True,
+            max_chunk_tokens=2000,  # But allow chunks
+            budget=Budget.MID,
+            request_context=request_context,
+        )
+
+        # Key assertions for new behavior
+        assert len(result_chunks_only.results) == 0, "max_tokens=0 should return 0 facts"
+        assert result_chunks_only.chunks is not None, "Should still include chunks dict"
+        assert len(result_chunks_only.chunks) > 0, "Should return chunks even with max_tokens=0"
+
+        # Verify chunks are from the same content (non-empty text)
+        for chunk_id, chunk_info in result_chunks_only.chunks.items():
+            assert len(chunk_info.chunk_text) > 0, "Chunks should contain text"
+            assert chunk_info.chunk_index >= 0, "Chunk should have valid index"
+
+    finally:
+        # Cleanup
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_recall_chunks_batching_with_varying_sizes(memory, request_context):
+    """
+    Test that chunk batching works correctly with varying chunk sizes.
+
+    This verifies that:
+    1. Chunks are fetched in batches until token budget is exhausted
+    2. The system handles varying chunk sizes across documents
+    3. Token budget is respected across multiple batch fetches
+    """
+    bank_id = "test-chunks-batching"
+
+    try:
+
+        # Retain multiple documents with different content sizes
+        # Document 1: Short content (small chunks)
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="Alice is a software engineer who specializes in Python programming and machine learning.",
+            context="doc1",
+            request_context=request_context,
+        )
+
+        # Document 2: Medium content
+        content_bob = """
+        Bob works as a data scientist at a tech startup in San Francisco.
+        He has expertise in natural language processing and computer vision.
+        Bob completed his PhD at Stanford University in 2020.
+        He leads a team of five engineers working on AI-powered recommendation systems.
+        """ * 5
+        await memory.retain_async(
+            bank_id=bank_id,
+            content=content_bob,
+            context="doc2",
+            request_context=request_context,
+        )
+
+        # Document 3: Long content (large chunks)
+        content_charlie = """
+        Charlie is the CTO of a growing AI company focused on healthcare applications.
+        He has over 15 years of experience in software architecture and distributed systems.
+        Charlie's team builds machine learning models for medical image analysis and diagnosis.
+        The company recently raised $50 million in Series B funding.
+        They have partnerships with major hospitals in the United States and Europe.
+        Charlie holds several patents in medical imaging and deep learning.
+        """ * 20
+        await memory.retain_async(
+            bank_id=bank_id,
+            content=content_charlie,
+            context="doc3",
+            request_context=request_context,
+        )
+
+        # Recall with modest chunk token budget
+        result = await memory.recall_async(
+            bank_id=bank_id,
+            query="Alice Bob Charlie",
+            max_tokens=0,  # No facts, only chunks
+            include_chunks=True,
+            max_chunk_tokens=1000,  # Limited chunk budget
+            budget=Budget.MID,
+            request_context=request_context,
+        )
+
+        assert len(result.results) == 0, "Should return 0 facts with max_tokens=0"
+        assert result.chunks is not None, "Should include chunks"
+
+        # Verify we got chunks and respected the token budget
+        if len(result.chunks) > 0:
+            # Count total tokens (approximate)
+            total_chunk_chars = sum(len(chunk.chunk_text) for chunk in result.chunks.values())
+            # Very rough estimate: 1 token ≈ 4 characters
+            estimated_tokens = total_chunk_chars // 4
+
+            # Should be reasonably close to budget (within 2x due to estimation and batching)
+            assert estimated_tokens <= 1000 * 2, f"Should respect chunk token budget (got ~{estimated_tokens} tokens)"
+
+    finally:
+        # Cleanup
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_recall_chunks_ordering_by_relevance(memory, request_context):
+    """
+    Test that chunks are returned in order of fact relevance.
+
+    Chunks should be ordered based on the top-scored (reranked) results,
+    not in document order or random order.
+    """
+    bank_id = "test-chunks-ordering"
+
+    try:
+
+        # Retain content with different relevance to query
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="The Python programming language is widely used for machine learning and data science applications.",
+            context="topic: Python",
+            request_context=request_context,
+        )
+
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="JavaScript is commonly used for web development and frontend applications.",
+            context="topic: JavaScript",
+            request_context=request_context,
+        )
+
+        await memory.retain_async(
+            bank_id=bank_id,
+            content="Python's scikit-learn library is excellent for traditional machine learning tasks and model training.",
+            context="topic: Python ML",
+            request_context=request_context,
+        )
+
+        # Query specifically about Python - should rank Python facts higher
+        result = await memory.recall_async(
+            bank_id=bank_id,
+            query="Python machine learning",
+            max_tokens=0,  # No facts
+            include_chunks=True,
+            max_chunk_tokens=5000,  # Enough for all chunks
+            budget=Budget.HIGH,  # Use high budget for better recall
+            request_context=request_context,
+        )
+
+        assert len(result.results) == 0, "Should return 0 facts with max_tokens=0"
+        assert result.chunks is not None, "Should include chunks"
+
+        # We should get chunks, and they should be ordered by relevance
+        # The exact ordering depends on the reranker, but we should have chunks
+        assert len(result.chunks) > 0, "Should return chunks from relevant facts"
+
+        # Verify chunks contain relevant content
+        all_chunk_text = " ".join(chunk.chunk_text for chunk in result.chunks.values())
+        # At least some chunks should mention Python (higher relevance)
+        # This is a soft check since exact ordering depends on scoring
+        assert "Python" in all_chunk_text or "python" in all_chunk_text.lower(), \
+            "Chunks should include content about Python (relevant to query)"
+
+    finally:
+        # Cleanup
+        await memory.delete_bank(bank_id, request_context=request_context)
+
+
+@pytest.mark.asyncio
+async def test_recall_chunks_without_include_flag(memory, request_context):
+    """
+    Test that chunks are NOT returned when include_chunks=False (default).
+
+    This ensures backward compatibility - chunks are only fetched when explicitly requested.
+    """
+    bank_id = "test-chunks-no-include"
+
+    try:
+
+        # Retain content
+        test_content = """
+        Sarah is a product manager at a fintech company in New York.
+        She specializes in user experience design and agile methodologies.
+        Sarah graduated from MIT with a degree in computer science.
+        She has led the development of three successful mobile banking applications.
+        """
+        await memory.retain_async(
+            bank_id=bank_id,
+            content=test_content,
+            request_context=request_context,
+        )
+
+        # Recall without include_chunks flag (default is False)
+        result = await memory.recall_async(
+            bank_id=bank_id,
+            query="Sarah product manager",
+            max_tokens=4096,
+            request_context=request_context,
+            # include_chunks=False is the default
+        )
+
+        # Should have facts but no chunks
+        assert len(result.results) > 0, "Should return facts"
+        assert result.chunks is None or len(result.chunks) == 0, \
+            "Should NOT return chunks when include_chunks=False"
+
+    finally:
+        # Cleanup
+        await memory.delete_bank(bank_id, request_context=request_context)

hindsight-api/tests/test_retain.py

@@ -2093,7 +2093,7 @@ async def test_custom_extraction_mode():
     import os
     from hindsight_api import LLMConfig
     from hindsight_api.engine.retain.fact_extraction import extract_facts_from_text
-    from hindsight_api.config import clear_config_cache
+    from hindsight_api.config import clear_config_cache, _get_raw_config
 
     # Save original env vars
     original_mode = os.getenv("HINDSIGHT_API_RETAIN_EXTRACTION_MODE")
@@ -2135,7 +2135,8 @@ If the text contains both Italian and English content, extract ONLY the Italian
             event_date=datetime(2024, 1, 15, tzinfo=timezone.utc),
             context="team meeting notes",
             llm_config=llm_config,
-            agent_name="TestUser"
+            agent_name="TestUser",
+            config=_get_raw_config(),
         )
 
         logger.info(f"\nExtracted {len(facts)} facts with custom mode (Italian only):")

hindsight-cli/src/api.rs

@@ -387,6 +387,43 @@ impl ApiClient {
         })
     }
 
+    pub fn get_bank_config(
+        &self,
+        bank_id: &str,
+        _verbose: bool,
+    ) -> Result<types::BankConfigResponse> {
+        self.runtime.block_on(async {
+            let response = self.client.get_bank_config(bank_id, None).await?;
+            Ok(response.into_inner())
+        })
+    }
+
+    pub fn update_bank_config(
+        &self,
+        bank_id: &str,
+        updates: std::collections::HashMap<String, serde_json::Value>,
+        _verbose: bool,
+    ) -> Result<types::BankConfigResponse> {
+        self.runtime.block_on(async {
+            // Convert HashMap to serde_json::Map
+            let updates_map: serde_json::Map<String, serde_json::Value> = updates.into_iter().collect();
+            let request = types::BankConfigUpdate { updates: updates_map };
+            let response = self.client.update_bank_config(bank_id, None, &request).await?;
+            Ok(response.into_inner())
+        })
+    }
+
+    pub fn reset_bank_config(
+        &self,
+        bank_id: &str,
+        _verbose: bool,
+    ) -> Result<types::BankConfigResponse> {
+        self.runtime.block_on(async {
+            let response = self.client.reset_bank_config(bank_id, None).await?;
+            Ok(response.into_inner())
+        })
+    }
+
     // --- Tag Methods ---
 
     pub fn list_tags(

hindsight-cli/src/commands/bank.rs

@@ -1,4 +1,4 @@
-use anyhow::Result;
+use anyhow::{anyhow, Result};
 use crate::api::ApiClient;
 use crate::output::{self, OutputFormat};
 use crate::ui;
@@ -655,3 +655,159 @@ pub fn clear_observations(
         Err(e) => Err(e),
     }
 }
+
+pub fn config(
+    client: &ApiClient,
+    bank_id: &str,
+    overrides_only: bool,
+    verbose: bool,
+    output_format: OutputFormat,
+) -> Result<()> {
+    let spinner = if output_format == OutputFormat::Pretty {
+        Some(ui::create_spinner("Fetching bank configuration..."))
+    } else {
+        None
+    };
+
+    let response = client.get_bank_config(bank_id, verbose);
+
+    if let Some(mut sp) = spinner {
+        sp.finish();
+    }
+
+    match response {
+        Ok(result) => {
+            if output_format == OutputFormat::Pretty {
+                ui::print_success(&format!("Configuration for bank '{}'", bank_id));
+                println!();
+                if overrides_only {
+                    println!("Bank-specific overrides:");
+                    if result.overrides.is_empty() {
+                        println!("  (none - using defaults)");
+                    } else {
+                        for (key, value) in result.overrides.iter() {
+                            println!("  {}: {:?}", key, value);
+                        }
+                    }
+                } else {
+                    println!("Resolved configuration (with all overrides applied):");
+                    for (key, value) in result.config.iter() {
+                        println!("  {}: {:?}", key, value);
+                    }
+                }
+            } else {
+                if overrides_only {
+                    output::print_output(&result.overrides, output_format)?;
+                } else {
+                    output::print_output(&result, output_format)?;
+                }
+            }
+            Ok(())
+        }
+        Err(e) => Err(e),
+    }
+}
+
+pub fn set_config(
+    client: &ApiClient,
+    bank_id: &str,
+    llm_provider: Option<String>,
+    llm_model: Option<String>,
+    llm_api_key: Option<String>,
+    llm_base_url: Option<String>,
+    verbose: bool,
+    output_format: OutputFormat,
+) -> Result<()> {
+    use std::collections::HashMap;
+
+    let mut updates: HashMap<String, serde_json::Value> = HashMap::new();
+
+    if let Some(provider) = llm_provider {
+        updates.insert("llm_provider".to_string(), serde_json::Value::String(provider));
+    }
+    if let Some(model) = llm_model {
+        updates.insert("llm_model".to_string(), serde_json::Value::String(model));
+    }
+    if let Some(api_key) = llm_api_key {
+        updates.insert("llm_api_key".to_string(), serde_json::Value::String(api_key));
+    }
+    if let Some(base_url) = llm_base_url {
+        updates.insert("llm_base_url".to_string(), serde_json::Value::String(base_url));
+    }
+
+    if updates.is_empty() {
+        return Err(anyhow!("No config updates provided. Use --llm-provider, --llm-model, --llm-api-key, or --llm-base-url".to_string()));
+    }
+
+    let spinner = if output_format == OutputFormat::Pretty {
+        Some(ui::create_spinner("Updating bank configuration..."))
+    } else {
+        None
+    };
+
+    let response = client.update_bank_config(bank_id, updates, verbose);
+
+    if let Some(mut sp) = spinner {
+        sp.finish();
+    }
+
+    match response {
+        Ok(result) => {
+            if output_format == OutputFormat::Pretty {
+                ui::print_success(&format!("Configuration updated for bank '{}'", bank_id));
+                println!("\nUpdated overrides:");
+                for (key, value) in result.overrides.iter() {
+                    println!("  {}: {:?}", key, value);
+                }
+            } else {
+                output::print_output(&result, output_format)?;
+            }
+            Ok(())
+        }
+        Err(e) => Err(e),
+    }
+}
+
+pub fn reset_config(
+    client: &ApiClient,
+    bank_id: &str,
+    yes: bool,
+    verbose: bool,
+    output_format: OutputFormat,
+) -> Result<()> {
+    if !yes && output_format == OutputFormat::Pretty {
+        let confirmed = ui::prompt_confirmation(&format!(
+            "Reset all configuration overrides for bank '{}'?",
+            bank_id
+        ))?;
+
+        if !confirmed {
+            ui::print_info("Operation cancelled");
+            return Ok(());
+        }
+    }
+
+    let spinner = if output_format == OutputFormat::Pretty {
+        Some(ui::create_spinner("Resetting bank configuration..."))
+    } else {
+        None
+    };
+
+    let response = client.reset_bank_config(bank_id, verbose);
+
+    if let Some(mut sp) = spinner {
+        sp.finish();
+    }
+
+    match response {
+        Ok(result) => {
+            if output_format == OutputFormat::Pretty {
+                ui::print_success(&format!("Configuration reset to defaults for bank '{}'", bank_id));
+            } else {
+                output::print_output(&result, output_format)?;
+            }
+            Ok(())
+        }
+        Err(e) => Err(e),
+    }
+}

hindsight-cli/src/errors.rs

@@ -58,8 +58,22 @@ fn format_error_message(err: &anyhow::Error, api_url: &str) -> String {
         );
     }
 
-    // 404 Not Found
+    // 404 Not Found - check for disabled features first
     if err_str.contains("404") {
+        if err_str.contains("Bank configuration API is disabled") {
+            return format!(
+                "{} {}\n\n{}\n  {}\n\n{}\n  {}\n\n{}\n  {}",
+                "✗".bright_red().bold(),
+                "Bank configuration API is disabled".bright_red().bold(),
+                "API URL:".bright_yellow(),
+                api_url.bright_white(),
+                "This feature is disabled by default for security.".bright_yellow(),
+                "To enable, set HINDSIGHT_API_ENABLE_BANK_CONFIG_API=true on the API server".bright_white(),
+                "Note:".bright_cyan(),
+                "This allows per-bank LLM configuration overrides via API".bright_white()
+            );
+        }
+
         return format!(
             "{} {}\n\n{}\n  {}\n\n{}\n  • {}\n  • {}\n\n{}\n  {}",
             "✗".bright_red().bold(),
@@ -74,8 +88,8 @@ fn format_error_message(err: &anyhow::Error, api_url: &str) -> String {
         );
     }
 
-    // 401/403 Authentication
-    if err_str.contains("401") || err_str.contains("403") {
+    // 401 Authentication failed
+    if err_str.contains("401") {
         return format!(
             "{} {}\n\n{}\n  {}\n\n{}\n  • {}\n  • {}\n\n{}\n  {}",
             "✗".bright_red().bold(),
@@ -90,6 +104,22 @@ fn format_error_message(err: &anyhow::Error, api_url: &str) -> String {
         );
     }
 
+    // 403 Forbidden
+    if err_str.contains("403") {
+        return format!(
+            "{} {}\n\n{}\n  {}\n\n{}\n  • {}\n  • {}\n\n{}\n  {}",
+            "✗".bright_red().bold(),
+            "Permission denied (403)".bright_red().bold(),
+            "API URL:".bright_yellow(),
+            api_url.bright_white(),
+            "Possible causes:".bright_yellow(),
+            "This operation is not allowed".bright_white(),
+            "The feature may be disabled on the server".bright_white(),
+            "Try:".bright_green(),
+            "Check server configuration or contact your administrator".bright_white()
+        );
+    }
+
     // 500 Server Error
     if err_str.contains("500") || err_str.contains("502") || err_str.contains("503") {
         return format!(

hindsight-cli/src/main.rs

@@ -279,6 +279,48 @@ enum BankCommands {
         #[arg(short = 'y', long)]
         yes: bool,
     },
+
+    /// Get bank configuration (hierarchical overrides)
+    Config {
+        /// Bank ID
+        bank_id: String,
+
+        /// Show only bank-specific overrides (not full resolved config)
+        #[arg(long)]
+        overrides_only: bool,
+    },
+
+    /// Update bank configuration (set hierarchical overrides)
+    SetConfig {
+        /// Bank ID
+        bank_id: String,
+
+        /// LLM provider override
+        #[arg(long)]
+        llm_provider: Option<String>,
+
+        /// LLM model override
+        #[arg(long)]
+        llm_model: Option<String>,
+
+        /// LLM API key override
+        #[arg(long)]
+        llm_api_key: Option<String>,
+
+        /// LLM base URL override
+        #[arg(long)]
+        llm_base_url: Option<String>,
+    },
+
+    /// Reset bank configuration to defaults (remove all overrides)
+    ResetConfig {
+        /// Bank ID
+        bank_id: String,
+
+        /// Skip confirmation prompt
+        #[arg(short = 'y', long)]
+        yes: bool,
+    },
 }
 
 #[derive(Subcommand)]
@@ -776,6 +818,15 @@ fn run() -> Result<()> {
             BankCommands::ClearObservations { bank_id, yes } => {
                 commands::bank::clear_observations(&client, &bank_id, yes, verbose, output_format)
             }
+            BankCommands::Config { bank_id, overrides_only } => {
+                commands::bank::config(&client, &bank_id, overrides_only, verbose, output_format)
+            }
+            BankCommands::SetConfig { bank_id, llm_provider, llm_model, llm_api_key, llm_base_url } => {
+                commands::bank::set_config(&client, &bank_id, llm_provider, llm_model, llm_api_key, llm_base_url, verbose, output_format)
+            }
+            BankCommands::ResetConfig { bank_id, yes } => {
+                commands::bank::reset_config(&client, &bank_id, yes, verbose, output_format)
+            }
         },
 
         // Memory commands

hindsight-clients/python/.openapi-generator/FILES

@@ -16,6 +16,8 @@ hindsight_client_api/models/__init__.py
 hindsight_client_api/models/add_background_request.py
 hindsight_client_api/models/async_operation_submit_response.py
 hindsight_client_api/models/background_response.py
+hindsight_client_api/models/bank_config_response.py
+hindsight_client_api/models/bank_config_update.py
 hindsight_client_api/models/bank_list_item.py
 hindsight_client_api/models/bank_list_response.py
 hindsight_client_api/models/bank_profile_response.py

hindsight-clients/python/hindsight_client_api/__init__.py

@@ -41,6 +41,8 @@ from hindsight_client_api.exceptions import ApiException
 from hindsight_client_api.models.add_background_request import AddBackgroundRequest
 from hindsight_client_api.models.async_operation_submit_response import AsyncOperationSubmitResponse
 from hindsight_client_api.models.background_response import BackgroundResponse
+from hindsight_client_api.models.bank_config_response import BankConfigResponse
+from hindsight_client_api.models.bank_config_update import BankConfigUpdate
 from hindsight_client_api.models.bank_list_item import BankListItem
 from hindsight_client_api.models.bank_list_response import BankListResponse
 from hindsight_client_api.models.bank_profile_response import BankProfileResponse

hindsight-clients/python/hindsight_client_api/api/banks_api.py

@@ -20,6 +20,8 @@ from pydantic import StrictStr
 from typing import Optional
 from hindsight_client_api.models.add_background_request import AddBackgroundRequest
 from hindsight_client_api.models.background_response import BackgroundResponse
+from hindsight_client_api.models.bank_config_response import BankConfigResponse
+from hindsight_client_api.models.bank_config_update import BankConfigUpdate
 from hindsight_client_api.models.bank_list_response import BankListResponse
 from hindsight_client_api.models.bank_profile_response import BankProfileResponse
 from hindsight_client_api.models.bank_stats_response import BankStatsResponse
@@ -1495,6 +1497,284 @@ class BanksApi:
 
 
 
+    @validate_call
+    async def get_bank_config(
+        self,
+        bank_id: StrictStr,
+        authorization: Optional[StrictStr] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> BankConfigResponse:
+        """Get bank configuration
+
+        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.
+
+        :param bank_id: (required)
+        :type bank_id: str
+        :param authorization:
+        :type authorization: str
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._get_bank_config_serialize(
+            bank_id=bank_id,
+            authorization=authorization,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "BankConfigResponse",
+            '422': "HTTPValidationError",
+        }
+        response_data = await self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        await response_data.read()
+        return self.api_client.response_deserialize(
+            response_data=response_data,
+            response_types_map=_response_types_map,
+        ).data
+
+
+    @validate_call
+    async def get_bank_config_with_http_info(
+        self,
+        bank_id: StrictStr,
+        authorization: Optional[StrictStr] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> ApiResponse[BankConfigResponse]:
+        """Get bank configuration
+
+        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.
+
+        :param bank_id: (required)
+        :type bank_id: str
+        :param authorization:
+        :type authorization: str
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._get_bank_config_serialize(
+            bank_id=bank_id,
+            authorization=authorization,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "BankConfigResponse",
+            '422': "HTTPValidationError",
+        }
+        response_data = await self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        await response_data.read()
+        return self.api_client.response_deserialize(
+            response_data=response_data,
+            response_types_map=_response_types_map,
+        )
+
+
+    @validate_call
+    async def get_bank_config_without_preload_content(
+        self,
+        bank_id: StrictStr,
+        authorization: Optional[StrictStr] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> RESTResponseType:
+        """Get bank configuration
+
+        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.
+
+        :param bank_id: (required)
+        :type bank_id: str
+        :param authorization:
+        :type authorization: str
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._get_bank_config_serialize(
+            bank_id=bank_id,
+            authorization=authorization,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "BankConfigResponse",
+            '422': "HTTPValidationError",
+        }
+        response_data = await self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        return response_data.response
+
+
+    def _get_bank_config_serialize(
+        self,
+        bank_id,
+        authorization,
+        _request_auth,
+        _content_type,
+        _headers,
+        _host_index,
+    ) -> RequestSerialized:
+
+        _host = None
+
+        _collection_formats: Dict[str, str] = {
+        }
+
+        _path_params: Dict[str, str] = {}
+        _query_params: List[Tuple[str, str]] = []
+        _header_params: Dict[str, Optional[str]] = _headers or {}
+        _form_params: List[Tuple[str, str]] = []
+        _files: Dict[
+            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
+        ] = {}
+        _body_params: Optional[bytes] = None
+
+        # process the path parameters
+        if bank_id is not None:
+            _path_params['bank_id'] = bank_id
+        # process the query parameters
+        # process the header parameters
+        if authorization is not None:
+            _header_params['authorization'] = authorization
+        # process the form parameters
+        # process the body parameter
+
+
+        # set the HTTP header `Accept`
+        if 'Accept' not in _header_params:
+            _header_params['Accept'] = self.api_client.select_header_accept(
+                [
+                    'application/json'
+                ]
+            )
+
+
+        # authentication setting
+        _auth_settings: List[str] = [
+        ]
+
+        return self.api_client.param_serialize(
+            method='GET',
+            resource_path='/v1/default/banks/{bank_id}/config',
+            path_params=_path_params,
+            query_params=_query_params,
+            header_params=_header_params,
+            body=_body_params,
+            post_params=_form_params,
+            files=_files,
+            auth_settings=_auth_settings,
+            collection_formats=_collection_formats,
+            _host=_host,
+            _request_auth=_request_auth
+        )
+
+
+
+
     @validate_call
     async def get_bank_profile(
         self,
@@ -2036,6 +2316,284 @@ class BanksApi:
 
 
 
+    @validate_call
+    async def reset_bank_config(
+        self,
+        bank_id: StrictStr,
+        authorization: Optional[StrictStr] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> BankConfigResponse:
+        """Reset bank configuration
+
+        Reset bank configuration to defaults by removing all bank-specific overrides. The bank will then use global and tenant-level configuration only.
+
+        :param bank_id: (required)
+        :type bank_id: str
+        :param authorization:
+        :type authorization: str
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._reset_bank_config_serialize(
+            bank_id=bank_id,
+            authorization=authorization,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "BankConfigResponse",
+            '422': "HTTPValidationError",
+        }
+        response_data = await self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        await response_data.read()
+        return self.api_client.response_deserialize(
+            response_data=response_data,
+            response_types_map=_response_types_map,
+        ).data
+
+
+    @validate_call
+    async def reset_bank_config_with_http_info(
+        self,
+        bank_id: StrictStr,
+        authorization: Optional[StrictStr] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> ApiResponse[BankConfigResponse]:
+        """Reset bank configuration
+
+        Reset bank configuration to defaults by removing all bank-specific overrides. The bank will then use global and tenant-level configuration only.
+
+        :param bank_id: (required)
+        :type bank_id: str
+        :param authorization:
+        :type authorization: str
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._reset_bank_config_serialize(
+            bank_id=bank_id,
+            authorization=authorization,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "BankConfigResponse",
+            '422': "HTTPValidationError",
+        }
+        response_data = await self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        await response_data.read()
+        return self.api_client.response_deserialize(
+            response_data=response_data,
+            response_types_map=_response_types_map,
+        )
+
+
+    @validate_call
+    async def reset_bank_config_without_preload_content(
+        self,
+        bank_id: StrictStr,
+        authorization: Optional[StrictStr] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> RESTResponseType:
+        """Reset bank configuration
+
+        Reset bank configuration to defaults by removing all bank-specific overrides. The bank will then use global and tenant-level configuration only.
+
+        :param bank_id: (required)
+        :type bank_id: str
+        :param authorization:
+        :type authorization: str
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._reset_bank_config_serialize(
+            bank_id=bank_id,
+            authorization=authorization,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "BankConfigResponse",
+            '422': "HTTPValidationError",
+        }
+        response_data = await self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        return response_data.response
+
+
+    def _reset_bank_config_serialize(
+        self,
+        bank_id,
+        authorization,
+        _request_auth,
+        _content_type,
+        _headers,
+        _host_index,
+    ) -> RequestSerialized:
+
+        _host = None
+
+        _collection_formats: Dict[str, str] = {
+        }
+
+        _path_params: Dict[str, str] = {}
+        _query_params: List[Tuple[str, str]] = []
+        _header_params: Dict[str, Optional[str]] = _headers or {}
+        _form_params: List[Tuple[str, str]] = []
+        _files: Dict[
+            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
+        ] = {}
+        _body_params: Optional[bytes] = None
+
+        # process the path parameters
+        if bank_id is not None:
+            _path_params['bank_id'] = bank_id
+        # process the query parameters
+        # process the header parameters
+        if authorization is not None:
+            _header_params['authorization'] = authorization
+        # process the form parameters
+        # process the body parameter
+
+
+        # set the HTTP header `Accept`
+        if 'Accept' not in _header_params:
+            _header_params['Accept'] = self.api_client.select_header_accept(
+                [
+                    'application/json'
+                ]
+            )
+
+
+        # authentication setting
+        _auth_settings: List[str] = [
+        ]
+
+        return self.api_client.param_serialize(
+            method='DELETE',
+            resource_path='/v1/default/banks/{bank_id}/config',
+            path_params=_path_params,
+            query_params=_query_params,
+            header_params=_header_params,
+            body=_body_params,
+            post_params=_form_params,
+            files=_files,
+            auth_settings=_auth_settings,
+            collection_formats=_collection_formats,
+            _host=_host,
+            _request_auth=_request_auth
+        )
+
+
+
+
     @validate_call
     async def trigger_consolidation(
         self,
@@ -2620,6 +3178,312 @@ class BanksApi:
 
 
 
+    @validate_call
+    async def update_bank_config(
+        self,
+        bank_id: StrictStr,
+        bank_config_update: BankConfigUpdate,
+        authorization: Optional[StrictStr] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> BankConfigResponse:
+        """Update bank configuration
+
+        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).
+
+        :param bank_id: (required)
+        :type bank_id: str
+        :param bank_config_update: (required)
+        :type bank_config_update: BankConfigUpdate
+        :param authorization:
+        :type authorization: str
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._update_bank_config_serialize(
+            bank_id=bank_id,
+            bank_config_update=bank_config_update,
+            authorization=authorization,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "BankConfigResponse",
+            '422': "HTTPValidationError",
+        }
+        response_data = await self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        await response_data.read()
+        return self.api_client.response_deserialize(
+            response_data=response_data,
+            response_types_map=_response_types_map,
+        ).data
+
+
+    @validate_call
+    async def update_bank_config_with_http_info(
+        self,
+        bank_id: StrictStr,
+        bank_config_update: BankConfigUpdate,
+        authorization: Optional[StrictStr] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> ApiResponse[BankConfigResponse]:
+        """Update bank configuration
+
+        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).
+
+        :param bank_id: (required)
+        :type bank_id: str
+        :param bank_config_update: (required)
+        :type bank_config_update: BankConfigUpdate
+        :param authorization:
+        :type authorization: str
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._update_bank_config_serialize(
+            bank_id=bank_id,
+            bank_config_update=bank_config_update,
+            authorization=authorization,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "BankConfigResponse",
+            '422': "HTTPValidationError",
+        }
+        response_data = await self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        await response_data.read()
+        return self.api_client.response_deserialize(
+            response_data=response_data,
+            response_types_map=_response_types_map,
+        )
+
+
+    @validate_call
+    async def update_bank_config_without_preload_content(
+        self,
+        bank_id: StrictStr,
+        bank_config_update: BankConfigUpdate,
+        authorization: Optional[StrictStr] = None,
+        _request_timeout: Union[
+            None,
+            Annotated[StrictFloat, Field(gt=0)],
+            Tuple[
+                Annotated[StrictFloat, Field(gt=0)],
+                Annotated[StrictFloat, Field(gt=0)]
+            ]
+        ] = None,
+        _request_auth: Optional[Dict[StrictStr, Any]] = None,
+        _content_type: Optional[StrictStr] = None,
+        _headers: Optional[Dict[StrictStr, Any]] = None,
+        _host_index: Annotated[StrictInt, Field(ge=0, le=0)] = 0,
+    ) -> RESTResponseType:
+        """Update bank configuration
+
+        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).
+
+        :param bank_id: (required)
+        :type bank_id: str
+        :param bank_config_update: (required)
+        :type bank_config_update: BankConfigUpdate
+        :param authorization:
+        :type authorization: str
+        :param _request_timeout: timeout setting for this request. If one
+                                 number provided, it will be total request
+                                 timeout. It can also be a pair (tuple) of
+                                 (connection, read) timeouts.
+        :type _request_timeout: int, tuple(int, int), optional
+        :param _request_auth: set to override the auth_settings for an a single
+                              request; this effectively ignores the
+                              authentication in the spec for a single request.
+        :type _request_auth: dict, optional
+        :param _content_type: force content-type for the request.
+        :type _content_type: str, Optional
+        :param _headers: set to override the headers for a single
+                         request; this effectively ignores the headers
+                         in the spec for a single request.
+        :type _headers: dict, optional
+        :param _host_index: set to override the host_index for a single
+                            request; this effectively ignores the host_index
+                            in the spec for a single request.
+        :type _host_index: int, optional
+        :return: Returns the result object.
+        """ # noqa: E501
+
+        _param = self._update_bank_config_serialize(
+            bank_id=bank_id,
+            bank_config_update=bank_config_update,
+            authorization=authorization,
+            _request_auth=_request_auth,
+            _content_type=_content_type,
+            _headers=_headers,
+            _host_index=_host_index
+        )
+
+        _response_types_map: Dict[str, Optional[str]] = {
+            '200': "BankConfigResponse",
+            '422': "HTTPValidationError",
+        }
+        response_data = await self.api_client.call_api(
+            *_param,
+            _request_timeout=_request_timeout
+        )
+        return response_data.response
+
+
+    def _update_bank_config_serialize(
+        self,
+        bank_id,
+        bank_config_update,
+        authorization,
+        _request_auth,
+        _content_type,
+        _headers,
+        _host_index,
+    ) -> RequestSerialized:
+
+        _host = None
+
+        _collection_formats: Dict[str, str] = {
+        }
+
+        _path_params: Dict[str, str] = {}
+        _query_params: List[Tuple[str, str]] = []
+        _header_params: Dict[str, Optional[str]] = _headers or {}
+        _form_params: List[Tuple[str, str]] = []
+        _files: Dict[
+            str, Union[str, bytes, List[str], List[bytes], List[Tuple[str, bytes]]]
+        ] = {}
+        _body_params: Optional[bytes] = None
+
+        # process the path parameters
+        if bank_id is not None:
+            _path_params['bank_id'] = bank_id
+        # process the query parameters
+        # process the header parameters
+        if authorization is not None:
+            _header_params['authorization'] = authorization
+        # process the form parameters
+        # process the body parameter
+        if bank_config_update is not None:
+            _body_params = bank_config_update
+
+
+        # set the HTTP header `Accept`
+        if 'Accept' not in _header_params:
+            _header_params['Accept'] = self.api_client.select_header_accept(
+                [
+                    'application/json'
+                ]
+            )
+
+        # set the HTTP header `Content-Type`
+        if _content_type:
+            _header_params['Content-Type'] = _content_type
+        else:
+            _default_content_type = (
+                self.api_client.select_header_content_type(
+                    [
+                        'application/json'
+                    ]
+                )
+            )
+            if _default_content_type is not None:
+                _header_params['Content-Type'] = _default_content_type
+
+        # authentication setting
+        _auth_settings: List[str] = [
+        ]
+
+        return self.api_client.param_serialize(
+            method='PATCH',
+            resource_path='/v1/default/banks/{bank_id}/config',
+            path_params=_path_params,
+            query_params=_query_params,
+            header_params=_header_params,
+            body=_body_params,
+            post_params=_form_params,
+            files=_files,
+            auth_settings=_auth_settings,
+            collection_formats=_collection_formats,
+            _host=_host,
+            _request_auth=_request_auth
+        )
+
+
+
+
     @validate_call
     async def update_bank_disposition(
         self,

hindsight-clients/python/hindsight_client_api/models/__init__.py

@@ -17,6 +17,8 @@
 from hindsight_client_api.models.add_background_request import AddBackgroundRequest
 from hindsight_client_api.models.async_operation_submit_response import AsyncOperationSubmitResponse
 from hindsight_client_api.models.background_response import BackgroundResponse
+from hindsight_client_api.models.bank_config_response import BankConfigResponse
+from hindsight_client_api.models.bank_config_update import BankConfigUpdate
 from hindsight_client_api.models.bank_list_item import BankListItem
 from hindsight_client_api.models.bank_list_response import BankListResponse
 from hindsight_client_api.models.bank_profile_response import BankProfileResponse

hindsight-clients/python/hindsight_client_api/models/bank_config_response.py

@@ -0,0 +1,91 @@
+# coding: utf-8
+
+"""
+    Hindsight HTTP API
+
+    HTTP API for Hindsight
+
+    The version of the OpenAPI document: 0.4.10
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from pydantic import BaseModel, ConfigDict, Field, StrictStr
+from typing import Any, ClassVar, Dict, List
+from typing import Optional, Set
+from typing_extensions import Self
+
+class BankConfigResponse(BaseModel):
+    """
+    Response model for bank configuration.
+    """ # noqa: E501
+    bank_id: StrictStr = 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)")
+    __properties: ClassVar[List[str]] = ["bank_id", "config", "overrides"]
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Optional[Self]:
+        """Create an instance of BankConfigResponse from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        """
+        excluded_fields: Set[str] = set([
+        ])
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
+        """Create an instance of BankConfigResponse from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate({
+            "bank_id": obj.get("bank_id"),
+            "config": obj.get("config"),
+            "overrides": obj.get("overrides")
+        })
+        return _obj
+
+

hindsight-clients/python/hindsight_client_api/models/bank_config_update.py

@@ -0,0 +1,87 @@
+# coding: utf-8
+
+"""
+    Hindsight HTTP API
+
+    HTTP API for Hindsight
+
+    The version of the OpenAPI document: 0.4.10
+    Generated by OpenAPI Generator (https://openapi-generator.tech)
+
+    Do not edit the class manually.
+"""  # noqa: E501
+
+
+from __future__ import annotations
+import pprint
+import re  # noqa: F401
+import json
+
+from pydantic import BaseModel, ConfigDict, Field
+from typing import Any, ClassVar, Dict, List
+from typing import Optional, Set
+from typing_extensions import Self
+
+class BankConfigUpdate(BaseModel):
+    """
+    Request model for updating bank configuration.
+    """ # noqa: E501
+    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.")
+    __properties: ClassVar[List[str]] = ["updates"]
+
+    model_config = ConfigDict(
+        populate_by_name=True,
+        validate_assignment=True,
+        protected_namespaces=(),
+    )
+
+
+    def to_str(self) -> str:
+        """Returns the string representation of the model using alias"""
+        return pprint.pformat(self.model_dump(by_alias=True))
+
+    def to_json(self) -> str:
+        """Returns the JSON representation of the model using alias"""
+        # TODO: pydantic v2: use .model_dump_json(by_alias=True, exclude_unset=True) instead
+        return json.dumps(self.to_dict())
+
+    @classmethod
+    def from_json(cls, json_str: str) -> Optional[Self]:
+        """Create an instance of BankConfigUpdate from a JSON string"""
+        return cls.from_dict(json.loads(json_str))
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the dictionary representation of the model using alias.
+
+        This has the following differences from calling pydantic's
+        `self.model_dump(by_alias=True)`:
+
+        * `None` is only added to the output dict for nullable fields that
+          were set at model initialization. Other fields with value `None`
+          are ignored.
+        """
+        excluded_fields: Set[str] = set([
+        ])
+
+        _dict = self.model_dump(
+            by_alias=True,
+            exclude=excluded_fields,
+            exclude_none=True,
+        )
+        return _dict
+
+    @classmethod
+    def from_dict(cls, obj: Optional[Dict[str, Any]]) -> Optional[Self]:
+        """Create an instance of BankConfigUpdate from a dict"""
+        if obj is None:
+            return None
+
+        if not isinstance(obj, dict):
+            return cls.model_validate(obj)
+
+        _obj = cls.model_validate({
+            "updates": obj.get("updates")
+        })
+        return _obj
+
+

hindsight-clients/python/hindsight_client_api/models/features_info.py

@@ -29,7 +29,8 @@ class FeaturesInfo(BaseModel):
     observations: StrictBool = Field(description="Whether observations (auto-consolidation) are enabled")
     mcp: StrictBool = Field(description="Whether MCP (Model Context Protocol) server is enabled")
     worker: StrictBool = Field(description="Whether the background worker is enabled")
-    __properties: ClassVar[List[str]] = ["observations", "mcp", "worker"]
+    bank_config_api: StrictBool = Field(description="Whether per-bank configuration API is enabled")
+    __properties: ClassVar[List[str]] = ["observations", "mcp", "worker", "bank_config_api"]
 
     model_config = ConfigDict(
         populate_by_name=True,
@@ -84,7 +85,8 @@ class FeaturesInfo(BaseModel):
         _obj = cls.model_validate({
             "observations": obj.get("observations"),
             "mcp": obj.get("mcp"),
-            "worker": obj.get("worker")
+            "worker": obj.get("worker"),
+            "bank_config_api": obj.get("bank_config_api")
         })
         return _obj
 

hindsight-clients/typescript/generated/sdk.gen.ts

@@ -39,6 +39,9 @@ import type {
   GetAgentStatsData,
   GetAgentStatsErrors,
   GetAgentStatsResponses,
+  GetBankConfigData,
+  GetBankConfigErrors,
+  GetBankConfigResponses,
   GetBankProfileData,
   GetBankProfileErrors,
   GetBankProfileResponses,
@@ -108,12 +111,18 @@ import type {
   RegenerateEntityObservationsData,
   RegenerateEntityObservationsErrors,
   RegenerateEntityObservationsResponses,
+  ResetBankConfigData,
+  ResetBankConfigErrors,
+  ResetBankConfigResponses,
   RetainMemoriesData,
   RetainMemoriesErrors,
   RetainMemoriesResponses,
   TriggerConsolidationData,
   TriggerConsolidationErrors,
   TriggerConsolidationResponses,
+  UpdateBankConfigData,
+  UpdateBankConfigErrors,
+  UpdateBankConfigResponses,
   UpdateBankData,
   UpdateBankDispositionData,
   UpdateBankDispositionErrors,
@@ -808,6 +817,55 @@ export const clearObservations = <ThrowOnError extends boolean = false>(
     ThrowOnError
   >({ url: "/v1/default/banks/{bank_id}/observations", ...options });
 
+/**
+ * Reset bank configuration
+ *
+ * Reset bank configuration to defaults by removing all bank-specific overrides. The bank will then use global and tenant-level configuration only.
+ */
+export const resetBankConfig = <ThrowOnError extends boolean = false>(
+  options: Options<ResetBankConfigData, ThrowOnError>,
+) =>
+  (options.client ?? client).delete<
+    ResetBankConfigResponses,
+    ResetBankConfigErrors,
+    ThrowOnError
+  >({ url: "/v1/default/banks/{bank_id}/config", ...options });
+
+/**
+ * Get bank configuration
+ *
+ * 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.
+ */
+export const getBankConfig = <ThrowOnError extends boolean = false>(
+  options: Options<GetBankConfigData, ThrowOnError>,
+) =>
+  (options.client ?? client).get<
+    GetBankConfigResponses,
+    GetBankConfigErrors,
+    ThrowOnError
+  >({ url: "/v1/default/banks/{bank_id}/config", ...options });
+
+/**
+ * Update bank configuration
+ *
+ * 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).
+ */
+export const updateBankConfig = <ThrowOnError extends boolean = false>(
+  options: Options<UpdateBankConfigData, ThrowOnError>,
+) =>
+  (options.client ?? client).patch<
+    UpdateBankConfigResponses,
+    UpdateBankConfigErrors,
+    ThrowOnError
+  >({
+    url: "/v1/default/banks/{bank_id}/config",
+    ...options,
+    headers: {
+      "Content-Type": "application/json",
+      ...options.headers,
+    },
+  });
+
 /**
  * Trigger consolidation
  *

hindsight-clients/typescript/generated/types.gen.ts

@@ -59,6 +59,52 @@ export type BackgroundResponse = {
   disposition?: DispositionTraits | null;
 };
 
+/**
+ * BankConfigResponse
+ *
+ * Response model for bank configuration.
+ */
+export type BankConfigResponse = {
+  /**
+   * Bank Id
+   *
+   * Bank identifier
+   */
+  bank_id: string;
+  /**
+   * Config
+   *
+   * Fully resolved configuration with all hierarchical overrides applied (Python field names)
+   */
+  config: {
+    [key: string]: unknown;
+  };
+  /**
+   * Overrides
+   *
+   * Bank-specific configuration overrides only (Python field names)
+   */
+  overrides: {
+    [key: string]: unknown;
+  };
+};
+
+/**
+ * BankConfigUpdate
+ *
+ * Request model for updating bank configuration.
+ */
+export type BankConfigUpdate = {
+  /**
+   * Updates
+   *
+   * 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.
+   */
+  updates: {
+    [key: string]: unknown;
+  };
+};
+
 /**
  * BankListItem
  *
@@ -816,6 +862,12 @@ export type FeaturesInfo = {
    * Whether the background worker is enabled
    */
   worker: boolean;
+  /**
+   * Bank Config Api
+   *
+   * Whether per-bank configuration API is enabled
+   */
+  bank_config_api: boolean;
 };
 
 /**
@@ -3426,6 +3478,119 @@ export type ClearObservationsResponses = {
 export type ClearObservationsResponse =
   ClearObservationsResponses[keyof ClearObservationsResponses];
 
+export type ResetBankConfigData = {
+  body?: never;
+  headers?: {
+    /**
+     * Authorization
+     */
+    authorization?: string | null;
+  };
+  path: {
+    /**
+     * Bank Id
+     */
+    bank_id: string;
+  };
+  query?: never;
+  url: "/v1/default/banks/{bank_id}/config";
+};
+
+export type ResetBankConfigErrors = {
+  /**
+   * Validation Error
+   */
+  422: HttpValidationError;
+};
+
+export type ResetBankConfigError =
+  ResetBankConfigErrors[keyof ResetBankConfigErrors];
+
+export type ResetBankConfigResponses = {
+  /**
+   * Successful Response
+   */
+  200: BankConfigResponse;
+};
+
+export type ResetBankConfigResponse =
+  ResetBankConfigResponses[keyof ResetBankConfigResponses];
+
+export type GetBankConfigData = {
+  body?: never;
+  headers?: {
+    /**
+     * Authorization
+     */
+    authorization?: string | null;
+  };
+  path: {
+    /**
+     * Bank Id
+     */
+    bank_id: string;
+  };
+  query?: never;
+  url: "/v1/default/banks/{bank_id}/config";
+};
+
+export type GetBankConfigErrors = {
+  /**
+   * Validation Error
+   */
+  422: HttpValidationError;
+};
+
+export type GetBankConfigError = GetBankConfigErrors[keyof GetBankConfigErrors];
+
+export type GetBankConfigResponses = {
+  /**
+   * Successful Response
+   */
+  200: BankConfigResponse;
+};
+
+export type GetBankConfigResponse =
+  GetBankConfigResponses[keyof GetBankConfigResponses];
+
+export type UpdateBankConfigData = {
+  body: BankConfigUpdate;
+  headers?: {
+    /**
+     * Authorization
+     */
+    authorization?: string | null;
+  };
+  path: {
+    /**
+     * Bank Id
+     */
+    bank_id: string;
+  };
+  query?: never;
+  url: "/v1/default/banks/{bank_id}/config";
+};
+
+export type UpdateBankConfigErrors = {
+  /**
+   * Validation Error
+   */
+  422: HttpValidationError;
+};
+
+export type UpdateBankConfigError =
+  UpdateBankConfigErrors[keyof UpdateBankConfigErrors];
+
+export type UpdateBankConfigResponses = {
+  /**
+   * Successful Response
+   */
+  200: BankConfigResponse;
+};
+
+export type UpdateBankConfigResponse =
+  UpdateBankConfigResponses[keyof UpdateBankConfigResponses];
+
 export type TriggerConsolidationData = {
   body?: never;
   headers?: {

hindsight-control-plane/next.config.ts

@@ -1,8 +1,12 @@
 import type { NextConfig } from "next";
 import path from "path";
 
+const basePath = process.env.NEXT_PUBLIC_BASE_PATH || '';
+
 const nextConfig: NextConfig = {
   output: 'standalone',
+  basePath: basePath,
+  assetPrefix: basePath,
   // Disable request logging in production
   logging: false,
   // Set the monorepo root explicitly to avoid detecting wrong lockfiles in parent directories

hindsight-control-plane/src/app/api/banks/[bankId]/config/route.ts

@@ -0,0 +1,77 @@
+import { NextRequest, NextResponse } from "next/server";
+import { lowLevelClient, sdk } from "@/lib/hindsight-client";
+
+export async function GET(
+  request: NextRequest,
+  { params }: { params: Promise<{ bankId: string }> }
+) {
+  try {
+    const { bankId } = await params;
+
+    const response = await sdk.getBankConfig({
+      client: lowLevelClient,
+      path: { bank_id: bankId },
+    });
+
+    if (!response.data) {
+      console.error("[Bank Config API] No data in response", { response, error: response.error });
+      throw new Error(`API returned no data: ${JSON.stringify(response.error || "Unknown error")}`);
+    }
+
+    return NextResponse.json(response.data, { status: 200 });
+  } catch (error) {
+    console.error("Error fetching bank config:", error);
+    return NextResponse.json({ error: "Failed to fetch bank config" }, { status: 500 });
+  }
+}
+
+export async function PATCH(
+  request: NextRequest,
+  { params }: { params: Promise<{ bankId: string }> }
+) {
+  try {
+    const { bankId } = await params;
+    const body = await request.json();
+    const { updates } = body;
+
+    const response = await sdk.updateBankConfig({
+      client: lowLevelClient,
+      path: { bank_id: bankId },
+      body: { updates },
+    });
+
+    if (!response.data) {
+      console.error("[Bank Config API] No data in response", { response, error: response.error });
+      throw new Error(`API returned no data: ${JSON.stringify(response.error || "Unknown error")}`);
+    }
+
+    return NextResponse.json(response.data, { status: 200 });
+  } catch (error) {
+    console.error("Error updating bank config:", error);
+    return NextResponse.json({ error: "Failed to update bank config" }, { status: 500 });
+  }
+}
+
+export async function DELETE(
+  request: NextRequest,
+  { params }: { params: Promise<{ bankId: string }> }
+) {
+  try {
+    const { bankId } = await params;
+
+    const response = await sdk.resetBankConfig({
+      client: lowLevelClient,
+      path: { bank_id: bankId },
+    });
+
+    if (!response.data) {
+      console.error("[Bank Config API] No data in response", { response, error: response.error });
+      throw new Error(`API returned no data: ${JSON.stringify(response.error || "Unknown error")}`);
+    }
+
+    return NextResponse.json(response.data, { status: 200 });
+  } catch (error) {
+    console.error("Error resetting bank config:", error);
+    return NextResponse.json({ error: "Failed to reset bank config" }, { status: 500 });
+  }
+}

hindsight-control-plane/src/app/banks/[bankId]/page.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import { useState } from "react";
 import { useParams, useRouter, useSearchParams } from "next/navigation";
 import { BankSelector } from "@/components/bank-selector";
 import { Sidebar } from "@/components/sidebar";
@@ -9,22 +10,56 @@ import { EntitiesView } from "@/components/entities-view";
 import { ThinkView } from "@/components/think-view";
 import { SearchDebugView } from "@/components/search-debug-view";
 import { BankProfileView } from "@/components/bank-profile-view";
+import { BankConfigView } from "@/components/bank-config-view";
+import { BankStatsView } from "@/components/bank-stats-view";
+import { BankOperationsView } from "@/components/bank-operations-view";
 import { MentalModelsView } from "@/components/mental-models-view";
 import { useFeatures } from "@/lib/features-context";
+import { useBank } from "@/lib/bank-context";
+import { client } from "@/lib/api";
+import { Button } from "@/components/ui/button";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import { Brain, Trash2, Loader2, MoreVertical, Pencil } from "lucide-react";
 
 type NavItem = "recall" | "reflect" | "data" | "documents" | "entities" | "profile";
 type DataSubTab = "world" | "experience" | "observations" | "mental-models";
+type BankConfigTab = "general" | "configuration";
 
 export default function BankPage() {
   const params = useParams();
   const router = useRouter();
   const searchParams = useSearchParams();
   const { features } = useFeatures();
+  const { currentBank: bankId, setCurrentBank, loadBanks } = useBank();
 
-  const bankId = params.bankId as string;
   const view = (searchParams.get("view") || "profile") as NavItem;
   const subTab = (searchParams.get("subTab") || "world") as DataSubTab;
+  const bankConfigTab = (searchParams.get("bankConfigTab") || "general") as BankConfigTab;
   const observationsEnabled = features?.observations ?? false;
+  const bankConfigEnabled = features?.bank_config_api ?? false;
+
+  // Bank actions state
+  const [showDeleteDialog, setShowDeleteDialog] = useState(false);
+  const [isDeleting, setIsDeleting] = useState(false);
+  const [showClearObservationsDialog, setShowClearObservationsDialog] = useState(false);
+  const [isClearingObservations, setIsClearingObservations] = useState(false);
+  const [isConsolidating, setIsConsolidating] = useState(false);
 
   const handleTabChange = (tab: NavItem) => {
     router.push(`/banks/${bankId}?view=${tab}`);
@@ -34,6 +69,58 @@ export default function BankPage() {
     router.push(`/banks/${bankId}?view=data&subTab=${newSubTab}`);
   };
 
+  const handleBankConfigTabChange = (newTab: BankConfigTab) => {
+    router.push(`/banks/${bankId}?view=profile&bankConfigTab=${newTab}`);
+  };
+
+  const handleDeleteBank = async () => {
+    if (!bankId) return;
+
+    setIsDeleting(true);
+    try {
+      await client.deleteBank(bankId);
+      setShowDeleteDialog(false);
+      setCurrentBank(null);
+      await loadBanks();
+      router.push("/");
+    } catch (error) {
+      console.error("Error deleting bank:", error);
+      alert("Error deleting bank: " + (error as Error).message);
+    } finally {
+      setIsDeleting(false);
+    }
+  };
+
+  const handleClearObservations = async () => {
+    if (!bankId) return;
+
+    setIsClearingObservations(true);
+    try {
+      const result = await client.clearObservations(bankId);
+      setShowClearObservationsDialog(false);
+      alert(result.message || "Observations cleared successfully");
+    } catch (error) {
+      console.error("Error clearing observations:", error);
+      alert("Error clearing observations: " + (error as Error).message);
+    } finally {
+      setIsClearingObservations(false);
+    }
+  };
+
+  const handleTriggerConsolidation = async () => {
+    if (!bankId) return;
+
+    setIsConsolidating(true);
+    try {
+      await client.triggerConsolidation(bankId);
+    } catch (error) {
+      console.error("Error triggering consolidation:", error);
+      alert("Error triggering consolidation: " + (error as Error).message);
+    } finally {
+      setIsConsolidating(false);
+    }
+  };
+
   return (
     <div className="min-h-screen bg-background flex flex-col">
       <BankSelector />
@@ -43,15 +130,125 @@ export default function BankPage() {
 
         <main className="flex-1 overflow-y-auto">
           <div className="p-6">
-            {/* Profile Tab */}
+            {/* Bank Configuration Tab */}
             {view === "profile" && (
               <div>
-                <h1 className="text-3xl font-bold mb-2 text-foreground">Bank Profile</h1>
-                <p className="text-muted-foreground mb-6">
-                  View and edit the memory bank profile, disposition traits, and background
-                  information.
-                </p>
-                <BankProfileView />
+                <div className="flex justify-between items-start mb-6">
+                  <div>
+                    <h1 className="text-3xl font-bold mb-2 text-foreground">Bank Configuration</h1>
+                    <p className="text-muted-foreground">
+                      Manage bank settings, profile, and operations.
+                    </p>
+                  </div>
+                  <DropdownMenu>
+                    <DropdownMenuTrigger asChild>
+                      <Button variant="outline" size="sm">
+                        Actions
+                        <MoreVertical className="w-4 h-4 ml-2" />
+                      </Button>
+                    </DropdownMenuTrigger>
+                    <DropdownMenuContent align="end" className="w-48">
+                      <DropdownMenuItem
+                        onClick={handleTriggerConsolidation}
+                        disabled={isConsolidating || !observationsEnabled}
+                        title={
+                          !observationsEnabled ? "Observations feature is not enabled" : undefined
+                        }
+                      >
+                        {isConsolidating ? (
+                          <Loader2 className="w-4 h-4 mr-2 animate-spin" />
+                        ) : (
+                          <Brain className="w-4 h-4 mr-2" />
+                        )}
+                        {isConsolidating ? "Consolidating..." : "Run Consolidation"}
+                        {!observationsEnabled && (
+                          <span className="ml-auto text-xs text-muted-foreground">Off</span>
+                        )}
+                      </DropdownMenuItem>
+                      <DropdownMenuItem
+                        onClick={() => setShowClearObservationsDialog(true)}
+                        disabled={!observationsEnabled}
+                        className="text-amber-600 dark:text-amber-400 focus:text-amber-700 dark:focus:text-amber-300"
+                        title={
+                          !observationsEnabled ? "Observations feature is not enabled" : undefined
+                        }
+                      >
+                        <Trash2 className="w-4 h-4 mr-2" />
+                        Clear Observations
+                        {!observationsEnabled && (
+                          <span className="ml-auto text-xs text-muted-foreground">Off</span>
+                        )}
+                      </DropdownMenuItem>
+                      <DropdownMenuSeparator />
+                      <DropdownMenuItem
+                        onClick={() => setShowDeleteDialog(true)}
+                        className="text-red-600 dark:text-red-400 focus:text-red-700 dark:focus:text-red-300"
+                      >
+                        <Trash2 className="w-4 h-4 mr-2" />
+                        Delete Bank
+                      </DropdownMenuItem>
+                    </DropdownMenuContent>
+                  </DropdownMenu>
+                </div>
+
+                {/* Sub-tabs */}
+                <div className="mb-6 border-b border-border">
+                  <div className="flex gap-1">
+                    <button
+                      onClick={() => handleBankConfigTabChange("general")}
+                      className={`px-6 py-3 font-semibold text-sm transition-all relative ${
+                        bankConfigTab === "general"
+                          ? "text-primary"
+                          : "text-muted-foreground hover:text-foreground"
+                      }`}
+                    >
+                      General
+                      {bankConfigTab === "general" && (
+                        <div className="absolute bottom-0 left-0 right-0 h-0.5 bg-primary" />
+                      )}
+                    </button>
+                    <button
+                      onClick={() => handleBankConfigTabChange("configuration")}
+                      className={`px-6 py-3 font-semibold text-sm transition-all relative ${
+                        bankConfigTab === "configuration"
+                          ? "text-primary"
+                          : "text-muted-foreground hover:text-foreground"
+                      }`}
+                    >
+                      Configuration
+                      {bankConfigTab === "configuration" && (
+                        <div className="absolute bottom-0 left-0 right-0 h-0.5 bg-primary" />
+                      )}
+                    </button>
+                  </div>
+                </div>
+
+                {/* Tab content */}
+                <div>
+                  {bankConfigTab === "general" && (
+                    <div>
+                      <p className="text-sm text-muted-foreground mb-4">
+                        Overview statistics and background operations for this memory bank.
+                      </p>
+                      <div className="space-y-6">
+                        <BankStatsView />
+                        <BankOperationsView />
+                      </div>
+                    </div>
+                  )}
+                  {bankConfigTab === "configuration" && (
+                    <div>
+                      <p className="text-sm text-muted-foreground mb-6">
+                        Configure disposition traits, mission, directives, and behavioral settings
+                        for this bank.
+                      </p>
+                      <div className="space-y-6">
+                        <BankProfileView />
+                        {bankConfigEnabled && <BankConfigView />}
+                      </div>
+                    </div>
+                  )}
+                </div>
               </div>
             )}
 
@@ -242,6 +439,88 @@ export default function BankPage() {
           </div>
         </main>
       </div>
+
+      {/* Delete Bank Confirmation Dialog */}
+      <AlertDialog open={showDeleteDialog} onOpenChange={setShowDeleteDialog}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Delete Memory Bank</AlertDialogTitle>
+            <AlertDialogDescription asChild>
+              <div className="space-y-2 text-sm text-muted-foreground">
+                <p>
+                  Are you sure you want to delete the memory bank{" "}
+                  <span className="font-semibold text-foreground">{bankId}</span>?
+                </p>
+                <p className="text-red-600 dark:text-red-400 font-medium">
+                  This action cannot be undone. All memories, entities, documents, and the bank
+                  profile will be permanently deleted.
+                </p>
+              </div>
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel disabled={isDeleting}>Cancel</AlertDialogCancel>
+            <AlertDialogAction
+              onClick={handleDeleteBank}
+              disabled={isDeleting}
+              className="bg-destructive text-destructive-foreground hover:bg-destructive/90"
+            >
+              {isDeleting ? (
+                <>
+                  <Loader2 className="w-4 h-4 mr-2 animate-spin" />
+                  Deleting...
+                </>
+              ) : (
+                <>
+                  <Trash2 className="w-4 h-4 mr-2" />
+                  Delete Bank
+                </>
+              )}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+
+      {/* Clear Observations Confirmation Dialog */}
+      <AlertDialog open={showClearObservationsDialog} onOpenChange={setShowClearObservationsDialog}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Clear Observations</AlertDialogTitle>
+            <AlertDialogDescription asChild>
+              <div className="space-y-2 text-sm text-muted-foreground">
+                <p>
+                  Are you sure you want to clear all observations for{" "}
+                  <span className="font-semibold text-foreground">{bankId}</span>?
+                </p>
+                <p className="text-amber-600 dark:text-amber-400 font-medium">
+                  This will delete all consolidated knowledge. Observations will be regenerated the
+                  next time consolidation runs.
+                </p>
+              </div>
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel disabled={isClearingObservations}>Cancel</AlertDialogCancel>
+            <AlertDialogAction
+              onClick={handleClearObservations}
+              disabled={isClearingObservations}
+              className="bg-amber-500 text-white hover:bg-amber-600"
+            >
+              {isClearingObservations ? (
+                <>
+                  <Loader2 className="w-4 h-4 mr-2 animate-spin" />
+                  Clearing...
+                </>
+              ) : (
+                <>
+                  <Trash2 className="w-4 h-4 mr-2" />
+                  Clear Observations
+                </>
+              )}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
     </div>
   );
 }

hindsight-control-plane/src/components/bank-config-view.tsx

@@ -0,0 +1,480 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { useBank } from "@/lib/bank-context";
+import { client } from "@/lib/api";
+import { Button } from "@/components/ui/button";
+import { Input } from "@/components/ui/input";
+import { Label } from "@/components/ui/label";
+import { Textarea } from "@/components/ui/textarea";
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from "@/components/ui/select";
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+} from "@/components/ui/dialog";
+import {
+  AlertDialog,
+  AlertDialogAction,
+  AlertDialogCancel,
+  AlertDialogContent,
+  AlertDialogDescription,
+  AlertDialogFooter,
+  AlertDialogHeader,
+  AlertDialogTitle,
+} from "@/components/ui/alert-dialog";
+import { Alert, AlertDescription } from "@/components/ui/alert";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuTrigger,
+} from "@/components/ui/dropdown-menu";
+import { Loader2, AlertCircle, CheckCircle2, Pencil, RotateCcw, MoreVertical } from "lucide-react";
+import { Card, CardContent, CardHeader, CardTitle, CardDescription } from "@/components/ui/card";
+
+// Field metadata for UI rendering
+const FIELD_CATEGORIES = {
+  retention: {
+    title: "Retention Settings",
+    description: "Control how memories are extracted and stored",
+    fields: {
+      retain_chunk_size: {
+        label: "Chunk Size",
+        type: "number",
+        description: "Size of text chunks for processing (tokens)",
+        min: 500,
+        max: 8000,
+      },
+      retain_extraction_mode: {
+        label: "Extraction Mode",
+        type: "select",
+        description: "How to extract facts from content",
+        options: ["concise", "verbose", "custom"],
+      },
+      retain_custom_instructions: {
+        label: "Custom Instructions",
+        type: "textarea",
+        description:
+          "Custom instructions for fact extraction (requires retain_extraction_mode='custom')",
+        placeholder: "Focus on technical details and implementation specifics...",
+        rows: 3,
+      },
+    },
+  },
+  consolidation: {
+    title: "Consolidation Settings",
+    description: "Control observation synthesis",
+    fields: {
+      enable_observations: {
+        label: "Enable Observations",
+        type: "boolean",
+        description: "Enable automatic consolidation of facts into observations",
+      },
+    },
+  },
+};
+
+export function BankConfigView() {
+  const { currentBank: bankId } = useBank();
+  const [loading, setLoading] = useState(true);
+  const [config, setConfig] = useState<Record<string, any>>({});
+  const [overrides, setOverrides] = useState<Record<string, any>>({});
+  const [showEditDialog, setShowEditDialog] = useState(false);
+  const [showResetDialog, setShowResetDialog] = useState(false);
+  const [resetting, setResetting] = useState(false);
+
+  useEffect(() => {
+    if (bankId) {
+      loadConfig();
+    }
+  }, [bankId]);
+
+  const loadConfig = async () => {
+    if (!bankId) return;
+
+    setLoading(true);
+    try {
+      const response = await client.getBankConfig(bankId);
+      setConfig(response.config);
+      setOverrides(response.overrides);
+    } catch (err: any) {
+      console.error("Failed to load config:", err);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleReset = () => {
+    setShowResetDialog(true);
+  };
+
+  const confirmReset = async () => {
+    if (!bankId) return;
+
+    setResetting(true);
+    try {
+      await client.resetBankConfig(bankId);
+      await loadConfig();
+      setShowResetDialog(false);
+    } catch (err: any) {
+      console.error("Failed to reset config:", err);
+      alert("Error resetting config: " + err.message);
+    } finally {
+      setResetting(false);
+    }
+  };
+
+  const renderReadOnlyField = (fieldKey: string, fieldMeta: any) => {
+    const value = config[fieldKey];
+
+    return (
+      <div
+        key={fieldKey}
+        className="flex items-start justify-between gap-4 p-3 border border-border rounded-lg bg-muted/30 hover:bg-muted/50 transition-colors"
+      >
+        <div className="flex-1 min-w-0">
+          <div className="text-sm font-medium font-mono">{fieldKey}</div>
+          {fieldMeta.description && (
+            <p className="text-xs text-muted-foreground mt-0.5">{fieldMeta.description}</p>
+          )}
+        </div>
+        <div className="text-sm text-foreground font-mono flex-shrink-0">
+          {fieldMeta.type === "boolean" ? (
+            <span className={value ? "text-green-600" : "text-muted-foreground"}>
+              {value ? "Enabled" : "Disabled"}
+            </span>
+          ) : fieldMeta.type === "textarea" ? (
+            <span className="text-muted-foreground italic">
+              {value ? `${value.substring(0, 50)}${value.length > 50 ? "..." : ""}` : "Not set"}
+            </span>
+          ) : (
+            value || <span className="text-muted-foreground italic">Not set</span>
+          )}
+        </div>
+      </div>
+    );
+  };
+
+  if (!bankId) {
+    return (
+      <div className="flex items-center justify-center py-12">
+        <p className="text-muted-foreground">No bank selected</p>
+      </div>
+    );
+  }
+
+  if (loading) {
+    return (
+      <div className="flex items-center justify-center py-12">
+        <Loader2 className="h-8 w-8 animate-spin text-muted-foreground" />
+      </div>
+    );
+  }
+
+  return (
+    <>
+      <Card>
+        <CardHeader className="pb-3">
+          <div className="flex items-center justify-between">
+            <div>
+              <CardTitle className="text-base">Configuration Settings</CardTitle>
+              <CardDescription className="text-xs">
+                Behavioral parameters for this memory bank
+              </CardDescription>
+            </div>
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <Button variant="ghost" size="sm" disabled={resetting}>
+                  {resetting ? (
+                    <Loader2 className="h-4 w-4 animate-spin" />
+                  ) : (
+                    <MoreVertical className="h-4 w-4" />
+                  )}
+                </Button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end">
+                <DropdownMenuItem onClick={() => setShowEditDialog(true)}>
+                  <Pencil className="h-4 w-4 mr-2" />
+                  Edit
+                </DropdownMenuItem>
+                <DropdownMenuItem onClick={handleReset}>
+                  <RotateCcw className="h-4 w-4 mr-2" />
+                  Reset to Defaults
+                </DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </div>
+        </CardHeader>
+        <CardContent className="space-y-6">
+          {Object.entries(FIELD_CATEGORIES).map(([catKey, category]) => (
+            <div key={catKey}>
+              <div className="mb-3">
+                <h3 className="text-sm font-semibold">{category.title}</h3>
+                <p className="text-xs text-muted-foreground">{category.description}</p>
+              </div>
+              <div className="grid grid-cols-2 gap-x-8 gap-y-4">
+                {Object.entries(category.fields).map(([fieldKey, fieldMeta]) =>
+                  renderReadOnlyField(fieldKey, fieldMeta)
+                )}
+              </div>
+            </div>
+          ))}
+        </CardContent>
+      </Card>
+
+      {showEditDialog && (
+        <ConfigEditDialog
+          bankId={bankId}
+          initialConfig={config}
+          overrides={overrides}
+          onClose={() => setShowEditDialog(false)}
+          onSaved={() => {
+            loadConfig();
+            setShowEditDialog(false);
+          }}
+        />
+      )}
+
+      <AlertDialog open={showResetDialog} onOpenChange={setShowResetDialog}>
+        <AlertDialogContent>
+          <AlertDialogHeader>
+            <AlertDialogTitle>Reset Configuration</AlertDialogTitle>
+            <AlertDialogDescription>
+              Are you sure you want to reset all configuration overrides to defaults? This action
+              cannot be undone.
+            </AlertDialogDescription>
+          </AlertDialogHeader>
+          <AlertDialogFooter>
+            <AlertDialogCancel disabled={resetting}>Cancel</AlertDialogCancel>
+            <AlertDialogAction onClick={confirmReset} disabled={resetting}>
+              {resetting ? (
+                <>
+                  <Loader2 className="h-4 w-4 mr-2 animate-spin" />
+                  Resetting...
+                </>
+              ) : (
+                "Reset to Defaults"
+              )}
+            </AlertDialogAction>
+          </AlertDialogFooter>
+        </AlertDialogContent>
+      </AlertDialog>
+    </>
+  );
+}
+
+// Edit dialog component
+function ConfigEditDialog({
+  bankId,
+  initialConfig,
+  overrides,
+  onClose,
+  onSaved,
+}: {
+  bankId: string;
+  initialConfig: Record<string, any>;
+  overrides: Record<string, any>;
+  onClose: () => void;
+  onSaved: () => void;
+}) {
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [config, setConfig] = useState(initialConfig);
+
+  const handleFieldChange = (field: string, value: any) => {
+    setConfig({ ...config, [field]: value });
+  };
+
+  const handleSave = async () => {
+    setSaving(true);
+    setError(null);
+    try {
+      const updates: Record<string, any> = {};
+      Object.keys(config).forEach((key) => {
+        const isConfigurable = Object.values(FIELD_CATEGORIES).some((cat) =>
+          Object.keys(cat.fields).includes(key)
+        );
+        if (isConfigurable) {
+          updates[key] = config[key];
+        }
+      });
+
+      await client.updateBankConfig(bankId, updates);
+      onSaved();
+    } catch (err: any) {
+      console.error("Failed to save config:", err);
+      setError(err.message || "Failed to save configuration");
+      setSaving(false);
+    }
+  };
+
+  const renderField = (fieldKey: string, fieldMeta: any) => {
+    const value = config[fieldKey];
+
+    if (fieldMeta.type === "boolean") {
+      return (
+        <div key={fieldKey} className="space-y-2">
+          <div className="flex items-center justify-between">
+            <div>
+              <Label htmlFor={fieldKey} className="font-mono">
+                {fieldKey}
+              </Label>
+              {fieldMeta.description && (
+                <p className="text-xs text-muted-foreground mt-1">{fieldMeta.description}</p>
+              )}
+            </div>
+            <button
+              onClick={() => handleFieldChange(fieldKey, !value)}
+              className={`relative inline-flex h-6 w-11 items-center rounded-full transition-colors ${
+                value ? "bg-primary" : "bg-muted"
+              }`}
+            >
+              <span
+                className={`inline-block h-4 w-4 transform rounded-full bg-white transition-transform ${
+                  value ? "translate-x-6" : "translate-x-1"
+                }`}
+              />
+            </button>
+          </div>
+        </div>
+      );
+    }
+
+    if (fieldMeta.type === "select") {
+      return (
+        <div key={fieldKey} className="space-y-2">
+          <Label htmlFor={fieldKey} className="font-mono">
+            {fieldKey}
+          </Label>
+          {fieldMeta.description && (
+            <p className="text-xs text-muted-foreground mt-1">{fieldMeta.description}</p>
+          )}
+          <Select
+            value={value?.toString()}
+            onValueChange={(val) => handleFieldChange(fieldKey, val)}
+          >
+            <SelectTrigger>
+              <SelectValue />
+            </SelectTrigger>
+            <SelectContent>
+              {fieldMeta.options.map((opt: string) => (
+                <SelectItem key={opt} value={opt}>
+                  {opt}
+                </SelectItem>
+              ))}
+            </SelectContent>
+          </Select>
+        </div>
+      );
+    }
+
+    if (fieldMeta.type === "textarea") {
+      return (
+        <div key={fieldKey} className="space-y-2">
+          <Label htmlFor={fieldKey} className="font-mono">
+            {fieldKey}
+          </Label>
+          {fieldMeta.description && (
+            <p className="text-xs text-muted-foreground mt-1">{fieldMeta.description}</p>
+          )}
+          <Textarea
+            id={fieldKey}
+            value={value || ""}
+            onChange={(e) => handleFieldChange(fieldKey, e.target.value || null)}
+            placeholder={fieldMeta.placeholder}
+            rows={fieldMeta.rows || 3}
+            className="font-mono text-sm"
+          />
+        </div>
+      );
+    }
+
+    // number or text
+    return (
+      <div key={fieldKey} className="space-y-2">
+        <Label htmlFor={fieldKey} className="font-mono">
+          {fieldKey}
+        </Label>
+        {fieldMeta.description && (
+          <p className="text-xs text-muted-foreground mt-1">{fieldMeta.description}</p>
+        )}
+        <Input
+          id={fieldKey}
+          type={fieldMeta.type || "text"}
+          value={value ?? ""}
+          onChange={(e) =>
+            handleFieldChange(
+              fieldKey,
+              fieldMeta.type === "number" ? parseFloat(e.target.value) : e.target.value
+            )
+          }
+          min={fieldMeta.min}
+          max={fieldMeta.max}
+        />
+      </div>
+    );
+  };
+
+  return (
+    <Dialog open onOpenChange={onClose}>
+      <DialogContent className="max-w-2xl max-h-[90vh] overflow-y-auto">
+        <DialogHeader>
+          <DialogTitle>Edit Configuration</DialogTitle>
+          <DialogDescription>
+            Customize behavioral settings for this bank. Changes only affect this bank and override
+            global defaults.
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-6 py-4">
+          {error && (
+            <Alert variant="destructive">
+              <AlertCircle className="h-4 w-4" />
+              <AlertDescription>{error}</AlertDescription>
+            </Alert>
+          )}
+
+          {Object.entries(FIELD_CATEGORIES).map(([catKey, category]) => (
+            <div key={catKey} className="space-y-4">
+              <div>
+                <h3 className="text-sm font-semibold">{category.title}</h3>
+                <p className="text-xs text-muted-foreground">{category.description}</p>
+              </div>
+              <div className="grid gap-4">
+                {Object.entries(category.fields).map(([fieldKey, fieldMeta]) =>
+                  renderField(fieldKey, fieldMeta)
+                )}
+              </div>
+            </div>
+          ))}
+        </div>
+
+        <DialogFooter>
+          <Button onClick={onClose} variant="outline" disabled={saving}>
+            Cancel
+          </Button>
+          <Button onClick={handleSave} disabled={saving}>
+            {saving ? (
+              <>
+                <Loader2 className="h-4 w-4 mr-2 animate-spin" />
+                Saving...
+              </>
+            ) : (
+              "Save Changes"
+            )}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}

hindsight-control-plane/src/components/bank-operations-view.tsx

@@ -0,0 +1,245 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { useBank } from "@/lib/bank-context";
+import { client } from "@/lib/api";
+import { Button } from "@/components/ui/button";
+import {
+  Table,
+  TableBody,
+  TableCell,
+  TableHead,
+  TableHeader,
+  TableRow,
+} from "@/components/ui/table";
+import { RefreshCw, Clock, AlertCircle, CheckCircle, Loader2, X } from "lucide-react";
+
+interface Operation {
+  id: string;
+  task_type: string;
+  items_count: number;
+  document_id: string | null;
+  created_at: string;
+  status: string;
+  error_message: string | null;
+}
+
+export function BankOperationsView() {
+  const { currentBank } = useBank();
+  const [operations, setOperations] = useState<Operation[]>([]);
+  const [totalOperations, setTotalOperations] = useState(0);
+  const [statusFilter, setStatusFilter] = useState<string | null>(null);
+  const [limit] = useState(10);
+  const [offset, setOffset] = useState(0);
+  const [cancellingOpId, setCancellingOpId] = useState<string | null>(null);
+  const [loading, setLoading] = useState(false);
+
+  const loadOperations = async (
+    newStatusFilter: string | null = statusFilter,
+    newOffset: number = offset
+  ) => {
+    if (!currentBank) return;
+
+    setLoading(true);
+    try {
+      const opsData = await client.listOperations(currentBank, {
+        status: newStatusFilter || undefined,
+        limit,
+        offset: newOffset,
+      });
+      setOperations(opsData.operations || []);
+      setTotalOperations(opsData.total || 0);
+    } catch (error) {
+      console.error("Error loading operations:", error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  const handleFilterChange = (newFilter: string | null) => {
+    setStatusFilter(newFilter);
+    setOffset(0);
+    loadOperations(newFilter, 0);
+  };
+
+  const handlePageChange = (newOffset: number) => {
+    setOffset(newOffset);
+    loadOperations(statusFilter, newOffset);
+  };
+
+  const handleCancelOperation = async (operationId: string) => {
+    if (!currentBank) return;
+
+    setCancellingOpId(operationId);
+    try {
+      await client.cancelOperation(currentBank, operationId);
+      await loadOperations();
+    } catch (error) {
+      console.error("Error cancelling operation:", error);
+      alert("Error cancelling operation: " + (error as Error).message);
+    } finally {
+      setCancellingOpId(null);
+    }
+  };
+
+  useEffect(() => {
+    if (currentBank) {
+      loadOperations();
+      // Refresh operations every 5 seconds
+      const interval = setInterval(() => loadOperations(), 5000);
+      return () => clearInterval(interval);
+    }
+  }, [currentBank]);
+
+  if (!currentBank) return null;
+
+  return (
+    <div className="space-y-4">
+      <div className="flex items-center justify-between">
+        <div>
+          <div className="flex items-center gap-2">
+            <h3 className="text-lg font-semibold">Background Operations</h3>
+            <button
+              onClick={() => loadOperations()}
+              className="p-1 rounded hover:bg-muted transition-colors"
+              title="Refresh operations"
+              disabled={loading}
+            >
+              <RefreshCw
+                className={`w-4 h-4 text-muted-foreground hover:text-foreground ${loading ? "animate-spin" : ""}`}
+              />
+            </button>
+          </div>
+          <p className="text-sm text-muted-foreground">
+            {totalOperations} operation{totalOperations !== 1 ? "s" : ""}
+            {statusFilter ? ` (${statusFilter})` : ""}
+          </p>
+        </div>
+        <div className="flex gap-1 bg-muted p-1 rounded-lg">
+          {[
+            { value: null, label: "All" },
+            { value: "pending", label: "Pending" },
+            { value: "completed", label: "Completed" },
+            { value: "failed", label: "Failed" },
+          ].map((filter) => (
+            <button
+              key={filter.value ?? "all"}
+              onClick={() => handleFilterChange(filter.value)}
+              className={`px-3 py-1.5 text-sm font-medium rounded-md transition-colors ${
+                statusFilter === filter.value
+                  ? "bg-background shadow-sm"
+                  : "text-muted-foreground hover:text-foreground"
+              }`}
+            >
+              {filter.label}
+            </button>
+          ))}
+        </div>
+      </div>
+      <div>
+        {operations.length > 0 ? (
+          <>
+            <div className="overflow-x-auto">
+              <Table>
+                <TableHeader>
+                  <TableRow>
+                    <TableHead className="w-[100px]">ID</TableHead>
+                    <TableHead>Type</TableHead>
+                    <TableHead>Created</TableHead>
+                    <TableHead>Status</TableHead>
+                    <TableHead className="w-[80px]"></TableHead>
+                  </TableRow>
+                </TableHeader>
+                <TableBody>
+                  {operations.map((op) => (
+                    <TableRow key={op.id} className={op.status === "failed" ? "bg-red-500/5" : ""}>
+                      <TableCell className="font-mono text-xs text-muted-foreground">
+                        {op.id.substring(0, 8)}
+                      </TableCell>
+                      <TableCell className="font-medium">{op.task_type}</TableCell>
+                      <TableCell className="text-sm text-muted-foreground">
+                        {new Date(op.created_at).toLocaleString()}
+                      </TableCell>
+                      <TableCell>
+                        {op.status === "pending" && (
+                          <span className="inline-flex items-center gap-1.5 px-2 py-0.5 rounded-full text-xs font-medium bg-amber-500/10 text-amber-600 dark:text-amber-400 border border-amber-500/20">
+                            <Clock className="w-3 h-3" />
+                            pending
+                          </span>
+                        )}
+                        {op.status === "failed" && (
+                          <span
+                            className="inline-flex items-center gap-1.5 px-2 py-0.5 rounded-full text-xs font-medium bg-red-500/10 text-red-600 dark:text-red-400 border border-red-500/20"
+                            title={op.error_message ?? undefined}
+                          >
+                            <AlertCircle className="w-3 h-3" />
+                            failed
+                          </span>
+                        )}
+                        {op.status === "completed" && (
+                          <span className="inline-flex items-center gap-1.5 px-2 py-0.5 rounded-full text-xs font-medium bg-emerald-500/10 text-emerald-600 dark:text-emerald-400 border border-emerald-500/20">
+                            <CheckCircle className="w-3 h-3" />
+                            completed
+                          </span>
+                        )}
+                      </TableCell>
+                      <TableCell>
+                        {op.status === "pending" && (
+                          <Button
+                            variant="ghost"
+                            size="sm"
+                            className="h-7 text-xs text-muted-foreground hover:text-red-600 dark:hover:text-red-400"
+                            onClick={() => handleCancelOperation(op.id)}
+                            disabled={cancellingOpId === op.id}
+                          >
+                            {cancellingOpId === op.id ? (
+                              <Loader2 className="w-3 h-3 animate-spin" />
+                            ) : (
+                              <X className="w-3 h-3 mr-1" />
+                            )}
+                            {cancellingOpId === op.id ? "" : "Cancel"}
+                          </Button>
+                        )}
+                      </TableCell>
+                    </TableRow>
+                  ))}
+                </TableBody>
+              </Table>
+            </div>
+            {/* Pagination */}
+            {totalOperations > limit && (
+              <div className="flex items-center justify-between mt-4 pt-4 border-t">
+                <p className="text-sm text-muted-foreground">
+                  Showing {offset + 1}-{Math.min(offset + limit, totalOperations)} of{" "}
+                  {totalOperations}
+                </p>
+                <div className="flex gap-2">
+                  <Button
+                    variant="outline"
+                    size="sm"
+                    onClick={() => handlePageChange(Math.max(0, offset - limit))}
+                    disabled={offset === 0}
+                  >
+                    Previous
+                  </Button>
+                  <Button
+                    variant="outline"
+                    size="sm"
+                    onClick={() => handlePageChange(offset + limit)}
+                    disabled={offset + limit >= totalOperations}
+                  >
+                    Next
+                  </Button>
+                </div>
+              </div>
+            )}
+          </>
+        ) : (
+          <p className="text-muted-foreground text-center py-8 text-sm">
+            No {statusFilter ? `${statusFilter} ` : ""}operations
+          </p>
+        )}
+      </div>
+    </div>
+  );
+}

hindsight-control-plane/src/components/bank-profile-view.tsx

@@ -151,66 +151,6 @@ const TRAIT_LABELS: Record<
   },
 };
 
-function DispositionEditor({
-  disposition,
-  editMode,
-  editDisposition,
-  onEditChange,
-}: {
-  disposition: DispositionTraits;
-  editMode: boolean;
-  editDisposition: DispositionTraits;
-  onEditChange: (trait: keyof DispositionTraits, value: number) => void;
-}) {
-  const data = editMode ? editDisposition : disposition;
-
-  return (
-    <div className="space-y-4">
-      {(Object.keys(TRAIT_LABELS) as Array<keyof DispositionTraits>).map((trait) => (
-        <div key={trait} className="space-y-2">
-          <div className="flex justify-between items-center">
-            <div>
-              <label className="text-sm font-medium text-foreground">
-                {TRAIT_LABELS[trait].label}
-              </label>
-              <p className="text-xs text-muted-foreground">{TRAIT_LABELS[trait].description}</p>
-            </div>
-            <span className="text-sm font-bold text-primary">{data[trait]}/5</span>
-          </div>
-          {editMode ? (
-            <>
-              <div className="flex justify-between text-[10px] text-muted-foreground">
-                <span>{TRAIT_LABELS[trait].lowLabel}</span>
-                <span>{TRAIT_LABELS[trait].highLabel}</span>
-              </div>
-              <input
-                type="range"
-                min="1"
-                max="5"
-                step="1"
-                value={editDisposition[trait]}
-                onChange={(e) => onEditChange(trait, parseInt(e.target.value))}
-                className="w-full h-2 bg-muted rounded-lg appearance-none cursor-pointer accent-primary"
-              />
-            </>
-          ) : (
-            <div className="flex items-center gap-2">
-              <span className="text-xs text-muted-foreground">{TRAIT_LABELS[trait].lowLabel}</span>
-              <div className="flex-1 h-2 bg-muted rounded-full overflow-hidden">
-                <div
-                  className="h-full bg-primary rounded-full transition-all"
-                  style={{ width: `${((data[trait] - 1) / 4) * 100}%` }}
-                />
-              </div>
-              <span className="text-xs text-muted-foreground">{TRAIT_LABELS[trait].highLabel}</span>
-            </div>
-          )}
-        </div>
-      ))}
-    </div>
-  );
-}
-
 export function BankProfileView() {
   const router = useRouter();
   const { currentBank, setCurrentBank, loadBanks } = useBank();
@@ -223,8 +163,8 @@ export function BankProfileView() {
   const [directives, setDirectives] = useState<Directive[]>([]);
   const [mentalModelsCount, setMentalModelsCount] = useState(0);
   const [loading, setLoading] = useState(false);
-  const [saving, setSaving] = useState(false);
-  const [editMode, setEditMode] = useState(false);
+  const [showDispositionDialog, setShowDispositionDialog] = useState(false);
+  const [showMissionDialog, setShowMissionDialog] = useState(false);
 
   // Directive state
   const [showCreateDirective, setShowCreateDirective] = useState(false);
@@ -235,12 +175,6 @@ export function BankProfileView() {
   } | null>(null);
   const [deletingDirective, setDeletingDirective] = useState(false);
 
-  // Ref to track editMode for polling (avoids stale closure)
-  const editModeRef = useRef(editMode);
-  useEffect(() => {
-    editModeRef.current = editMode;
-  }, [editMode]);
-
   // Delete state
   const [showDeleteDialog, setShowDeleteDialog] = useState(false);
   const [isDeleting, setIsDeleting] = useState(false);
@@ -258,14 +192,6 @@ export function BankProfileView() {
   const [opsOffset, setOpsOffset] = useState(0);
   const [cancellingOpId, setCancellingOpId] = useState<string | null>(null);
 
-  // Edit state
-  const [editMission, setEditMission] = useState("");
-  const [editDisposition, setEditDisposition] = useState<DispositionTraits>({
-    skepticism: 3,
-    literalism: 3,
-    empathy: 3,
-  });
-
   const loadOperations = async (
     statusFilter: string | null = opsStatusFilter,
     offset: number = opsOffset
@@ -319,12 +245,6 @@ export function BankProfileView() {
       setDirectives(directivesData.items || []);
       setMentalModelsCount(mentalModelsData.items?.length || 0);
       await loadOperations();
-
-      // Only initialize edit state when not in edit mode
-      if (!editModeRef.current) {
-        setEditMission(profileData.mission || "");
-        setEditDisposition(profileData.disposition);
-      }
     } catch (error) {
       console.error("Error loading bank profile:", error);
       alert("Error loading bank profile: " + (error as Error).message);
@@ -333,33 +253,6 @@ export function BankProfileView() {
     }
   };
 
-  const handleSave = async () => {
-    if (!currentBank) return;
-
-    setSaving(true);
-    try {
-      await client.updateBankProfile(currentBank, {
-        mission: editMission,
-        disposition: editDisposition,
-      });
-      await loadData();
-      setEditMode(false);
-    } catch (error) {
-      console.error("Error saving bank profile:", error);
-      alert("Error saving bank profile: " + (error as Error).message);
-    } finally {
-      setSaving(false);
-    }
-  };
-
-  const handleCancel = () => {
-    if (profile) {
-      setEditMission(profile.mission || "");
-      setEditDisposition(profile.disposition);
-    }
-    setEditMode(false);
-  };
-
   const handleDeleteBank = async () => {
     if (!currentBank) return;
 
@@ -501,238 +394,58 @@ export function BankProfileView() {
 
   return (
     <div className="space-y-6">
-      {/* Header with actions */}
-      <div className="flex justify-between items-center">
-        <div>
-          <h2 className="text-2xl font-bold text-foreground">{profile?.name || currentBank}</h2>
-          <p className="text-sm text-muted-foreground font-mono">{currentBank}</p>
-        </div>
-        <div className="flex gap-2">
-          {editMode ? (
-            <>
-              <Button onClick={handleCancel} variant="secondary" disabled={saving}>
-                Cancel
-              </Button>
-              <Button onClick={handleSave} disabled={saving}>
-                {saving ? (
-                  <>
-                    <RefreshCw className="w-4 h-4 mr-2 animate-spin" />
-                    Saving...
-                  </>
-                ) : (
-                  <>
-                    <Save className="w-4 h-4 mr-2" />
-                    Save Changes
-                  </>
-                )}
-              </Button>
-            </>
-          ) : (
-            <DropdownMenu>
-              <DropdownMenuTrigger asChild>
-                <Button variant="outline" size="sm">
-                  Actions
-                  <MoreVertical className="w-4 h-4 ml-2" />
-                </Button>
-              </DropdownMenuTrigger>
-              <DropdownMenuContent align="end" className="w-48">
-                <DropdownMenuItem onClick={() => setEditMode(true)}>
-                  <Pencil className="w-4 h-4 mr-2" />
-                  Edit Profile
-                </DropdownMenuItem>
-                <DropdownMenuSeparator />
-                <DropdownMenuItem
-                  onClick={handleTriggerConsolidation}
-                  disabled={isConsolidating || !observationsEnabled}
-                  title={!observationsEnabled ? "Observations feature is not enabled" : undefined}
-                >
-                  {isConsolidating ? (
-                    <Loader2 className="w-4 h-4 mr-2 animate-spin" />
-                  ) : (
-                    <Brain className="w-4 h-4 mr-2" />
-                  )}
-                  {isConsolidating ? "Consolidating..." : "Run Consolidation"}
-                  {!observationsEnabled && (
-                    <span className="ml-auto text-xs text-muted-foreground">Off</span>
-                  )}
-                </DropdownMenuItem>
-                <DropdownMenuItem
-                  onClick={() => setShowClearObservationsDialog(true)}
-                  disabled={!observationsEnabled}
-                  className="text-amber-600 dark:text-amber-400 focus:text-amber-700 dark:focus:text-amber-300"
-                  title={!observationsEnabled ? "Observations feature is not enabled" : undefined}
-                >
-                  <Trash2 className="w-4 h-4 mr-2" />
-                  Clear Observations
-                  {!observationsEnabled && (
-                    <span className="ml-auto text-xs text-muted-foreground">Off</span>
-                  )}
-                </DropdownMenuItem>
-                <DropdownMenuSeparator />
-                <DropdownMenuItem
-                  onClick={() => setShowDeleteDialog(true)}
-                  className="text-red-600 dark:text-red-400 focus:text-red-700 dark:focus:text-red-300"
-                >
-                  <Trash2 className="w-4 h-4 mr-2" />
-                  Delete Bank
-                </DropdownMenuItem>
-              </DropdownMenuContent>
-            </DropdownMenu>
-          )}
-        </div>
-      </div>
-
-      {/* Stats Overview - Compact cards */}
-      {stats && (
-        <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
-          <Card className="bg-gradient-to-br from-blue-500/10 to-blue-600/5 border-blue-500/20">
-            <CardContent className="p-4">
-              <div className="flex items-center gap-3">
-                <div className="p-2 rounded-lg bg-blue-500/20">
-                  <Database className="w-5 h-5 text-blue-500" />
-                </div>
-                <div>
-                  <p className="text-xs text-muted-foreground font-medium">Memories</p>
-                  <p className="text-2xl font-bold text-foreground">{stats.total_nodes}</p>
-                </div>
-              </div>
-            </CardContent>
-          </Card>
-
-          <Card className="bg-gradient-to-br from-purple-500/10 to-purple-600/5 border-purple-500/20">
-            <CardContent className="p-4">
-              <div className="flex items-center gap-3">
-                <div className="p-2 rounded-lg bg-purple-500/20">
-                  <Link2 className="w-5 h-5 text-purple-500" />
-                </div>
-                <div>
-                  <p className="text-xs text-muted-foreground font-medium">Links</p>
-                  <p className="text-2xl font-bold text-foreground">{stats.total_links}</p>
-                </div>
-              </div>
-            </CardContent>
-          </Card>
-
-          <Card className="bg-gradient-to-br from-emerald-500/10 to-emerald-600/5 border-emerald-500/20">
-            <CardContent className="p-4">
-              <div className="flex items-center gap-3">
-                <div className="p-2 rounded-lg bg-emerald-500/20">
-                  <FolderOpen className="w-5 h-5 text-emerald-500" />
-                </div>
-                <div>
-                  <p className="text-xs text-muted-foreground font-medium">Documents</p>
-                  <p className="text-2xl font-bold text-foreground">{stats.total_documents}</p>
-                </div>
-              </div>
-            </CardContent>
-          </Card>
-
-          <Card
-            className={`bg-gradient-to-br ${stats.pending_operations > 0 ? "from-amber-500/10 to-amber-600/5 border-amber-500/20" : "from-slate-500/10 to-slate-600/5 border-slate-500/20"}`}
-          >
-            <CardContent className="p-4">
-              <div className="flex items-center gap-3">
-                <div
-                  className={`p-2 rounded-lg ${stats.pending_operations > 0 ? "bg-amber-500/20" : "bg-slate-500/20"}`}
-                >
-                  <Activity
-                    className={`w-5 h-5 ${stats.pending_operations > 0 ? "text-amber-500 animate-pulse" : "text-slate-500"}`}
-                  />
-                </div>
-                <div>
-                  <p className="text-xs text-muted-foreground font-medium">Pending</p>
-                  <p className="text-2xl font-bold text-foreground">{stats.pending_operations}</p>
-                </div>
-              </div>
-            </CardContent>
-          </Card>
-        </div>
-      )}
-
-      {/* Memory Type Breakdown */}
-      {stats && (
-        <div className="grid grid-cols-5 gap-3">
-          <div className="bg-blue-500/10 border border-blue-500/20 rounded-xl p-4 text-center">
-            <p className="text-xs text-blue-600 dark:text-blue-400 font-semibold uppercase tracking-wide">
-              World Facts
-            </p>
-            <p className="text-2xl font-bold text-blue-600 dark:text-blue-400 mt-1">
-              {stats.nodes_by_fact_type?.world || 0}
-            </p>
-          </div>
-          <div className="bg-purple-500/10 border border-purple-500/20 rounded-xl p-4 text-center">
-            <p className="text-xs text-purple-600 dark:text-purple-400 font-semibold uppercase tracking-wide">
-              Experience
-            </p>
-            <p className="text-2xl font-bold text-purple-600 dark:text-purple-400 mt-1">
-              {stats.nodes_by_fact_type?.experience || 0}
-            </p>
-          </div>
-          <div
-            className={`rounded-xl p-4 text-center ${
-              observationsEnabled
-                ? "bg-amber-500/10 border border-amber-500/20"
-                : "bg-muted/50 border border-muted"
-            }`}
-            title={!observationsEnabled ? "Observations feature is not enabled" : undefined}
-          >
-            <p
-              className={`text-xs font-semibold uppercase tracking-wide ${
-                observationsEnabled ? "text-amber-600 dark:text-amber-400" : "text-muted-foreground"
-              }`}
-            >
-              Observations
-              {!observationsEnabled && <span className="ml-1 normal-case">(Off)</span>}
-            </p>
-            <p
-              className={`text-2xl font-bold mt-1 ${
-                observationsEnabled ? "text-amber-600 dark:text-amber-400" : "text-muted-foreground"
-              }`}
-            >
-              {observationsEnabled ? stats.total_mental_models || 0 : "—"}
-            </p>
-          </div>
-          <div className="bg-cyan-500/10 border border-cyan-500/20 rounded-xl p-4 text-center">
-            <p className="text-xs text-cyan-600 dark:text-cyan-400 font-semibold uppercase tracking-wide">
-              Mental Models
-            </p>
-            <p className="text-2xl font-bold text-cyan-600 dark:text-cyan-400 mt-1">
-              {mentalModelsCount}
-            </p>
-          </div>
-          <div className="bg-rose-500/10 border border-rose-500/20 rounded-xl p-4 text-center">
-            <p className="text-xs text-rose-600 dark:text-rose-400 font-semibold uppercase tracking-wide">
-              Directives
-            </p>
-            <p className="text-2xl font-bold text-rose-600 dark:text-rose-400 mt-1">
-              {directives.length}
-            </p>
-          </div>
-        </div>
-      )}
-
       <div className="grid grid-cols-1 lg:grid-cols-2 gap-6">
         {/* Disposition Chart */}
         <Card>
           <CardHeader className="pb-2">
-            <CardTitle className="flex items-center gap-2 text-lg">
-              <Brain className="w-5 h-5 text-primary" />
-              Disposition Profile
-            </CardTitle>
-            <CardDescription>
-              Traits that shape how observations are formed via Reflect
-            </CardDescription>
+            <div className="flex items-start justify-between">
+              <div>
+                <CardTitle className="flex items-center gap-2 text-lg">
+                  <Brain className="w-5 h-5 text-primary" />
+                  Disposition Profile
+                </CardTitle>
+                <CardDescription>Traits that shape the reasoning and perspective</CardDescription>
+              </div>
+              <Button onClick={() => setShowDispositionDialog(true)} variant="ghost" size="sm">
+                <Pencil className="h-4 w-4" />
+              </Button>
+            </div>
           </CardHeader>
           <CardContent>
             {profile && (
-              <DispositionEditor
-                disposition={profile.disposition}
-                editMode={editMode}
-                editDisposition={editDisposition}
-                onEditChange={(trait, value) =>
-                  setEditDisposition((prev) => ({ ...prev, [trait]: value }))
-                }
-              />
+              <div className="space-y-4">
+                {(Object.keys(TRAIT_LABELS) as Array<keyof DispositionTraits>).map((trait) => (
+                  <div key={trait} className="space-y-2">
+                    <div className="flex justify-between items-center">
+                      <div>
+                        <label className="text-sm font-medium text-foreground">
+                          {TRAIT_LABELS[trait].label}
+                        </label>
+                        <p className="text-xs text-muted-foreground">
+                          {TRAIT_LABELS[trait].description}
+                        </p>
+                      </div>
+                      <span className="text-sm font-bold text-primary">
+                        {profile.disposition[trait]}/5
+                      </span>
+                    </div>
+                    <div className="flex items-center gap-2">
+                      <span className="text-xs text-muted-foreground">
+                        {TRAIT_LABELS[trait].lowLabel}
+                      </span>
+                      <div className="flex-1 h-2 bg-muted rounded-full overflow-hidden">
+                        <div
+                          className="h-full bg-primary rounded-full transition-all"
+                          style={{ width: `${((profile.disposition[trait] - 1) / 4) * 100}%` }}
+                        />
+                      </div>
+                      <span className="text-xs text-muted-foreground">
+                        {TRAIT_LABELS[trait].highLabel}
+                      </span>
+                    </div>
+                  </div>
+                ))}
+              </div>
             )}
           </CardContent>
         </Card>
@@ -740,30 +453,26 @@ export function BankProfileView() {
         {/* Mission */}
         <Card>
           <CardHeader className="pb-2">
-            <CardTitle className="flex items-center gap-2 text-lg">
-              <Target className="w-5 h-5 text-primary" />
-              Mission
-            </CardTitle>
-            <CardDescription>
-              Who the agent is and what they&apos;re trying to accomplish. Used for mental models
-              and reflect.
-            </CardDescription>
+            <div className="flex items-start justify-between">
+              <div>
+                <CardTitle className="flex items-center gap-2 text-lg">
+                  <Target className="w-5 h-5 text-primary" />
+                  Mission
+                </CardTitle>
+                <CardDescription>
+                  Affects how observations, reflect, and mental models are created
+                </CardDescription>
+              </div>
+              <Button onClick={() => setShowMissionDialog(true)} variant="ghost" size="sm">
+                <Pencil className="h-4 w-4" />
+              </Button>
+            </div>
           </CardHeader>
           <CardContent>
-            {editMode ? (
-              <Textarea
-                value={editMission}
-                onChange={(e) => setEditMission(e.target.value)}
-                placeholder="e.g., I am a PM for the engineering team. I help coordinate sprints and track project progress..."
-                rows={6}
-                className="resize-none"
-              />
-            ) : (
-              <p className="text-sm text-foreground whitespace-pre-wrap leading-relaxed">
-                {profile?.mission ||
-                  "No mission set. Set a mission to derive structural mental models and personalize reflect responses."}
-              </p>
-            )}
+            <p className="text-sm text-foreground whitespace-pre-wrap leading-relaxed">
+              {profile?.mission ||
+                "No mission set. Set a mission to derive structural mental models and personalize reflect responses."}
+            </p>
           </CardContent>
         </Card>
       </div>
@@ -841,158 +550,6 @@ export function BankProfileView() {
         </CardContent>
       </Card>
 
-      {/* Operations Section */}
-      <Card>
-        <CardHeader className="pb-2">
-          <div className="flex items-center justify-between">
-            <div>
-              <CardTitle className="flex items-center gap-2 text-lg">
-                <Activity className="w-5 h-5 text-primary" />
-                Background Operations
-                <button
-                  onClick={() => loadOperations()}
-                  className="p-1 rounded hover:bg-muted transition-colors"
-                  title="Refresh operations"
-                >
-                  <RefreshCw className="w-4 h-4 text-muted-foreground hover:text-foreground" />
-                </button>
-              </CardTitle>
-              <CardDescription>
-                {totalOperations} operation{totalOperations !== 1 ? "s" : ""}
-                {opsStatusFilter ? ` (${opsStatusFilter})` : ""}
-              </CardDescription>
-            </div>
-            <div className="flex gap-1 bg-muted p-1 rounded-lg">
-              {[
-                { value: null, label: "All" },
-                { value: "pending", label: "Pending" },
-                { value: "completed", label: "Completed" },
-                { value: "failed", label: "Failed" },
-              ].map((filter) => (
-                <button
-                  key={filter.value ?? "all"}
-                  onClick={() => handleOpsFilterChange(filter.value)}
-                  className={`px-3 py-1.5 text-sm font-medium rounded-md transition-colors ${
-                    opsStatusFilter === filter.value
-                      ? "bg-background shadow-sm"
-                      : "text-muted-foreground hover:text-foreground"
-                  }`}
-                >
-                  {filter.label}
-                </button>
-              ))}
-            </div>
-          </div>
-        </CardHeader>
-        <CardContent>
-          {operations.length > 0 ? (
-            <>
-              <div className="overflow-x-auto">
-                <Table>
-                  <TableHeader>
-                    <TableRow>
-                      <TableHead className="w-[100px]">ID</TableHead>
-                      <TableHead>Type</TableHead>
-                      <TableHead>Created</TableHead>
-                      <TableHead>Status</TableHead>
-                      <TableHead className="w-[80px]"></TableHead>
-                    </TableRow>
-                  </TableHeader>
-                  <TableBody>
-                    {operations.map((op) => (
-                      <TableRow
-                        key={op.id}
-                        className={op.status === "failed" ? "bg-red-500/5" : ""}
-                      >
-                        <TableCell className="font-mono text-xs text-muted-foreground">
-                          {op.id.substring(0, 8)}
-                        </TableCell>
-                        <TableCell className="font-medium">{op.task_type}</TableCell>
-                        <TableCell className="text-sm text-muted-foreground">
-                          {new Date(op.created_at).toLocaleString()}
-                        </TableCell>
-                        <TableCell>
-                          {op.status === "pending" && (
-                            <span className="inline-flex items-center gap-1.5 px-2 py-0.5 rounded-full text-xs font-medium bg-amber-500/10 text-amber-600 dark:text-amber-400 border border-amber-500/20">
-                              <Clock className="w-3 h-3" />
-                              pending
-                            </span>
-                          )}
-                          {op.status === "failed" && (
-                            <span
-                              className="inline-flex items-center gap-1.5 px-2 py-0.5 rounded-full text-xs font-medium bg-red-500/10 text-red-600 dark:text-red-400 border border-red-500/20"
-                              title={op.error_message ?? undefined}
-                            >
-                              <AlertCircle className="w-3 h-3" />
-                              failed
-                            </span>
-                          )}
-                          {op.status === "completed" && (
-                            <span className="inline-flex items-center gap-1.5 px-2 py-0.5 rounded-full text-xs font-medium bg-emerald-500/10 text-emerald-600 dark:text-emerald-400 border border-emerald-500/20">
-                              <CheckCircle className="w-3 h-3" />
-                              completed
-                            </span>
-                          )}
-                        </TableCell>
-                        <TableCell>
-                          {op.status === "pending" && (
-                            <Button
-                              variant="ghost"
-                              size="sm"
-                              className="h-7 text-xs text-muted-foreground hover:text-red-600 dark:hover:text-red-400"
-                              onClick={() => handleCancelOperation(op.id)}
-                              disabled={cancellingOpId === op.id}
-                            >
-                              {cancellingOpId === op.id ? (
-                                <Loader2 className="w-3 h-3 animate-spin" />
-                              ) : (
-                                <X className="w-3 h-3 mr-1" />
-                              )}
-                              {cancellingOpId === op.id ? "" : "Cancel"}
-                            </Button>
-                          )}
-                        </TableCell>
-                      </TableRow>
-                    ))}
-                  </TableBody>
-                </Table>
-              </div>
-              {/* Pagination */}
-              {totalOperations > opsLimit && (
-                <div className="flex items-center justify-between mt-4 pt-4 border-t">
-                  <p className="text-sm text-muted-foreground">
-                    Showing {opsOffset + 1}-{Math.min(opsOffset + opsLimit, totalOperations)} of{" "}
-                    {totalOperations}
-                  </p>
-                  <div className="flex gap-2">
-                    <Button
-                      variant="outline"
-                      size="sm"
-                      onClick={() => handleOpsPageChange(Math.max(0, opsOffset - opsLimit))}
-                      disabled={opsOffset === 0}
-                    >
-                      Previous
-                    </Button>
-                    <Button
-                      variant="outline"
-                      size="sm"
-                      onClick={() => handleOpsPageChange(opsOffset + opsLimit)}
-                      disabled={opsOffset + opsLimit >= totalOperations}
-                    >
-                      Next
-                    </Button>
-                  </div>
-                </div>
-              )}
-            </>
-          ) : (
-            <p className="text-muted-foreground text-center py-8 text-sm">
-              No {opsStatusFilter ? `${opsStatusFilter} ` : ""}operations
-            </p>
-          )}
-        </CardContent>
-      </Card>
-
       {/* Delete Confirmation Dialog */}
       <AlertDialog open={showDeleteDialog} onOpenChange={setShowDeleteDialog}>
         <AlertDialogContent>
@@ -1142,10 +699,197 @@ export function BankProfileView() {
           }}
         />
       )}
+
+      {/* Disposition Edit Dialog */}
+      {showDispositionDialog && profile && (
+        <DispositionEditDialog
+          disposition={profile.disposition}
+          onClose={() => setShowDispositionDialog(false)}
+          onSaved={async () => {
+            await loadData();
+            setShowDispositionDialog(false);
+          }}
+        />
+      )}
+
+      {/* Mission Edit Dialog */}
+      {showMissionDialog && profile && (
+        <MissionEditDialog
+          mission={profile.mission || ""}
+          onClose={() => setShowMissionDialog(false)}
+          onSaved={async () => {
+            await loadData();
+            setShowMissionDialog(false);
+          }}
+        />
+      )}
     </div>
   );
 }
 
+// ============= DISPOSITION EDIT DIALOG =============
+
+function DispositionEditDialog({
+  disposition,
+  onClose,
+  onSaved,
+}: {
+  disposition: DispositionTraits;
+  onClose: () => void;
+  onSaved: () => void;
+}) {
+  const { currentBank } = useBank();
+  const [saving, setSaving] = useState(false);
+  const [editDisposition, setEditDisposition] = useState<DispositionTraits>(disposition);
+
+  const handleSave = async () => {
+    if (!currentBank) return;
+
+    setSaving(true);
+    try {
+      await client.updateBankProfile(currentBank, {
+        disposition: editDisposition,
+      });
+      onSaved();
+    } catch (error) {
+      console.error("Error saving disposition:", error);
+      alert("Error saving disposition: " + (error as Error).message);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <Dialog open onOpenChange={onClose}>
+      <DialogContent className="max-w-xl">
+        <DialogHeader>
+          <DialogTitle>Edit Disposition Traits</DialogTitle>
+          <DialogDescription>Traits that shape the reasoning and perspective</DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-4 py-4">
+          {(Object.keys(TRAIT_LABELS) as Array<keyof DispositionTraits>).map((trait) => (
+            <div key={trait} className="space-y-2">
+              <div className="flex justify-between items-center">
+                <div>
+                  <label className="text-sm font-medium text-foreground">
+                    {TRAIT_LABELS[trait].label}
+                  </label>
+                  <p className="text-xs text-muted-foreground">{TRAIT_LABELS[trait].description}</p>
+                </div>
+                <span className="text-sm font-bold text-primary">{editDisposition[trait]}/5</span>
+              </div>
+              <div className="flex justify-between text-[10px] text-muted-foreground">
+                <span>{TRAIT_LABELS[trait].lowLabel}</span>
+                <span>{TRAIT_LABELS[trait].highLabel}</span>
+              </div>
+              <input
+                type="range"
+                min="1"
+                max="5"
+                step="1"
+                value={editDisposition[trait]}
+                onChange={(e) =>
+                  setEditDisposition((prev) => ({ ...prev, [trait]: parseInt(e.target.value) }))
+                }
+                className="w-full h-2 bg-muted rounded-lg appearance-none cursor-pointer accent-primary"
+              />
+            </div>
+          ))}
+        </div>
+
+        <DialogFooter>
+          <Button onClick={onClose} variant="outline" disabled={saving}>
+            Cancel
+          </Button>
+          <Button onClick={handleSave} disabled={saving}>
+            {saving ? (
+              <>
+                <RefreshCw className="w-4 h-4 mr-2 animate-spin" />
+                Saving...
+              </>
+            ) : (
+              "Save Changes"
+            )}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
+// ============= MISSION EDIT DIALOG =============
+
+function MissionEditDialog({
+  mission,
+  onClose,
+  onSaved,
+}: {
+  mission: string;
+  onClose: () => void;
+  onSaved: () => void;
+}) {
+  const { currentBank } = useBank();
+  const [saving, setSaving] = useState(false);
+  const [editMission, setEditMission] = useState(mission);
+
+  const handleSave = async () => {
+    if (!currentBank) return;
+
+    setSaving(true);
+    try {
+      await client.updateBankProfile(currentBank, {
+        mission: editMission,
+      });
+      onSaved();
+    } catch (error) {
+      console.error("Error saving mission:", error);
+      alert("Error saving mission: " + (error as Error).message);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <Dialog open onOpenChange={onClose}>
+      <DialogContent className="max-w-xl">
+        <DialogHeader>
+          <DialogTitle>Edit Mission</DialogTitle>
+          <DialogDescription>
+            Affects how observations, reflect, and mental models are created
+          </DialogDescription>
+        </DialogHeader>
+
+        <div className="space-y-2 py-4">
+          <Textarea
+            value={editMission}
+            onChange={(e) => setEditMission(e.target.value)}
+            placeholder="e.g., I am a PM for the engineering team. I help coordinate sprints and track project progress..."
+            rows={8}
+            className="resize-none"
+          />
+        </div>
+
+        <DialogFooter>
+          <Button onClick={onClose} variant="outline" disabled={saving}>
+            Cancel
+          </Button>
+          <Button onClick={handleSave} disabled={saving}>
+            {saving ? (
+              <>
+                <RefreshCw className="w-4 h-4 mr-2 animate-spin" />
+                Saving...
+              </>
+            ) : (
+              "Save Changes"
+            )}
+          </Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  );
+}
+
 // ============= DIRECTIVE FORM DIALOG (CREATE/EDIT) =============
 
 function DirectiveFormDialog({

hindsight-control-plane/src/components/bank-stats-view.tsx

@@ -0,0 +1,208 @@
+"use client";
+
+import { useState, useEffect } from "react";
+import { useBank } from "@/lib/bank-context";
+import { useFeatures } from "@/lib/features-context";
+import { client } from "@/lib/api";
+import { Card, CardContent } from "@/components/ui/card";
+import { Database, Link2, FolderOpen, Activity, Clock } from "lucide-react";
+
+interface BankStats {
+  bank_id: string;
+  total_nodes: number;
+  total_links: number;
+  total_documents: number;
+  nodes_by_fact_type: {
+    world?: number;
+    experience?: number;
+    opinion?: number;
+  };
+  links_by_link_type: {
+    temporal?: number;
+    semantic?: number;
+    entity?: number;
+  };
+  pending_operations: number;
+  failed_operations: number;
+  last_consolidated_at: string | null;
+  pending_consolidation: number;
+  total_mental_models: number;
+}
+
+export function BankStatsView() {
+  const { currentBank } = useBank();
+  const { features } = useFeatures();
+  const observationsEnabled = features?.observations ?? false;
+  const [stats, setStats] = useState<BankStats | null>(null);
+  const [mentalModelsCount, setMentalModelsCount] = useState(0);
+  const [directivesCount, setDirectivesCount] = useState(0);
+  const [loading, setLoading] = useState(false);
+
+  const loadData = async () => {
+    if (!currentBank) return;
+
+    setLoading(true);
+    try {
+      const [statsData, mentalModelsData, directivesData] = await Promise.all([
+        client.getBankStats(currentBank),
+        client.listMentalModels(currentBank),
+        client.listDirectives(currentBank),
+      ]);
+      setStats(statsData as BankStats);
+      setMentalModelsCount(mentalModelsData.items?.length || 0);
+      setDirectivesCount(directivesData.items?.length || 0);
+    } catch (error) {
+      console.error("Error loading bank stats:", error);
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  useEffect(() => {
+    if (currentBank) {
+      loadData();
+      // Refresh stats every 5 seconds
+      const interval = setInterval(loadData, 5000);
+      return () => clearInterval(interval);
+    }
+  }, [currentBank]);
+
+  if (loading && !stats) {
+    return (
+      <div className="flex items-center justify-center py-12">
+        <Clock className="w-12 h-12 mx-auto mb-3 text-muted-foreground animate-pulse" />
+      </div>
+    );
+  }
+
+  if (!stats) return null;
+
+  return (
+    <div className="space-y-6">
+      {/* Stats Overview - Compact cards */}
+      <div className="grid grid-cols-2 md:grid-cols-4 gap-4">
+        <Card className="bg-gradient-to-br from-blue-500/10 to-blue-600/5 border-blue-500/20">
+          <CardContent className="p-4">
+            <div className="flex items-center gap-3">
+              <div className="p-2 rounded-lg bg-blue-500/20">
+                <Database className="w-5 h-5 text-blue-500" />
+              </div>
+              <div>
+                <p className="text-xs text-muted-foreground font-medium">Memories</p>
+                <p className="text-2xl font-bold text-foreground">{stats.total_nodes}</p>
+              </div>
+            </div>
+          </CardContent>
+        </Card>
+
+        <Card className="bg-gradient-to-br from-purple-500/10 to-purple-600/5 border-purple-500/20">
+          <CardContent className="p-4">
+            <div className="flex items-center gap-3">
+              <div className="p-2 rounded-lg bg-purple-500/20">
+                <Link2 className="w-5 h-5 text-purple-500" />
+              </div>
+              <div>
+                <p className="text-xs text-muted-foreground font-medium">Links</p>
+                <p className="text-2xl font-bold text-foreground">{stats.total_links}</p>
+              </div>
+            </div>
+          </CardContent>
+        </Card>
+
+        <Card className="bg-gradient-to-br from-emerald-500/10 to-emerald-600/5 border-emerald-500/20">
+          <CardContent className="p-4">
+            <div className="flex items-center gap-3">
+              <div className="p-2 rounded-lg bg-emerald-500/20">
+                <FolderOpen className="w-5 h-5 text-emerald-500" />
+              </div>
+              <div>
+                <p className="text-xs text-muted-foreground font-medium">Documents</p>
+                <p className="text-2xl font-bold text-foreground">{stats.total_documents}</p>
+              </div>
+            </div>
+          </CardContent>
+        </Card>
+
+        <Card
+          className={`bg-gradient-to-br ${stats.pending_operations > 0 ? "from-amber-500/10 to-amber-600/5 border-amber-500/20" : "from-slate-500/10 to-slate-600/5 border-slate-500/20"}`}
+        >
+          <CardContent className="p-4">
+            <div className="flex items-center gap-3">
+              <div
+                className={`p-2 rounded-lg ${stats.pending_operations > 0 ? "bg-amber-500/20" : "bg-slate-500/20"}`}
+              >
+                <Activity
+                  className={`w-5 h-5 ${stats.pending_operations > 0 ? "text-amber-500 animate-pulse" : "text-slate-500"}`}
+                />
+              </div>
+              <div>
+                <p className="text-xs text-muted-foreground font-medium">Pending</p>
+                <p className="text-2xl font-bold text-foreground">{stats.pending_operations}</p>
+              </div>
+            </div>
+          </CardContent>
+        </Card>
+      </div>
+
+      {/* Memory Type Breakdown */}
+      <div className="grid grid-cols-5 gap-3">
+        <div className="bg-blue-500/10 border border-blue-500/20 rounded-xl p-4 text-center">
+          <p className="text-xs text-blue-600 dark:text-blue-400 font-semibold uppercase tracking-wide">
+            World Facts
+          </p>
+          <p className="text-2xl font-bold text-blue-600 dark:text-blue-400 mt-1">
+            {stats.nodes_by_fact_type?.world || 0}
+          </p>
+        </div>
+        <div className="bg-purple-500/10 border border-purple-500/20 rounded-xl p-4 text-center">
+          <p className="text-xs text-purple-600 dark:text-purple-400 font-semibold uppercase tracking-wide">
+            Experience
+          </p>
+          <p className="text-2xl font-bold text-purple-600 dark:text-purple-400 mt-1">
+            {stats.nodes_by_fact_type?.experience || 0}
+          </p>
+        </div>
+        <div
+          className={`rounded-xl p-4 text-center ${
+            observationsEnabled
+              ? "bg-amber-500/10 border border-amber-500/20"
+              : "bg-muted/50 border border-muted"
+          }`}
+          title={!observationsEnabled ? "Observations feature is not enabled" : undefined}
+        >
+          <p
+            className={`text-xs font-semibold uppercase tracking-wide ${
+              observationsEnabled ? "text-amber-600 dark:text-amber-400" : "text-muted-foreground"
+            }`}
+          >
+            Observations
+            {!observationsEnabled && <span className="ml-1 normal-case">(Off)</span>}
+          </p>
+          <p
+            className={`text-2xl font-bold mt-1 ${
+              observationsEnabled ? "text-amber-600 dark:text-amber-400" : "text-muted-foreground"
+            }`}
+          >
+            {observationsEnabled ? stats.total_mental_models || 0 : "—"}
+          </p>
+        </div>
+        <div className="bg-cyan-500/10 border border-cyan-500/20 rounded-xl p-4 text-center">
+          <p className="text-xs text-cyan-600 dark:text-cyan-400 font-semibold uppercase tracking-wide">
+            Mental Models
+          </p>
+          <p className="text-2xl font-bold text-cyan-600 dark:text-cyan-400 mt-1">
+            {mentalModelsCount}
+          </p>
+        </div>
+        <div className="bg-rose-500/10 border border-rose-500/20 rounded-xl p-4 text-center">
+          <p className="text-xs text-rose-600 dark:text-rose-400 font-semibold uppercase tracking-wide">
+            Directives
+          </p>
+          <p className="text-2xl font-bold text-rose-600 dark:text-rose-400 mt-1">
+            {directivesCount}
+          </p>
+        </div>
+      </div>
+    </div>
+  );
+}

hindsight-control-plane/src/components/sidebar.tsx

@@ -2,6 +2,7 @@
 
 import { useState } from "react";
 import { useBank } from "@/lib/bank-context";
+import { useFeatures } from "@/lib/features-context";
 import {
   Search,
   Sparkles,
@@ -11,6 +12,7 @@ import {
   ChevronLeft,
   ChevronRight,
   Box,
+  Settings,
 } from "lucide-react";
 import { cn } from "@/lib/utils";
 import Link from "next/link";
@@ -24,6 +26,7 @@ interface SidebarProps {
 
 export function Sidebar({ currentTab, onTabChange }: SidebarProps) {
   const { currentBank } = useBank();
+  const { features } = useFeatures();
   const [isCollapsed, setIsCollapsed] = useState(true);
 
   if (!currentBank) {
@@ -36,7 +39,7 @@ export function Sidebar({ currentTab, onTabChange }: SidebarProps) {
     { id: "reflect" as NavItem, label: "Reflect", icon: Sparkles },
     { id: "documents" as NavItem, label: "Documents", icon: FileText },
     { id: "entities" as NavItem, label: "Entities", icon: Users },
-    { id: "profile" as NavItem, label: "Memory Bank", icon: Box },
+    { id: "profile" as NavItem, label: "Bank Configuration", icon: Settings },
   ];
 
   return (

hindsight-control-plane/src/components/ui/alert.tsx

@@ -0,0 +1,49 @@
+import * as React from "react";
+import { cva, type VariantProps } from "class-variance-authority";
+
+import { cn } from "@/lib/utils";
+
+const alertVariants = cva(
+  "relative w-full rounded-lg border px-4 py-3 text-sm [&>svg+div]:translate-y-[-3px] [&>svg]:absolute [&>svg]:left-4 [&>svg]:top-4 [&>svg]:text-foreground [&>svg~*]:pl-7",
+  {
+    variants: {
+      variant: {
+        default: "bg-background text-foreground",
+        destructive:
+          "border-destructive/50 text-destructive dark:border-destructive [&>svg]:text-destructive",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+);
+
+const Alert = React.forwardRef<
+  HTMLDivElement,
+  React.HTMLAttributes<HTMLDivElement> & VariantProps<typeof alertVariants>
+>(({ className, variant, ...props }, ref) => (
+  <div ref={ref} role="alert" className={cn(alertVariants({ variant }), className)} {...props} />
+));
+Alert.displayName = "Alert";
+
+const AlertTitle = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLHeadingElement>>(
+  ({ className, ...props }, ref) => (
+    <h5
+      ref={ref}
+      className={cn("mb-1 font-medium leading-none tracking-tight", className)}
+      {...props}
+    />
+  )
+);
+AlertTitle.displayName = "AlertTitle";
+
+const AlertDescription = React.forwardRef<
+  HTMLParagraphElement,
+  React.HTMLAttributes<HTMLParagraphElement>
+>(({ className, ...props }, ref) => (
+  <div ref={ref} className={cn("text-sm [&_p]:leading-relaxed", className)} {...props} />
+));
+AlertDescription.displayName = "AlertDescription";
+
+export { Alert, AlertTitle, AlertDescription };

hindsight-control-plane/src/lib/api.ts

@@ -684,9 +684,48 @@ export class ControlPlaneClient {
         observations: boolean;
         mcp: boolean;
         worker: boolean;
+        bank_config_api: boolean;
       };
     }>("/api/version");
   }
+
+  /**
+   * Get bank configuration (resolved with hierarchy)
+   */
+  async getBankConfig(bankId: string) {
+    return this.fetchApi<{
+      bank_id: string;
+      config: Record<string, any>;
+      overrides: Record<string, any>;
+    }>(`/api/banks/${bankId}/config`);
+  }
+
+  /**
+   * Update bank configuration overrides
+   */
+  async updateBankConfig(bankId: string, updates: Record<string, any>) {
+    return this.fetchApi<{
+      bank_id: string;
+      config: Record<string, any>;
+      overrides: Record<string, any>;
+    }>(`/api/banks/${bankId}/config`, {
+      method: "PATCH",
+      body: JSON.stringify({ updates }),
+    });
+  }
+
+  /**
+   * Reset bank configuration to defaults
+   */
+  async resetBankConfig(bankId: string) {
+    return this.fetchApi<{
+      bank_id: string;
+      config: Record<string, any>;
+      overrides: Record<string, any>;
+    }>(`/api/banks/${bankId}/config`, {
+      method: "DELETE",
+    });
+  }
 }
 
 // Export singleton instance

hindsight-control-plane/src/lib/features-context.tsx

@@ -7,6 +7,7 @@ interface Features {
   observations: boolean;
   mcp: boolean;
   worker: boolean;
+  bank_config_api: boolean;
 }
 
 interface FeaturesContextType {
@@ -19,6 +20,7 @@ const defaultFeatures: Features = {
   observations: false,
   mcp: false,
   worker: false,
+  bank_config_api: false,
 };
 
 const FeaturesContext = createContext<FeaturesContextType | undefined>(undefined);

hindsight-docs/blog/2026-02-09-resolving-memory-conflicts.md

@@ -1,4 +1,14 @@
+---
+title: How We Solved Memory Conflicts in Hindsight
+description: Learn how Hindsight handles contradictory information by tracking temporal evolution and preserving history in its memory consolidation system.
+authors: [hindsight]
+tags: [engineering, memory-systems, conflict-resolution]
+image: /img/blog/2026-02-09/consolidation-pipeline.png
+date: 2026-02-09
+---
+
 # How We Solved Memory Conflicts in Hindsight
+
 One of the hardest problems we tackled in Hindsight was dealing with contradictions. When you're building a memory system for AI agents, reality isn't static. It evolves. 
 
 A CRM agent might learn that "Acme Corp is a key prospect" in January, then encounter "Acme Corp is now a paying customer" in March. Naive approaches either lose the history or drown in duplicate facts.

hindsight-docs/docs/developer/api/recall.mdx

@@ -44,10 +44,10 @@ Make sure you've completed the [Quick Start](./quickstart) to install the client
 | `query` | string | required | Natural language query |
 | `types` | list | all | Filter: `world`, `experience`, `observation` |
 | `budget` | string | "mid" | Budget level: `low`, `mid`, `high` |
-| `max_tokens` | int | 4096 | Token budget for results |
+| `max_tokens` | int | 4096 | Token budget for memory facts (text only) |
 | `trace` | bool | false | Enable trace output for debugging |
 | `include_chunks` | bool | false | Include raw text chunks that generated the memories |
-| `max_chunk_tokens` | int | 500 | Token budget for chunks |
+| `max_chunk_tokens` | int | 500 | Token budget for chunks (independent of `max_tokens`) |
 | `tags` | list | None | Filter memories by tags (see [Tag Filtering](#filter-by-tags)) |
 | `tags_match` | string | "any" | How to match tags: `any`, `all`, `any_strict`, `all_strict` |
 
@@ -93,6 +93,15 @@ The `max_tokens` parameter lets you control how much of your agent's context bud
 
 This design means you never have to guess whether 10 results or 50 results will fit your context. Just specify the token budget and Hindsight returns as many relevant memories as will fit.
 
+:::note Chunks are Independent
+When `include_chunks=True`, chunks are fetched **independently** of the `max_tokens` filtering. This means:
+- Setting `max_tokens=0` will return **0 memory facts** but can still return **chunks** (up to `max_chunk_tokens`)
+- Chunks are based on the top-scored (reranked) results **before** token filtering
+- Chunks are fetched in batches (batch size estimated as `(max_chunk_tokens / retain_chunk_size) * 2`) until the token budget is exhausted
+- This batching approach handles varying chunk sizes across documents efficiently
+- This allows you to retrieve raw source text without memory facts when needed
+:::
+
 ## Budget Levels
 
 The `budget` parameter controls graph traversal depth:

hindsight-docs/docs/developer/configuration.md

@@ -57,6 +57,71 @@ hindsight-admin run-db-migration
 hindsight-admin run-db-migration --schema tenant_acme
 ```
 
+### Vector Extension
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HINDSIGHT_API_VECTOR_EXTENSION` | Vector extension to use: `auto`, `pgvector`, or `vchord` | `auto` |
+
+Hindsight supports two PostgreSQL vector extensions:
+- **pgvector**: Standard extension, works well for most embeddings (up to ~2000 dimensions)
+- **vchord**: Optimized for high-dimensional embeddings (3000+ dimensions), includes BM25 search
+
+When set to `auto` (default), Hindsight automatically detects which extension is installed, preferring vchord if both are available.
+
+**When to use vchord:**
+- Using high-dimensional embeddings (e.g., `text-embedding-3-large` with 3072 dimensions)
+- Need better performance with large embedding dimensions
+- Want to use vchord's BM25 search capabilities
+
+**When to use pgvector:**
+- Using standard embedding dimensions (384-1536)
+- Prefer the widely-adopted pgvector extension
+- Simpler deployment (pgvector is more commonly available)
+
+**Switching extensions:**
+
+If you need to switch from one extension to another:
+1. Set `HINDSIGHT_API_VECTOR_EXTENSION` to your desired extension (`pgvector` or `vchord`)
+2. If your database has existing data, you'll get an error with migration instructions
+3. For empty databases, indexes will be automatically recreated on startup
+
+### Text Search Extension
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HINDSIGHT_API_TEXT_SEARCH_EXTENSION` | Text search backend: `native`, `vchord`, or `pg_textsearch` | `native` |
+
+Hindsight supports three text search backends for BM25 keyword retrieval:
+- **native**: PostgreSQL's built-in full-text search (`tsvector` + GIN indexes)
+- **vchord**: VectorChord BM25 (`bm25vector` + BM25 indexes) - requires `vchord_bm25` extension
+- **pg_textsearch**: Timescale BM25 (text columns + BM25 indexes) - requires `pg_textsearch` extension
+
+**When to use native:**
+- Standard PostgreSQL deployment (no extra extensions)
+- Simpler setup and wider compatibility
+- Works well for most use cases
+
+**When to use vchord:**
+- Already using vchord for vector search (good integration)
+- Want better BM25 ranking performance
+- Need advanced tokenization (uses `llmlingua2` tokenizer)
+
+**When to use pg_textsearch:**
+- Want industry-standard BM25 ranking with better relevance than native PostgreSQL
+- Need efficient top-K queries with Block-Max WAND optimization
+- Prefer lower memory footprint compared to vchord
+- Already using Timescale or have `pg_textsearch` available
+
+**Switching backends:**
+
+To switch between backends:
+1. Set `HINDSIGHT_API_TEXT_SEARCH_EXTENSION` to your desired backend (`native`, `vchord`, or `pg_textsearch`)
+2. If your database has existing data, you'll get an error with migration instructions
+3. For empty databases, the columns/indexes will be automatically recreated on startup
+
+**Note:** VectorChord uses the `llmlingua2` tokenizer for multilingual support, while native and pg_textsearch use PostgreSQL's English tokenizer.
+
 ### LLM Provider
 
 | Variable | Description | Default |
@@ -267,7 +332,7 @@ export HINDSIGHT_API_RETAIN_LLM_MAX_BACKOFF=120.0    # Cap at 2min instead of 1m
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `HINDSIGHT_API_EMBEDDINGS_PROVIDER` | Provider: `local`, `tei`, `openai`, `cohere`, or `litellm` | `local` |
+| `HINDSIGHT_API_EMBEDDINGS_PROVIDER` | Provider: `local`, `tei`, `openai`, `cohere`, `litellm`, or `litellm-sdk` | `local` |
 | `HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL` | Model for local provider | `BAAI/bge-small-en-v1.5` |
 | `HINDSIGHT_API_EMBEDDINGS_LOCAL_TRUST_REMOTE_CODE` | Allow loading models with custom code (security risk, disabled by default) | `false` |
 | `HINDSIGHT_API_EMBEDDINGS_TEI_URL` | TEI server URL | - |
@@ -280,6 +345,9 @@ export HINDSIGHT_API_RETAIN_LLM_MAX_BACKOFF=120.0    # Cap at 2min instead of 1m
 | `HINDSIGHT_API_EMBEDDINGS_LITELLM_API_BASE` | LiteLLM proxy base URL for embeddings | `http://localhost:4000` |
 | `HINDSIGHT_API_EMBEDDINGS_LITELLM_API_KEY` | LiteLLM proxy API key for embeddings (optional, depends on proxy config) | - |
 | `HINDSIGHT_API_EMBEDDINGS_LITELLM_MODEL` | LiteLLM embedding model (use provider prefix, e.g., `cohere/embed-english-v3.0`) | `text-embedding-3-small` |
+| `HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_API_KEY` | LiteLLM SDK API key for direct embedding provider access | - |
+| `HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_MODEL` | LiteLLM SDK embedding model (use provider prefix, e.g., `cohere/embed-english-v3.0`) | `cohere/embed-english-v3.0` |
+| `HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_API_BASE` | Custom base URL for LiteLLM SDK embeddings (optional) | - |
 
 ```bash
 # Local (default) - uses SentenceTransformers
@@ -322,6 +390,18 @@ export HINDSIGHT_API_EMBEDDINGS_PROVIDER=litellm
 export HINDSIGHT_API_EMBEDDINGS_LITELLM_API_BASE=http://localhost:4000
 export HINDSIGHT_API_EMBEDDINGS_LITELLM_API_KEY=your-litellm-key  # optional
 export HINDSIGHT_API_EMBEDDINGS_LITELLM_MODEL=text-embedding-3-small  # or cohere/embed-english-v3.0
+
+# LiteLLM SDK - direct API access without proxy server (recommended)
+export HINDSIGHT_API_EMBEDDINGS_PROVIDER=litellm-sdk
+export HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_API_KEY=your-provider-api-key
+export HINDSIGHT_API_EMBEDDINGS_LITELLM_SDK_MODEL=cohere/embed-english-v3.0
+
+# Supported LiteLLM SDK embedding providers:
+# - cohere/embed-english-v3.0 (1024 dimensions)
+# - openai/text-embedding-3-small (1536 dimensions)
+# - together_ai/togethercomputer/m2-bert-80M-8k-retrieval
+# - huggingface/sentence-transformers/all-MiniLM-L6-v2
+# - voyage/voyage-2
 ```
 
 #### Embedding Dimensions
@@ -344,7 +424,7 @@ Supported OpenAI embedding dimensions:
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `HINDSIGHT_API_RERANKER_PROVIDER` | Provider: `local`, `tei`, `cohere`, `flashrank`, `litellm`, or `rrf` | `local` |
+| `HINDSIGHT_API_RERANKER_PROVIDER` | Provider: `local`, `tei`, `cohere`, `flashrank`, `litellm`, `litellm-sdk`, or `rrf` | `local` |
 | `HINDSIGHT_API_RERANKER_LOCAL_MODEL` | Model for local provider | `cross-encoder/ms-marco-MiniLM-L-6-v2` |
 | `HINDSIGHT_API_RERANKER_LOCAL_MAX_CONCURRENT` | Max concurrent local reranking (prevents CPU thrashing under load) | `4` |
 | `HINDSIGHT_API_RERANKER_LOCAL_TRUST_REMOTE_CODE` | Allow loading models with custom code (security risk, disabled by default) | `false` |
@@ -356,7 +436,10 @@ Supported OpenAI embedding dimensions:
 | `HINDSIGHT_API_RERANKER_COHERE_BASE_URL` | Custom base URL for Cohere-compatible API (e.g., Azure-hosted) | - |
 | `HINDSIGHT_API_RERANKER_LITELLM_API_BASE` | LiteLLM proxy base URL for reranking | `http://localhost:4000` |
 | `HINDSIGHT_API_RERANKER_LITELLM_API_KEY` | LiteLLM proxy API key for reranking (optional, depends on proxy config) | - |
-| `HINDSIGHT_API_RERANKER_LITELLM_MODEL` | LiteLLM rerank model (use provider prefix, e.g., `cohere/rerank-english-v3.0`) | `cohere/rerank-english-v3.0` |
+| `HINDSIGHT_API_RERANKER_LITELLM_MODEL` | LiteLLM **proxy** rerank model (use provider prefix, e.g., `cohere/rerank-english-v3.0`) | `cohere/rerank-english-v3.0` |
+| `HINDSIGHT_API_RERANKER_LITELLM_SDK_API_KEY` | LiteLLM **SDK** API key for direct reranking (no proxy needed) | - |
+| `HINDSIGHT_API_RERANKER_LITELLM_SDK_MODEL` | LiteLLM SDK rerank model (e.g., `deepinfra/Qwen3-reranker-8B`) | `cohere/rerank-english-v3.0` |
+| `HINDSIGHT_API_RERANKER_LITELLM_SDK_API_BASE` | Custom API base URL for LiteLLM SDK (optional) | - |
 | `HINDSIGHT_API_RERANKER_FLASHRANK_MODEL` | FlashRank model for fast CPU-based reranking | `ms-marco-MiniLM-L-12-v2` |
 | `HINDSIGHT_API_RERANKER_FLASHRANK_CACHE_DIR` | Cache directory for FlashRank models | System default |
 
@@ -386,19 +469,31 @@ export HINDSIGHT_API_RERANKER_COHERE_API_KEY=your-azure-api-key
 export HINDSIGHT_API_RERANKER_COHERE_MODEL=rerank-english-v3.0
 export HINDSIGHT_API_RERANKER_COHERE_BASE_URL=https://your-azure-cohere-endpoint.com
 
-# LiteLLM proxy - unified gateway for multiple reranking providers
+# LiteLLM proxy - unified gateway for multiple reranking providers (requires running LiteLLM proxy server)
 export HINDSIGHT_API_RERANKER_PROVIDER=litellm
 export HINDSIGHT_API_RERANKER_LITELLM_API_BASE=http://localhost:4000
 export HINDSIGHT_API_RERANKER_LITELLM_API_KEY=your-litellm-key  # optional
 export HINDSIGHT_API_RERANKER_LITELLM_MODEL=cohere/rerank-english-v3.0  # or voyage/rerank-2, together_ai/...
+
+# LiteLLM SDK - direct API access without proxy (recommended for simplicity)
+export HINDSIGHT_API_RERANKER_PROVIDER=litellm-sdk
+export HINDSIGHT_API_RERANKER_LITELLM_SDK_API_KEY=your-deepinfra-api-key
+export HINDSIGHT_API_RERANKER_LITELLM_SDK_MODEL=deepinfra/Qwen3-reranker-8B  # or cohere/rerank-english-v3.0, etc.
 ```
 
-LiteLLM supports multiple reranking providers via the `/rerank` endpoint:
-- Cohere (`cohere/rerank-english-v3.0`, `cohere/rerank-multilingual-v3.0`)
-- Together AI (`together_ai/...`)
-- Voyage AI (`voyage/rerank-2`)
-- Jina AI (`jina_ai/...`)
-- AWS Bedrock (`bedrock/...`)
+#### LiteLLM Proxy vs SDK
+
+- **`litellm`**: Requires running a separate LiteLLM proxy server. Good for centralized configuration, rate limiting, and caching.
+- **`litellm-sdk`**: Direct API access without proxy. Simpler setup, lower latency, fewer infrastructure components.
+
+Both support the same providers:
+- **Cohere** (`cohere/rerank-english-v3.0`, `cohere/rerank-multilingual-v3.0`)
+- **DeepInfra** (`deepinfra/Qwen3-reranker-8B`, `deepinfra/bge-reranker-v2-m3`)
+- **Together AI** (`together_ai/Salesforce/Llama-Rank-V1`)
+- **HuggingFace** (`huggingface/BAAI/bge-reranker-v2-m3`)
+- **Voyage AI** (`voyage/rerank-2`)
+- **Jina AI** (`jina_ai/jina-reranker-v2`)
+- **AWS Bedrock** (`bedrock/...`)
 
 ### Authentication
 
@@ -429,6 +524,7 @@ For advanced authentication (JWT, OAuth, multi-tenant schemas), implement a cust
 |----------|-------------|---------|
 | `HINDSIGHT_API_HOST` | Bind address | `0.0.0.0` |
 | `HINDSIGHT_API_PORT` | Server port | `8888` |
+| `HINDSIGHT_API_BASE_PATH` | Base path for API when behind reverse proxy (e.g., `/hindsight`) | `""` (root) |
 | `HINDSIGHT_API_WORKERS` | Number of uvicorn worker processes | `1` |
 | `HINDSIGHT_API_LOG_LEVEL` | Log level: `debug`, `info`, `warning`, `error` | `info` |
 | `HINDSIGHT_API_LOG_FORMAT` | Log format: `text` or `json` (structured logging for cloud platforms) | `text` |
@@ -649,12 +745,198 @@ The Control Plane is the web UI for managing memory banks.
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `HINDSIGHT_CP_DATAPLANE_API_URL` | URL of the API service | `http://localhost:8888` |
+| `NEXT_PUBLIC_BASE_PATH` | Base path for Control Plane UI when behind reverse proxy (e.g., `/hindsight`) | `""` (root) |
 
 ```bash
 # Point Control Plane to a remote API service
 export HINDSIGHT_CP_DATAPLANE_API_URL=http://api.example.com:8888
 ```
 
+### Hierarchical Configuration
+
+Hindsight supports per-bank configuration overrides through a hierarchical system: **Global (env vars) → Tenant → Bank**.
+
+#### Type-Safe Config Access
+
+To prevent accidentally using global defaults when bank-specific overrides exist, Hindsight enforces type-safe config access:
+
+**In Application Code:**
+```python
+from hindsight_api.config import get_config
+
+# ✅ Access static (infrastructure) fields
+config = get_config()
+host = config.host  # OK - static field
+port = config.port  # OK - static field
+
+# ❌ Attempting to access bank-configurable fields raises an error
+chunk_size = config.retain_chunk_size  # ConfigFieldAccessError!
+```
+
+**Error Message:**
+```
+ConfigFieldAccessError: Field 'retain_chunk_size' is bank-configurable and cannot
+be accessed from global config. Use ConfigResolver.resolve_full_config(bank_id, context)
+to get bank-specific config.
+```
+
+**For Bank-Specific Config:**
+```python
+# Internal code that needs bank-specific settings
+from hindsight_api.config_resolver import ConfigResolver
+
+# Resolve full config for a specific bank
+config = await config_resolver.resolve_full_config(bank_id, request_context)
+chunk_size = config.retain_chunk_size  # ✅ Uses bank-specific value
+```
+
+This design prevents bugs where global defaults are used instead of bank overrides, making it impossible to make this mistake at compile/development time.
+
+#### Security Model
+
+Configuration fields are categorized for security:
+
+1. **Configurable Fields** - Safe behavioral settings that can be customized per-bank:
+   - Retention: `retain_chunk_size`, `retain_extraction_mode`, `retain_custom_instructions`
+   - Consolidation: `enable_observations`
+
+2. **Credential Fields** - NEVER exposed or configurable via API:
+   - API keys: `*_api_key` (all LLM API keys)
+   - Infrastructure: `*_base_url` (all base URLs)
+
+3. **Static Fields** - Server-level only, cannot be overridden:
+   - Infrastructure: `database_url`, `port`, `host`, `worker_count`
+   - Provider/Model selection: `llm_provider`, `llm_model` (requires presets - not yet implemented)
+   - Performance tuning: `llm_max_concurrent`, `llm_timeout`, retrieval settings, optimization flags
+
+#### Enabling the API
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `HINDSIGHT_API_ENABLE_BANK_CONFIG_API` | Enable per-bank config API | `false` |
+
+**Important:** The bank config API is **disabled by default** for security. Enable it explicitly:
+
+```bash
+export HINDSIGHT_API_ENABLE_BANK_CONFIG_API=true
+```
+
+#### API Endpoints
+
+- `GET /v1/default/banks/{bank_id}/config` - View resolved config (filtered by permissions)
+- `PATCH /v1/default/banks/{bank_id}/config` - Update bank overrides (only allowed fields)
+- `DELETE /v1/default/banks/{bank_id}/config` - Reset to defaults
+
+#### Permission System
+
+Tenant extensions can control which fields banks are allowed to modify via `get_allowed_config_fields()`:
+
+```python
+class CustomTenantExtension(TenantExtension):
+    async def get_allowed_config_fields(self, context, bank_id):
+        # Option 1: Allow all configurable fields
+        return None
+
+        # Option 2: Allow specific fields only
+        return {"retain_chunk_size", "retain_custom_instructions"}
+
+        # Option 3: Read-only (no modifications)
+        return set()
+```
+
+#### Examples
+
+```bash
+# Update retention settings for a bank
+curl -X PATCH http://localhost:8888/v1/default/banks/my-bank/config \
+  -H "Content-Type: application/json" \
+  -d '{
+    "updates": {
+      "retain_chunk_size": 4000,
+      "retain_extraction_mode": "custom",
+      "retain_custom_instructions": "Focus on technical details and implementation specifics"
+    }
+  }'
+
+# Note: retain_extraction_mode must be "custom" to use retain_custom_instructions
+
+# View resolved config (respects permissions)
+curl http://localhost:8888/v1/default/banks/my-bank/config
+
+# Reset to defaults
+curl -X DELETE http://localhost:8888/v1/default/banks/my-bank/config
+```
+
+**Security Notes:**
+- Credentials (API keys, base URLs) are never returned in responses
+- Only configurable fields can be modified
+- Responses are filtered by tenant permissions
+- Attempting to set credentials returns 400 error
+
+### Reverse Proxy / Subpath Deployment
+
+To deploy Hindsight under a subpath (e.g., `example.com/hindsight/`):
+
+1. Set both environment variables to the same path:
+   ```bash
+   HINDSIGHT_API_BASE_PATH=/hindsight
+   NEXT_PUBLIC_BASE_PATH=/hindsight
+   ```
+
+2. Configure your reverse proxy to:
+   - Forward `/hindsight/*` requests to Hindsight
+   - Preserve the full path in forwarded requests
+   - Set appropriate proxy headers (X-Forwarded-Proto, X-Forwarded-For)
+
+**Example: Nginx Configuration**
+
+```nginx
+location /hindsight/ {
+    proxy_pass http://localhost:8888/;
+    proxy_set_header Host $host;
+    proxy_set_header X-Real-IP $remote_addr;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Forwarded-Proto $scheme;
+}
+```
+
+**Example: Traefik Configuration**
+
+```yaml
+http:
+  routers:
+    hindsight:
+      rule: "PathPrefix(`/hindsight`)"
+      service: hindsight
+      middlewares:
+        - hindsight-stripprefix
+
+  middlewares:
+    hindsight-stripprefix:
+      stripPrefix:
+        prefixes:
+          - "/hindsight"
+
+  services:
+    hindsight:
+      loadBalancer:
+        servers:
+          - url: "http://localhost:8888"
+```
+
+**Important Notes:**
+- The base path must start with `/` and should NOT end with `/`
+- Both API and Control Plane should use the same base path
+- After setting environment variables, restart both services
+- OpenAPI docs will be available at `<base-path>/docs` (e.g., `/hindsight/docs`)
+
+**Complete Examples:**
+
+See `docker/compose-examples/` directory for:
+- Nginx configuration files (`simple.conf`, `api-and-control-plane.conf`)
+- Docker Compose setups (`docker-compose.yml`, `reverse-proxy-only.yml`)
+- Traefik and other reverse proxy examples
+- Full deployment documentation
 ---
 
 ## Example .env File

hindsight-docs/docs/developer/installation.md

@@ -3,7 +3,7 @@
 Hindsight can be deployed in several ways depending on your infrastructure and requirements.
 
 :::tip Don't want to manage infrastructure?
-**[Hindsight Cloud](https://vectorize.io/hindsight/cloud)** is a fully managed service that handles all infrastructure, scaling, and maintenance. We're onboarding design partners now — [request early access](https://vectorize.io/hindsight/cloud).
+**[Hindsight Cloud](https://ui.hindsight.vectorize.io/signup)** is a fully managed service that handles all infrastructure, scaling, and maintenance — [sign up here](https://ui.hindsight.vectorize.io/signup).
 :::
 
 ## Prerequisites

hindsight-docs/docs/developer/mcp-server.md

@@ -71,6 +71,7 @@ curl -X POST http://localhost:8888/mcp \
   -H "Authorization: Bearer your-secret-key" \
   -H "X-Bank-Id: my-bank" \
   -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
   -d '{"jsonrpc": "2.0", "method": "tools/list", "id": 1}'
 ```
 
@@ -78,10 +79,10 @@ If the key is missing or invalid, requests will receive a `401 Unauthorized` res
 
 ## Bank Selection
 
-Specify the memory bank via:
+The memory bank is resolved in this priority order:
 
-1. **X-Bank-Id header** (recommended): `--header "X-Bank-Id: my-bank"`
-2. **URL path**: `http://localhost:8888/mcp/my-bank/`
+1. **URL path** (highest priority): `http://localhost:8888/mcp/my-bank/`
+2. **X-Bank-Id header**: `--header "X-Bank-Id: my-bank"`
 3. **Default**: Uses `HINDSIGHT_MCP_BANK_ID` env var (default: "default")
 
 ## Per-Bank Endpoints
@@ -93,6 +94,19 @@ This design:
 - **Enforces isolation** — each MCP connection is scoped to a single bank
 - **Enables multi-tenant setups** — connect different users to different endpoints
 
+## Two Modes
+
+The MCP server operates in two modes depending on the URL:
+
+| Mode | URL | Tools | bank_id |
+|------|-----|-------|---------|
+| **Single-bank** | `/mcp/{bank_id}/` | Memory + mental model tools | Implicit from URL |
+| **Multi-bank** | `/mcp/` | All tools including bank management | Explicit `bank_id` parameter on each tool |
+
+**Single-bank mode** (recommended) scopes all operations to the bank in the URL. Tools don't expose a `bank_id` parameter.
+
+**Multi-bank mode** exposes all tools with an optional `bank_id` parameter, plus bank management tools (`list_banks`, `create_bank`).
+
 ---
 
 ## Available Tools
@@ -105,6 +119,7 @@ Store information to long-term memory.
 |-----------|------|----------|-------------|
 | `content` | string | Yes | The fact or memory to store |
 | `context` | string | No | Category for the memory (default: `general`) |
+| `timestamp` | string | No | ISO 8601 timestamp for when the event occurred |
 
 **Example:**
 ```json
@@ -132,7 +147,7 @@ Search memories to provide personalized responses.
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `query` | string | Yes | Natural language search query |
-| `max_results` | integer | No | Maximum results to return (default: 10) |
+| `max_tokens` | integer | No | Maximum tokens to return (default: 4096) |
 
 **Example:**
 ```json
@@ -144,21 +159,6 @@ Search memories to provide personalized responses.
 }
 ```
 
-**Response:**
-```json
-{
-  "results": [
-    {
-      "id": "fact_abc123",
-      "text": "User prefers Python over JavaScript for backend development",
-      "type": "world",
-      "context": "programming_preferences",
-      "event_date": null
-    }
-  ]
-}
-```
-
 **When to use:**
 - Start of conversation to recall relevant context
 - Before making recommendations
@@ -195,10 +195,110 @@ Generate thoughtful analysis by synthesizing stored memories with the bank's per
 
 ---
 
+### create_mental_model
+
+Create a mental model — a living document that stays current with your memories. Mental models are pre-computed reflections that get automatically refreshed as new memories are stored.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `name` | string | Yes | Human-readable name for the mental model |
+| `source_query` | string | Yes | The query used to generate and refresh the model |
+| `mental_model_id` | string | No | Custom ID (alphanumeric lowercase with hyphens). Auto-generated if not provided |
+| `tags` | list[string] | No | Tags for organizing and filtering models |
+| `max_tokens` | integer | No | Maximum tokens for model content (default: 2048) |
+
+**Example:**
+```json
+{
+  "name": "create_mental_model",
+  "arguments": {
+    "name": "Team Directory",
+    "source_query": "Who works here and what do they do?",
+    "tags": ["team", "people"]
+  }
+}
+```
+
+Content generation runs asynchronously. The response includes an `operation_id` to track progress.
+
+---
+
+### list_mental_models
+
+List all mental models in a bank, optionally filtered by tags.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `tags` | list[string] | No | Filter models by tags |
+
+---
+
+### get_mental_model
+
+Retrieve a specific mental model by ID, including its full content.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `mental_model_id` | string | Yes | The ID of the mental model to retrieve |
+
+---
+
+### update_mental_model
+
+Update a mental model's metadata or settings.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `mental_model_id` | string | Yes | The ID of the mental model to update |
+| `name` | string | No | New name |
+| `source_query` | string | No | New source query |
+| `tags` | list[string] | No | New tags |
+| `max_tokens` | integer | No | New max tokens |
+
+---
+
+### delete_mental_model
+
+Permanently delete a mental model.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `mental_model_id` | string | Yes | The ID of the mental model to delete |
+
+---
+
+### refresh_mental_model
+
+Re-generate a mental model's content from the latest memories. Runs asynchronously.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `mental_model_id` | string | Yes | The ID of the mental model to refresh |
+
+---
+
+### list_banks (multi-bank mode only)
+
+List all available memory banks.
+
+---
+
+### create_bank (multi-bank mode only)
+
+Create a new memory bank or retrieve an existing one.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `bank_id` | string | Yes | The ID for the new bank |
+| `name` | string | No | Human-friendly name for the bank |
+| `mission` | string | No | Mission describing who the agent is and what they're trying to accomplish |
+
+---
+
 ## Integration with AI Assistants
 
 The MCP server can be used with any MCP-compatible AI assistant. See the [Authentication](#authentication) section above for Claude Code and Claude Desktop configuration examples.
 
 Each user can have their own configuration pointing to their personal memory bank using either:
-- The `X-Bank-Id` header (recommended)
-- A bank-specific URL path like `/mcp/alice/`
+- A bank-specific URL path like `/mcp/alice/` (recommended)
+- The `X-Bank-Id` header

hindsight-docs/docs/sdks/integrations/local-mcp.md

@@ -132,7 +132,6 @@ Search memories to provide personalized responses.
 |-----------|------|----------|-------------|
 | `query` | string | Yes | Natural language search query |
 | `max_tokens` | integer | No | Maximum tokens to return (default: 4096) |
-| `budget` | string | No | Search depth: `low`, `mid`, or `high` (default: `low`) |
 
 **Example:**
 ```json
@@ -140,8 +139,7 @@ Search memories to provide personalized responses.
   "name": "recall",
   "arguments": {
     "query": "What are the user's color preferences?",
-    "max_tokens": 2048,
-    "budget": "mid"
+    "max_tokens": 2048
   }
 }
 ```

hindsight-docs/docs/sdks/integrations/skills.md

@@ -161,11 +161,11 @@ uvx hindsight-embed configure
 
 ## Cloud Mode Setup
 
-Cloud mode connects to [Hindsight Cloud](https://vectorize.io/hindsight/cloud), allowing teams to share memories about a codebase. When one team member learns something, everyone benefits.
+Cloud mode connects to [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup), allowing teams to share memories about a codebase. When one team member learns something, everyone benefits.
 
 ### Prerequisites
 
-1. A Hindsight Cloud account ([request access](https://vectorize.io/hindsight/cloud))
+1. A Hindsight Cloud account ([sign up](https://ui.hindsight.vectorize.io/signup))
 2. An API key from your team admin
 3. A bank ID for your project (e.g., `team-acme-frontend`)
 

hindsight-docs/docusaurus.config.ts

@@ -226,7 +226,7 @@ const config: Config = {
           className: 'navbar-item-changelog',
         },
         {
-          href: 'https://vectorize.io/hindsight/cloud',
+          href: 'https://ui.hindsight.vectorize.io/signup',
           position: 'right',
           label: 'Hindsight Cloud',
           className: 'navbar-item-cloud',
@@ -285,7 +285,7 @@ const config: Config = {
             },
             {
               label: 'Hindsight Cloud',
-              href: 'https://vectorize.io/hindsight/cloud',
+              href: 'https://ui.hindsight.vectorize.io/signup',
             },
           ],
         },

hindsight-docs/src/components/CopyPageButton/index.tsx

@@ -0,0 +1,162 @@
+import React, { useState, useCallback } from 'react';
+import styles from './styles.module.css';
+
+export default function CopyPageButton(): JSX.Element | null {
+  const [copied, setCopied] = useState(false);
+
+  const copyPageAsMarkdown = useCallback(async () => {
+    try {
+      // Get the page content
+      const contentElement = document.querySelector('.markdown');
+      if (!contentElement) return;
+
+      // Convert HTML to markdown-like text
+      let markdown = '';
+
+      // Add title
+      const title = document.querySelector('h1')?.textContent;
+      if (title) {
+        markdown += `# ${title}\n\n`;
+      }
+
+      // Extract text content from the markdown container
+      const extractMarkdown = (element: Element): string => {
+        let text = '';
+
+        const processNode = (node: Node): string => {
+          if (node.nodeType === Node.TEXT_NODE) {
+            return node.textContent || '';
+          }
+
+          if (node.nodeType === Node.ELEMENT_NODE) {
+            const el = node as Element;
+            const tagName = el.tagName.toLowerCase();
+            const children = Array.from(el.childNodes).map(processNode).join('');
+
+            switch (tagName) {
+              case 'h1':
+                return `# ${children}\n\n`;
+              case 'h2':
+                return `## ${children}\n\n`;
+              case 'h3':
+                return `### ${children}\n\n`;
+              case 'h4':
+                return `#### ${children}\n\n`;
+              case 'h5':
+                return `##### ${children}\n\n`;
+              case 'h6':
+                return `###### ${children}\n\n`;
+              case 'p':
+                return `${children}\n\n`;
+              case 'ul':
+                return `${children}\n`;
+              case 'ol':
+                return `${children}\n`;
+              case 'li':
+                const parent = el.parentElement;
+                const isOrdered = parent?.tagName.toLowerCase() === 'ol';
+                if (isOrdered) {
+                  const index = Array.from(parent?.children || []).indexOf(el) + 1;
+                  return `${index}. ${children}\n`;
+                }
+                return `- ${children}\n`;
+              case 'code':
+                const isBlock = el.parentElement?.tagName.toLowerCase() === 'pre';
+                if (isBlock) {
+                  const lang = el.className.replace('language-', '');
+                  return `\`\`\`${lang}\n${children}\n\`\`\`\n\n`;
+                }
+                return `\`${children}\``;
+              case 'pre':
+                return children; // Already handled by code block
+              case 'blockquote':
+                return children.split('\n').map(line => `> ${line}`).join('\n') + '\n\n';
+              case 'a':
+                const href = el.getAttribute('href') || '';
+                return `[${children}](${href})`;
+              case 'strong':
+              case 'b':
+                return `**${children}**`;
+              case 'em':
+              case 'i':
+                return `*${children}*`;
+              case 'br':
+                return '\n';
+              case 'hr':
+                return '---\n\n';
+              case 'table':
+                return `${children}\n`;
+              case 'thead':
+              case 'tbody':
+                return children;
+              case 'tr':
+                return `${children}|\n`;
+              case 'th':
+              case 'td':
+                return `| ${children} `;
+              case 'img':
+                const src = el.getAttribute('src') || '';
+                const alt = el.getAttribute('alt') || '';
+                return `![${alt}](${src})`;
+              default:
+                return children;
+            }
+          }
+
+          return '';
+        };
+
+        Array.from(element.childNodes).forEach(node => {
+          text += processNode(node);
+        });
+
+        return text;
+      };
+
+      // Skip the title h1 if it's already added
+      const contentToCopy = Array.from(contentElement.children)
+        .filter(child => !(child.tagName === 'H1' && child.textContent === title))
+        .map(child => extractMarkdown(child))
+        .join('');
+
+      markdown += contentToCopy;
+
+      // Clean up excessive newlines
+      markdown = markdown.replace(/\n{3,}/g, '\n\n').trim();
+
+      // Copy to clipboard
+      await navigator.clipboard.writeText(markdown);
+
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    } catch (error) {
+      console.error('Failed to copy page content:', error);
+    }
+  }, []);
+
+  return (
+    <button
+      className={`${styles.copyPageButton} ${copied ? styles.copied : ''}`}
+      onClick={copyPageAsMarkdown}
+      aria-label="Copy page as markdown"
+      title="Copy page as markdown"
+    >
+      {copied ? (
+        <>
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+            <path d="M12.736 3.97a.733.733 0 0 1 1.047 0c.286.289.29.756.01 1.05L7.88 12.01a.733.733 0 0 1-1.065.02L3.217 8.384a.757.757 0 0 1 0-1.06.733.733 0 0 1 1.047 0l3.052 3.093 5.4-6.425a.247.247 0 0 1 .02-.022Z"/>
+          </svg>
+          <span className={styles.buttonText}>Copied!</span>
+        </>
+      ) : (
+        <>
+          <svg width="16" height="16" viewBox="0 0 16 16" fill="currentColor">
+            <path d="M4 2a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2v8a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V2zm2-1a1 1 0 0 0-1 1v8a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1V2a1 1 0 0 0-1-1H6z"/>
+            <path d="M2 5a1 1 0 0 0-1 1v8a1 1 0 0 0 1 1h8a1 1 0 0 0 1-1v-1h1v1a2 2 0 0 1-2 2H2a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h1v1H2z"/>
+          </svg>
+          <span className={styles.buttonText}>Copy page</span>
+        </>
+      )}
+    </button>
+  );
+}

hindsight-docs/src/components/CopyPageButton/styles.module.css

@@ -0,0 +1,55 @@
+.copyPageButton {
+  display: flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 12px;
+  background: transparent;
+  border: 1px solid var(--ifm-color-emphasis-300);
+  border-radius: 6px;
+  color: var(--ifm-font-color-base);
+  font-size: 14px;
+  font-weight: 500;
+  cursor: pointer;
+  transition: all 0.2s ease;
+  white-space: nowrap;
+}
+
+.copyPageButton:hover {
+  background-color: var(--ifm-color-emphasis-100);
+  border-color: var(--ifm-color-emphasis-400);
+}
+
+.copyPageButton:active {
+  transform: translateY(1px);
+}
+
+.copyPageButton.copied {
+  background-color: var(--ifm-color-success-contrast-background);
+  border-color: var(--ifm-color-success);
+  color: var(--ifm-color-success-darkest);
+}
+
+.copyPageButton.copied:hover {
+  background-color: var(--ifm-color-success-contrast-background);
+  border-color: var(--ifm-color-success);
+}
+
+.buttonText {
+  margin: 0 4px;
+}
+
+/* Dark mode adjustments */
+[data-theme='dark'] .copyPageButton {
+  border-color: var(--ifm-color-emphasis-400);
+}
+
+[data-theme='dark'] .copyPageButton:hover {
+  background-color: var(--ifm-color-emphasis-200);
+  border-color: var(--ifm-color-emphasis-500);
+}
+
+[data-theme='dark'] .copyPageButton.copied {
+  background-color: var(--ifm-color-success-dark);
+  border-color: var(--ifm-color-success);
+  color: var(--ifm-color-success-contrast-foreground);
+}

hindsight-docs/src/theme/DocItem/Content/index.tsx

@@ -0,0 +1,21 @@
+import React from 'react';
+import DocItemContent from '@theme-original/DocItem/Content';
+import type DocItemContentType from '@theme/DocItem/Content';
+import type { WrapperProps } from '@docusaurus/types';
+import CopyPageButton from '@site/src/components/CopyPageButton';
+import styles from './styles.module.css';
+
+type Props = WrapperProps<typeof DocItemContentType>;
+
+export default function DocItemContentWrapper(props: Props): JSX.Element {
+  return (
+    <>
+      <div className={styles.docItemHeader}>
+        <div className={styles.docItemActions}>
+          <CopyPageButton />
+        </div>
+      </div>
+      <DocItemContent {...props} />
+    </>
+  );
+}

hindsight-docs/src/theme/DocItem/Content/styles.module.css

@@ -0,0 +1,20 @@
+.docItemHeader {
+  display: flex;
+  justify-content: flex-end;
+  align-items: center;
+  margin-bottom: 1rem;
+  padding-bottom: 0.5rem;
+  border-bottom: 1px solid var(--ifm-color-emphasis-200);
+}
+
+.docItemActions {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+}
+
+@media (max-width: 768px) {
+  .docItemHeader {
+    margin-bottom: 0.75rem;
+  }
+}

hindsight-docs/static/openapi.json

@@ -2749,6 +2749,189 @@
         }
       }
     },
+    "/v1/default/banks/{bank_id}/config": {
+      "get": {
+        "tags": [
+          "Banks"
+        ],
+        "summary": "Get bank configuration",
+        "description": "Get fully resolved configuration for a bank including all hierarchical overrides (global \u2192 tenant \u2192 bank). The 'config' field contains all resolved config values. The 'overrides' field shows only bank-specific overrides.",
+        "operationId": "get_bank_config",
+        "parameters": [
+          {
+            "name": "bank_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "title": "Bank Id"
+            }
+          },
+          {
+            "name": "authorization",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Authorization"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BankConfigResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      },
+      "patch": {
+        "tags": [
+          "Banks"
+        ],
+        "summary": "Update bank configuration",
+        "description": "Update configuration overrides for a bank. Only hierarchical fields can be overridden (LLM settings, retention parameters, etc.). Keys can be provided in Python field format (llm_provider) or environment variable format (HINDSIGHT_API_LLM_PROVIDER).",
+        "operationId": "update_bank_config",
+        "parameters": [
+          {
+            "name": "bank_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "title": "Bank Id"
+            }
+          },
+          {
+            "name": "authorization",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Authorization"
+            }
+          }
+        ],
+        "requestBody": {
+          "required": true,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/BankConfigUpdate"
+              }
+            }
+          }
+        },
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BankConfigResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      },
+      "delete": {
+        "tags": [
+          "Banks"
+        ],
+        "summary": "Reset bank configuration",
+        "description": "Reset bank configuration to defaults by removing all bank-specific overrides. The bank will then use global and tenant-level configuration only.",
+        "operationId": "reset_bank_config",
+        "parameters": [
+          {
+            "name": "bank_id",
+            "in": "path",
+            "required": true,
+            "schema": {
+              "type": "string",
+              "title": "Bank Id"
+            }
+          },
+          {
+            "name": "authorization",
+            "in": "header",
+            "required": false,
+            "schema": {
+              "anyOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "null"
+                }
+              ],
+              "title": "Authorization"
+            }
+          }
+        ],
+        "responses": {
+          "200": {
+            "description": "Successful Response",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/BankConfigResponse"
+                }
+              }
+            }
+          },
+          "422": {
+            "description": "Validation Error",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/HTTPValidationError"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
     "/v1/default/banks/{bank_id}/consolidate": {
       "post": {
         "tags": [
@@ -3042,6 +3225,70 @@
           "mission": "I was born in Texas. I am a software engineer with 10 years of experience."
         }
       },
+      "BankConfigResponse": {
+        "properties": {
+          "bank_id": {
+            "type": "string",
+            "title": "Bank Id",
+            "description": "Bank identifier"
+          },
+          "config": {
+            "additionalProperties": true,
+            "type": "object",
+            "title": "Config",
+            "description": "Fully resolved configuration with all hierarchical overrides applied (Python field names)"
+          },
+          "overrides": {
+            "additionalProperties": true,
+            "type": "object",
+            "title": "Overrides",
+            "description": "Bank-specific configuration overrides only (Python field names)"
+          }
+        },
+        "type": "object",
+        "required": [
+          "bank_id",
+          "config",
+          "overrides"
+        ],
+        "title": "BankConfigResponse",
+        "description": "Response model for bank configuration.",
+        "example": {
+          "bank_id": "my-bank",
+          "config": {
+            "llm_model": "gpt-4",
+            "llm_provider": "openai",
+            "retain_extraction_mode": "verbose"
+          },
+          "overrides": {
+            "llm_model": "gpt-4",
+            "retain_extraction_mode": "verbose"
+          }
+        }
+      },
+      "BankConfigUpdate": {
+        "properties": {
+          "updates": {
+            "additionalProperties": true,
+            "type": "object",
+            "title": "Updates",
+            "description": "Configuration overrides. Keys can be in Python field format (llm_provider) or environment variable format (HINDSIGHT_API_LLM_PROVIDER). Only hierarchical fields can be overridden per-bank."
+          }
+        },
+        "type": "object",
+        "required": [
+          "updates"
+        ],
+        "title": "BankConfigUpdate",
+        "description": "Request model for updating bank configuration.",
+        "example": {
+          "updates": {
+            "llm_model": "claude-sonnet-4-5",
+            "retain_custom_instructions": "Extract technical details carefully",
+            "retain_extraction_mode": "verbose"
+          }
+        }
+      },
       "BankListItem": {
         "properties": {
           "bank_id": {
@@ -4243,13 +4490,19 @@
             "type": "boolean",
             "title": "Worker",
             "description": "Whether the background worker is enabled"
+          },
+          "bank_config_api": {
+            "type": "boolean",
+            "title": "Bank Config Api",
+            "description": "Whether per-bank configuration API is enabled"
           }
         },
         "type": "object",
         "required": [
           "observations",
           "mcp",
-          "worker"
+          "worker",
+          "bank_config_api"
         ],
         "title": "FeaturesInfo",
         "description": "Feature flags indicating which capabilities are enabled."
@@ -6259,6 +6512,7 @@
         "example": {
           "api_version": "0.4.0",
           "features": {
+            "bank_config_api": false,
             "mcp": true,
             "observations": false,
             "worker": true

hindsight-docs/versioned_docs/version-0.3/developer/installation.md

@@ -3,7 +3,7 @@
 Hindsight can be deployed in several ways depending on your infrastructure and requirements.
 
 :::tip Don't want to manage infrastructure?
-**[Hindsight Cloud](https://vectorize.io/hindsight/cloud)** is a fully managed service that handles all infrastructure, scaling, and maintenance. We're onboarding design partners now — [request early access](https://vectorize.io/hindsight/cloud).
+**[Hindsight Cloud](https://ui.hindsight.vectorize.io/signup)** is a fully managed service that handles all infrastructure, scaling, and maintenance — [sign up here](https://ui.hindsight.vectorize.io/signup).
 :::
 
 ## Prerequisites

hindsight-docs/versioned_docs/version-0.3/sdks/integrations/skills.md

@@ -161,11 +161,11 @@ uvx hindsight-embed configure
 
 ## Cloud Mode Setup
 
-Cloud mode connects to [Hindsight Cloud](https://vectorize.io/hindsight/cloud), allowing teams to share memories about a codebase. When one team member learns something, everyone benefits.
+Cloud mode connects to [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup), allowing teams to share memories about a codebase. When one team member learns something, everyone benefits.
 
 ### Prerequisites
 
-1. A Hindsight Cloud account ([request access](https://vectorize.io/hindsight/cloud))
+1. A Hindsight Cloud account ([sign up](https://ui.hindsight.vectorize.io/signup))
 2. An API key from your team admin
 3. A bank ID for your project (e.g., `team-acme-frontend`)
 

hindsight-docs/versioned_docs/version-0.4/developer/installation.md

@@ -3,7 +3,7 @@
 Hindsight can be deployed in several ways depending on your infrastructure and requirements.
 
 :::tip Don't want to manage infrastructure?
-**[Hindsight Cloud](https://vectorize.io/hindsight/cloud)** is a fully managed service that handles all infrastructure, scaling, and maintenance. We're onboarding design partners now — [request early access](https://vectorize.io/hindsight/cloud).
+**[Hindsight Cloud](https://ui.hindsight.vectorize.io/signup)** is a fully managed service that handles all infrastructure, scaling, and maintenance — [sign up here](https://ui.hindsight.vectorize.io/signup).
 :::
 
 ## Prerequisites

hindsight-docs/versioned_docs/version-0.4/sdks/integrations/skills.md

@@ -161,11 +161,11 @@ uvx hindsight-embed configure
 
 ## Cloud Mode Setup
 
-Cloud mode connects to [Hindsight Cloud](https://vectorize.io/hindsight/cloud), allowing teams to share memories about a codebase. When one team member learns something, everyone benefits.
+Cloud mode connects to [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup), allowing teams to share memories about a codebase. When one team member learns something, everyone benefits.
 
 ### Prerequisites
 
-1. A Hindsight Cloud account ([request access](https://vectorize.io/hindsight/cloud))
+1. A Hindsight Cloud account ([sign up](https://ui.hindsight.vectorize.io/signup))
 2. An API key from your team admin
 3. A bank ID for your project (e.g., `team-acme-frontend`)
 

hindsight-integration-tests/README.md

@@ -2,19 +2,60 @@
 
 E2E and integration tests for Hindsight API that require a running server.
 
-## Running Tests
+## Test Types
 
-1. Start the API server:
-   ```bash
-   ./scripts/dev/start-api.sh
-   ```
+### 1. Tests with External Server
+Tests like `test_mcp_e2e.py` expect a server to already be running.
 
-2. Run the tests:
-   ```bash
-   cd hindsight-integration-tests
-   HINDSIGHT_API_URL=http://localhost:8888 uv run pytest tests/ -v
-   ```
+**Running:**
+```bash
+# Start the API server
+./scripts/dev/start-api.sh
+
+# Run tests
+cd hindsight-integration-tests
+HINDSIGHT_API_URL=http://localhost:8888 uv run pytest tests/test_mcp_e2e.py -v
+```
+
+### 2. Self-Contained Tests
+Tests like `test_base_path_deployment.py` manage their own server lifecycle and use docker-compose.
+
+**Running:**
+```bash
+cd hindsight-integration-tests
+
+# Run with pytest
+uv run pytest tests/test_base_path_deployment.py -v
+
+# Or run directly for nice output
+uv run python tests/test_base_path_deployment.py
+```
+
+**Requirements:**
+- Docker and docker-compose installed (for reverse proxy test)
+- No nginx required on host!
+
+**What it tests:**
+- ✅ API with base path (direct server)
+- ✅ Full reverse proxy via docker-compose + Nginx
+- ✅ Regression: API without base path
+- ✅ Full retain/recall workflow
+
+These tests:
+- Start their own API servers on dedicated ports (18888-18891)
+- Use docker-compose to test actual deployment scenarios
+- Run in parallel with other tests (no port conflicts)
+- Clean up automatically
+
+## Running All Tests
+
+```bash
+cd hindsight-integration-tests
+uv run pytest tests/ -v
+```
+
+This runs both types. Self-contained tests won't conflict with the external server.
 
 ## Environment Variables
 
-- `HINDSIGHT_API_URL` - Base URL of the running Hindsight API (default: `http://localhost:8888`)
+- `HINDSIGHT_API_URL` - Base URL for external-server tests (default: `http://localhost:8888`)

hindsight-integration-tests/tests/test_base_path_deployment.py

@@ -0,0 +1,494 @@
+"""
+Integration test for base path deployment using Docker Compose.
+
+This test validates that Hindsight works correctly when deployed
+behind a reverse proxy with path-based routing using the actual
+Docker Compose examples from docker/compose-examples/.
+
+Tests:
+1. API with base path (direct, no proxy)
+2. Full stack via docker-compose with Nginx reverse proxy
+3. Regression: API without base path still works
+
+Requirements:
+- Docker and docker-compose installed
+- No nginx required on host!
+"""
+import asyncio
+import os
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import httpx
+import pytest
+
+# Paths
+REPO_ROOT = Path(__file__).parent.parent.parent
+API_PATH = REPO_ROOT / "hindsight-api"
+COMPOSE_EXAMPLES_PATH = REPO_ROOT / "docker" / "docker-compose" / "nginx"
+
+# Add hindsight-api to path for direct API testing
+sys.path.insert(0, str(API_PATH))
+
+
+def run_command(cmd: list[str], cwd: str | Path | None = None, env: dict | None = None) -> subprocess.CompletedProcess:
+    """Run a command and return the result."""
+    return subprocess.run(
+        cmd,
+        cwd=cwd,
+        env=env,
+        capture_output=True,
+        text=True,
+    )
+
+
+def check_docker_available() -> bool:
+    """Check if Docker is available."""
+    result = run_command(["docker", "info"])
+    return result.returncode == 0
+
+
+def get_docker_compose_command() -> list[str]:
+    """Get the docker-compose command (modern or legacy)."""
+    import shutil
+    # Try modern docker compose plugin first
+    if shutil.which("docker"):
+        result = run_command(["docker", "compose", "version"])
+        if result.returncode == 0:
+            return ["docker", "compose"]
+    # Fall back to legacy docker-compose
+    if shutil.which("docker-compose"):
+        return ["docker-compose"]
+    raise RuntimeError("docker-compose not available")
+
+
+def check_docker_compose_available() -> bool:
+    """Check if docker-compose is available."""
+    try:
+        get_docker_compose_command()
+        return True
+    except RuntimeError:
+        return False
+
+
+class APIServer:
+    """Helper to manage API server lifecycle for direct testing."""
+
+    def __init__(self, base_path: str | None = None, port: int = 18888):
+        self.base_path = base_path
+        self.port = port
+        self.process = None
+        self.env = os.environ.copy()
+        if base_path:
+            self.env["HINDSIGHT_API_BASE_PATH"] = base_path
+
+    def start(self):
+        """Start the API server."""
+        cmd = [
+            "uv",
+            "run",
+            "--directory",
+            str(API_PATH),
+            "hindsight-api",
+            "--host",
+            "0.0.0.0",
+            "--port",
+            str(self.port),
+        ]
+
+        log_file = f"/tmp/hindsight-api-{self.port}.log"
+        self.log_file = open(log_file, "w")
+
+        self.process = subprocess.Popen(
+            cmd, env=self.env, stdout=self.log_file, stderr=subprocess.STDOUT
+        )
+
+        # Wait for server to be ready
+        base_url = f"http://localhost:{self.port}"
+        if self.base_path:
+            health_url = f"{base_url}{self.base_path}/health"
+        else:
+            health_url = f"{base_url}/health"
+
+        for _ in range(60):  # 60 second timeout
+            try:
+                response = httpx.get(health_url, timeout=2.0)
+                if response.status_code == 200:
+                    return
+            except (httpx.ConnectError, httpx.ReadTimeout):
+                pass
+            time.sleep(1)
+
+        # Failed to start
+        self.log_file.flush()
+        with open(log_file) as f:
+            print(f"API server failed to start. Logs:\n{f.read()}")
+        raise RuntimeError(f"API server failed to start on port {self.port}")
+
+    def stop(self):
+        """Stop the API server."""
+        if self.process:
+            self.process.terminate()
+            try:
+                self.process.wait(timeout=10)
+            except subprocess.TimeoutExpired:
+                self.process.kill()
+                self.process.wait()
+            self.process = None
+
+        if hasattr(self, "log_file") and self.log_file:
+            self.log_file.close()
+
+    def __enter__(self):
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.stop()
+
+
+class DockerComposeStack:
+    """Helper to manage docker-compose stack lifecycle."""
+
+    def __init__(self, compose_file: Path, project_name: str = "hindsight-test"):
+        self.compose_file = compose_file
+        self.project_name = project_name
+        self.compose_cmd = get_docker_compose_command()
+        self.env = os.environ.copy()
+        # Set required env vars for docker-compose
+        self.env["OPENAI_API_KEY"] = os.environ.get("OPENAI_API_KEY", "test-key")
+        self.env["HINDSIGHT_API_LLM_PROVIDER"] = os.environ.get("HINDSIGHT_API_LLM_PROVIDER", "mock")
+        self.env["HINDSIGHT_API_LLM_MODEL"] = os.environ.get("HINDSIGHT_API_LLM_MODEL", "mock-model")
+
+    def start(self, timeout: int = 120):
+        """Start the docker-compose stack."""
+        print(f"Starting docker-compose stack: {self.compose_file.name}")
+
+        # Pull images first (but don't fail if it doesn't work)
+        run_command(
+            self.compose_cmd + ["-f", str(self.compose_file), "-p", self.project_name, "pull"],
+            cwd=self.compose_file.parent,
+            env=self.env,
+        )
+
+        # Start services
+        result = run_command(
+            self.compose_cmd + ["-f", str(self.compose_file), "-p", self.project_name, "up", "-d", "--build"],
+            cwd=self.compose_file.parent,
+            env=self.env,
+        )
+
+        if result.returncode != 0:
+            print(f"Failed to start docker-compose:\nSTDOUT: {result.stdout}\nSTDERR: {result.stderr}")
+            raise RuntimeError("Failed to start docker-compose stack")
+
+        # Wait for services to be healthy
+        start_time = time.time()
+        while time.time() - start_time < timeout:
+            result = run_command(
+                self.compose_cmd + ["-f", str(self.compose_file), "-p", self.project_name, "ps", "--format", "json"],
+                cwd=self.compose_file.parent,
+                env=self.env,
+            )
+
+            if result.returncode == 0:
+                # Give it a few more seconds to fully initialize
+                time.sleep(5)
+                return
+
+            time.sleep(2)
+
+        # Timeout - show logs and fail
+        self.show_logs()
+        raise RuntimeError(f"Docker compose stack failed to start within {timeout}s")
+
+    def show_logs(self):
+        """Show docker-compose logs."""
+        result = run_command(
+            self.compose_cmd + ["-f", str(self.compose_file), "-p", self.project_name, "logs", "--tail=100"],
+            cwd=self.compose_file.parent,
+            env=self.env,
+        )
+        print(f"Docker compose logs:\n{result.stdout}\n{result.stderr}")
+
+    def stop(self):
+        """Stop and remove the docker-compose stack."""
+        print(f"Stopping docker-compose stack: {self.compose_file.name}")
+        result = run_command(
+            self.compose_cmd + ["-f", str(self.compose_file), "-p", self.project_name, "down", "-v"],
+            cwd=self.compose_file.parent,
+            env=self.env,
+        )
+
+        if result.returncode != 0:
+            print(f"Warning: Failed to stop docker-compose:\n{result.stderr}")
+
+    def __enter__(self):
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        self.stop()
+
+
+def test_api_without_base_path():
+    """Regression test: API works at root path (default behavior)."""
+    with APIServer(base_path=None, port=18888) as server:
+        base_url = f"http://localhost:{server.port}"
+
+        # Health check
+        response = httpx.get(f"{base_url}/health")
+        assert response.status_code == 200
+        assert "status" in response.json()
+
+        # API endpoints
+        response = httpx.get(f"{base_url}/v1/default/banks")
+        assert response.status_code == 200
+        assert "banks" in response.json()
+
+        # OpenAPI docs
+        response = httpx.get(f"{base_url}/docs")
+        assert response.status_code == 200
+
+
+def test_api_with_base_path_direct():
+    """Test API with base path configuration (direct, no proxy)."""
+    base_path = "/hindsight"
+
+    with APIServer(base_path=base_path, port=18889) as server:
+        base_url = f"http://localhost:{server.port}"
+
+        # Base path SHOULD work
+        response = httpx.get(f"{base_url}{base_path}/health")
+        assert response.status_code == 200
+        assert "status" in response.json()
+
+        # API endpoints with base path
+        response = httpx.get(f"{base_url}{base_path}/v1/default/banks")
+        assert response.status_code == 200
+        assert "banks" in response.json()
+
+        # OpenAPI docs with base path
+        response = httpx.get(f"{base_url}{base_path}/docs")
+        assert response.status_code == 200
+
+        # OpenAPI schema should have correct server URL
+        response = httpx.get(f"{base_url}{base_path}/openapi.json")
+        assert response.status_code == 200
+        openapi = response.json()
+        assert "servers" in openapi
+        assert openapi["servers"][0]["url"] == base_path
+
+
+@pytest.mark.skipif(
+    not check_docker_compose_available(),
+    reason="docker-compose not available"
+)
+def test_reverse_proxy_simple_config():
+    """
+    Test reverse proxy deployment using docker-compose with Nginx.
+
+    This creates a minimal test setup with:
+    - API server running on HOST via uv (not Docker - faster, no image build needed!)
+    - Nginx container that proxies to the host API
+
+    This tests the actual reverse proxy scenario without requiring the
+    heavy Hindsight Docker image.
+    """
+    base_path = "/hindsight"
+    api_port = 18890
+
+    # Start API on host with base path
+    with APIServer(base_path=base_path, port=api_port):
+        # Create test docker-compose file (nginx only)
+        test_compose = COMPOSE_EXAMPLES_PATH / "test-reverse-proxy.yml"
+
+        # Determine host address for nginx to reach host machine
+        # host.docker.internal works on Docker Desktop (Mac/Windows)
+        # On Linux, we use host network mode
+        import platform
+        if platform.system() == "Linux":
+            network_mode = "host"
+            api_host = "localhost"
+            nginx_port = 18080  # With host mode, nginx must listen on 18080 directly
+            port_mapping = ""  # No port mapping with host mode
+        else:
+            network_mode = "bridge"
+            api_host = "host.docker.internal"
+            nginx_port = 80  # With bridge mode, nginx listens on 80 and is mapped
+            port_mapping = """    ports:
+      - "18080:80"
+"""
+
+        compose_content = f"""version: '3.8'
+
+services:
+  nginx:
+    image: nginx:alpine
+{port_mapping}    volumes:
+      - ./test-nginx.conf:/etc/nginx/nginx.conf:ro
+    network_mode: {network_mode}
+"""
+
+        # Create test nginx config
+        nginx_config = f"""events {{
+    worker_connections 1024;
+}}
+
+http {{
+    server {{
+        listen {nginx_port};
+        server_name localhost;
+
+        location {base_path}/ {{
+            proxy_pass http://{api_host}:{api_port};
+            proxy_set_header Host $host;
+            proxy_set_header X-Real-IP $remote_addr;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto $scheme;
+        }}
+    }}
+}}
+"""
+
+        # Write test files
+        test_compose.write_text(compose_content)
+        test_nginx_conf = COMPOSE_EXAMPLES_PATH / "test-nginx.conf"
+        test_nginx_conf.write_text(nginx_config)
+
+        try:
+            # Start nginx via docker-compose
+            with DockerComposeStack(test_compose, project_name="hindsight-base-path-test"):
+                proxy_url = "http://localhost:18080"
+
+                # Give nginx a moment to start
+                time.sleep(2)
+
+                # Test through nginx proxy
+                response = httpx.get(f"{proxy_url}{base_path}/health", timeout=10.0)
+                assert response.status_code == 200
+                assert "status" in response.json()
+
+                # API endpoints through proxy
+                response = httpx.get(f"{proxy_url}{base_path}/v1/default/banks", timeout=10.0)
+                assert response.status_code == 200
+                assert "banks" in response.json()
+
+                # OpenAPI docs through proxy
+                response = httpx.get(f"{proxy_url}{base_path}/docs", timeout=10.0)
+                assert response.status_code == 200
+
+        finally:
+            # Cleanup test files
+            test_compose.unlink(missing_ok=True)
+            test_nginx_conf.unlink(missing_ok=True)
+
+
+@pytest.mark.asyncio
+async def test_full_workflow_with_base_path():
+    """Test full retain/recall workflow through base path."""
+    base_path = "/hindsight"
+    bank_id = "integration_test_bank"
+
+    with APIServer(base_path=base_path, port=18891) as server:
+        base_url = f"http://localhost:{server.port}{base_path}"
+
+        async with httpx.AsyncClient(base_url=base_url, timeout=30.0) as client:
+            # 1. Get bank profile (creates if needed)
+            response = await client.get(f"/v1/default/banks/{bank_id}/profile")
+            assert response.status_code == 200
+
+            # 2. Store a memory
+            response = await client.post(
+                f"/v1/default/banks/{bank_id}/memories",
+                json={
+                    "items": [
+                        {
+                            "content": "Hindsight supports deployment under custom base paths for reverse proxy scenarios.",
+                            "context": "integration test"
+                        }
+                    ]
+                },
+            )
+            assert response.status_code == 200
+            result = response.json()
+            assert result["success"] is True
+
+            # 3. Recall the memory
+            response = await client.post(
+                f"/v1/default/banks/{bank_id}/memories/recall",
+                json={"query": "base path deployment"}
+            )
+            assert response.status_code == 200
+            recall_result = response.json()
+            assert "results" in recall_result
+            # Should find our memory
+            assert len(recall_result["results"]) > 0
+
+
+if __name__ == "__main__":
+    """Run tests directly with python."""
+    import sys
+
+    print("=" * 70)
+    print("Hindsight Base Path Integration Tests")
+    print("=" * 70)
+    print()
+
+    all_passed = True
+
+    # Test 1: Without base path
+    print("Test 1: API without base path (regression test)")
+    print("-" * 70)
+    try:
+        test_api_without_base_path()
+        print("✅ PASSED\n")
+    except Exception as e:
+        print(f"❌ FAILED: {e}\n")
+        all_passed = False
+
+    # Test 2: With base path (direct)
+    print("Test 2: API with base path (direct, no proxy)")
+    print("-" * 70)
+    try:
+        test_api_with_base_path_direct()
+        print("✅ PASSED\n")
+    except Exception as e:
+        print(f"❌ FAILED: {e}\n")
+        all_passed = False
+
+    # Test 3: Docker compose reverse proxy
+    print("Test 3: Reverse proxy via docker-compose")
+    print("-" * 70)
+    if check_docker_available() and check_docker_compose_available():
+        try:
+            test_reverse_proxy_simple_config()
+            print("✅ PASSED\n")
+        except Exception as e:
+            print(f"❌ FAILED: {e}\n")
+            import traceback
+            traceback.print_exc()
+            all_passed = False
+    else:
+        print("⚠️  SKIPPED: Docker or docker-compose not available\n")
+
+    # Test 4: Full workflow
+    print("Test 4: Full retain/recall workflow with base path")
+    print("-" * 70)
+    try:
+        asyncio.run(test_full_workflow_with_base_path())
+        print("✅ PASSED\n")
+    except Exception as e:
+        print(f"❌ FAILED: {e}\n")
+        all_passed = False
+
+    # Summary
+    print("=" * 70)
+    if all_passed:
+        print("✅ All tests passed!")
+        sys.exit(0)
+    else:
+        print("❌ Some tests failed")
+        sys.exit(1)

skills/hindsight-docs/references/developer/installation.md

@@ -3,7 +3,7 @@
 Hindsight can be deployed in several ways depending on your infrastructure and requirements.
 
 :::tip Don't want to manage infrastructure?
-**[Hindsight Cloud](https://vectorize.io/hindsight/cloud)** is a fully managed service that handles all infrastructure, scaling, and maintenance. We're onboarding design partners now — [request early access](https://vectorize.io/hindsight/cloud).
+**[Hindsight Cloud](https://ui.hindsight.vectorize.io/signup)** is a fully managed service that handles all infrastructure, scaling, and maintenance — [sign up here](https://ui.hindsight.vectorize.io/signup).
 :::
 
 ## Prerequisites

skills/hindsight-docs/references/sdks/integrations/skills.md

@@ -161,11 +161,11 @@ uvx hindsight-embed configure
 
 ## Cloud Mode Setup
 
-Cloud mode connects to [Hindsight Cloud](https://vectorize.io/hindsight/cloud), allowing teams to share memories about a codebase. When one team member learns something, everyone benefits.
+Cloud mode connects to [Hindsight Cloud](https://ui.hindsight.vectorize.io/signup), allowing teams to share memories about a codebase. When one team member learns something, everyone benefits.
 
 ### Prerequisites
 
-1. A Hindsight Cloud account ([request access](https://vectorize.io/hindsight/cloud))
+1. A Hindsight Cloud account ([sign up](https://ui.hindsight.vectorize.io/signup))
 2. An API key from your team admin
 3. A bank ID for your project (e.g., `team-acme-frontend`)
 

uv.lock

@@ -1012,6 +1012,58 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/fc/dc/f7dd14213bf511690dccaa5094d436947c253b418c86c86211d1c76e6e44/fastmcp-2.14.3-py3-none-any.whl", hash = "sha256:103c6b4c6e97a9acc251c81d303f110fe4f2bdba31353df515d66272bf1b9414", size = 416220 },
 ]
 
+[[package]]
+name = "fastuuid"
+version = "0.14.0"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/c3/7d/d9daedf0f2ebcacd20d599928f8913e9d2aea1d56d2d355a93bfa2b611d7/fastuuid-0.14.0.tar.gz", hash = "sha256:178947fc2f995b38497a74172adee64fdeb8b7ec18f2a5934d037641ba265d26", size = 18232 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/98/f3/12481bda4e5b6d3e698fbf525df4443cc7dce746f246b86b6fcb2fba1844/fastuuid-0.14.0-cp311-cp311-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl", hash = "sha256:73946cb950c8caf65127d4e9a325e2b6be0442a224fd51ba3b6ac44e1912ce34", size = 516386 },
+    { url = "https://files.pythonhosted.org/packages/59/19/2fc58a1446e4d72b655648eb0879b04e88ed6fa70d474efcf550f640f6ec/fastuuid-0.14.0-cp311-cp311-macosx_10_12_x86_64.whl", hash = "sha256:12ac85024637586a5b69645e7ed986f7535106ed3013640a393a03e461740cb7", size = 264569 },
+    { url = "https://files.pythonhosted.org/packages/78/29/3c74756e5b02c40cfcc8b1d8b5bac4edbd532b55917a6bcc9113550e99d1/fastuuid-0.14.0-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:05a8dde1f395e0c9b4be515b7a521403d1e8349443e7641761af07c7ad1624b1", size = 254366 },
+    { url = "https://files.pythonhosted.org/packages/52/96/d761da3fccfa84f0f353ce6e3eb8b7f76b3aa21fd25e1b00a19f9c80a063/fastuuid-0.14.0-cp311-cp311-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:09378a05020e3e4883dfdab438926f31fea15fd17604908f3d39cbeb22a0b4dc", size = 278978 },
+    { url = "https://files.pythonhosted.org/packages/fc/c2/f84c90167cc7765cb82b3ff7808057608b21c14a38531845d933a4637307/fastuuid-0.14.0-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:bbb0c4b15d66b435d2538f3827f05e44e2baafcc003dd7d8472dc67807ab8fd8", size = 279692 },
+    { url = "https://files.pythonhosted.org/packages/af/7b/4bacd03897b88c12348e7bd77943bac32ccf80ff98100598fcff74f75f2e/fastuuid-0.14.0-cp311-cp311-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:cd5a7f648d4365b41dbf0e38fe8da4884e57bed4e77c83598e076ac0c93995e7", size = 303384 },
+    { url = "https://files.pythonhosted.org/packages/c0/a2/584f2c29641df8bd810d00c1f21d408c12e9ad0c0dafdb8b7b29e5ddf787/fastuuid-0.14.0-cp311-cp311-musllinux_1_1_aarch64.whl", hash = "sha256:c0a94245afae4d7af8c43b3159d5e3934c53f47140be0be624b96acd672ceb73", size = 460921 },
+    { url = "https://files.pythonhosted.org/packages/24/68/c6b77443bb7764c760e211002c8638c0c7cce11cb584927e723215ba1398/fastuuid-0.14.0-cp311-cp311-musllinux_1_1_i686.whl", hash = "sha256:2b29e23c97e77c3a9514d70ce343571e469098ac7f5a269320a0f0b3e193ab36", size = 480575 },
+    { url = "https://files.pythonhosted.org/packages/5a/87/93f553111b33f9bb83145be12868c3c475bf8ea87c107063d01377cc0e8e/fastuuid-0.14.0-cp311-cp311-musllinux_1_1_x86_64.whl", hash = "sha256:1e690d48f923c253f28151b3a6b4e335f2b06bf669c68a02665bc150b7839e94", size = 452317 },
+    { url = "https://files.pythonhosted.org/packages/9e/8c/a04d486ca55b5abb7eaa65b39df8d891b7b1635b22db2163734dc273579a/fastuuid-0.14.0-cp311-cp311-win32.whl", hash = "sha256:a6f46790d59ab38c6aa0e35c681c0484b50dc0acf9e2679c005d61e019313c24", size = 154804 },
+    { url = "https://files.pythonhosted.org/packages/9c/b2/2d40bf00820de94b9280366a122cbaa60090c8cf59e89ac3938cf5d75895/fastuuid-0.14.0-cp311-cp311-win_amd64.whl", hash = "sha256:e150eab56c95dc9e3fefc234a0eedb342fac433dacc273cd4d150a5b0871e1fa", size = 156099 },
+    { url = "https://files.pythonhosted.org/packages/02/a2/e78fcc5df65467f0d207661b7ef86c5b7ac62eea337c0c0fcedbeee6fb13/fastuuid-0.14.0-cp312-cp312-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl", hash = "sha256:77e94728324b63660ebf8adb27055e92d2e4611645bf12ed9d88d30486471d0a", size = 510164 },
+    { url = "https://files.pythonhosted.org/packages/2b/b3/c846f933f22f581f558ee63f81f29fa924acd971ce903dab1a9b6701816e/fastuuid-0.14.0-cp312-cp312-macosx_10_12_x86_64.whl", hash = "sha256:caa1f14d2102cb8d353096bc6ef6c13b2c81f347e6ab9d6fbd48b9dea41c153d", size = 261837 },
+    { url = "https://files.pythonhosted.org/packages/54/ea/682551030f8c4fa9a769d9825570ad28c0c71e30cf34020b85c1f7ee7382/fastuuid-0.14.0-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:d23ef06f9e67163be38cece704170486715b177f6baae338110983f99a72c070", size = 251370 },
+    { url = "https://files.pythonhosted.org/packages/14/dd/5927f0a523d8e6a76b70968e6004966ee7df30322f5fc9b6cdfb0276646a/fastuuid-0.14.0-cp312-cp312-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:0c9ec605ace243b6dbe3bd27ebdd5d33b00d8d1d3f580b39fdd15cd96fd71796", size = 277766 },
+    { url = "https://files.pythonhosted.org/packages/16/6e/c0fb547eef61293153348f12e0f75a06abb322664b34a1573a7760501336/fastuuid-0.14.0-cp312-cp312-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:808527f2407f58a76c916d6aa15d58692a4a019fdf8d4c32ac7ff303b7d7af09", size = 278105 },
+    { url = "https://files.pythonhosted.org/packages/2d/b1/b9c75e03b768f61cf2e84ee193dc18601aeaf89a4684b20f2f0e9f52b62c/fastuuid-0.14.0-cp312-cp312-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:2fb3c0d7fef6674bbeacdd6dbd386924a7b60b26de849266d1ff6602937675c8", size = 301564 },
+    { url = "https://files.pythonhosted.org/packages/fc/fa/f7395fdac07c7a54f18f801744573707321ca0cee082e638e36452355a9d/fastuuid-0.14.0-cp312-cp312-musllinux_1_1_aarch64.whl", hash = "sha256:ab3f5d36e4393e628a4df337c2c039069344db5f4b9d2a3c9cea48284f1dd741", size = 459659 },
+    { url = "https://files.pythonhosted.org/packages/66/49/c9fd06a4a0b1f0f048aacb6599e7d96e5d6bc6fa680ed0d46bf111929d1b/fastuuid-0.14.0-cp312-cp312-musllinux_1_1_i686.whl", hash = "sha256:b9a0ca4f03b7e0b01425281ffd44e99d360e15c895f1907ca105854ed85e2057", size = 478430 },
+    { url = "https://files.pythonhosted.org/packages/be/9c/909e8c95b494e8e140e8be6165d5fc3f61fdc46198c1554df7b3e1764471/fastuuid-0.14.0-cp312-cp312-musllinux_1_1_x86_64.whl", hash = "sha256:3acdf655684cc09e60fb7e4cf524e8f42ea760031945aa8086c7eae2eeeabeb8", size = 450894 },
+    { url = "https://files.pythonhosted.org/packages/90/eb/d29d17521976e673c55ef7f210d4cdd72091a9ec6755d0fd4710d9b3c871/fastuuid-0.14.0-cp312-cp312-win32.whl", hash = "sha256:9579618be6280700ae36ac42c3efd157049fe4dd40ca49b021280481c78c3176", size = 154374 },
+    { url = "https://files.pythonhosted.org/packages/cc/fc/f5c799a6ea6d877faec0472d0b27c079b47c86b1cdc577720a5386483b36/fastuuid-0.14.0-cp312-cp312-win_amd64.whl", hash = "sha256:d9e4332dc4ba054434a9594cbfaf7823b57993d7d8e7267831c3e059857cf397", size = 156550 },
+    { url = "https://files.pythonhosted.org/packages/a5/83/ae12dd39b9a39b55d7f90abb8971f1a5f3c321fd72d5aa83f90dc67fe9ed/fastuuid-0.14.0-cp313-cp313-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl", hash = "sha256:77a09cb7427e7af74c594e409f7731a0cf887221de2f698e1ca0ebf0f3139021", size = 510720 },
+    { url = "https://files.pythonhosted.org/packages/53/b0/a4b03ff5d00f563cc7546b933c28cb3f2a07344b2aec5834e874f7d44143/fastuuid-0.14.0-cp313-cp313-macosx_10_12_x86_64.whl", hash = "sha256:9bd57289daf7b153bfa3e8013446aa144ce5e8c825e9e366d455155ede5ea2dc", size = 262024 },
+    { url = "https://files.pythonhosted.org/packages/9c/6d/64aee0a0f6a58eeabadd582e55d0d7d70258ffdd01d093b30c53d668303b/fastuuid-0.14.0-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:ac60fc860cdf3c3f327374db87ab8e064c86566ca8c49d2e30df15eda1b0c2d5", size = 251679 },
+    { url = "https://files.pythonhosted.org/packages/60/f5/a7e9cda8369e4f7919d36552db9b2ae21db7915083bc6336f1b0082c8b2e/fastuuid-0.14.0-cp313-cp313-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:ab32f74bd56565b186f036e33129da77db8be09178cd2f5206a5d4035fb2a23f", size = 277862 },
+    { url = "https://files.pythonhosted.org/packages/f0/d3/8ce11827c783affffd5bd4d6378b28eb6cc6d2ddf41474006b8d62e7448e/fastuuid-0.14.0-cp313-cp313-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:33e678459cf4addaedd9936bbb038e35b3f6b2061330fd8f2f6a1d80414c0f87", size = 278278 },
+    { url = "https://files.pythonhosted.org/packages/a2/51/680fb6352d0bbade04036da46264a8001f74b7484e2fd1f4da9e3db1c666/fastuuid-0.14.0-cp313-cp313-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:1e3cc56742f76cd25ecb98e4b82a25f978ccffba02e4bdce8aba857b6d85d87b", size = 301788 },
+    { url = "https://files.pythonhosted.org/packages/fa/7c/2014b5785bd8ebdab04ec857635ebd84d5ee4950186a577db9eff0fb8ff6/fastuuid-0.14.0-cp313-cp313-musllinux_1_1_aarch64.whl", hash = "sha256:cb9a030f609194b679e1660f7e32733b7a0f332d519c5d5a6a0a580991290022", size = 459819 },
+    { url = "https://files.pythonhosted.org/packages/01/d2/524d4ceeba9160e7a9bc2ea3e8f4ccf1ad78f3bde34090ca0c51f09a5e91/fastuuid-0.14.0-cp313-cp313-musllinux_1_1_i686.whl", hash = "sha256:09098762aad4f8da3a888eb9ae01c84430c907a297b97166b8abc07b640f2995", size = 478546 },
+    { url = "https://files.pythonhosted.org/packages/bc/17/354d04951ce114bf4afc78e27a18cfbd6ee319ab1829c2d5fb5e94063ac6/fastuuid-0.14.0-cp313-cp313-musllinux_1_1_x86_64.whl", hash = "sha256:1383fff584fa249b16329a059c68ad45d030d5a4b70fb7c73a08d98fd53bcdab", size = 450921 },
+    { url = "https://files.pythonhosted.org/packages/fb/be/d7be8670151d16d88f15bb121c5b66cdb5ea6a0c2a362d0dcf30276ade53/fastuuid-0.14.0-cp313-cp313-win32.whl", hash = "sha256:a0809f8cc5731c066c909047f9a314d5f536c871a7a22e815cc4967c110ac9ad", size = 154559 },
+    { url = "https://files.pythonhosted.org/packages/22/1d/5573ef3624ceb7abf4a46073d3554e37191c868abc3aecd5289a72f9810a/fastuuid-0.14.0-cp313-cp313-win_amd64.whl", hash = "sha256:0df14e92e7ad3276327631c9e7cec09e32572ce82089c55cb1bb8df71cf394ed", size = 156539 },
+    { url = "https://files.pythonhosted.org/packages/16/c9/8c7660d1fe3862e3f8acabd9be7fc9ad71eb270f1c65cce9a2b7a31329ab/fastuuid-0.14.0-cp314-cp314-macosx_10_12_x86_64.macosx_11_0_arm64.macosx_10_12_universal2.whl", hash = "sha256:b852a870a61cfc26c884af205d502881a2e59cc07076b60ab4a951cc0c94d1ad", size = 510600 },
+    { url = "https://files.pythonhosted.org/packages/4c/f4/a989c82f9a90d0ad995aa957b3e572ebef163c5299823b4027986f133dfb/fastuuid-0.14.0-cp314-cp314-macosx_10_12_x86_64.whl", hash = "sha256:c7502d6f54cd08024c3ea9b3514e2d6f190feb2f46e6dbcd3747882264bb5f7b", size = 262069 },
+    { url = "https://files.pythonhosted.org/packages/da/6c/a1a24f73574ac995482b1326cf7ab41301af0fabaa3e37eeb6b3df00e6e2/fastuuid-0.14.0-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:1ca61b592120cf314cfd66e662a5b54a578c5a15b26305e1b8b618a6f22df714", size = 251543 },
+    { url = "https://files.pythonhosted.org/packages/1a/20/2a9b59185ba7a6c7b37808431477c2d739fcbdabbf63e00243e37bd6bf49/fastuuid-0.14.0-cp314-cp314-manylinux_2_17_aarch64.manylinux2014_aarch64.whl", hash = "sha256:aa75b6657ec129d0abded3bec745e6f7ab642e6dba3a5272a68247e85f5f316f", size = 277798 },
+    { url = "https://files.pythonhosted.org/packages/ef/33/4105ca574f6ded0af6a797d39add041bcfb468a1255fbbe82fcb6f592da2/fastuuid-0.14.0-cp314-cp314-manylinux_2_17_x86_64.manylinux2014_x86_64.whl", hash = "sha256:a8a0dfea3972200f72d4c7df02c8ac70bad1bb4c58d7e0ec1e6f341679073a7f", size = 278283 },
+    { url = "https://files.pythonhosted.org/packages/fe/8c/fca59f8e21c4deb013f574eae05723737ddb1d2937ce87cb2a5d20992dc3/fastuuid-0.14.0-cp314-cp314-manylinux_2_5_i686.manylinux1_i686.whl", hash = "sha256:1bf539a7a95f35b419f9ad105d5a8a35036df35fdafae48fb2fd2e5f318f0d75", size = 301627 },
+    { url = "https://files.pythonhosted.org/packages/cb/e2/f78c271b909c034d429218f2798ca4e89eeda7983f4257d7865976ddbb6c/fastuuid-0.14.0-cp314-cp314-musllinux_1_1_aarch64.whl", hash = "sha256:9a133bf9cc78fdbd1179cb58a59ad0100aa32d8675508150f3658814aeefeaa4", size = 459778 },
+    { url = "https://files.pythonhosted.org/packages/1e/f0/5ff209d865897667a2ff3e7a572267a9ced8f7313919f6d6043aed8b1caa/fastuuid-0.14.0-cp314-cp314-musllinux_1_1_i686.whl", hash = "sha256:f54d5b36c56a2d5e1a31e73b950b28a0d83eb0c37b91d10408875a5a29494bad", size = 478605 },
+    { url = "https://files.pythonhosted.org/packages/e0/c8/2ce1c78f983a2c4987ea865d9516dbdfb141a120fd3abb977ae6f02ba7ca/fastuuid-0.14.0-cp314-cp314-musllinux_1_1_x86_64.whl", hash = "sha256:ec27778c6ca3393ef662e2762dba8af13f4ec1aaa32d08d77f71f2a70ae9feb8", size = 450837 },
+    { url = "https://files.pythonhosted.org/packages/df/60/dad662ec9a33b4a5fe44f60699258da64172c39bd041da2994422cdc40fe/fastuuid-0.14.0-cp314-cp314-win32.whl", hash = "sha256:e23fc6a83f112de4be0cc1990e5b127c27663ae43f866353166f87df58e73d06", size = 154532 },
+    { url = "https://files.pythonhosted.org/packages/1f/f6/da4db31001e854025ffd26bc9ba0740a9cbba2c3259695f7c5834908b336/fastuuid-0.14.0-cp314-cp314-win_amd64.whl", hash = "sha256:df61342889d0f5e7a32f7284e55ef95103f2110fee433c2ae7c2c0956d76ac8a", size = 156457 },
+]
+
 [[package]]
 name = "filelock"
 version = "3.20.3"
@@ -1370,6 +1422,7 @@ dependencies = [
     { name = "httpx" },
     { name = "langchain-core" },
     { name = "langchain-text-splitters" },
+    { name = "litellm" },
     { name = "openai" },
     { name = "opentelemetry-api" },
     { name = "opentelemetry-exporter-otlp-proto-http" },
@@ -1440,6 +1493,7 @@ requires-dist = [
     { name = "httpx", specifier = ">=0.27.0" },
     { name = "langchain-core", specifier = ">=1.2.5" },
     { name = "langchain-text-splitters", specifier = ">=0.3.0" },
+    { name = "litellm", specifier = ">=1.0.0" },
     { name = "openai", specifier = ">=1.0.0" },
     { name = "opentelemetry-api", specifier = ">=1.20.0" },
     { name = "opentelemetry-exporter-otlp-proto-http", specifier = ">=1.20.0" },
@@ -2018,6 +2072,29 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/0f/17/4280bc381b40a642ea5efe1bab0237f03507a9d4281484c5baa1db82055a/langsmith-0.4.42-py3-none-any.whl", hash = "sha256:015b0a0c17eb1a61293e8cbb7d41778a4b37caddd267d54274ba94e4721b301b", size = 401937 },
 ]
 
+[[package]]
+name = "litellm"
+version = "1.81.10"
+source = { registry = "https://pypi.org/simple" }
+dependencies = [
+    { name = "aiohttp" },
+    { name = "click" },
+    { name = "fastuuid" },
+    { name = "httpx" },
+    { name = "importlib-metadata" },
+    { name = "jinja2" },
+    { name = "jsonschema" },
+    { name = "openai" },
+    { name = "pydantic" },
+    { name = "python-dotenv" },
+    { name = "tiktoken" },
+    { name = "tokenizers" },
+]
+sdist = { url = "https://files.pythonhosted.org/packages/40/fc/78887158b4057835ba2c647a1bd4da650fd79142f8412c6d0bbe6d8c6081/litellm-1.81.10.tar.gz", hash = "sha256:8d769a7200888e1295592af5ce5cb0ff035832250bd0102a4ca50acf5820ca50", size = 16297572 }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/b1/bb/3f3cc3d79657bc9daaa1319ec3a9d75e4889fc88d07e327f0ac02cd2ac7d/litellm-1.81.10-py3-none-any.whl", hash = "sha256:9efa1cbe61ac051f6500c267b173d988ff2d511c2eecf1c8f2ee546c0870747c", size = 14457931 },
+]
+
 [[package]]
 name = "lupa"
 version = "2.6"
@@ -2624,7 +2701,7 @@ wheels = [
 
 [[package]]
 name = "openai"
-version = "2.7.2"
+version = "2.20.0"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "anyio" },
@@ -2636,9 +2713,9 @@ dependencies = [
     { name = "tqdm" },
     { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/71/e3/cec27fa28ef36c4ccea71e9e8c20be9b8539618732989a82027575aab9d4/openai-2.7.2.tar.gz", hash = "sha256:082ef61163074d8efad0035dd08934cf5e3afd37254f70fc9165dd6a8c67dcbd", size = 595732 }
+sdist = { url = "https://files.pythonhosted.org/packages/6e/5a/f495777c02625bfa18212b6e3b73f1893094f2bf660976eb4bc6f43a1ca2/openai-2.20.0.tar.gz", hash = "sha256:2654a689208cd0bf1098bb9462e8d722af5cbe961e6bba54e6f19fb843d88db1", size = 642355 }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/25/66/22cfe4b695b5fd042931b32c67d685e867bfd169ebf46036b95b57314c33/openai-2.7.2-py3-none-any.whl", hash = "sha256:116f522f4427f8a0a59b51655a356da85ce092f3ed6abeca65f03c8be6e073d9", size = 1008375 },
+    { url = "https://files.pythonhosted.org/packages/b5/a0/cf4297aa51bbc21e83ef0ac018947fa06aea8f2364aad7c96cbf148590e6/openai-2.20.0-py3-none-any.whl", hash = "sha256:38d989c4b1075cd1f76abc68364059d822327cf1a932531d429795f4fc18be99", size = 1098479 },
 ]
 
 [[package]]