feat: support litellm-sdk for reranker endpoint

chore: remove dead code
2026-02-12 14:43:35 +01:00 · 2026-02-12 14:21:53 +01:00 · 2026-02-12 14:21:26 +01:00
737 changed files with 22730 additions and 110309 deletions
@@ -5,7 +5,7 @@
 # Supported providers: openai, groq, ollama, gemini, anthropic, lmstudio, vertexai
 HINDSIGHT_API_LLM_PROVIDER=openai
 HINDSIGHT_API_LLM_API_KEY=your-api-key-here
-HINDSIGHT_API_LLM_MODEL=gpt-4o-mini
+HINDSIGHT_API_LLM_MODEL=o3-mini
 HINDSIGHT_API_LLM_BASE_URL=https://api.openai.com/v1

 # Example: Anthropic Claude configuration
@@ -41,12 +41,6 @@ HINDSIGHT_API_LOG_LEVEL=info
 # HINDSIGHT_API_DATABASE_URL=postgresql://user:pass@host:5432/db
 # HINDSIGHT_API_DATABASE_SCHEMA=public  # PostgreSQL schema name (default: public)

-# Vector Extension (Optional - uses pgvector by default)
-# Options: "pgvector" (default), "vchord", "pgvectorscale" (DiskANN)
-# HINDSIGHT_API_VECTOR_EXTENSION=pgvector
-# For Azure PostgreSQL with DiskANN:
-# HINDSIGHT_API_VECTOR_EXTENSION=pgvectorscale  # Auto-detects pg_diskann on Azure
-
 # Embeddings Configuration (Optional - uses local by default)
 # Provider: "local" (default) or "tei" (HuggingFace Text Embeddings Inference)
 # HINDSIGHT_API_EMBEDDINGS_PROVIDER=local
@@ -31,9 +31,6 @@ jobs:
      - run: npm ci --workspace=hindsight-docs
      - run: uv run generate-llms-full
      - run: npm run build --workspace=hindsight-docs
-        env:
-          UMAMI_URL: https://analytics.hindsight.vectorize.io
-          UMAMI_WEBSITE_ID: ${{ secrets.UMAMI_WEBSITE_ID }}
      - uses: actions/upload-pages-artifact@v3
        with:
          path: hindsight-docs/build
@@ -46,14 +46,6 @@ jobs:
      working-directory: ./hindsight-embed
      run: uv build --out-dir dist

-    - name: Build hindsight-crewai
-      working-directory: ./hindsight-integrations/crewai
-      run: uv build --out-dir dist
-
-    - name: Build hindsight-pydantic-ai
-      working-directory: ./hindsight-integrations/pydantic-ai
-      run: uv build --out-dir dist
-
    # Publish in order (client and api first, then hindsight-all which depends on them)
    - name: Publish hindsight-client to PyPI
      uses: pypa/gh-action-pypi-publish@release/v1
@@ -85,18 +77,6 @@ jobs:
        packages-dir: ./hindsight-embed/dist
        skip-existing: true

-    - name: Publish hindsight-crewai to PyPI
-      uses: pypa/gh-action-pypi-publish@release/v1
-      with:
-        packages-dir: ./hindsight-integrations/crewai/dist
-        skip-existing: true
-
-    - name: Publish hindsight-pydantic-ai to PyPI
-      uses: pypa/gh-action-pypi-publish@release/v1
-      with:
-        packages-dir: ./hindsight-integrations/pydantic-ai/dist
-        skip-existing: true
-
    # Upload artifacts for GitHub release
    - name: Upload artifacts
      uses: actions/upload-artifact@v4
@@ -108,8 +88,6 @@ jobs:
          hindsight/dist/*
          hindsight-integrations/litellm/dist/*
          hindsight-embed/dist/*
-          hindsight-integrations/crewai/dist/*
-          hindsight-integrations/pydantic-ai/dist/*
        retention-days: 1

  release-typescript-client:
@@ -259,55 +237,6 @@ jobs:
        path: hindsight-integrations/ai-sdk/*.tgz
        retention-days: 1

-  release-chat-integration:
-    runs-on: ubuntu-latest
-    environment: npm
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Set up Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version: '22'
-        registry-url: 'https://registry.npmjs.org'
-
-    - name: Install dependencies
-      working-directory: ./hindsight-integrations/chat
-      run: npm ci
-
-    - name: Build
-      working-directory: ./hindsight-integrations/chat
-      run: npm run build
-
-    - name: Publish to npm
-      working-directory: ./hindsight-integrations/chat
-      run: |
-        set +e
-        OUTPUT=$(npm publish --access public 2>&1)
-        EXIT_CODE=$?
-        echo "$OUTPUT"
-        if [ $EXIT_CODE -ne 0 ]; then
-          if echo "$OUTPUT" | grep -q "cannot publish over"; then
-            echo "Package version already published, skipping..."
-            exit 0
-          fi
-          exit $EXIT_CODE
-        fi
-      env:
-        NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
-
-    - name: Pack for GitHub release
-      working-directory: ./hindsight-integrations/chat
-      run: npm pack
-
-    - name: Upload artifacts
-      uses: actions/upload-artifact@v4
-      with:
-        name: chat-integration
-        path: hindsight-integrations/chat/*.tgz
-        retention-days: 1
-
  release-control-plane:
    runs-on: ubuntu-latest
    environment: npm
@@ -339,14 +268,11 @@ jobs:
    - name: Build
      run: npm run build --workspace=hindsight-control-plane

-    - name: Verify standalone build
-      run: test -f hindsight-control-plane/standalone/server.js || (echo 'standalone/server.js missing - build failed' && exit 1)
-
    - name: Publish to npm
      working-directory: ./hindsight-control-plane
      run: |
        set +e
-        OUTPUT=$(npm publish --access public --ignore-scripts 2>&1)
+        OUTPUT=$(npm publish --access public 2>&1)
        EXIT_CODE=$?
        echo "$OUTPUT"
        if [ $EXIT_CODE -ne 0 ]; then
@@ -387,10 +313,6 @@ jobs:
            target: aarch64-apple-darwin
            artifact_name: hindsight
            asset_name: hindsight-darwin-arm64
-          - os: ubuntu-24.04-arm
-            target: aarch64-unknown-linux-gnu
-            artifact_name: hindsight
-            asset_name: hindsight-linux-arm64

    steps:
    - uses: actions/checkout@v4
@@ -565,7 +487,7 @@ jobs:

  create-github-release:
    runs-on: ubuntu-latest
-    needs: [release-python-packages, release-typescript-client, release-openclaw-integration, release-ai-sdk-integration, release-chat-integration, release-control-plane, release-rust-cli, release-docker-images, release-helm-chart]
+    needs: [release-python-packages, release-typescript-client, release-openclaw-integration, release-ai-sdk-integration, release-control-plane, release-rust-cli, release-docker-images, release-helm-chart]
    permissions:
      contents: write

@@ -600,12 +522,6 @@ jobs:
        name: ai-sdk-integration
        path: ./artifacts/ai-sdk-integration

-    - name: Download Chat Integration
-      uses: actions/download-artifact@v4
-      with:
-        name: chat-integration
-        path: ./artifacts/chat-integration
-
    - name: Download Control Plane
      uses: actions/download-artifact@v4
      with:
@@ -644,7 +560,6 @@ jobs:
        cp artifacts/python-packages/hindsight-api/dist/* release-assets/ || true
        cp artifacts/python-packages/hindsight/dist/* release-assets/ || true
        cp artifacts/python-packages/hindsight-integrations/litellm/dist/* release-assets/ || true
-        cp artifacts/python-packages/hindsight-integrations/pydantic-ai/dist/* release-assets/ || true
        cp artifacts/python-packages/hindsight-embed/dist/* release-assets/ || true
        # TypeScript client
        cp artifacts/typescript-client/*.tgz release-assets/ || true
@@ -652,8 +567,6 @@ jobs:
        cp artifacts/openclaw-integration/*.tgz release-assets/ || true
        # AI SDK Integration
        cp artifacts/ai-sdk-integration/*.tgz release-assets/ || true
-        # Chat Integration
-        cp artifacts/chat-integration/*.tgz release-assets/ || true
        # Control Plane
        cp artifacts/control-plane/*.tgz release-assets/ || true
        # Rust CLI binaries
@@ -97,29 +97,6 @@ jobs:
      working-directory: ./hindsight-integrations/ai-sdk
      run: npm run build

-  build-chat-integration:
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Set up Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version: '22'
-
-    - name: Install dependencies
-      working-directory: ./hindsight-integrations/chat
-      run: npm ci
-
-    - name: Run tests
-      working-directory: ./hindsight-integrations/chat
-      run: npm test
-
-    - name: Build
-      working-directory: ./hindsight-integrations/chat
-      run: npm run build
-
  build-control-plane:
    runs-on: ubuntu-latest

@@ -194,9 +171,9 @@ jobs:
  test-rust-cli:
    runs-on: ubuntu-latest
    env:
-      HINDSIGHT_API_LLM_PROVIDER: vertexai
-      HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY: /tmp/gcp-credentials.json
-      HINDSIGHT_API_LLM_MODEL: google/gemini-2.5-flash-lite
+      HINDSIGHT_API_LLM_PROVIDER: groq
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
      HINDSIGHT_API_URL: http://localhost:8888
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu
@@ -204,12 +181,6 @@ jobs:
    steps:
    - uses: actions/checkout@v4

-    - name: Setup GCP credentials
-      run: |
-        printf '%s' '${{ secrets.GCP_VERTEXAI_CREDENTIALS }}' > /tmp/gcp-credentials.json
-        PROJECT_ID=$(jq -r '.project_id' /tmp/gcp-credentials.json)
-        echo "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$PROJECT_ID" >> $GITHUB_ENV
-
    - name: Install Rust
      uses: dtolnay/rust-toolchain@stable

@@ -256,46 +227,25 @@ jobs:
      working-directory: ./hindsight-api
      run: uv sync --frozen --no-install-project --index-strategy unsafe-best-match

-    - name: Cache HuggingFace models
-      uses: actions/cache@v4
-      with:
-        path: ~/.cache/huggingface
-        key: ${{ runner.os }}-huggingface-${{ hashFiles('hindsight-api/pyproject.toml') }}
-        restore-keys: |
-          ${{ runner.os }}-huggingface-
-
-    - name: Pre-download models
-      working-directory: ./hindsight-api
-      run: |
-        uv run python -c "
-        from sentence_transformers import SentenceTransformer, CrossEncoder
-        print('Downloading embedding model...')
-        SentenceTransformer('BAAI/bge-small-en-v1.5')
-        print('Downloading cross-encoder model...')
-        CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2')
-        print('Models downloaded successfully')
-        "
-
    - name: Create .env file
      run: |
        cat > .env << EOF
        HINDSIGHT_API_LLM_PROVIDER=${{ env.HINDSIGHT_API_LLM_PROVIDER }}
+        HINDSIGHT_API_LLM_API_KEY=${{ env.HINDSIGHT_API_LLM_API_KEY }}
        HINDSIGHT_API_LLM_MODEL=${{ env.HINDSIGHT_API_LLM_MODEL }}
-        HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY=/tmp/gcp-credentials.json
-        HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID
        EOF

    - name: Start API server
      run: |
        ./scripts/dev/start-api.sh > /tmp/api-server.log 2>&1 &
        echo "Waiting for API server to be ready..."
-        for i in {1..120}; do
+        for i in {1..60}; do
          if curl -sf http://localhost:8888/health > /dev/null 2>&1; then
            echo "API server is ready after ${i}s"
            break
          fi
-          if [ $i -eq 120 ]; then
-            echo "API server failed to start after 120s"
+          if [ $i -eq 60 ]; then
+            echo "API server failed to start after 60s"
            cat /tmp/api-server.log
            exit 1
          fi
@@ -390,21 +340,12 @@ jobs:

    # Only test slim variants to save disk space (they're much smaller)
    # Slim variants require external embedding providers
-    - name: Setup GCP credentials for smoke test
-      if: matrix.variant == 'slim'
-      run: |
-        printf '%s' '${{ secrets.GCP_VERTEXAI_CREDENTIALS }}' > /tmp/gcp-credentials.json
-        PROJECT_ID=$(jq -r '.project_id' /tmp/gcp-credentials.json)
-        echo "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$PROJECT_ID" >> $GITHUB_ENV
-
    - name: Smoke test - verify container starts
      if: matrix.variant == 'slim'
      env:
-        HINDSIGHT_API_LLM_PROVIDER: vertexai
-        HINDSIGHT_API_LLM_MODEL: google/gemini-2.5-flash-lite
-        HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY: /tmp/gcp-credentials.json
-        HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID: ${{ env.HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID }}
-        HINDSIGHT_API_EMBEDDINGS_PROVIDER: cohere
+        GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
+        HINDSIGHT_API_EMBEDDINGS_PROVIDER: openai
+        HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
        HINDSIGHT_API_RERANKER_PROVIDER: cohere
        HINDSIGHT_API_COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}
      run: ./docker/test-image.sh "hindsight-${{ matrix.name }}:test" "${{ matrix.target }}"
@@ -412,13 +353,14 @@ jobs:
  test-api:
    runs-on: ubuntu-latest
    env:
-      HINDSIGHT_API_LLM_PROVIDER: vertexai
-      HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY: /tmp/gcp-credentials.json
-      HINDSIGHT_API_LLM_MODEL: google/gemini-2.5-flash-lite
+      HINDSIGHT_API_LLM_PROVIDER: groq
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
+      GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
      GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
      COHERE_API_KEY: ${{ secrets.COHERE_API_KEY }}
      HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # Prefer CPU-only PyTorch in CI (but keep PyPI for everything else)
      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu
@@ -426,12 +368,6 @@ jobs:
    steps:
    - uses: actions/checkout@v4

-    - name: Setup GCP credentials
-      run: |
-        printf '%s' '${{ secrets.GCP_VERTEXAI_CREDENTIALS }}' > /tmp/gcp-credentials.json
-        PROJECT_ID=$(jq -r '.project_id' /tmp/gcp-credentials.json)
-        echo "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$PROJECT_ID" >> $GITHUB_ENV
-
    - name: Install uv
      uses: astral-sh/setup-uv@v5
      with:
@@ -478,9 +414,9 @@ jobs:
  test-python-client:
    runs-on: ubuntu-latest
    env:
-      HINDSIGHT_API_LLM_PROVIDER: vertexai
-      HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY: /tmp/gcp-credentials.json
-      HINDSIGHT_API_LLM_MODEL: google/gemini-2.5-flash-lite
+      HINDSIGHT_API_LLM_PROVIDER: groq
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
      HINDSIGHT_API_URL: http://localhost:8888
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # Prefer CPU-only PyTorch in CI (but keep PyPI for everything else)
@@ -489,12 +425,6 @@ jobs:
    steps:
    - uses: actions/checkout@v4

-    - name: Setup GCP credentials
-      run: |
-        printf '%s' '${{ secrets.GCP_VERTEXAI_CREDENTIALS }}' > /tmp/gcp-credentials.json
-        PROJECT_ID=$(jq -r '.project_id' /tmp/gcp-credentials.json)
-        echo "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$PROJECT_ID" >> $GITHUB_ENV
-
    - name: Install uv
      uses: astral-sh/setup-uv@v5
      with:
@@ -522,46 +452,25 @@ jobs:
      working-directory: ./hindsight-api
      run: uv sync --frozen --no-install-project --index-strategy unsafe-best-match

-    - name: Cache HuggingFace models
-      uses: actions/cache@v4
-      with:
-        path: ~/.cache/huggingface
-        key: ${{ runner.os }}-huggingface-${{ hashFiles('hindsight-api/pyproject.toml') }}
-        restore-keys: |
-          ${{ runner.os }}-huggingface-
-
-    - name: Pre-download models
-      working-directory: ./hindsight-api
-      run: |
-        uv run python -c "
-        from sentence_transformers import SentenceTransformer, CrossEncoder
-        print('Downloading embedding model...')
-        SentenceTransformer('BAAI/bge-small-en-v1.5')
-        print('Downloading cross-encoder model...')
-        CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2')
-        print('Models downloaded successfully')
-        "
-
    - name: Create .env file
      run: |
        cat > .env << EOF
        HINDSIGHT_API_LLM_PROVIDER=${{ env.HINDSIGHT_API_LLM_PROVIDER }}
+        HINDSIGHT_API_LLM_API_KEY=${{ env.HINDSIGHT_API_LLM_API_KEY }}
        HINDSIGHT_API_LLM_MODEL=${{ env.HINDSIGHT_API_LLM_MODEL }}
-        HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY=/tmp/gcp-credentials.json
-        HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID
        EOF

    - name: Start API server
      run: |
        ./scripts/dev/start-api.sh > /tmp/api-server.log 2>&1 &
        echo "Waiting for API server to be ready..."
-        for i in {1..120}; do
+        for i in {1..60}; do
          if curl -sf http://localhost:8888/health > /dev/null 2>&1; then
            echo "API server is ready after ${i}s"
            break
          fi
-          if [ $i -eq 120 ]; then
-            echo "API server failed to start after 120s"
+          if [ $i -eq 60 ]; then
+            echo "API server failed to start after 60s"
            cat /tmp/api-server.log
            exit 1
          fi
@@ -581,9 +490,9 @@ jobs:
  test-typescript-client:
    runs-on: ubuntu-latest
    env:
-      HINDSIGHT_API_LLM_PROVIDER: vertexai
-      HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY: /tmp/gcp-credentials.json
-      HINDSIGHT_API_LLM_MODEL: google/gemini-2.5-flash-lite
+      HINDSIGHT_API_LLM_PROVIDER: groq
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
      HINDSIGHT_API_URL: http://localhost:8888
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # Prefer CPU-only PyTorch in CI (but keep PyPI for everything else)
@@ -592,12 +501,6 @@ jobs:
    steps:
    - uses: actions/checkout@v4

-    - name: Setup GCP credentials
-      run: |
-        printf '%s' '${{ secrets.GCP_VERTEXAI_CREDENTIALS }}' > /tmp/gcp-credentials.json
-        PROJECT_ID=$(jq -r '.project_id' /tmp/gcp-credentials.json)
-        echo "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$PROJECT_ID" >> $GITHUB_ENV
-
    - name: Install uv
      uses: astral-sh/setup-uv@v5
      with:
@@ -630,46 +533,25 @@ jobs:
      working-directory: ./hindsight-clients/typescript
      run: npm run build

-    - name: Cache HuggingFace models
-      uses: actions/cache@v4
-      with:
-        path: ~/.cache/huggingface
-        key: ${{ runner.os }}-huggingface-${{ hashFiles('hindsight-api/pyproject.toml') }}
-        restore-keys: |
-          ${{ runner.os }}-huggingface-
-
-    - name: Pre-download models
-      working-directory: ./hindsight-api
-      run: |
-        uv run python -c "
-        from sentence_transformers import SentenceTransformer, CrossEncoder
-        print('Downloading embedding model...')
-        SentenceTransformer('BAAI/bge-small-en-v1.5')
-        print('Downloading cross-encoder model...')
-        CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2')
-        print('Models downloaded successfully')
-        "
-
    - name: Create .env file
      run: |
        cat > .env << EOF
        HINDSIGHT_API_LLM_PROVIDER=${{ env.HINDSIGHT_API_LLM_PROVIDER }}
+        HINDSIGHT_API_LLM_API_KEY=${{ env.HINDSIGHT_API_LLM_API_KEY }}
        HINDSIGHT_API_LLM_MODEL=${{ env.HINDSIGHT_API_LLM_MODEL }}
-        HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY=/tmp/gcp-credentials.json
-        HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID
        EOF

    - name: Start API server
      run: |
        ./scripts/dev/start-api.sh > /tmp/api-server.log 2>&1 &
        echo "Waiting for API server to be ready..."
-        for i in {1..120}; do
+        for i in {1..60}; do
          if curl -sf http://localhost:8888/health > /dev/null 2>&1; then
            echo "API server is ready after ${i}s"
            break
          fi
-          if [ $i -eq 120 ]; then
-            echo "API server failed to start after 120s"
+          if [ $i -eq 60 ]; then
+            echo "API server failed to start after 60s"
            cat /tmp/api-server.log
            exit 1
          fi
@@ -686,36 +568,12 @@ jobs:
        echo "=== API Server Logs ==="
        cat /tmp/api-server.log || echo "No API server log found"

-  build-rust-cli-arm64:
-    runs-on: ubuntu-24.04-arm
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Install Rust
-      uses: dtolnay/rust-toolchain@stable
-      with:
-        targets: aarch64-unknown-linux-gnu
-
-    - name: Cache cargo
-      uses: actions/cache@v4
-      with:
-        path: |
-          ~/.cargo/registry
-          ~/.cargo/git
-          hindsight-cli/target
-        key: linux-arm64-cargo-${{ hashFiles('**/Cargo.lock') }}
-
-    - name: Build CLI
-      working-directory: hindsight-cli
-      run: cargo build --release --target aarch64-unknown-linux-gnu
-
  test-rust-client:
    runs-on: ubuntu-latest
    env:
-      HINDSIGHT_API_LLM_PROVIDER: vertexai
-      HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY: /tmp/gcp-credentials.json
-      HINDSIGHT_API_LLM_MODEL: google/gemini-2.5-flash-lite
+      HINDSIGHT_API_LLM_PROVIDER: groq
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
      HINDSIGHT_API_URL: http://localhost:8888
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      # Prefer CPU-only PyTorch in CI (but keep PyPI for everything else)
@@ -724,12 +582,6 @@ jobs:
    steps:
    - uses: actions/checkout@v4

-    - name: Setup GCP credentials
-      run: |
-        printf '%s' '${{ secrets.GCP_VERTEXAI_CREDENTIALS }}' > /tmp/gcp-credentials.json
-        PROJECT_ID=$(jq -r '.project_id' /tmp/gcp-credentials.json)
-        echo "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$PROJECT_ID" >> $GITHUB_ENV
-
    - name: Install uv
      uses: astral-sh/setup-uv@v5
      with:
@@ -761,46 +613,25 @@ jobs:
      working-directory: ./hindsight-api
      run: uv sync --frozen --no-install-project --index-strategy unsafe-best-match

-    - name: Cache HuggingFace models
-      uses: actions/cache@v4
-      with:
-        path: ~/.cache/huggingface
-        key: ${{ runner.os }}-huggingface-${{ hashFiles('hindsight-api/pyproject.toml') }}
-        restore-keys: |
-          ${{ runner.os }}-huggingface-
-
-    - name: Pre-download models
-      working-directory: ./hindsight-api
-      run: |
-        uv run python -c "
-        from sentence_transformers import SentenceTransformer, CrossEncoder
-        print('Downloading embedding model...')
-        SentenceTransformer('BAAI/bge-small-en-v1.5')
-        print('Downloading cross-encoder model...')
-        CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2')
-        print('Models downloaded successfully')
-        "
-
    - name: Create .env file
      run: |
        cat > .env << EOF
        HINDSIGHT_API_LLM_PROVIDER=${{ env.HINDSIGHT_API_LLM_PROVIDER }}
+        HINDSIGHT_API_LLM_API_KEY=${{ env.HINDSIGHT_API_LLM_API_KEY }}
        HINDSIGHT_API_LLM_MODEL=${{ env.HINDSIGHT_API_LLM_MODEL }}
-        HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY=/tmp/gcp-credentials.json
-        HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID
        EOF

    - name: Start API server
      run: |
        ./scripts/dev/start-api.sh > /tmp/api-server.log 2>&1 &
        echo "Waiting for API server to be ready..."
-        for i in {1..120}; do
+        for i in {1..60}; do
          if curl -sf http://localhost:8888/health > /dev/null 2>&1; then
            echo "API server is ready after ${i}s"
            break
          fi
-          if [ $i -eq 120 ]; then
-            echo "API server failed to start after 120s"
+          if [ $i -eq 60 ]; then
+            echo "API server failed to start after 60s"
            cat /tmp/api-server.log
            exit 1
          fi
@@ -817,225 +648,12 @@ jobs:
        echo "=== API Server Logs ==="
        cat /tmp/api-server.log || echo "No API server log found"

-  test-go-client:
-    runs-on: ubuntu-latest
-    env:
-      HINDSIGHT_API_LLM_PROVIDER: vertexai
-      HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY: /tmp/gcp-credentials.json
-      HINDSIGHT_API_LLM_MODEL: google/gemini-2.5-flash-lite
-      HINDSIGHT_API_URL: http://localhost:8888
-      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      # Prefer CPU-only PyTorch in CI (but keep PyPI for everything else)
-      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Setup GCP credentials
-      run: |
-        printf '%s' '${{ secrets.GCP_VERTEXAI_CREDENTIALS }}' > /tmp/gcp-credentials.json
-        PROJECT_ID=$(jq -r '.project_id' /tmp/gcp-credentials.json)
-        echo "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$PROJECT_ID" >> $GITHUB_ENV
-
-    - name: Install uv
-      uses: astral-sh/setup-uv@v5
-      with:
-        enable-cache: true
-        prune-cache: false
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version-file: ".python-version"
-
-    - name: Set up Go
-      uses: actions/setup-go@v5
-      with:
-        go-version: '1.23'
-        cache-dependency-path: hindsight-clients/go/go.sum
-
-    - name: Build API
-      working-directory: ./hindsight-api
-      run: uv build
-
-    - name: Install API dependencies
-      working-directory: ./hindsight-api
-      run: uv sync --frozen --no-install-project --index-strategy unsafe-best-match
-
-    - name: Cache HuggingFace models
-      uses: actions/cache@v4
-      with:
-        path: ~/.cache/huggingface
-        key: ${{ runner.os }}-huggingface-${{ hashFiles('hindsight-api/pyproject.toml') }}
-        restore-keys: |
-          ${{ runner.os }}-huggingface-
-
-    - name: Pre-download models
-      working-directory: ./hindsight-api
-      run: |
-        uv run python -c "
-        from sentence_transformers import SentenceTransformer, CrossEncoder
-        print('Downloading embedding model...')
-        SentenceTransformer('BAAI/bge-small-en-v1.5')
-        print('Downloading cross-encoder model...')
-        CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2')
-        print('Models downloaded successfully')
-        "
-
-    - name: Create .env file
-      run: |
-        cat > .env << EOF
-        HINDSIGHT_API_LLM_PROVIDER=${{ env.HINDSIGHT_API_LLM_PROVIDER }}
-        HINDSIGHT_API_LLM_MODEL=${{ env.HINDSIGHT_API_LLM_MODEL }}
-        HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY=/tmp/gcp-credentials.json
-        HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID
-        EOF
-
-    - name: Start API server
-      run: |
-        ./scripts/dev/start-api.sh > /tmp/api-server.log 2>&1 &
-        echo "Waiting for API server to be ready..."
-        for i in {1..120}; do
-          if curl -sf http://localhost:8888/health > /dev/null 2>&1; then
-            echo "API server is ready after ${i}s"
-            break
-          fi
-          if [ $i -eq 120 ]; then
-            echo "API server failed to start after 120s"
-            cat /tmp/api-server.log
-            exit 1
-          fi
-          sleep 1
-        done
-
-    - name: Build Go client
-      working-directory: ./hindsight-clients/go
-      run: go build ./...
-
-    - name: Run Go client tests
-      working-directory: ./hindsight-clients/go
-      run: go test -v -tags=integration
-
-    - name: Show API server logs
-      if: always()
-      run: |
-        echo "=== API Server Logs ==="
-        cat /tmp/api-server.log || echo "No API server log found"
-
-  test-openclaw-integration:
-    runs-on: ubuntu-latest
-    env:
-      HINDSIGHT_API_LLM_PROVIDER: vertexai
-      HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY: /tmp/gcp-credentials.json
-      HINDSIGHT_API_LLM_MODEL: google/gemini-2.5-flash-lite
-      HINDSIGHT_API_URL: http://localhost:8888
-      HINDSIGHT_EMBED_PACKAGE_PATH: ${{ github.workspace }}/hindsight-embed
-      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Setup GCP credentials
-      run: |
-        printf '%s' '${{ secrets.GCP_VERTEXAI_CREDENTIALS }}' > /tmp/gcp-credentials.json
-        PROJECT_ID=$(jq -r '.project_id' /tmp/gcp-credentials.json)
-        echo "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$PROJECT_ID" >> $GITHUB_ENV
-
-    - name: Install uv
-      uses: astral-sh/setup-uv@v5
-      with:
-        enable-cache: true
-        prune-cache: false
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version-file: ".python-version"
-
-    - name: Set up Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version: '22'
-
-    - name: Build API
-      working-directory: ./hindsight-api
-      run: uv build
-
-    - name: Install API dependencies
-      working-directory: ./hindsight-api
-      run: uv sync --frozen --no-install-project --index-strategy unsafe-best-match
-
-    - name: Install embed dependencies
-      working-directory: ./hindsight-embed
-      run: uv sync --frozen --index-strategy unsafe-best-match
-
-    - name: Cache HuggingFace models
-      uses: actions/cache@v4
-      with:
-        path: ~/.cache/huggingface
-        key: ${{ runner.os }}-huggingface-${{ hashFiles('hindsight-api/pyproject.toml') }}
-        restore-keys: |
-          ${{ runner.os }}-huggingface-
-
-    - name: Pre-download models
-      working-directory: ./hindsight-api
-      run: |
-        uv run python -c "
-        from sentence_transformers import SentenceTransformer, CrossEncoder
-        print('Downloading embedding model...')
-        SentenceTransformer('BAAI/bge-small-en-v1.5')
-        print('Downloading cross-encoder model...')
-        CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2')
-        print('Models downloaded successfully')
-        "
-
-    - name: Install openclaw integration dependencies
-      working-directory: ./hindsight-integrations/openclaw
-      run: npm ci
-
-    - name: Create .env file
-      run: |
-        cat > .env << EOF
-        HINDSIGHT_API_LLM_PROVIDER=${{ env.HINDSIGHT_API_LLM_PROVIDER }}
-        HINDSIGHT_API_LLM_MODEL=${{ env.HINDSIGHT_API_LLM_MODEL }}
-        HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY=/tmp/gcp-credentials.json
-        HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID
-        EOF
-
-    - name: Start API server
-      run: |
-        ./scripts/dev/start-api.sh > /tmp/api-server.log 2>&1 &
-        echo "Waiting for API server to be ready..."
-        for i in {1..120}; do
-          if curl -sf http://localhost:8888/health > /dev/null 2>&1; then
-            echo "API server is ready after ${i}s"
-            break
-          fi
-          if [ $i -eq 120 ]; then
-            echo "API server failed to start after 120s"
-            cat /tmp/api-server.log
-            exit 1
-          fi
-          sleep 1
-        done
-
-    - name: Run openclaw integration tests
-      working-directory: ./hindsight-integrations/openclaw
-      run: npm run test:integration
-
-    - name: Show API server logs
-      if: always()
-      run: |
-        echo "=== API Server Logs ==="
-        cat /tmp/api-server.log || echo "No API server log found"
-
  test-integration:
    runs-on: ubuntu-latest
    env:
-      HINDSIGHT_API_LLM_PROVIDER: vertexai
-      HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY: /tmp/gcp-credentials.json
-      HINDSIGHT_API_LLM_MODEL: google/gemini-2.5-flash-lite
+      HINDSIGHT_API_LLM_PROVIDER: groq
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
      HINDSIGHT_API_URL: http://localhost:8888
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu
@@ -1043,12 +661,6 @@ jobs:
    steps:
    - uses: actions/checkout@v4

-    - name: Setup GCP credentials
-      run: |
-        printf '%s' '${{ secrets.GCP_VERTEXAI_CREDENTIALS }}' > /tmp/gcp-credentials.json
-        PROJECT_ID=$(jq -r '.project_id' /tmp/gcp-credentials.json)
-        echo "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$PROJECT_ID" >> $GITHUB_ENV
-
    - name: Install uv
      uses: astral-sh/setup-uv@v5
      with:
@@ -1096,22 +708,21 @@ jobs:
      run: |
        cat > .env << EOF
        HINDSIGHT_API_LLM_PROVIDER=${{ env.HINDSIGHT_API_LLM_PROVIDER }}
+        HINDSIGHT_API_LLM_API_KEY=${{ env.HINDSIGHT_API_LLM_API_KEY }}
        HINDSIGHT_API_LLM_MODEL=${{ env.HINDSIGHT_API_LLM_MODEL }}
-        HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY=/tmp/gcp-credentials.json
-        HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID
        EOF

    - name: Start API server
      run: |
        ./scripts/dev/start-api.sh > /tmp/api-server.log 2>&1 &
        echo "Waiting for API server to be ready..."
-        for i in {1..120}; do
+        for i in {1..60}; do
          if curl -sf http://localhost:8888/health > /dev/null 2>&1; then
            echo "API server is ready after ${i}s"
            break
          fi
-          if [ $i -eq 120 ]; then
-            echo "API server failed to start after 120s"
+          if [ $i -eq 60 ]; then
+            echo "API server failed to start after 60s"
            cat /tmp/api-server.log
            exit 1
          fi
@@ -1128,35 +739,6 @@ jobs:
        echo "=== API Server Logs ==="
        cat /tmp/api-server.log || echo "No API server log found"

-  test-crewai-integration:
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Install uv
-      uses: astral-sh/setup-uv@v5
-      with:
-        enable-cache: true
-        prune-cache: false
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version-file: ".python-version"
-
-    - name: Build crewai integration
-      working-directory: ./hindsight-integrations/crewai
-      run: uv build
-
-    - name: Install dependencies
-      working-directory: ./hindsight-integrations/crewai
-      run: uv sync --frozen
-
-    - name: Run tests
-      working-directory: ./hindsight-integrations/crewai
-      run: uv run pytest tests -v
-
  test-litellm-integration:
    runs-on: ubuntu-latest

@@ -1186,53 +768,18 @@ jobs:
      working-directory: ./hindsight-integrations/litellm
      run: uv run pytest tests -v

-  test-pydantic-ai-integration:
-    runs-on: ubuntu-latest
-
-    steps:
-    - uses: actions/checkout@v4
-
-    - name: Install uv
-      uses: astral-sh/setup-uv@v5
-      with:
-        enable-cache: true
-        prune-cache: false
-
-    - name: Set up Python
-      uses: actions/setup-python@v5
-      with:
-        python-version-file: ".python-version"
-
-    - name: Build pydantic-ai integration
-      working-directory: ./hindsight-integrations/pydantic-ai
-      run: uv build
-
-    - name: Install dependencies
-      working-directory: ./hindsight-integrations/pydantic-ai
-      run: uv sync --frozen
-
-    - name: Run tests
-      working-directory: ./hindsight-integrations/pydantic-ai
-      run: uv run pytest tests -v
-
  test-embed:
    runs-on: ubuntu-latest
    env:
-      HINDSIGHT_API_LLM_PROVIDER: vertexai
-      HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY: /tmp/gcp-credentials.json
-      HINDSIGHT_API_LLM_MODEL: google/gemini-2.5-flash-lite
+      HINDSIGHT_API_LLM_PROVIDER: groq
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
      # Prefer CPU-only PyTorch in CI
      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu

    steps:
    - uses: actions/checkout@v4

-    - name: Setup GCP credentials
-      run: |
-        printf '%s' '${{ secrets.GCP_VERTEXAI_CREDENTIALS }}' > /tmp/gcp-credentials.json
-        PROJECT_ID=$(jq -r '.project_id' /tmp/gcp-credentials.json)
-        echo "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$PROJECT_ID" >> $GITHUB_ENV
-
    - name: Install uv
      uses: astral-sh/setup-uv@v5
      with:
@@ -1268,25 +815,19 @@ jobs:
  test-hindsight-all:
    runs-on: ubuntu-latest
    env:
-      HINDSIGHT_API_LLM_PROVIDER: vertexai
-      HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY: /tmp/gcp-credentials.json
-      HINDSIGHT_API_LLM_MODEL: google/gemini-2.5-flash-lite
+      HINDSIGHT_API_LLM_PROVIDER: groq
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
      # For test_server_integration.py compatibility
-      HINDSIGHT_LLM_PROVIDER: vertexai
-      HINDSIGHT_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY: /tmp/gcp-credentials.json
-      HINDSIGHT_LLM_MODEL: google/gemini-2.5-flash-lite
+      HINDSIGHT_LLM_PROVIDER: groq
+      HINDSIGHT_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
+      HINDSIGHT_LLM_MODEL: openai/gpt-oss-20b
      # Prefer CPU-only PyTorch in CI
      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu

    steps:
    - uses: actions/checkout@v4

-    - name: Setup GCP credentials
-      run: |
-        printf '%s' '${{ secrets.GCP_VERTEXAI_CREDENTIALS }}' > /tmp/gcp-credentials.json
-        PROJECT_ID=$(jq -r '.project_id' /tmp/gcp-credentials.json)
-        echo "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$PROJECT_ID" >> $GITHUB_ENV
-
    - name: Install uv
      uses: astral-sh/setup-uv@v5
      with:
@@ -1321,15 +862,11 @@ jobs:

  test-doc-examples:
    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        language: [python, node, cli, go]
-    name: test-doc-examples (${{ matrix.language }})
+    needs: test-rust-cli
    env:
-      HINDSIGHT_API_LLM_PROVIDER: vertexai
-      HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY: /tmp/gcp-credentials.json
-      HINDSIGHT_API_LLM_MODEL: google/gemini-2.5-flash-lite
+      HINDSIGHT_API_LLM_PROVIDER: groq
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
      HINDSIGHT_API_URL: http://localhost:8888
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu
@@ -1337,32 +874,14 @@ jobs:
    steps:
    - uses: actions/checkout@v4

-    - name: Setup GCP credentials
-      run: |
-        printf '%s' '${{ secrets.GCP_VERTEXAI_CREDENTIALS }}' > /tmp/gcp-credentials.json
-        PROJECT_ID=$(jq -r '.project_id' /tmp/gcp-credentials.json)
-        echo "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$PROJECT_ID" >> $GITHUB_ENV
-
-    - name: Install Rust
-      if: matrix.language == 'cli'
-      uses: dtolnay/rust-toolchain@stable
-
-    - name: Cache cargo
-      if: matrix.language == 'cli'
-      uses: actions/cache@v4
+    - name: Download CLI artifact
+      uses: actions/download-artifact@v4
      with:
-        path: |
-          ~/.cargo/registry
-          ~/.cargo/git
-          hindsight-cli/target
-        key: ${{ runner.os }}-cargo-${{ hashFiles('**/Cargo.lock') }}
+        name: hindsight-cli
+        path: /usr/local/bin

-    - name: Build CLI
-      if: matrix.language == 'cli'
-      working-directory: hindsight-cli
-      run: |
-        cargo build --release
-        cp target/release/hindsight /usr/local/bin/hindsight
+    - name: Make CLI executable
+      run: chmod +x /usr/local/bin/hindsight

    - name: Install uv
      uses: astral-sh/setup-uv@v5
@@ -1376,7 +895,6 @@ jobs:
        python-version-file: ".python-version"

    - name: Set up Node.js
-      if: matrix.language == 'node'
      uses: actions/setup-node@v4
      with:
        node-version: '20'
@@ -1390,68 +908,63 @@ jobs:
        uv sync --frozen --no-install-project --index-strategy unsafe-best-match

    - name: Install Python client dependencies
-      if: matrix.language == 'python'
      working-directory: ./hindsight-clients/python
      run: uv sync --frozen --extra test --index-strategy unsafe-best-match

    - name: Install TypeScript client
-      if: matrix.language == 'node'
      run: |
        npm ci --workspace=hindsight-clients/typescript
        npm run build --workspace=hindsight-clients/typescript

-    - name: Cache HuggingFace models
-      uses: actions/cache@v4
-      with:
-        path: ~/.cache/huggingface
-        key: ${{ runner.os }}-huggingface-${{ hashFiles('hindsight-api/pyproject.toml') }}
-        restore-keys: |
-          ${{ runner.os }}-huggingface-
-
-    - name: Pre-download models
-      working-directory: ./hindsight-api
-      run: |
-        uv run python -c "
-        from sentence_transformers import SentenceTransformer, CrossEncoder
-        print('Downloading embedding model...')
-        SentenceTransformer('BAAI/bge-small-en-v1.5')
-        print('Downloading reranker model...')
-        CrossEncoder('cross-encoder/ms-marco-MiniLM-L-6-v2')
-        print('Models downloaded successfully')
-        "
-
    - name: Create .env file
      run: |
        cat > .env << EOF
        HINDSIGHT_API_LLM_PROVIDER=${{ env.HINDSIGHT_API_LLM_PROVIDER }}
+        HINDSIGHT_API_LLM_API_KEY=${{ env.HINDSIGHT_API_LLM_API_KEY }}
        HINDSIGHT_API_LLM_MODEL=${{ env.HINDSIGHT_API_LLM_MODEL }}
-        HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY=/tmp/gcp-credentials.json
-        HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID
        EOF

    - name: Start API server
      run: |
        ./scripts/dev/start-api.sh > /tmp/api-server.log 2>&1 &
        echo "Waiting for API server to be ready..."
-        for i in {1..120}; do
+        for i in {1..60}; do
          if curl -sf http://localhost:8888/health > /dev/null 2>&1; then
            echo "API server is ready after ${i}s"
            break
          fi
-          if [ $i -eq 120 ]; then
-            echo "API server failed to start after 120s"
+          if [ $i -eq 60 ]; then
+            echo "API server failed to start after 60s"
            cat /tmp/api-server.log
            exit 1
          fi
          sleep 1
        done

+    - name: Run Python doc examples
+      working-directory: ./hindsight-clients/python
+      run: |
+        for f in ../../hindsight-docs/examples/api/*.py; do
+          echo "Running $f..."
+          uv run python "$f"
+        done
+
+    - name: Run Node.js doc examples
+      run: |
+        for f in hindsight-docs/examples/api/*.mjs; do
+          echo "Running $f..."
+          node "$f"
+        done
+
    - name: Configure CLI
-      if: matrix.language == 'cli'
      run: hindsight configure --api-url http://localhost:8888

-    - name: Run doc examples (${{ matrix.language }})
-      run: ./scripts/test-doc-examples.sh --lang ${{ matrix.language }}
+    - name: Run CLI doc examples
+      run: |
+        for f in hindsight-docs/examples/api/*.sh; do
+          echo "Running $f..."
+          bash "$f"
+        done

    - name: Show API server logs
      if: always()
@@ -1462,9 +975,9 @@ jobs:
  test-upgrade:
    runs-on: ubuntu-latest
    env:
-      HINDSIGHT_API_LLM_PROVIDER: vertexai
-      HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY: /tmp/gcp-credentials.json
-      HINDSIGHT_API_LLM_MODEL: google/gemini-2.5-flash-lite
+      HINDSIGHT_API_LLM_PROVIDER: groq
+      HINDSIGHT_API_LLM_API_KEY: ${{ secrets.GROQ_API_KEY }}
+      HINDSIGHT_API_LLM_MODEL: openai/gpt-oss-20b
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      UV_INDEX: pytorch=https://download.pytorch.org/whl/cpu

@@ -1473,12 +986,6 @@ jobs:
      with:
        fetch-depth: 0  # Full history needed for git clone of tags

-    - name: Setup GCP credentials
-      run: |
-        printf '%s' '${{ secrets.GCP_VERTEXAI_CREDENTIALS }}' > /tmp/gcp-credentials.json
-        PROJECT_ID=$(jq -r '.project_id' /tmp/gcp-credentials.json)
-        echo "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=$PROJECT_ID" >> $GITHUB_ENV
-
    - name: Fetch tags
      run: git fetch --tags

@@ -46,7 +46,6 @@ hindsight-docs/static/llms-full.txt
 hindsight-dev/benchmarks/locomo/results/
 hindsight-dev/benchmarks/longmemeval/results/
 hindsight-dev/benchmarks/consolidation/results/
-hindsight-dev/benchmarks/perf/results/
 benchmarks/results/
 hindsight-cli/target
 hindsight-clients/rust/target
@@ -57,15 +57,8 @@ cd hindsight-control-plane && npm run dev

 ### Benchmarks
 ```bash
-# Accuracy benchmarks
 ./scripts/benchmarks/run-longmemeval.sh
 ./scripts/benchmarks/run-locomo.sh
-
-# Performance benchmarks
-./scripts/benchmarks/run-consolidation.sh
-./scripts/benchmarks/run-retain-perf.sh --document <path>  # Requires API server running
-
-# Results viewer
 ./scripts/benchmarks/start-visualizer.sh  # View results at localhost:8001
 ```

@@ -317,10 +310,10 @@ npm install
 Required env vars:
 - `HINDSIGHT_API_LLM_PROVIDER`: openai, anthropic, gemini, groq, ollama, lmstudio
 - `HINDSIGHT_API_LLM_API_KEY`: Your API key
- `HINDSIGHT_API_LLM_MODEL`: Model name (e.g., gpt-4o-mini, claude-sonnet-4-20250514)
+- `HINDSIGHT_API_LLM_MODEL`: Model name (e.g., o3-mini, claude-sonnet-4-20250514)

 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: true)
+- `HINDSIGHT_API_ENABLE_BANK_CONFIG_API`: Enable per-bank config API (default: false, disabled for security)
@@ -36,7 +36,7 @@ Hindsight is being used in production at Fortune 500 enterprises and by a growin

 ## Adding Hindsight to Your AI Agents

-The easiest way to use Hindsight with an existing agent is with the LLM Wrapper. You can add memory to your agent with 2 lines of code. That will swap your current LLM client out with the Hindsight wrapper. After that, memories will be stored and retrieved automatically as you make LLM calls.
+The easiest way use Hindsight with an existing agent is with the LLM Wrapper. You can add memory to your agent with 2 lines of code. That will swap your current LLM client out with the Hindsight wrapper. After that, memories will be stored and retrieved automatically as you make LLM calls.

 If you need more control over how and when your agent stores and recalls memories, there's also a simple API you can integrate with using the SDKs or directly via HTTP.

@@ -181,7 +181,7 @@ Satisfying these requirements in Hindsight is straightforward. When new user inp

 ![Overview](./hindsight-docs/static/img/hindsight-overview.webp)

-Most agent memory implementations rely on basic vector search or sometimes use a knowledge graph. Hindsight uses biomimetic data structures to organize agent memories in a way that is more like how human memory works:
+Most agent memory implementation rely on basic vector search or sometimes use a knowledge graph. Hindsight uses biomimetic data structures to organize agent memories in a way that is more like how human memory works:

 - **World:** Facts about the world ("The stove gets hot")
 - **Experiences:** Agent's own experiences ("I touched the stove and it really hurt")
@@ -307,5 +307,3 @@ MIT — see [LICENSE](./LICENSE)
 ---

 Built by [Vectorize.io](https://vectorize.io)
-
-<img src="https://umami-pixel.chris-latimer.workers.dev/?id=a8b043e6-6964-454d-80df-69b69d3f0d50&host=github.com&url=/vectorize-io/hindsight" width="1" height="1" alt="" />
@@ -1,32 +0,0 @@
-# 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
@@ -1,91 +0,0 @@
-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:
@@ -1,83 +0,0 @@
-# Docker Compose file for Hindsight with S3 file storage (SeaweedFS)
-#
-# SeaweedFS (Apache 2.0) provides an S3-compatible object storage backend
-# for storing uploaded files instead of PostgreSQL BYTEA storage.
-#
-# 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)
-# - SEAWEEDFS_S3_ACCESS_KEY: S3 access key (default: hindsight_s3_key)
-# - SEAWEEDFS_S3_SECRET_KEY: S3 secret key (default: hindsight_s3_secret)
-
-services:
-  db:
-    image: pgvector/pgvector:pg${HINDSIGHT_DB_VERSION:-18}
-    container_name: hindsight-db
-    restart: always
-    environment:
-      POSTGRES_USER: ${HINDSIGHT_DB_USER:-hindsight_user}
-      POSTGRES_PASSWORD: ${HINDSIGHT_DB_PASSWORD:?Please set the HINDSIGHT_DB_PASSWORD env variable}
-      POSTGRES_DB: ${HINDSIGHT_DB_NAME:-hindsight_db}
-    volumes:
-      - pg_data:/var/lib/postgresql/${HINDSIGHT_DB_VERSION:-18}/docker
-    networks:
-      - hindsight-net
-
-  seaweedfs:
-    image: chrislusf/seaweedfs:latest
-    container_name: hindsight-seaweedfs
-    restart: always
-    # Single-node mode: master + volume + filer + S3 gateway all in one process
-    command: >
-      server
-      -s3
-      -s3.port=8333
-      -s3.config=/etc/seaweedfs/s3.json
-      -ip.bind=0.0.0.0
-    volumes:
-      - seaweedfs_data:/data
-      - ./s3.json:/etc/seaweedfs/s3.json:ro
-    # Expose S3 API port (uncomment to access from host)
-    # ports:
-    #   - "8333:8333"
-    networks:
-      - hindsight-net
-
-  hindsight:
-    image: ghcr.io/vectorize-io/hindsight:${HINDSIGHT_VERSION:-latest}
-    container_name: hindsight-app
-    ports:
-      - "8888:8888"
-      - "9999:9999"
-    environment:
-      - HINDSIGHT_API_LLM_API_KEY=${OPENAI_API_KEY?Please set the OPENAI_API_KEY env variable}
-      - HINDSIGHT_API_DATABASE_URL=postgresql://${HINDSIGHT_DB_USER:-hindsight_user}:${HINDSIGHT_DB_PASSWORD:?Please set the HINDSIGHT_DB_PASSWORD env variable}@db:5432/${HINDSIGHT_DB_NAME:-hindsight_db}
-      # S3 file storage configuration (SeaweedFS)
-      - HINDSIGHT_API_FILE_STORAGE_TYPE=s3
-      - HINDSIGHT_API_FILE_STORAGE_S3_BUCKET=hindsight
-      - HINDSIGHT_API_FILE_STORAGE_S3_ENDPOINT=http://seaweedfs:8333
-      - HINDSIGHT_API_FILE_STORAGE_S3_REGION=us-east-1
-      - HINDSIGHT_API_FILE_STORAGE_S3_ACCESS_KEY_ID=${SEAWEEDFS_S3_ACCESS_KEY:-hindsight_s3_key}
-      - HINDSIGHT_API_FILE_STORAGE_S3_SECRET_ACCESS_KEY=${SEAWEEDFS_S3_SECRET_KEY:-hindsight_s3_secret}
-    depends_on:
-      - db
-      - seaweedfs
-    networks:
-      - hindsight-net
-
-networks:
-  hindsight-net:
-    driver: bridge
-
-volumes:
-  pg_data:
-  seaweedfs_data:
@@ -1,19 +0,0 @@
-{
-  "identities": [
-    {
-      "name": "hindsight",
-      "credentials": [
-        {
-          "accessKey": "hindsight_s3_key",
-          "secretKey": "hindsight_s3_secret"
-        }
-      ],
-      "actions": [
-        "Admin",
-        "Read",
-        "Write",
-        "List"
-      ]
-    }
-  ]
-}
@@ -1,16 +0,0 @@
-# Git
-.git
-.gitignore
-.gitattributes
-
-# Docker
-docker-compose.yaml
-.dockerignore
-
-# Documentation
-README.md
-*.md
-
-# Environment
-.env
-.env.example
@@ -1,25 +0,0 @@
-# PostgreSQL Configuration
-HINDSIGHT_DB_USER=hindsight_user
-HINDSIGHT_DB_PASSWORD=change-me-to-secure-password
-HINDSIGHT_DB_NAME=hindsight_db
-
-# Hindsight Version
-HINDSIGHT_VERSION=latest
-
-# LLM Configuration
-HINDSIGHT_API_LLM_PROVIDER=openai
-OPENAI_API_KEY=your-openai-api-key-here
-
-# Alternative LLM providers (uncomment and configure as needed):
-# HINDSIGHT_API_LLM_PROVIDER=anthropic
-# ANTHROPIC_API_KEY=your-anthropic-api-key
-
-# HINDSIGHT_API_LLM_PROVIDER=gemini
-# GEMINI_API_KEY=your-gemini-api-key
-
-# HINDSIGHT_API_LLM_PROVIDER=groq
-# GROQ_API_KEY=your-groq-api-key
-
-# Vector and Text Search (already configured in docker-compose.yaml)
-# HINDSIGHT_API_VECTOR_EXTENSION=pgvectorscale
-# HINDSIGHT_API_TEXT_SEARCH_EXTENSION=pg_textsearch
@@ -1,55 +0,0 @@
-# PostgreSQL with pgvector, pgvectorscale, and pg_textsearch extensions
-# All three extensions from Timescale/pgvector for high-performance vector and text search
-# Note: Requires PostgreSQL 16+
-FROM postgres:17
-
-# Install build dependencies and Rust toolchain
-RUN apt-get update && apt-get install -y \
-    build-essential \
-    git \
-    postgresql-server-dev-17 \
-    libpq-dev \
-    cmake \
-    curl \
-    pkg-config \
-    libssl-dev \
-    && rm -rf /var/lib/apt/lists/*
-
-# Install Rust toolchain (required for pgvectorscale)
-RUN curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
-ENV PATH="/root/.cargo/bin:${PATH}"
-
-# Install pgvector (required by pgvectorscale)
-RUN cd /tmp && \
-    git clone --branch v0.8.0 https://github.com/pgvector/pgvector.git && \
-    cd pgvector && \
-    make && \
-    make install && \
-    rm -rf /tmp/pgvector
-
-# Install cargo-pgrx (PostgreSQL extension framework for Rust)
-RUN cargo install cargo-pgrx --version 0.12.5 --locked && \
-    cargo pgrx init --pg17 /usr/bin/pg_config
-
-# Install pgvectorscale (DiskANN index support)
-RUN cd /tmp && \
-    git clone --branch 0.5.1 https://github.com/timescale/pgvectorscale.git && \
-    cd pgvectorscale/pgvectorscale && \
-    cargo pgrx install --release && \
-    rm -rf /tmp/pgvectorscale
-
-# Install pg_textsearch (BM25 text search)
-RUN cd /tmp && \
-    git clone https://github.com/timescale/pg_textsearch.git && \
-    cd pg_textsearch && \
-    make && \
-    make install && \
-    rm -rf /tmp/pg_textsearch
-
-# Clean up build dependencies (keep runtime dependencies)
-RUN apt-get purge -y --auto-remove git cmake curl && \
-    rm -rf /root/.cargo/registry /root/.cargo/git
-
-# Ensure extensions are preloaded (pg_textsearch requires preloading)
-RUN echo "shared_preload_libraries = 'pg_textsearch'" >> /usr/share/postgresql/postgresql.conf.sample
-
@@ -1,101 +0,0 @@
-# Hindsight with Timescale Extensions
-
-This Docker Compose setup provides a complete Hindsight deployment with **Timescale extensions**:
- **pgvectorscale** - DiskANN algorithm for disk-based scalable vector search  
- **pg_textsearch** - High-performance BM25 text search
-
-Both extensions are from [Timescale](https://github.com/timescale) and provide production-grade performance.
-
-## Prerequisites
-
- Docker and Docker Compose installed
- OpenAI API key (or another LLM provider)
-
-## Quick Start
-
-```bash
-# Set environment variables
-export HINDSIGHT_DB_PASSWORD="your-secure-password"
-export OPENAI_API_KEY="your-openai-api-key"
-
-# Build and start
-docker compose -f docker/docker-compose/timescale/docker-compose.yaml up -d --build
-
-# Check logs
-
-docker compose -f docker/docker-compose/timescale/docker-compose.yaml logs -f
-```
-
-**Access:**
- API: http://localhost:8888
- Control Plane: http://localhost:9999
-
-## Stop and Clean Up
-
-```bash
-# Stop services
-docker compose -f docker/docker-compose/timescale/docker-compose.yaml down
-
-# Remove volumes (deletes all data)
-docker compose -f docker/docker-compose/timescale/docker-compose.yaml down -v
-```
-
-## Configuration
-
-### Environment Variables
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `HINDSIGHT_DB_PASSWORD` | PostgreSQL password | `hindsight_password` |
-| `HINDSIGHT_DB_USER` | PostgreSQL username | `hindsight_user` |
-| `HINDSIGHT_DB_NAME` | Database name | `hindsight_db` |
-| `HINDSIGHT_VERSION` | Hindsight Docker image version | `latest` |
-| `OPENAI_API_KEY` | OpenAI API key | (required) |
-| `HINDSIGHT_API_LLM_PROVIDER` | LLM provider | `openai` |
-
-### Why Timescale Extensions?
-
-**pgvectorscale (DiskANN):**
- 28x lower p95 latency vs dedicated vector databases
- 16x higher query throughput at 99% recall
- 60-75% cost reduction (disk is cheaper than RAM)
- Best for large datasets (10M+ vectors)
-
-**pg_textsearch (BM25):**
- High-performance keyword retrieval
- Native BM25 ranking algorithm
- Optimized for full-text search
-
-## Troubleshooting
-
-### Extensions not installed
-
-Check if extensions are available:
-
-```bash
-docker exec -it hindsight-db-timescale psql -U hindsight_user -d hindsight_db -c "\dx"
-```
-
-You should see:
- `vector` (pgvector)
- `vectorscale` (pgvectorscale/DiskANN)
- `pg_textsearch` (BM25 search)
-
-### Build fails
-
-If the Docker build fails during pgvectorscale compilation:
-
-1. Ensure you have sufficient memory (recommended: 4GB+)
-2. Check Docker build logs for Rust compilation errors
-3. Try building with more resources: `docker compose build --no-cache --memory 4g`
-
-### Port conflicts
-
-If port 5438 is already in use, modify the `ports` section in docker-compose.yaml.
-
-## Learn More
-
- [pgvectorscale GitHub](https://github.com/timescale/pgvectorscale)
- [pg_textsearch GitHub](https://github.com/timescale/pg_textsearch)
- [HNSW vs DiskANN](https://www.tigerdata.com/learn/hnsw-vs-diskann)
- [Hindsight Documentation](https://hindsight.dev)
@@ -1,108 +0,0 @@
-name: hindsight
-# Docker Compose file for Hindsight with Timescale extensions
-# - pgvectorscale: DiskANN vector search (disk-based, scalable)
-# - pg_textsearch: BM25 text search (high-performance keyword retrieval)
-#
-# Quick start:
-# docker compose -f docker/docker-compose/timescale/docker-compose.yaml up -d --build
-#
-# Required environment variables:
-# - HINDSIGHT_DB_PASSWORD: Password for the PostgreSQL user
-# - OPENAI_API_KEY (or configure another LLM provider)
-#
-# Optional environment variables with defaults:
-# - HINDSIGHT_VERSION: Hindsight application version (default: latest)
-# - HINDSIGHT_DB_USER: PostgreSQL user (default: hindsight_user)
-# - HINDSIGHT_DB_NAME: PostgreSQL database name (default: hindsight_db)
-
-services:
-  db:
-    # Custom PostgreSQL image with Timescale extensions (pgvectorscale + pg_textsearch)
-    build:
-      context: .
-      dockerfile: Dockerfile
-    container_name: hindsight-db-timescale
-    restart: always
-    # Expose PostgreSQL port (using 5438 to avoid conflicts with other setups)
-    ports:
-      - "5438:5432"
-    environment:
-      POSTGRES_USER: ${HINDSIGHT_DB_USER:-hindsight_user}
-      POSTGRES_PASSWORD: ${HINDSIGHT_DB_PASSWORD:-hindsight_password}
-      POSTGRES_DB: ${HINDSIGHT_DB_NAME:-hindsight_db}
-    volumes:
-      - pg_data:/var/lib/postgresql/data
-    networks:
-      - hindsight-net
-    # Health check to ensure database is ready
-    healthcheck:
-      test: ["CMD-SHELL", "pg_isready -U hindsight_user"]
-      interval: 5s
-      timeout: 5s
-      retries: 5
-
-  timescale-init:
-    build:
-      context: .
-      dockerfile: Dockerfile
-    depends_on:
-      db:
-        condition: service_healthy
-    environment:
-      - PGPASSWORD=${HINDSIGHT_DB_PASSWORD:-hindsight_password}
-    command: >
-      bash -c "
-        echo 'PostgreSQL is ready - creating hindsight_db database';
-        psql -h hindsight-db-timescale -p 5432 -U hindsight_user -c 'CREATE DATABASE hindsight_db;' 2>/dev/null || echo 'Database already exists';
-        echo 'Installing Timescale extensions...';
-        echo '1/3: Installing pgvector (required by pgvectorscale)...';
-        psql -h hindsight-db-timescale -p 5432 -U hindsight_user -d hindsight_db -c 'CREATE EXTENSION IF NOT EXISTS vector CASCADE;';
-        echo '2/3: Installing pgvectorscale (DiskANN vector search)...';
-        psql -h hindsight-db-timescale -p 5432 -U hindsight_user -d hindsight_db -c 'CREATE EXTENSION IF NOT EXISTS vectorscale CASCADE;';
-        echo '3/3: Installing pg_textsearch (BM25 text search)...';
-        psql -h hindsight-db-timescale -p 5432 -U hindsight_user -d hindsight_db -c 'CREATE EXTENSION IF NOT EXISTS pg_textsearch CASCADE;';
-        echo '';
-        echo '✅ Timescale extensions installed successfully';
-        echo '';
-        echo 'Installed extensions:';
-        psql -h hindsight-db-timescale -p 5432 -U hindsight_user -d hindsight_db -c \"\\dx\" | grep -E '(vector|vectorscale|pg_textsearch)';
-      "
-    restart: "no"
-    networks:
-      - hindsight-net
-
-  hindsight:
-    image: ghcr.io/vectorize-io/hindsight:${HINDSIGHT_VERSION:-latest}
-    container_name: hindsight-app-timescale
-    ports:
-      - "8888:8888"
-      - "9999:9999"
-    environment:
-      # LLM Configuration
-      HINDSIGHT_API_LLM_PROVIDER: ${HINDSIGHT_API_LLM_PROVIDER:-openai}
-      HINDSIGHT_API_LLM_API_KEY: ${OPENAI_API_KEY:-your-api-key}
-
-      # Database Configuration
-      HINDSIGHT_API_DATABASE_URL: postgresql://${HINDSIGHT_DB_USER:-hindsight_user}:${HINDSIGHT_DB_PASSWORD:-hindsight_password}@db:5432/${HINDSIGHT_DB_NAME:-hindsight_db}
-
-      # Timescale Extensions
-      # pgvectorscale: DiskANN algorithm for disk-based scalable vector search
-      HINDSIGHT_API_VECTOR_EXTENSION: pgvectorscale
-      # pg_textsearch: High-performance BM25 text search
-      HINDSIGHT_API_TEXT_SEARCH_EXTENSION: pg_textsearch
-
-    depends_on:
-      db:
-        condition: service_healthy
-      timescale-init:
-        condition: service_completed_successfully
-    networks:
-      - hindsight-net
-
-
-networks:
-  hindsight-net:
-    driver: bridge
-
-volumes:
-  pg_data:
@@ -170,11 +170,6 @@ RUN chown -R hindsight:hindsight /app

 USER hindsight

-# Create pg0 data directory as hindsight user so that Docker seeds new named
-# volumes with correct ownership (UID 1000) on first use, avoiding the
-# "Permission denied" error when mounting a fresh root-owned volume.
-RUN mkdir -p /home/hindsight/.pg0
-
 ENV PATH="/app/api/.venv/bin:${PATH}"

 # Pre-download tiktoken encoding (ALWAYS - required for token counting even in air-gapped envs)
@@ -326,11 +321,6 @@ RUN chown -R hindsight:hindsight /app

 USER hindsight

-# Create pg0 data directory as hindsight user so that Docker seeds new named
-# volumes with correct ownership (UID 1000) on first use, avoiding the
-# "Permission denied" error when mounting a fresh root-owned volume.
-RUN mkdir -p /home/hindsight/.pg0
-
 ENV PATH="/app/api/.venv/bin:${PATH}"

 # Pre-download tiktoken encoding (ALWAYS - required for token counting even in air-gapped envs)
@@ -97,7 +97,7 @@ fi
 if [ "$ENABLE_CP" = "true" ]; then
    echo "🎛️  Starting Control Plane..."
    cd /app/control-plane
-    PORT="${HINDSIGHT_CP_PORT:-9999}" node server.js &
+    PORT=9999 node server.js &
    CP_PID=$!
    PIDS+=($CP_PID)
 else
@@ -110,7 +110,7 @@ echo "✅ Hindsight is running!"
 echo ""
 echo "📍 Access:"
 if [ "$ENABLE_CP" = "true" ]; then
-    echo "   Control Plane: http://localhost:${HINDSIGHT_CP_PORT:-9999}"
+    echo "   Control Plane: http://localhost:9999"
 fi
 if [ "$ENABLE_API" = "true" ]; then
    echo "   API:           http://localhost:8888"
@@ -13,9 +13,9 @@
 #   target  - Optional: 'cp-only' for control plane, otherwise assumes API image (default: api)
 #
 # Environment variables:
-#   HINDSIGHT_API_LLM_API_KEY                   - Required for API/standalone images (LLM verification)
-#   HINDSIGHT_API_LLM_PROVIDER                  - LLM provider (default: openai)
-#   HINDSIGHT_API_LLM_MODEL                     - LLM model (default: gpt-4o-mini)
+#   GROQ_API_KEY                                - Required for API/standalone images (LLM verification)
+#   HINDSIGHT_API_LLM_PROVIDER                  - LLM provider (default: groq)
+#   HINDSIGHT_API_LLM_MODEL                     - LLM model (default: llama-3.3-70b-versatile)
 #   HINDSIGHT_API_EMBEDDINGS_PROVIDER           - Embeddings provider (optional, for slim images: openai, cohere, tei)
 #   HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY     - OpenAI API key for embeddings (optional)
 #   HINDSIGHT_API_RERANKER_PROVIDER             - Reranker provider (optional, for slim images: cohere, tei)
@@ -34,7 +34,7 @@
 #   ./docker/test-image.sh hindsight-control-plane:test cp-only
 #
 #   # Test slim image with external providers
-#   export HINDSIGHT_API_LLM_API_KEY=sk_xxx
+#   export GROQ_API_KEY=gsk_xxx
 #   export HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai
 #   export HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY=sk-xxx
 #   export HINDSIGHT_API_RERANKER_PROVIDER=cohere
@@ -60,8 +60,8 @@ IMAGE="${1:-}"
 TARGET="${2:-api}"
 TIMEOUT="${SMOKE_TEST_TIMEOUT:-120}"
 CONTAINER_NAME="${SMOKE_TEST_CONTAINER_NAME:-hindsight-smoke-test}"
-LLM_PROVIDER="${HINDSIGHT_API_LLM_PROVIDER:-openai}"
-LLM_MODEL="${HINDSIGHT_API_LLM_MODEL:-gpt-4o-mini}"
+LLM_PROVIDER="${HINDSIGHT_API_LLM_PROVIDER:-groq}"
+LLM_MODEL="${HINDSIGHT_API_LLM_MODEL:-llama-3.3-70b-versatile}"

 # Validate arguments
 if [ -z "$IMAGE" ]; then
@@ -88,9 +88,9 @@ else
 fi

 # Check for required environment variables
-if [ "$NEEDS_LLM" = true ] && [ "$LLM_PROVIDER" != "vertexai" ] && [ -z "${HINDSIGHT_API_LLM_API_KEY:-}" ]; then
-    echo -e "${RED}Error: HINDSIGHT_API_LLM_API_KEY environment variable is required for API/standalone images${NC}"
-    echo "Set it with: export HINDSIGHT_API_LLM_API_KEY=your-api-key"
+if [ "$NEEDS_LLM" = true ] && [ -z "${GROQ_API_KEY:-}" ]; then
+    echo -e "${RED}Error: GROQ_API_KEY environment variable is required for API/standalone images${NC}"
+    echo "Set it with: export GROQ_API_KEY=your-api-key"
    exit 2
 fi

@@ -123,25 +123,9 @@ else
    # Build docker run command with required and optional env vars
    DOCKER_CMD="docker run -d --name $CONTAINER_NAME"
    DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_LLM_PROVIDER=$LLM_PROVIDER"
-    if [ -n "${HINDSIGHT_API_LLM_API_KEY:-}" ]; then
-        DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_LLM_API_KEY=${HINDSIGHT_API_LLM_API_KEY}"
-    fi
+    DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_LLM_API_KEY=${GROQ_API_KEY}"
    DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_LLM_MODEL=$LLM_MODEL"

-    # Add Vertex AI config if provider is vertexai
-    if [ "$LLM_PROVIDER" = "vertexai" ]; then
-        if [ -n "${HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY:-}" ]; then
-            DOCKER_CMD="$DOCKER_CMD -v ${HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY}:/tmp/gcp-credentials.json:ro"
-            DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY=/tmp/gcp-credentials.json"
-        fi
-        if [ -n "${HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID:-}" ]; then
-            DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID=${HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID}"
-        fi
-        if [ -n "${HINDSIGHT_API_LLM_VERTEXAI_REGION:-}" ]; then
-            DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_LLM_VERTEXAI_REGION=${HINDSIGHT_API_LLM_VERTEXAI_REGION}"
-        fi
-    fi
-
    # Add optional embeddings provider config
    if [ -n "${HINDSIGHT_API_EMBEDDINGS_PROVIDER:-}" ]; then
        DOCKER_CMD="$DOCKER_CMD -e HINDSIGHT_API_EMBEDDINGS_PROVIDER=${HINDSIGHT_API_EMBEDDINGS_PROVIDER}"
@@ -6,17 +6,24 @@
 # It expects API keys to be set in environment variables.
 #
 # Usage:
+#   export GROQ_API_KEY=gsk_xxx
 #   export OPENAI_API_KEY=sk-xxx
 #   export COHERE_API_KEY=xxx
 #   ./docker/test-slim-local.sh
 #
 # Or inline:
-#   OPENAI_API_KEY=sk_xxx COHERE_API_KEY=xxx ./docker/test-slim-local.sh
+#   GROQ_API_KEY=gsk_xxx OPENAI_API_KEY=sk_xxx COHERE_API_KEY=xxx ./docker/test-slim-local.sh
 #

 set -euo pipefail

 # Check for required API keys
+if [ -z "${GROQ_API_KEY:-}" ]; then
+    echo "❌ Error: GROQ_API_KEY environment variable is required"
+    echo "Set it with: export GROQ_API_KEY=gsk_xxx"
+    exit 1
+fi
+
 if [ -z "${OPENAI_API_KEY:-}" ]; then
    echo "❌ Error: OPENAI_API_KEY environment variable is required"
    echo "Set it with: export OPENAI_API_KEY=sk-xxx"
@@ -34,10 +41,7 @@ IMAGE="${1:-hindsight-slim:test}"
 echo "Testing image: $IMAGE"
 echo ""

-# Set up LLM and external providers
-export HINDSIGHT_API_LLM_PROVIDER=openai
-export HINDSIGHT_API_LLM_API_KEY=$OPENAI_API_KEY
-export HINDSIGHT_API_LLM_MODEL=gpt-4o-mini
+# Set up external providers
 export HINDSIGHT_API_EMBEDDINGS_PROVIDER=openai
 export HINDSIGHT_API_EMBEDDINGS_OPENAI_API_KEY=$OPENAI_API_KEY
 export HINDSIGHT_API_RERANKER_PROVIDER=cohere
@@ -2,8 +2,8 @@ apiVersion: v2
 name: hindsight
 description: Hindsight helm chart
 type: application
-version: 0.4.16
-appVersion: "0.4.16"
+version: 0.4.10
+appVersion: "0.4.10"
 keywords:
  - ai
  - memory
@@ -46,4 +46,4 @@ __all__ = [
    "RemoteTEICrossEncoder",
    "LLMConfig",
 ]
-__version__ = "0.4.16"
+__version__ = "0.4.10"
@@ -24,35 +24,14 @@ depends_on: str | Sequence[str] | None = None

 def _detect_vector_extension() -> str:
    """
-    Detect or validate vector extension: 'pgvector', 'vchord', or 'pgvectorscale'.
+    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 == "pgvectorscale":
-        # pgvectorscale/DiskANN requires pgvector
-        pgvector_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vector'")).scalar()
-        if not pgvector_check:
-            raise RuntimeError(
-                "DiskANN requires pgvector. Install with: CREATE EXTENSION vector; then vectorscale or pg_diskann CASCADE;"
-            )
-        # Check for either vectorscale (open source) or pg_diskann (Azure)
-        vectorscale_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vectorscale'")).scalar()
-        pg_diskann_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'pg_diskann'")).scalar()
-
-        if vectorscale_check:
-            return "pgvectorscale"
-        elif pg_diskann_check:
-            return "pg_diskann"
-        else:
-            raise RuntimeError(
-                "Configured vector extension 'pgvectorscale' not found. Install either:\n"
-                "  - pgvectorscale: CREATE EXTENSION vectorscale CASCADE;\n"
-                "  - pg_diskann (Azure): CREATE EXTENSION pg_diskann CASCADE;"
-            )
-    elif vector_extension == "vchord":
+    if vector_extension == "vchord":
        vchord_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vchord'")).scalar()
        if not vchord_check:
            raise RuntimeError(
@@ -67,14 +46,12 @@ def _detect_vector_extension() -> str:
            )
        return "pgvector"
    else:
-        raise ValueError(
-            f"Invalid HINDSIGHT_API_VECTOR_EXTENSION: {vector_extension}. Must be 'pgvector', 'vchord', or 'pgvectorscale'"
-        )
+        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'.
+    Detect or validate text search extension: 'native' or 'vchord'.
    Respects HINDSIGHT_API_TEXT_SEARCH_EXTENSION env var.
    Creates the extension if needed.
    """
@@ -92,23 +69,11 @@ def _detect_text_search_extension() -> str:
                # 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'"
+            f"Invalid HINDSIGHT_API_TEXT_SEARCH_EXTENSION: {text_search_extension}. Must be 'native' or 'vchord'"
        )


@@ -267,12 +232,6 @@ def upgrade() -> None:
            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("""
@@ -312,21 +271,7 @@ def upgrade() -> None:
    # Create vector index - conditional based on available extension
    vector_ext = _detect_vector_extension()

-    if vector_ext == "pgvectorscale":
-        # Use DiskANN index for pgvectorscale (disk-based, scalable)
-        op.execute("""
-            CREATE INDEX idx_memory_units_embedding ON memory_units
-            USING diskann (embedding vector_cosine_ops)
-            WITH (num_neighbors = 50)
-        """)
-    elif vector_ext == "pg_diskann":
-        # Use DiskANN index for pg_diskann (Azure)
-        op.execute("""
-            CREATE INDEX idx_memory_units_embedding ON memory_units
-            USING diskann (embedding vector_cosine_ops)
-            WITH (max_neighbors = 50)
-        """)
-    elif vector_ext == "vchord":
+    if vector_ext == "vchord":
        # Use vchordrq index for vchord (supports high-dimensional embeddings)
        op.execute("""
            CREATE INDEX idx_memory_units_embedding ON memory_units
@@ -350,14 +295,6 @@ def upgrade() -> None:
            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("""
@@ -1,70 +0,0 @@
-"""Add file_storage table for BYTEA-based file storage
-
-Revision ID: a1b2c3d4e5f6
-Revises: y0t1u2v3w4x5
-Create Date: 2026-02-16
-
-Creates a dedicated table for storing uploaded files using BYTEA.
-This provides zero-config file storage that "just works" for development
-and small deployments. For production/scale, use S3-compatible storage.
-
-Files are stored in a separate table to avoid bloating the documents table.
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "a1b2c3d4e5f6"
-down_revision: str | Sequence[str] | None = "y0t1u2v3w4x5"
-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:
-    """Create file_storage table for BYTEA storage."""
-    schema = _get_schema_prefix()
-
-    # Create file_storage table (minimal: just key + data)
-    op.execute(
-        f"""
-        CREATE TABLE {schema}file_storage (
-            storage_key TEXT PRIMARY KEY,
-            data BYTEA NOT NULL
-        )
-    """
-    )
-
-    # Add file tracking columns to documents table
-    op.execute(
-        f"""
-        ALTER TABLE {schema}documents
-        ADD COLUMN IF NOT EXISTS file_storage_key TEXT,
-        ADD COLUMN IF NOT EXISTS file_original_name TEXT,
-        ADD COLUMN IF NOT EXISTS file_content_type TEXT
-    """
-    )
-
-
-def downgrade() -> None:
-    """Remove file_storage table and related columns."""
-    schema = _get_schema_prefix()
-
-    # Drop columns from documents table
-    op.execute(
-        f"""
-        ALTER TABLE {schema}documents
-        DROP COLUMN IF EXISTS file_storage_key,
-        DROP COLUMN IF EXISTS file_original_name,
-        DROP COLUMN IF EXISTS file_content_type
-    """
-    )
-
-    # Drop file_storage table
-    op.execute(f"DROP TABLE IF EXISTS {schema}file_storage")
@@ -1,88 +0,0 @@
-"""Add text_signals column to memory_units for enriched BM25 indexing.
-
-text_signals stores a denormalized space-separated string of entity names
-(and future signals) to improve full-text search recall without polluting
-the stored fact text.
-
- vchord: text_signals included in tokenize() at insert time
- native: search_vector GENERATED column regenerated to include text_signals
- pg_textsearch: no change (index only supports a single base column)
-
-Revision ID: a2b3c4d5e6f7
-Revises: z1u2v3w4x5y6
-Create Date: 2026-02-28
-"""
-
-import os
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "a2b3c4d5e6f7"
-down_revision: str | Sequence[str] | None = "aa2b3c4d5e6f"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def _get_schema_prefix() -> str:
-    schema = context.config.get_main_option("target_schema")
-    return f'"{schema}".' if schema else ""
-
-
-def _detect_text_search_extension() -> str:
-    return os.getenv("HINDSIGHT_API_TEXT_SEARCH_EXTENSION", "native").lower()
-
-
-def upgrade() -> None:
-    schema = _get_schema_prefix()
-    table = f"{schema}memory_units"
-    text_search_ext = _detect_text_search_extension()
-
-    # Add text_signals column (nullable TEXT, populated at retain time)
-    op.execute(f"ALTER TABLE {table} ADD COLUMN IF NOT EXISTS text_signals TEXT")
-
-    if text_search_ext == "native":
-        # Native PostgreSQL: drop and recreate the GENERATED tsvector column to include text_signals
-        op.execute(f"ALTER TABLE {table} DROP COLUMN IF EXISTS search_vector")
-        op.execute(f"""
-            ALTER TABLE {table}
-            ADD COLUMN search_vector tsvector
-            GENERATED ALWAYS AS (
-                to_tsvector('english',
-                    COALESCE(text, '') || ' ' ||
-                    COALESCE(context, '') || ' ' ||
-                    COALESCE(text_signals, '')
-                )
-            ) STORED
-        """)
-        # Recreate GIN index (was dropped with the column)
-        op.execute(f"""
-            CREATE INDEX IF NOT EXISTS idx_memory_units_text_search
-            ON {table} USING gin(search_vector)
-        """)
-
-    # vchord: tokenize() call in fact_storage.py is updated to include text_signals at insert time
-    # pg_textsearch: no change — index operates on the base `text` column only
-
-
-def downgrade() -> None:
-    schema = _get_schema_prefix()
-    table = f"{schema}memory_units"
-    text_search_ext = _detect_text_search_extension()
-
-    if text_search_ext == "native":
-        op.execute(f"DROP INDEX IF EXISTS {schema}idx_memory_units_text_search")
-        op.execute(f"ALTER TABLE {table} DROP COLUMN IF EXISTS search_vector")
-        op.execute(f"""
-            ALTER TABLE {table}
-            ADD COLUMN search_vector tsvector
-            GENERATED ALWAYS AS (
-                to_tsvector('english', COALESCE(text, '') || ' ' || COALESCE(context, ''))
-            ) STORED
-        """)
-        op.execute(f"""
-            CREATE INDEX idx_memory_units_text_search
-            ON {table} USING gin(search_vector)
-        """)
-
-    op.execute(f"ALTER TABLE {table} DROP COLUMN IF EXISTS text_signals")
@@ -1,54 +0,0 @@
-"""Add GIN index on source_memory_ids for observation lookup performance
-
-Without this index, queries using the array overlap operator (&&) or array
-containment (@>) on source_memory_ids require a full sequential scan over all
-observation memory_units. At ~77k observations this was measured at 45ms per
-query, becoming a bottleneck during consolidation recall (57-64s timeouts) and
-user recall (18-27s average).
-
-The GIN index reduces these queries to index scans: 45ms → 0.049ms (927x
-speedup). Recall dropped from 18-27s to ~6s, and consolidation recall
-stabilised from timeout to ~15s.
-
-Created with CONCURRENTLY so the migration does not block reads or writes.
-CONCURRENTLY requires running outside a transaction block, so the migration
-emits an explicit COMMIT before the statement and uses IF NOT EXISTS for
-idempotency.
-
-Revision ID: a2b3c4d5e6f8
-Revises: f7g8h9i0j1k2
-Create Date: 2026-03-04
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "a2b3c4d5e6f8"
-down_revision: str | Sequence[str] | None = "f7g8h9i0j1k2"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def _get_schema_prefix() -> str:
-    schema = context.config.get_main_option("target_schema")
-    return f'"{schema}".' if schema else ""
-
-
-def upgrade() -> None:
-    schema = _get_schema_prefix()
-
-    # CREATE INDEX CONCURRENTLY cannot run inside a transaction block.
-    # Commit the current Alembic transaction first.
-    op.execute("COMMIT")
-    op.execute(
-        f"CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_memory_units_source_memory_ids "
-        f"ON {schema}memory_units USING GIN (source_memory_ids) "
-        f"WHERE source_memory_ids IS NOT NULL"
-    )
-
-
-def downgrade() -> None:
-    schema = _get_schema_prefix()
-    op.execute("COMMIT")
-    op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {schema}idx_memory_units_source_memory_ids")
@@ -1,36 +0,0 @@
-"""Make event_date nullable in memory_units to support timestamp-free content
-
-Revision ID: aa2b3c4d5e6f
-Revises: z1u2v3w4x5y6
-Create Date: 2026-03-02
-
-When callers retain content without a timestamp (e.g. fictional documents, static text),
-the event_date column should be allowed to be NULL rather than defaulting to utcnow().
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "aa2b3c4d5e6f"
-down_revision: str | Sequence[str] | None = "z1u2v3w4x5y6"
-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:
-    schema = _get_schema_prefix()
-    op.execute(f"ALTER TABLE {schema}memory_units ALTER COLUMN event_date DROP NOT NULL")
-
-
-def downgrade() -> None:
-    schema = _get_schema_prefix()
-    # Backfill NULLs with now() before restoring the NOT NULL constraint
-    op.execute(f"UPDATE {schema}memory_units SET event_date = now() WHERE event_date IS NULL")
-    op.execute(f"ALTER TABLE {schema}memory_units ALTER COLUMN event_date SET NOT NULL")
@@ -1,68 +0,0 @@
-"""Add partial indexes on memory_units temporal date fields for fast temporal retrieval
-
-Revision ID: b3c4d5e6f7g8
-Revises: c1a2b3d4e5f6
-Create Date: 2026-03-02
-
-The temporal retrieval entry-point query filters memory_units by occurred_start,
-occurred_end, and mentioned_at using OR conditions. Without dedicated indexes the
-planner falls back to a sequential scan of all bank rows after applying the
-(bank_id, fact_type) index, then re-checks each date field.
-
-These three partial indexes give the planner bitmap-index scan options for the
-three most common date predicates, dramatically reducing the row set before any
-embedding computation is required.
-
-All indexes are created CONCURRENTLY so the migration does not block writes on
-memory_units during production deployments. CONCURRENTLY requires running outside
-a transaction block; see migrations.py for how this is handled safely.
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "b3c4d5e6f7g8"
-down_revision: str | Sequence[str] | None = "c1a2b3d4e5f6"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def _get_schema_prefix() -> str:
-    schema = context.config.get_main_option("target_schema")
-    return f'"{schema}".' if schema else ""
-
-
-def upgrade() -> None:
-    schema = _get_schema_prefix()
-    # Partial index on occurred_start (covers "occurred_start BETWEEN $4 AND $5")
-    op.execute("COMMIT")
-    op.execute(
-        f"CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_memory_units_bank_occurred_start "
-        f"ON {schema}memory_units(bank_id, fact_type, occurred_start) "
-        f"WHERE occurred_start IS NOT NULL"
-    )
-    # Partial index on occurred_end (covers "occurred_end BETWEEN $4 AND $5")
-    op.execute("COMMIT")
-    op.execute(
-        f"CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_memory_units_bank_occurred_end "
-        f"ON {schema}memory_units(bank_id, fact_type, occurred_end) "
-        f"WHERE occurred_end IS NOT NULL"
-    )
-    # Partial index on mentioned_at (covers "mentioned_at BETWEEN $4 AND $5")
-    op.execute("COMMIT")
-    op.execute(
-        f"CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_memory_units_bank_mentioned_at "
-        f"ON {schema}memory_units(bank_id, fact_type, mentioned_at) "
-        f"WHERE mentioned_at IS NOT NULL"
-    )
-
-
-def downgrade() -> None:
-    schema = _get_schema_prefix()
-    op.execute("COMMIT")
-    op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {schema}idx_memory_units_bank_mentioned_at")
-    op.execute("COMMIT")
-    op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {schema}idx_memory_units_bank_occurred_end")
-    op.execute("COMMIT")
-    op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {schema}idx_memory_units_bank_occurred_start")
@@ -1,34 +0,0 @@
-"""Backfill observation_scopes column if missing.
-
-This migration ensures observation_scopes exists even on databases that had
-revision z1u2v3w4x5y6 applied when it referred to the old text_signals migration
-(before it was renamed to a2b3c4d5e6f7). The ADD COLUMN IF NOT EXISTS makes this
-a no-op on databases that already have the column.
-
-Revision ID: b4c5d6e7f8a9
-Revises: a2b3c4d5e6f7
-Create Date: 2026-03-02
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "b4c5d6e7f8a9"
-down_revision: str | Sequence[str] | None = "a2b3c4d5e6f7"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def _get_schema_prefix() -> str:
-    schema = context.config.get_main_option("target_schema")
-    return f'"{schema}".' if schema else ""
-
-
-def upgrade() -> None:
-    schema = _get_schema_prefix()
-    op.execute(f"ALTER TABLE {schema}memory_units ADD COLUMN IF NOT EXISTS observation_scopes JSONB")
-
-
-def downgrade() -> None:
-    pass  # intentionally no-op — safe to leave the column in place
@@ -1,46 +0,0 @@
-"""Enable pg_trgm extension and add GIN trigram index on entities.canonical_name
-
-Revision ID: c1a2b3d4e5f6
-Revises: b4c5d6e7f8a9
-Create Date: 2026-03-02
-
-Index is created CONCURRENTLY so the migration does not block writes on entities
-during production deployments. CONCURRENTLY requires running outside a transaction
-block; see migrations.py for how this is handled safely.
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "c1a2b3d4e5f6"
-down_revision: str | Sequence[str] | None = "b4c5d6e7f8a9"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def _get_schema_prefix() -> str:
-    schema = context.config.get_main_option("target_schema")
-    return f'"{schema}".' if schema else ""
-
-
-def upgrade() -> None:
-    # pg_trgm ships with every standard PostgreSQL installation as a contrib module.
-    # It enables fast similarity lookups via GIN indexes, used for entity name matching.
-    op.execute("CREATE EXTENSION IF NOT EXISTS pg_trgm")
-
-    schema = _get_schema_prefix()
-    # GIN index on canonical_name enables sub-millisecond trigram similarity queries
-    # (% operator, similarity()) instead of full-table scans across all bank entities.
-    op.execute("COMMIT")
-    op.execute(
-        f"CREATE INDEX CONCURRENTLY IF NOT EXISTS entities_canonical_name_trgm_idx "
-        f"ON {schema}entities USING GIN (canonical_name gin_trgm_ops)"
-    )
-
-
-def downgrade() -> None:
-    schema = _get_schema_prefix()
-    op.execute("COMMIT")
-    op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {schema}entities_canonical_name_trgm_idx")
-    # Note: not dropping pg_trgm extension as other indexes may depend on it
@@ -1,30 +0,0 @@
-"""Add history column to mental_models
-
-Revision ID: c3d4e5f6g7h8
-Revises: a2b3c4d5e6f7, a2b3c4d5e6f8
-Create Date: 2026-03-06
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "c3d4e5f6g7h8"
-down_revision: str | Sequence[str] | None = ("a2b3c4d5e6f7", "a2b3c4d5e6f8")
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def _get_schema_prefix() -> str:
-    schema = context.config.get_main_option("target_schema")
-    return f'"{schema}".' if schema else ""
-
-
-def upgrade() -> None:
-    schema = _get_schema_prefix()
-    op.execute(f"ALTER TABLE {schema}mental_models ADD COLUMN IF NOT EXISTS history JSONB DEFAULT '[]'::jsonb")
-
-
-def downgrade() -> None:
-    schema = _get_schema_prefix()
-    op.execute(f"ALTER TABLE {schema}mental_models DROP COLUMN IF EXISTS history")
@@ -1,83 +0,0 @@
-"""Add covering and composite indexes to speed up link expansion graph retrieval.
-
-Two indexes target the two bottlenecks identified by EXPLAIN ANALYZE on a 17M-row
-memory_links table:
-
-1. idx_memory_links_to_type_weight  (to_unit_id, link_type, weight DESC)
-   The semantic incoming direction — finding facts that consider seeds as their
-   nearest neighbour — currently hits an expensive BitmapAnd of two separate
-   bitmap scans (to_unit_id bitmap ∩ link_type bitmap).  A composite index
-   on (to_unit_id, link_type) turns this into a single index scan and reduces
-   latency from ~36 ms to < 5 ms per query.
-
-2. idx_memory_links_entity_covering  (from_unit_id) INCLUDE (to_unit_id, entity_id)
-   WHERE link_type = 'entity'
-   The entity co-occurrence expansion uses COUNT(DISTINCT ml.entity_id) and
-   joins on ml.to_unit_id.  Without a covering index the planner must read
-   ~2 500 heap pages to fetch entity_id and to_unit_id after the bitmap index
-   scan, adding ~230 ms of random I/O.  INCLUDE adds those two columns to the
-   index leaf pages so the entire query can be served from the index (index-only
-   scan), eliminating the heap reads entirely.
-   Partial index (WHERE link_type = 'entity') keeps index size ~40 % smaller.
-
-Both indexes are created with CONCURRENTLY so the migration does not block
-concurrent reads or writes on memory_links.  CONCURRENTLY requires running
-outside a transaction block, so the migration emits an explicit COMMIT before
-each statement and uses IF NOT EXISTS for idempotency.
-
-Revision ID: d2e3f4a5b6c7
-Revises: b3c4d5e6f7g8
-Create Date: 2026-03-02
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "d2e3f4a5b6c7"
-down_revision: str | Sequence[str] | None = "b3c4d5e6f7g8"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def _get_schema_prefix() -> str:
-    schema = context.config.get_main_option("target_schema")
-    return f'"{schema}".' if schema else ""
-
-
-def upgrade() -> None:
-    schema = _get_schema_prefix()
-
-    # CREATE INDEX CONCURRENTLY cannot run inside a transaction block.
-    # Commit the current Alembic transaction, then issue each CONCURRENTLY
-    # statement in its own implicit autocommit transaction.
-    # IF NOT EXISTS makes each statement idempotent if the migration is retried.
-
-    # Index for the semantic *incoming* direction in link_expansion_retrieval.py.
-    # Replaces the BitmapAnd of idx_memory_links_to_unit ∩ idx_memory_links_link_type
-    # with a single composite index scan.
-    op.execute("COMMIT")
-    op.execute(
-        f"CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_memory_links_to_type_weight "
-        f"ON {schema}memory_links(to_unit_id, link_type, weight DESC)"
-    )
-
-    # Covering index for entity co-occurrence expansion.
-    # Enables an index-only scan: entity_id and to_unit_id are read from the
-    # index leaf pages instead of the heap, eliminating ~2 500 random heap-page
-    # reads per expansion query.
-    op.execute("COMMIT")
-    op.execute(
-        f"CREATE INDEX CONCURRENTLY IF NOT EXISTS idx_memory_links_entity_covering "
-        f"ON {schema}memory_links(from_unit_id) "
-        f"INCLUDE (to_unit_id, entity_id) "
-        f"WHERE link_type = 'entity'"
-    )
-
-
-def downgrade() -> None:
-    schema = _get_schema_prefix()
-    op.execute("COMMIT")
-    op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {schema}idx_memory_links_entity_covering")
-    op.execute("COMMIT")
-    op.execute(f"DROP INDEX CONCURRENTLY IF EXISTS {schema}idx_memory_links_to_type_weight")
@@ -1,62 +0,0 @@
-"""Add webhooks table and next_retry_at to async_operations.
-
-Webhook deliveries are handled as async_operations tasks (operation_type='webhook_delivery')
-rather than a dedicated webhook_deliveries table.
-
-Revision ID: e4f5a6b7c8d9
-Revises: d2e3f4a5b6c7
-Create Date: 2026-03-04
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "e4f5a6b7c8d9"
-down_revision: str | Sequence[str] | None = "d2e3f4a5b6c7"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def _get_schema_prefix() -> str:
-    schema = context.config.get_main_option("target_schema")
-    return f'"{schema}".' if schema else ""
-
-
-def upgrade() -> None:
-    schema = _get_schema_prefix()
-
-    op.execute(
-        f"""
-        CREATE TABLE IF NOT EXISTS {schema}webhooks (
-            id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
-            bank_id TEXT,
-            url TEXT NOT NULL,
-            secret TEXT,
-            event_types TEXT[] NOT NULL DEFAULT '{{}}',
-            enabled BOOLEAN NOT NULL DEFAULT TRUE,
-            created_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
-            updated_at TIMESTAMPTZ NOT NULL DEFAULT NOW()
-        )
-        """
-    )
-
-    # Index for bank-scoped webhook lookup
-    op.execute(f"CREATE INDEX IF NOT EXISTS idx_webhooks_bank_id ON {schema}webhooks(bank_id)")
-
-    # Add next_retry_at to async_operations for task-owned retry scheduling
-    op.execute(f"ALTER TABLE {schema}async_operations ADD COLUMN IF NOT EXISTS next_retry_at TIMESTAMPTZ NULL")
-
-    # Index for polling: status + next_retry_at
-    op.execute(
-        f"CREATE INDEX IF NOT EXISTS idx_async_operations_status_retry "
-        f"ON {schema}async_operations(status, next_retry_at)"
-    )
-
-
-def downgrade() -> None:
-    schema = _get_schema_prefix()
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_async_operations_status_retry")
-    op.execute(f"ALTER TABLE {schema}async_operations DROP COLUMN IF EXISTS next_retry_at")
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_webhooks_bank_id")
-    op.execute(f"DROP TABLE IF EXISTS {schema}webhooks")
@@ -1,33 +0,0 @@
-"""Add http_config JSONB column to webhooks table.
-
-Stores HTTP delivery configuration (method, timeout, headers, params) as a
-single JSONB column rather than separate columns.
-
-Revision ID: f7g8h9i0j1k2
-Revises: e4f5a6b7c8d9
-Create Date: 2026-03-04
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "f7g8h9i0j1k2"
-down_revision: str | Sequence[str] | None = "e4f5a6b7c8d9"
-branch_labels: str | Sequence[str] | None = None
-depends_on: str | Sequence[str] | None = None
-
-
-def _get_schema_prefix() -> str:
-    schema = context.config.get_main_option("target_schema")
-    return f'"{schema}".' if schema else ""
-
-
-def upgrade() -> None:
-    schema = _get_schema_prefix()
-    op.execute(f"ALTER TABLE {schema}webhooks ADD COLUMN IF NOT EXISTS http_config JSONB NOT NULL DEFAULT '{{}}'")
-
-
-def downgrade() -> None:
-    schema = _get_schema_prefix()
-    op.execute(f"ALTER TABLE {schema}webhooks DROP COLUMN IF EXISTS http_config")
@@ -31,35 +31,14 @@ def _get_schema_prefix() -> str:

 def _detect_vector_extension() -> str:
    """
-    Detect or validate vector extension: 'pgvector', 'vchord', or 'pgvectorscale'.
+    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 == "pgvectorscale":
-        # pgvectorscale/DiskANN requires pgvector
-        pgvector_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vector'")).scalar()
-        if not pgvector_check:
-            raise RuntimeError(
-                "DiskANN requires pgvector. Install with: CREATE EXTENSION vector; then vectorscale or pg_diskann CASCADE;"
-            )
-        # Check for either vectorscale (open source) or pg_diskann (Azure)
-        vectorscale_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vectorscale'")).scalar()
-        pg_diskann_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'pg_diskann'")).scalar()
-
-        if vectorscale_check:
-            return "pgvectorscale"
-        elif pg_diskann_check:
-            return "pg_diskann"
-        else:
-            raise RuntimeError(
-                "Configured vector extension 'pgvectorscale' not found. Install either:\n"
-                "  - pgvectorscale: CREATE EXTENSION vectorscale CASCADE;\n"
-                "  - pg_diskann (Azure): CREATE EXTENSION pg_diskann CASCADE;"
-            )
-    elif vector_extension == "vchord":
+    if vector_extension == "vchord":
        vchord_check = conn.execute(text("SELECT 1 FROM pg_extension WHERE extname = 'vchord'")).scalar()
        if not vchord_check:
            raise RuntimeError(
@@ -74,14 +53,12 @@ def _detect_vector_extension() -> str:
            )
        return "pgvector"
    else:
-        raise ValueError(
-            f"Invalid HINDSIGHT_API_VECTOR_EXTENSION: {vector_extension}. Must be 'pgvector', 'vchord', or 'pgvectorscale'"
-        )
+        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'.
+    Detect or validate text search extension: 'native' or 'vchord'.
    Respects HINDSIGHT_API_TEXT_SEARCH_EXTENSION env var.
    Creates the extension if needed.
    """
@@ -99,23 +76,11 @@ def _detect_text_search_extension() -> str:
                # 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'"
+            f"Invalid HINDSIGHT_API_TEXT_SEARCH_EXTENSION: {text_search_extension}. Must be 'native' or 'vchord'"
        )


@@ -157,19 +122,7 @@ def upgrade() -> None:
    op.execute(f"CREATE INDEX idx_learnings_bank_id ON {schema}learnings(bank_id)")

    # Create vector index based on detected extension
-    if vector_ext == "pgvectorscale":
-        op.execute(f"""
-            CREATE INDEX idx_learnings_embedding ON {schema}learnings
-            USING diskann (embedding vector_cosine_ops)
-            WITH (num_neighbors = 50)
-        """)
-    elif vector_ext == "pg_diskann":
-        op.execute(f"""
-            CREATE INDEX idx_learnings_embedding ON {schema}learnings
-            USING diskann (embedding vector_cosine_ops)
-            WITH (max_neighbors = 50)
-        """)
-    elif vector_ext == "vchord":
+    if vector_ext == "vchord":
        op.execute(f"""
            CREATE INDEX idx_learnings_embedding ON {schema}learnings
            USING vchordrq (embedding vector_l2_ops)
@@ -193,15 +146,6 @@ def upgrade() -> None:
            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"""
@@ -236,19 +180,7 @@ def upgrade() -> None:
    op.execute(f"CREATE INDEX idx_pinned_reflections_bank_id ON {schema}pinned_reflections(bank_id)")

    # Create vector index based on detected extension
-    if vector_ext == "pgvectorscale":
-        op.execute(f"""
-            CREATE INDEX idx_pinned_reflections_embedding ON {schema}pinned_reflections
-            USING diskann (embedding vector_cosine_ops)
-            WITH (num_neighbors = 50)
-        """)
-    elif vector_ext == "pg_diskann":
-        op.execute(f"""
-            CREATE INDEX idx_pinned_reflections_embedding ON {schema}pinned_reflections
-            USING diskann (embedding vector_cosine_ops)
-            WITH (max_neighbors = 50)
-        """)
-    elif vector_ext == "vchord":
+    if vector_ext == "vchord":
        op.execute(f"""
            CREATE INDEX idx_pinned_reflections_embedding ON {schema}pinned_reflections
            USING vchordrq (embedding vector_l2_ops)
@@ -272,16 +204,6 @@ def upgrade() -> None:
            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"""
@@ -1,49 +0,0 @@
-"""Add GIN index on async_operations.result_metadata for parent_operation_id queries
-
-Revision ID: y0t1u2v3w4x5
-Revises: x9s0t1u2v3w4
-Create Date: 2026-02-13
-
-This migration adds a GIN index on the result_metadata JSONB column in the
-async_operations table to support efficient queries for child operations by
-parent_operation_id.
-
-The index enables fast lookups when querying for child operations:
-  SELECT * FROM async_operations
-  WHERE result_metadata::jsonb @> '{"parent_operation_id": "uuid"}'::jsonb
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "y0t1u2v3w4x5"
-down_revision: str | Sequence[str] | None = "x9s0t1u2v3w4"
-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 GIN index on result_metadata for efficient parent_operation_id queries."""
-    schema = _get_schema_prefix()
-
-    # Add GIN index for JSONB containment queries (@> operator)
-    op.execute(f"""
-        CREATE INDEX idx_async_operations_result_metadata
-        ON {schema}async_operations
-        USING gin(result_metadata)
-    """)
-
-
-def downgrade() -> None:
-    """Remove GIN index on result_metadata."""
-    schema = _get_schema_prefix()
-
-    # Drop index
-    op.execute(f"DROP INDEX IF EXISTS {schema}idx_async_operations_result_metadata")
@@ -1,35 +0,0 @@
-"""Add observation_scopes column to memory_units table
-
-Revision ID: z1u2v3w4x5y6
-Revises: a1b2c3d4e5f6
-Create Date: 2026-02-25
-
-Adds observation_scopes JSONB column to memory_units to control how observations
-are scoped during consolidation. Accepts "per_tag", "combined", or an explicit
-list of tag-set lists for custom multi-pass consolidation.
-"""
-
-from collections.abc import Sequence
-
-from alembic import context, op
-
-revision: str = "z1u2v3w4x5y6"
-down_revision: str | Sequence[str] | None = "a1b2c3d4e5f6"
-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:
-    schema = _get_schema_prefix()
-    op.execute(f"ALTER TABLE {schema}memory_units ADD COLUMN IF NOT EXISTS observation_scopes JSONB")
-
-
-def downgrade() -> None:
-    schema = _get_schema_prefix()
-    op.execute(f"ALTER TABLE {schema}memory_units DROP COLUMN IF EXISTS observation_scopes")
@@ -8,48 +8,12 @@ from contextvars import ContextVar
 from fastmcp import FastMCP

 from hindsight_api import MemoryEngine
-from hindsight_api.config import _get_raw_config
 from hindsight_api.engine.memory_engine import _current_schema
 from hindsight_api.extensions import MCPExtension, load_extension
 from hindsight_api.extensions.tenant import AuthenticationError
 from hindsight_api.mcp_tools import MCPToolsConfig, register_mcp_tools
 from hindsight_api.models import RequestContext

-# All tools available in the system (explicit list — no wildcards)
-_ALL_TOOLS: frozenset[str] = frozenset(
-    {
-        "retain",
-        "recall",
-        "reflect",
-        "list_banks",
-        "create_bank",
-        "list_mental_models",
-        "get_mental_model",
-        "create_mental_model",
-        "update_mental_model",
-        "delete_mental_model",
-        "refresh_mental_model",
-        "list_directives",
-        "create_directive",
-        "delete_directive",
-        "list_memories",
-        "get_memory",
-        "delete_memory",
-        "list_documents",
-        "get_document",
-        "delete_document",
-        "list_operations",
-        "get_operation",
-        "cancel_operation",
-        "list_tags",
-        "get_bank",
-        "get_bank_stats",
-        "update_bank",
-        "delete_bank",
-        "clear_memories",
-    }
-)
-
 # Configure logging from HINDSIGHT_API_LOG_LEVEL environment variable
 _log_level_str = os.environ.get("HINDSIGHT_API_LOG_LEVEL", "info").lower()
 _log_level_map = {
@@ -114,15 +78,21 @@ def create_mcp_server(memory: MemoryEngine, multi_bank: bool = True) -> FastMCP:
                   If False, only expose bank-scoped tools without bank_id parameters.

    Returns:
-        Configured FastMCP server instance
+        Configured FastMCP server instance with stateless_http enabled
    """
-    mcp = FastMCP("hindsight-mcp-server")
+    # Use stateless_http=True for Claude Code compatibility
+    mcp = FastMCP("hindsight-mcp-server", stateless_http=True)

-    global_config = _get_raw_config()
-
-    # Tools available for this mode (multi-bank exposes all tools; single-bank excludes bank-management tools)
-    _SINGLE_BANK_TOOLS: frozenset[str] = frozenset(
-        {
+    # Configure and register tools using shared module
+    config = MCPToolsConfig(
+        bank_id_resolver=get_current_bank_id,
+        api_key_resolver=get_current_api_key,  # Propagate API key for tenant auth
+        tenant_id_resolver=get_current_tenant_id,  # Propagate tenant_id for usage metering
+        api_key_id_resolver=get_current_api_key_id,  # Propagate api_key_id for usage metering
+        include_bank_id_param=multi_bank,
+        tools=None
+        if multi_bank
+        else {
            "retain",
            "recall",
            "reflect",
@@ -132,40 +102,8 @@ def create_mcp_server(memory: MemoryEngine, multi_bank: bool = True) -> FastMCP:
            "update_mental_model",
            "delete_mental_model",
            "refresh_mental_model",
-            "list_directives",
-            "create_directive",
-            "delete_directive",
-            "list_memories",
-            "get_memory",
-            "delete_memory",
-            "list_documents",
-            "get_document",
-            "delete_document",
-            "list_operations",
-            "get_operation",
-            "cancel_operation",
-            "list_tags",
-            "get_bank",
-            "update_bank",
-            "delete_bank",
-            "clear_memories",
-        }
-    )
-    base_tools: frozenset[str] | None = None if multi_bank else _SINGLE_BANK_TOOLS
-
-    # Apply global mcp_enabled_tools filter (env-level allowlist)
-    if global_config.mcp_enabled_tools is not None:
-        allowed = frozenset(global_config.mcp_enabled_tools)
-        base_tools = (base_tools if base_tools is not None else _ALL_TOOLS) & allowed
-
-    # Configure and register tools using shared module
-    config = MCPToolsConfig(
-        bank_id_resolver=get_current_bank_id,
-        api_key_resolver=get_current_api_key,  # Propagate API key for tenant auth
-        tenant_id_resolver=get_current_tenant_id,  # Propagate tenant_id for usage metering
-        api_key_id_resolver=get_current_api_key_id,  # Propagate api_key_id for usage metering
-        include_bank_id_param=multi_bank,
-        tools=base_tools,
+        },  # Scoped tools for single-bank mode (excludes bank management: list_banks, create_bank)
+        retain_fire_and_forget=False,  # HTTP MCP supports sync/async modes
    )

    register_mcp_tools(mcp, memory, config)
@@ -273,9 +211,9 @@ class MCPMiddleware:
        else:
            # Create servers internally (for direct construction / tests)
            self.multi_bank_server = create_mcp_server(memory, multi_bank=True)
-            self.multi_bank_app = self.multi_bank_server.http_app(path="/", stateless_http=True)
+            self.multi_bank_app = self.multi_bank_server.http_app(path="/")
            self.single_bank_server = create_mcp_server(memory, multi_bank=False)
-            self.single_bank_app = self.single_bank_server.http_app(path="/", stateless_http=True)
+            self.single_bank_app = self.single_bank_server.http_app(path="/")

    def _get_header(self, scope: dict, name: str) -> str | None:
        """Extract a header value from ASGI scope."""
@@ -331,7 +269,7 @@ class MCPMiddleware:
                auth_tenant_id = auth_context.tenant_id
                auth_api_key_id = auth_context.api_key_id
            except AuthenticationError as e:
-                await self._send_error(send, 401, str(e), extra_headers=e.headers)
+                await self._send_error(send, 401, str(e))
                return

        # Set schema from tenant context so downstream DB queries use the correct schema
@@ -413,17 +351,14 @@ class MCPMiddleware:
            if schema_token is not None:
                _current_schema.reset(schema_token)

-    async def _send_error(self, send, status: int, message: str, extra_headers: dict[str, str] | None = None):
+    async def _send_error(self, send, status: int, message: str):
        """Send an error response."""
        body = json.dumps({"error": message}).encode()
-        headers = [(b"content-type", b"application/json")]
-        for key, value in (extra_headers or {}).items():
-            headers.append((key.encode(), value.encode()))
        await send(
            {
                "type": "http.response.start",
                "status": status,
-                "headers": headers,
+                "headers": [(b"content-type", b"application/json")],
            }
        )
        await send(
@@ -444,9 +379,9 @@ def create_mcp_servers(memory: MemoryEngine):
        Tuple of (multi_bank_server, single_bank_server, multi_bank_app, single_bank_app)
    """
    multi_bank_server = create_mcp_server(memory, multi_bank=True)
-    multi_bank_app = multi_bank_server.http_app(path="/", stateless_http=True)
+    multi_bank_app = multi_bank_server.http_app(path="/")

    single_bank_server = create_mcp_server(memory, multi_bank=False)
-    single_bank_app = single_bank_server.http_app(path="/", stateless_http=True)
+    single_bank_app = single_bank_server.http_app(path="/")

    return multi_bank_server, single_bank_server, multi_bank_app, single_bank_app
@@ -86,8 +86,6 @@ def print_startup_info(
    reranker_provider: str,
    mcp_enabled: bool = False,
    version: str | None = None,
-    vector_extension: str | None = None,
-    text_search_extension: str | None = None,
 ):
    """Print styled startup information."""
    print(color_start("Starting Hindsight API..."))
@@ -98,8 +96,6 @@ def print_startup_info(
    print(f"  {dim('LLM:')} {color(f'{llm_provider} / {llm_model}', 0.6)}")
    print(f"  {dim('Embeddings:')} {color(embeddings_provider, 0.8)}")
    print(f"  {dim('Reranker:')} {color(reranker_provider, 1.0)}")
-    extensions = f"{vector_extension or 'default'} (vector) / {text_search_extension or 'default'} (text)"
-    print(f"  {dim('Extensions:')} {color(extensions, 0.4)}")
    if mcp_enabled:
        print(f"  {dim('MCP:')} {color_end('enabled at /mcp')}")
    print()
@@ -129,11 +129,6 @@ ENV_LLM_INITIAL_BACKOFF = "HINDSIGHT_API_LLM_INITIAL_BACKOFF"
 ENV_LLM_MAX_BACKOFF = "HINDSIGHT_API_LLM_MAX_BACKOFF"
 ENV_LLM_TIMEOUT = "HINDSIGHT_API_LLM_TIMEOUT"
 ENV_LLM_GROQ_SERVICE_TIER = "HINDSIGHT_API_LLM_GROQ_SERVICE_TIER"
-ENV_LLM_OPENAI_SERVICE_TIER = "HINDSIGHT_API_LLM_OPENAI_SERVICE_TIER"
-
-# Defaults for service tiers
-DEFAULT_LLM_GROQ_SERVICE_TIER = "auto"  # "on_demand", "flex", or "auto"
-DEFAULT_LLM_OPENAI_SERVICE_TIER = None  # None (default) or "flex" (50% cheaper)

 # Per-operation LLM configuration (optional, falls back to global LLM config)
 ENV_RETAIN_LLM_PROVIDER = "HINDSIGHT_API_RETAIN_LLM_PROVIDER"
@@ -194,14 +189,6 @@ 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"
@@ -218,10 +205,6 @@ 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"

-# ZeroEntropy configuration (reranker only)
-ENV_RERANKER_ZEROENTROPY_API_KEY = "HINDSIGHT_API_RERANKER_ZEROENTROPY_API_KEY"
-ENV_RERANKER_ZEROENTROPY_MODEL = "HINDSIGHT_API_RERANKER_ZEROENTROPY_MODEL"
-
 ENV_VECTOR_EXTENSION = "HINDSIGHT_API_VECTOR_EXTENSION"
 ENV_TEXT_SEARCH_EXTENSION = "HINDSIGHT_API_TEXT_SEARCH_EXTENSION"

@@ -232,12 +215,13 @@ 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_MCP_ENABLED_TOOLS = "HINDSIGHT_API_MCP_ENABLED_TOOLS"
 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"
 ENV_RECALL_CONNECTION_BUDGET = "HINDSIGHT_API_RECALL_CONNECTION_BUDGET"
+ENV_MCP_LOCAL_BANK_ID = "HINDSIGHT_API_MCP_LOCAL_BANK_ID"
+ENV_MCP_INSTRUCTIONS = "HINDSIGHT_API_MCP_INSTRUCTIONS"
 ENV_MENTAL_MODEL_REFRESH_CONCURRENCY = "HINDSIGHT_API_MENTAL_MODEL_REFRESH_CONCURRENCY"

 # OpenTelemetry tracing configuration
@@ -252,60 +236,17 @@ ENV_LLM_VERTEXAI_PROJECT_ID = "HINDSIGHT_API_LLM_VERTEXAI_PROJECT_ID"
 ENV_LLM_VERTEXAI_REGION = "HINDSIGHT_API_LLM_VERTEXAI_REGION"
 ENV_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY = "HINDSIGHT_API_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY"

-# Gemini safety settings
-ENV_LLM_GEMINI_SAFETY_SETTINGS = "HINDSIGHT_API_LLM_GEMINI_SAFETY_SETTINGS"
-
 # Retain settings
 ENV_RETAIN_MAX_COMPLETION_TOKENS = "HINDSIGHT_API_RETAIN_MAX_COMPLETION_TOKENS"
 ENV_RETAIN_CHUNK_SIZE = "HINDSIGHT_API_RETAIN_CHUNK_SIZE"
 ENV_RETAIN_EXTRACT_CAUSAL_LINKS = "HINDSIGHT_API_RETAIN_EXTRACT_CAUSAL_LINKS"
 ENV_RETAIN_EXTRACTION_MODE = "HINDSIGHT_API_RETAIN_EXTRACTION_MODE"
-ENV_RETAIN_MISSION = "HINDSIGHT_API_RETAIN_MISSION"
 ENV_RETAIN_CUSTOM_INSTRUCTIONS = "HINDSIGHT_API_RETAIN_CUSTOM_INSTRUCTIONS"
-ENV_RETAIN_BATCH_TOKENS = "HINDSIGHT_API_RETAIN_BATCH_TOKENS"
-ENV_RETAIN_ENTITY_LOOKUP = "HINDSIGHT_API_RETAIN_ENTITY_LOOKUP"
-ENV_RETAIN_BATCH_ENABLED = "HINDSIGHT_API_RETAIN_BATCH_ENABLED"
-ENV_RETAIN_BATCH_POLL_INTERVAL_SECONDS = "HINDSIGHT_API_RETAIN_BATCH_POLL_INTERVAL_SECONDS"
-
-# File storage configuration
-ENV_FILE_STORAGE_TYPE = "HINDSIGHT_API_FILE_STORAGE_TYPE"
-ENV_FILE_STORAGE_S3_BUCKET = "HINDSIGHT_API_FILE_STORAGE_S3_BUCKET"
-ENV_FILE_STORAGE_S3_REGION = "HINDSIGHT_API_FILE_STORAGE_S3_REGION"
-ENV_FILE_STORAGE_S3_ENDPOINT = "HINDSIGHT_API_FILE_STORAGE_S3_ENDPOINT"
-ENV_FILE_STORAGE_S3_ACCESS_KEY_ID = "HINDSIGHT_API_FILE_STORAGE_S3_ACCESS_KEY_ID"
-ENV_FILE_STORAGE_S3_SECRET_ACCESS_KEY = "HINDSIGHT_API_FILE_STORAGE_S3_SECRET_ACCESS_KEY"
-ENV_FILE_STORAGE_GCS_BUCKET = "HINDSIGHT_API_FILE_STORAGE_GCS_BUCKET"
-ENV_FILE_STORAGE_GCS_SERVICE_ACCOUNT_KEY = "HINDSIGHT_API_FILE_STORAGE_GCS_SERVICE_ACCOUNT_KEY"
-ENV_FILE_STORAGE_AZURE_CONTAINER = "HINDSIGHT_API_FILE_STORAGE_AZURE_CONTAINER"
-ENV_FILE_STORAGE_AZURE_ACCOUNT_NAME = "HINDSIGHT_API_FILE_STORAGE_AZURE_ACCOUNT_NAME"
-ENV_FILE_STORAGE_AZURE_ACCOUNT_KEY = "HINDSIGHT_API_FILE_STORAGE_AZURE_ACCOUNT_KEY"
-ENV_FILE_PARSER = "HINDSIGHT_API_FILE_PARSER"
-ENV_FILE_PARSER_ALLOWLIST = "HINDSIGHT_API_FILE_PARSER_ALLOWLIST"
-ENV_FILE_PARSER_IRIS_TOKEN = "HINDSIGHT_API_FILE_PARSER_IRIS_TOKEN"
-ENV_FILE_PARSER_IRIS_ORG_ID = "HINDSIGHT_API_FILE_PARSER_IRIS_ORG_ID"
-ENV_FILE_CONVERSION_MAX_BATCH_SIZE_MB = "HINDSIGHT_API_FILE_CONVERSION_MAX_BATCH_SIZE_MB"
-ENV_FILE_CONVERSION_MAX_BATCH_SIZE = "HINDSIGHT_API_FILE_CONVERSION_MAX_BATCH_SIZE"
-ENV_ENABLE_FILE_UPLOAD_API = "HINDSIGHT_API_ENABLE_FILE_UPLOAD_API"
-ENV_FILE_DELETE_AFTER_RETAIN = "HINDSIGHT_API_FILE_DELETE_AFTER_RETAIN"

 # Observations settings (consolidated knowledge from facts)
 ENV_ENABLE_OBSERVATIONS = "HINDSIGHT_API_ENABLE_OBSERVATIONS"
 ENV_CONSOLIDATION_BATCH_SIZE = "HINDSIGHT_API_CONSOLIDATION_BATCH_SIZE"
-ENV_CONSOLIDATION_LLM_BATCH_SIZE = "HINDSIGHT_API_CONSOLIDATION_LLM_BATCH_SIZE"
 ENV_CONSOLIDATION_MAX_TOKENS = "HINDSIGHT_API_CONSOLIDATION_MAX_TOKENS"
-ENV_CONSOLIDATION_SOURCE_FACTS_MAX_TOKENS = "HINDSIGHT_API_CONSOLIDATION_SOURCE_FACTS_MAX_TOKENS"
-ENV_CONSOLIDATION_SOURCE_FACTS_MAX_TOKENS_PER_OBSERVATION = (
-    "HINDSIGHT_API_CONSOLIDATION_SOURCE_FACTS_MAX_TOKENS_PER_OBSERVATION"
-)
-ENV_OBSERVATIONS_MISSION = "HINDSIGHT_API_OBSERVATIONS_MISSION"
-ENV_ENABLE_OBSERVATION_HISTORY = "HINDSIGHT_API_ENABLE_OBSERVATION_HISTORY"
-ENV_ENABLE_MENTAL_MODEL_HISTORY = "HINDSIGHT_API_ENABLE_MENTAL_MODEL_HISTORY"
-
-# Webhook configuration (global, static - server-level only)
-ENV_WEBHOOK_URL = "HINDSIGHT_API_WEBHOOK_URL"
-ENV_WEBHOOK_SECRET = "HINDSIGHT_API_WEBHOOK_SECRET"
-ENV_WEBHOOK_EVENT_TYPES = "HINDSIGHT_API_WEBHOOK_EVENT_TYPES"
-ENV_WEBHOOK_DELIVERY_POLL_INTERVAL_SECONDS = "HINDSIGHT_API_WEBHOOK_DELIVERY_POLL_INTERVAL_SECONDS"

 # Optimization flags
 ENV_SKIP_LLM_VERIFICATION = "HINDSIGHT_API_SKIP_LLM_VERIFICATION"
@@ -331,13 +272,6 @@ ENV_WORKER_CONSOLIDATION_MAX_SLOTS = "HINDSIGHT_API_WORKER_CONSOLIDATION_MAX_SLO

 # Reflect agent settings
 ENV_REFLECT_MAX_ITERATIONS = "HINDSIGHT_API_REFLECT_MAX_ITERATIONS"
-ENV_REFLECT_MAX_CONTEXT_TOKENS = "HINDSIGHT_API_REFLECT_MAX_CONTEXT_TOKENS"
-ENV_REFLECT_MISSION = "HINDSIGHT_API_REFLECT_MISSION"
-
-# Disposition settings
-ENV_DISPOSITION_SKEPTICISM = "HINDSIGHT_API_DISPOSITION_SKEPTICISM"
-ENV_DISPOSITION_LITERALISM = "HINDSIGHT_API_DISPOSITION_LITERALISM"
-ENV_DISPOSITION_EMPATHY = "HINDSIGHT_API_DISPOSITION_EMPATHY"

 # Default values
 DEFAULT_DATABASE_URL = "pg0"
@@ -346,18 +280,18 @@ DEFAULT_LLM_PROVIDER = "openai"

 # Provider-specific default models
 PROVIDER_DEFAULT_MODELS = {
-    "openai": "gpt-4o-mini",
+    "openai": "o3-mini",
    "anthropic": "claude-haiku-4-5-20251001",
    "gemini": "gemini-2.5-flash",
    "groq": "openai/gpt-oss-120b",
    "ollama": "gemma3:12b",
    "lmstudio": "local-model",
-    "vertexai": "google/gemini-2.5-flash-lite",
+    "vertexai": "gemini-2.0-flash-001",
    "openai-codex": "gpt-5.2-codex",
    "claude-code": "claude-sonnet-4-5-20250929",
    "mock": "mock-model",
 }
-DEFAULT_LLM_MODEL = "gpt-4o-mini"  # Fallback if provider not in table
+DEFAULT_LLM_MODEL = "o3-mini"  # Fallback if provider not in table
 DEFAULT_LLM_MAX_CONCURRENT = 32
 DEFAULT_LLM_MAX_RETRIES = 10  # Max retry attempts for LLM API calls
 DEFAULT_LLM_INITIAL_BACKOFF = 1.0  # Initial backoff in seconds for retry exponential backoff
@@ -369,9 +303,6 @@ DEFAULT_LLM_VERTEXAI_PROJECT_ID = None  # Required for Vertex AI
 DEFAULT_LLM_VERTEXAI_REGION = "us-central1"
 DEFAULT_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY = None  # Optional, uses ADC if not set

-# Gemini safety settings defaults
-DEFAULT_LLM_GEMINI_SAFETY_SETTINGS = None  # None = use Gemini default safety settings
-
 DEFAULT_EMBEDDINGS_PROVIDER = "local"
 DEFAULT_EMBEDDINGS_LOCAL_MODEL = "BAAI/bge-small-en-v1.5"
 DEFAULT_EMBEDDINGS_LOCAL_FORCE_CPU = False  # Force CPU mode for local embeddings (avoids MPS/XPC issues on macOS)
@@ -395,23 +326,17 @@ 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"

-DEFAULT_RERANKER_ZEROENTROPY_MODEL = "zerank-2"
+# Vector extension (pgvector vs vchord)
+DEFAULT_VECTOR_EXTENSION = "pgvector"  # Options: "pgvector", "vchord"

-# Vector extension (pgvector, vchord, or pgvectorscale)
-DEFAULT_VECTOR_EXTENSION = "pgvector"  # Options: "pgvector", "vchord", "pgvectorscale"
-
-# Text search extension (native PostgreSQL, vchord BM25, or Timescale pg_textsearch)
-DEFAULT_TEXT_SEARCH_EXTENSION = "native"  # Options: "native", "vchord", "pg_textsearch"
+# Text search extension (native PostgreSQL vs vchord BM25)
+DEFAULT_TEXT_SEARCH_EXTENSION = "native"  # Options: "native", "vchord"

 # 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
@@ -419,12 +344,12 @@ DEFAULT_LOG_LEVEL = "info"
 DEFAULT_LOG_FORMAT = "text"  # Options: "text", "json"
 DEFAULT_WORKERS = 1
 DEFAULT_MCP_ENABLED = True
-DEFAULT_MCP_ENABLED_TOOLS: list[str] | None = None  # None = all tools enabled
-DEFAULT_ENABLE_BANK_CONFIG_API = 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
 DEFAULT_RECALL_CONNECTION_BUDGET = 4  # Max concurrent DB connections per recall operation
+DEFAULT_MCP_LOCAL_BANK_ID = "mcp"
 DEFAULT_MENTAL_MODEL_REFRESH_CONCURRENCY = 8  # Max concurrent mental model refreshes

 # Retain settings
@@ -433,36 +358,12 @@ DEFAULT_RETAIN_CHUNK_SIZE = 3000  # Max chars per chunk for fact extraction
 DEFAULT_RETAIN_EXTRACT_CAUSAL_LINKS = True  # Extract causal links between facts
 DEFAULT_RETAIN_EXTRACTION_MODE = "concise"  # Extraction mode: "concise", "verbose", or "custom"
 RETAIN_EXTRACTION_MODES = ("concise", "verbose", "custom")  # Allowed extraction modes
-DEFAULT_RETAIN_MISSION = None  # Declarative spec of what to retain (injected into any extraction mode)
 DEFAULT_RETAIN_CUSTOM_INSTRUCTIONS = None  # Custom extraction guidelines (only used when mode="custom")
-DEFAULT_RETAIN_BATCH_TOKENS = 10_000  # ~40KB of text  # Max chars per sub-batch for async retain auto-splitting
-DEFAULT_RETAIN_ENTITY_LOOKUP = "trigram"  # "full" or "trigram"
-DEFAULT_RETAIN_BATCH_ENABLED = False  # Use LLM Batch API for fact extraction (only when async=True)
-DEFAULT_RETAIN_BATCH_POLL_INTERVAL_SECONDS = 60  # Batch API polling interval in seconds
-
-# File storage defaults
-DEFAULT_FILE_STORAGE_TYPE = "native"  # PostgreSQL BYTEA storage
-DEFAULT_FILE_PARSER = "markitdown"  # Default parser fallback chain (comma-separated, e.g. "iris,markitdown")
-DEFAULT_FILE_PARSER_ALLOWLIST = None  # Allowlist of parsers clients may request (None = all registered parsers)
-DEFAULT_FILE_CONVERSION_MAX_BATCH_SIZE_MB = 100  # Max total batch size in MB (all files combined)
-DEFAULT_FILE_CONVERSION_MAX_BATCH_SIZE = 10  # Max files per batch upload
-DEFAULT_ENABLE_FILE_UPLOAD_API = True  # Enable file upload endpoint
-DEFAULT_FILE_DELETE_AFTER_RETAIN = True  # Delete file bytes after retain (saves storage)

 # Observations defaults (consolidated knowledge from facts)
 DEFAULT_ENABLE_OBSERVATIONS = True  # Observations enabled by default
-DEFAULT_ENABLE_OBSERVATION_HISTORY = True  # Observation history tracking enabled by default
-DEFAULT_ENABLE_MENTAL_MODEL_HISTORY = True  # Mental model history tracking enabled by default
 DEFAULT_CONSOLIDATION_BATCH_SIZE = 50  # Memories to load per batch (internal memory optimization)
-DEFAULT_CONSOLIDATION_LLM_BATCH_SIZE = 8  # Facts per LLM call (1 = no batching; >1 = batch mode)
-DEFAULT_CONSOLIDATION_MAX_TOKENS = 512  # Max tokens for recall when finding related observations
-DEFAULT_CONSOLIDATION_SOURCE_FACTS_MAX_TOKENS = (
-    -1
-)  # Total token budget for source facts in consolidation recall (-1 = unlimited)
-DEFAULT_CONSOLIDATION_SOURCE_FACTS_MAX_TOKENS_PER_OBSERVATION = (
-    256  # Max tokens of source facts per observation in consolidation prompt (-1 = unlimited)
-)
-DEFAULT_OBSERVATIONS_MISSION = None  # Declarative spec of what observations are for this bank
+DEFAULT_CONSOLIDATION_MAX_TOKENS = 1024  # Max tokens for recall when finding related observations

 # Database migrations
 DEFAULT_RUN_MIGRATIONS_ON_STARTUP = True
@@ -484,12 +385,6 @@ DEFAULT_WORKER_CONSOLIDATION_MAX_SLOTS = 2  # Max concurrent consolidation tasks

 # Reflect agent settings
 DEFAULT_REFLECT_MAX_ITERATIONS = 10  # Max tool call iterations before forcing response
-DEFAULT_REFLECT_MAX_CONTEXT_TOKENS = 100_000  # Max accumulated context tokens before forcing final prompt
-
-# Disposition defaults (None = not set, fall back to bank DB value or 3)
-DEFAULT_DISPOSITION_SKEPTICISM = None
-DEFAULT_DISPOSITION_LITERALISM = None
-DEFAULT_DISPOSITION_EMPATHY = None

 # OpenTelemetry tracing configuration
 DEFAULT_OTEL_TRACES_ENABLED = False  # Disabled by default for backward compatibility
@@ -519,12 +414,6 @@ Use this tool PROACTIVELY to:
 # Default embedding dimension (used by initial migration, adjusted at runtime)
 EMBEDDING_DIMENSION = DEFAULT_EMBEDDING_DIMENSION

-# Webhook configuration defaults
-DEFAULT_WEBHOOK_URL = None  # None = no global webhook configured
-DEFAULT_WEBHOOK_SECRET = None  # None = no signing
-DEFAULT_WEBHOOK_EVENT_TYPES = "consolidation.completed"  # Comma-separated; default = all supported events
-DEFAULT_WEBHOOK_DELIVERY_POLL_INTERVAL_SECONDS = 30  # How often to poll for pending deliveries
-

 class JsonFormatter(logging.Formatter):
    """JSON formatter for structured logging.
@@ -556,11 +445,6 @@ class JsonFormatter(logging.Formatter):
        return json.dumps(log_entry)


-def _parse_str_list(value: str) -> list[str]:
-    """Parse a comma-separated string into a non-empty list of stripped tokens."""
-    return [v.strip() for v in value.split(",") if v.strip()]
-
-
 def _validate_extraction_mode(mode: str) -> str:
    """Validate and normalize extraction mode."""
    mode_lower = mode.lower()
@@ -598,17 +482,12 @@ class HindsightConfig:
    llm_initial_backoff: float
    llm_max_backoff: float
    llm_timeout: float
-    llm_groq_service_tier: str  # Groq: "on_demand", "flex", or "auto"
-    llm_openai_service_tier: str | None  # OpenAI: None (default) or "flex" (50% cheaper)

    # Vertex AI configuration
    llm_vertexai_project_id: str | None
    llm_vertexai_region: str
    llm_vertexai_service_account_key: str | None

-    # Gemini safety settings (None = use Gemini defaults; list of dicts with category/threshold)
-    llm_gemini_safety_settings: list | None
-
    # Per-operation LLM configuration (None = use default LLM config)
    retain_llm_provider: str | None
    retain_llm_api_key: str | None
@@ -653,9 +532,6 @@ 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
@@ -673,11 +549,6 @@ 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
-    reranker_zeroentropy_api_key: str | None
-    reranker_zeroentropy_model: str

    # Server
    host: str
@@ -686,7 +557,6 @@ class HindsightConfig:
    log_level: str
    log_format: str
    mcp_enabled: bool
-    mcp_enabled_tools: list[str] | None  # None = all tools; explicit list = allowlist
    enable_bank_config_api: bool

    # Recall
@@ -701,59 +571,12 @@ class HindsightConfig:
    retain_chunk_size: int
    retain_extract_causal_links: bool
    retain_extraction_mode: str
-    retain_mission: str | None
    retain_custom_instructions: str | None
-    retain_batch_tokens: int
-    retain_batch_enabled: bool
-    retain_batch_poll_interval_seconds: int
-    retain_entity_lookup: str  # "full" or "trigram"
-
-    # File storage (static - server-level only)
-    file_storage_type: str  # "native" (PostgreSQL) or "s3" (S3-compatible)
-    file_storage_s3_bucket: str | None  # S3 bucket name (required for s3 storage)
-    file_storage_s3_region: str | None  # S3 region (optional, uses SDK default)
-    file_storage_s3_endpoint: str | None  # S3 endpoint URL (for MinIO, R2, etc.)
-    file_storage_s3_access_key_id: str | None  # S3 access key (optional, uses env/IAM)
-    file_storage_s3_secret_access_key: str | None  # S3 secret key (optional, uses env/IAM)
-    file_storage_gcs_bucket: str | None  # GCS bucket name (required for gcs storage)
-    file_storage_gcs_service_account_key: str | None  # GCS service account key JSON (optional, uses ADC)
-    file_storage_azure_container: str | None  # Azure container name (required for azure storage)
-    file_storage_azure_account_name: str | None  # Azure storage account name
-    file_storage_azure_account_key: str | None  # Azure storage account key
-    file_parser: list[str]  # Ordered fallback chain of parsers (e.g. ["iris", "markitdown"])
-    file_parser_allowlist: list[str] | None  # Parsers clients may request (None = all registered)
-    file_parser_iris_token: str | None  # Vectorize API token for iris parser (VECTORIZE_TOKEN)
-    file_parser_iris_org_id: str | None  # Vectorize org ID for iris parser (VECTORIZE_ORG_ID)
-    file_conversion_max_batch_size_mb: int  # Max total batch size in MB (all files combined)
-    file_conversion_max_batch_size: int  # Max files per request
-    enable_file_upload_api: bool
-    file_delete_after_retain: bool

    # Observations settings (consolidated knowledge from facts)
    enable_observations: bool
-    enable_observation_history: bool
-    enable_mental_model_history: bool
    consolidation_batch_size: int
-    consolidation_llm_batch_size: int
    consolidation_max_tokens: int
-    consolidation_source_facts_max_tokens: int
-    consolidation_source_facts_max_tokens_per_observation: int
-    observations_mission: str | None
-
-    # Entity labels (controlled vocabulary of key:value classification labels extracted at retain time)
-    # List of label group dicts: [{key, description, type, optional, values: [{value, description}]}]
-    entity_labels: list | None
-    # Whether to extract regular named entities alongside entity labels (default: True)
-    # When False: only label entities are extracted (or no entities at all if no labels configured)
-    entities_allow_free_form: bool
-
-    # Reflect agent settings
-    reflect_mission: str | None
-
-    # Disposition settings (hierarchical - can be overridden per bank; None = fall back to DB)
-    disposition_skepticism: int | None
-    disposition_literalism: int | None
-    disposition_empathy: int | None

    # Optimization flags
    skip_llm_verification: bool
@@ -779,7 +602,6 @@ class HindsightConfig:

    # Reflect agent settings
    reflect_max_iterations: int
-    reflect_max_context_tokens: int

    # OpenTelemetry tracing configuration
    otel_traces_enabled: bool
@@ -788,12 +610,6 @@ class HindsightConfig:
    otel_service_name: str
    otel_deployment_environment: str

-    # Webhook configuration (static - server-level only, not per-bank)
-    webhook_url: str | None  # Global webhook URL (None = disabled)
-    webhook_secret: str | None  # HMAC signing secret (None = unsigned)
-    webhook_event_types: list[str]  # Event types to deliver globally
-    webhook_delivery_poll_interval_seconds: int  # How often the delivery worker polls
-
    # Class-level sets for configuration categorization

    # CREDENTIAL_FIELDS: Never exposed via API, never configurable per-tenant/bank
@@ -813,50 +629,20 @@ class HindsightConfig:
        "reranker_cohere_base_url",
        # Service Account Keys
        "llm_vertexai_service_account_key",
-        # File storage credentials
-        "file_storage_s3_access_key_id",
-        "file_storage_s3_secret_access_key",
-        "file_storage_gcs_service_account_key",
-        "file_storage_azure_account_key",
-        # File parser credentials
-        "file_parser_iris_token",
    }

    # 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 = {
-        # MCP tool access control
-        "mcp_enabled_tools",
        # Retention settings (behavioral)
        "retain_chunk_size",
        "retain_extraction_mode",
-        "retain_mission",
        "retain_custom_instructions",
-        # Entity labels (controlled vocabulary for entity classification)
-        "entity_labels",
-        "entities_allow_free_form",
        # Consolidation settings
        "enable_observations",
-        "consolidation_llm_batch_size",
-        "consolidation_source_facts_max_tokens",
-        "consolidation_source_facts_max_tokens_per_observation",
-        "observations_mission",
-        # Reflect settings
-        "reflect_mission",
-        # Disposition settings
-        "disposition_skepticism",
-        "disposition_literalism",
-        "disposition_empathy",
-        # Gemini safety settings (controls content filtering for Gemini/VertexAI providers)
-        "llm_gemini_safety_settings",
    }

-    @property
-    def file_conversion_max_batch_size_bytes(self) -> int:
-        """Get maximum total batch size in bytes."""
-        return self.file_conversion_max_batch_size_mb * 1024 * 1024
-
    @classmethod
    def get_configurable_fields(cls) -> set[str]:
        """
@@ -913,14 +699,14 @@ class HindsightConfig:
    def validate(self) -> None:
        """Validate configuration values and raise errors for invalid combinations."""
        # Validate vector_extension
-        valid_extensions = ("pgvector", "vchord", "pgvectorscale")
+        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")
+        valid_text_search = ("native", "vchord")
        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)}"
@@ -963,15 +749,11 @@ class HindsightConfig:
            llm_initial_backoff=float(os.getenv(ENV_LLM_INITIAL_BACKOFF, str(DEFAULT_LLM_INITIAL_BACKOFF))),
            llm_max_backoff=float(os.getenv(ENV_LLM_MAX_BACKOFF, str(DEFAULT_LLM_MAX_BACKOFF))),
            llm_timeout=float(os.getenv(ENV_LLM_TIMEOUT, str(DEFAULT_LLM_TIMEOUT))),
-            llm_groq_service_tier=os.getenv(ENV_LLM_GROQ_SERVICE_TIER, DEFAULT_LLM_GROQ_SERVICE_TIER),
-            llm_openai_service_tier=os.getenv(ENV_LLM_OPENAI_SERVICE_TIER, DEFAULT_LLM_OPENAI_SERVICE_TIER),
            # Vertex AI
            llm_vertexai_project_id=os.getenv(ENV_LLM_VERTEXAI_PROJECT_ID) or DEFAULT_LLM_VERTEXAI_PROJECT_ID,
            llm_vertexai_region=os.getenv(ENV_LLM_VERTEXAI_REGION, DEFAULT_LLM_VERTEXAI_REGION),
            llm_vertexai_service_account_key=os.getenv(ENV_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY)
            or DEFAULT_LLM_VERTEXAI_SERVICE_ACCOUNT_KEY,
-            # Gemini safety settings (JSON-encoded list of {category, threshold} dicts)
-            llm_gemini_safety_settings=json.loads(os.getenv(ENV_LLM_GEMINI_SAFETY_SETTINGS, "null")),
            # Per-operation LLM config (None = use default)
            retain_llm_provider=os.getenv(ENV_RETAIN_LLM_PROVIDER) or None,
            retain_llm_api_key=os.getenv(ENV_RETAIN_LLM_API_KEY) or None,
@@ -1065,12 +847,6 @@ 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),
@@ -1100,13 +876,6 @@ 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,
-            # ZeroEntropy reranker
-            reranker_zeroentropy_api_key=os.getenv(ENV_RERANKER_ZEROENTROPY_API_KEY),
-            reranker_zeroentropy_model=os.getenv(ENV_RERANKER_ZEROENTROPY_MODEL, DEFAULT_RERANKER_ZEROENTROPY_MODEL),
            # Server
            host=os.getenv(ENV_HOST, DEFAULT_HOST),
            port=int(os.getenv(ENV_PORT, DEFAULT_PORT)),
@@ -1114,9 +883,6 @@ class HindsightConfig:
            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",
-            mcp_enabled_tools=[t.strip() for t in os.getenv(ENV_MCP_ENABLED_TOOLS).split(",") if t.strip()]
-            if os.getenv(ENV_MCP_ENABLED_TOOLS)
-            else DEFAULT_MCP_ENABLED_TOOLS,
            enable_bank_config_api=os.getenv(ENV_ENABLE_BANK_CONFIG_API, str(DEFAULT_ENABLE_BANK_CONFIG_API)).lower()
            == "true",
            # Recall
@@ -1144,76 +910,15 @@ class HindsightConfig:
            retain_extraction_mode=_validate_extraction_mode(
                os.getenv(ENV_RETAIN_EXTRACTION_MODE, DEFAULT_RETAIN_EXTRACTION_MODE)
            ),
-            retain_mission=os.getenv(ENV_RETAIN_MISSION) or DEFAULT_RETAIN_MISSION,
            retain_custom_instructions=os.getenv(ENV_RETAIN_CUSTOM_INSTRUCTIONS) or DEFAULT_RETAIN_CUSTOM_INSTRUCTIONS,
-            retain_batch_tokens=int(os.getenv(ENV_RETAIN_BATCH_TOKENS, str(DEFAULT_RETAIN_BATCH_TOKENS))),
-            retain_entity_lookup=os.getenv(ENV_RETAIN_ENTITY_LOOKUP, DEFAULT_RETAIN_ENTITY_LOOKUP),
-            retain_batch_enabled=os.getenv(ENV_RETAIN_BATCH_ENABLED, str(DEFAULT_RETAIN_BATCH_ENABLED)).lower()
-            == "true",
-            retain_batch_poll_interval_seconds=int(
-                os.getenv(ENV_RETAIN_BATCH_POLL_INTERVAL_SECONDS, str(DEFAULT_RETAIN_BATCH_POLL_INTERVAL_SECONDS))
-            ),
-            # File storage
-            file_storage_type=os.getenv(ENV_FILE_STORAGE_TYPE, DEFAULT_FILE_STORAGE_TYPE),
-            file_storage_s3_bucket=os.getenv(ENV_FILE_STORAGE_S3_BUCKET) or None,
-            file_storage_s3_region=os.getenv(ENV_FILE_STORAGE_S3_REGION) or None,
-            file_storage_s3_endpoint=os.getenv(ENV_FILE_STORAGE_S3_ENDPOINT) or None,
-            file_storage_s3_access_key_id=os.getenv(ENV_FILE_STORAGE_S3_ACCESS_KEY_ID) or None,
-            file_storage_s3_secret_access_key=os.getenv(ENV_FILE_STORAGE_S3_SECRET_ACCESS_KEY) or None,
-            file_storage_gcs_bucket=os.getenv(ENV_FILE_STORAGE_GCS_BUCKET) or None,
-            file_storage_gcs_service_account_key=os.getenv(ENV_FILE_STORAGE_GCS_SERVICE_ACCOUNT_KEY) or None,
-            file_storage_azure_container=os.getenv(ENV_FILE_STORAGE_AZURE_CONTAINER) or None,
-            file_storage_azure_account_name=os.getenv(ENV_FILE_STORAGE_AZURE_ACCOUNT_NAME) or None,
-            file_storage_azure_account_key=os.getenv(ENV_FILE_STORAGE_AZURE_ACCOUNT_KEY) or None,
-            file_parser=_parse_str_list(os.getenv(ENV_FILE_PARSER, DEFAULT_FILE_PARSER)),
-            file_parser_allowlist=_parse_str_list(os.getenv(ENV_FILE_PARSER_ALLOWLIST))
-            if os.getenv(ENV_FILE_PARSER_ALLOWLIST)
-            else None,
-            file_parser_iris_token=os.getenv(ENV_FILE_PARSER_IRIS_TOKEN) or None,
-            file_parser_iris_org_id=os.getenv(ENV_FILE_PARSER_IRIS_ORG_ID) or None,
-            file_conversion_max_batch_size_mb=int(
-                os.getenv(ENV_FILE_CONVERSION_MAX_BATCH_SIZE_MB, str(DEFAULT_FILE_CONVERSION_MAX_BATCH_SIZE_MB))
-            ),
-            file_conversion_max_batch_size=int(
-                os.getenv(ENV_FILE_CONVERSION_MAX_BATCH_SIZE, str(DEFAULT_FILE_CONVERSION_MAX_BATCH_SIZE))
-            ),
-            enable_file_upload_api=os.getenv(ENV_ENABLE_FILE_UPLOAD_API, str(DEFAULT_ENABLE_FILE_UPLOAD_API)).lower()
-            == "true",
-            file_delete_after_retain=os.getenv(
-                ENV_FILE_DELETE_AFTER_RETAIN, str(DEFAULT_FILE_DELETE_AFTER_RETAIN)
-            ).lower()
-            == "true",
            # Observations settings (consolidated knowledge from facts)
            enable_observations=os.getenv(ENV_ENABLE_OBSERVATIONS, str(DEFAULT_ENABLE_OBSERVATIONS)).lower() == "true",
-            enable_observation_history=os.getenv(
-                ENV_ENABLE_OBSERVATION_HISTORY, str(DEFAULT_ENABLE_OBSERVATION_HISTORY)
-            ).lower()
-            == "true",
-            enable_mental_model_history=os.getenv(
-                ENV_ENABLE_MENTAL_MODEL_HISTORY, str(DEFAULT_ENABLE_MENTAL_MODEL_HISTORY)
-            ).lower()
-            == "true",
            consolidation_batch_size=int(
                os.getenv(ENV_CONSOLIDATION_BATCH_SIZE, str(DEFAULT_CONSOLIDATION_BATCH_SIZE))
            ),
-            consolidation_llm_batch_size=int(
-                os.getenv(ENV_CONSOLIDATION_LLM_BATCH_SIZE, str(DEFAULT_CONSOLIDATION_LLM_BATCH_SIZE))
-            ),
            consolidation_max_tokens=int(
                os.getenv(ENV_CONSOLIDATION_MAX_TOKENS, str(DEFAULT_CONSOLIDATION_MAX_TOKENS))
            ),
-            consolidation_source_facts_max_tokens=int(
-                os.getenv(ENV_CONSOLIDATION_SOURCE_FACTS_MAX_TOKENS, str(DEFAULT_CONSOLIDATION_SOURCE_FACTS_MAX_TOKENS))
-            ),
-            consolidation_source_facts_max_tokens_per_observation=int(
-                os.getenv(
-                    ENV_CONSOLIDATION_SOURCE_FACTS_MAX_TOKENS_PER_OBSERVATION,
-                    str(DEFAULT_CONSOLIDATION_SOURCE_FACTS_MAX_TOKENS_PER_OBSERVATION),
-                )
-            ),
-            observations_mission=os.getenv(ENV_OBSERVATIONS_MISSION) or DEFAULT_OBSERVATIONS_MISSION,
-            entity_labels=None,
-            entities_allow_free_form=True,
            # Database migrations
            run_migrations_on_startup=os.getenv(ENV_RUN_MIGRATIONS_ON_STARTUP, "true").lower() == "true",
            # Database connection pool
@@ -1233,20 +938,6 @@ class HindsightConfig:
            ),
            # Reflect agent settings
            reflect_max_iterations=int(os.getenv(ENV_REFLECT_MAX_ITERATIONS, str(DEFAULT_REFLECT_MAX_ITERATIONS))),
-            reflect_max_context_tokens=int(
-                os.getenv(ENV_REFLECT_MAX_CONTEXT_TOKENS, str(DEFAULT_REFLECT_MAX_CONTEXT_TOKENS))
-            ),
-            reflect_mission=os.getenv(ENV_REFLECT_MISSION) or None,
-            # Disposition settings (None = fall back to DB value)
-            disposition_skepticism=int(os.getenv(ENV_DISPOSITION_SKEPTICISM))
-            if os.getenv(ENV_DISPOSITION_SKEPTICISM)
-            else DEFAULT_DISPOSITION_SKEPTICISM,
-            disposition_literalism=int(os.getenv(ENV_DISPOSITION_LITERALISM))
-            if os.getenv(ENV_DISPOSITION_LITERALISM)
-            else DEFAULT_DISPOSITION_LITERALISM,
-            disposition_empathy=int(os.getenv(ENV_DISPOSITION_EMPATHY))
-            if os.getenv(ENV_DISPOSITION_EMPATHY)
-            else DEFAULT_DISPOSITION_EMPATHY,
            # OpenTelemetry tracing configuration
            otel_traces_enabled=os.getenv(ENV_OTEL_TRACES_ENABLED, str(DEFAULT_OTEL_TRACES_ENABLED)).lower()
            in ("true", "1", "yes"),
@@ -1254,20 +945,6 @@ class HindsightConfig:
            otel_exporter_otlp_headers=os.getenv(ENV_OTEL_EXPORTER_OTLP_HEADERS) or None,
            otel_service_name=os.getenv(ENV_OTEL_SERVICE_NAME, DEFAULT_OTEL_SERVICE_NAME),
            otel_deployment_environment=os.getenv(ENV_OTEL_DEPLOYMENT_ENVIRONMENT, DEFAULT_OTEL_DEPLOYMENT_ENVIRONMENT),
-            # Webhook configuration (static, server-level only)
-            webhook_url=os.getenv(ENV_WEBHOOK_URL) or DEFAULT_WEBHOOK_URL,
-            webhook_secret=os.getenv(ENV_WEBHOOK_SECRET) or DEFAULT_WEBHOOK_SECRET,
-            webhook_event_types=[
-                t.strip()
-                for t in os.getenv(ENV_WEBHOOK_EVENT_TYPES, DEFAULT_WEBHOOK_EVENT_TYPES).split(",")
-                if t.strip()
-            ],
-            webhook_delivery_poll_interval_seconds=int(
-                os.getenv(
-                    ENV_WEBHOOK_DELIVERY_POLL_INTERVAL_SECONDS,
-                    str(DEFAULT_WEBHOOK_DELIVERY_POLL_INTERVAL_SECONDS),
-                )
-            ),
        )
        config.validate()
        return config
@@ -16,7 +16,6 @@ from typing import Any
 import asyncpg

 from hindsight_api.config import HindsightConfig, _get_raw_config, normalize_config_dict
-from hindsight_api.engine.memory_engine import fq_table
 from hindsight_api.extensions.tenant import TenantExtension
 from hindsight_api.models import RequestContext

@@ -150,8 +149,8 @@ class ConfigResolver:
        try:
            async with self.pool.acquire() as conn:
                row = await conn.fetchrow(
-                    f"""
-                    SELECT config FROM {fq_table("banks")} WHERE bank_id = $1
+                    """
+                    SELECT config FROM banks WHERE bank_id = $1
                    """,
                    bank_id,
                )
@@ -242,8 +241,8 @@ class ConfigResolver:
        # Merge with existing config (JSONB || operator)
        async with self.pool.acquire() as conn:
            await conn.execute(
-                f"""
-                UPDATE {fq_table("banks")}
+                """
+                UPDATE banks
                SET config = config || $1::jsonb,
                    updated_at = now()
                WHERE bank_id = $2
@@ -263,9 +262,9 @@ class ConfigResolver:
        """
        async with self.pool.acquire() as conn:
            await conn.execute(
-                f"""
-                UPDATE {fq_table("banks")}
-                SET config = '{{}}'::jsonb,
+                """
+                UPDATE banks
+                SET config = '{}'::jsonb,
                    updated_at = now()
                WHERE bank_id = $1
                """,
@@ -1,83 +1,85 @@
 """Prompts for the consolidation engine."""

-# Default mission when no bank-specific mission is set
-_DEFAULT_MISSION = "Track every detail: names, numbers, dates, places, and relationships. Prefer specifics over abstractions, never generalise."
+CONSOLIDATION_SYSTEM_PROMPT = """You are a memory consolidation system. Your job is to convert facts into durable knowledge (observations) and merge with existing knowledge when appropriate.

-# Processing rules — always present regardless of mission
-_PROCESSING_RULES = """Processing rules (always apply):
- REDUNDANT: same info worded differently → UPDATE the existing observation.
- CONTRADICTION/UPDATE: capture both states with temporal markers ("used to X, now Y").
- RESOLVE REFERENCES: when a new fact provides a concrete value resolving a vague placeholder in an existing observation (e.g. "home country", "hometown", "birthplace", "native language", "her ex", "that city"), UPDATE the observation to embed the resolved value explicitly. Example: new fact says "grandma in Sweden" + existing observation says "moved from her home country" → update to "home country is Sweden".
- NEVER merge observations about different people or unrelated topics."""
+You must output ONLY valid JSON with no markdown code blocks or additional text. However, the "text" field within each observation should use markdown formatting (headers, lists, bold, etc.) for clarity and readability.

-# Data section — format placeholders {facts_text} and {observations_text} are substituted at call time
-_BATCH_DATA_SECTION = """
-NEW FACTS:
-{facts_text}
+## EXTRACT DURABLE KNOWLEDGE, NOT EPHEMERAL STATE
+Facts often describe events or actions. Extract the DURABLE KNOWLEDGE implied by the fact, not the transient state.

-EXISTING OBSERVATIONS (JSON array, pooled from recalls across all facts above):
+Examples of extracting durable knowledge:
+- "User moved to Room 203" -> "Room 203 exists" (location exists, not where user is now)
+- "User visited Acme Corp at Room 105" -> "Acme Corp is located in Room 105"
+- "User took the elevator to floor 3" -> "Floor 3 is accessible by elevator"
+- "User met Sarah at the lobby" -> "Sarah can be found at the lobby"
+
+DO NOT track current user position/state as knowledge - that changes constantly.
+DO track permanent facts learned from the user's actions.
+
+## PRESERVE SPECIFIC DETAILS
+Keep names, locations, numbers, and other specifics. Do NOT:
+- Abstract into general principles
+- Generate business insights
+- Make knowledge generic
+
+GOOD examples:
+- Fact: "John likes pizza" -> "John likes pizza"
+- Fact: "Alice works at Google" -> "Alice works at Google"
+
+BAD examples:
+- "John likes pizza" -> "Understanding dietary preferences helps..." (TOO ABSTRACT)
+- "User is at Room 203" -> "User is currently at Room 203" (EPHEMERAL STATE)
+
+## MERGE RULES (when comparing to existing observations):
+1. REDUNDANT: Same information worded differently → update existing
+2. CONTRADICTION: Opposite information about same topic → update with temporal markers showing change
+   Example: "Alex used to love pizza but now hates it" OR "Alex's pizza preference changed from love to hate"
+3. UPDATE: New state replacing old state → update showing the transition with "used to", "now", "changed from X to Y"
+
+## CRITICAL RULES:
+- NEVER merge facts about DIFFERENT people
+- NEVER merge unrelated topics (food preferences vs work vs hobbies)
+- When merging contradictions, the "text" field MUST capture BOTH states with temporal markers:
+  * Use "used to X, now Y" OR "changed from X to Y" OR "X but now Y"
+  * DO NOT just state the new fact - you MUST show the change
+- Keep observations focused on ONE specific topic per person
+- The "text" field MUST contain durable knowledge, not ephemeral state
+- Do NOT include "tags" in output - tags are handled automatically"""
+
+CONSOLIDATION_USER_PROMPT = """Analyze this new fact and consolidate into knowledge.
+{mission_section}
+NEW FACT: {fact_text}
+
+EXISTING OBSERVATIONS (JSON array with source memories and dates):
 {observations_text}

 Each observation includes:
 - id: unique identifier for updating
 - text: the observation content
 - proof_count: number of supporting memories
+- tags: visibility scope (handled automatically)
+- created_at/updated_at: when observation was created/modified
 - occurred_start/occurred_end: temporal range of source facts
 - source_memories: array of supporting facts with their text and dates

-Compare the facts against existing observations:
- Same topic as an existing observation → UPDATE it (observation_id + source_fact_ids)
- New topic with durable knowledge → CREATE a new observation (source_fact_ids)
- Cross-reference facts within the batch: a later fact may resolve a vague reference in an earlier one
- Purely ephemeral facts → omit them (no create/update needed)"""
+Instructions:
+1. Extract DURABLE KNOWLEDGE from the new fact (not ephemeral state)
+2. Review source_memories in existing observations to understand evidence
+3. Check dates to detect contradictions or updates
+4. Compare with observations:
+   - Same topic → UPDATE with learning_id
+   - New topic → CREATE new observation
+   - Purely ephemeral → return []

-# Output format — JSON braces escaped as {{ }} so .format() leaves them literal
-_BATCH_OUTPUT_FORMAT = """
-Output a JSON object with three arrays.
+Output JSON array of actions (the "text" field should use markdown formatting for structure):
+[
+  {{"action": "update", "learning_id": "uuid-from-observations", "text": "## Updated Knowledge\n\n**Key point**: details here\n\n- Supporting detail 1\n- Supporting detail 2", "reason": "..."}},
+  {{"action": "create", "text": "## New Durable Knowledge\n\nDescription with **emphasis** and proper structure", "reason": "..."}}
+]

-## EXAMPLE
+Return [] if fact contains no durable knowledge.

-Input facts:
-[a1b2c3d4-e5f6-7890-abcd-ef1234567890] Alice mentioned she works long hours, often past midnight | Involving: Alice (occurred_start=2024-01-15, mentioned_at=2024-01-15)
-[b2c3d4e5-f6a7-8901-bcde-f12345678901] Alice said she's exhausted from the project deadlines | Involving: Alice (occurred_start=2024-01-20, mentioned_at=2024-01-20)
-
-Good observation text — clean prose, no metadata, each fact tracked distinctly:
-  "Alice works long hours, often past midnight."
-  "Alice feels exhausted from project deadlines."
-
-Bad observation text — NEVER do this (verbatim copy of fact text with metadata):
-  "Alice mentioned she works long hours, often past midnight | Involving: Alice (occurred_start=2024-01-15, mentioned_at=2024-01-15)"
-
-Observation text rules:
- Write clean prose — NEVER copy raw fact lines or their metadata (temporal fields, "Involving:", "When:" labels, UUIDs).
- Parenthesized metadata like (occurred_start=...) and pipe-separated labels like "| Involving: ..." are fact formatting — strip them entirely from observation text.
- How many observations to create and how much to aggregate is driven by the MISSION above.
-
-{{"creates": [{{"text": "Alice works long hours, often past midnight.", "source_fact_ids": ["a1b2c3d4-e5f6-7890-abcd-ef1234567890"]}}, {{"text": "Alice feels exhausted from project deadlines.", "source_fact_ids": ["b2c3d4e5-f6a7-8901-bcde-f12345678901"]}}],
-  "updates": [{{"text": "Alice works at Acme Corp as a senior engineer", "observation_id": "c3d4e5f6-a7b8-9012-cdef-123456789012", "source_fact_ids": ["d4e5f6a7-b8c9-0123-defa-234567890123"]}}],
-  "deletes": [{{"observation_id": "e5f6a7b8-c9d0-1234-efab-345678901234"}}]}}
-
-Rules:
- "source_fact_ids": copy the EXACT UUID strings shown in brackets [uuid] from NEW FACTS — never use integers or positions.
- "observation_id": copy the EXACT "id" UUID string from EXISTING OBSERVATIONS.
- One create/update may reference multiple facts when they jointly support the observation.
- "deletes": only when an observation is directly superseded or contradicted by new facts.
- Do NOT include "tags" — handled automatically.
- Return {{"creates": [], "updates": [], "deletes": []}} if nothing durable is found."""
-
-
-def build_batch_consolidation_prompt(observations_mission: str | None = None) -> str:
-    """
-    Build the consolidation prompt for batch mode (multiple facts per LLM call).
-
-    The mission defines *what* to track (customisable per bank).
-    Processing rules and output format are always present regardless of mission.
-    """
-    mission = observations_mission or _DEFAULT_MISSION
-
-    return (
-        "You are a memory consolidation system. Synthesize facts into observations "
-        "and merge with existing observations when appropriate.\n\n"
-        f"## MISSION\n{mission}\n\n"
-        f"{_PROCESSING_RULES}" + _BATCH_DATA_SECTION + _BATCH_OUTPUT_FORMAT
-    )
+IMPORTANT: Format the "text" field with markdown for better readability:
+- Use headers, lists, bold/italic, tables where appropriate
+- CRITICAL: Add blank lines before and after block elements (tables, code blocks, lists)
+- Ensure proper spacing for markdown to render correctly"""
@@ -21,7 +21,6 @@ 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,
@@ -29,12 +28,10 @@ from ..config import (
    DEFAULT_RERANKER_PROVIDER,
    DEFAULT_RERANKER_TEI_BATCH_SIZE,
    DEFAULT_RERANKER_TEI_MAX_CONCURRENT,
-    DEFAULT_RERANKER_ZEROENTROPY_MODEL,
    ENV_RERANKER_COHERE_API_KEY,
    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,
@@ -43,7 +40,6 @@ from ..config import (
    ENV_RERANKER_TEI_BATCH_SIZE,
    ENV_RERANKER_TEI_MAX_CONCURRENT,
    ENV_RERANKER_TEI_URL,
-    ENV_RERANKER_ZEROENTROPY_API_KEY,
 )

 logger = logging.getLogger(__name__)
@@ -558,104 +554,6 @@ class CohereCrossEncoder(CrossEncoderModel):
        return all_scores


-class ZeroEntropyCrossEncoder(CrossEncoderModel):
-    """
-    ZeroEntropy cross-encoder implementation using the ZeroEntropy Rerank API.
-
-    Supports zerank-2 (flagship) and zerank-2-small models.
-    See: https://docs.zeroentropy.dev/models
-    """
-
-    RERANK_URL = "https://api.zeroentropy.dev/v1/models/rerank"
-
-    def __init__(
-        self,
-        api_key: str,
-        model: str = DEFAULT_RERANKER_ZEROENTROPY_MODEL,
-        timeout: float = 60.0,
-    ):
-        """
-        Initialize ZeroEntropy cross-encoder client.
-
-        Args:
-            api_key: ZeroEntropy API key
-            model: ZeroEntropy rerank model name (default: zerank-2)
-            timeout: Request timeout in seconds (default: 60.0)
-        """
-        self.api_key = api_key
-        self.model = model
-        self.timeout = timeout
-        self._async_client: httpx.AsyncClient | None = None
-
-    @property
-    def provider_name(self) -> str:
-        return "zeroentropy"
-
-    async def initialize(self) -> None:
-        """Initialize the async HTTP client."""
-        if self._async_client is not None:
-            return
-
-        logger.info(f"Reranker: initializing ZeroEntropy provider with model {self.model}")
-        self._async_client = httpx.AsyncClient(
-            timeout=self.timeout,
-            headers={
-                "Authorization": f"Bearer {self.api_key}",
-                "Content-Type": "application/json",
-            },
-        )
-        logger.info("Reranker: ZeroEntropy provider initialized")
-
-    async def predict(self, pairs: list[tuple[str, str]]) -> list[float]:
-        """
-        Score query-document pairs using the ZeroEntropy Rerank API.
-
-        Args:
-            pairs: List of (query, document) tuples to score
-
-        Returns:
-            List of relevance scores
-        """
-        if self._async_client is None:
-            raise RuntimeError("Reranker not initialized. Call initialize() first.")
-
-        if not pairs:
-            return []
-
-        # Group pairs by query for efficient batching
-        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]
-
-            response = await self._async_client.post(
-                self.RERANK_URL,
-                json={
-                    "model": self.model,
-                    "query": query,
-                    "documents": texts,
-                    "top_n": len(texts),
-                },
-            )
-            response.raise_for_status()
-            result = response.json()
-
-            # Map scores back to original positions
-            for item in result.get("results", []):
-                original_idx = item["index"]
-                score = item["relevance_score"]
-                all_scores[indices[original_idx]] = score
-
-        return all_scores
-
-
 class RRFPassthroughCrossEncoder(CrossEncoderModel):
    """
    Passthrough cross-encoder that preserves RRF scores without neural reranking.
@@ -930,126 +828,6 @@ 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.
@@ -1099,30 +877,9 @@ 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 == "zeroentropy":
-        api_key = config.reranker_zeroentropy_api_key
-        if not api_key:
-            raise ValueError(
-                f"{ENV_RERANKER_ZEROENTROPY_API_KEY} is required when {ENV_RERANKER_PROVIDER} is 'zeroentropy'"
-            )
-        return ZeroEntropyCrossEncoder(
-            api_key=api_key,
-            model=config.reranker_zeroentropy_model,
-        )
    elif provider == "rrf":
        return RRFPassthroughCrossEncoder()
    else:
        raise ValueError(
-            f"Unknown reranker provider: {provider}. Supported: 'local', 'tei', 'cohere', 'zeroentropy', 'flashrank', 'litellm', 'litellm-sdk', 'rrf'"
+            f"Unknown reranker provider: {provider}. Supported: 'local', 'tei', 'cohere', 'flashrank', 'litellm', 'rrf'"
        )
@@ -20,7 +20,6 @@ RETRYABLE_EXCEPTIONS = (
    asyncpg.exceptions.InterfaceError,
    asyncpg.exceptions.ConnectionDoesNotExistError,
    asyncpg.exceptions.TooManyConnectionsError,
-    asyncpg.exceptions.DeadlockDetectedError,
    OSError,
    ConnectionError,
    asyncio.TimeoutError,
@@ -19,7 +19,6 @@ 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,
@@ -27,7 +26,6 @@ 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,
@@ -722,150 +720,6 @@ 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,
-                "encoding_format": "float",
-            }
-            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,
-                    "encoding_format": "float",
-                }
-                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.
@@ -917,19 +771,7 @@ 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}. "
-            f"Supported: 'local', 'tei', 'openai', 'cohere', 'litellm', 'litellm-sdk'"
+            f"Unknown embeddings provider: {provider}. Supported: 'local', 'tei', 'openai', 'cohere', 'litellm'"
        )
@@ -5,10 +5,6 @@ Uses spaCy for entity extraction and implements resolution logic
 to disambiguate entities across memory units.
 """

-import asyncio
-import logging
-from collections import defaultdict
-from dataclasses import dataclass, field
 from datetime import UTC, datetime
 from difflib import SequenceMatcher

@@ -16,43 +12,6 @@ import asyncpg

 from .db_utils import acquire_with_retry
 from .memory_engine import fq_table
-from .retain.entity_labels import build_labels_lookup as _build_labels_lookup_from_config
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class _EntityToCreate:
-    """An entity that needs to be inserted (no matching candidate found)."""
-
-    idx: int
-    name: str
-    event_date: datetime | None
-
-
-@dataclass
-class _EntityStat:
-    """Stat accumulation entry for a resolved entity (post-transaction update)."""
-
-    entity_id: str
-    event_date: datetime | None
-
-
-@dataclass
-class _EntityStatAgg:
-    """Aggregated stats used when flushing pending updates."""
-
-    count: int = 0
-    max_date: datetime | None = None
-
-
-@dataclass
-class _CooccurrencePair:
-    """A (entity_id_1, entity_id_2) pair observed in a retain batch (for post-txn flush)."""
-
-    entity_id_1: str
-    entity_id_2: str
-

 # Load spaCy model (singleton)
 _nlp = None
@@ -63,95 +22,14 @@ class EntityResolver:
    Resolves entities to canonical IDs with disambiguation.
    """

-    def __init__(self, pool: asyncpg.Pool, entity_lookup: str = "full"):
+    def __init__(self, pool: asyncpg.Pool):
        """
        Initialize entity resolver.

        Args:
            pool: asyncpg connection pool
-            entity_lookup: Lookup strategy — "full" loads all bank entities then
-                matches in Python; "trigram" uses pg_trgm GIN index to fetch only
-                similar candidates per entity name (much faster for large banks).
        """
        self.pool = pool
-        self.entity_lookup = entity_lookup
-        # Keyed by asyncio task id so concurrent retain batches never mix their
-        # pending updates.  flush_pending_stats() pops only the calling task's items.
-        self._pending_stats: dict[int, list[_EntityStat]] = {}
-        self._pending_cooccurrences: dict[int, list[_CooccurrencePair]] = {}
-
-    def _task_key(self) -> int:
-        """Return a unique key for the current asyncio task (or 0 for non-task context)."""
-        task = asyncio.current_task()
-        return id(task) if task is not None else 0
-
-    async def flush_pending_stats(self) -> None:
-        """
-        Flush accumulated entity stats and co-occurrence counts for the current task.
-
-        Must be called AFTER the retain transaction commits.  Pops only the items
-        accumulated by the calling asyncio task so concurrent retain batches never
-        flush each other's uncommitted entity IDs.
-        """
-        if self.pool is None:
-            return
-
-        key = self._task_key()
-        stats = self._pending_stats.pop(key, [])
-        cooccurrences = self._pending_cooccurrences.pop(key, [])
-
-        if not stats and not cooccurrences:
-            return
-
-        async with acquire_with_retry(self.pool) as conn:
-            if stats:
-                # Aggregate: sum counts and find max date per entity_id.
-                agg: dict[str, _EntityStatAgg] = defaultdict(_EntityStatAgg)
-                for s in stats:
-                    entry = agg[s.entity_id]
-                    entry.count += 1
-                    if s.event_date is not None:
-                        entry.max_date = s.event_date if entry.max_date is None else max(entry.max_date, s.event_date)
-
-                # Sort by entity_id so all concurrent workers acquire row locks in
-                # the same order — prevents circular lock dependencies (deadlocks).
-                rows = sorted((eid, a.count, a.max_date) for eid, a in agg.items())
-                await conn.executemany(
-                    f"""
-                    UPDATE {fq_table("entities")} SET
-                        mention_count = mention_count + $2,
-                        last_seen     = GREATEST(last_seen, $3)
-                    WHERE id = $1::uuid
-                    """,
-                    rows,
-                )
-
-            if cooccurrences:
-                # Aggregate: count occurrences per (entity_id_1, entity_id_2) pair.
-                coo_agg: dict[tuple[str, str], int] = {}
-                for c in cooccurrences:
-                    pair = (c.entity_id_1, c.entity_id_2)
-                    coo_agg[pair] = coo_agg.get(pair, 0) + 1
-
-                now = datetime.now(UTC)
-                # Sort by (entity_id_1, entity_id_2) for consistent lock ordering.
-                await conn.executemany(
-                    f"""
-                    INSERT INTO {fq_table("entity_cooccurrences")}
-                        (entity_id_1, entity_id_2, cooccurrence_count, last_cooccurred)
-                    VALUES ($1, $2, $3, $4)
-                    ON CONFLICT (entity_id_1, entity_id_2)
-                    DO UPDATE SET
-                        cooccurrence_count = {fq_table("entity_cooccurrences")}.cooccurrence_count + EXCLUDED.cooccurrence_count,
-                        last_cooccurred    = GREATEST({fq_table("entity_cooccurrences")}.last_cooccurred, EXCLUDED.last_cooccurred)
-                    """,
-                    sorted((e1, e2, count, now) for (e1, e2), count in coo_agg.items()),
-                )
-
-    @staticmethod
-    def _build_labels_lookup(entity_labels: list | None) -> set[str]:
-        """Build a set of valid 'key:value' entity label strings for fast lookup."""
-        return _build_labels_lookup_from_config(entity_labels)

    async def resolve_entities_batch(
        self,
@@ -160,7 +38,6 @@ class EntityResolver:
        context: str,
        unit_event_date,
        conn=None,
-        entity_labels: list | None = None,
    ) -> list[str]:
        """
        Resolve multiple entities in batch (MUCH faster than sequential).
@@ -181,34 +58,15 @@ class EntityResolver:
        if not entities_data:
            return []

-        taxonomy_lookup = self._build_labels_lookup(entity_labels)
        if conn is None:
            async with acquire_with_retry(self.pool) as conn:
-                return await self._resolve_entities_batch_impl(
-                    conn, bank_id, entities_data, context, unit_event_date, taxonomy_lookup
-                )
+                return await self._resolve_entities_batch_impl(conn, bank_id, entities_data, context, unit_event_date)
        else:
-            return await self._resolve_entities_batch_impl(
-                conn, bank_id, entities_data, context, unit_event_date, taxonomy_lookup
-            )
+            return await self._resolve_entities_batch_impl(conn, bank_id, entities_data, context, unit_event_date)

    async def _resolve_entities_batch_impl(
-        self,
-        conn,
-        bank_id: str,
-        entities_data: list[dict],
-        context: str,
-        unit_event_date,
-        taxonomy_lookup: set[str] | None = None,
+        self, conn, bank_id: str, entities_data: list[dict], context: str, unit_event_date
    ) -> list[str]:
-        if self.entity_lookup == "trigram":
-            return await self._resolve_entities_batch_trigram(conn, bank_id, entities_data, unit_event_date)
-        return await self._resolve_entities_batch_full(conn, bank_id, entities_data, unit_event_date)
-
-    async def _resolve_entities_batch_full(
-        self, conn, bank_id: str, entities_data: list[dict], unit_event_date
-    ) -> list[str]:
-        """Original strategy: load all bank entities then match in Python."""
        # Query ALL candidates for this bank
        all_entities = await conn.fetch(
            f"""
@@ -272,103 +130,10 @@ class EntityResolver:
                    matching.append((ent_id, canonical_name, metadata, last_seen, mention_count))
            all_candidates[entity_text] = matching

-        return await self._resolve_from_candidates(
-            conn, bank_id, entities_data, unit_event_date, all_candidates, cooccurrence_map
-        )
-
-    async def _resolve_entities_batch_trigram(
-        self, conn, bank_id: str, entities_data: list[dict], unit_event_date
-    ) -> list[str]:
-        """
-        Trigram strategy: fetch only similar candidates per entity name using pg_trgm.
-
-        Instead of loading all bank entities (O(N)), uses a GIN trigram index to fetch
-        only the small set of candidates that are textually similar to each input name.
-        Reduces DB data transfer from 165K rows to ~5-20 rows per entity.
-        """
-        entity_texts = list(set(e["text"] for e in entities_data))
-
-        # Fetch candidates for all unique entity texts in a single batched query.
-        # The trigram % operator uses the GIN index; the substring conditions cover
-        # exact prefix/suffix matches that trigrams might miss at low similarity.
-        rows = await conn.fetch(
-            f"""
-            SELECT DISTINCT ON (e.id)
-                e.id, e.canonical_name, e.metadata, e.last_seen, e.mention_count,
-                q.query_text
-            FROM unnest($2::text[]) AS q(query_text)
-            JOIN {fq_table("entities")} e ON (
-                e.bank_id = $1
-                AND (
-                    e.canonical_name % q.query_text
-                    OR LOWER(e.canonical_name) LIKE '%' || LOWER(q.query_text) || '%'
-                    OR LOWER(q.query_text) LIKE '%' || LOWER(e.canonical_name) || '%'
-                )
-            )
-            """,
-            bank_id,
-            entity_texts,
-        )
-
-        # Group candidates by query_text
-        all_candidates: dict[str, list] = {t: [] for t in entity_texts}
-        candidate_ids: set = set()
-        for row in rows:
-            query_text = row["query_text"]
-            all_candidates[query_text].append(
-                (row["id"], row["canonical_name"], row["metadata"], row["last_seen"], row["mention_count"])
-            )
-            candidate_ids.add(row["id"])
-
-        # Fetch co-occurrences only for the candidate entities (not all bank entities)
-        cooccurrence_map: dict[str, set[str]] = {}
-        if candidate_ids:
-            candidate_id_list = list(candidate_ids)
-            cooc_rows = await conn.fetch(
-                f"""
-                SELECT ec.entity_id_1, ec.entity_id_2
-                FROM {fq_table("entity_cooccurrences")} ec
-                WHERE ec.entity_id_1 = ANY($1::uuid[])
-                   OR ec.entity_id_2 = ANY($1::uuid[])
-                """,
-                candidate_id_list,
-            )
-            # Build name lookup for co-occurrence mapping
-            id_to_name = {
-                row["id"]: row["canonical_name"].lower()
-                for cands in all_candidates.values()
-                for row in [{"id": c[0], "canonical_name": c[1]} for c in cands]
-            }
-            for row in cooc_rows:
-                eid1, eid2 = row["entity_id_1"], row["entity_id_2"]
-                if eid1 not in cooccurrence_map:
-                    cooccurrence_map[eid1] = set()
-                if eid2 not in cooccurrence_map:
-                    cooccurrence_map[eid2] = set()
-                if eid2 in id_to_name:
-                    cooccurrence_map[eid1].add(id_to_name[eid2])
-                if eid1 in id_to_name:
-                    cooccurrence_map[eid2].add(id_to_name[eid1])
-
-        return await self._resolve_from_candidates(
-            conn, bank_id, entities_data, unit_event_date, all_candidates, cooccurrence_map
-        )
-
-    async def _resolve_from_candidates(
-        self,
-        conn,
-        bank_id: str,
-        entities_data: list[dict],
-        unit_event_date,
-        all_candidates: dict[str, list],
-        cooccurrence_map: dict[str, set[str]],
-    ) -> list[str]:
-        """Shared scoring + upsert logic used by both lookup strategies."""
-
        # Resolve each entity using pre-fetched candidates
        entity_ids = [None] * len(entities_data)
-        entities_to_update: list[_EntityStat] = []
-        entities_to_create: list[_EntityToCreate] = []
+        entities_to_update = []  # (entity_id, event_date)
+        entities_to_create = []  # (idx, entity_data, event_date)

        for idx, entity_data in enumerate(entities_data):
            entity_text = entity_data["text"]
@@ -380,7 +145,7 @@ class EntityResolver:

            if not candidates:
                # Will create new entity
-                entities_to_create.append(_EntityToCreate(idx=idx, name=entity_text, event_date=entity_event_date))
+                entities_to_create.append((idx, entity_data, entity_event_date))
                continue

            # Score candidates
@@ -424,83 +189,73 @@ class EntityResolver:

            if best_score > threshold:
                entity_ids[idx] = best_candidate
-                entities_to_update.append(_EntityStat(entity_id=best_candidate, event_date=entity_event_date))
+                entities_to_update.append((best_candidate, entity_event_date))
            else:
-                entities_to_create.append(
-                    _EntityToCreate(idx=idx, name=entity_data["text"], event_date=entity_event_date)
-                )
+                entities_to_create.append((idx, entity_data, entity_event_date))

-        # Existing entities: IDs already known from the candidate SELECT above.
-        # No in-transaction UPDATE — mention_count/last_seen are stats deferred to
-        # flush_pending_stats() which the orchestrator calls after the transaction.
-        pending: list[_EntityStat] = list(entities_to_update)
+        # Batch update existing entities
+        if entities_to_update:
+            await conn.executemany(
+                f"""
+                UPDATE {fq_table("entities")} SET
+                    mention_count = mention_count + 1,
+                    last_seen = $2
+                WHERE id = $1::uuid
+                """,
+                entities_to_update,
+            )

-        # New entities: INSERT with DO NOTHING to avoid row locks on concurrent races.
-        # ON CONFLICT DO NOTHING returns nothing for rows that conflicted; we handle
-        # that rare case with a fallback SELECT.
+        # Batch create new entities using COPY + INSERT for maximum speed
+        # This handles duplicates via ON CONFLICT and returns all IDs
        if entities_to_create:
-            # Group by lowercase name — deduplicate within the batch.
-            @dataclass
-            class _NameGroup:
-                name: str
-                event_date: datetime | None
-                indices: list[int] = field(default_factory=list)
+            # Group entities by canonical name (lowercase) to handle duplicates within batch
+            # For duplicates, we only insert once and reuse the ID, but track the count
+            unique_entities = {}  # lowercase_name -> (entity_data, event_date, [indices])
+            for idx, entity_data, event_date in entities_to_create:
+                name_lower = entity_data["text"].lower()
+                if name_lower not in unique_entities:
+                    unique_entities[name_lower] = (entity_data, event_date, [idx])
+                else:
+                    # Same entity appears multiple times - add index to list
+                    unique_entities[name_lower][2].append(idx)

-            groups: dict[str, _NameGroup] = {}
-            for e in entities_to_create:
-                name_lower = e.name.lower()
-                if name_lower not in groups:
-                    groups[name_lower] = _NameGroup(name=e.name, event_date=e.event_date)
-                groups[name_lower].indices.append(e.idx)
+            # Batch insert unique entities and get their IDs
+            # Use a single query with unnest for speed
+            entity_names = []
+            entity_dates = []
+            entity_counts = []  # Track how many times each entity appears in this batch
+            indices_map = []  # Maps result index -> list of original indices

-            # Sort by lowercase name for deterministic ordering.
-            sorted_groups = sorted(groups.items())
-            entity_names = [g.name for _, g in sorted_groups]
-            entity_dates = [g.event_date for _, g in sorted_groups]
+            for name_lower, (entity_data, event_date, indices) in unique_entities.items():
+                entity_names.append(entity_data["text"])
+                entity_dates.append(event_date)
+                entity_counts.append(len(indices))  # Count of occurrences in this batch
+                indices_map.append(indices)

-            # INSERT ... ON CONFLICT DO NOTHING — no row lock on already-existing entities.
-            inserted_rows = await conn.fetch(
+            # Batch INSERT ... ON CONFLICT with RETURNING
+            # Uses the batch count for mention_count instead of always 1
+            rows = await conn.fetch(
                f"""
                INSERT INTO {fq_table("entities")} (bank_id, canonical_name, first_seen, last_seen, mention_count)
-                SELECT $1, name, COALESCE(event_date, now()), COALESCE(event_date, now()), 1
-                FROM unnest($2::text[], $3::timestamptz[]) AS t(name, event_date)
+                SELECT $1, name, event_date, event_date, cnt
+                FROM unnest($2::text[], $3::timestamptz[], $4::int[]) AS t(name, event_date, cnt)
                ON CONFLICT (bank_id, LOWER(canonical_name))
-                DO NOTHING
-                RETURNING id, LOWER(canonical_name) AS name_lower
+                DO UPDATE SET
+                    mention_count = {fq_table("entities")}.mention_count + EXCLUDED.mention_count,
+                    last_seen = EXCLUDED.last_seen
+                RETURNING id
                """,
                bank_id,
                entity_names,
                entity_dates,
+                entity_counts,
            )
-            id_by_name: dict[str, str] = {row["name_lower"]: row["id"] for row in inserted_rows}

-            # Fallback SELECT for names that conflicted (another worker won the race).
-            missing = [n for n, _ in sorted_groups if n not in id_by_name]
-            if missing:
-                existing_rows = await conn.fetch(
-                    f"""
-                    SELECT id, LOWER(canonical_name) AS name_lower
-                    FROM {fq_table("entities")}
-                    WHERE bank_id = $1 AND LOWER(canonical_name) = ANY($2::text[])
-                    """,
-                    bank_id,
-                    missing,
-                )
-                for row in existing_rows:
-                    id_by_name[row["name_lower"]] = row["id"]
-
-            # Assign entity IDs back and queue for post-txn stats flush.
-            for name_lower, g in sorted_groups:
-                entity_id = id_by_name.get(name_lower)
-                if entity_id:
-                    for original_idx in g.indices:
-                        entity_ids[original_idx] = entity_id
-                    pending.append(_EntityStat(entity_id=entity_id, event_date=g.event_date))
-
-        # Accumulate into the resolver's pending list; the orchestrator flushes
-        # these with await entity_resolver.flush_pending_stats() after the txn.
-        key = self._task_key()
-        self._pending_stats.setdefault(key, []).extend(pending)
+            # Map returned IDs back to original indices
+            for result_idx, row in enumerate(rows):
+                entity_id = row["id"]
+                for original_idx in indices_map[result_idx]:
+                    entity_ids[original_idx] = entity_id

        return entity_ids

@@ -653,7 +408,7 @@ class EntityResolver:
        entity_id = await conn.fetchval(
            f"""
            INSERT INTO {fq_table("entities")} (bank_id, canonical_name, first_seen, last_seen, mention_count)
-            VALUES ($1, $2, COALESCE($3, now()), COALESCE($4, now()), 1)
+            VALUES ($1, $2, $3, $4, 1)
            ON CONFLICT (bank_id, LOWER(canonical_name))
            DO UPDATE SET
                mention_count = {fq_table("entities")}.mention_count + 1,
@@ -786,14 +541,19 @@ class EntityResolver:
                        entity_id_1, entity_id_2 = entity_id_2, entity_id_1
                    cooccurrence_pairs.add((entity_id_1, entity_id_2))

-        # Accumulate co-occurrence pairs for post-transaction flush.
-        # The actual INSERT/UPDATE is deferred to flush_pending_stats() to avoid
-        # row-level lock contention (ON CONFLICT DO UPDATE inside a long transaction
-        # serialises concurrent writers on popular entity pairs).
+        # Batch update co-occurrences
        if cooccurrence_pairs:
-            key = self._task_key()
-            self._pending_cooccurrences.setdefault(key, []).extend(
-                _CooccurrencePair(entity_id_1=e1, entity_id_2=e2) for e1, e2 in cooccurrence_pairs
+            now = datetime.now(UTC)
+            await conn.executemany(
+                f"""
+                INSERT INTO {fq_table("entity_cooccurrences")} (entity_id_1, entity_id_2, cooccurrence_count, last_cooccurred)
+                VALUES ($1, $2, $3, $4)
+                ON CONFLICT (entity_id_1, entity_id_2)
+                DO UPDATE SET
+                    cooccurrence_count = {fq_table("entity_cooccurrences")}.cooccurrence_count + 1,
+                    last_cooccurred = EXCLUDED.last_cooccurred
+                """,
+                [(e1, e2, 1, now) for e1, e2 in cooccurrence_pairs],
            )

    async def get_units_by_entity(self, entity_id: str, limit: int = 100) -> list[str]:
@@ -12,7 +12,6 @@ from typing import TYPE_CHECKING, Any
 if TYPE_CHECKING:
    from hindsight_api.engine.memory_engine import Budget
    from hindsight_api.engine.response_models import RecallResult, ReflectResult
-    from hindsight_api.engine.search.tags import TagsMatch
    from hindsight_api.models import RequestContext


@@ -49,7 +48,6 @@ class MemoryEngineInterface(ABC):
        contents: list[dict[str, Any]],
        *,
        request_context: "RequestContext",
-        document_tags: list[str] | None = None,
    ) -> dict[str, Any]:
        """
        Retain a batch of memory items.
@@ -57,9 +55,8 @@ class MemoryEngineInterface(ABC):
        Args:
            bank_id: The memory bank ID.
            contents: List of content dicts with 'content', optional 'event_date',
-                     'context', 'metadata', 'document_id', and per-item 'tags'.
+                     'context', 'metadata', 'document_id'.
            request_context: Request context for authentication.
-            document_tags: Optional tags applied to all items in the batch.

        Returns:
            Dict with processing results.
@@ -338,8 +335,6 @@ class MemoryEngineInterface(ABC):
        bank_id: str,
        *,
        search_query: str | None = None,
-        tags: list[str] | None = None,
-        tags_match: "TagsMatch" = "any_strict",
        limit: int = 100,
        offset: int = 0,
        request_context: "RequestContext",
@@ -349,9 +344,7 @@ class MemoryEngineInterface(ABC):

        Args:
            bank_id: The memory bank ID.
-            search_query: Case-insensitive substring filter on document ID.
-            tags: Filter by tags.
-            tags_match: How to match tags (any, all, any_strict, all_strict).
+            search_query: Search query.
            limit: Maximum results.
            offset: Pagination offset.
            request_context: Request context for authentication.
@@ -568,7 +561,6 @@ class MemoryEngineInterface(ABC):
        contents: list[dict[str, Any]],
        *,
        request_context: "RequestContext",
-        document_tags: list[str] | None = None,
    ) -> dict[str, Any]:
        """
        Submit a batch retain operation to run asynchronously.
@@ -577,7 +569,6 @@ class MemoryEngineInterface(ABC):
            bank_id: The memory bank ID.
            contents: List of content dicts to retain.
            request_context: Request context for authentication.
-            document_tags: Optional tags applied to all items in the async batch.

        Returns:
            Dict with operation_id and items_count.
@@ -128,67 +128,6 @@ class LLMInterface(ABC):
        """
        pass

-    async def supports_batch_api(self) -> bool:
-        """
-        Check if this provider supports batch API operations.
-
-        Returns:
-            True if provider supports submit_batch/get_batch_status/retrieve_batch_results
-        """
-        return False
-
-    async def submit_batch(
-        self,
-        requests: list[dict[str, Any]],
-        endpoint: str = "/v1/chat/completions",
-        completion_window: str = "24h",
-    ) -> dict[str, Any]:
-        """
-        Submit a batch of requests to the provider's batch API.
-
-        Args:
-            requests: List of request dicts in JSONL format (custom_id, method, url, body)
-            endpoint: API endpoint for the batch (e.g., "/v1/chat/completions")
-            completion_window: Completion window (e.g., "24h")
-
-        Returns:
-            Dict with batch metadata: {"batch_id": str, "status": str, ...}
-
-        Raises:
-            NotImplementedError: If provider doesn't support batch API
-        """
-        raise NotImplementedError(f"Batch API not supported for provider: {self.provider}")
-
-    async def get_batch_status(self, batch_id: str) -> dict[str, Any]:
-        """
-        Get the status of a batch job.
-
-        Args:
-            batch_id: Batch identifier returned from submit_batch
-
-        Returns:
-            Dict with status info: {"batch_id": str, "status": str, "completed_at": str, ...}
-
-        Raises:
-            NotImplementedError: If provider doesn't support batch API
-        """
-        raise NotImplementedError(f"Batch API not supported for provider: {self.provider}")
-
-    async def retrieve_batch_results(self, batch_id: str) -> list[dict[str, Any]]:
-        """
-        Retrieve completed batch results.
-
-        Args:
-            batch_id: Batch identifier returned from submit_batch
-
-        Returns:
-            List of result dicts (one per request, matched by custom_id)
-
-        Raises:
-            NotImplementedError: If provider doesn't support batch API
-        """
-        raise NotImplementedError(f"Batch API not supported for provider: {self.provider}")
-
    @abstractmethod
    async def cleanup(self) -> None:
        """Clean up resources (close connections, etc.)."""
@@ -60,59 +60,6 @@ class OutputTooLongError(Exception):
    pass


-def parse_llm_json(raw: str) -> Any:
-    """
-    Robustly parse JSON returned by an LLM.
-
-    Handles common LLM output quirks:
-    1. Markdown code fences (```json ... ```) — strip them before parsing.
-    2. Embedded control characters (\\x00-\\x1f, \\x7f) — replace with space
-       and retry if the initial parse fails.
-
-    Args:
-        raw: Raw text returned by the LLM.
-
-    Returns:
-        Parsed Python object (dict, list, etc.).
-
-    Raises:
-        json.JSONDecodeError: If the text cannot be parsed even after cleanup.
-    """
-    text = raw.strip()
-
-    # Strip markdown code fences (some models wrap JSON in ```json ... ```)
-    if text.startswith("```"):
-        text = text.split("\n", 1)[1] if "\n" in text else text[3:]
-        if text.endswith("```"):
-            text = text[:-3]
-        text = text.strip()
-
-    try:
-        return json.loads(text)
-    except json.JSONDecodeError:
-        # Some models (e.g. Gemini) embed raw control characters inside JSON
-        # string values. Replacing them with a space usually produces valid JSON.
-        cleaned = re.sub(r"[\x00-\x1f\x7f]", " ", text)
-        return json.loads(cleaned)
-
-
-_PROVIDERS_WITHOUT_API_KEY = frozenset(
-    {
-        "ollama",
-        "lmstudio",
-        "openai-codex",
-        "claude-code",
-        "mock",
-        "vertexai",
-    }
-)
-
-
-def requires_api_key(provider: str) -> bool:
-    """Return True if the given provider requires an API key to operate."""
-    return provider.lower() not in _PROVIDERS_WITHOUT_API_KEY
-
-
 def create_llm_provider(
    provider: str,
    api_key: str,
@@ -120,11 +67,9 @@ def create_llm_provider(
    model: str,
    reasoning_effort: str,
    groq_service_tier: str | None = None,
-    openai_service_tier: str | None = None,
    vertexai_project_id: str | None = None,
    vertexai_region: str | None = None,
    vertexai_credentials: Any = None,
-    gemini_safety_settings: list | None = None,
 ) -> Any:  # Returns LLMInterface
    """
    Factory function to create the appropriate LLM provider implementation.
@@ -135,8 +80,7 @@ def create_llm_provider(
        base_url: Base URL for the API.
        model: Model name.
        reasoning_effort: Reasoning effort level for supported providers.
-        groq_service_tier: Groq service tier (for Groq provider) - "on_demand", "flex", or "auto".
-        openai_service_tier: OpenAI service tier (for OpenAI provider) - None (default) or "flex" (50% cheaper).
+        groq_service_tier: Groq service tier (for Groq provider).
        vertexai_project_id: Vertex AI project ID (for VertexAI provider).
        vertexai_region: Vertex AI region (for VertexAI provider).
        vertexai_credentials: Vertex AI credentials object (for VertexAI provider).
@@ -193,7 +137,6 @@ def create_llm_provider(
            vertexai_project_id=vertexai_project_id,
            vertexai_region=vertexai_region,
            vertexai_credentials=vertexai_credentials,
-            gemini_safety_settings=gemini_safety_settings,
        )

    elif provider_lower == "anthropic":
@@ -213,7 +156,6 @@ def create_llm_provider(
            model=model,
            reasoning_effort=reasoning_effort,
            groq_service_tier=groq_service_tier,
-            openai_service_tier=openai_service_tier,
        )

    else:
@@ -235,8 +177,6 @@ class LLMProvider:
        model: str,
        reasoning_effort: str = "low",
        groq_service_tier: str | None = None,
-        openai_service_tier: str | None = None,
-        gemini_safety_settings: list | None = None,
    ):
        """
        Initialize LLM provider.
@@ -247,20 +187,15 @@ class LLMProvider:
            base_url: Base URL for the API.
            model: Model name.
            reasoning_effort: Reasoning effort level for supported providers.
-            groq_service_tier: Groq service tier ("on_demand", "flex", "auto") - from config.
-            openai_service_tier: OpenAI service tier (None or "flex") - from config.
-            gemini_safety_settings: Safety settings for Gemini/VertexAI providers.
+            groq_service_tier: Groq service tier ("on_demand", "flex", "auto"). Default: None (uses Groq's default).
        """
        self.provider = provider.lower()
        self.api_key = api_key
        self.base_url = base_url
        self.model = model
        self.reasoning_effort = reasoning_effort
-        # Service tiers from hierarchical config (not env vars)
-        self.groq_service_tier = groq_service_tier
-        self.openai_service_tier = openai_service_tier
-        # Gemini safety settings (instance default; can be overridden per-request via context var)
-        self.gemini_safety_settings = gemini_safety_settings
+        # Default to 'auto' for best performance, users can override to 'on_demand' for free tier
+        self.groq_service_tier = groq_service_tier or os.getenv(ENV_LLM_GROQ_SERVICE_TIER, "auto")

        # Validate provider
        valid_providers = [
@@ -329,18 +264,6 @@ class LLMProvider:
                f"model={self.model}, auth={'service_account' if service_account_key else 'ADC'}"
            )

-        # For Gemini/VertexAI providers: read safety settings from global config if not explicitly provided
-        # Use _get_raw_config() to bypass StaticConfigProxy (which blocks configurable fields),
-        # since LLMProvider initialization legitimately needs the server-level default.
-        if self.provider in ("gemini", "vertexai") and self.gemini_safety_settings is None:
-            from ..config import _get_raw_config
-
-            try:
-                raw_config = _get_raw_config()
-                self.gemini_safety_settings = raw_config.llm_gemini_safety_settings
-            except Exception:
-                pass  # Config may not be initialized in test environments
-
        # Create provider implementation using factory
        self._provider_impl = create_llm_provider(
            provider=self.provider,
@@ -349,11 +272,9 @@ class LLMProvider:
            model=self.model,
            reasoning_effort=self.reasoning_effort,
            groq_service_tier=self.groq_service_tier,
-            openai_service_tier=self.openai_service_tier,
            vertexai_project_id=vertexai_project_id,
            vertexai_region=vertexai_region,
            vertexai_credentials=vertexai_credentials,
-            gemini_safety_settings=self.gemini_safety_settings,
        )

        # Backward compatibility: Keep mock provider properties
@@ -522,14 +443,6 @@ class LLMProvider:

            return result

-    def set_response_callback(self, fn: Any) -> None:
-        """Set a callback invoked on each call() instead of the fixed mock response."""
-        if self.provider == "mock":
-            from .providers.mock_llm import MockLLM
-
-            if isinstance(self._provider_impl, MockLLM):
-                self._provider_impl.set_response_callback(fn)
-
    def set_mock_response(self, response: Any) -> None:
        """Set the response to return from mock calls."""
        # Backward compatibility: Store in both wrapper and provider implementation
@@ -622,23 +535,6 @@ class LLMProvider:
        # SDK will automatically check for authentication when first used
        # No need to verify here - let it fail gracefully on first call with helpful error

-    def with_config(self, config: Any) -> "ConfiguredLLMProvider":
-        """
-        Return a configured wrapper for a specific bank operation.
-
-        The wrapper applies per-bank overrides (e.g. Gemini safety settings)
-        to every ``call()`` / ``call_with_tools()`` invocation without
-        changing the underlying provider or its long-lived client connection.
-
-        Args:
-            config: Resolved ``HindsightConfig`` for the current bank/request.
-
-        Returns:
-            A ``ConfiguredLLMProvider`` that delegates to this provider with
-            the supplied config applied.
-        """
-        return ConfiguredLLMProvider(self, config.llm_gemini_safety_settings)
-
    async def cleanup(self) -> None:
        """Clean up resources."""
        pass
@@ -649,9 +545,8 @@ class LLMProvider:
        provider = os.getenv("HINDSIGHT_API_LLM_PROVIDER", "groq")
        api_key = os.getenv("HINDSIGHT_API_LLM_API_KEY", "")

-        # API key not needed for openai-codex (uses OAuth), claude-code (uses Keychain OAuth),
-        # ollama (local), or vertexai (uses GCP service account credentials)
-        if not api_key and provider not in ("openai-codex", "claude-code", "ollama", "vertexai"):
+        # API key not needed for openai-codex (uses OAuth) or claude-code (uses Keychain OAuth)
+        if not api_key and provider not in ("openai-codex", "claude-code"):
            raise ValueError(
                "HINDSIGHT_API_LLM_API_KEY environment variable is required (unless using openai-codex or claude-code)"
            )
@@ -667,9 +562,8 @@ class LLMProvider:
        provider = os.getenv("HINDSIGHT_API_ANSWER_LLM_PROVIDER", os.getenv("HINDSIGHT_API_LLM_PROVIDER", "groq"))
        api_key = os.getenv("HINDSIGHT_API_ANSWER_LLM_API_KEY", os.getenv("HINDSIGHT_API_LLM_API_KEY", ""))

-        # API key not needed for openai-codex (uses OAuth), claude-code (uses Keychain OAuth),
-        # ollama (local), or vertexai (uses GCP service account credentials)
-        if not api_key and provider not in ("openai-codex", "claude-code", "ollama", "vertexai"):
+        # API key not needed for openai-codex (uses OAuth) or claude-code (uses Keychain OAuth)
+        if not api_key and provider not in ("openai-codex", "claude-code"):
            raise ValueError(
                "HINDSIGHT_API_LLM_API_KEY or HINDSIGHT_API_ANSWER_LLM_API_KEY environment variable is required "
                "(unless using openai-codex or claude-code)"
@@ -686,9 +580,8 @@ class LLMProvider:
        provider = os.getenv("HINDSIGHT_API_JUDGE_LLM_PROVIDER", os.getenv("HINDSIGHT_API_LLM_PROVIDER", "groq"))
        api_key = os.getenv("HINDSIGHT_API_JUDGE_LLM_API_KEY", os.getenv("HINDSIGHT_API_LLM_API_KEY", ""))

-        # API key not needed for openai-codex (uses OAuth), claude-code (uses Keychain OAuth),
-        # ollama (local), or vertexai (uses GCP service account credentials)
-        if not api_key and provider not in ("openai-codex", "claude-code", "ollama", "vertexai"):
+        # API key not needed for openai-codex (uses OAuth) or claude-code (uses Keychain OAuth)
+        if not api_key and provider not in ("openai-codex", "claude-code"):
            raise ValueError(
                "HINDSIGHT_API_LLM_API_KEY or HINDSIGHT_API_JUDGE_LLM_API_KEY environment variable is required "
                "(unless using openai-codex or claude-code)"
@@ -700,58 +593,5 @@ class LLMProvider:
        return cls(provider=provider, api_key=api_key, base_url=base_url, model=model, reasoning_effort="high")


-class ConfiguredLLMProvider:
-    """
-    Thin wrapper around LLMProvider that applies bank-specific config to every call.
-
-    Obtained via ``LLMProvider.with_config(resolved_config)``.  The wrapper
-    sets any provider-specific overrides (currently Gemini safety settings)
-    immediately before each call using a ContextVar token, then resets it
-    afterwards — so nesting is safe and the configuration cannot leak across
-    operations.
-
-    All attribute access falls through to the underlying provider so callers
-    that read ``llm.provider``, ``llm.model``, etc. continue to work without
-    any changes.
-    """
-
-    def __init__(self, provider: "LLMProvider", gemini_safety_settings: list | None) -> None:
-        # Use object.__setattr__ to avoid triggering __getattr__
-        object.__setattr__(self, "_provider", provider)
-        object.__setattr__(self, "_gemini_safety_settings", gemini_safety_settings)
-
-    # ── attribute passthrough ──────────────────────────────────────────────────
-
-    def __getattr__(self, name: str) -> Any:
-        return getattr(object.__getattribute__(self, "_provider"), name)
-
-    # ── overridden call methods ────────────────────────────────────────────────
-
-    async def call(self, messages: list[dict[str, Any]], **kwargs: Any) -> Any:
-        from .providers.gemini_llm import _safety_settings_ctx
-
-        token = _safety_settings_ctx.set(object.__getattribute__(self, "_gemini_safety_settings"))
-        try:
-            return await object.__getattribute__(self, "_provider").call(messages=messages, **kwargs)
-        finally:
-            _safety_settings_ctx.reset(token)
-
-    async def call_with_tools(
-        self,
-        messages: list[dict[str, Any]],
-        tools: list[dict[str, Any]],
-        **kwargs: Any,
-    ) -> "LLMToolCallResult":
-        from .providers.gemini_llm import _safety_settings_ctx
-
-        token = _safety_settings_ctx.set(object.__getattribute__(self, "_gemini_safety_settings"))
-        try:
-            return await object.__getattribute__(self, "_provider").call_with_tools(
-                messages=messages, tools=tools, **kwargs
-            )
-        finally:
-            _safety_settings_ctx.reset(token)
-
-
 # Backwards compatibility alias
 LLMConfig = LLMProvider
@@ -0,0 +1,14 @@
+"""
+Mental models module for Hindsight.
+
+Mental models contain directives - hard rules that are injected into reflect prompts.
+Directives are user-defined and their observations are user-provided (not LLM-generated).
+
+Other types of consolidated knowledge are handled by:
+- Learnings: Automatic bottom-up consolidation from facts
+- Pinned Reflections: User-curated living documents
+"""
+
+from .models import MentalModel, MentalModelSubtype
+
+__all__ = ["MentalModel", "MentalModelSubtype"]
@@ -0,0 +1,53 @@
+"""
+Pydantic models for mental models.
+"""
+
+from datetime import datetime, timezone
+from enum import Enum
+
+from pydantic import BaseModel, Field
+
+
+class MentalModelSubtype(str, Enum):
+    """Subtype of mental model.
+
+    Currently only DIRECTIVE is supported. Other types of consolidated knowledge
+    are handled by:
+    - Learnings: Automatic bottom-up consolidation from facts
+    - Pinned Reflections: User-curated living documents
+    """
+
+    DIRECTIVE = "directive"  # User-defined hard rules, observations user-provided
+
+
+class MentalModel(BaseModel):
+    """
+    A mental model representing synthesized understanding.
+
+    Mental models are the agent's consolidated knowledge. Unlike raw facts,
+    mental models provide:
+    - A one-liner description for quick scanning/retrieval
+    - A full summary for deep understanding
+    - Links to related mental models
+    """
+
+    id: str = Field(description="Unique identifier within the bank")
+    bank_id: str = Field(description="Bank this mental model belongs to")
+    subtype: MentalModelSubtype = Field(description="How this model was created")
+    name: str = Field(description="Human-readable name")
+    description: str = Field(description="One-liner for quick scanning and retrieval matching")
+    summary: str | None = Field(default=None, description="Full synthesized understanding")
+
+    # References
+    entity_id: str | None = Field(default=None, description="Reference to entities table when type=entity")
+    source_facts: list[str] = Field(default_factory=list, description="Fact IDs used to generate summary")
+    links: list[str] = Field(default_factory=list, description="Related mental model IDs")
+
+    # Tags for scoped visibility (similar to document tags)
+    tags: list[str] = Field(default_factory=list, description="Tags for scoped visibility filtering")
+
+    # Timestamps
+    last_updated: datetime | None = Field(default=None, description="When summary was last regenerated")
+    created_at: datetime = Field(
+        default_factory=lambda: datetime.now(timezone.utc), description="When this model was created"
+    )
@@ -1,69 +0,0 @@
-"""
-Typed metadata models for async operations.
-
-These dataclasses define the structure of result_metadata for different operation types.
-The metadata is exposed in the API for debugging purposes and may change without notice.
-"""
-
-from dataclasses import asdict, dataclass
-from typing import Any
-
-
-@dataclass
-class BatchRetainParentMetadata:
-    """Metadata for parent batch_retain operations (when split into sub-batches)."""
-
-    items_count: int
-    total_tokens: int
-    num_sub_batches: int
-    is_parent: bool = True
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dict for JSON serialization."""
-        return asdict(self)
-
-
-@dataclass
-class BatchRetainChildMetadata:
-    """Metadata for child batch_retain operations (individual sub-batches)."""
-
-    items_count: int
-    parent_operation_id: str
-    sub_batch_index: int
-    total_sub_batches: int
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dict for JSON serialization."""
-        return asdict(self)
-
-
-@dataclass
-class RetainMetadata:
-    """Metadata for regular retain operations (non-batched, deprecated async path)."""
-
-    items_count: int
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dict for JSON serialization."""
-        return asdict(self)
-
-
-@dataclass
-class ConsolidationMetadata:
-    """Metadata for consolidation operations."""
-
-    # Currently empty, but structure for future fields
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dict for JSON serialization."""
-        return asdict(self)
-
-
-@dataclass
-class RefreshMentalModelMetadata:
-    """Metadata for mental model refresh operations."""
-
-    mental_model_id: str
-
-    def to_dict(self) -> dict[str, Any]:
-        """Convert to dict for JSON serialization."""
-        return asdict(self)
@@ -1,128 +0,0 @@
-"""File parser implementations."""
-
-import logging
-from dataclasses import dataclass
-
-from .base import FileParser, UnsupportedFileTypeError
-from .iris import IrisParser
-from .markitdown import MarkitdownParser
-
-__all__ = [
-    "FileParser",
-    "UnsupportedFileTypeError",
-    "IrisParser",
-    "MarkitdownParser",
-    "FileParserRegistry",
-    "ConvertResult",
-]
-
-
-@dataclass
-class ConvertResult:
-    """Result of a successful file conversion."""
-
-    content: str
-    parser_name: str
-
-
-logger = logging.getLogger(__name__)
-
-
-class FileParserRegistry:
-    """Registry for file parsers with auto-detection."""
-
-    def __init__(self):
-        """Initialize empty parser registry."""
-        self._parsers: dict[str, FileParser] = {}
-
-    def register(self, parser: FileParser):
-        """
-        Register a parser.
-
-        Args:
-            parser: FileParser instance
-        """
-        self._parsers[parser.name()] = parser
-
-    def get_parser(
-        self,
-        name: str | None,
-        filename: str,
-        content_type: str | None = None,
-    ) -> FileParser:
-        """
-        Get parser by name or auto-detect.
-
-        Args:
-            name: Parser name (e.g., "markitdown") or None for auto-detect
-            filename: File name for auto-detection
-            content_type: MIME type (optional)
-
-        Returns:
-            FileParser instance
-
-        Raises:
-            ValueError: If no suitable parser found
-        """
-        if name:
-            # Explicit parser requested — return it directly, let the parser
-            # raise UnsupportedFileTypeError from convert() if needed
-            if name not in self._parsers:
-                raise ValueError(f"Parser '{name}' not found. Available: {list(self._parsers.keys())}")
-            return self._parsers[name]
-
-        # Auto-detect parser
-        for parser in self._parsers.values():
-            if parser.supports(filename, content_type):
-                return parser
-
-        raise ValueError(f"No parser found for {filename}. Available parsers: {list(self._parsers.keys())}")
-
-    async def convert_with_fallback(
-        self,
-        parsers: list[str],
-        file_data: bytes,
-        filename: str,
-        content_type: str | None = None,
-    ) -> ConvertResult:
-        """
-        Try each parser in order, falling back on failure or empty content.
-
-        Moves to the next parser if the current one raises UnsupportedFileTypeError
-        or returns empty content. Any other exception (RuntimeError, network error,
-        etc.) also triggers a fallback so the chain is exhausted before failing.
-
-        Args:
-            parsers: Ordered list of parser names to try
-            file_data: Raw file bytes
-            filename: Original filename
-            content_type: MIME type (optional)
-
-        Returns:
-            ConvertResult with the parsed content and the name of the parser that succeeded
-
-        Raises:
-            ValueError: If a parser name is not registered
-            RuntimeError: If all parsers fail or return empty content
-        """
-        last_error: Exception | None = None
-        for name in parsers:
-            parser = self.get_parser(name, filename, content_type)
-            try:
-                content = await parser.convert(file_data, filename)
-                if content and content.strip():
-                    return ConvertResult(content=content, parser_name=name)
-                logger.warning(f"Parser '{name}' returned empty content for '{filename}', trying next")
-                last_error = RuntimeError(f"Parser '{name}' returned no content for '{filename}'")
-            except UnsupportedFileTypeError as e:
-                logger.warning(f"Parser '{name}' does not support '{filename}', trying next: {e}")
-                last_error = e
-            except Exception as e:
-                logger.warning(f"Parser '{name}' failed for '{filename}', trying next: {e}")
-                last_error = e
-
-        raise last_error or RuntimeError(f"No parsers available for '{filename}'")
-
-    def list_parsers(self) -> list[str]:
-        """Get list of registered parser names."""
-        return list(self._parsers.keys())
@@ -1,58 +0,0 @@
-"""Abstract base class for file parsers."""
-
-from abc import ABC, abstractmethod
-
-
-class UnsupportedFileTypeError(Exception):
-    """Raised by a parser when it does not support the given file type."""
-
-    pass
-
-
-class FileParser(ABC):
-    """Abstract base for file to markdown parsers."""
-
-    @abstractmethod
-    async def convert(self, file_data: bytes, filename: str) -> str:
-        """
-        Parse file to markdown.
-
-        Args:
-            file_data: Raw file bytes
-            filename: Original filename (used for format detection)
-
-        Returns:
-            Markdown content as string
-
-        Raises:
-            UnsupportedFileTypeError: If the file type is not supported by this parser
-            RuntimeError: If parsing fails for another reason
-        """
-        pass
-
-    def supports(self, filename: str, content_type: str | None = None) -> bool:
-        """
-        Check if parser supports this file type.
-
-        Override this for local/static extension-based filtering.
-        Parsers that delegate to a remote service should leave this as True
-        and raise UnsupportedFileTypeError from convert() instead.
-
-        Args:
-            filename: File name (used for extension check)
-            content_type: MIME type (optional)
-
-        Returns:
-            True if this parser can handle the file (default: True)
-        """
-        return True
-
-    @abstractmethod
-    def name(self) -> str:
-        """
-        Get parser name.
-
-        Returns:
-            Parser name (e.g., "markitdown")
-        """
-        pass
@@ -1,138 +0,0 @@
-"""Iris parser implementation using the Vectorize Iris HTTP API."""
-
-import asyncio
-import logging
-import mimetypes
-import time
-
-import httpx
-
-from .base import FileParser, UnsupportedFileTypeError
-
-logger = logging.getLogger(__name__)
-
-_IRIS_BASE_URL = "https://api.vectorize.io/v1"
-_DEFAULT_POLL_INTERVAL = 2.0  # seconds
-_DEFAULT_TIMEOUT = 300.0  # seconds
-
-
-class IrisParser(FileParser):
-    """
-    Iris file parser using the Vectorize Iris cloud extraction service.
-
-    Uploads files to the Vectorize Iris API, starts an extraction job,
-    and polls until the text is ready. The API determines which file types
-    are supported — UnsupportedFileTypeError is raised if the file is rejected.
-
-    Authentication:
-        Requires HINDSIGHT_API_FILE_PARSER_IRIS_TOKEN and
-        HINDSIGHT_API_FILE_PARSER_IRIS_ORG_ID environment variables,
-        or pass them explicitly via the constructor.
-    """
-
-    def __init__(
-        self,
-        token: str,
-        org_id: str,
-        poll_interval: float = _DEFAULT_POLL_INTERVAL,
-        timeout: float = _DEFAULT_TIMEOUT,
-    ):
-        """
-        Initialize iris parser.
-
-        Args:
-            token: Vectorize API token
-            org_id: Vectorize organization ID
-            poll_interval: Seconds between status poll requests (default: 2)
-            timeout: Maximum seconds to wait for extraction (default: 300)
-        """
-        self._token = token
-        self._org_id = org_id
-        self._poll_interval = poll_interval
-        self._timeout = timeout
-        self._auth_headers = {"Authorization": f"Bearer {token}"}
-
-    async def convert(self, file_data: bytes, filename: str) -> str:
-        """
-        Parse file to text using the Vectorize Iris API.
-
-        Raises:
-            UnsupportedFileTypeError: If the Iris API rejects the file type (4xx)
-            RuntimeError: If extraction fails for another reason
-        """
-        content_type = mimetypes.guess_type(filename)[0] or "application/octet-stream"
-
-        async with httpx.AsyncClient(timeout=httpx.Timeout(30.0, read=120.0)) as client:
-            # Step 1: Request a presigned upload URL
-            init_resp = await client.post(
-                f"{_IRIS_BASE_URL}/org/{self._org_id}/files",
-                headers=self._auth_headers,
-                json={"name": filename, "contentType": content_type},
-            )
-            _raise_for_status(init_resp, filename, "file upload init")
-            init_data = init_resp.json()
-            file_id: str = init_data["fileId"]
-            upload_url: str = init_data["uploadUrl"]
-
-            # Step 2: Upload the file bytes to the presigned URL (no auth header)
-            # Ensure file_data is plain bytes (GCS storage may return obstore.Bytes)
-            upload_resp = await client.put(
-                upload_url,
-                content=bytes(file_data),
-                headers={"Content-Type": content_type},
-            )
-            _raise_for_status(upload_resp, filename, "file upload")
-
-            # Step 3: Start extraction
-            extract_resp = await client.post(
-                f"{_IRIS_BASE_URL}/org/{self._org_id}/extraction",
-                headers=self._auth_headers,
-                json={"fileId": file_id},
-            )
-            _raise_for_status(extract_resp, filename, "start extraction")
-            extraction_id: str = extract_resp.json()["extractionId"]
-
-            # Step 4: Poll until ready or timeout
-            deadline = time.monotonic() + self._timeout
-            while True:
-                status_resp = await client.get(
-                    f"{_IRIS_BASE_URL}/org/{self._org_id}/extraction/{extraction_id}",
-                    headers=self._auth_headers,
-                )
-                _raise_for_status(status_resp, filename, "poll extraction status")
-                status_data = status_resp.json()
-
-                if status_data.get("ready"):
-                    data = status_data.get("data", {})
-                    if not data.get("success"):
-                        error = data.get("error", "unknown error")
-                        raise RuntimeError(f"Iris extraction failed for '{filename}': {error}")
-                    text = data.get("text")
-                    if not text:
-                        raise RuntimeError(f"No content extracted from '{filename}'")
-                    return text
-
-                if time.monotonic() >= deadline:
-                    raise RuntimeError(f"Iris extraction timed out after {self._timeout}s for '{filename}'")
-
-                await asyncio.sleep(self._poll_interval)
-
-    def name(self) -> str:
-        """Get parser name."""
-        return "iris"
-
-
-def _raise_for_status(response: httpx.Response, filename: str, step: str) -> None:
-    """
-    Raise an appropriate error including the response body on HTTP errors.
-
-    Raises UnsupportedFileTypeError for 4xx responses (file rejected by the API),
-    RuntimeError for other HTTP errors.
-    """
-    if not response.is_error:
-        return
-    body = response.text or "<empty>"
-    msg = f"Iris API error during {step} for '{filename}': {response.status_code} {response.reason_phrase} — {body}"
-    if response.is_client_error:
-        raise UnsupportedFileTypeError(msg)
-    raise RuntimeError(msg)
@@ -1,109 +0,0 @@
-"""Markitdown parser implementation."""
-
-import asyncio
-import logging
-import tempfile
-from pathlib import Path
-
-from .base import FileParser
-
-logger = logging.getLogger(__name__)
-
-
-class MarkitdownParser(FileParser):
-    """
-    Markitdown file parser.
-
-    Uses Microsoft's markitdown library to convert various file formats
-    to markdown including PDF, Office docs, images (via OCR), audio, HTML.
-
-    Supported formats:
-    - PDF (.pdf)
-    - Word (.docx, .doc)
-    - PowerPoint (.pptx, .ppt)
-    - Excel (.xlsx, .xls)
-    - Images (.jpg, .jpeg, .png) - with OCR
-    - HTML (.html, .htm)
-    - Text (.txt, .md)
-    - Audio (.mp3, .wav) - with transcription
-    """
-
-    def __init__(self):
-        """Initialize markitdown parser."""
-        # Lazy import to avoid requiring markitdown for all users
-        try:
-            from markitdown import MarkItDown
-
-            self._markitdown = MarkItDown()
-        except ImportError as e:
-            raise ImportError(
-                "markitdown package is required for file parsing. Install with: pip install markitdown"
-            ) from e
-
-    async def convert(self, file_data: bytes, filename: str) -> str:
-        """Parse file to markdown using markitdown."""
-        # markitdown is synchronous, so we run it in executor to avoid blocking
-        loop = asyncio.get_event_loop()
-        return await loop.run_in_executor(None, self._convert_sync, file_data, filename)
-
-    def _convert_sync(self, file_data: bytes, filename: str) -> str:
-        """Synchronous parsing (runs in thread pool)."""
-        # Write to temp file (markitdown requires file path)
-        with tempfile.NamedTemporaryFile(suffix=Path(filename).suffix, delete=False) as tmp:
-            tmp.write(file_data)
-            tmp_path = tmp.name
-
-        try:
-            # Parse using markitdown
-            result = self._markitdown.convert(tmp_path)
-
-            if not result or not result.text_content:
-                raise RuntimeError(f"No content extracted from '{filename}'")
-
-            return result.text_content
-
-        except Exception as e:
-            logger.error(f"Markitdown parsing failed for {filename}: {e}")
-            raise RuntimeError(f"Failed to parse '{filename}': {e}") from e
-
-        finally:
-            # Clean up temp file
-            try:
-                Path(tmp_path).unlink()
-            except Exception:
-                pass
-
-    def supports(self, filename: str, content_type: str | None = None) -> bool:
-        """Check if markitdown supports this file type."""
-        # Supported extensions (from markitdown docs)
-        supported_extensions = {
-            # Documents
-            ".pdf",
-            ".docx",
-            ".doc",
-            ".pptx",
-            ".ppt",
-            ".xlsx",
-            ".xls",
-            # Images (with OCR)
-            ".jpg",
-            ".jpeg",
-            ".png",
-            # Web
-            ".html",
-            ".htm",
-            # Text
-            ".txt",
-            ".md",
-            ".csv",
-            # Audio (with transcription)
-            ".mp3",
-            ".wav",
-        }
-
-        ext = Path(filename).suffix.lower()
-        return ext in supported_extensions
-
-    def name(self) -> str:
-        """Get parser name."""
-        return "markitdown"
@@ -238,24 +238,21 @@ class ClaudeCodeLLM(LLMInterface):
                )

                # Record trace span
-                try:
-                    from hindsight_api.tracing import get_span_recorder
+                from hindsight_api.tracing import get_span_recorder

-                    span_recorder = get_span_recorder()
-                    span_recorder.record_llm_call(
-                        provider=self.provider,
-                        model=self.model,
-                        scope=scope,
-                        messages=messages,
-                        response_content=result if isinstance(result, str) else result.model_dump_json(),
-                        input_tokens=estimated_input,
-                        output_tokens=estimated_output,
-                        duration=duration,
-                        finish_reason=None,
-                        error=None,
-                    )
-                except Exception:
-                    pass  # logging failure must never affect the operation
+                span_recorder = get_span_recorder()
+                span_recorder.record_llm_call(
+                    provider=self.provider,
+                    model=self.model,
+                    scope=scope,
+                    messages=messages,
+                    response_content=result if isinstance(result, str) else json.dumps(result),
+                    input_tokens=estimated_input,
+                    output_tokens=estimated_output,
+                    duration=duration,
+                    finish_reason=None,
+                    error=None,
+                )

                # Log slow calls
                if duration > 10.0:
@@ -11,7 +11,6 @@ import json
 import logging
 import os
 import time
-from contextvars import ContextVar
 from typing import Any

 from google import genai
@@ -19,18 +18,11 @@ from google.genai import errors as genai_errors
 from google.genai import types as genai_types

 from hindsight_api.engine.llm_interface import LLMInterface, OutputTooLongError
-from hindsight_api.engine.llm_wrapper import parse_llm_json
 from hindsight_api.engine.response_models import LLMToolCall, LLMToolCallResult, TokenUsage
 from hindsight_api.metrics import get_metrics_collector

 logger = logging.getLogger(__name__)

-# Per-request Gemini safety settings override.
-# Set exclusively by ConfiguredLLMProvider.call() / call_with_tools() via token-based
-# set/reset, so it is properly scoped to each individual LLM call and never leaks.
-_safety_settings_ctx: ContextVar[list | None] = ContextVar("gemini_safety_settings", default=None)
-
-
 # Vertex AI imports (optional)
 try:
    import google.auth
@@ -65,9 +57,6 @@ class GeminiLLM(LLMInterface):
        self._client = None
        self._is_vertexai = self.provider == "vertexai"

-        # Safety settings: None means use Gemini's defaults
-        self._safety_settings: list | None = kwargs.get("gemini_safety_settings")
-
        if self._is_vertexai:
            self._init_vertexai(**kwargs)
        else:
@@ -226,29 +215,16 @@ class GeminiLLM(LLMInterface):
        if temperature is not None:
            config_kwargs["temperature"] = temperature

-        # Apply safety settings: context var (per-request bank override) takes precedence over instance default
-        effective_safety_settings = _safety_settings_ctx.get()
-        if effective_safety_settings is None:
-            effective_safety_settings = self._safety_settings
-        if effective_safety_settings is not None:
-            config_kwargs["safety_settings"] = [
-                genai_types.SafetySetting(category=s["category"], threshold=s["threshold"])
-                for s in effective_safety_settings
-            ]
-
        generation_config = genai_types.GenerateContentConfig(**config_kwargs) if config_kwargs else None

        last_exception = None

        for attempt in range(max_retries + 1):
            try:
-                response = await asyncio.wait_for(
-                    self._client.aio.models.generate_content(
-                        model=self.model,
-                        contents=gemini_contents,
-                        config=generation_config,
-                    ),
-                    timeout=90.0,  # Safety net for network hangs; valid slow responses are <90s
+                response = await self._client.aio.models.generate_content(
+                    model=self.model,
+                    contents=gemini_contents,
+                    config=generation_config,
                )

                content = response.text
@@ -271,7 +247,7 @@ class GeminiLLM(LLMInterface):

                # Parse structured output if requested
                if response_format is not None:
-                    json_data = parse_llm_json(content)
+                    json_data = json.loads(content)
                    if skip_validation:
                        result = json_data
                    else:
@@ -429,57 +405,31 @@ class GeminiLLM(LLMInterface):
        # Convert messages
        system_instruction = None
        gemini_contents = []
-        msg_list = list(messages)
-        i = 0
-        while i < len(msg_list):
-            msg = msg_list[i]
+        for msg in messages:
            role = msg.get("role", "user")
            content = msg.get("content", "")

            if role == "system":
                system_instruction = (system_instruction + "\n\n" + content) if system_instruction else content
-                i += 1
            elif role == "tool":
-                # Gemini requires ALL tool responses for a given model turn to be grouped
-                # into a single Content with multiple FunctionResponse parts.
-                # Consecutive role="tool" messages correspond to one model turn's tool calls.
-                parts = []
-                while i < len(msg_list) and msg_list[i].get("role") == "tool":
-                    tool_msg = msg_list[i]
-                    tool_content = tool_msg.get("content", "")
-                    parts.append(
-                        genai_types.Part(
-                            function_response=genai_types.FunctionResponse(
-                                name=tool_msg.get("name", ""),
-                                response={"result": tool_content},
+                # Gemini uses function_response
+                gemini_contents.append(
+                    genai_types.Content(
+                        role="user",
+                        parts=[
+                            genai_types.Part(
+                                function_response=genai_types.FunctionResponse(
+                                    name=msg.get("name", ""),
+                                    response={"result": content},
+                                )
                            )
-                        )
+                        ],
                    )
-                    i += 1
-                gemini_contents.append(genai_types.Content(role="user", parts=parts))
+                )
            elif role == "assistant":
-                tool_calls_in_msg = msg.get("tool_calls", [])
-                if tool_calls_in_msg:
-                    # Convert OpenAI-style tool_calls to Gemini function_call parts
-                    # This is required for proper multi-turn conversation history
-                    parts = []
-                    if content:
-                        parts.append(genai_types.Part(text=content))
-                    for tc in tool_calls_in_msg:
-                        fn = tc.get("function", {})
-                        fn_name = fn.get("name", "")
-                        fn_args_str = fn.get("arguments", "{}")
-                        fn_args = parse_llm_json(fn_args_str)
-                        parts.append(
-                            genai_types.Part(function_call=genai_types.FunctionCall(name=fn_name, args=fn_args))
-                        )
-                    gemini_contents.append(genai_types.Content(role="model", parts=parts))
-                else:
-                    gemini_contents.append(genai_types.Content(role="model", parts=[genai_types.Part(text=content)]))
-                i += 1
+                gemini_contents.append(genai_types.Content(role="model", parts=[genai_types.Part(text=content)]))
            else:
                gemini_contents.append(genai_types.Content(role="user", parts=[genai_types.Part(text=content)]))
-                i += 1

        config_kwargs: dict[str, Any] = {"tools": gemini_tools}
        if system_instruction:
@@ -487,50 +437,15 @@ class GeminiLLM(LLMInterface):
        if temperature is not None:
            config_kwargs["temperature"] = temperature

-        # Map OpenAI-style tool_choice to Gemini FunctionCallingConfig
-        if tool_choice == "required":
-            config_kwargs["tool_config"] = genai_types.ToolConfig(
-                function_calling_config=genai_types.FunctionCallingConfig(
-                    mode="ANY",
-                )
-            )
-        elif isinstance(tool_choice, dict) and tool_choice.get("type") == "function":
-            fn_name = tool_choice.get("function", {}).get("name")
-            if fn_name:
-                config_kwargs["tool_config"] = genai_types.ToolConfig(
-                    function_calling_config=genai_types.FunctionCallingConfig(
-                        mode="ANY",
-                        allowed_function_names=[fn_name],
-                    )
-                )
-        elif tool_choice == "none":
-            config_kwargs["tool_config"] = genai_types.ToolConfig(
-                function_calling_config=genai_types.FunctionCallingConfig(mode="NONE")
-            )
-        # "auto" is the default (no tool_config needed)
-
-        # Apply safety settings: context var (per-request bank override) takes precedence over instance default
-        effective_safety_settings = _safety_settings_ctx.get()
-        if effective_safety_settings is None:
-            effective_safety_settings = self._safety_settings
-        if effective_safety_settings is not None:
-            config_kwargs["safety_settings"] = [
-                genai_types.SafetySetting(category=s["category"], threshold=s["threshold"])
-                for s in effective_safety_settings
-            ]
-
        config = genai_types.GenerateContentConfig(**config_kwargs)

        last_exception = None
        for attempt in range(max_retries + 1):
            try:
-                response = await asyncio.wait_for(
-                    self._client.aio.models.generate_content(
-                        model=self.model,
-                        contents=gemini_contents,
-                        config=config,
-                    ),
-                    timeout=90.0,  # Safety net for network hangs; valid slow responses are <90s
+                response = await self._client.aio.models.generate_content(
+                    model=self.model,
+                    contents=gemini_contents,
+                    config=config,
                )

                # Extract content and tool calls
@@ -6,7 +6,6 @@ without making actual API calls to external LLM services.
 """

 import logging
-from collections.abc import Callable
 from typing import Any

 from ..llm_interface import LLMInterface
@@ -67,7 +66,6 @@ class MockLLM(LLMInterface):
        self._mock_calls: list[dict] = []
        self._mock_response: Any = None
        self._mock_exception: Exception | None = None
-        self._response_callback: Callable[[list[dict], str], Any] | None = None

    async def verify_connection(self) -> None:
        """
@@ -149,9 +147,7 @@ class MockLLM(LLMInterface):
        )

        # Return mock response
-        if self._response_callback is not None:
-            result = self._response_callback(messages, scope)
-        elif self._mock_response is not None:
+        if self._mock_response is not None:
            result = self._mock_response
        elif response_format is not None:
            # Try to create a minimal valid instance of the response format
@@ -218,15 +214,7 @@ class MockLLM(LLMInterface):

        span_recorder = get_span_recorder()

-        if self._response_callback is not None:
-            cb_result = self._response_callback(messages, scope)
-            if isinstance(cb_result, LLMToolCallResult):
-                result = cb_result
-            else:
-                result = LLMToolCallResult(
-                    content=str(cb_result) if cb_result is not None else "mock response", finish_reason="stop"
-                )
-        elif self._mock_response is not None:
+        if self._mock_response is not None:
            if isinstance(self._mock_response, LLMToolCallResult):
                result = self._mock_response
            elif isinstance(self._mock_response, list):
@@ -270,16 +258,6 @@ class MockLLM(LLMInterface):
        """Clean up resources (no-op for mock provider)."""
        pass

-    def set_response_callback(self, fn: Callable[[list[dict], str], Any]) -> None:
-        """
-        Set a callback invoked on each call() instead of _mock_response.
-
-        The callback receives (messages, scope) and returns the response.
-        Useful for returning different responses per call (e.g., cycling
-        through a corpus in a benchmark).
-        """
-        self._response_callback = fn
-
    def set_mock_response(self, response: Any) -> None:
        """
        Set the response to return from mock calls.
@@ -16,7 +16,6 @@ Features:
 """

 import asyncio
-import io
 import json
 import logging
 import os
@@ -97,9 +96,8 @@ class OpenAICompatibleLLM(LLMInterface):
        if self.provider in ("openai", "groq") and not self.api_key:
            raise ValueError(f"API key is required for {self.provider}")

-        # Service tier configuration (from config, not env vars)
-        self.groq_service_tier = groq_service_tier
-        self.openai_service_tier = kwargs.get("openai_service_tier")
+        # Groq service tier configuration
+        self.groq_service_tier = groq_service_tier or os.getenv("HINDSIGHT_API_LLM_GROQ_SERVICE_TIER", "auto")

        # Get timeout config
        self.timeout = timeout or float(os.getenv(ENV_LLM_TIMEOUT, str(DEFAULT_LLM_TIMEOUT)))
@@ -784,140 +782,6 @@ class OpenAICompatibleLLM(LLMInterface):
            raise last_exception
        raise RuntimeError("Ollama call failed after all retries")

-    async def supports_batch_api(self) -> bool:
-        """Check if this provider supports batch API operations."""
-        # Only OpenAI and Groq support batch API
-        return self.provider in ("openai", "groq")
-
-    async def submit_batch(
-        self,
-        requests: list[dict[str, Any]],
-        endpoint: str = "/v1/chat/completions",
-        completion_window: str = "24h",
-    ) -> dict[str, Any]:
-        """
-        Submit a batch of requests to OpenAI/Groq Batch API.
-
-        Args:
-            requests: List of request dicts with custom_id, method, url, body
-            endpoint: API endpoint (e.g., "/v1/chat/completions")
-            completion_window: Completion window (e.g., "24h")
-
-        Returns:
-            Dict with batch metadata including batch_id
-
-        Raises:
-            NotImplementedError: If provider doesn't support batch API
-        """
-        if not await self.supports_batch_api():
-            raise NotImplementedError(f"Batch API not supported for provider: {self.provider}")
-
-        logger.info(f"Submitting batch with {len(requests)} requests to {self.provider}")
-
-        # Format requests as JSONL
-        jsonl_content = "\n".join(json.dumps(req) for req in requests)
-
-        # Upload file to provider (wrap in BytesIO with filename)
-        file_bytes = io.BytesIO(jsonl_content.encode("utf-8"))
-        file_bytes.name = "batch_input.jsonl"  # OpenAI SDK needs a filename
-
-        file_response = await self._client.files.create(
-            file=file_bytes,
-            purpose="batch",
-        )
-
-        logger.debug(f"Uploaded batch file: {file_response.id}")
-
-        # Create batch
-        batch_response = await self._client.batches.create(
-            input_file_id=file_response.id,
-            endpoint=endpoint,
-            completion_window=completion_window,
-        )
-
-        logger.info(f"Batch submitted: {batch_response.id}, status={batch_response.status}")
-
-        return {
-            "batch_id": batch_response.id,
-            "status": batch_response.status,
-            "input_file_id": file_response.id,
-            "created_at": batch_response.created_at,
-            "request_count": len(requests),
-        }
-
-    async def get_batch_status(self, batch_id: str) -> dict[str, Any]:
-        """
-        Get the status of a batch job.
-
-        Args:
-            batch_id: Batch identifier
-
-        Returns:
-            Dict with status info (batch_id, status, completed_at, etc.)
-        """
-        if not await self.supports_batch_api():
-            raise NotImplementedError(f"Batch API not supported for provider: {self.provider}")
-
-        batch = await self._client.batches.retrieve(batch_id)
-
-        result = {
-            "batch_id": batch.id,
-            "status": batch.status,
-            "created_at": batch.created_at,
-            "request_counts": {
-                "total": batch.request_counts.total if batch.request_counts else 0,
-                "completed": batch.request_counts.completed if batch.request_counts else 0,
-                "failed": batch.request_counts.failed if batch.request_counts else 0,
-            },
-        }
-
-        if batch.completed_at:
-            result["completed_at"] = batch.completed_at
-        if batch.output_file_id:
-            result["output_file_id"] = batch.output_file_id
-        if batch.error_file_id:
-            result["error_file_id"] = batch.error_file_id
-        if batch.errors:
-            result["errors"] = batch.errors
-
-        return result
-
-    async def retrieve_batch_results(self, batch_id: str) -> list[dict[str, Any]]:
-        """
-        Retrieve completed batch results.
-
-        Args:
-            batch_id: Batch identifier
-
-        Returns:
-            List of result dicts (one per request, matched by custom_id)
-        """
-        if not await self.supports_batch_api():
-            raise NotImplementedError(f"Batch API not supported for provider: {self.provider}")
-
-        # Get batch status
-        batch = await self._client.batches.retrieve(batch_id)
-
-        if batch.status != "completed":
-            raise ValueError(f"Batch {batch_id} is not completed yet (status: {batch.status})")
-
-        if not batch.output_file_id:
-            raise ValueError(f"Batch {batch_id} has no output file")
-
-        # Download results file
-        logger.debug(f"Downloading results for batch {batch_id} from file {batch.output_file_id}")
-        file_content = await self._client.files.content(batch.output_file_id)
-
-        # Parse JSONL results
-        results = []
-        for line in file_content.text.strip().split("\n"):
-            if line:
-                results.append(json.loads(line))
-
-        logger.info(f"Retrieved {len(results)} results for batch {batch_id}")
-
-        return results
-
    async def cleanup(self) -> None:
        """Clean up resources (close OpenAI client connections)."""
        if hasattr(self, "_client") and self._client:
@@ -92,17 +92,11 @@ class DateparserQueryAnalyzer(QueryAnalyzer):
        self._search_dates = None

    def load(self) -> None:
-        """Load dateparser and warm up internal data structures.
-
-        Triggers the real initialization cost (regex tables, timezone data) at
-        load time so the first actual recall doesn't pay the cold-start penalty.
-        """
+        """Load dateparser (lazy import)."""
        if self._search_dates is None:
            from dateparser.search import search_dates

            self._search_dates = search_dates
-            # Warm up: fire a dummy call to trigger lazy-loaded internal tables.
-            self._search_dates("today")

    def analyze(self, query: str, reference_date: datetime | None = None) -> QueryAnalysis:
        """
@@ -14,26 +14,32 @@ import re
 import time
 from typing import TYPE_CHECKING, Any, Awaitable, Callable

-import tiktoken
-
 from .models import DirectiveInfo, LLMCall, ReflectAgentResult, TokenUsageSummary, ToolCall
 from .prompts import FINAL_SYSTEM_PROMPT, _extract_directive_rules, build_final_prompt, build_system_prompt_for_tools
 from .tools_schema import get_reflect_tools


 def _build_directives_applied(directives: list[dict[str, Any]] | None) -> list[DirectiveInfo]:
-    """Build list of DirectiveInfo from directives."""
+    """Build list of DirectiveInfo from directive mental models.
+
+    Handles multiple directive formats:
+    1. New format: directives have direct 'content' field
+    2. Fallback: directives have 'description' field
+    """
    if not directives:
        return []

-    return [
-        DirectiveInfo(
-            id=directive.get("id", ""),
-            name=directive.get("name", ""),
-            content=directive.get("content", ""),
-        )
-        for directive in directives
-    ]
+    result = []
+    for directive in directives:
+        directive_id = directive.get("id", "")
+        directive_name = directive.get("name", "")
+
+        # Get content from 'content' field or fallback to 'description'
+        content = directive.get("content", "") or directive.get("description", "")
+
+        result.append(DirectiveInfo(id=directive_id, name=directive_name, content=content))
+
+    return result


 if TYPE_CHECKING:
@@ -261,46 +267,6 @@ OUTPUT:"""
        return None, 0, 0


-_TIKTOKEN_ENCODING = tiktoken.get_encoding("cl100k_base")
-
-
-def _count_messages_tokens(messages: list[dict[str, Any]]) -> int:
-    """Estimate the token count of the messages list using cl100k_base encoding."""
-    total = 0
-    for msg in messages:
-        content = msg.get("content") or ""
-        if isinstance(content, str):
-            total += len(_TIKTOKEN_ENCODING.encode(content))
-        elif isinstance(content, list):
-            for part in content:
-                if isinstance(part, dict) and isinstance(part.get("text"), str):
-                    total += len(_TIKTOKEN_ENCODING.encode(part["text"]))
-        # Tool call arguments and results also count
-        for tc in msg.get("tool_calls") or []:
-            if isinstance(tc, dict):
-                func = tc.get("function", {})
-                total += len(_TIKTOKEN_ENCODING.encode(func.get("arguments", "")))
-    return total
-
-
-def _is_context_overflow_error(exc: Exception) -> bool:
-    """Return True if the exception signals the LLM context window was exceeded."""
-    msg = str(exc).lower()
-    return any(
-        phrase in msg
-        for phrase in (
-            "context_length_exceeded",
-            "context length exceeded",
-            "maximum context length",
-            "prompt_too_long",
-            "prompt is too long",
-            "resource_exhausted",
-            "input is too long",
-            "too many tokens",
-        )
-    )
-
-
 async def run_reflect_agent(
    llm_config: "LLMProvider",
    bank_id: str,
@@ -308,7 +274,7 @@ async def run_reflect_agent(
    bank_profile: dict[str, Any],
    search_mental_models_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
    search_observations_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
-    recall_fn: Callable[[str, int, int], Awaitable[dict[str, Any]]],
+    recall_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
    expand_fn: Callable[[list[str], str], Awaitable[dict[str, Any]]],
    context: str | None = None,
    max_iterations: int = DEFAULT_MAX_ITERATIONS,
@@ -317,7 +283,6 @@ async def run_reflect_agent(
    directives: list[dict[str, Any]] | None = None,
    has_mental_models: bool = False,
    budget: str | None = None,
-    max_context_tokens: int = 100_000,
 ) -> ReflectAgentResult:
    """
    Execute the reflect agent loop using native tool calling.
@@ -425,15 +390,12 @@ async def run_reflect_agent(
            f"total={elapsed_ms}ms"
        )

-    consecutive_errors = 0
    for iteration in range(max_iterations):
        is_last = iteration == max_iterations - 1

        if is_last:
            # Force text response on last iteration - no tools
-            prompt = build_final_prompt(
-                query, context_history, bank_profile, context, max_context_tokens=max_context_tokens
-            )
+            prompt = build_final_prompt(query, context_history, bank_profile, context)
            llm_start = time.time()
            response, usage = await llm_config.call(
                messages=[
@@ -478,91 +440,17 @@ async def run_reflect_agent(
                directives_applied=directives_applied,
            )

-        # Proactive context-window guard: if accumulated messages would exceed the
-        # configured token budget, bail out early and synthesize from what we have.
-        estimated_tokens = _count_messages_tokens(messages)
-        if estimated_tokens >= max_context_tokens and (
-            bool(available_memory_ids) or bool(available_mental_model_ids) or bool(available_observation_ids)
-        ):
-            logger.warning(
-                f"[REFLECT {reflect_id}] Context budget exceeded on iteration {iteration + 1}: "
-                f"~{estimated_tokens} tokens >= {max_context_tokens} limit. Forcing final synthesis."
-            )
-            prompt = build_final_prompt(
-                query, context_history, bank_profile, context, max_context_tokens=max_context_tokens
-            )
-            llm_start = time.time()
-            response, usage = await llm_config.call(
-                messages=[
-                    {"role": "system", "content": FINAL_SYSTEM_PROMPT},
-                    {"role": "user", "content": prompt},
-                ],
-                scope="reflect",
-                max_completion_tokens=max_tokens,
-                return_usage=True,
-            )
-            llm_duration = int((time.time() - llm_start) * 1000)
-            total_input_tokens += usage.input_tokens
-            total_output_tokens += usage.output_tokens
-            llm_trace.append(
-                {
-                    "scope": "final",
-                    "duration_ms": llm_duration,
-                    "input_tokens": usage.input_tokens,
-                    "output_tokens": usage.output_tokens,
-                }
-            )
-            answer = _clean_answer_text(response.strip())
-
-            structured_output = None
-            if response_schema and answer:
-                structured_output, struct_in, struct_out = await _generate_structured_output(
-                    answer, response_schema, llm_config, reflect_id
-                )
-                total_input_tokens += struct_in
-                total_output_tokens += struct_out
-
-            _log_completion(answer, iteration + 1, forced=True)
-            return ReflectAgentResult(
-                text=answer,
-                structured_output=structured_output,
-                iterations=iteration + 1,
-                tools_called=total_tools_called,
-                tool_trace=tool_trace,
-                llm_trace=_get_llm_trace(),
-                usage=_get_usage(),
-                directives_applied=directives_applied,
-            )
-
        # Call LLM with tools
        llm_start = time.time()

-        # Determine tool_choice for this iteration.
-        # Force the full hierarchical retrieval path before allowing auto:
-        # With mental models:
-        #   0 → search_mental_models, 1 → search_observations, 2 → recall, 3+ → auto
-        # Without mental models:
-        #   0 → search_observations, 1 → recall, 2+ → auto
-        if iteration == 0 and has_mental_models:
-            iter_tool_choice: str | dict = {"type": "function", "function": {"name": "search_mental_models"}}
-        elif iteration == 0:
-            iter_tool_choice = {"type": "function", "function": {"name": "search_observations"}}
-        elif iteration == 1 and has_mental_models:
-            iter_tool_choice = {"type": "function", "function": {"name": "search_observations"}}
-        elif iteration == 1 or (iteration == 2 and has_mental_models):
-            iter_tool_choice = {"type": "function", "function": {"name": "recall"}}
-        else:
-            iter_tool_choice = "auto"
-
        try:
            result = await llm_config.call_with_tools(
                messages=messages,
                tools=tools,
                scope="reflect_tool_call",
-                tool_choice=iter_tool_choice,
+                tool_choice="required" if iteration == 0 else "auto",  # Force tool use on first iteration
            )
            llm_duration = int((time.time() - llm_start) * 1000)
-            consecutive_errors = 0
            total_input_tokens += result.input_tokens
            total_output_tokens += result.output_tokens
            llm_trace.append(
@@ -576,25 +464,15 @@ async def run_reflect_agent(

        except Exception as e:
            err_duration = int((time.time() - llm_start) * 1000)
-            consecutive_errors += 1
            logger.warning(f"[REFLECT {reflect_id}] LLM error on iteration {iteration + 1}: {e} ({err_duration}ms)")
            llm_trace.append({"scope": f"agent_{iteration + 1}_err", "duration_ms": err_duration})
+            # Guardrail: If no evidence gathered yet, retry
            has_gathered_evidence = (
                bool(available_memory_ids) or bool(available_mental_model_ids) or bool(available_observation_ids)
            )
-            # Context overflow errors must never be retried — retrying would only make them worse.
-            # Skip straight to final synthesis with whatever evidence we have.
-            if _is_context_overflow_error(e):
-                logger.warning(
-                    f"[REFLECT {reflect_id}] Context window exceeded on iteration {iteration + 1}, "
-                    "forcing final synthesis from gathered evidence."
-                )
-            # For other errors: retry if no evidence yet (but cap consecutive errors to avoid long hangs)
-            elif not has_gathered_evidence and iteration < max_iterations - 1 and consecutive_errors < 2:
+            if not has_gathered_evidence and iteration < max_iterations - 1:
                continue
-            prompt = build_final_prompt(
-                query, context_history, bank_profile, context, max_context_tokens=max_context_tokens
-            )
+            prompt = build_final_prompt(query, context_history, bank_profile, context)
            llm_start = time.time()
            response, usage = await llm_config.call(
                messages=[
@@ -665,9 +543,7 @@ async def run_reflect_agent(
                    directives_applied=directives_applied,
                )
            # Empty response, force final
-            prompt = build_final_prompt(
-                query, context_history, bank_profile, context, max_context_tokens=max_context_tokens
-            )
+            prompt = build_final_prompt(query, context_history, bank_profile, context)
            llm_start = time.time()
            response, usage = await llm_config.call(
                messages=[
@@ -931,9 +807,9 @@ async def _process_done_tool(
        answer = "No answer provided."

    # Validate IDs (only include IDs that were actually retrieved)
-    used_memory_ids = [mid for mid in (args.get("memory_ids") or []) if mid in available_memory_ids]
-    used_mental_model_ids = [mid for mid in (args.get("mental_model_ids") or []) if mid in available_mental_model_ids]
-    used_observation_ids = [oid for oid in (args.get("observation_ids") or []) if oid in available_observation_ids]
+    used_memory_ids = [mid for mid in args.get("memory_ids", []) if mid in available_memory_ids]
+    used_mental_model_ids = [mid for mid in args.get("mental_model_ids", []) if mid in available_mental_model_ids]
+    used_observation_ids = [oid for oid in args.get("observation_ids", []) if oid in available_observation_ids]

    # Generate structured output if schema provided
    structured_output = None
@@ -969,7 +845,7 @@ async def _execute_tool_with_timing(
    tc: "LLMToolCall",
    search_mental_models_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
    search_observations_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
-    recall_fn: Callable[[str, int, int], Awaitable[dict[str, Any]]],
+    recall_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
    expand_fn: Callable[[list[str], str], Awaitable[dict[str, Any]]],
 ) -> tuple[dict[str, Any], int]:
    """Execute a tool call and return result with timing."""
@@ -1041,7 +917,7 @@ async def _execute_tool(
    args: dict[str, Any],
    search_mental_models_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
    search_observations_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
-    recall_fn: Callable[[str, int, int], Awaitable[dict[str, Any]]],
+    recall_fn: Callable[[str, int], Awaitable[dict[str, Any]]],
    expand_fn: Callable[[list[str], str], Awaitable[dict[str, Any]]],
 ) -> dict[str, Any]:
    """Execute a single tool by name."""
@@ -1067,8 +943,7 @@ async def _execute_tool(
        if not query:
            return {"error": "recall requires a query parameter"}
        max_tokens = max(int(args.get("max_tokens") or 2048), 1000)  # Default 2048, min 1000
-        max_chunk_tokens = max(int(args.get("max_chunk_tokens") or 1000), 1000)  # Always enabled, min 1000
-        return await recall_fn(query, max_tokens, max_chunk_tokens)
+        return await recall_fn(query, max_tokens)

    elif tool_name == "expand":
        memory_ids = args.get("memory_ids", [])
@@ -1096,9 +971,9 @@ def _summarize_input(tool_name: str, args: dict[str, Any]) -> str:
    elif tool_name == "recall":
        query = args.get("query", "")
        query_preview = f"'{query[:30]}...'" if len(query) > 30 else f"'{query}'"
+        # Show actual value used (default 2048, min 1000)
        max_tokens = max(int(args.get("max_tokens") or 2048), 1000)
-        max_chunk_tokens = max(int(args.get("max_chunk_tokens") or 1000), 1000)
-        return f"(query={query_preview}, max_tokens={max_tokens}, max_chunk_tokens={max_chunk_tokens})"
+        return f"(query={query_preview}, max_tokens={max_tokens})"
    elif tool_name == "expand":
        memory_ids = args.get("memory_ids", [])
        depth = args.get("depth", "chunk")
@@ -10,30 +10,59 @@ The reflect agent uses hierarchical retrieval:
 import json
 from typing import Any

-import tiktoken
-
-_TIKTOKEN_ENCODING = tiktoken.get_encoding("cl100k_base")
-
-# Fraction of max_context_tokens reserved for tool results in the final synthesis prompt.
-# The remainder covers the system prompt, question, bank context, and output tokens.
-_FINAL_PROMPT_CONTEXT_FRACTION = 0.8
-

 def _extract_directive_rules(directives: list[dict[str, Any]]) -> list[str]:
-    """Extract directive rules as a list of strings."""
+    """
+    Extract directive rules as a list of strings.
+
+    Args:
+        directives: List of directives with name and content
+
+    Returns:
+        List of directive rule strings
+    """
    rules = []
    for directive in directives:
-        name = directive.get("name", "")
+        directive_name = directive.get("name", "")
+        # New format: directives have direct content field
        content = directive.get("content", "")
        if content:
-            rules.append(f"**{name}**: {content}" if name else content)
+            if directive_name:
+                rules.append(f"**{directive_name}**: {content}")
+            else:
+                rules.append(content)
+        else:
+            # Legacy format: check for observations
+            observations = directive.get("observations", [])
+            if observations:
+                for obs in observations:
+                    # Support both Pydantic Observation objects and dicts
+                    if hasattr(obs, "title"):
+                        title = obs.title
+                        obs_content = obs.content
+                    else:
+                        title = obs.get("title", "")
+                        obs_content = obs.get("content", "")
+                    if title and obs_content:
+                        rules.append(f"**{title}**: {obs_content}")
+                    elif obs_content:
+                        rules.append(obs_content)
+            elif directive_name:
+                # Fallback to description
+                desc = directive.get("description", "")
+                if desc:
+                    rules.append(f"**{directive_name}**: {desc}")
    return rules


 def build_directives_section(directives: list[dict[str, Any]]) -> str:
-    """Build the directives section for the system prompt.
+    """
+    Build the directives section for the system prompt.

    Directives are hard rules that MUST be followed in all responses.
+
+    Args:
+        directives: List of directive mental models with observations
    """
    if not directives:
        return ""
@@ -140,12 +169,6 @@ def build_system_prompt_for_tools(

    parts.extend(
        [
-            "## LANGUAGE RULE (default - directives take precedence)",
-            "- By default, detect the language of the user's question and respond in that SAME language.",
-            "- If the question is in Chinese, respond in Chinese. If in Japanese, respond in Japanese.",
-            "- IMPORTANT: The DIRECTIVES section above has HIGHER PRIORITY than this rule.",
-            "  If a directive specifies a language (e.g. 'Always respond in French'), follow the directive.",
-            "",
            "## CRITICAL RULES",
            "- ONLY use information from tool results - no external knowledge or guessing",
            "- You SHOULD synthesize, infer, and reason from the retrieved memories",
@@ -182,7 +205,6 @@ def build_system_prompt_for_tools(
                "### 3. RAW FACTS (recall) - Ground Truth",
                "- Individual memories (world facts and experiences)",
                "- Use when: no mental models/observations exist, they're stale, or you need specific details",
-                "- MANDATORY: If search_mental_models and search_observations both return 0 results, you MUST call recall() before giving up",
                "- This is the source of truth that other levels are built from",
                "",
            ]
@@ -200,7 +222,6 @@ def build_system_prompt_for_tools(
                "### 2. RAW FACTS (recall) - Ground Truth",
                "- Individual memories (world facts and experiences)",
                "- Use when: no observations exist, they're stale, or you need specific details",
-                "- MANDATORY: If search_observations returns 0 results or count=0, you MUST call recall() before giving up",
                "- This is the source of truth that observations are built from",
                "",
            ]
@@ -278,7 +299,7 @@ def build_system_prompt_for_tools(
        parts.extend(
            [
                "1. First, try search_observations() - check for consolidated knowledge",
-                "2. If search_observations returns 0 results OR observations are stale, you MUST call recall() for raw facts",
+                "2. If observations are stale OR you need specific details, use recall() for raw facts",
                "3. Use expand() if you need more context on specific memories",
                "4. When ready, call done() with your answer and supporting IDs",
            ]
@@ -294,7 +315,6 @@ def build_system_prompt_for_tools(
            "- Format for clarity and readability with proper spacing and hierarchy",
            "- NEVER include memory IDs, UUIDs, or 'Memory references' in the answer text",
            "- Put IDs ONLY in the memory_ids/mental_model_ids/observation_ids arrays, not in the answer",
-            "- CRITICAL: This is a NON-CONVERSATIONAL system. NEVER ask follow-up questions, offer further assistance, or suggest next steps. Your answer must be complete and self-contained. The user cannot reply.",
        ]
    )

@@ -402,7 +422,6 @@ def build_final_prompt(
    context_history: list[dict],
    bank_profile: dict,
    additional_context: str | None = None,
-    max_context_tokens: int = 100_000,
 ) -> str:
    """Build the final prompt when forcing a text response (no tools)."""
    parts = []
@@ -432,32 +451,18 @@ def build_final_prompt(
    if additional_context:
        parts.append(f"\n## Additional Context\n{additional_context}")

-    # Tool call history — include as many entries as fit within the token budget,
-    # preferring the most recent calls (they tend to be the most targeted).
+    # Tool call history
    if context_history:
        parts.append("\n## Retrieved Data (synthesize and reason from this data)")
-        token_budget = int(max_context_tokens * _FINAL_PROMPT_CONTEXT_FRACTION)
-        # Render entries newest-first, then reverse so the prompt reads chronologically.
-        rendered: list[str] = []
-        truncated = False
-        for entry in reversed(context_history):
+        for entry in context_history:
            tool = entry["tool"]
            output = entry["output"]
+            # Format as proper JSON for LLM readability
            try:
                output_str = json.dumps(output, indent=2, default=str)
            except (TypeError, ValueError):
                output_str = str(output)
-            block = f"\n### From {tool}:\n```json\n{output_str}\n```"
-            block_tokens = len(_TIKTOKEN_ENCODING.encode(block))
-            if block_tokens > token_budget:
-                truncated = True
-                break
-            rendered.append(block)
-            token_budget -= block_tokens
-        for block in reversed(rendered):
-            parts.append(block)
-        if truncated:
-            parts.append("\n*Note: Some earlier tool results were omitted to stay within the context window.*")
+            parts.append(f"\n### From {tool}:\n```json\n{output_str}\n```")
    else:
        parts.append("\n## Retrieved Data\nNo data was retrieved.")

@@ -505,6 +510,4 @@ CRITICAL: Output ONLY the final synthesized answer. Do NOT include:
 - Meta-commentary about what you're doing ("I'll search...", "Let me analyze...")
 - Explanations of your reasoning process
 - Descriptions of your approach
-Just provide the direct answer with proper markdown formatting.
-
-CRITICAL: This is a NON-CONVERSATIONAL system. NEVER ask follow-up questions, offer to search again, suggest alternatives, or end with anything like "Would you like me to..." or "Let me know if...". The user cannot reply. Your answer must be complete and self-contained."""
+Just provide the direct answer with proper markdown formatting."""
@@ -9,7 +9,7 @@ Implements hierarchical retrieval:

 import logging
 import uuid
-from datetime import datetime, timezone
+from datetime import datetime, timedelta, timezone
 from typing import TYPE_CHECKING, Any

 if TYPE_CHECKING:
@@ -20,6 +20,9 @@ if TYPE_CHECKING:

 logger = logging.getLogger(__name__)

+# Observation is considered stale if not updated in this many days
+STALE_THRESHOLD_DAYS = 7
+

 async def tool_search_mental_models(
    conn: "Connection",
@@ -30,7 +33,6 @@ async def tool_search_mental_models(
    tags: list[str] | None = None,
    tags_match: str = "any",
    exclude_ids: list[str] | None = None,
-    pending_consolidation: int = 0,
 ) -> dict[str, Any]:
    """
    Search user-curated mental models by semantic similarity.
@@ -85,6 +87,7 @@ async def tool_search_mental_models(
        *params,
    )

+    now = datetime.now(timezone.utc)
    mental_models = []

    for row in rows:
@@ -92,10 +95,11 @@ async def tool_search_mental_models(
        if last_refreshed_at and last_refreshed_at.tzinfo is None:
            last_refreshed_at = last_refreshed_at.replace(tzinfo=timezone.utc)

-        # A mental model is stale when there are memories that haven't been consolidated yet —
-        # the same signal used for observations staleness.
-        is_stale = pending_consolidation > 0
-        staleness_reason = f"{pending_consolidation} memories pending consolidation" if is_stale else None
+        # Calculate freshness
+        is_stale = False
+        if last_refreshed_at:
+            age = now - last_refreshed_at
+            is_stale = age > timedelta(days=STALE_THRESHOLD_DAYS)

        mental_models.append(
            {
@@ -106,7 +110,6 @@ async def tool_search_mental_models(
                "relevance": round(row["relevance"], 4),
                "updated_at": last_refreshed_at.isoformat() if last_refreshed_at else None,
                "is_stale": is_stale,
-                "staleness_reason": staleness_reason,
            }
        )

@@ -129,7 +132,7 @@ async def tool_search_observations(
    pending_consolidation: int = 0,
 ) -> dict[str, Any]:
    """
-    Search consolidated observations using recall with include_source_facts.
+    Search consolidated observations using recall with include_observations.

    Observations are auto-generated from memories. Returns freshness info
    so the agent knows if it should also verify with recall().
@@ -146,24 +149,72 @@ async def tool_search_observations(
        pending_consolidation: Number of memories waiting to be consolidated

    Returns:
-        Dict with matching observations including freshness info and source memories
+        Dict with matching observations including freshness info
    """
+    from ..memory_engine import fq_table
+
+    # Use recall to search observations (they come back in results field when fact_type=["observation"])
    result = await memory_engine.recall_async(
        bank_id=bank_id,
        query=query,
-        fact_type=["observation"],
-        max_tokens=max_tokens,
+        fact_type=["observation"],  # Only retrieve observations
+        max_tokens=max_tokens,  # Token budget controls how many observations are returned
        enable_trace=False,
        request_context=request_context,
        tags=tags,
        tags_match=tags_match,
-        include_source_facts=True,
-        max_source_facts_tokens=-1,  # No token limit — include all source facts
        _connection_budget=1,
        _quiet=True,
    )

-    is_stale = pending_consolidation > 0
+    observations = []
+
+    # When fact_type=["observation"], results come back in `results` field as MemoryFact objects
+    # We need to fetch additional fields (proof_count, source_memory_ids) from the database
+    if result.results:
+        obs_ids = [m.id for m in result.results]
+
+        # Fetch proof_count and source_memory_ids for these observations
+        pool = await memory_engine._get_pool()
+        async with pool.acquire() as conn:
+            obs_rows = await conn.fetch(
+                f"""
+                SELECT id, proof_count, source_memory_ids
+                FROM {fq_table("memory_units")}
+                WHERE id = ANY($1::uuid[])
+                """,
+                obs_ids,
+            )
+            obs_data = {str(row["id"]): row for row in obs_rows}
+
+        for m in result.results:
+            # Get additional data from DB lookup
+            extra = obs_data.get(m.id, {})
+            proof_count = extra.get("proof_count", 1) if extra else 1
+            source_ids = extra.get("source_memory_ids", []) if extra else []
+            # Convert UUIDs to strings
+            source_memory_ids = [str(sid) for sid in (source_ids or [])]
+
+            # Determine staleness
+            is_stale = False
+            staleness_reason = None
+            if pending_consolidation > 0:
+                is_stale = True
+                staleness_reason = f"{pending_consolidation} memories pending consolidation"
+
+            observations.append(
+                {
+                    "id": str(m.id),
+                    "text": m.text,
+                    "proof_count": proof_count,
+                    "source_memory_ids": source_memory_ids,
+                    "tags": m.tags or [],
+                    "is_stale": is_stale,
+                    "staleness_reason": staleness_reason,
+                }
+            )
+
+    # Return freshness info (more understandable than raw pending_consolidation count)
    if pending_consolidation == 0:
        freshness = "up_to_date"
    elif pending_consolidation < 10:
@@ -173,10 +224,8 @@ async def tool_search_observations(

    return {
        "query": query,
-        "count": len(result.results),
-        "observations": [m.model_dump() for m in result.results],
-        "source_facts": {k: v.model_dump() for k, v in (result.source_facts or {}).items()},
-        "is_stale": is_stale,
+        "count": len(observations),
+        "observations": observations,
        "freshness": freshness,
    }

@@ -187,10 +236,10 @@ async def tool_recall(
    query: str,
    request_context: "RequestContext",
    max_tokens: int = 2048,
+    max_results: int = 50,
    tags: list[str] | None = None,
    tags_match: str = "any",
    connection_budget: int = 1,
-    max_chunk_tokens: int = 1000,
 ) -> dict[str, Any]:
    """
    Search memories using TEMPR retrieval.
@@ -204,19 +253,18 @@ async def tool_recall(
        query: Search query
        request_context: Request context for authentication
        max_tokens: Maximum tokens for results (default 2048)
+        max_results: Maximum number of results
        tags: Filter by tags (includes untagged memories)
        tags_match: How to match tags - "any" (OR), "all" (AND), or "exact"
        connection_budget: Max DB connections for this recall (default 1 for internal ops)
-        max_chunk_tokens: Maximum tokens for raw source chunk text (default 1000, always included)

    Returns:
-        Dict with list of matching memories including raw chunk text
+        Dict with list of matching memories
    """
-    include_chunks = True
    result = await memory_engine.recall_async(
        bank_id=bank_id,
        query=query,
-        fact_type=["experience", "world"],
+        fact_type=["experience", "world"],  # Exclude opinions and observations
        max_tokens=max_tokens,
        enable_trace=False,
        request_context=request_context,
@@ -224,14 +272,24 @@ async def tool_recall(
        tags_match=tags_match,
        _connection_budget=connection_budget,
        _quiet=True,  # Suppress logging for internal operations
-        include_chunks=include_chunks,
-        max_chunk_tokens=max_chunk_tokens,
    )

+    memories = []
+    for m in result.results[:max_results]:
+        memories.append(
+            {
+                "id": str(m.id),
+                "text": m.text,
+                "type": m.fact_type,
+                "entities": m.entities or [],
+                "occurred": m.occurred_start,  # Already ISO format string
+            }
+        )
+
    return {
        "query": query,
-        "memories": [m.model_dump() for m in result.results],
-        "chunks": {k: v.model_dump() for k, v in (result.chunks or {}).items()},
+        "count": len(memories),
+        "memories": memories,
    }


@@ -47,8 +47,7 @@ TOOL_SEARCH_OBSERVATIONS = {
        "description": (
            "Search consolidated observations (auto-generated knowledge). These are automatically "
            "synthesized from memories. Returns observations with freshness info (updated_at, is_stale). "
-            "If an observation is STALE, you should ALSO use recall() to verify with current facts. "
-            "IMPORTANT: If search_mental_models is available, you MUST call it FIRST before using this tool."
+            "If an observation is STALE, you should ALSO use recall() to verify with current facts."
        ),
        "parameters": {
            "type": "object",
@@ -96,10 +95,6 @@ TOOL_RECALL = {
                    "type": "integer",
                    "description": "Optional limit on result size (default 2048). Use higher values for broader searches.",
                },
-                "max_chunk_tokens": {
-                    "type": "integer",
-                    "description": "Maximum tokens for raw source chunk text included alongside each memory fact (default 1000, min 1000). Chunks provide the surrounding context the fact was extracted from. Increase for broader context.",
-                },
            },
            "required": ["reason", "query"],
        },
@@ -144,7 +139,7 @@ TOOL_DONE_ANSWER = {
            "properties": {
                "answer": {
                    "type": "string",
-                    "description": "Your response as well-formatted markdown. Use headers, lists, bold/italic, and code blocks for clarity. NEVER include memory IDs, UUIDs, or 'Memory references' in this text - put IDs only in memory_ids array. LANGUAGE: By default, write in the SAME language as the user's question. However, if a language directive in the system prompt specifies a different language, follow that directive instead.",
+                    "description": "Your response as well-formatted markdown. Use headers, lists, bold/italic, and code blocks for clarity. NEVER include memory IDs, UUIDs, or 'Memory references' in this text - put IDs only in memory_ids array.",
                },
                "memory_ids": {
                    "type": "array",
@@ -195,11 +190,7 @@ def _build_done_tool_with_directives(directive_rules: list[str]) -> dict:
                "properties": {
                    "answer": {
                        "type": "string",
-                        "description": (
-                            "Your response as well-formatted markdown. Use headers, lists, bold/italic, and code blocks for clarity. "
-                            "NEVER include memory IDs, UUIDs, or 'Memory references' in this text - put IDs only in memory_ids array. "
-                            f"MANDATORY: Your answer MUST comply with ALL directives:\n{rules_list}"
-                        ),
+                        "description": "Your response as well-formatted markdown. Use headers, lists, bold/italic, and code blocks for clarity. NEVER include memory IDs, UUIDs, or 'Memory references' in this text - put IDs only in memory_ids array.",
                    },
                    "memory_ids": {
                        "type": "array",
@@ -159,10 +159,6 @@ class MemoryFact(BaseModel):
        None, description="ID of the chunk this fact was extracted from (format: bank_id_document_id_chunk_index)"
    )
    tags: list[str] | None = Field(None, description="Visibility scope tags associated with this fact")
-    source_fact_ids: list[str] | None = Field(
-        None,
-        description="IDs of source facts this observation was derived from (observation type only, when source_facts is enabled)",
-    )


 class ChunkInfo(BaseModel):
@@ -230,9 +226,6 @@ class RecallResult(BaseModel):
    chunks: dict[str, ChunkInfo] | None = Field(
        None, description="Chunks for facts, keyed by '{document_id}_{chunk_index}'"
    )
-    source_facts: dict[str, MemoryFact] | None = Field(
-        None, description="Source facts for observation-type results, keyed by fact ID"
-    )


 class ReflectResult(BaseModel):
@@ -5,6 +5,7 @@ This package contains modular components for the retain operation:
 - types: Type definitions for retain pipeline
 - fact_extraction: Extract facts from content
 - embedding_processing: Augment texts and generate embeddings
+- deduplication: Check for duplicate facts
 - entity_processing: Process and resolve entities
 - link_creation: Create temporal, semantic, entity, and causal links
 - chunk_storage: Handle chunk storage
@@ -13,6 +14,7 @@ This package contains modular components for the retain operation:

 from . import (
    chunk_storage,
+    deduplication,
    embedding_processing,
    entity_processing,
    fact_extraction,
@@ -33,6 +35,7 @@ __all__ = [
    # Modules
    "fact_extraction",
    "embedding_processing",
+    "deduplication",
    "entity_processing",
    "link_creation",
    "chunk_storage",
@@ -0,0 +1,85 @@
+"""
+Deduplication logic for retain pipeline.
+
+Checks for duplicate facts using semantic similarity and temporal proximity.
+"""
+
+import logging
+from collections import defaultdict
+from datetime import UTC
+
+from .types import ProcessedFact
+
+logger = logging.getLogger(__name__)
+
+
+async def check_duplicates_batch(conn, bank_id: str, facts: list[ProcessedFact], duplicate_checker_fn) -> list[bool]:
+    """
+    Check which facts are duplicates using batched time-window queries.
+
+    Groups facts by 12-hour time buckets to efficiently check for duplicates
+    within a 24-hour window.
+
+    Args:
+        conn: Database connection
+        bank_id: Bank identifier
+        facts: List of ProcessedFact objects to check
+        duplicate_checker_fn: Async function(conn, bank_id, texts, embeddings, date, time_window_hours)
+                              that returns List[bool] indicating duplicates
+
+    Returns:
+        List of boolean flags (same length as facts) indicating if each fact is a duplicate
+    """
+    if not facts:
+        return []
+
+    # Group facts by event_date (rounded to 12-hour buckets) for efficient batching
+    time_buckets = defaultdict(list)
+    for idx, fact in enumerate(facts):
+        # Use occurred_start if available, otherwise use mentioned_at
+        # For deduplication purposes, we need a time reference
+        fact_date = fact.occurred_start if fact.occurred_start is not None else fact.mentioned_at
+
+        # Defensive: if both are None (shouldn't happen), use now()
+        if fact_date is None:
+            from datetime import datetime
+
+            fact_date = datetime.now(UTC)
+
+        # Round to 12-hour bucket to group similar times
+        bucket_key = fact_date.replace(hour=(fact_date.hour // 12) * 12, minute=0, second=0, microsecond=0)
+        time_buckets[bucket_key].append((idx, fact))
+
+    # Process each bucket in batch
+    all_is_duplicate = [False] * len(facts)
+
+    for bucket_date, bucket_items in time_buckets.items():
+        indices = [item[0] for item in bucket_items]
+        texts = [item[1].fact_text for item in bucket_items]
+        embeddings = [item[1].embedding for item in bucket_items]
+
+        # Check duplicates for this time bucket
+        dup_flags = await duplicate_checker_fn(conn, bank_id, texts, embeddings, bucket_date, time_window_hours=24)
+
+        # Map results back to original indices
+        for idx, is_dup in zip(indices, dup_flags):
+            all_is_duplicate[idx] = is_dup
+
+    return all_is_duplicate
+
+
+def filter_duplicates(facts: list[ProcessedFact], is_duplicate_flags: list[bool]) -> list[ProcessedFact]:
+    """
+    Filter out duplicate facts based on duplicate flags.
+
+    Args:
+        facts: List of ProcessedFact objects
+        is_duplicate_flags: Boolean flags indicating which facts are duplicates
+
+    Returns:
+        List of non-duplicate facts
+    """
+    if len(facts) != len(is_duplicate_flags):
+        raise ValueError(f"Mismatch between facts ({len(facts)}) and flags ({len(is_duplicate_flags)})")
+
+    return [fact for fact, is_dup in zip(facts, is_duplicate_flags) if not is_dup]
@@ -27,21 +27,11 @@ def augment_texts_with_dates(facts: list[ExtractedFact], format_date_fn) -> list
    """
    augmented_texts = []
    for fact in facts:
-        # Use occurred_start as the representative date, fall back to mentioned_at
+        # Use occurred_start as the representative date
        fact_date = fact.occurred_start or fact.mentioned_at
-        # Augment text with date and entity names for embedding (but store original text in DB)
-        # Entity names (including key:value labels) improve retrieval without polluting stored content
-        if fact_date is not None:
-            readable_date = format_date_fn(fact_date)
-            if fact.occurred_end and fact.occurred_end != fact.occurred_start:
-                readable_end = format_date_fn(fact.occurred_end)
-                augmented_text = f"{fact.fact_text} (happened from {readable_date} to {readable_end})"
-            else:
-                augmented_text = f"{fact.fact_text} (happened in {readable_date})"
-        else:
-            augmented_text = fact.fact_text
-        if fact.entities:
-            augmented_text = f"{augmented_text} [{', '.join(fact.entities)}]"
+        readable_date = format_date_fn(fact_date)
+        # Augment text with date for embedding (but store original text in DB)
+        augmented_text = f"{fact.fact_text} (happened in {readable_date})"
        augmented_texts.append(augmented_text)
    return augmented_texts

@@ -41,9 +41,10 @@ async def generate_embeddings_batch(embeddings_backend, texts: list[str]) -> lis
        List of embeddings in same order as input texts
    """
    try:
+        # Run embeddings in thread pool to avoid blocking event loop
        loop = asyncio.get_event_loop()
        embeddings = await loop.run_in_executor(
-            None,
+            None,  # Use default thread pool
            embeddings_backend.encode,
            texts,
        )
@@ -1,194 +0,0 @@
-"""
-Entity labels models and helpers for retain pipeline.
-
-Defines a controlled vocabulary of key:value classification labels
-(e.g., 'pedagogy:scaffolding', 'interest:active') that are extracted
-at retain time and stored as entities.
-"""
-
-from typing import Literal
-
-from pydantic import BaseModel, Field, create_model
-
-
-class LabelValue(BaseModel):
-    """A single allowed value for a label group."""
-
-    value: str
-    description: str = ""
-
-
-class LabelGroup(BaseModel):
-    """A label group (dimension) with its type and allowed values."""
-
-    key: str
-    description: str = ""
-    type: Literal["value", "multi-values", "text"] = "value"
-    optional: bool = True
-    tag: bool = False
-    values: list[LabelValue] = []
-
-
-class EntityLabelsConfig(BaseModel):
-    """Entity labels configuration for a bank (controlled vocabulary)."""
-
-    attributes: list[LabelGroup] = []
-
-
-def parse_entity_labels(raw: dict | list | None) -> EntityLabelsConfig | None:
-    """
-    Parse raw entity labels config into EntityLabelsConfig.
-
-    Accepts:
-    - None → returns None
-    - list → list of attribute dicts (each may use legacy free_values/multi_value or new type field)
-    - dict → {attributes: [...]}
-
-    Legacy migration (backward-compat):
-    - free_values=True          → type="text"
-    - multi_value=True          → type="multi-values"
-    - neither / free_values=False → type="value"
-
-    Args:
-        raw: Raw entity labels config from bank config
-
-    Returns:
-        EntityLabelsConfig or None if raw is None/empty
-    """
-    if raw is None:
-        return None
-
-    if isinstance(raw, list):
-        if not raw:
-            return None
-        attributes = [LabelGroup.model_validate(_migrate_label_group(a)) for a in raw]
-        return EntityLabelsConfig(attributes=attributes)
-
-    if isinstance(raw, dict):
-        attrs_raw = raw.get("attributes", [])
-        if not attrs_raw:
-            return None
-        attributes = [LabelGroup.model_validate(_migrate_label_group(a)) for a in attrs_raw]
-        return EntityLabelsConfig(attributes=attributes)
-
-    return None
-
-
-def _migrate_label_group(raw: dict) -> dict:
-    """Migrate legacy free_values/multi_value fields to the new type field."""
-    if not isinstance(raw, dict) or "type" in raw:
-        return raw
-    patched = dict(raw)
-    if patched.get("free_values"):
-        patched["type"] = "text"
-    elif patched.get("multi_value"):
-        patched["type"] = "multi-values"
-    else:
-        patched["type"] = "value"
-    # Remove legacy keys so Pydantic doesn't error on unknown fields
-    patched.pop("free_values", None)
-    patched.pop("multi_value", None)
-    return patched
-
-
-def build_labels_model(labels_cfg: EntityLabelsConfig) -> type[BaseModel] | None:
-    """
-    Build a dynamic Pydantic model for structured label extraction.
-
-    Each LabelGroup becomes a typed field based on its type:
-    - type="text"                        → str | None  (always optional)
-    - type="value",   optional=True      → Literal["v1","v2"] | None
-    - type="value",   optional=False     → Literal["v1","v2"]  (required)
-    - type="multi-values"                → list[Literal["v1","v2"]]
-
-    Args:
-        labels_cfg: Parsed EntityLabelsConfig
-
-    Returns:
-        Dynamic Pydantic model class, or None if no groups defined
-    """
-    fields: dict = {}
-    for group in labels_cfg.attributes:
-        if not group.key:
-            continue
-        description = group.description or group.key
-
-        if group.type == "text":
-            # Free-form: any string value accepted, always optional
-            fields[group.key] = (str | None, Field(default=None, description=description))
-        else:
-            # Enum-constrained: must have defined values
-            if not group.values:
-                continue
-            values = tuple(v.value for v in group.values if v.value)
-            if not values:
-                continue
-            # Literal[("v1", "v2")] is equivalent to Literal["v1", "v2"] in Python 3.11+
-            literal_type = Literal[values]  # type: ignore[valid-type]
-            if group.type == "multi-values":
-                fields[group.key] = (
-                    list[literal_type],  # type: ignore[valid-type]
-                    Field(default_factory=list, description=description),
-                )
-            elif group.optional:
-                fields[group.key] = (
-                    literal_type | None,  # type: ignore[valid-type]
-                    Field(default=None, description=description),
-                )
-            else:
-                fields[group.key] = (
-                    literal_type,  # type: ignore[valid-type]
-                    Field(description=description),
-                )
-
-    if not fields:
-        return None
-
-    return create_model("Labels", **fields)
-
-
-def is_label_entity(text: str, labels_cfg: EntityLabelsConfig, labels_lookup: set[str]) -> bool:
-    """
-    Return True if entity text belongs to any configured label group.
-
-    For enum groups: checks the pre-built lookup set.
-    For text groups: checks that the text starts with a known key prefix.
-    """
-    if text.lower() in labels_lookup:
-        return True
-    for group in labels_cfg.attributes:
-        if group.type == "text" and group.key and text.lower().startswith(f"{group.key.lower()}:"):
-            return True
-    return False
-
-
-def build_labels_lookup(labels_cfg: EntityLabelsConfig | list | None) -> set[str]:
-    """
-    Build a set of valid 'key:value' label strings (lowercase) for fast lookup.
-
-    Accepts either EntityLabelsConfig or raw list/None for backwards compatibility.
-
-    Args:
-        labels_cfg: EntityLabelsConfig, raw list of attribute dicts, or None
-
-    Returns:
-        Set of lowercase 'key:value' strings
-    """
-    if labels_cfg is None:
-        return set()
-
-    # Accept raw list/dict for backwards compatibility
-    if not isinstance(labels_cfg, EntityLabelsConfig):
-        parsed = parse_entity_labels(labels_cfg)
-        if parsed is None:
-            return set()
-        labels_cfg = parsed
-
-    valid = set()
-    for group in labels_cfg.attributes:
-        if group.type == "text":
-            continue  # No fixed vocabulary — all values accepted in post-processing
-        for v in group.values:
-            if group.key and v.value:
-                valid.add(f"{group.key}:{v.value}".lower())
-    return valid
@@ -20,7 +20,6 @@ async def process_entities_batch(
    facts: list[ProcessedFact],
    log_buffer: list[str] = None,
    user_entities_per_content: dict[int, list[dict]] = None,
-    entity_labels: list | None = None,
 ) -> list[EntityLink]:
    """
    Process entities for all facts and create entity links.
@@ -91,7 +90,6 @@ async def process_entities_batch(
        fact_dates,
        entities_per_fact,
        log_buffer,  # Pass log_buffer for detailed logging
-        entity_labels=entity_labels,
    )

    return entity_links
@@ -47,8 +47,6 @@ async def insert_facts_batch(
    chunk_ids = []
    document_ids = []
    tags_list = []
-    observation_scopes_list = []
-    text_signals_list = []

    for fact in facts:
        fact_texts.append(_sanitize_text(fact.fact_text))
@@ -70,19 +68,6 @@ async def insert_facts_batch(
        document_ids.append(fact.document_id if fact.document_id else document_id)
        # Convert tags to JSON string for proper batch insertion (PostgreSQL unnest doesn't handle 2D arrays well)
        tags_list.append(json.dumps(fact.tags if fact.tags else []))
-        # observation_scopes: stored as JSONB (string or 2D array), None if not provided
-        observation_scopes_list.append(
-            json.dumps(fact.observation_scopes) if fact.observation_scopes is not None else None
-        )
-        # Build text_signals: entity names + date tokens for enriched BM25 indexing
-        signal_parts = []
-        if fact.entities:
-            signal_parts.extend(e.name for e in fact.entities)
-        if fact.occurred_start:
-            signal_parts.append(fact.occurred_start.strftime("%B %-d %Y"))
-        if fact.occurred_end and fact.occurred_end != fact.occurred_start:
-            signal_parts.append(fact.occurred_end.strftime("%B %-d %Y"))
-        text_signals_list.append(" ".join(signal_parts) if signal_parts else None)

    # Batch insert all facts
    # Note: tags are passed as JSON strings and converted back to varchar[] via jsonb_array_elements_text + array_agg
@@ -90,19 +75,16 @@ async def insert_facts_batch(
    config = get_config()
    if config.text_search_extension == "vchord":
        # VectorChord: manually tokenize and insert search_vector
-        # text_signals (entity names etc.) are included in the tokenize input for enriched BM25
        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[], $15::jsonb[], $16::text[]
+                    $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,
-                       observation_scopes_json, text_signals)
+                       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,
-                                     observation_scopes, text_signals, search_vector)
+                                     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,
@@ -111,30 +93,22 @@ async def insert_facts_batch(
                    (SELECT array_agg(elem) FROM jsonb_array_elements_text(tags_json) AS elem),
                    '{{}}'::varchar[]
                ),
-                observation_scopes_json,
-                text_signals,
-                tokenize(
-                    COALESCE(text, '') || ' ' || COALESCE(context, '') || ' ' || COALESCE(text_signals, ''),
-                    'llmlingua2'
-                )::bm25_catalog.bm25vector
+                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 (expression includes text_signals), don't include it
-        # pg_textsearch: indexes operate on base columns directly, don't populate search_vector
+    else:  # native
+        # Native PostgreSQL: search_vector is GENERATED ALWAYS, don't include it
        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[], $15::jsonb[], $16::text[]
+                    $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,
-                       observation_scopes_json, text_signals)
+                       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,
-                                     observation_scopes, text_signals)
+                                     context, fact_type, confidence_score, metadata, chunk_id, document_id, tags)
            SELECT
                $1,
                text, embedding, event_date, occurred_start, occurred_end, mentioned_at,
@@ -142,9 +116,7 @@ async def insert_facts_batch(
                COALESCE(
                    (SELECT array_agg(elem) FROM jsonb_array_elements_text(tags_json) AS elem),
                    '{{}}'::varchar[]
-                ),
-                observation_scopes_json,
-                text_signals
+                )
            FROM input_data
            RETURNING id
        """
@@ -165,8 +137,6 @@ async def insert_facts_batch(
        chunk_ids,
        document_ids,
        tags_list,
-        observation_scopes_list,
-        text_signals_list,
    )

    unit_ids = [str(row["id"]) for row in results]
@@ -47,9 +47,6 @@ def compute_temporal_links(

    links = []
    for unit_id, unit_event_date in new_units.items():
-        # Units without event_date can't form temporal links
-        if unit_event_date is None:
-            continue
        # Normalize unit_event_date for consistent comparison
        unit_event_date_norm = _normalize_datetime(unit_event_date)

@@ -99,11 +96,7 @@ def compute_temporal_query_bounds(
        return None, None

    # Normalize all dates to be timezone-aware to avoid comparison issues
-    # Filter out None values — units without event_date can't form temporal links
-    all_dates = [_normalize_datetime(d) for d in new_units.values() if d is not None]
-
-    if not all_dates:
-        return None, None
+    all_dates = [_normalize_datetime(d) for d in new_units.values()]

    try:
        min_date = min(all_dates) - timedelta(hours=time_window_hours)
@@ -150,7 +143,6 @@ async def extract_entities_batch_optimized(
    fact_dates: list,
    llm_entities: list[list[dict]],
    log_buffer: list[str] = None,
-    entity_labels: list | None = None,
 ) -> list[tuple]:
    """
    Process LLM-extracted entities for ALL facts in batch.
@@ -240,7 +232,6 @@ async def extract_entities_batch_optimized(
                context=context,
                unit_event_date=None,  # Not used when per-entity dates provided
                conn=conn,  # Use main transaction connection
-                entity_labels=entity_labels,
            )

            _log(
@@ -441,23 +432,20 @@ async def create_temporal_links_batch_per_fact(
        min_date, max_date = compute_temporal_query_bounds(new_units, time_window_hours)

        fetch_neighbors_start = time_mod.time()
-        if min_date is not None and max_date is not None:
-            all_candidates = await conn.fetch(
-                f"""
-                SELECT id, event_date
-                FROM {fq_table("memory_units")}
-                WHERE bank_id = $1
-                  AND event_date BETWEEN $2 AND $3
-                  AND id::text != ALL($4)
-                ORDER BY event_date DESC
-                """,
-                bank_id,
-                min_date,
-                max_date,
-                unit_ids,
-            )
-        else:
-            all_candidates = []
+        all_candidates = await conn.fetch(
+            f"""
+            SELECT id, event_date
+            FROM {fq_table("memory_units")}
+            WHERE bank_id = $1
+              AND event_date BETWEEN $2 AND $3
+              AND id::text != ALL($4)
+            ORDER BY event_date DESC
+            """,
+            bank_id,
+            min_date,
+            max_date,
+            unit_ids,
+        )
        _log(
            log_buffer,
            f"      [7.2] Fetch {len(all_candidates)} candidate neighbors (1 query): {time_mod.time() - fetch_neighbors_start:.3f}s",
@@ -472,15 +460,11 @@ async def create_temporal_links_batch_per_fact(
            # Convert new_units dict to candidate format for within-batch linking
            new_unit_items = list(new_units.items())
            for i, (unit_id, event_date) in enumerate(new_unit_items):
-                if event_date is None:
-                    continue  # Skip units without event_date for temporal linking
                unit_event_date_norm = _normalize_datetime(event_date)

                # Compare with other new units (only those after this one to avoid duplicates)
                for j in range(i + 1, len(new_unit_items)):
                    other_id, other_event_date = new_unit_items[j]
-                    if other_event_date is None:
-                        continue  # Skip units without event_date
                    other_event_date_norm = _normalize_datetime(other_event_date)

                    # Check if within time window
@@ -498,13 +482,14 @@ async def create_temporal_links_batch_per_fact(
            # Batch inserts to avoid timeout on large batches
            BATCH_SIZE = 1000
            for batch_start in range(0, len(links), BATCH_SIZE):
+                batch = links[batch_start : batch_start + BATCH_SIZE]
                await conn.executemany(
                    f"""
                    INSERT INTO {fq_table("memory_links")} (from_unit_id, to_unit_id, link_type, weight, entity_id)
                    VALUES ($1, $2, $3, $4, $5)
                    ON CONFLICT (from_unit_id, to_unit_id, link_type, COALESCE(entity_id, '00000000-0000-0000-0000-000000000000'::uuid)) DO NOTHING
                    """,
-                    links[batch_start : batch_start + BATCH_SIZE],
+                    batch,
                )
            _log(log_buffer, f"      [7.4] Insert {len(links)} temporal links: {time_mod.time() - insert_start:.3f}s")

@@ -552,46 +537,82 @@ async def create_semantic_links_batch(

        import numpy as np

-        # Use pgvector ANN search (HNSW index) for each new unit instead of fetching
-        # all existing embeddings into Python. At large scale (100K+ units) the old
-        # approach would transfer 100K × 384 floats (~150 MB) per retain call; the
-        # ANN query completes in <5 ms and transfers only top_k rows.
-        ann_start = time_mod.time()
-        all_links = []
-
-        # Build UUID exclude list once for all ANN queries
-        import uuid as uuid_mod
-
-        exclude_uuids = [uuid_mod.UUID(uid) if isinstance(uid, str) else uid for uid in unit_ids]
-
-        for unit_id, new_embedding in zip(unit_ids, embeddings):
-            emb_str = str(list(new_embedding) if not isinstance(new_embedding, list) else new_embedding)
-            rows = await conn.fetch(
-                f"""
-                SELECT id::text,
-                       1 - (embedding <=> $1::vector) AS similarity
-                FROM {fq_table("memory_units")}
-                WHERE bank_id = $2
-                  AND embedding IS NOT NULL
-                  AND id != ALL($3::uuid[])
-                ORDER BY embedding <=> $1::vector
-                LIMIT $4
-                """,
-                emb_str,
-                bank_id,
-                exclude_uuids,
-                top_k,
-            )
-            for row in rows:
-                sim = float(min(1.0, max(0.0, row["similarity"])))
-                if sim >= threshold:
-                    all_links.append((unit_id, str(row["id"]), "semantic", sim, None))
-
+        # Fetch ALL existing units with embeddings in ONE query
+        fetch_start = time_mod.time()
+        all_existing = await conn.fetch(
+            f"""
+            SELECT id, embedding
+            FROM {fq_table("memory_units")}
+            WHERE bank_id = $1
+              AND embedding IS NOT NULL
+              AND id::text != ALL($2)
+            """,
+            bank_id,
+            unit_ids,
+        )
        _log(
            log_buffer,
-            f"      [8.1] ANN search for {len(unit_ids)} new units → {len(all_links)} candidate links: {time_mod.time() - ann_start:.3f}s",
+            f"      [8.1] Fetch {len(all_existing)} existing embeddings (1 query): {time_mod.time() - fetch_start:.3f}s",
        )

+        # Convert to numpy for vectorized similarity computation
+        compute_start = time_mod.time()
+        all_links = []
+
+        if all_existing:
+            # Convert existing embeddings to numpy array
+            existing_ids = [str(row["id"]) for row in all_existing]
+            # Stack embeddings as 2D array: (num_embeddings, embedding_dim)
+            embedding_arrays = []
+            for row in all_existing:
+                raw_emb = row["embedding"]
+                # Handle different pgvector formats
+                if isinstance(raw_emb, str):
+                    # Parse string format: "[1.0, 2.0, ...]"
+                    import json
+
+                    emb = np.array(json.loads(raw_emb), dtype=np.float32)
+                elif isinstance(raw_emb, (list, tuple)):
+                    emb = np.array(raw_emb, dtype=np.float32)
+                else:
+                    # Try direct conversion (works for numpy arrays, pgvector objects, etc.)
+                    emb = np.array(raw_emb, dtype=np.float32)
+
+                # Ensure it's 1D
+                if emb.ndim != 1:
+                    raise ValueError(f"Expected 1D embedding, got shape {emb.shape}")
+                embedding_arrays.append(emb)
+
+            if not embedding_arrays:
+                existing_embeddings = np.array([])
+            elif len(embedding_arrays) == 1:
+                # Single embedding: reshape to (1, dim)
+                existing_embeddings = embedding_arrays[0].reshape(1, -1)
+            else:
+                # Multiple embeddings: vstack
+                existing_embeddings = np.vstack(embedding_arrays)
+
+            # For each new unit, compute similarities with ALL existing units
+            for unit_id, new_embedding in zip(unit_ids, embeddings):
+                new_emb_array = np.array(new_embedding)
+
+                # Compute cosine similarities (dot product for normalized vectors)
+                similarities = np.dot(existing_embeddings, new_emb_array)
+
+                # Find top-k above threshold
+                # Get indices of similarities above threshold
+                above_threshold = np.where(similarities >= threshold)[0]
+
+                if len(above_threshold) > 0:
+                    # Sort by similarity (descending) and take top-k
+                    sorted_indices = above_threshold[np.argsort(-similarities[above_threshold])][:top_k]
+
+                    for idx in sorted_indices:
+                        similar_id = existing_ids[idx]
+                        # Clamp to [0, 1] to handle floating point precision issues
+                        similarity = float(min(1.0, max(0.0, similarities[idx])))
+                        all_links.append((unit_id, similar_id, "semantic", similarity, None))
+
        # Also compute similarities WITHIN the new batch (new units to each other)
        # Apply the same top_k limit per unit as we do for existing units
        if len(unit_ids) > 1:
@@ -622,7 +643,7 @@ async def create_semantic_links_batch(

        _log(
            log_buffer,
-            f"      [8.2] Within-batch similarities added {len(all_links)} total semantic links",
+            f"      [8.2] Compute similarities & generate {len(all_links)} semantic links: {time_mod.time() - compute_start:.3f}s",
        )

        if all_links:
@@ -630,13 +651,14 @@ async def create_semantic_links_batch(
            # Batch inserts to avoid timeout on large batches
            BATCH_SIZE = 1000
            for batch_start in range(0, len(all_links), BATCH_SIZE):
+                batch = all_links[batch_start : batch_start + BATCH_SIZE]
                await conn.executemany(
                    f"""
                    INSERT INTO {fq_table("memory_links")} (from_unit_id, to_unit_id, link_type, weight, entity_id)
                    VALUES ($1, $2, $3, $4, $5)
                    ON CONFLICT (from_unit_id, to_unit_id, link_type, COALESCE(entity_id, '00000000-0000-0000-0000-000000000000'::uuid)) DO NOTHING
                    """,
-                    all_links[batch_start : batch_start + BATCH_SIZE],
+                    batch,
                )
            _log(
                log_buffer, f"      [8.3] Insert {len(all_links)} semantic links: {time_mod.time() - insert_start:.3f}s"
@@ -652,18 +674,18 @@ async def create_semantic_links_batch(
        raise


-async def insert_entity_links_batch(conn, links: list[EntityLink], chunk_size: int = 5000):
+async def insert_entity_links_batch(conn, links: list[EntityLink], chunk_size: int = 50000):
    """
-    Insert all entity links using COPY to temp table + chunked INSERT for reliability.
+    Insert all entity links using COPY to temp table + INSERT for maximum speed.

-    Uses PostgreSQL COPY (via copy_records_to_table) for bulk loading into a
-    temp table, then INSERT ... ON CONFLICT in chunks of chunk_size. Chunking
-    prevents single-query timeouts on very large tables (100M+ rows).
+    Uses PostgreSQL COPY (via copy_records_to_table) for bulk loading,
+    then INSERT ... ON CONFLICT from temp table. This is the fastest
+    method for bulk inserts with conflict handling.

    Args:
        conn: Database connection
        links: List of EntityLink objects
-        chunk_size: Number of rows per INSERT chunk (default 5000)
+        chunk_size: Number of rows per batch (default 50000)
    """
    if not links:
        return
@@ -672,11 +694,10 @@ async def insert_entity_links_batch(conn, links: list[EntityLink], chunk_size: i

    total_start = time_mod.time()

-    # Create temp table with serial for stable chunked access
+    # Create temp table for bulk loading
    create_start = time_mod.time()
    await conn.execute("""
        CREATE TEMP TABLE IF NOT EXISTS _temp_entity_links (
-            _row_num SERIAL,
            from_unit_id uuid,
            to_unit_id uuid,
            link_type text,
@@ -693,7 +714,9 @@ async def insert_entity_links_batch(conn, links: list[EntityLink], chunk_size: i

    # Convert EntityLink objects to tuples for COPY
    convert_start = time_mod.time()
-    records = [(link.from_unit_id, link.to_unit_id, link.link_type, link.weight, link.entity_id) for link in links]
+    records = []
+    for link in links:
+        records.append((link.from_unit_id, link.to_unit_id, link.link_type, link.weight, link.entity_id))
    logger.debug(f"      [9.3] Convert {len(records)} records: {time_mod.time() - convert_start:.3f}s")

    # Bulk load using COPY (fastest method)
@@ -705,25 +728,15 @@ async def insert_entity_links_batch(conn, links: list[EntityLink], chunk_size: i
    )
    logger.debug(f"      [9.4] COPY {len(records)} records to temp table: {time_mod.time() - copy_start:.3f}s")

-    # Insert from temp table in chunks to avoid single-query timeouts on large tables
+    # Insert from temp table with ON CONFLICT (single query for all rows)
    insert_start = time_mod.time()
-    total_rows = len(records)
-    chunks = 0
-    for chunk_start in range(0, total_rows, chunk_size):
-        chunk_end = chunk_start + chunk_size
-        await conn.execute(
-            f"""
-            INSERT INTO {fq_table("memory_links")} (from_unit_id, to_unit_id, link_type, weight, entity_id)
-            SELECT from_unit_id, to_unit_id, link_type, weight, entity_id
-            FROM _temp_entity_links
-            WHERE _row_num > $1 AND _row_num <= $2
-            ON CONFLICT (from_unit_id, to_unit_id, link_type, COALESCE(entity_id, '00000000-0000-0000-0000-000000000000'::uuid)) DO NOTHING
-            """,
-            chunk_start,
-            chunk_end,
-        )
-        chunks += 1
-    logger.debug(f"      [9.5] INSERT {total_rows} rows in {chunks} chunks: {time_mod.time() - insert_start:.3f}s")
+    await conn.execute(f"""
+        INSERT INTO {fq_table("memory_links")} (from_unit_id, to_unit_id, link_type, weight, entity_id)
+        SELECT from_unit_id, to_unit_id, link_type, weight, entity_id
+        FROM _temp_entity_links
+        ON CONFLICT (from_unit_id, to_unit_id, link_type, COALESCE(entity_id, '00000000-0000-0000-0000-000000000000'::uuid)) DO NOTHING
+    """)
+    logger.debug(f"      [9.5] INSERT from temp table: {time_mod.time() - insert_start:.3f}s")
    logger.debug(f"      [9.TOTAL] Entity links batch insert: {time_mod.time() - total_start:.3f}s")


@@ -7,7 +7,6 @@ Coordinates all retain pipeline modules to store memories efficiently.
 import logging
 import time
 import uuid
-from collections.abc import Awaitable, Callable
 from datetime import UTC, datetime
 from typing import Any

@@ -53,11 +52,10 @@ def parse_datetime_flexible(value: Any) -> datetime:
        raise TypeError(f"Expected datetime or string, got {type(value).__name__}")


-import asyncpg
-
 from ..response_models import TokenUsage
 from . import (
    chunk_storage,
+    deduplication,
    embedding_processing,
    entity_processing,
    fact_extraction,
@@ -75,6 +73,7 @@ async def retain_batch(
    llm_config,
    entity_resolver,
    format_date_fn,
+    duplicate_checker_fn,
    bank_id: str,
    contents_dicts: list[RetainContentDict],
    config,
@@ -83,9 +82,6 @@ async def retain_batch(
    fact_type_override: str | None = None,
    confidence_score: float | None = None,
    document_tags: list[str] | None = None,
-    operation_id: str | None = None,
-    schema: str | None = None,
-    outbox_callback: Callable[["asyncpg.Connection"], Awaitable[None]] | None = None,
 ) -> tuple[list[list[str]], TokenUsage]:
    """
    Process a batch of content through the retain pipeline.
@@ -96,6 +92,7 @@ async def retain_batch(
        llm_config: LLM configuration for fact extraction
        entity_resolver: Entity resolver for entity processing
        format_date_fn: Function to format datetime to readable string
+        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
@@ -129,14 +126,12 @@ async def retain_batch(
        item_tags = item.get("tags", []) or []
        merged_tags = list(set(item_tags + (document_tags or [])))

-        # Handle event_date: distinguish "not provided" (default to now) from
-        # "explicitly None" (caller opted into no timestamp).
-        if "event_date" in item and item["event_date"] is None:
-            event_date_value = None  # Caller explicitly signalled "unknown date"
-        elif item.get("event_date"):
-            event_date_value = parse_datetime_flexible(item["event_date"])
+        # Handle event_date: parse flexibly (handles both datetime objects and ISO strings)
+        event_date_value = item.get("event_date")
+        if event_date_value:
+            event_date_value = parse_datetime_flexible(event_date_value)
        else:
-            event_date_value = utcnow()  # Backward-compatible default
+            event_date_value = utcnow()

        content = RetainContent(
            content=item["content"],
@@ -145,7 +140,6 @@ async def retain_batch(
            metadata=item.get("metadata", {}),
            entities=item.get("entities", []),
            tags=merged_tags,
-            observation_scopes=item.get("observation_scopes"),
        )
        contents.append(content)

@@ -153,27 +147,20 @@ async def retain_batch(
    step_start = time.time()

    extracted_facts, chunks, usage = await fact_extraction.extract_facts_from_contents(
-        contents, llm_config, agent_name, config, pool, operation_id, schema
+        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"
    )

    if not extracted_facts:
-        # Still need to create document if document_id was provided or chunks exist
-        from collections import defaultdict
-
-        docs_tracked = 0
+        # Still need to create document if document_id was provided
        async with acquire_with_retry(pool) as conn:
            async with conn.transaction():
-                # Group contents by document_id (consistent with normal path)
-                contents_by_doc_early = defaultdict(list)
-                for idx, content_dict in enumerate(contents_dicts):
-                    doc_id = content_dict.get("document_id")
-                    contents_by_doc_early[doc_id].append((idx, content_dict))
+                await fact_storage.ensure_bank_exists(conn, bank_id)

+                # Handle document tracking even with no facts
                if document_id:
-                    # Legacy: single document_id parameter
                    combined_content = "\n".join([c.get("content", "") for c in contents_dicts])
                    # Collect tags from all content items and merge with document_tags
                    all_tags = set(document_tags or [])
@@ -198,57 +185,45 @@ async def retain_batch(
                    await fact_storage.handle_document_tracking(
                        conn, bank_id, document_id, combined_content, is_first_batch, retain_params, merged_tags
                    )
-                    docs_tracked += 1
                else:
-                    # Handle per-item document_ids and/or chunks (mirrors normal path logic)
-                    has_any_doc_ids = any(item.get("document_id") for item in contents_dicts)
+                    # Check for per-item document_ids
+                    from collections import defaultdict

-                    if has_any_doc_ids or chunks:
-                        for original_doc_id, doc_contents in contents_by_doc_early.items():
-                            should_create_doc = (original_doc_id is not None) or chunks
-                            if not should_create_doc:
-                                continue
+                    contents_by_doc = defaultdict(list)
+                    for idx, content_dict in enumerate(contents_dicts):
+                        doc_id = content_dict.get("document_id")
+                        if doc_id:
+                            contents_by_doc[doc_id].append((idx, content_dict))

-                            actual_doc_id = original_doc_id
-                            if actual_doc_id is None:
-                                # No document_id but have chunks - generate one
-                                actual_doc_id = str(uuid.uuid4())
+                    for doc_id, doc_contents in contents_by_doc.items():
+                        combined_content = "\n".join([c.get("content", "") for _, c in doc_contents])
+                        # Collect tags from all content items for this document and merge with document_tags
+                        all_tags = set(document_tags or [])
+                        for _, item in doc_contents:
+                            item_tags = item.get("tags", []) or []
+                            all_tags.update(item_tags)
+                        merged_tags = list(all_tags)

-                            combined_content = "\n".join([c.get("content", "") for _, c in doc_contents])
-                            all_tags = set(document_tags or [])
-                            for _, item in doc_contents:
-                                item_tags = item.get("tags", []) or []
-                                all_tags.update(item_tags)
-                            merged_tags = list(all_tags)
-
-                            retain_params = {}
-                            if doc_contents:
-                                first_item = doc_contents[0][1]
-                                if first_item.get("context"):
-                                    retain_params["context"] = first_item["context"]
-                                if first_item.get("event_date"):
-                                    retain_params["event_date"] = (
-                                        first_item["event_date"].isoformat()
-                                        if hasattr(first_item["event_date"], "isoformat")
-                                        else str(first_item["event_date"])
-                                    )
-                                if first_item.get("metadata"):
-                                    retain_params["metadata"] = first_item["metadata"]
-                            await fact_storage.handle_document_tracking(
-                                conn,
-                                bank_id,
-                                actual_doc_id,
-                                combined_content,
-                                is_first_batch,
-                                retain_params,
-                                merged_tags,
-                            )
-                            docs_tracked += 1
+                        retain_params = {}
+                        if doc_contents:
+                            first_item = doc_contents[0][1]
+                            if first_item.get("context"):
+                                retain_params["context"] = first_item["context"]
+                            if first_item.get("event_date"):
+                                retain_params["event_date"] = (
+                                    first_item["event_date"].isoformat()
+                                    if hasattr(first_item["event_date"], "isoformat")
+                                    else str(first_item["event_date"])
+                                )
+                            if first_item.get("metadata"):
+                                retain_params["metadata"] = first_item["metadata"]
+                        await fact_storage.handle_document_tracking(
+                            conn, bank_id, doc_id, combined_content, is_first_batch, retain_params, merged_tags
+                        )

        total_time = time.time() - start_time
-        doc_status = f"{docs_tracked} document(s) tracked" if docs_tracked > 0 else "no document tracked"
        logger.info(
-            f"RETAIN_BATCH COMPLETE: 0 facts extracted from {len(contents)} contents in {total_time:.3f}s ({doc_status}, no facts)"
+            f"RETAIN_BATCH COMPLETE: 0 facts extracted from {len(contents)} contents in {total_time:.3f}s (document tracked, no facts)"
        )
        return [[] for _ in contents], usage

@@ -283,6 +258,9 @@ async def retain_batch(
    # Step 4: Database transaction
    async with acquire_with_retry(pool) as conn:
        async with conn.transaction():
+            # Ensure bank exists
+            await fact_storage.ensure_bank_exists(conn, bank_id)
+
            # Handle document tracking for all documents
            step_start = time.time()
            # Map None document_id to generated UUIDs
@@ -434,7 +412,20 @@ async def retain_batch(
                        actual_doc_id = document_id
                    processed_fact.document_id = actual_doc_id

-            non_duplicate_facts = processed_facts
+            # Deduplication
+            step_start = time.time()
+            is_duplicate_flags = await deduplication.check_duplicates_batch(
+                conn, bank_id, processed_facts, duplicate_checker_fn
+            )
+            log_buffer.append(
+                f"[4] Deduplication: {sum(is_duplicate_flags)} duplicates in {time.time() - step_start:.3f}s"
+            )
+
+            # Filter out duplicates
+            non_duplicate_facts = deduplication.filter_duplicates(processed_facts, is_duplicate_flags)
+
+            if not non_duplicate_facts:
+                return [[] for _ in contents], usage

            # Insert facts (document_id is now stored per-fact)
            step_start = time.time()
@@ -455,7 +446,6 @@ async def retain_batch(
                non_duplicate_facts,
                log_buffer,
                user_entities_per_content=user_entities_per_content,
-                entity_labels=getattr(config, "entity_labels", None),
            )
            log_buffer.append(f"[6] Process entities: {len(entity_links)} links in {time.time() - step_start:.3f}s")

@@ -486,16 +476,7 @@ async def retain_batch(
            log_buffer.append(f"[10] Causal links: {causal_link_count} links in {time.time() - step_start:.3f}s")

            # Map results back to original content items
-            result_unit_ids = _map_results_to_contents(contents, extracted_facts, unit_ids)
-
-            # Transactional outbox: queue any side-effect tasks (e.g. webhook deliveries)
-            # inside the same transaction so they are atomically committed with the retain data.
-            if outbox_callback:
-                await outbox_callback(conn)
-
-        # Flush entity stats (mention_count / last_seen) now that the transaction
-        # has committed.  Uses a fresh pool connection — no locks held.
-        await entity_resolver.flush_pending_stats()
+            result_unit_ids = _map_results_to_contents(contents, extracted_facts, is_duplicate_flags, unit_ids)

        # Log final summary
        total_time = time.time() - start_time
@@ -513,20 +494,28 @@ async def retain_batch(
 def _map_results_to_contents(
    contents: list[RetainContent],
    extracted_facts: list[ExtractedFact],
+    is_duplicate_flags: list[bool],
    unit_ids: list[str],
 ) -> list[list[str]]:
-    """Map created unit IDs back to original content items."""
-    facts_by_content: dict[int, list[int]] = {i: [] for i in range(len(contents))}
+    """
+    Map created unit IDs back to original content items.
+
+    Accounts for duplicates when mapping back.
+    """
+    result_unit_ids = []
+    filtered_idx = 0
+
+    # Group facts by content_index
+    facts_by_content = {i: [] for i in range(len(contents))}
    for i, fact in enumerate(extracted_facts):
        facts_by_content[fact.content_index].append(i)

-    result_unit_ids = []
-    unit_idx = 0
    for content_index in range(len(contents)):
        content_unit_ids = []
-        for _ in facts_by_content[content_index]:
-            content_unit_ids.append(unit_ids[unit_idx])
-            unit_idx += 1
+        for fact_idx in facts_by_content[content_index]:
+            if not is_duplicate_flags[fact_idx]:
+                content_unit_ids.append(unit_ids[filtered_idx])
+                filtered_idx += 1
        result_unit_ids.append(content_unit_ids)

    return result_unit_ids
@@ -6,8 +6,8 @@ from content input to fact storage.
 """

 from dataclasses import dataclass, field
-from datetime import datetime
-from typing import Literal, TypedDict
+from datetime import UTC, datetime
+from typing import TypedDict
 from uuid import UUID


@@ -22,21 +22,20 @@ class RetainContentDict(TypedDict, total=False):
        document_id: Document ID for this content item (optional)
        entities: User-provided entities to merge with extracted entities (optional)
        tags: Visibility scope tags for this content item (optional)
-        observation_scopes: How to scope observations for consolidation (optional).
-            "per_tag" runs one pass per individual tag; "combined" (default) runs a
-            single pass with all tags; a list[list[str]] specifies exact passes.
    """

    content: str  # Required
    context: str
-    event_date: datetime | None
+    event_date: datetime
    metadata: dict[str, str]
    document_id: str
    entities: list[dict[str, str]]  # [{"text": "...", "type": "..."}]
    tags: list[str]  # Visibility scope tags
-    observation_scopes: (
-        Literal["per_tag", "combined", "all_combinations"] | list[list[str]]
-    )  # Observation scopes for consolidation
+
+
+def _now_utc() -> datetime:
+    """Factory function for default event_date."""
+    return datetime.now(UTC)


@dataclass
@@ -49,13 +48,10 @@ class RetainContent:

    content: str
    context: str = ""
-    event_date: datetime | None = None
+    event_date: datetime = field(default_factory=_now_utc)
    metadata: dict[str, str] = field(default_factory=dict)
    entities: list[dict[str, str]] = field(default_factory=list)  # User-provided entities
    tags: list[str] = field(default_factory=list)  # Visibility scope tags
-    observation_scopes: Literal["per_tag", "combined", "all_combinations"] | list[list[str]] | None = (
-        None  # Observation scopes
-    )


@dataclass
@@ -121,9 +117,6 @@ class ExtractedFact:
    mentioned_at: datetime | None = None
    metadata: dict[str, str] = field(default_factory=dict)
    tags: list[str] = field(default_factory=list)  # Visibility scope tags
-    observation_scopes: Literal["per_tag", "combined", "all_combinations"] | list[list[str]] | None = (
-        None  # Observation scopes
-    )


@dataclass
@@ -142,7 +135,7 @@ class ProcessedFact:
    # Temporal data
    occurred_start: datetime | None
    occurred_end: datetime | None
-    mentioned_at: datetime | None
+    mentioned_at: datetime

    # Context and metadata
    context: str
@@ -172,9 +165,6 @@ class ProcessedFact:
    # Visibility scope tags
    tags: list[str] = field(default_factory=list)

-    # Observation scopes for consolidation
-    observation_scopes: Literal["per_tag", "combined", "all_combinations"] | list[list[str]] | None = None
-
    @property
    def is_duplicate(self) -> bool:
        """Check if this fact was marked as a duplicate."""
@@ -195,10 +185,12 @@ class ProcessedFact:
        Returns:
            ProcessedFact ready for storage
        """
+        from datetime import datetime
+
        # Use occurred dates only if explicitly provided by LLM
        occurred_start = extracted_fact.occurred_start
        occurred_end = extracted_fact.occurred_end
-        mentioned_at = extracted_fact.mentioned_at  # May be None when caller opted into no timestamp
+        mentioned_at = extracted_fact.mentioned_at or datetime.now(UTC)

        # Convert entity strings to EntityRef objects
        entities = [EntityRef(name=name) for name in extracted_fact.entities]
@@ -217,7 +209,6 @@ class ProcessedFact:
            chunk_id=chunk_id,
            content_index=extracted_fact.content_index,
            tags=extracted_fact.tags,
-            observation_scopes=extracted_fact.observation_scopes,
        )


@@ -162,7 +162,7 @@ class BFSGraphRetriever(GraphRetriever):
        entry_points = await conn.fetch(
            f"""
            SELECT id, text, context, event_date, occurred_start, occurred_end,
-                   mentioned_at, fact_type, document_id, chunk_id, tags,
+                   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
@@ -216,7 +216,7 @@ class BFSGraphRetriever(GraphRetriever):
                neighbors = await conn.fetch(
                    f"""
                    SELECT mu.id, mu.text, mu.context, mu.occurred_start, mu.occurred_end,
-                           mu.mentioned_at, mu.fact_type,
+                           mu.mentioned_at, mu.embedding, mu.fact_type,
                           mu.document_id, mu.chunk_id, mu.tags,
                           ml.weight, ml.link_type, ml.from_unit_id
                    FROM {fq_table("memory_links")} ml
@@ -1,28 +1,18 @@
 """
 Link Expansion graph retrieval.

-Expands from semantic/temporal seeds through three parallel, first-class signals
-stored in memory_links:
+A simple, fast graph retrieval that expands from seeds via:
+1. Entity links: Find facts sharing entities with seeds (filtered by entity frequency)
+2. Causal links: Find facts causally linked to seeds (top-k by weight)

-1. Entity links  — precomputed co-occurrence graph (created at retain time, bounded to
-                   MAX_LINKS_PER_ENTITY per entity). Score = number of distinct shared
-                   entities between the seed set and each candidate.
-2. Semantic links — precomputed kNN graph (each new fact linked to its top-5 most
-                    similar existing facts at insert time, similarity >= 0.7). Checked
-                    in both directions since the graph is not symmetric. Score = weight.
-3. Causal links  — explicit causal chains (causes/caused_by/enables/prevents).
-                   Score = weight + 1.0 (boosted as highest-quality signal).
-
-All three signals are bounded at retain time, so no LATERAL fan-out caps are needed
-at query time. Each expansion is a simple aggregation over a small result set.
-
-For non-observation fact types the three expansions are issued as a single CTE query
-(one roundtrip, one connection) with a `source` discriminator column so the Python
-merge step can apply per-signal score transformations.
+Characteristics:
+- 2-3 DB queries (seed finding + parallel entity/causal expansion)
+- Sublinear: only touches connected facts via indexes
+- No iteration, no propagation, no normalization
+- Target: <100ms
 """

 import logging
-import math
 import time

 from ..db_utils import acquire_with_retry
@@ -55,7 +45,7 @@ async def _find_semantic_seeds(
    rows = await conn.fetch(
        f"""
        SELECT id, text, context, event_date, occurred_start, occurred_end,
-               mentioned_at, fact_type, document_id, chunk_id, tags,
+               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
@@ -75,23 +65,27 @@ class LinkExpansionRetriever(GraphRetriever):
    """
    Graph retrieval via direct link expansion from seeds.

-    Runs three expansions through precomputed memory_links: entity co-occurrence,
-    semantic kNN, and causal chains, all bounded at retain time.
-
-    For non-observation fact types the three expansions are issued as a single CTE
-    query (one roundtrip, one connection slot) with a `source` discriminator column.
-    The Python merge step applies per-signal score transformations.
+    Expands through entity co-occurrence and causal links in a single query.
+    Fast and simple alternative to MPFP.
    """

    def __init__(
        self,
+        max_entity_frequency: int = 500,
        causal_weight_threshold: float = 0.3,
+        causal_limit_per_seed: int = 10,
    ):
        """
+        Initialize link expansion retriever.
+
        Args:
-            causal_weight_threshold: Minimum weight for causal links to follow.
+            max_entity_frequency: Skip entities appearing in more than this many facts
+            causal_weight_threshold: Minimum weight for causal links
+            causal_limit_per_seed: Max causal links to follow per seed
        """
+        self.max_entity_frequency = max_entity_frequency
        self.causal_weight_threshold = causal_weight_threshold
+        self.causal_limit_per_seed = causal_limit_per_seed

    @property
    def name(self) -> str:
@@ -116,7 +110,7 @@ class LinkExpansionRetriever(GraphRetriever):

        Args:
            pool: Database connection pool
-            query_embedding_str: Query embedding as string
+            query_embedding_str: Query embedding (unused, kept for interface)
            bank_id: Memory bank ID
            fact_type: Fact type to filter
            budget: Maximum results to return
@@ -124,7 +118,7 @@ class LinkExpansionRetriever(GraphRetriever):
            semantic_seeds: Pre-computed semantic entry points
            temporal_seeds: Pre-computed temporal entry points
            adjacency: Unused, kept for interface compatibility
-            tags: Optional list of tags for visibility filtering
+            tags: Optional list of tags for visibility filtering (OR matching)

        Returns:
            Tuple of (results, timings)
@@ -132,6 +126,8 @@ class LinkExpansionRetriever(GraphRetriever):
        start_time = time.time()
        timings = MPFPTimings(fact_type=fact_type)

+        # Use single connection for all queries to reduce pool pressure
+        # (queries are fast ~50ms each, connection acquisition is the bottleneck)
        async with acquire_with_retry(pool) as conn:
            # Find seeds if not provided
            if semantic_seeds:
@@ -154,6 +150,7 @@ class LinkExpansionRetriever(GraphRetriever):
                    f"(tags={tags}, tags_match={tags_match})"
                )

+            # Add temporal seeds if provided
            if temporal_seeds:
                all_seeds.extend(temporal_seeds)

@@ -163,61 +160,223 @@ class LinkExpansionRetriever(GraphRetriever):
            seed_ids = list({s.id for s in all_seeds})
            timings.pattern_count = len(seed_ids)

+            # Run entity and causal expansion sequentially on same connection
            query_start = time.time()

+            # For observations, traverse through source_memory_ids to find entity connections.
+            # Observations don't have direct unit_entities - they inherit entities via their
+            # source world/experience facts.
+            #
+            # Path: observation → source_memory_ids → world fact → entities →
+            #       ALL world facts with those entities → their observations (excluding seeds)
            if fact_type == "observation":
-                entity_rows, semantic_rows, causal_rows = await self._expand_observations(conn, seed_ids, budget)
+                # Debug: Check what source_memory_ids exist on seed observations
+                debug_sources = await conn.fetch(
+                    f"""
+                    SELECT id, source_memory_ids
+                    FROM {fq_table("memory_units")}
+                    WHERE id = ANY($1::uuid[])
+                    """,
+                    seed_ids,
+                )
+                source_ids_found = []
+                for row in debug_sources:
+                    if row["source_memory_ids"]:
+                        source_ids_found.extend(row["source_memory_ids"])
+                logger.debug(
+                    f"[LinkExpansion] observation graph: {len(seed_ids)} seeds, "
+                    f"{len(source_ids_found)} source_memory_ids found"
+                )
+
+                entity_rows = await conn.fetch(
+                    f"""
+                    WITH seed_sources AS (
+                        -- Get source memory IDs from seed observations
+                        SELECT DISTINCT unnest(source_memory_ids) AS source_id
+                        FROM {fq_table("memory_units")}
+                        WHERE id = ANY($1::uuid[])
+                          AND source_memory_ids IS NOT NULL
+                    ),
+                    source_entities AS (
+                        -- Get entities from those source memories (filtered by frequency)
+                        SELECT DISTINCT ue.entity_id
+                        FROM seed_sources ss
+                        JOIN {fq_table("unit_entities")} ue ON ss.source_id = ue.unit_id
+                        JOIN {fq_table("entities")} e ON ue.entity_id = e.id
+                        WHERE e.mention_count < $2
+                    ),
+                    all_connected_sources AS (
+                        -- Find ALL world facts sharing those entities (don't exclude seed sources)
+                        -- The exclusion happens at the observation level, not the source level
+                        SELECT DISTINCT other_ue.unit_id AS source_id
+                        FROM source_entities se
+                        JOIN {fq_table("unit_entities")} other_ue ON se.entity_id = other_ue.entity_id
+                    )
+                    -- Find observations derived from connected source memories
+                    -- Only exclude the actual seed observations
+                    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, mu.tags,
+                        COUNT(DISTINCT cs.source_id)::float AS score
+                    FROM all_connected_sources cs
+                    JOIN {fq_table("memory_units")} mu
+                        ON mu.source_memory_ids @> ARRAY[cs.source_id]
+                    WHERE mu.fact_type = 'observation'
+                      AND mu.id != ALL($1::uuid[])
+                    GROUP BY mu.id
+                    ORDER BY score DESC
+                    LIMIT $3
+                    """,
+                    seed_ids,
+                    self.max_entity_frequency,
+                    budget,
+                )
+                logger.debug(f"[LinkExpansion] observation graph: found {len(entity_rows)} connected observations")
            else:
-                entity_rows, semantic_rows, causal_rows = await self._expand_combined(conn, seed_ids, fact_type, budget)
+                # For world/experience facts, use direct entity lookup
+                entity_rows = 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, mu.tags,
+                        COUNT(*)::float AS score
+                    FROM {fq_table("unit_entities")} seed_ue
+                    JOIN {fq_table("entities")} e ON seed_ue.entity_id = e.id
+                    JOIN {fq_table("unit_entities")} other_ue ON seed_ue.entity_id = other_ue.entity_id
+                    JOIN {fq_table("memory_units")} mu ON other_ue.unit_id = mu.id
+                    WHERE seed_ue.unit_id = ANY($1::uuid[])
+                      AND e.mention_count < $2
+                      AND mu.id != ALL($1::uuid[])
+                      AND mu.fact_type = $3
+                    GROUP BY mu.id
+                    ORDER BY score DESC
+                    LIMIT $4
+                    """,
+                    seed_ids,
+                    self.max_entity_frequency,
+                    fact_type,
+                    budget,
+                )
+
+            causal_rows = await conn.fetch(
+                f"""
+                SELECT DISTINCT ON (mu.id)
+                    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, mu.tags,
+                    ml.weight + 1.0 AS score
+                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($1::uuid[])
+                  AND ml.link_type IN ('causes', 'caused_by', 'enables', 'prevents')
+                  AND ml.weight >= $2
+                  AND mu.fact_type = $3
+                ORDER BY mu.id, ml.weight DESC
+                LIMIT $4
+                """,
+                seed_ids,
+                self.causal_weight_threshold,
+                fact_type,
+                budget,
+            )
+
+            # Fallback: semantic/temporal/entity links from memory_links table
+            # These are secondary to entity links (via unit_entities) and causal links
+            # Weight is halved (0.5x) to prioritize primary link types
+            # Check both directions: seeds -> others AND others -> seeds
+            fallback_rows = await conn.fetch(
+                f"""
+                WITH outgoing AS (
+                    -- Links FROM seeds TO other facts
+                    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, mu.tags,
+                           ml.weight
+                    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($1::uuid[])
+                      AND ml.link_type IN ('semantic', 'temporal', 'entity')
+                      AND ml.weight >= $2
+                      AND mu.fact_type = $3
+                      AND mu.id != ALL($1::uuid[])
+                ),
+                incoming AS (
+                    -- Links FROM other facts TO seeds (reverse direction)
+                    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, mu.tags,
+                           ml.weight
+                    FROM {fq_table("memory_links")} ml
+                    JOIN {fq_table("memory_units")} mu ON ml.from_unit_id = mu.id
+                    WHERE ml.to_unit_id = ANY($1::uuid[])
+                      AND ml.link_type IN ('semantic', 'temporal', 'entity')
+                      AND ml.weight >= $2
+                      AND mu.fact_type = $3
+                      AND mu.id != ALL($1::uuid[])
+                ),
+                combined AS (
+                    SELECT * FROM outgoing
+                    UNION ALL
+                    SELECT * FROM incoming
+                )
+                SELECT DISTINCT ON (id)
+                    id, text, context, event_date, occurred_start,
+                    occurred_end, mentioned_at, embedding,
+                    fact_type, document_id, chunk_id, tags,
+                    (MAX(weight) * 0.5) AS score
+                FROM combined
+                GROUP BY id, text, context, event_date, occurred_start,
+                         occurred_end, mentioned_at, embedding,
+                         fact_type, document_id, chunk_id, tags
+                ORDER BY id, score DESC
+                LIMIT $4
+                """,
+                seed_ids,
+                self.causal_weight_threshold,
+                fact_type,
+                budget,
+            )

            timings.edge_load_time = time.time() - query_start
-            timings.db_queries = 1
-            timings.edge_count = len(entity_rows) + len(semantic_rows) + len(causal_rows)
+            timings.db_queries = 3
+            timings.edge_count = len(entity_rows) + len(causal_rows) + len(fallback_rows)

-        # Merge results with additive intra-score: entity + semantic + causal ∈ [0, 3].
-        #
-        # Entity score: tanh(count × 0.5) maps shared-entity count to [0, 1]:
-        #   1 entity → 0.46,  2 → 0.76,  3 → 0.91,  4 → 0.96  (saturates naturally)
-        # Semantic score: similarity weight, already ∈ [0.7, 1.0].
-        # Causal score:   link weight, already ∈ [0, 1].
-        #
-        # Facts appearing in multiple signals accumulate higher scores, rewarding
-        # convergent evidence. The outer RRF uses rank position from this sorted list.
-        entity_scores: dict[str, float] = {}
-        semantic_scores: dict[str, float] = {}
-        causal_scores: dict[str, float] = {}
+        # Merge results, taking max score per fact
+        # Priority: entity links (unit_entities) > causal links > fallback links
+        score_map: dict[str, float] = {}
        row_map: dict[str, dict] = {}

        for row in entity_rows:
            fact_id = str(row["id"])
-            entity_scores[fact_id] = math.tanh(row["score"] * 0.5)
+            score_map[fact_id] = max(score_map.get(fact_id, 0), row["score"])
            row_map[fact_id] = dict(row)

-        for row in semantic_rows:
-            fact_id = str(row["id"])
-            semantic_scores[fact_id] = max(semantic_scores.get(fact_id, 0.0), row["score"])
-            row_map.setdefault(fact_id, dict(row))
-
        for row in causal_rows:
            fact_id = str(row["id"])
-            causal_scores[fact_id] = max(causal_scores.get(fact_id, 0.0), row["score"])
-            row_map.setdefault(fact_id, dict(row))
+            score_map[fact_id] = max(score_map.get(fact_id, 0), row["score"])
+            if fact_id not in row_map:
+                row_map[fact_id] = dict(row)

-        all_ids = set(entity_scores) | set(semantic_scores) | set(causal_scores)
-        score_map = {
-            fid: entity_scores.get(fid, 0.0) + semantic_scores.get(fid, 0.0) + causal_scores.get(fid, 0.0)
-            for fid in all_ids
-        }
+        for row in fallback_rows:
+            fact_id = str(row["id"])
+            score_map[fact_id] = max(score_map.get(fact_id, 0), row["score"])
+            if fact_id not in row_map:
+                row_map[fact_id] = dict(row)

+        # Sort by score and limit
        sorted_ids = sorted(score_map.keys(), key=lambda x: score_map[x], reverse=True)[:budget]
        rows = [row_map[fact_id] for fact_id in sorted_ids]

+        # Convert to results
        results = []
        for row in rows:
            result = RetrievalResult.from_db_row(dict(row))
            result.activation = row["score"]
            results.append(result)

+        # Apply tags filtering (graph expansion may reach untagged memories)
        if tags:
            results = filter_results_by_tags(results, tags, match=tags_match)

@@ -230,254 +389,3 @@ class LinkExpansionRetriever(GraphRetriever):
        )

        return results, timings
-
-    async def _expand_combined(
-        self,
-        conn,
-        seed_ids: list,
-        fact_type: str,
-        budget: int,
-    ) -> tuple[list, list, list]:
-        """
-        Single-roundtrip CTE query combining entity, semantic, and causal expansions.
-
-        Uses a `source` discriminator column so the caller can apply per-signal
-        score transformations.  The three CTEs share one connection slot — important
-        for asyncpg which does not allow concurrent queries on the same connection.
-
-        Index coverage (requires migration d2e3f4a5b6c7):
-          entity:   idx_memory_links_entity_covering (from_unit_id) INCLUDE (to_unit_id, entity_id)
-                    WHERE link_type = 'entity'  → index-only scan, no heap reads
-          semantic incoming:
-                    idx_memory_links_to_type_weight (to_unit_id, link_type, weight DESC)
-                    → replaces costly BitmapAnd of two separate scans
-        """
-        ml = fq_table("memory_links")
-        mu = fq_table("memory_units")
-        all_rows = await conn.fetch(
-            f"""
-            WITH entity_expanded AS (
-                -- Entity co-occurrence: seeds → their precomputed entity-link neighbors.
-                -- Score = distinct shared entities (bounded at retain time to
-                -- MAX_LINKS_PER_ENTITY=50).  GROUP BY mu.id is sufficient because mu.id
-                -- is the primary key and functionally determines all other mu columns.
-                SELECT
-                    mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start,
-                    mu.occurred_end, mu.mentioned_at,
-                    mu.fact_type, mu.document_id, mu.chunk_id, mu.tags,
-                    COUNT(DISTINCT ml.entity_id)::float AS score,
-                    'entity'::text AS source
-                FROM {ml} ml
-                JOIN {mu} mu ON mu.id = ml.to_unit_id
-                WHERE ml.from_unit_id = ANY($1::uuid[])
-                  AND ml.link_type = 'entity'
-                  AND mu.fact_type = $2
-                  AND mu.id != ALL($1::uuid[])
-                GROUP BY mu.id
-                ORDER BY score DESC
-                LIMIT $3
-            ),
-            semantic_expanded AS (
-                -- Semantic kNN: both outgoing (seeds → their kNN at insert time) and
-                -- incoming (facts inserted after seeds that found seeds as kNN).
-                -- Score = max similarity weight across both directions.
-                SELECT
-                    id, text, context, event_date, occurred_start,
-                    occurred_end, mentioned_at,
-                    fact_type, document_id, chunk_id, tags,
-                    MAX(weight) AS score,
-                    'semantic'::text AS source
-                FROM (
-                    SELECT
-                        mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start,
-                        mu.occurred_end, mu.mentioned_at,
-                        mu.fact_type, mu.document_id, mu.chunk_id, mu.tags,
-                        ml.weight
-                    FROM {ml} ml
-                    JOIN {mu} mu ON mu.id = ml.to_unit_id
-                    WHERE ml.from_unit_id = ANY($1::uuid[])
-                      AND ml.link_type = 'semantic'
-                      AND mu.fact_type = $2
-                      AND mu.id != ALL($1::uuid[])
-                    UNION ALL
-                    SELECT
-                        mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start,
-                        mu.occurred_end, mu.mentioned_at,
-                        mu.fact_type, mu.document_id, mu.chunk_id, mu.tags,
-                        ml.weight
-                    FROM {ml} ml
-                    JOIN {mu} mu ON mu.id = ml.from_unit_id
-                    WHERE ml.to_unit_id = ANY($1::uuid[])
-                      AND ml.link_type = 'semantic'
-                      AND mu.fact_type = $2
-                      AND mu.id != ALL($1::uuid[])
-                ) sem_raw
-                GROUP BY id, text, context, event_date, occurred_start,
-                         occurred_end, mentioned_at,
-                         fact_type, document_id, chunk_id, tags
-                ORDER BY score DESC
-                LIMIT $3
-            ),
-            causal_expanded AS (
-                -- Causal chains: explicit causes/enables/prevents links from seeds.
-                -- DISTINCT ON handles the case where a seed has multiple causal links
-                -- to the same target; best weight wins.
-                SELECT DISTINCT ON (mu.id)
-                    mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start,
-                    mu.occurred_end, mu.mentioned_at,
-                    mu.fact_type, mu.document_id, mu.chunk_id, mu.tags,
-                    ml.weight AS score,
-                    'causal'::text AS source
-                FROM {ml} ml
-                JOIN {mu} mu ON ml.to_unit_id = mu.id
-                WHERE ml.from_unit_id = ANY($1::uuid[])
-                  AND ml.link_type IN ('causes', 'caused_by', 'enables', 'prevents')
-                  AND ml.weight >= $4
-                  AND mu.fact_type = $2
-                ORDER BY mu.id, ml.weight DESC
-                LIMIT $3
-            )
-            SELECT * FROM entity_expanded
-            UNION ALL
-            SELECT * FROM semantic_expanded
-            UNION ALL
-            SELECT * FROM causal_expanded
-            """,
-            seed_ids,
-            fact_type,
-            budget,
-            self.causal_weight_threshold,
-        )
-
-        entity_rows = [r for r in all_rows if r["source"] == "entity"]
-        semantic_rows = [r for r in all_rows if r["source"] == "semantic"]
-        causal_rows = [r for r in all_rows if r["source"] == "causal"]
-        return entity_rows, semantic_rows, causal_rows
-
-    async def _expand_observations(
-        self,
-        conn,
-        seed_ids: list,
-        budget: int,
-    ) -> tuple[list, list, list]:
-        """
-        Observation-specific expansion.
-
-        Observations don't have direct entity links in memory_links (they're created
-        by consolidation, not retain).  Instead, traverse source_memory_ids → world
-        facts → entities → other world facts → their observations.
-
-        Semantic and causal expansions run as a second combined CTE query.
-        """
-        source_ids_found: list = []
-        if logger.isEnabledFor(logging.DEBUG):
-            debug_rows = await conn.fetch(
-                f"""
-                SELECT id, source_memory_ids
-                FROM {fq_table("memory_units")}
-                WHERE id = ANY($1::uuid[])
-                """,
-                seed_ids,
-            )
-            for row in debug_rows:
-                if row["source_memory_ids"]:
-                    source_ids_found.extend(row["source_memory_ids"])
-            logger.debug(
-                f"[LinkExpansion] observation graph: {len(seed_ids)} seeds, "
-                f"{len(source_ids_found)} source_memory_ids found"
-            )
-
-        entity_rows = await conn.fetch(
-            f"""
-            WITH seed_sources AS (
-                SELECT DISTINCT unnest(source_memory_ids) AS source_id
-                FROM {fq_table("memory_units")}
-                WHERE id = ANY($1::uuid[])
-                  AND source_memory_ids IS NOT NULL
-            ),
-            connected_sources AS (
-                -- Mirror the non-observation entity expansion: follow pre-bounded entity
-                -- links in memory_links (capped to MAX_LINKS_PER_ENTITY=50 at retain time).
-                -- Score = number of distinct shared entities, same as the non-obs path.
-                SELECT DISTINCT ml.to_unit_id AS source_id
-                FROM seed_sources ss
-                JOIN {fq_table("memory_links")} ml ON ml.from_unit_id = ss.source_id
-                WHERE ml.link_type = 'entity'
-            ),
-            connected_array AS (
-                SELECT array_agg(source_id) AS source_ids FROM connected_sources
-            )
-            SELECT
-                mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start,
-                mu.occurred_end, mu.mentioned_at,
-                mu.fact_type, mu.document_id, mu.chunk_id, mu.tags,
-                (SELECT COUNT(DISTINCT s) FROM unnest(mu.source_memory_ids) s WHERE s = ANY(ca.source_ids))::float AS score
-            FROM {fq_table("memory_units")} mu, connected_array ca
-            WHERE mu.fact_type = 'observation'
-              AND mu.id != ALL($1::uuid[])
-              AND ca.source_ids IS NOT NULL
-              AND mu.source_memory_ids && ca.source_ids
-            ORDER BY score DESC
-            LIMIT $2
-            """,
-            seed_ids,
-            budget,
-        )
-        logger.debug(f"[LinkExpansion] observation graph: found {len(entity_rows)} connected observations")
-
-        # Semantic + causal for observations in one query
-        ml = fq_table("memory_links")
-        mu = fq_table("memory_units")
-        sem_causal_rows = await conn.fetch(
-            f"""
-            WITH semantic_expanded AS (
-                SELECT
-                    id, text, context, event_date, occurred_start,
-                    occurred_end, mentioned_at,
-                    fact_type, document_id, chunk_id, tags,
-                    MAX(weight) AS score,
-                    'semantic'::text AS source
-                FROM (
-                    SELECT mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start,
-                           mu.occurred_end, mu.mentioned_at, mu.fact_type, mu.document_id,
-                           mu.chunk_id, mu.tags, ml.weight
-                    FROM {ml} ml JOIN {mu} mu ON mu.id = ml.to_unit_id
-                    WHERE ml.from_unit_id = ANY($1::uuid[])
-                      AND ml.link_type = 'semantic' AND mu.fact_type = 'observation'
-                      AND mu.id != ALL($1::uuid[])
-                    UNION ALL
-                    SELECT mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start,
-                           mu.occurred_end, mu.mentioned_at, mu.fact_type, mu.document_id,
-                           mu.chunk_id, mu.tags, ml.weight
-                    FROM {ml} ml JOIN {mu} mu ON mu.id = ml.from_unit_id
-                    WHERE ml.to_unit_id = ANY($1::uuid[])
-                      AND ml.link_type = 'semantic' AND mu.fact_type = 'observation'
-                      AND mu.id != ALL($1::uuid[])
-                ) sem_raw
-                GROUP BY id, text, context, event_date, occurred_start, occurred_end,
-                         mentioned_at, fact_type, document_id, chunk_id, tags
-                ORDER BY score DESC LIMIT $2
-            ),
-            causal_expanded AS (
-                SELECT DISTINCT ON (mu.id)
-                    mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start,
-                    mu.occurred_end, mu.mentioned_at, mu.fact_type, mu.document_id,
-                    mu.chunk_id, mu.tags, ml.weight AS score, 'causal'::text AS source
-                FROM {ml} ml JOIN {mu} mu ON ml.to_unit_id = mu.id
-                WHERE ml.from_unit_id = ANY($1::uuid[])
-                  AND ml.link_type IN ('causes', 'caused_by', 'enables', 'prevents')
-                  AND ml.weight >= $3 AND mu.fact_type = 'observation'
-                ORDER BY mu.id, ml.weight DESC LIMIT $2
-            )
-            SELECT * FROM semantic_expanded
-            UNION ALL
-            SELECT * FROM causal_expanded
-            """,
-            seed_ids,
-            budget,
-            self.causal_weight_threshold,
-        )
-
-        semantic_rows = [r for r in sem_causal_rows if r["source"] == "semantic"]
-        causal_rows = [r for r in sem_causal_rows if r["source"] == "causal"]
-        return entity_rows, semantic_rows, causal_rows
@@ -449,7 +449,7 @@ async def fetch_memory_units_by_ids(
        rows = await conn.fetch(
            f"""
            SELECT id, text, context, event_date, occurred_start, occurred_end,
-                   mentioned_at, fact_type, document_id, chunk_id, tags
+                   mentioned_at, embedding, fact_type, document_id, chunk_id, tags
            FROM {fq_table("memory_units")}
            WHERE id = ANY($1::uuid[])
              AND fact_type = $2
@@ -2,72 +2,8 @@
 Cross-encoder neural reranking for search results.
 """

-from datetime import datetime, timezone
-
 from .types import MergedCandidate, ScoredResult

-UTC = timezone.utc
-
-# Multiplicative boost alphas for recency and temporal proximity.
-# Each signal contributes at most ±(alpha/2) relative adjustment to the base CE score,
-# so the max combined boost is (1 + alpha/2)^2 ≈ +21% and min is (1 - alpha/2)^2 ≈ -19%.
-_RECENCY_ALPHA: float = 0.2
-_TEMPORAL_ALPHA: float = 0.2
-
-
-def apply_combined_scoring(
-    scored_results: list[ScoredResult],
-    now: datetime,
-    recency_alpha: float = _RECENCY_ALPHA,
-    temporal_alpha: float = _TEMPORAL_ALPHA,
-) -> None:
-    """Apply combined scoring to a list of ScoredResults in-place.
-
-    Uses the cross-encoder score as the primary relevance signal, with recency
-    and temporal proximity applied as multiplicative boosts. This ensures the
-    influence of these secondary signals is always proportional to the base
-    relevance score, regardless of the cross-encoder model's score calibration.
-
-    Formula::
-
-        recency_boost  = 1 + recency_alpha  * (recency  - 0.5)   # in [1-α/2, 1+α/2]
-        temporal_boost = 1 + temporal_alpha * (temporal - 0.5)   # in [1-α/2, 1+α/2]
-        combined_score = cross_encoder_score_normalized * recency_boost * temporal_boost
-
-    Temporal proximity is treated as neutral (0.5) when not set by temporal retrieval,
-    so temporal_boost collapses to 1.0 for non-temporal queries.
-
-    Args:
-        scored_results: Results from the cross-encoder reranker. Mutated in place.
-        now: Current UTC datetime for recency calculation.
-        recency_alpha: Max relative recency adjustment (default 0.2 → ±10%).
-        temporal_alpha: Max relative temporal adjustment (default 0.2 → ±10%).
-    """
-    if now.tzinfo is None:
-        now = now.replace(tzinfo=UTC)
-
-    for sr in scored_results:
-        # Recency: linear decay over 365 days → [0.1, 1.0]; neutral 0.5 if no date.
-        sr.recency = 0.5
-        if sr.retrieval.occurred_start:
-            occurred = sr.retrieval.occurred_start
-            if occurred.tzinfo is None:
-                occurred = occurred.replace(tzinfo=UTC)
-            days_ago = (now - occurred).total_seconds() / 86400
-            sr.recency = max(0.1, min(1.0, 1.0 - (days_ago / 365)))
-
-        # Temporal proximity: meaningful only for temporal queries; neutral otherwise.
-        sr.temporal = sr.retrieval.temporal_proximity if sr.retrieval.temporal_proximity is not None else 0.5
-
-        # RRF: kept at 0.0 for trace continuity but excluded from scoring.
-        # RRF is batch-relative (min-max normalised) and redundant after reranking.
-        sr.rrf_normalized = 0.0
-
-        recency_boost = 1.0 + recency_alpha * (sr.recency - 0.5)
-        temporal_boost = 1.0 + temporal_alpha * (sr.temporal - 0.5)
-        sr.combined_score = sr.cross_encoder_score_normalized * recency_boost * temporal_boost
-        sr.weight = sr.combined_score
-

 class CrossEncoderReranker:
    """
@@ -127,7 +127,7 @@ async def retrieve_semantic_bm25_combined(
        results = await conn.fetch(
            f"""
            WITH semantic_ranked AS (
-                SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, fact_type, document_id, chunk_id, tags,
+                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,
                       NULL::float AS bm25_score,
                       'semantic' AS source,
@@ -139,7 +139,7 @@ async def retrieve_semantic_bm25_combined(
                  AND (1 - (embedding <=> $1::vector)) >= 0.3
                  {tags_clause}
            )
-            SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, fact_type, document_id, chunk_id, tags,
+            SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, embedding, fact_type, document_id, chunk_id, tags,
                   similarity, bm25_score, source
            FROM semantic_ranked
            WHERE rn <= $4
@@ -164,74 +164,99 @@ async def retrieve_semantic_bm25_combined(
    # Build tags clause - param 6 if tags provided
    tags_clause = build_tags_where_clause_simple(tags, 6, match=tags_match)

-    # 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]
+        if tags:
+            params.append(tags)
+
+        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,
+                       NULL::float AS bm25_score,
+                       'semantic' AS source,
+                       ROW_NUMBER() OVER (PARTITION BY fact_type ORDER BY embedding <=> $1::vector) AS rn
+                FROM {fq_table("memory_units")}
+                WHERE bank_id = $2
+                  AND embedding IS NOT NULL
+                  AND fact_type = ANY($3)
+                  AND (1 - (embedding <=> $1::vector)) >= 0.3
+                  {tags_clause}
+            ),
+            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,
+                       search_vector <&> to_bm25query('idx_memory_units_text_search', tokenize($5, 'llmlingua2')) AS bm25_score,
+                       'bm25' AS source,
+                       ROW_NUMBER() OVER (PARTITION BY fact_type ORDER BY search_vector <&> to_bm25query('idx_memory_units_text_search', tokenize($5, 'llmlingua2')) DESC) AS rn
+                FROM {fq_table("memory_units")}
+                WHERE bank_id = $2
+                  AND fact_type = ANY($3)
+                  {tags_clause}
+            ),
+            semantic AS (
+                SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, embedding, fact_type, document_id, chunk_id, tags,
+                       similarity, bm25_score, source
+                FROM semantic_ranked WHERE rn <= $4
+            ),
+            bm25 AS (
+                SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, embedding, fact_type, document_id, chunk_id, tags,
+                       similarity, bm25_score, source
+                FROM bm25_ranked WHERE rn <= $4
+            )
+            SELECT * FROM semantic
+            UNION ALL
+            SELECT * FROM bm25
+        """
    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)

-    if tags:
-        params.append(tags)
-
-    # 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, fact_type, document_id, chunk_id, tags,
-                   1 - (embedding <=> $1::vector) AS similarity,
-                   NULL::float AS bm25_score,
-                   'semantic' AS source,
-                   ROW_NUMBER() OVER (PARTITION BY fact_type ORDER BY embedding <=> $1::vector) AS rn
-            FROM {fq_table("memory_units")}
-            WHERE bank_id = $2
-              AND embedding IS NOT NULL
-              AND fact_type = ANY($3)
-              AND (1 - (embedding <=> $1::vector)) >= 0.3
-              {tags_clause}
-        ),
-        bm25_ranked AS (
-            SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, fact_type, document_id, chunk_id, tags,
-                   NULL::float AS similarity,
-                   {bm25_score_expr} AS bm25_score,
-                   'bm25' AS source,
-                   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)
-              {bm25_where_filter}
-              {tags_clause}
-        ),
-        semantic AS (
-            SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, fact_type, document_id, chunk_id, tags,
-                   similarity, bm25_score, source
-            FROM semantic_ranked WHERE rn <= $4
-        ),
-        bm25 AS (
-            SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, fact_type, document_id, chunk_id, tags,
-                   similarity, bm25_score, source
-            FROM bm25_ranked WHERE rn <= $4
-        )
-        SELECT * FROM semantic
-        UNION ALL
-        SELECT * FROM bm25
-    """
+        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,
+                       NULL::float AS bm25_score,
+                       'semantic' AS source,
+                       ROW_NUMBER() OVER (PARTITION BY fact_type ORDER BY embedding <=> $1::vector) AS rn
+                FROM {fq_table("memory_units")}
+                WHERE bank_id = $2
+                  AND embedding IS NOT NULL
+                  AND fact_type = ANY($3)
+                  AND (1 - (embedding <=> $1::vector)) >= 0.3
+                  {tags_clause}
+            ),
+            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' AS source,
+                       ROW_NUMBER() OVER (PARTITION BY fact_type ORDER BY ts_rank_cd(search_vector, to_tsquery('english', $5)) DESC) AS rn
+                FROM {fq_table("memory_units")}
+                WHERE bank_id = $2
+                  AND fact_type = ANY($3)
+                  AND search_vector @@ to_tsquery('english', $5)
+                  {tags_clause}
+            ),
+            semantic AS (
+                SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, embedding, fact_type, document_id, chunk_id, tags,
+                       similarity, bm25_score, source
+                FROM semantic_ranked WHERE rn <= $4
+            ),
+            bm25 AS (
+                SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, embedding, fact_type, document_id, chunk_id, tags,
+                       similarity, bm25_score, source
+                FROM bm25_ranked WHERE rn <= $4
+            )
+            SELECT * FROM semantic
+            UNION ALL
+            SELECT * FROM bm25
+        """

    # Combined CTE query for both semantic and BM25 across all fact types
    # Uses window functions to limit per fact_type per method
@@ -297,20 +322,13 @@ async def retrieve_temporal_combined(
    if tags:
        params.append(tags)

-    # Two-phase entry point query:
-    # Phase 1 (date_ranked): rank by date only — no embedding computation — for all units in
-    #   the temporal window. This lets the planner use date indexes for filtering.
-    # Phase 2 (sim_ranked): join back to memory_units for only the top-50-per-type candidates
-    #   and compute embedding similarity for that small set (≤ 50 × len(fact_types) rows).
-    # This avoids computing embedding distances for potentially thousands of date-range rows.
+    # Batch query: Get entry points for ALL fact types at once with window function
    entry_points = await conn.fetch(
        f"""
-        WITH date_ranked AS MATERIALIZED (
-            SELECT id, fact_type,
-                   ROW_NUMBER() OVER (
-                       PARTITION BY fact_type
-                       ORDER BY COALESCE(occurred_start, mentioned_at, occurred_end) DESC NULLS LAST
-                   ) AS rn
+        WITH ranked_entries 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,
+                   ROW_NUMBER() OVER (PARTITION BY fact_type ORDER BY COALESCE(occurred_start, mentioned_at, occurred_end) DESC, embedding <=> $1::vector) AS rn
            FROM {fq_table("memory_units")}
            WHERE bank_id = $2
              AND fact_type = ANY($3)
@@ -325,20 +343,12 @@ async def retrieve_temporal_combined(
                  OR
                  (occurred_end IS NOT NULL AND occurred_end BETWEEN $4 AND $5)
              )
+              AND (1 - (embedding <=> $1::vector)) >= $6
              {tags_clause}
-        ),
-        sim_ranked AS (
-            SELECT mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start, mu.occurred_end, mu.mentioned_at, mu.fact_type, mu.document_id, mu.chunk_id, mu.tags,
-                   1 - (mu.embedding <=> $1::vector) AS similarity,
-                   ROW_NUMBER() OVER (PARTITION BY mu.fact_type ORDER BY mu.embedding <=> $1::vector) AS sim_rn
-            FROM date_ranked dr
-            JOIN {fq_table("memory_units")} mu ON mu.id = dr.id
-            WHERE dr.rn <= 50
-              AND (1 - (mu.embedding <=> $1::vector)) >= $6
        )
-        SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, fact_type, document_id, chunk_id, tags, similarity
-        FROM sim_ranked
-        WHERE sim_rn <= 10
+        SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, embedding, fact_type, document_id, chunk_id, tags, similarity
+        FROM ranked_entries
+        WHERE rn <= 10
        """,
        *params,
    )
@@ -402,52 +412,34 @@ async def retrieve_temporal_combined(
        frontier = list(node_scores.keys())
        budget_remaining = budget - len(ft_entry_points)
        batch_size = 20
-        # Per-source neighbor limit: lets the planner use the composite index
-        # (from_unit_id, link_type, weight DESC) with early termination, avoiding
-        # a full scan of all links from all source nodes before sorting.
-        per_source_limit = 10
-        # Safety cap on BFS iterations to prevent runaway spreading in dense graphs.
-        max_iterations = 5
-        iteration = 0

-        # Build tags clause for spreading (use param 7 since 1-6 are used)
-        spreading_tags_clause = build_tags_where_clause_simple(tags, 7, table_alias="mu.", match=tags_match)
+        # Build tags clause for spreading (use param 6 since 1-5 are used)
+        spreading_tags_clause = build_tags_where_clause_simple(tags, 6, table_alias="mu.", match=tags_match)

-        while frontier and budget_remaining > 0 and iteration < max_iterations:
-            iteration += 1
+        while frontier and budget_remaining > 0:
            batch_ids = frontier[:batch_size]
            frontier = frontier[batch_size:]

-            # $1=query_emb, $2=batch_ids, $3=fact_type, $4=threshold, $5=per_source_limit, $6=bank_id, $7=tags
-            spreading_params = [query_emb_str, batch_ids, ft, semantic_threshold, per_source_limit, bank_id]
+            spreading_params = [query_emb_str, batch_ids, ft, semantic_threshold, batch_size * 10]
            if tags:
                spreading_params.append(tags)

-            # LATERAL join: for each source node, fetch top-K neighbors by weight using
-            # the existing idx_memory_links_from_type_weight index with early-exit semantics.
-            # This avoids scanning all temporal links from all source nodes before sorting.
-            # bank_id on memory_units lets the planner use idx_memory_units_bank_fact_type.
            neighbors = await conn.fetch(
                f"""
-                SELECT src.from_unit_id, mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start, mu.occurred_end, mu.mentioned_at, mu.fact_type, mu.document_id, mu.chunk_id, mu.tags,
-                       l.weight, l.link_type,
+                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, mu.tags,
+                       ml.weight, ml.link_type, ml.from_unit_id,
                       1 - (mu.embedding <=> $1::vector) AS similarity
-                FROM unnest($2::uuid[]) AS src(from_unit_id)
-                CROSS JOIN LATERAL (
-                    SELECT ml.to_unit_id, ml.weight, ml.link_type
-                    FROM {fq_table("memory_links")} ml
-                    WHERE ml.from_unit_id = src.from_unit_id
-                      AND ml.link_type IN ('temporal', 'causes', 'caused_by', 'enables', 'prevents')
-                      AND ml.weight >= 0.1
-                    ORDER BY ml.weight DESC
-                    LIMIT $5
-                ) l
-                JOIN {fq_table("memory_units")} mu ON mu.id = l.to_unit_id
-                WHERE mu.bank_id = $6
+                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
                  {spreading_tags_clause}
+                ORDER BY ml.weight DESC
+                LIMIT $5
                """,
                *spreading_params,
            )
@@ -46,6 +46,7 @@ class RetrievalResult:
    mentioned_at: datetime | None = None
    document_id: str | None = None
    chunk_id: str | None = None
+    embedding: list[float] | None = None
    tags: list[str] | None = None  # Visibility scope tags

    # Retrieval-specific scores (only one will be set depending on retrieval method)
@@ -69,6 +70,7 @@ class RetrievalResult:
            mentioned_at=row.get("mentioned_at"),
            document_id=row.get("document_id"),
            chunk_id=row.get("chunk_id"),
+            embedding=row.get("embedding"),
            tags=row.get("tags"),
            similarity=row.get("similarity"),
            bm25_score=row.get("bm25_score"),
@@ -152,6 +154,7 @@ class ScoredResult:
            "mentioned_at": self.retrieval.mentioned_at,
            "document_id": self.retrieval.document_id,
            "chunk_id": self.retrieval.chunk_id,
+            "embedding": self.retrieval.embedding,
            "tags": self.retrieval.tags,
            "semantic_similarity": self.retrieval.similarity,
            "bm25_score": self.retrieval.bm25_score,
@@ -1,79 +0,0 @@
-"""File storage backends for uploaded files."""
-
-from collections.abc import Callable
-
-from .base import FileStorage
-from .postgresql import PostgreSQLFileStorage
-
-__all__ = ["FileStorage", "PostgreSQLFileStorage", "create_file_storage"]
-
-
-def create_file_storage(
-    storage_type: str,
-    pool_getter: Callable | None = None,
-    schema: str | None = None,
-    schema_getter: Callable | None = None,
-    **kwargs,
-) -> FileStorage:
-    """
-    Create file storage backend based on configuration.
-
-    Args:
-        storage_type: "native" (PostgreSQL BYTEA) or "s3" (S3-compatible object storage)
-        pool_getter: Database pool getter (required for native)
-        schema: Static database schema (for native single-tenant)
-        schema_getter: Callable returning current schema at query time (for native multi-tenant)
-        **kwargs: Additional args passed to storage backend
-
-    Returns:
-        FileStorage instance
-
-    Raises:
-        ValueError: If storage_type is unknown or required args are missing
-    """
-    if storage_type == "native":
-        if not pool_getter:
-            raise ValueError("pool_getter required for native (PostgreSQL) storage")
-        return PostgreSQLFileStorage(pool_getter=pool_getter, schema=schema, schema_getter=schema_getter)
-    elif storage_type == "s3":
-        from ...config import get_config
-        from .s3 import S3FileStorage
-
-        config = get_config()
-        bucket = config.file_storage_s3_bucket
-        if not bucket:
-            raise ValueError("HINDSIGHT_API_FILE_STORAGE_S3_BUCKET is required for S3 storage")
-        return S3FileStorage(
-            bucket=bucket,
-            region=config.file_storage_s3_region,
-            endpoint=config.file_storage_s3_endpoint,
-            access_key_id=config.file_storage_s3_access_key_id,
-            secret_access_key=config.file_storage_s3_secret_access_key,
-        )
-    elif storage_type == "gcs":
-        from ...config import get_config
-        from .gcs import GCSFileStorage
-
-        config = get_config()
-        bucket = config.file_storage_gcs_bucket
-        if not bucket:
-            raise ValueError("HINDSIGHT_API_FILE_STORAGE_GCS_BUCKET is required for GCS storage")
-        return GCSFileStorage(
-            bucket=bucket,
-            service_account_key=config.file_storage_gcs_service_account_key,
-        )
-    elif storage_type == "azure":
-        from ...config import get_config
-        from .azure import AzureFileStorage
-
-        config = get_config()
-        container = config.file_storage_azure_container
-        if not container:
-            raise ValueError("HINDSIGHT_API_FILE_STORAGE_AZURE_CONTAINER is required for Azure storage")
-        return AzureFileStorage(
-            container_name=container,
-            account_name=config.file_storage_azure_account_name,
-            account_key=config.file_storage_azure_account_key,
-        )
-    else:
-        raise ValueError(f"Unknown storage type: {storage_type}. Supported: 'native', 's3', 'gcs', 'azure'.")
@@ -1,62 +0,0 @@
-"""Azure Blob Storage backend using obstore."""
-
-import logging
-from datetime import timedelta
-
-import obstore as obs
-from obstore.store import AzureStore
-
-from .base import FileStorage
-
-logger = logging.getLogger(__name__)
-
-
-class AzureFileStorage(FileStorage):
-    """
-    Azure Blob Storage backend.
-
-    Uses obstore (Rust-backed) for high-throughput async access to Azure Blob Storage.
-    Supports account key, SAS token, and default Azure credentials.
-    """
-
-    def __init__(
-        self,
-        container_name: str,
-        account_name: str | None = None,
-        account_key: str | None = None,
-    ):
-        kwargs: dict = {}
-        if account_name:
-            kwargs["account_name"] = account_name
-        if account_key:
-            kwargs["account_key"] = account_key
-
-        self._store = AzureStore(container_name, **kwargs)
-        logger.info(f"Initialized Azure file storage: container={container_name}, account={account_name}")
-
-    async def store(self, file_data: bytes, key: str, metadata: dict[str, str] | None = None) -> str:
-        await obs.put_async(self._store, key, file_data)
-        logger.debug(f"Stored file {key} ({len(file_data)} bytes) in Azure")
-        return key
-
-    async def retrieve(self, key: str) -> bytes:
-        try:
-            response = await obs.get_async(self._store, key)
-            return await response.bytes_async()
-        except Exception as e:
-            if "not found" in str(e).lower() or "BlobNotFound" in str(e):
-                raise FileNotFoundError(f"File not found: {key}") from e
-            raise
-
-    async def delete(self, key: str) -> None:
-        await obs.delete_async(self._store, key)
-
-    async def exists(self, key: str) -> bool:
-        try:
-            await obs.head_async(self._store, key)
-            return True
-        except Exception:
-            return False
-
-    async def get_download_url(self, key: str, expires_in: int = 3600) -> str:
-        return await obs.sign_async(self._store, "GET", key, timedelta(seconds=expires_in))
@@ -1,83 +0,0 @@
-"""Abstract base class for file storage backends."""
-
-from abc import ABC, abstractmethod
-
-
-class FileStorage(ABC):
-    """Abstract base for file storage backends."""
-
-    @abstractmethod
-    async def store(
-        self,
-        file_data: bytes,
-        key: str,
-        metadata: dict[str, str] | None = None,
-    ) -> str:
-        """
-        Store file and return storage key.
-
-        Args:
-            file_data: Raw file bytes
-            key: Storage key (e.g., "banks/{bank_id}/files/{file_id}.pdf")
-            metadata: Optional metadata to store with file
-
-        Returns:
-            Storage key that can be used to retrieve the file
-        """
-        pass
-
-    @abstractmethod
-    async def retrieve(self, key: str) -> bytes:
-        """
-        Retrieve file by storage key.
-
-        Args:
-            key: Storage key
-
-        Returns:
-            File data as bytes
-
-        Raises:
-            FileNotFoundError: If file does not exist
-        """
-        pass
-
-    @abstractmethod
-    async def delete(self, key: str) -> None:
-        """
-        Delete file by storage key.
-
-        Args:
-            key: Storage key
-        """
-        pass
-
-    @abstractmethod
-    async def exists(self, key: str) -> bool:
-        """
-        Check if file exists.
-
-        Args:
-            key: Storage key
-
-        Returns:
-            True if file exists, False otherwise
-        """
-        pass
-
-    @abstractmethod
-    async def get_download_url(self, key: str, expires_in: int = 3600) -> str:
-        """
-        Get a URL for downloading the file.
-
-        For PostgreSQL storage, this might be a relative API path.
-        For S3, this would be a pre-signed URL.
-
-        Args:
-            key: Storage key
-            expires_in: Expiration time in seconds (may be ignored for some backends)
-
-        Returns:
-            Download URL or path
-        """
-        pass
@@ -1,105 +0,0 @@
-"""Google Cloud Storage backend using obstore."""
-
-import logging
-import os
-from datetime import datetime, timedelta, timezone
-
-import obstore as obs
-from obstore.store import GCSStore
-
-from .base import FileStorage
-
-logger = logging.getLogger(__name__)
-
-
-def _make_google_auth_credential_provider():
-    """Create a credential provider using google.auth (supports all credential types).
-
-    obstore's built-in credential parsing only supports service_account and
-    authorized_user JSON types.  This provider uses the google-auth library
-    which additionally handles external_account (Workload Identity Federation),
-    impersonated credentials, and metadata-server credentials.
-    """
-    import google.auth
-    import google.auth.transport.requests
-
-    credentials, _ = google.auth.default(scopes=["https://www.googleapis.com/auth/cloud-platform"])
-    request = google.auth.transport.requests.Request()
-
-    def _provide():
-        credentials.refresh(request)
-        expiry = credentials.expiry
-        if expiry and expiry.tzinfo is None:
-            expiry = expiry.replace(tzinfo=timezone.utc)
-        return {"token": credentials.token, "expires_at": expiry}
-
-    return _provide
-
-
-class GCSFileStorage(FileStorage):
-    """
-    Google Cloud Storage backend.
-
-    Uses obstore (Rust-backed) for high-throughput async access to GCS.
-    Supports Application Default Credentials, service account keys, and explicit credentials.
-    """
-
-    def __init__(
-        self,
-        bucket: str,
-        service_account_key: str | None = None,
-    ):
-        kwargs: dict = {}
-        if service_account_key:
-            kwargs["service_account_key"] = service_account_key
-        else:
-            # Use google.auth credential provider for broad credential type support
-            # (service_account, authorized_user, external_account, metadata server, etc.)
-            try:
-                kwargs["credential_provider"] = _make_google_auth_credential_provider()
-                logger.info("Using google.auth credential provider for GCS")
-            except Exception as e:
-                logger.warning(
-                    f"Failed to create google.auth credential provider, falling back to obstore defaults: {e}"
-                )
-
-        # Workaround for https://github.com/developmentseed/obstore/issues/605
-        # obstore's Rust layer doesn't support external_account credentials (Workload
-        # Identity Federation) and eagerly parses GOOGLE_APPLICATION_CREDENTIALS even
-        # when credential_provider is given. Per the obstore maintainer's guidance,
-        # remove env vars so the Rust code doesn't try to authenticate itself.
-        # google.auth (used by credential_provider above) has already loaded credentials.
-        gac = os.environ.pop("GOOGLE_APPLICATION_CREDENTIALS", None)
-        try:
-            self._store = GCSStore(bucket, **kwargs)
-        finally:
-            if gac is not None:
-                os.environ["GOOGLE_APPLICATION_CREDENTIALS"] = gac
-        logger.info(f"Initialized GCS file storage: bucket={bucket}")
-
-    async def store(self, file_data: bytes, key: str, metadata: dict[str, str] | None = None) -> str:
-        await obs.put_async(self._store, key, file_data)
-        logger.debug(f"Stored file {key} ({len(file_data)} bytes) in GCS")
-        return key
-
-    async def retrieve(self, key: str) -> bytes:
-        try:
-            response = await obs.get_async(self._store, key)
-            return await response.bytes_async()
-        except Exception as e:
-            if "not found" in str(e).lower():
-                raise FileNotFoundError(f"File not found: {key}") from e
-            raise
-
-    async def delete(self, key: str) -> None:
-        await obs.delete_async(self._store, key)
-
-    async def exists(self, key: str) -> bool:
-        try:
-            await obs.head_async(self._store, key)
-            return True
-        except Exception:
-            return False
-
-    async def get_download_url(self, key: str, expires_in: int = 3600) -> str:
-        return await obs.sign_async(self._store, "GET", key, timedelta(seconds=expires_in))
@@ -1,153 +0,0 @@
-"""PostgreSQL BYTEA-based file storage (default, zero-config)."""
-
-import logging
-from collections.abc import Callable
-from typing import TYPE_CHECKING
-
-if TYPE_CHECKING:
-    import asyncpg
-
-from .base import FileStorage
-
-logger = logging.getLogger(__name__)
-
-
-def fq_table(table: str, schema: str | None = None) -> str:
-    """Get fully-qualified table name with optional schema prefix."""
-    if schema:
-        return f'"{schema}".{table}'
-    return table
-
-
-class PostgreSQLFileStorage(FileStorage):
-    """
-    PostgreSQL BYTEA-based file storage.
-
-    Stores files directly in PostgreSQL using BYTEA columns.
-    This is the default storage backend - zero configuration required!
-
-    Pros:
-    - Works out of the box (no external dependencies)
-    - Transactional consistency with database
-    - Simple backups (included in pg_dump)
-    - Good performance for <10MB files
-
-    Cons:
-    - Database bloat for large/many files
-    - Not ideal for distributed deployments
-    - Higher cost than object storage at scale
-
-    For production/scale, consider S3FileStorage instead.
-    """
-
-    def __init__(
-        self,
-        pool_getter: Callable[[], "asyncpg.Pool"],
-        schema: str | None = None,
-        schema_getter: Callable[[], str] | None = None,
-    ):
-        """
-        Initialize PostgreSQL file storage.
-
-        Args:
-            pool_getter: Function that returns asyncpg connection pool
-            schema: Static database schema (fallback for single-tenant / tests)
-            schema_getter: Callable returning current schema at query time (for multi-tenant)
-        """
-        self._pool_getter = pool_getter
-        self._static_schema = schema
-        self._schema_getter = schema_getter
-
-    @property
-    def _schema(self) -> str | None:
-        """Resolve schema dynamically per-request when schema_getter is provided."""
-        if self._schema_getter:
-            return self._schema_getter()
-        return self._static_schema
-
-    async def store(
-        self,
-        file_data: bytes,
-        key: str,
-        metadata: dict[str, str] | None = None,
-    ) -> str:
-        """Store file in PostgreSQL."""
-        pool = self._pool_getter()
-
-        async with pool.acquire() as conn:
-            await conn.execute(
-                f"""
-                INSERT INTO {fq_table("file_storage", self._schema)}
-                (storage_key, data)
-                VALUES ($1, $2)
-                ON CONFLICT (storage_key) DO UPDATE SET
-                    data = EXCLUDED.data
-                """,
-                key,
-                file_data,
-            )
-
-        logger.debug(f"Stored file {key} ({len(file_data)} bytes) in PostgreSQL")
-        return key
-
-    async def retrieve(self, key: str) -> bytes:
-        """Retrieve file from PostgreSQL."""
-        pool = self._pool_getter()
-
-        async with pool.acquire() as conn:
-            row = await conn.fetchrow(
-                f"""
-                SELECT data FROM {fq_table("file_storage", self._schema)}
-                WHERE storage_key = $1
-                """,
-                key,
-            )
-
-            if not row:
-                raise FileNotFoundError(f"File not found: {key}")
-
-            return bytes(row["data"])
-
-    async def delete(self, key: str) -> None:
-        """Delete file from PostgreSQL."""
-        pool = self._pool_getter()
-
-        async with pool.acquire() as conn:
-            result = await conn.execute(
-                f"""
-                DELETE FROM {fq_table("file_storage", self._schema)}
-                WHERE storage_key = $1
-                """,
-                key,
-            )
-
-            # Check if anything was deleted
-            if result == "DELETE 0":
-                logger.warning(f"Attempted to delete non-existent file: {key}")
-
-    async def exists(self, key: str) -> bool:
-        """Check if file exists in PostgreSQL."""
-        pool = self._pool_getter()
-
-        async with pool.acquire() as conn:
-            row = await conn.fetchrow(
-                f"""
-                SELECT 1 FROM {fq_table("file_storage", self._schema)}
-                WHERE storage_key = $1
-                """,
-                key,
-            )
-
-            return row is not None
-
-    async def get_download_url(self, key: str, expires_in: int = 3600) -> str:
-        """
-        Get download URL for PostgreSQL-stored file.
-
-        Returns an API endpoint path (not a pre-signed URL since the file
-        is stored in the database). The expires_in parameter is ignored
-        for PostgreSQL storage.
-        """
-        # Return API path for download endpoint
-        # (expires_in ignored for database storage - auth handled at API level)
-        return f"/v1/default/files/download/{key}"
@@ -1,71 +0,0 @@
-"""S3 object storage backend using obstore."""
-
-import logging
-from datetime import timedelta
-
-import obstore as obs
-from obstore.store import S3Store
-
-from .base import FileStorage
-
-logger = logging.getLogger(__name__)
-
-
-class S3FileStorage(FileStorage):
-    """
-    S3-compatible object storage backend.
-
-    Uses obstore (Rust-backed) for high-throughput async access to
-    Amazon S3, MinIO, Cloudflare R2, and other S3-compliant APIs.
-    """
-
-    def __init__(
-        self,
-        bucket: str,
-        region: str | None = None,
-        endpoint: str | None = None,
-        access_key_id: str | None = None,
-        secret_access_key: str | None = None,
-    ):
-        kwargs: dict = {}
-        if region:
-            kwargs["region"] = region
-        if endpoint:
-            kwargs["endpoint"] = endpoint
-            # Allow plain HTTP for local S3-compatible services (MinIO, LocalStack, etc.)
-            if endpoint.startswith("http://"):
-                kwargs["allow_http"] = True
-        if access_key_id:
-            kwargs["access_key_id"] = access_key_id
-        if secret_access_key:
-            kwargs["secret_access_key"] = secret_access_key
-
-        self._store = S3Store(bucket, **kwargs)
-        logger.info(f"Initialized S3 file storage: bucket={bucket}, region={region}, endpoint={endpoint}")
-
-    async def store(self, file_data: bytes, key: str, metadata: dict[str, str] | None = None) -> str:
-        await obs.put_async(self._store, key, file_data)
-        logger.debug(f"Stored file {key} ({len(file_data)} bytes) in S3")
-        return key
-
-    async def retrieve(self, key: str) -> bytes:
-        try:
-            response = await obs.get_async(self._store, key)
-            return await response.bytes_async()
-        except Exception as e:
-            if "not found" in str(e).lower() or "NoSuchKey" in str(e):
-                raise FileNotFoundError(f"File not found: {key}") from e
-            raise
-
-    async def delete(self, key: str) -> None:
-        await obs.delete_async(self._store, key)
-
-    async def exists(self, key: str) -> bool:
-        try:
-            await obs.head_async(self._store, key)
-            return True
-        except Exception:
-            return False
-
-    async def get_download_url(self, key: str, expires_in: int = 3600) -> str:
-        return await obs.sign_async(self._store, "GET", key, timedelta(seconds=expires_in))
@@ -22,16 +22,9 @@ from hindsight_api.extensions.http import HttpExtension
 from hindsight_api.extensions.loader import load_extension
 from hindsight_api.extensions.mcp import MCPExtension
 from hindsight_api.extensions.operation_validator import (
-    # Bank Management operations
-    BankListContext,
-    BankListResult,
-    BankReadContext,
-    BankWriteContext,
    # Consolidation operation
    ConsolidateContext,
    ConsolidateResult,
-    # File Conversion
-    FileConvertResult,
    # Mental Model operations
    MentalModelGetContext,
    MentalModelGetResult,
@@ -77,16 +70,9 @@ __all__ = [
    "RetainContext",
    "RetainResult",
    "ValidationResult",
-    # Operation Validator - Bank Management
-    "BankListContext",
-    "BankListResult",
-    "BankReadContext",
-    "BankWriteContext",
    # Operation Validator - Consolidation
    "ConsolidateContext",
    "ConsolidateResult",
-    # Operation Validator - File Conversion
-    "FileConvertResult",
    # Operation Validator - Mental Model
    "MentalModelGetContext",
    "MentalModelGetResult",
@@ -96,8 +96,6 @@ class DefaultExtensionContext(ExtensionContext):

    async def run_migration(self, schema: str) -> None:
        """Run migrations for a specific schema."""
-        import asyncio
-
        from hindsight_api.config import get_config
        from hindsight_api.migrations import (
            ensure_embedding_dimension,
@@ -113,14 +111,10 @@ class DefaultExtensionContext(ExtensionContext):
            if engine_url:
                db_url = engine_url

-        # Run synchronous migration functions in a thread so the asyncio event loop
-        # remains free. This is critical for single-machine deployments where the
-        # worker runs in-process: if run_migrations() blocks the event loop, any
-        # in-flight asyncpg transactions cannot flush their COMMIT, and
-        # CREATE INDEX CONCURRENTLY inside the migration waits for those transactions
-        # forever — a deadlock.
+        run_migrations(db_url, schema=schema)
+
+        # Get config for vector extension setting
        config = get_config()
-        await asyncio.to_thread(run_migrations, db_url, schema=schema)

        # Ensure embedding column dimension matches the model's dimension
        # This is needed because migrations create columns with default dimension
@@ -129,23 +123,15 @@ class DefaultExtensionContext(ExtensionContext):
            if embeddings is not None:
                dimension = getattr(embeddings, "dimension", None)
                if dimension is not None:
-                    await asyncio.to_thread(
-                        ensure_embedding_dimension,
-                        db_url,
-                        dimension,
-                        schema=schema,
-                        vector_extension=config.vector_extension,
+                    ensure_embedding_dimension(
+                        db_url, dimension, schema=schema, vector_extension=config.vector_extension
                    )

        # Ensure vector indexes match the configured extension
-        await asyncio.to_thread(
-            ensure_vector_extension, db_url, vector_extension=config.vector_extension, schema=schema
-        )
+        ensure_vector_extension(db_url, vector_extension=config.vector_extension, schema=schema)

        # Ensure text search columns/indexes match the configured extension
-        await asyncio.to_thread(
-            ensure_text_search_extension, db_url, text_search_extension=config.text_search_extension, schema=schema
-        )
+        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."""
@@ -87,15 +87,3 @@ class HttpExtension(Extension, ABC):
            ```
        """
        pass
-
-    def get_root_router(self, memory: "MemoryEngine") -> APIRouter | None:
-        """
-        Return a FastAPI router with endpoints mounted at the app root.
-
-        Unlike get_router() which is mounted at /ext/, this router is mounted
-        directly on the application root. Use for well-known endpoints or other
-        paths that must be at specific locations.
-
-        Returns None by default (no root routes). Override to provide root-level routes.
-        """
-        return None
@@ -200,44 +200,6 @@ class ConsolidateResult:
    error: str | None = None


-# =============================================================================
-# Bank Management Contexts
-# =============================================================================
-
-
-@dataclass
-class BankReadContext:
-    """Context for a bank read operation validation (pre-operation)."""
-
-    bank_id: str
-    operation: str  # "get_bank_profile", "get_bank_stats"
-    request_context: "RequestContext"
-
-
-@dataclass
-class BankWriteContext:
-    """Context for a bank write operation validation (pre-operation)."""
-
-    bank_id: str
-    operation: str  # "delete_bank", "update_bank", "update_bank_disposition", "set_bank_mission", "merge_bank_mission", "clear_observations", "clear_observations_for_memory"
-    request_context: "RequestContext"
-
-
-@dataclass
-class BankListContext:
-    """Context for filtering the bank list (post-query)."""
-
-    banks: list[dict]
-    request_context: "RequestContext"
-
-
-@dataclass
-class BankListResult:
-    """Result of filtering the bank list."""
-
-    banks: list[dict]
-
-
 # =============================================================================
 # Mental Model Contexts
 # =============================================================================
@@ -289,28 +251,6 @@ class MentalModelRefreshResult:
    error: str | None = None


-# =============================================================================
-# File Conversion Post-operation Context
-# =============================================================================
-
-
-@dataclass
-class FileConvertResult:
-    """Result context for post-file-conversion hook.
-
-    Fired after a file is converted to markdown, before the retain step.
-    """
-
-    bank_id: str
-    parser_name: str
-    filename: str
-    output_chars: int
-    output_text: str
-    request_context: "RequestContext"
-    success: bool = True
-    error: str | None = None
-
-
 class OperationValidatorExtension(Extension, ABC):
    """
    Validates and hooks into retain/recall/reflect/consolidate operations.
@@ -518,31 +458,6 @@ class OperationValidatorExtension(Extension, ABC):
        """
        pass

-    # =========================================================================
-    # File Conversion - Post-operation hook (optional - override to implement)
-    # =========================================================================
-
-    async def on_file_convert_complete(self, result: FileConvertResult) -> None:
-        """
-        Called after a file is converted to markdown (before the retain step).
-
-        Override to implement post-conversion logic such as:
-        - Billing for premium parsers (e.g., Iris)
-        - Usage tracking
-        - Audit logging
-
-        Args:
-            result: Result context containing:
-                - bank_id: Bank identifier
-                - parser_name: Name of the parser used (e.g., 'markitdown', 'iris')
-                - filename: Original filename
-                - output_chars: Character count of the converted markdown
-                - request_context: Request context with auth info
-                - success: Whether the conversion succeeded
-                - error: Error message (if failed)
-        """
-        pass
-
    # =========================================================================
    # Mental Model - Pre-operation validation hook (optional - override to implement)
    # =========================================================================
@@ -620,63 +535,3 @@ class OperationValidatorExtension(Extension, ABC):
                - error: Error message (if failed)
        """
        pass
-
-    # =========================================================================
-    # Bank Management - Validation hooks (optional - override to implement)
-    # =========================================================================
-
-    async def validate_bank_read(self, ctx: BankReadContext) -> ValidationResult:
-        """
-        Validate a bank read operation before execution.
-
-        Override to implement custom validation logic for bank reads
-        (get_bank_profile, get_bank_stats).
-
-        Args:
-            ctx: Context containing:
-                - bank_id: Bank identifier
-                - operation: Operation name
-                - request_context: Request context with auth info
-
-        Returns:
-            ValidationResult indicating whether the operation is allowed.
-        """
-        return ValidationResult.accept()
-
-    async def validate_bank_write(self, ctx: BankWriteContext) -> ValidationResult:
-        """
-        Validate a bank write operation before execution.
-
-        Override to implement custom validation logic for bank writes
-        (delete_bank, update_bank, update_bank_disposition, set_bank_mission,
-        merge_bank_mission, clear_observations, clear_observations_for_memory).
-
-        Args:
-            ctx: Context containing:
-                - bank_id: Bank identifier
-                - operation: Operation name
-                - request_context: Request context with auth info
-
-        Returns:
-            ValidationResult indicating whether the operation is allowed.
-        """
-        return ValidationResult.accept()
-
-    async def filter_bank_list(self, ctx: BankListContext) -> BankListResult:
-        """
-        Filter the bank list after querying.
-
-        Unlike validate_* methods, this is a post-query filter that narrows results
-        rather than a gate that blocks the operation.
-
-        Override to implement custom filtering (e.g., restrict to allowed banks).
-
-        Args:
-            ctx: Context containing:
-                - banks: List of bank dicts from the database
-                - request_context: Request context with auth info
-
-        Returns:
-            BankListResult with the filtered list of banks.
-        """
-        return BankListResult(banks=ctx.banks)
@@ -11,9 +11,8 @@ from hindsight_api.models import RequestContext
 class AuthenticationError(Exception):
    """Raised when authentication fails."""

-    def __init__(self, reason: str, headers: dict[str, str] | None = None):
+    def __init__(self, reason: str):
        self.reason = reason
-        self.headers = headers or {}
        super().__init__(f"Authentication failed: {reason}")


@@ -166,12 +166,9 @@ def main():
            llm_initial_backoff=config.llm_initial_backoff,
            llm_max_backoff=config.llm_max_backoff,
            llm_timeout=config.llm_timeout,
-            llm_groq_service_tier=config.llm_groq_service_tier,
-            llm_openai_service_tier=config.llm_openai_service_tier,
            llm_vertexai_project_id=config.llm_vertexai_project_id,
            llm_vertexai_region=config.llm_vertexai_region,
            llm_vertexai_service_account_key=config.llm_vertexai_service_account_key,
-            llm_gemini_safety_settings=config.llm_gemini_safety_settings,
            retain_llm_provider=config.retain_llm_provider,
            retain_llm_api_key=config.retain_llm_api_key,
            retain_llm_model=config.retain_llm_model,
@@ -211,9 +208,6 @@ 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,
@@ -229,18 +223,12 @@ 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,
-            reranker_zeroentropy_api_key=config.reranker_zeroentropy_api_key,
-            reranker_zeroentropy_model=config.reranker_zeroentropy_model,
            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,
-            mcp_enabled_tools=config.mcp_enabled_tools,
            enable_bank_config_api=config.enable_bank_config_api,
            graph_retriever=config.graph_retriever,
            mpfp_top_k_neighbors=config.mpfp_top_k_neighbors,
@@ -250,42 +238,10 @@ def main():
            retain_chunk_size=config.retain_chunk_size,
            retain_extract_causal_links=config.retain_extract_causal_links,
            retain_extraction_mode=config.retain_extraction_mode,
-            retain_mission=config.retain_mission,
            retain_custom_instructions=config.retain_custom_instructions,
-            retain_batch_tokens=config.retain_batch_tokens,
-            retain_entity_lookup=config.retain_entity_lookup,
-            retain_batch_enabled=config.retain_batch_enabled,
-            retain_batch_poll_interval_seconds=config.retain_batch_poll_interval_seconds,
-            file_storage_type=config.file_storage_type,
-            file_storage_s3_bucket=config.file_storage_s3_bucket,
-            file_storage_s3_region=config.file_storage_s3_region,
-            file_storage_s3_endpoint=config.file_storage_s3_endpoint,
-            file_storage_s3_access_key_id=config.file_storage_s3_access_key_id,
-            file_storage_s3_secret_access_key=config.file_storage_s3_secret_access_key,
-            file_storage_gcs_bucket=config.file_storage_gcs_bucket,
-            file_storage_gcs_service_account_key=config.file_storage_gcs_service_account_key,
-            file_storage_azure_container=config.file_storage_azure_container,
-            file_storage_azure_account_name=config.file_storage_azure_account_name,
-            file_storage_azure_account_key=config.file_storage_azure_account_key,
-            file_parser=config.file_parser,
-            file_parser_allowlist=config.file_parser_allowlist,
-            file_parser_iris_token=config.file_parser_iris_token,
-            file_parser_iris_org_id=config.file_parser_iris_org_id,
-            file_conversion_max_batch_size_mb=config.file_conversion_max_batch_size_mb,
-            file_conversion_max_batch_size=config.file_conversion_max_batch_size,
-            enable_file_upload_api=config.enable_file_upload_api,
-            file_delete_after_retain=config.file_delete_after_retain,
            enable_observations=config.enable_observations,
-            enable_observation_history=config.enable_observation_history,
-            enable_mental_model_history=config.enable_mental_model_history,
            consolidation_batch_size=config.consolidation_batch_size,
-            consolidation_llm_batch_size=config.consolidation_llm_batch_size,
            consolidation_max_tokens=config.consolidation_max_tokens,
-            consolidation_source_facts_max_tokens=config.consolidation_source_facts_max_tokens,
-            consolidation_source_facts_max_tokens_per_observation=config.consolidation_source_facts_max_tokens_per_observation,
-            observations_mission=config.observations_mission,
-            entity_labels=config.entity_labels,
-            entities_allow_free_form=config.entities_allow_free_form,
            skip_llm_verification=config.skip_llm_verification,
            lazy_reranker=config.lazy_reranker,
            run_migrations_on_startup=config.run_migrations_on_startup,
@@ -301,21 +257,12 @@ def main():
            worker_max_slots=config.worker_max_slots,
            worker_consolidation_max_slots=config.worker_consolidation_max_slots,
            reflect_max_iterations=config.reflect_max_iterations,
-            reflect_max_context_tokens=config.reflect_max_context_tokens,
-            reflect_mission=config.reflect_mission,
-            disposition_skepticism=config.disposition_skepticism,
-            disposition_literalism=config.disposition_literalism,
-            disposition_empathy=config.disposition_empathy,
            mental_model_refresh_concurrency=config.mental_model_refresh_concurrency,
            otel_traces_enabled=config.otel_traces_enabled,
            otel_exporter_otlp_endpoint=config.otel_exporter_otlp_endpoint,
            otel_exporter_otlp_headers=config.otel_exporter_otlp_headers,
            otel_service_name=config.otel_service_name,
            otel_deployment_environment=config.otel_deployment_environment,
-            webhook_url=config.webhook_url,
-            webhook_secret=config.webhook_secret,
-            webhook_event_types=config.webhook_event_types,
-            webhook_delivery_poll_interval_seconds=config.webhook_delivery_poll_interval_seconds,
        )
    config.configure_logging()
    if not args.daemon:
@@ -393,8 +340,6 @@ def main():
        "proxy_headers": args.proxy_headers,
        "ws": "wsproto",  # Use wsproto instead of websockets to avoid deprecation warnings
        "loop": loop_impl,  # Explicitly set event loop implementation
-        "timeout_keep_alive": 30,  # Exceed aiohttp's 15s client timeout so the client always closes first
-        "timeout_graceful_shutdown": 5,  # Cap graceful shutdown at 5s; also enables force-kill on second Ctrl+C
    }

    # Add optional parameters if provided
@@ -423,8 +368,6 @@ def main():
            reranker_provider=config.reranker_provider,
            mcp_enabled=config.mcp_enabled,
            version=__version__,
-            vector_extension=config.vector_extension,
-            text_search_extension=config.text_search_extension,
        )

    # Start idle checker in daemon mode
@@ -1,14 +1,8 @@
 """
-Local MCP server entry point for use with Claude Code (HTTP transport).
+Local MCP server for use with Claude Code (stdio transport).

-This is a thin wrapper around the main hindsight-api server that pre-configures
-sensible defaults for local use (embedded PostgreSQL via pg0, warning log level).
-
-The full API runs on localhost:8888. Configure Claude Code's MCP settings:
-    claude mcp add --transport http hindsight http://localhost:8888/mcp/
-
-Or pinned to a specific bank (single-bank mode):
-    claude mcp add --transport http hindsight http://localhost:8888/mcp/default/
+This runs a fully local Hindsight instance with embedded PostgreSQL (pg0).
+No external database or server required.

 Run with:
    hindsight-local-mcp
@@ -16,24 +10,148 @@ Run with:
 Or with uvx:
    uvx hindsight-api@latest hindsight-local-mcp

+Configure in Claude Code's MCP settings:
+    {
+        "mcpServers": {
+            "hindsight": {
+                "command": "uvx",
+                "args": ["hindsight-api@latest", "hindsight-local-mcp"],
+                "env": {
+                    "HINDSIGHT_API_LLM_API_KEY": "your-openai-key"
+                }
+            }
+        }
+    }
+
 Environment variables:
    HINDSIGHT_API_LLM_API_KEY: Required. API key for LLM provider.
    HINDSIGHT_API_LLM_PROVIDER: Optional. LLM provider (default: "openai").
    HINDSIGHT_API_LLM_MODEL: Optional. LLM model (default: "gpt-4o-mini").
-    HINDSIGHT_API_DATABASE_URL: Optional. Override database URL (default: pg0://hindsight-mcp).
+    HINDSIGHT_API_MCP_LOCAL_BANK_ID: Optional. Memory bank ID (default: "mcp").
+    HINDSIGHT_API_LOG_LEVEL: Optional. Log level (default: "warning").
+    HINDSIGHT_API_MCP_INSTRUCTIONS: Optional. Additional instructions appended to both retain and recall tools.
+
+Example custom instructions (these are ADDED to the default behavior):
+    To also store assistant actions:
+        HINDSIGHT_API_MCP_INSTRUCTIONS="Also store every action you take, including tool calls, code written, and decisions made."
+
+    To also store conversation summaries:
+        HINDSIGHT_API_MCP_INSTRUCTIONS="Also store summaries of important conversations and their outcomes."
 """

+import logging
 import os
+import sys
+
+from mcp.server.fastmcp import FastMCP
+
+from hindsight_api.config import (
+    DEFAULT_MCP_LOCAL_BANK_ID,
+    DEFAULT_MCP_RECALL_DESCRIPTION,
+    DEFAULT_MCP_RETAIN_DESCRIPTION,
+    ENV_MCP_INSTRUCTIONS,
+    ENV_MCP_LOCAL_BANK_ID,
+)
+from hindsight_api.mcp_tools import MCPToolsConfig, register_mcp_tools
+
+# Configure logging - default to warning to avoid polluting stderr during MCP init
+# MCP clients interpret stderr output as errors, so we suppress INFO logs by default
+_log_level_str = os.environ.get("HINDSIGHT_API_LOG_LEVEL", "warning").lower()
+_log_level_map = {
+    "critical": logging.CRITICAL,
+    "error": logging.ERROR,
+    "warning": logging.WARNING,
+    "info": logging.INFO,
+    "debug": logging.DEBUG,
+}
+logging.basicConfig(
+    level=_log_level_map.get(_log_level_str, logging.WARNING),
+    format="%(asctime)s - %(levelname)s - %(name)s - %(message)s",
+    stream=sys.stderr,  # MCP uses stdout for protocol, logs go to stderr
+)
+logger = logging.getLogger(__name__)


-def main() -> None:
-    """Start the Hindsight API server with local defaults."""
-    # Set local defaults (only if not already configured by the user)
-    os.environ.setdefault("HINDSIGHT_API_DATABASE_URL", "pg0://hindsight-mcp")
+def create_local_mcp_server(bank_id: str, memory=None) -> FastMCP:
+    """
+    Create a stdio MCP server with retain/recall tools.

-    from hindsight_api.main import main as api_main
+    Args:
+        bank_id: The memory bank ID to use for all operations.
+        memory: Optional MemoryEngine instance. If not provided, creates one with pg0.

-    api_main()
+    Returns:
+        Configured FastMCP server instance.
+    """
+    # Import here to avoid slow startup if just checking --help
+    from hindsight_api import MemoryEngine
+
+    # Create memory engine with pg0 embedded database if not provided
+    if memory is None:
+        memory = MemoryEngine(db_url="pg0://hindsight-mcp")
+
+    # Get custom instructions from environment variable (appended to both tools)
+    extra_instructions = os.environ.get(ENV_MCP_INSTRUCTIONS, "")
+
+    retain_description = DEFAULT_MCP_RETAIN_DESCRIPTION
+    recall_description = DEFAULT_MCP_RECALL_DESCRIPTION
+
+    if extra_instructions:
+        retain_description = f"{DEFAULT_MCP_RETAIN_DESCRIPTION}\n\nAdditional instructions: {extra_instructions}"
+        recall_description = f"{DEFAULT_MCP_RECALL_DESCRIPTION}\n\nAdditional instructions: {extra_instructions}"
+
+    mcp = FastMCP("hindsight")
+
+    # Configure and register tools using shared module
+    config = MCPToolsConfig(
+        bank_id_resolver=lambda: bank_id,
+        include_bank_id_param=False,  # Local MCP uses fixed bank_id
+        tools={"retain", "recall"},  # Local MCP only has retain and recall
+        retain_description=retain_description,
+        recall_description=recall_description,
+        retain_fire_and_forget=True,  # Local MCP uses fire-and-forget pattern
+    )
+
+    register_mcp_tools(mcp, memory, config)
+
+    return mcp
+
+
+async def _initialize_and_run(bank_id: str):
+    """Initialize memory and run the MCP server."""
+    from hindsight_api import MemoryEngine
+
+    # Create and initialize memory engine with pg0 embedded database
+    # Note: We avoid printing to stderr during init as MCP clients show it as "errors"
+    memory = MemoryEngine(db_url="pg0://hindsight-mcp")
+    await memory.initialize()
+
+    # Create and run the server
+    mcp = create_local_mcp_server(bank_id, memory=memory)
+    await mcp.run_stdio_async()
+
+
+def main():
+    """Main entry point for the stdio MCP server."""
+    import asyncio
+
+    from hindsight_api.config import ENV_LLM_API_KEY, get_config
+
+    # Check for required environment variables
+    config = get_config()
+    if not config.llm_api_key:
+        print(f"Error: {ENV_LLM_API_KEY} environment variable is required", file=sys.stderr)
+        print("Set it in your MCP configuration or shell environment", file=sys.stderr)
+        sys.exit(1)
+
+    # Get bank ID from environment, default to "mcp"
+    bank_id = os.environ.get(ENV_MCP_LOCAL_BANK_ID, DEFAULT_MCP_LOCAL_BANK_ID)
+
+    # Note: We don't print to stderr as MCP clients display it as "error output"
+    # Use HINDSIGHT_API_LOG_LEVEL=debug for verbose startup logging
+
+    # Run the async initialization and server
+    asyncio.run(_initialize_and_run(bank_id))


 if __name__ == "__main__":
--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Nicolò Boschi	7972fd3906	feat: support litellm-sdk for reranker endpoint	2026-02-12 14:43:35 +01:00
Nicolò Boschi	86b698460e	chore: remove dead code	2026-02-12 14:21:53 +01:00
Nicolò Boschi	6f9cef674b	chore: remove dead code	2026-02-12 14:21:26 +01:00